Metadata-Version: 2.5
Name: readvars
Version: 0.0.1
Summary: Read and process EnergyPlus ESO files
Project-URL: Documentation, https://github.com/Jason W. DeGraw/readvars#readme
Project-URL: Issues, https://github.com/Jason W. DeGraw/readvars/issues
Project-URL: Source, https://github.com/Jason W. DeGraw/readvars
Author-email: "Jason W. DeGraw" <jason.degraw@gmail.com>
License: EnergyPlus, Copyright (c) 1996-present, The Board of Trustees of the
        University of Illinois, The Regents of the University of California, through
        Lawrence Berkeley National Laboratory (subject to receipt of any required
        approvals from the U.S. Dept. of Energy), Oak Ridge National Laboratory,
        managed by UT-Battelle, Alliance for Energy Innovation, LLC, and other
        contributors. All rights reserved.
        
        NOTICE: This Software was developed under funding from the U.S. Department of
        Energy and the U.S. Government consequently retains certain rights. As such,
        the U.S. Government has been granted for itself and others acting on its
        behalf a paid-up, nonexclusive, irrevocable, worldwide license in the
        Software to reproduce, distribute copies to the public, prepare derivative
        works, and perform publicly and display publicly, and to permit others to do
        so.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        (1) Redistributions of source code must retain the above copyright notice,
            this list of conditions and the following disclaimer.
        
        (2) Redistributions in binary form must reproduce the above copyright notice,
            this list of conditions and the following disclaimer in the documentation
            and/or other materials provided with the distribution.
        
        (3) Neither the name of the University of California, Lawrence Berkeley
            National Laboratory, the University of Illinois, U.S. Dept. of Energy nor
            the names of its contributors may be used to endorse or promote products
            derived from this software without specific prior written permission.
        
        (4) Use of EnergyPlus(TM) Name. If Licensee (i) distributes the software in
            stand-alone form without changes from the version obtained under this
            License, or (ii) Licensee makes a reference solely to the software
            portion of its product, Licensee must refer to the software as
            "EnergyPlus version X" software, where "X" is the version number Licensee
            obtained under this License and may not use a different name for the
            software. Except as specifically required in this Section (4), Licensee
            shall not use in a company name, a product name, in advertising,
            publicity, or other promotional activities any name, trade name,
            trademark, logo, or other designation of "EnergyPlus", "E+", "e+" or
            confusingly similar designation, without the U.S. Department of Energy's
            prior written consent.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
        ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
        LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
        SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
        INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
        CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
        ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
        POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE.txt
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.8
Provides-Extra: test
Requires-Dist: pytest-cov>=4; extra == 'test'
Requires-Dist: pytest>=7; extra == 'test'
Description-Content-Type: text/markdown

# readvars

`readvars` is a stand-alone Python implementation of EnergyPlus's historical
ReadVarsESO utility. It reads EnergyPlus ESO and MTR files and writes the same
row-oriented delimited output expected by existing ReadVarsESO workflows.

The package supports both the legacy RVI/MVI interface and a modern interface
for discovering and filtering output variables. It has no runtime
dependencies.

## Installation

```console
python -m pip install readvars
```

This installs both `readvars` and `ReadVarsESO` console commands. The latter is
provided for compatibility with tools that invoke the legacy executable name.

## Command line

Convert every variable in an ESO file:

```console
readvars read eplusout.eso
```

Choose an output file and select hourly temperature variables:

```console
readvars read eplusout.eso --output temperatures.csv \
  --frequency hourly --search temperature
```

Inspect the data dictionary as a table, CSV, or JSON:

```console
readvars list eplusout.eso --format table
readvars list eplusout.eso --frequency hourly --format json
```

The `--list` and `--read` spellings are accepted as aliases. Run
`readvars --help` for all modern options.

### Legacy compatibility

An existing RVI or MVI file can be passed exactly as it was to ReadVarsESO:

```console
ReadVarsESO custom.rvi hourly unlimited fixheader
```

With no arguments, the command reads `eplusout.eso`, writes `eplusout.csv`,
and creates the traditional `readvars.audit` file. Output extensions select
the legacy delimiter: `.csv` uses a comma, `.tab` a tab, and `.txt` a space.

## Python API

```python
from readvars import convert, list_variables

variables = list_variables(
    "eplusout.eso",
    frequency="hourly",
    search="temperature",
)

output_path = convert(
    "eplusout.eso",
    "temperatures.csv",
    frequency="hourly",
    search="temperature",
)
```

`list_variables` returns `DictionaryRecord` objects. `convert` returns the
output `pathlib.Path`. Accepted frequency names are `timestep`, `time-step`,
`detailed`, `detail`, `hourly`, `daily`, `monthly`, `annual`, `runperiod`, and
`run-period`.

## Development

Install the test dependencies and run pytest:

```console
python -m pip install -e ".[test]"
pytest
```

The integration tests exercise modern conversion and the legacy RVI path
against an EnergyPlus ESO fixture; unit tests cover parsing, filtering, and
time aggregation behavior.

### Gold-file regression tests

Regression cases are pairs of files under `tests/data` with the same stem and
`.rvi`/`.eso` extensions. Pytest runs the Python port in an isolated directory
and compares its output byte-for-byte with the corresponding stored output
under `tests/gold`:

```console
hatch run test:run -m regression
```

The normal test suite does not require an EnergyPlus installation. Gold files
are updated separately and deliberately using a legacy executable. For example,
to regenerate them from EnergyPlus 26.1:

```console
hatch run python scripts/generate_gold.py \
  C:\EnergyPlus-26.1.0\PostProcess\ReadVarsESO.exe
```

Pass one or more fixture stems after the executable to regenerate only selected
cases. Gold-file changes should be reviewed before they are committed.

## License

`readvars` is distributed under the EnergyPlus license in
[`LICENSE.txt`](LICENSE.txt).
