From 93436aa82cb6de85fa9676cf98a795d57ca572bd Mon Sep 17 00:00:00 2001 From: voightp Date: Wed, 15 Jul 2026 14:37:58 +0200 Subject: [PATCH] Add missing module/class/function docstrings, make DBEsoFile.from_raw_outputs public, simplify a range/len loop to plain iteration, and tighten pylint disables in pyproject.toml (documenting IronPython 2.7 compatibility exceptions and scoping the run_resource_models.py exception locally). --- db_eplusout_reader/__init__.py | 2 + db_eplusout_reader/constants.py | 2 + db_eplusout_reader/db_esofile.py | 157 ++++++++++-------- db_eplusout_reader/exceptions.py | 3 + db_eplusout_reader/get_results.py | 2 + .../processing/esofile_reader.py | 4 + db_eplusout_reader/processing/esofile_time.py | 8 +- db_eplusout_reader/processing/raw_eso_data.py | 6 + db_eplusout_reader/results_dict.py | 7 + db_eplusout_reader/sql_reader.py | 15 +- pyproject.toml | 26 +-- scripts/copy_outputs_to_test_files.py | 1 + scripts/run_resource_models.py | 3 +- tests/test_sql_results.py | 2 + 14 files changed, 141 insertions(+), 97 deletions(-) diff --git a/db_eplusout_reader/__init__.py b/db_eplusout_reader/__init__.py index 9934ee3..c997d07 100644 --- a/db_eplusout_reader/__init__.py +++ b/db_eplusout_reader/__init__.py @@ -1,3 +1,5 @@ +"""A tool to fetch results from EnergyPlus output files.""" + __version__ = "0.1.0" from db_eplusout_reader.db_esofile import DBEsoFile, DBEsoFileCollection diff --git a/db_eplusout_reader/constants.py b/db_eplusout_reader/constants.py index 02ceb2c..e5d4c99 100644 --- a/db_eplusout_reader/constants.py +++ b/db_eplusout_reader/constants.py @@ -1,3 +1,5 @@ +"""Shared frequency and variable field constants.""" + TS = "timestep" H = "hourly" D = "daily" diff --git a/db_eplusout_reader/db_esofile.py b/db_eplusout_reader/db_esofile.py index 337588b..6e82886 100644 --- a/db_eplusout_reader/db_esofile.py +++ b/db_eplusout_reader/db_esofile.py @@ -1,3 +1,5 @@ +"""Classes representing processed EnergyPlus .eso file output data.""" + from db_eplusout_reader.constants import RP, TS, A, D, H, M from db_eplusout_reader.exceptions import CollectionRequired, raise_if_missing from db_eplusout_reader.processing.esofile_reader import Variable, process_eso_file @@ -9,79 +11,80 @@ class DBEsoFile: - def __init__(self, environment_name, header, outputs, dates, n_days, days_of_week): - """ - Represents processed EnergyPlus eso file output data. + """ + Represents processed EnergyPlus eso file output data. - Results are stored in bins identified by output frequency. + Results are stored in bins identified by output frequency. - Parameters - ---------- - environment_name : str - A name of the environment. - header : dict of {str, dict of {int, Variable}} - Processed header dictionary. - outputs : dict of {str, dict of {int, list of float}} - Processed numeric outputs. - dates : dict of {str, datetime} - Parsed dates. - n_days : dict of {str, list of int} - Number of days for each step for monthly to runperiod frequencies. - days_of_week: - Day of week for each step for timestep to daily frequencies. - - Example - ------- - environment_name 'TEST (01-01:31-12)' - header { - 'hourly' : { - Variable(key='B1:ZONE1', type='Zone Mean Air Temperature', units='C'): 322, - Variable(key='B1:ZONE2', type='Zone Air Relative Humidity', units='%'): 304 - ... - }, - 'daily' : { - Variable(key='B1:ZONE1', type='Zone Air Relative Humidity', units='%'): 521, - Variable(key='B1:ZONE2', type='Zone Air Relative Humidity', units='%'): 565 - ... - } - } - outputs { - 'hourly' : { - 322 : [17.906587634970627, 17.198486368112462, 16.653197201251096, ...] - 304 : [0.006551864336487204, 0.0061786832466626095, 0.005800374315868216, ...] - ... - }, - 'daily' : { - 521 : [38.83017767728567, 48.74604212532369, 41.69013850729892, ...] - 565 : [43.25127519033924, 55.42681891740626, 42.215387940031526, ...] - ... - } - } - dates { - 'hourly' : [ - datetime.datetime(2002, 1, 1, 1, 0), - datetime.datetime(2002, 1, 1, 2, 0), - datetime.datetime(2002, 1, 1, 3, 0), - ... - ], - 'daily' : [ - datetime.datetime(2002, 1, 1, 0, 0), - datetime.datetime(2002, 1, 2, 0, 0), - datetime.datetime(2002, 1, 3, 0, 0), - ... - } - n_days { - 'monthly': [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31], - 'annual': [365], - 'runperiod': [365] + Parameters + ---------- + environment_name : str + A name of the environment. + header : dict of {str, dict of {int, Variable}} + Processed header dictionary. + outputs : dict of {str, dict of {int, list of float}} + Processed numeric outputs. + dates : dict of {str, datetime} + Parsed dates. + n_days : dict of {str, list of int} + Number of days for each step for monthly to runperiod frequencies. + days_of_week: + Day of week for each step for timestep to daily frequencies. + + Example + ------- + environment_name 'TEST (01-01:31-12)' + header { + 'hourly' : { + Variable(key='B1:ZONE1', type='Zone Mean Air Temperature', units='C'): 322, + Variable(key='B1:ZONE2', type='Zone Air Relative Humidity', units='%'): 304 + ... + }, + 'daily' : { + Variable(key='B1:ZONE1', type='Zone Air Relative Humidity', units='%'): 521, + Variable(key='B1:ZONE2', type='Zone Air Relative Humidity', units='%'): 565 + ... } - days_of_week { - 'hourly': ['Tuesday', 'Tuesday', 'Tuesday', 'Tuesday', ...], - 'daily': ['Tuesday', 'Wednesday', 'Thursday', 'Friday', ...], + } + outputs { + 'hourly' : { + 322 : [17.906587634970627, 17.198486368112462, 16.653197201251096, ...] + 304 : [0.006551864336487204, 0.0061786832466626095, 0.005800374315868216, ...] + ... + }, + 'daily' : { + 521 : [38.83017767728567, 48.74604212532369, 41.69013850729892, ...] + 565 : [43.25127519033924, 55.42681891740626, 42.215387940031526, ...] ... } + } + dates { + 'hourly' : [ + datetime.datetime(2002, 1, 1, 1, 0), + datetime.datetime(2002, 1, 1, 2, 0), + datetime.datetime(2002, 1, 1, 3, 0), + ... + ], + 'daily' : [ + datetime.datetime(2002, 1, 1, 0, 0), + datetime.datetime(2002, 1, 2, 0, 0), + datetime.datetime(2002, 1, 3, 0, 0), + ... + } + n_days { + 'monthly': [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31], + 'annual': [365], + 'runperiod': [365] + } + days_of_week { + 'hourly': ['Tuesday', 'Tuesday', 'Tuesday', 'Tuesday', ...], + 'daily': ['Tuesday', 'Wednesday', 'Thursday', 'Friday', ...], + ... + } - """ + """ + + def __init__(self, environment_name, header, outputs, dates, n_days, days_of_week): self.environment_name = environment_name self.header = header self.outputs = outputs @@ -90,7 +93,8 @@ def __init__(self, environment_name, header, outputs, dates, n_days, days_of_wee self.days_of_week = days_of_week @classmethod - def _from_raw_outputs(cls, raw_outputs, year): + def from_raw_outputs(cls, raw_outputs, year): + """Create a DBEsoFile from a single environment's RawOutputData.""" dates = convert_raw_date_data(raw_outputs.dates, raw_outputs.days_of_week, year) n_days = get_n_days_from_cumulative(raw_outputs.cumulative_days) return cls( @@ -104,9 +108,10 @@ def _from_raw_outputs(cls, raw_outputs, year): @classmethod def from_path(cls, file_path, year=None): + """Create a DBEsoFile from a path; raises CollectionRequired if multi-environment.""" all_raw_outputs = process_eso_file(file_path) if len(all_raw_outputs) == 1: - return cls._from_raw_outputs(all_raw_outputs[0], year) + return cls.from_raw_outputs(all_raw_outputs[0], year) raise CollectionRequired( "Cannot process file {}. " "as there are multiple environments included.\n" @@ -117,6 +122,7 @@ def from_path(cls, file_path, year=None): @property def frequencies(self): + """List available output frequencies, ordered from most to least granular.""" order = {TS: 0, H: 1, D: 2, M: 3, A: 4, RP: 5} return sorted(list(self.header.keys()), key=lambda x: order[x]) @@ -249,15 +255,17 @@ def __init__(self, db_eso_files=None): @classmethod def from_path(cls, file_path, year=None): + """Create a DBEsoFileCollection holding one DBEsoFile per environment in the file.""" all_raw_outputs = process_eso_file(file_path) db_eso_files = [] for raw_outputs in all_raw_outputs: - db_eso_file = DBEsoFile._from_raw_outputs(raw_outputs, year) + db_eso_file = DBEsoFile.from_raw_outputs(raw_outputs, year) db_eso_files.append(db_eso_file) return cls(db_eso_files) @property def environment_names(self): + """List environment names of the held DBEsoFile objects.""" return [ef.environment_name for ef in self._db_eso_files] def __iter__(self): @@ -271,28 +279,37 @@ def __contains__(self, item): return item in self._db_eso_files def append(self, item): + """Append a DBEsoFile to the collection.""" self._db_eso_files.append(item) def count(self): + """Return the number of DBEsoFile objects in the collection.""" len(self._db_eso_files) def index(self, item): + """Return the index of the given DBEsoFile in the collection.""" return self._db_eso_files.index(item) def extend(self, items): + """Extend the collection with an iterable of DBEsoFile objects.""" self._db_eso_files.extend(items) def insert(self, index, item): + """Insert a DBEsoFile at the given index.""" self._db_eso_files.insert(index, item) def pop(self, index): + """Remove and return the DBEsoFile at the given index.""" return self._db_eso_files.pop(index) def remove(self, item): + """Remove the first occurrence of the given DBEsoFile from the collection.""" self._db_eso_files.remove(item) def reverse(self): + """Reverse the order of the collection in place.""" reversed(self._db_eso_files) def sort(self, reverse): + """Sort the collection in place by file name.""" self._db_eso_files.sort(key=lambda ef: ef.file_name, reverse=reverse) diff --git a/db_eplusout_reader/exceptions.py b/db_eplusout_reader/exceptions.py index 4c0c720..a195dee 100644 --- a/db_eplusout_reader/exceptions.py +++ b/db_eplusout_reader/exceptions.py @@ -1,3 +1,6 @@ +"""Exceptions raised while reading and processing EnergyPlus output files.""" + + class IncompleteFile(Exception): """Exception raised when the file is not complete.""" diff --git a/db_eplusout_reader/get_results.py b/db_eplusout_reader/get_results.py index 789ed81..b9f7a8c 100644 --- a/db_eplusout_reader/get_results.py +++ b/db_eplusout_reader/get_results.py @@ -1,3 +1,5 @@ +"""High level entry point to extract results from .eso or .sql files.""" + import os from db_eplusout_reader.db_esofile import DBEsoFile, DBEsoFileCollection diff --git a/db_eplusout_reader/processing/esofile_reader.py b/db_eplusout_reader/processing/esofile_reader.py index 9745ba7..a0c6c40 100644 --- a/db_eplusout_reader/processing/esofile_reader.py +++ b/db_eplusout_reader/processing/esofile_reader.py @@ -1,3 +1,5 @@ +"""Parse the header and body of an EnergyPlus .eso file into raw output data.""" + import re from collections import defaultdict, namedtuple from datetime import datetime @@ -222,6 +224,7 @@ def parse_annual_frequency(): def split_raw_line(raw_line): + """Split a raw eso file body line into its line id and remaining fields.""" split_line = raw_line.split(",") line_id = int(split_line[0]) line = split_line[1:] @@ -229,6 +232,7 @@ def split_raw_line(raw_line): def process_frequency_line(line_id, line, all_raw_outputs, header, all_ids, raw_outputs): + """Process a frequency line, returning the (possibly new) raw outputs and frequency.""" if line_id == ENVIRONMENT_LINE: # initialize variables for current environment environment_name = line[0].strip() diff --git a/db_eplusout_reader/processing/esofile_time.py b/db_eplusout_reader/processing/esofile_time.py index 5cb1742..b34e685 100644 --- a/db_eplusout_reader/processing/esofile_time.py +++ b/db_eplusout_reader/processing/esofile_time.py @@ -1,3 +1,5 @@ +"""Convert raw EnergyPlus timestamp data into standard datetime objects.""" + import calendar import logging from collections import namedtuple @@ -86,13 +88,13 @@ def check_year_increment(first_step_data, current_step_data): def generate_datetime_dates(raw_dates, year): """Generate datetime index for a given period.""" dates = [] - for i in range(0, len(raw_dates)): + for raw_date in raw_dates: # based on the first, current and previous # steps decide if the year should be incremented - if check_year_increment(raw_dates[0], raw_dates[i]): + if check_year_increment(raw_dates[0], raw_date): year += 1 # year can be incremented automatically when converting to datetime - date = parse_eso_timestamp(year, *raw_dates[i]) + date = parse_eso_timestamp(year, *raw_date) dates.append(date) return dates diff --git a/db_eplusout_reader/processing/raw_eso_data.py b/db_eplusout_reader/processing/raw_eso_data.py index db087c8..c7dc029 100644 --- a/db_eplusout_reader/processing/raw_eso_data.py +++ b/db_eplusout_reader/processing/raw_eso_data.py @@ -1,9 +1,13 @@ +"""Container holding raw, not-yet-dated numeric outputs parsed from an .eso file.""" + from collections import defaultdict from db_eplusout_reader.constants import RP, A, M class RawOutputData: + """Holds raw, not-yet-dated numeric outputs and dictionaries for a single environment.""" + def __init__(self, environment_name, header, all_ids=None): self.environment_name = environment_name self.header = header @@ -25,6 +29,7 @@ def __init__(self, environment_name, header, all_ids=None): ) = self.initialize_results_bins() def initialize_results_bins(self): + """Create empty outputs, dates, cumulative_days and days_of_week bins for all_ids.""" outputs = defaultdict(dict) dates = {} cumulative_days = {} @@ -40,5 +45,6 @@ def initialize_results_bins(self): return outputs, dates, cumulative_days, days_of_week def initialize_next_outputs_step(self, frequency): + """Append a nan placeholder to every output array for the given frequency.""" for value in self.outputs[frequency].values(): value.append(float("nan")) diff --git a/db_eplusout_reader/results_dict.py b/db_eplusout_reader/results_dict.py index a491c6f..37bbb69 100644 --- a/db_eplusout_reader/results_dict.py +++ b/db_eplusout_reader/results_dict.py @@ -1,3 +1,5 @@ +"""Dictionary-like container for extracted results and its table/csv export helpers.""" + import csv import sys from collections import OrderedDict @@ -48,6 +50,7 @@ def _items(self): @property def scalar(self): + """Return the first value of the first variable's array.""" try: return self._items[0][1][0] except IndexError: @@ -55,18 +58,22 @@ def scalar(self): @property def first_array(self): + """Return the numeric array of the first variable.""" return self._items[0][1] @property def first_variable(self): + """Return the first Variable named tuple.""" return self._items[0][0] @property def variables(self): + """Return all Variable named tuples.""" return [v[0] for v in self._items] @property def arrays(self): + """Return all numeric arrays.""" return [v[1] for v in self._items] def to_table(self, explode_header=True): diff --git a/db_eplusout_reader/sql_reader.py b/db_eplusout_reader/sql_reader.py index 45159de..3d8632d 100644 --- a/db_eplusout_reader/sql_reader.py +++ b/db_eplusout_reader/sql_reader.py @@ -1,3 +1,5 @@ +"""Read variables and results directly from an EnergyPlus .sql output file.""" + import os.path import sqlite3 from collections import OrderedDict @@ -48,9 +50,9 @@ def eso_to_sql_variable(variable): """Convert 'Variable' to be compatible with sql queries.""" sql_columns = ["KeyValue", "Name", "Units"] sql_variable = {} - for variable, column in zip(variable, sql_columns): - if variable is not None: - sql_variable[column] = variable + for piece, column in zip(variable, sql_columns): + if piece is not None: + sql_variable[column] = piece return sql_variable @@ -99,8 +101,9 @@ def to_string(unicode_variable): def get_unsorted_sub_dict(rows): + """Build an id : Variable mapping from data dict rows, in original row order.""" unsorted_dict = {} - for id_, frequency, key, type_, units in rows: + for id_, _frequency, key, type_, units in rows: unicode_variable = Variable(key, type_, units) variable = to_string(unicode_variable) unsorted_dict[id_] = variable @@ -108,8 +111,9 @@ def get_unsorted_sub_dict(rows): def sort_by_value(unsorted_dict): + """Return an OrderedDict of the given dict's items sorted by value.""" sorted_dct = OrderedDict() - sorted_items = [item for item in sorted(unsorted_dict.items(), key=lambda x: x[1])] + sorted_items = list(sorted(unsorted_dict.items(), key=lambda x: x[1])) for key, value in sorted_items: sorted_dct[key] = value return sorted_dct @@ -217,6 +221,7 @@ def parse_sql_timestamps(time_rows): def filter_timestamps(timestamps, start_date, end_date): + """Return timestamps that lie between start and end dates.""" valid_timestamps = [] for timestamp in timestamps: if validate_time(timestamp, start_date, end_date): diff --git a/pyproject.toml b/pyproject.toml index 170c642..53454bd 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -57,24 +57,14 @@ ignore-patterns = ["test_.*\\.py", "conftest\\.py"] [tool.pylint."messages control"] disable = [ - "C0114", # missing-module-docstring - "C0115", # missing-class-docstring - "C0116", # missing-function-docstring - "C0200", # consider-using-enumerate - "C0209", # consider-using-f-string - "C0301", # line-too-long (handled by ruff) - "R0903", # too-few-public-methods - "R0913", # too-many-arguments - "R0917", # too-many-positional-arguments - "R1704", # redefined-argument-from-local - "R1720", # no-else-raise - "R1721", # unnecessary-comprehension - "R1725", # super-with-arguments - "R1737", # use-yield-from - "W0108", # unnecessary-lambda - "W0212", # protected-access - "W0612", # unused-variable - "W0621", # redefined-outer-name (common in pytest fixtures) + # 2.7 DesignBuilder iron python compatibility + "C0209", # consider-using-f-string, "W0707", # raise-missing-from + "R1737", # use-yield-from "W1514", # unspecified-encoding + # Relax the rules, marginal fails, better to disable + # than specify the full pylint config + "R0913", # too-many-arguments + "R0903", # too-few-public-methods + "R0917", # too-many-positional-arguments ] diff --git a/scripts/copy_outputs_to_test_files.py b/scripts/copy_outputs_to_test_files.py index c4f1547..cf5d77b 100644 --- a/scripts/copy_outputs_to_test_files.py +++ b/scripts/copy_outputs_to_test_files.py @@ -18,6 +18,7 @@ def main() -> None: + """Copy matching .eso/.sql outputs from resources/output/ into tests/test_files/.""" TEST_FILES.mkdir(parents=True, exist_ok=True) copied: list[str] = [] diff --git a/scripts/run_resource_models.py b/scripts/run_resource_models.py index 923a9b7..08474be 100644 --- a/scripts/run_resource_models.py +++ b/scripts/run_resource_models.py @@ -72,7 +72,8 @@ def reset_idd() -> None: pass # resetidd() always raises this after clearing state -def main() -> None: +def main() -> None: # pylint: disable=too-many-locals, too-many-statements + """Run every IDF in resources/, grouped by EnergyPlus version, and report timings.""" idf_files = sorted(RESOURCES.glob("*.idf")) if not idf_files: print("No IDF files found in resources/") diff --git a/tests/test_sql_results.py b/tests/test_sql_results.py index 4748479..0bc39b7 100644 --- a/tests/test_sql_results.py +++ b/tests/test_sql_results.py @@ -149,6 +149,8 @@ def test_non_strict_missing_variable_ignored(self, sql_path): def test_strict_message_lists_missing(self, sql_path): with pytest.raises(VariableNotFound, match="Does Not Exist"): get_results(sql_path, self._MISSING, frequency=H, strict=True) + + class TestListVariables: def test_get_tables(self, any_sql_path): tables = get_tables(any_sql_path)