This project serves as a catch-all for openmod devs' useful python tools and APIs (though we are generally language lovers and are not limited to Python specifically).
For the foreseeable future, this repo is a bit adhoc -- anything of use that fits
the general theme of energy modeling is welcome. We try to split additions by
subject into the appropriate files (e.g., GIS-related work to gis.py, etc.).
The contributors to this repository strive to write clear, understandable, tested, and documented code. We recognize this requires a nontrivial effort and respect the effort of others by being willing to review pull requests and otherwise offer comments, critiques, and first-user experiences.
Apart from using the issue tracker, please join the listserv for any in depth discussions.
As this is a hodgepodge of tools, different tooling requires different dependencies.
- numpy
- pandas
- scipy
- fiona
- rasterio
- shapely
- pyomo
You can install toolchest like any other python module
./setup.py install
or for local installations
./setup.py install --user
From the root directory, run
nosetests -w tests
After you install the project locally, you can generate documentation by
cd docs
make html
You can serve the documentation locally via
make serve
You can then view the docs at http://localhost:8000/build/html/
Follow the above instructions replacing make with ./make.bat.
toolchest currently follows a master-branch based work flow. All features
introduced in pull requests are merged directly into master. Should the code
base become more complex, it is likely that we will transition to a
develop-master git-based release work flow, as described
here.
We follow semantic versioning for version numbering.
Any contribution can be pulled into master via a Pull Request provided it
meets the following conditions:
- follows pep8 style
- is documented with docstrings formatted in the numpy style
- is tested
- passes CI on both Windows and Linux
- is reviewed by at least one other contributor
Contributions that upgrade only documentation are the sole caveat to the above
requirements. Documentation-only additions can be pushed directly to the
master branch. However, if a review is desired, they can of course go through
the process as well.
Style guides are always annoying to follow at first but are
immensely useful. Feel
free to hook in autopep8 to your
favorite editor to automatically fix any style issues. For emacs, you can add
the following lines
; see https://github.com/paetzke/py-autopep8.el
(require 'py-autopep8)
(add-hook 'python-mode-hook 'py-autopep8-enable-on-save)
Should any conflicts arise in the course of the project, without any other particularly good solution, resolution will follow a majority rule on the listserv.