Contributing to Pint#

Pint uses (and thanks):

You can contribute in different ways:

Report issues#

You can report any issues with the package, the documentation to the Pint issue tracker. Also feel free to submit feature requests, comments or questions.

Contribute code#

To contribute fixes, code or documentation to Pint, fork Pint in github and submit the changes using a pull request against the master branch.

  • If you are submitting new code, add tests (see below) and documentation.

  • Write “Closes #<bug number>” in the PR description or a comment, as described in the github docs.

  • Log the change in the CHANGES file.

  • Execute pre-commit run --all-files and resolve any issues.

In any case, feel free to use the issue tracker to discuss ideas for new features or improvements.

Notice that we will not merge a PR if tests are failing. In certain cases tests pass in your machine but not in travis. There might be multiple reasons for this but these are some of the most common

  • Your new code does not work for other Python or Numpy versions.

  • The documentation is not being built properly or the examples in the docs are not working.

  • linters are reporting that the code does no adhere to the standards.

Setting up your environment#

If you’re contributing to this project for the fist time, you can set up your environment on Linux or OSX with the following commands:

$ git clone git@github.com:hgrecco/pint.git
$ cd pint
$ python -m virtualenv venv
$ source venv/bin/activate
$ pip install -e '.[test]'
$ pip install -r requirements_docs.txt
$ pip install pre-commit # This step and the next are optional but recommended.
$ pre-commit install

Writing tests#

We use pytest for testing. If you contribute code you need to add tests:

  • If you are fixing a bug, add a test to test_issues.py, or amend/enrich the general test suite to cover the use case.

  • If you are adding a new feature, add a test in the appropiate place. There is usually a test_X.py for each X.py file. There are some other test files that deal with individual/specific features. If in doubt, ask.

  • Prefer functions to classes.

  • When using classes, derive from QuantityTestCase.

  • Use parametrize as much as possible.

  • Use fixtures (see conftest.py) instead of instantiating the registry yourself. Check out the existing fixtures before creating your own.

  • When your test does not modify the registry, use sess_registry fixture.

  • Do not create a unit registry outside a test or fixture setup.

  • If you need a specific registry, and you need to reuse it create a fixture in your test module called local_registry or similar.

  • Checkout helpers.py for some convenience functions before reinventing the wheel.

Running tests and building documentation#

To run the test suite, invoke pytest from the pint directory:

$ cd pint
$ pytest

To run the doctests, invoke Sphinx’s doctest module from the docs directory:

$ cd docs
$ make doctest

To build the documentation, invoke Sphinx from the docs directory:

$ cd docs
$ make html

Extension Packages#

Pint naturally integrates with other libraries in the scientific Python ecosystem, and a small number of `extension/compatibility packages<numpy.html#Compatibility-Packages>`_ have arisen to aid in compatibility between certain packages. Pint’s rule of thumb for integration features that work best as an extension package versus direct inclusion in Pint is:

  • Extension (separate packages)

  • Integration (built in to Pint)

    • Duck array types wrapped by Pint (below Pint in the type casting hierarchy)

    • Intermingling of APIs occurs

    • Examples: Dask