Contributing

If you would like to contribute to this project, please follow the following steps:

  1. Fork this repository

  2. Create a new branch for your feature or bugfix

  3. Make your changes

  4. Commit your changes

  5. Push your changes to your fork

  6. Create a pull request

Please make sure to follow the coding standards and conventions used throughout the project. Also, please make sure to write tests for your code.

Create a virtual environment

Create a virtual environment and install the required dependencies using the following commands:

$ python3 -m venv venv
venv$ source venv/bin/activate
venv$ pip install .[dependencies] .[dev-dependencies]

Running the tests

Tests can be run using the following command:

venv$ bin/run_tests.sh
======================================= test session starts =======================================
platform darwin -- Python 3.10.4, pytest-7.4.2, pluggy-1.3.0
rootdir: /Users/olijohns/cfgclasses
plugins: anyio-4.3.0, mypy-testing-0.1.1
collected 60 items

cfgclasses/test/test_argspec.py ....................................                        [ 60%]
cfgclasses/test/test_configclass.py ....                                                    [ 66%]
cfgclasses/test/test_deprecated_api.py .....                                                [ 75%]
cfgclasses/test/test_transforms.py ...                                                      [ 80%]
cfgclasses/test/test_typing.py ............                                                 [100%]

======================================= 60 passed in 3.07s ========================================
Wrote XML report to coverage.xml
Name                                     Stmts   Miss  Cover   Missing
----------------------------------------------------------------------
cfgclasses/__init__.py                       6      0   100%
cfgclasses/arghelper.py                     58      1    98%   323
cfgclasses/argspec.py                      162      3    98%   334, 348-349
cfgclasses/configclass.py                   66      2    97%   88, 98
cfgclasses/test/__init__.py                  0      0   100%
cfgclasses/test/test_argspec.py             86      0   100%
cfgclasses/test/test_configclass.py         59      0   100%
cfgclasses/test/test_deprecated_api.py      61      0   100%
cfgclasses/test/test_transforms.py          40      0   100%
cfgclasses/test/test_typing.py              57      0   100%
cfgclasses/transforms.py                    13      0   100%
cfgclasses/validation.py                    29      0   100%
----------------------------------------------------------------------
TOTAL                                      637      6    99%

Code coverage should be as close to 100% as possible. Only minor error flows are skipped in the current code.

Run the formatters linters

Linters can be run using the following command:

venv$ bin/run_tools.sh
All done! ✨ 🍰 ✨
17 files left unchanged.
Skipped 5 files
Success: no issues found in 16 source files

--------------------------------------------------------------------
Your code has been rated at 10.00/10 (previous run: 10.00/10, +0.00)

Build the documentation

The documentation can be built using the following command:

venv$ bin/build_docs.sh
Running Sphinx v7.2.5
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 8 source files that are out of date
updating environment: 1 added, 8 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] index
generating indices... genindex py-modindex done
writing additional pages... search done
copying images... [100%] _static/icon.png
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.

This can then be viewed locally by opening the _build/html/index.html file in a web browser. E.g. with python3 -m http.server and navigating to http://localhost:8000/_build/html/index.html

Building the package for deployment

The package can be built and deployed to pypi using the following commands.

Be sure to bump the version number in pyproject.toml and docs/source/conf.py before release. Similarly, be sure to tag the git commit for the release with the version number.

venv$ python3 -m pip install --upgrade hatch twine pkginfo
venv$ python3 -m build
venv$ python3 -m twine upload --repository testpypi dist/* # To test the upload
venv$ python3 -m twine upload dist/* # To upload to pypi