From 19b78394fc3a6fe052532e33b36e62c5abdce1fa Mon Sep 17 00:00:00 2001 From: Will Usher Date: Tue, 20 Jun 2023 22:39:21 +0200 Subject: [PATCH] Add documentation for Python API --- docs/convert.rst | 37 +++++++++++++++++++++++++++++++++++++ docs/index.rst | 5 +++-- src/otoole/convert.py | 29 ++++++++++++++++++++++------- 3 files changed, 62 insertions(+), 9 deletions(-) create mode 100644 docs/convert.rst diff --git a/docs/convert.rst b/docs/convert.rst new file mode 100644 index 00000000..16111aec --- /dev/null +++ b/docs/convert.rst @@ -0,0 +1,37 @@ +.. _convert: + +========== +Python API +========== + +otoole also provides a Python API to access all the features available from the command line tool. + +Converting between formats +-------------------------- + +``otoole`` currently supports conversion between the following formats: + +- Excel +- A folder of CSV files +- GNU MathProg datafile + +>>> from otoole import convert +>>> convert('my_model.yaml', 'excel', 'csv', 'my_model.xlsx', 'my_model_csvs') + +See :py:func:`otoole.convert.convert` for more details + +Converting solver results to a folder of CSV files +-------------------------------------------------- + +The ``convert_results`` function creates a folder of CSV result files from a CBC_, CLP_, +Gurobi_ or CPLEX_ solution file:: + +>>> from otoole import convert_results +>>> convert_results('my_model.yaml', 'cbc', 'csv', 'my_model.sol', 'my_model_csvs', input_datafile='my_model.dat') + +See :func:`otoole.convert.convert_results` for more details + +.. _CBC: https://github.com/coin-or/Cbc +.. _CLP: https://github.com/coin-or/Clp +.. _CPLEX: https://www.ibm.com/products/ilog-cplex-optimization-studio/cplex-optimizer +.. _Gurobi: https://www.gurobi.com/ diff --git a/docs/index.rst b/docs/index.rst index 568e5ed6..2cc3d0cd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,8 +5,8 @@ Welcome to the documentation of ``otoole``! =========================================== **otoole**, or **O**\ SeMOSYS **tool**\ s for **e**\ nergy work, is a Python package -which provides a command-line interface for users of OSeMOSYS. The aim of the package is -to provide commonly used pre- and post-processing steps when working with OSeMOSYS models. +which provides a command-line interface and Python API for users of OSeMOSYS. The aim of the +package is to provide commonly used pre- and post-processing steps when working with OSeMOSYS models. Specifically, ``otoole`` allows the user to convert between data formats, process solutions, and visualise the reference energy system. @@ -28,6 +28,7 @@ Contents Core Functionality Data Formats Examples + Python API Contributing License Authors diff --git a/src/otoole/convert.py b/src/otoole/convert.py index 068a66cd..f3a95063 100644 --- a/src/otoole/convert.py +++ b/src/otoole/convert.py @@ -36,14 +36,29 @@ def convert_results( Arguments --------- config : str + Path to config file + from_format : str + Available options are 'cbc', 'cplex' and 'gurobi' + to_format : str + Available options are 'csv' + from_path : str + Path to cbc, cplex or gurobi solution file + to_path : str + Path to destination folder input_datapackage : str + Path to folder containing datapackage.json input_csvs : str + Path to folder containing CSVs input_datafile : str - to_path : str - from_path : str - from_format : str - to_format : str + Path to datafile write_defaults : str + Write default values to CSVs + + Returns + ------- + bool + True if conversion was successful, False otherwise + """ msg = "Conversion from {} to {} is not yet implemented".format( from_format, to_format @@ -124,12 +139,14 @@ def convert( from_path : str Path to destination file (if datafile or excel) or folder (csv or datapackage) write_defaults: bool, default: False + Write default values to CSVs keep_whitespace: bool, default: False + Keep whitespace in CSVs Returns ------- bool - True if conversion was successful + True if conversion was successful, False otherwise """ msg = "Conversion from {} to {} is not yet implemented".format( @@ -144,8 +161,6 @@ def convert( logger.info("Validating config from {}".format(config)) validate_config(user_config) - # set read strategy - keep_whitespace = True if keep_whitespace else False if from_format == "datafile":