From 5a19e7048040cbd6fbf76400978a60566e6ea864 Mon Sep 17 00:00:00 2001 From: jon-hagg <66005238+jon-hagg@users.noreply.github.com> Date: Tue, 8 Sep 2020 17:27:31 -0700 Subject: [PATCH] docs: fix warnings from sphinx build (#286) --- powersimdata/data_access/csv_store.py | 3 +++ powersimdata/data_access/execute_list.py | 4 ++++ powersimdata/data_access/scenario_list.py | 1 + powersimdata/data_access/sql_store.py | 19 +++++++++++++++---- powersimdata/design/clean_capacity_scaling.py | 8 ++++++++ powersimdata/input/change_table.py | 3 ++- powersimdata/scenario/state.py | 1 + 7 files changed, 34 insertions(+), 5 deletions(-) diff --git a/powersimdata/data_access/csv_store.py b/powersimdata/data_access/csv_store.py index 942b02b84..acf3d1976 100644 --- a/powersimdata/data_access/csv_store.py +++ b/powersimdata/data_access/csv_store.py @@ -21,6 +21,7 @@ def __init__(self, ssh_client): def get_table(self, filename, path_on_server): """Read the given file from the server, falling back to local copy if unable to connect. + :return: (*pandas.DataFrame*) -- the specified table as a data frame. """ local_path = Path(server_setup.LOCAL_DIR, filename) @@ -39,6 +40,7 @@ def get_table(self, filename, path_on_server): def _get_from_server(self, path_on_server): """Return csv table from server. + :return: (*pandas.DataFrame*) -- the specified file as a data frame. """ with self.ssh_client.open_sftp() as sftp: @@ -47,6 +49,7 @@ def _get_from_server(self, path_on_server): def _parse_csv(self, file_object): """Read file from disk into data frame + :param str, path object or file-like object file_object: a reference to the csv file :return: (*pandas.DataFrame*) -- the specified file as a data frame. diff --git a/powersimdata/data_access/execute_list.py b/powersimdata/data_access/execute_list.py index dac75a99d..7f0b8ef5f 100644 --- a/powersimdata/data_access/execute_list.py +++ b/powersimdata/data_access/execute_list.py @@ -11,6 +11,7 @@ class ExecuteTable(SqlStore): def get_status(self, scenario_id): """Get status of scenario by scenario_id + :param str scenario_id: the scenario id :return: (*pandas.DataFrame*) -- results as a data frame. """ @@ -21,6 +22,7 @@ def get_status(self, scenario_id): def get_execute_table(self, limit=None): """Return the execute table as a data frame + :return: (*pandas.DataFrame*) -- execute list as a data frame. """ query = self.select_all() @@ -33,6 +35,7 @@ def get_execute_table(self, limit=None): def add_entry(self, scenario_info): """Add entry to execute list + :param collections.OrderedDict scenario_info: entry to add """ scenario_id, status = scenario_info["id"], "created" @@ -78,6 +81,7 @@ def __init__(self, ssh_client): def get_execute_table(self): """Returns execute table from server if possible, otherwise read local copy. Updates the local copy upon successful server connection. + :return: (*pandas.DataFrame*) -- execute list as a data frame. """ return self.get_table("ExecuteList.csv", server_setup.EXECUTE_LIST) diff --git a/powersimdata/data_access/scenario_list.py b/powersimdata/data_access/scenario_list.py index 67f8b7963..9fbf8b503 100644 --- a/powersimdata/data_access/scenario_list.py +++ b/powersimdata/data_access/scenario_list.py @@ -30,6 +30,7 @@ class ScenarioTable(SqlStore): def get_scenario_by_id(self, scenario_id): """Get entry from scenario list by id + :param str scenario_id: scenario id :return: (*pandas.DataFrame*) -- results as a data frame. """ diff --git a/powersimdata/data_access/sql_store.py b/powersimdata/data_access/sql_store.py index 68b1a0b3e..cab268e28 100644 --- a/powersimdata/data_access/sql_store.py +++ b/powersimdata/data_access/sql_store.py @@ -28,6 +28,7 @@ def execute(self, sql, args=None): def get_connection(): """Temporary connection used for local development + :return: (*str*) -- connection string for postgres db """ return "dbname=psd host=localhost user=postgres password=example" @@ -36,6 +37,7 @@ def get_connection(): def get_cursor_factory(): """Return cursor class to be passed to connection for executing sql. Default to DictCursor unless DEBUG_MODE is set. + :returns: a cursor class callable for use by psycopg2 connection :rtype: psycopg2.extras.DictCursor or powersimdata.data_access.sql_store.LoggingCursor """ @@ -46,6 +48,7 @@ def get_cursor_factory(): def to_data_frame(result): """Convert psycopg2 result set to data frame + :param list result: list of DictRow containing query results cast to strings :return: (*pd.DataFrame*) -- query results as data frame """ @@ -67,6 +70,7 @@ def __init__(self): def _table(self): """Get table object for use in query generation. + :return: (*psycopg2.sql.Identifier*) -- Identifier instance :raises ValueError: if :attr:`table` has not been defined. """ @@ -76,6 +80,7 @@ def _table(self): def _columns(self, subset=None): """Get column list object for use in query generation. + :return: (*psycopg2.sql.SQL*) -- SQL instance :raises ValueError: if :attr:`columns` has not been defined. """ @@ -89,7 +94,8 @@ def _columns(self, subset=None): def select_all(self): """Build SELECT query. - :return (*psycopg2.sql.SQL*) -- query representation + + :return: (*psycopg2.sql.SQL*) -- query representation """ return SQL("SELECT {fields} FROM {table}").format( fields=self._columns(), table=self._table() @@ -97,8 +103,9 @@ def select_all(self): def select_where(self, key): """Build SELECT .. WHERE query filtered by key + :param str key: column to use in WHERE clause - :return (*psycopg2.sql.SQL*) -- query representation + :return: (*psycopg2.sql.SQL*) -- query representation """ where_clause = SQL(" WHERE {key} = %s").format(key=Identifier(key)) return self.select_all() + where_clause @@ -106,8 +113,9 @@ def select_where(self, key): def insert(self, subset=None): """Build INSERT statement on current table for all columns, or subset if specified. + :param iterable subset: collection of columns to specify in query - :return (*psycopg2.sql.SQL*) -- template for insert statement + :return: (*psycopg2.sql.SQL*) -- template for insert statement """ n_values = len(subset) if subset is not None else len(self.columns) return SQL("INSERT INTO {table} ({fields}) VALUES ({values})").format( @@ -118,8 +126,9 @@ def insert(self, subset=None): def delete(self, key): """Build DELETE .. WHERE statement on current table using key to filter. + :param str key: column to use in WHERE clause - :return (*psycopg2.sql.SQL*) -- template for delete statement + :return: (*psycopg2.sql.SQL*) -- template for delete statement """ return SQL("DELETE FROM {table} WHERE {key} = %s").format( table=self._table(), key=Identifier(key) @@ -127,6 +136,7 @@ def delete(self, key): def __enter__(self): """Context manager entrypoint. + :return: the current instance """ self.conn.__enter__() @@ -137,6 +147,7 @@ def __enter__(self): def __exit__(self, exc_type, exc_value, traceback): """Context manager teardown. Either commit or rollback transaction and close the connection. Reraise exception if applicable. + :raises SqlException: If any exception occurred. Sets the original exception as the cause of the new one. """ diff --git a/powersimdata/design/clean_capacity_scaling.py b/powersimdata/design/clean_capacity_scaling.py index f3c269522..85efe38e6 100644 --- a/powersimdata/design/clean_capacity_scaling.py +++ b/powersimdata/design/clean_capacity_scaling.py @@ -138,6 +138,7 @@ def _make_zonename2target(grid, targets): def _get_scenario_length(scenario): """Get the number of hours in a scenario. + :param powersimdata.scenario.scenario.Scenario scenario: A Scenario instance. :return: (*int*) -- the number of hours in the scenario. """ @@ -157,6 +158,7 @@ def add_resource_data_to_targets(input_targets, scenario, calculate_curtailment= """Add resource data to targets. This data includes: previous capacity, previous generation, previous capacity factor (with and without curtailment), and previous curtailment. + :param pandas.DataFrame input_targets: table includeing target names, used to summarize resource data. :param powersimdata.scenario.scenario.Scenario scenario: A Scenario instance. @@ -227,6 +229,7 @@ def add_resource_data_to_targets(input_targets, scenario, calculate_curtailment= def add_demand_to_targets(input_targets, scenario): """Add demand data to targets. + :param pandas.DataFrame input_targets: table including target names, used to summarize demand. :param powersimdata.scenario.scenario.Scenario scenario: A Scenario instance. @@ -245,6 +248,7 @@ def add_demand_to_targets(input_targets, scenario): def add_shortfall_to_targets(input_targets): """Add shortfall data to targets. + :param pandas.DataFrame input_targets: table with demand, prev_generation, and ce_target_fraction. :return: (*pandas.DataFrame*) -- DataFrame of targets including shortfall data. @@ -275,6 +279,7 @@ def add_shortfall_to_targets(input_targets): def calculate_overall_shortfall(targets, method, normalized=False): """Calculates overall shortfall. + :param pandas.DataFrame targets: table of targets. :param str method: shortfall calculation method ("independent" or "collaborative"). :param bool normalized: whether to normalize by total demand. @@ -309,6 +314,7 @@ def add_new_capacities_independent( input_targets, scenario_length, addl_curtailment=None ): """Calculates new capacities based on an Independent strategy. + :param pandas.DataFrame input_targets: table of targets. :param int scenario_length: number of hours in new scenario. :param pandas.DataFrame/None addl_curtailment: additional expected curtailment @@ -372,6 +378,7 @@ def add_new_capacities_collaborative( input_targets, scenario_length, solar_fraction=None, addl_curtailment=None ): """Calculates new capacities based on a Collaborative strategy. + :param pandas.DataFrame input_targets: table of targets. :param int scenario_length: number of hours in new scenario. :param float/None solar_fraction: how much new capacity should be solar. @@ -488,6 +495,7 @@ def calculate_clean_capacity_scaling( """Given a reference scenario (to get 'baseline' values), a method, and a set of targets (either via a dataframe or a filename to load a dataframe), calculate capacities for a new scenario to meet the calculated shortfall. + :param powersimdata.scenario.scenario.Scenario ref_scenario: Scenario instance to get baseline capacities and capacity factors from. :param str method: which capacity scaling method to use. diff --git a/powersimdata/input/change_table.py b/powersimdata/input/change_table.py index 2dbee4c1e..64b9e6bd3 100644 --- a/powersimdata/input/change_table.py +++ b/powersimdata/input/change_table.py @@ -78,7 +78,7 @@ class ChangeTable(object): keys in the dictionary are: *'capacity'*, *'from_bus_id'* and *'to_bus_id'* with values giving the capacity of the line and the bus id at each end of the line. - * *'new_plant': + * *'new_plant'*: value is a list. Each entry in this list is a dictionary enclosing all the information needed to add a new generator to the grid. The keys in the dictionary are *'type'*, *'bus_id'*, *'Pmax'* for @@ -341,6 +341,7 @@ def scale_renewable_stubs(self, **kwargs): def scale_congested_mesh_branches(self, ref_scenario, **kwargs): """Scales congested branches based on previous scenario results. + :param powersimdata.scenario.scenario.Scenario ref_scenario: the reference scenario to be used in determining branch scaling. diff --git a/powersimdata/scenario/state.py b/powersimdata/scenario/state.py index f8fe2abc8..b74728966 100644 --- a/powersimdata/scenario/state.py +++ b/powersimdata/scenario/state.py @@ -5,6 +5,7 @@ class State(object): """Defines an interface for encapsulating the behavior associated with a particular state of the Scenario object. + :param powrsimdata.scenario.scenario.Scenario scenario: scenario instance :raise TypeError: if not instantiated through a derived class """