Skip to content

Commit 1d304a6

Browse files
kaklisekbonney
kaklise
and
kbonney
authored
Added framework for WNTR extensions (#554)
* Added WNTR extensions and simple hello world example * updated workflows * updated extensions workflow badge * fix coverage -m flag override bug * ignore extension files in doctests * move requirements.txt dependencies to extrasrequire; update workflow installation commands * draft bulletpoint for requirements handling * added extension point of contact --------- Co-authored-by: kbonney <kirkb1998@gmail.com>
1 parent 387cce4 commit 1d304a6

File tree

20 files changed

+232
-64
lines changed

20 files changed

+232
-64
lines changed

‎.github/workflows/build_deploy_pages.yml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,7 @@ jobs:
2525
python-version: '3.11'
2626
- name: Install package
2727
run: |
28-
pip install -e .
29-
pip install -r requirements.txt
28+
pip install -e .[optional,doc]
3029
- name: Build documentation
3130
run: sphinx-build documentation/ documentation/_build/html
3231
- name: Upload artifact

‎.github/workflows/build_tests.yml‎

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -136,7 +136,7 @@ jobs:
136136
brew reinstall libomp
137137
- name: Test wntr
138138
run: |
139-
pip install -r requirements.txt
139+
pip install --find-links=. --pre "wntr[optional,test]"
140140
pytest wntr/tests/ --ignore=wntr/tests/test_demos.py --ignore=wntr/tests/test_examples.py
141141
142142
run_coverage:
@@ -163,16 +163,16 @@ jobs:
163163
run: |
164164
python --version
165165
python -m pip install --upgrade pip
166-
pip install -r requirements.txt
167-
python -m pip install -e .
166+
python -m pip install -e .[optional,test]
168167
- name: Run Tests
169168
if: ${{ matrix.os != 'macos-latest' }}
170-
run: |
171-
coverage erase
172-
coverage run --context=${{ matrix.os }}.py${{ matrix.python-version }} --source=wntr --omit="*/tests/*","*/sim/network_isolation/network_isolation.py","*/sim/aml/evaluator.py" -m pytest --doctest-modules --doctest-glob="*.rst" wntr
173-
coverage run --context=${{ matrix.os }}.py${{ matrix.python-version }} --source=wntr --omit="*/tests/*","*/sim/network_isolation/network_isolation.py","*/sim/aml/evaluator.py" --append -m pytest --doctest-glob="*.rst" documentation
174169
env:
170+
OMIT: "'*/tests/*','*/extensions/*','*/sim/network_isolation/network_isolation.py','*/sim/aml/evaluator.py'"
175171
COVERAGE_FILE: .coverage.${{ matrix.python-version }}.${{ matrix.os }}
172+
run: |
173+
coverage erase
174+
coverage run --context=${{ matrix.os }}.py${{ matrix.python-version }} --source=wntr --omit=$OMIT -m pytest -m "not extensions" --ignore=wntr/extensions --doctest-modules --doctest-glob="*.rst" wntr
175+
coverage run --context=${{ matrix.os }}.py${{ matrix.python-version }} --source=wntr --omit=$OMIT --append -m pytest --doctest-glob="*.rst" --ignore-glob="*/extensions/*.rst" documentation
176176
- name: Run Tests (ARM-processor)
177177
if: ${{ matrix.os == 'macos-latest'}}
178178
# doctests are not flexible enough to skip EPANET=v2.0 errors on ARM processor, so do not run doctests on ARM system
@@ -200,8 +200,7 @@ jobs:
200200
- name: Install coverage
201201
run: |
202202
python -m pip install --upgrade pip
203-
pip install -r requirements.txt
204-
python -m pip install -e .
203+
python -m pip install -e .[optional,test]
205204
pip install coveralls
206205
- name: Download coverage artifacts from test matrix
207206
uses: actions/download-artifact@v4

‎.github/workflows/extensions.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# This workflow will install Python dependencies, run tests and lint with a single version of Python
2+
# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
3+
4+
name: extensions
5+
6+
on:
7+
push:
8+
branches:
9+
- '**'
10+
pull_request:
11+
branches:
12+
- '**'
13+
14+
jobs:
15+
test:
16+
strategy:
17+
matrix:
18+
python-version: ['3.10', '3.11', '3.12', '3.13']
19+
fail-fast: false
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@v2
23+
- name: Set up Python ${{ matrix.python-version }}
24+
uses: actions/setup-python@v4
25+
with:
26+
python-version: ${{ matrix.python-version }}
27+
- name: Install packages
28+
run: |
29+
python -m pip install --upgrade pip
30+
pip install -e .[optional,test]
31+
- name: Run tests and coverage (unittests plus doctests)
32+
run: |
33+
coverage run --source=wntr --include="*/extensions/*" -m pytest -m extensions --doctest-modules wntr
34+
coverage run --source=wntr --include="*/extensions/*" --append -m pytest --doctest-glob="extensions/*.rst" documentation
35+
# coverage report --fail-under=70
36+

‎.github/workflows/quick_check.yml‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -27,15 +27,13 @@ jobs:
2727
- name: Install packages
2828
run: |
2929
python -m pip install --upgrade pip
30-
pip install -r requirements.txt
31-
pip install --upgrade coverage pytest
32-
- name: Install package for development
33-
run: |
34-
python -m pip install -e .
30+
pip install -e .[optional,test]
3531
- name: Run tests and coverage (unittests plus doctests)
32+
env:
33+
OMIT: "'*/tests/*','*/extensions/*','*/sim/network_isolation/network_isolation.py','*/sim/aml/evaluator.py'"
3634
run: |
37-
coverage run --source=wntr --omit="*/tests/*","*/sim/network_isolation/network_isolation.py","*/sim/aml/evaluator.py" -m pytest -m "not time_consuming" --doctest-modules --doctest-glob="*.rst" wntr
38-
coverage run --source=wntr --omit="*/tests/*","*/sim/network_isolation/network_isolation.py","*/sim/aml/evaluator.py" --append -m pytest --doctest-glob="*.rst" documentation
35+
coverage run --source=wntr --omit=$OMIT -m pytest -m "not time_consuming and not extensions" --ignore=wntr/extensions --doctest-modules --doctest-glob="*.rst" wntr
36+
coverage run --source=wntr --omit=$OMIT --append -m pytest --doctest-glob="*.rst" --ignore-glob="*/extensions/*.rst" documentation
3937
coverage report --fail-under=70
4038
# coverage run --source=wntr --omit="*/tests/*" --append -m pytest --doctest-glob="*.rst" documentation
4139

‎documentation/developers.rst‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,8 @@ Bug reports and feature requests
9393
Bug reports and feature requests can be submitted to https://github.com/USEPA/WNTR/issues.
9494
The core development team will prioritize and assign bug reports and feature requests to team members.
9595

96+
.. _contributing:
97+
9698
Contributing
9799
---------------------
98100
Software developers, within the core development team and external collaborators,
@@ -101,6 +103,8 @@ Software developers interested in contributing to the project are encouraged to
101103
create a `Fork` of the project and submit a `Pull Request` using GitHub.
102104
Pull requests will be reviewed by the core development team.
103105

106+
Pull requests
107+
^^^^^^^^^^^^^
104108
Pull requests can be made to the **main** or **dev** (development) branch.
105109
Developers can discuss new features and the appropriate branch for contributing
106110
by opening a new issue on https://github.com/USEPA/WNTR/issues.
@@ -115,6 +119,35 @@ Pull requests must meet the following minimum requirements to be included in WNT
115119

116120
* Network model files will not be duplicated in the repository. Network files are stored in examples/network and wntr/tests/networks_for_testing only.
117121

122+
Extensions
123+
^^^^^^^^^^
124+
WNTR extensions are intended to house beta and self-contained functionality that adds to WNTR.
125+
Developers interested in contributing to WNTR extensions should communicate with the core development team
126+
through https://github.com/USEPA/WNTR/issues prior to submitting a pull request.
127+
See :ref:`extensions` for a list of current WNTR extensions.
128+
129+
Extensions adhere to the following file structure:
130+
131+
* **Source code**: Source code files (*.py) associated with the extension, with the exception of documentation and testing,
132+
reside in a folder named ``wntr\extensions\<extension_name>``. The folder contains an ``__int__.py`` file to import the extension.
133+
* **Documentation**: Documentation resides in a file named ``documentation\extensions\<extension_name>.rst``.
134+
The documentation page should include
135+
1) a high level summary of the extension,
136+
2) a point of contact (developer name and GitHub username), and
137+
3) supporting documentation and examples (using doctest).
138+
A link to the documentation should also be added to ``documentation\extensions.rst`` and ``documentation\userguide.rst``.
139+
* **Testing**: Tests are run using the `extensions workflow <https://github.com/USEPA/WNTR/tree/main/.github/workflows/extensions.yml>`_.
140+
Tests reside in a file named ``wntr\tests\extensions\test_<extension_name>.py``.
141+
Tests should be marked ``@pytest.mark.extensions``.
142+
* **Requirements**: If the extension requires packages beyond WNTR's core dependencies, add a corresponding entry to
143+
``extras_require`` in ``setup.py``. Users can then install the extension's dependencies with ``pip install wntr[<extension_name>]``.
144+
145+
.. note::
146+
While documentation is required for extensions, the documentation is not included in the
147+
`WNTR EPA Report <https://cfpub.epa.gov/si/si_public_record_report.cfm?Lab=NHSRC&dirEntryID=337793>`_.
148+
Documentation for extensions is only available online.
149+
Extensions that have long-term test failures will be removed from the repository.
150+
118151
Software release
119152
------------------
120153
The software release process requires administrative privileges and knowledge about the external services used in the release process.

‎documentation/extensions.rst‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
.. raw:: latex
2+
3+
\clearpage
4+
5+
.. _extensions:
6+
7+
Extensions
8+
==========
9+
|extensions|
10+
11+
.. |extensions| image:: https://github.com/USEPA/WNTR/actions/workflows/extensions.yml/badge.svg
12+
:target: https://github.com/USEPA/WNTR/actions/workflows/extensions.yml
13+
14+
WNTR extensions are intended to house beta and self-contained functionality that adds to WNTR,
15+
but is currently not part of core WNTR development. The extensions should be designed for a wide audience.
16+
17+
WNTR currently includes the following extension:
18+
19+
- :ref:`hello_world`
20+
21+
Additional extensions will be added at a later date.
22+
23+
.. note::
24+
Developers interested in contributing to WNTR extensions should communicate with the core development team
25+
through https://github.com/USEPA/WNTR/issues prior to submitting a pull request.
26+
See :ref:`contributing` for more information.
27+
28+
While documentation is required for extensions, the documentation is not included in the
29+
`WNTR EPA Report <https://cfpub.epa.gov/si/si_public_record_report.cfm?Lab=NHSRC&dirEntryID=337793>`_.
30+
Documentation for extensions is only available online.
31+
Extensions that have long term test failures will be removed from the repository.
32+
33+
Third-party packages
34+
---------------------
35+
Developers are also encouraged to create third-party software packages that extends functionality in WNTR.
36+
A list of software packages that build on WNTR is included below:
37+
38+
.. include:: third_party_software.rst

‎documentation/extensions/hello_world.rst‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
2+
.. role:: red
3+
4+
.. raw:: latex
5+
6+
\clearpage
7+
8+
.. _hello_world:
9+
10+
Hello World
11+
===========================================
12+
13+
**Summary**: "hello_world" is a WNTR extension that demonstrates the file structure of a simple extension.
14+
See :ref:`contributing` for more information on creating an extension.
15+
16+
**Point of contact**: Katherine Klise, https://github.com/kaklise
17+
18+
-----
19+
20+
The Hello World extension contains a single function that returns "Hello World!".
21+
22+
.. doctest::
23+
24+
>>> import wntr.extensions.hello_world as hello_world
25+
26+
>>> output = hello_world.example_module.example_function()
27+
>>> print(output)
28+
Hello World!

‎documentation/index_latex.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ WNTR documentation
3535
graphics
3636
gis
3737
advancedsim
38+
extensions
3839
license
3940
users
4041
developers

‎documentation/third_party_software.rst‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
* CriticalityMaps: https://github.com/pshassett/CriticalityMaps
2+
3+
* Digital HydrAuLic SIMulator (DHALSIM): https://github.com/Critical-Infrastructure-Systems-Lab/DHALSIM
4+
5+
* InfraRisk: https://github.com/srijithbalakrishnan/dreaminsg-integrated-model
6+
7+
* LeakDB: https://github.com/KIOS-Research/LeakDB
8+
9+
* MAGNets: https://github.com/meghnathomas/MAGNets
10+
11+
* MILPNet: https://github.com/meghnathomas/MILPNet
12+
13+
* PPMTools: https://github.com/USEPA/PPMtools
14+
15+
* PTSNet: https://github.com/gandresr/ptsnet
16+
17+
* TSNet: https://github.com/glorialulu/TSNet
18+
19+
* VisWaterNet: https://github.com/tylertrimble/viswaternet
20+
21+
* wntr-qgis: https://github.com/angusmcb/wntr-qgis
22+
23+
* wntr-quantum: https://github.com/QuantumApplicationLab/wntr-quantum
24+
25+
See the `WNTR GitHub Dependeny Graph <https://github.com/USEPA/WNTR/network/dependents?dependent_type=REPOSITORY>`_ to find additional repositories and packages that use WNTR.

‎documentation/userguide.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,14 @@ U.S. Department of Energy's National Nuclear Security Administration under contr
7272
graphics
7373
gis
7474
advancedsim
75+
76+
.. toctree::
77+
:maxdepth: 1
78+
:hidden:
79+
:caption: Extensions
80+
81+
extensions
82+
extensions/hello_world
7583

7684
.. toctree::
7785
:maxdepth: 1

0 commit comments

Comments
 (0)