Skip to content

Commit

Permalink
fixing docstring formatting issues
Browse files Browse the repository at this point in the history
aerispaha committed Dec 18, 2024

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
1 parent 3e22a8b commit b421d99
Showing 5 changed files with 88 additions and 37 deletions.
2 changes: 2 additions & 0 deletions swmmio/utils/dataframes.py
Original file line number Diff line number Diff line change
@@ -209,8 +209,10 @@ def get_link_coords(row, nodexys, verticies):
def get_inp_options_df(inp_path):
"""
Parse ONLY the OPTIONS section of the inp file into a dataframe
:param inp_path: path to inp file
:return: pandas.DataFrame
>>> from swmmio.tests.data import MODEL_FULL_FEATURES_XY
>>> ops = get_inp_options_df(MODEL_FULL_FEATURES_XY)
>>> ops[:3]
39 changes: 29 additions & 10 deletions swmmio/utils/text.py
Original file line number Diff line number Diff line change
@@ -225,13 +225,26 @@ def find_byte_range_of_section(path, start_string):

def get_inp_sections_details(inp_path, include_brackets=False):
"""
creates a dictionary with all the headers found in an INP file
Creates a dictionary with all the headers found in an INP file
(which varies based on what the user has defined in a given model)
and updates them based on the definitions in inp_header_dict
this ensures the list is comprehensive
:param inp_path:
:param include_brackets: whether to parse sections including the []
:return: OrderedDict
to ensure the list is comprehensive.
Parameters
----------
inp_path : str
Path to the INP file.
include_brackets : bool, optional
Whether to parse sections including the brackets ([]). Default is False.
Returns
-------
OrderedDict
An ordered dictionary with section headers as keys and their
corresponding details.
Examples
--------
>>> from swmmio.tests.data import MODEL_FULL_FEATURES_XY
>>> headers = get_inp_sections_details(MODEL_FULL_FEATURES_XY)
>>> [header for header, cols in headers.items()][:4]
@@ -283,14 +296,20 @@ def get_inp_sections_details(inp_path, include_brackets=False):
return found_sects


def get_rpt_sections_details(rpt_path):
def get_rpt_sections_details(rpt_path: str):
"""
Extracts and returns the details of sections from a SWMM report file.
:param rpt_path:
:param include_brackets:
:return:
# >>> MODEL_FULL_FEATURES__NET_PATH
Parameters
----------
rpt_path : str
The file path to the SWMM report file.
Returns
-------
OrderedDict
An ordered dictionary where the keys are section headers found in the report file
and the values are the corresponding details as defined in the RPT_OBJECTS.
"""
from swmmio.defs import RPT_OBJECTS
found_sects = OrderedDict()
15 changes: 14 additions & 1 deletion swmmio/version_control/inp.py
Original file line number Diff line number Diff line change
@@ -74,7 +74,20 @@ def __radd__(self, other):

def save(self, dir, filename):
"""
save the current BuildInstructions instance to file (human readable)
Save the current BuildInstructions instance to a file in a human-readable format.
Parameters
----------
dir : str
The directory where the file will be saved. If the directory does not exist, it will be created.
filename : str
The name of the file to save the BuildInstructions instance to.
Notes
-----
This method writes metadata and instructions to the specified file. The instructions are written
by concatenating the removed, altered, and added changes for each section and then writing them
to the file.
"""
if not os.path.exists(dir):
os.makedirs(dir)
36 changes: 24 additions & 12 deletions swmmio/version_control/utils.py
Original file line number Diff line number Diff line change
@@ -6,19 +6,31 @@
from swmmio.utils.functions import format_inp_section_header


def copy_rpts_hsf(from_dir, to_dir, search_dir):
def copy_rpts_hsf(from_dir: str, to_dir: str, search_dir: str):

"""
walk through a directory and find all rpts and hot start files and copy to
another location based on the relative path from the to_dir.
ex:
to_directory = r'P:\02_Projects\SouthPhila\SE_SFR\MasterModels'
from_dir = r'F:\models\SPhila\MasterModels_170104'
search_dir = r'F:\models\SPhila\MasterModels_170104\Combinations'
copy_rpts_hsf(from_dir, to_dir, search_dir)
Good for model results written on a local drive to a network drive
Walk through a directory and find all .rpt and hot start (.hsf) files and copy them to
another location based on the relative path from the `to_dir`.
Parameters
----------
from_dir : str
The source directory from which the relative path is derived.
to_dir : str
The destination directory where the files will be copied.
search_dir : str
The directory to search for .rpt and .hsf files.
Examples
--------
>>> to_directory = r'P:\\02_Projects\\SouthPhila\\SE_SFR\\MasterModels'
>>> from_dir = r'F:\\models\\SPhila\\MasterModels_170104'
>>> search_dir = r'F:\\models\\SPhila\\MasterModels_170104\\Combinations'
>>> copy_rpts_hsf(from_dir, to_dir, search_dir)
Notes
-----
This function is useful for copying model results written on a local drive to a network drive.
"""

# chain.from_iterable(os.walk(path) for path in paths):
33 changes: 19 additions & 14 deletions swmmio/version_control/version_control.py
Original file line number Diff line number Diff line change
@@ -47,24 +47,29 @@ def propagate_changes_from_baseline(baseline_dir, alternatives_dir, combi_dir,
bi.build(baseline_dir, model.inp.path) # overwrite old inp


def create_combinations(baseline_dir, rsn_dir, combi_dir, version_id='',
comments=''):
def create_combinations(baseline_dir, rsn_dir, combi_dir, version_id='', comments=''):
"""
Generate SWMM5 models of each logical combination of all implementation
phases (IP) across all relief sewer networks (RSN).
Inputs:
baseline_dir -> path to directory containing the baseline SWMM5 model
rsn_dir -> path to directory containing subdirectories for each RSN
containing directories for each IP within the network
combi_dir -> target directory in which child models will be created
version_id -> identifier for a given version (optional)
comments -> comments tracked within build instructions log for
each model scenario (optional)
Calling create_combinations will update child models if parent models have
been changed.
Parameters
----------
baseline_dir : str
Path to directory containing the baseline SWMM5 model.
rsn_dir : str
Path to directory containing subdirectories for each RSN, which contain
directories for each IP within the network.
combi_dir : str
Target directory in which child models will be created.
version_id : str, optional
Identifier for a given version (default is an empty string).
comments : str, optional
Comments tracked within build instructions log for each model scenario
(default is an empty string).
Notes
-----
Calling `create_combinations` will update child models if parent models have
"""

base_inp_path = Model(baseline_dir).inp.path

0 comments on commit b421d99

Please sign in to comment.