CONTRIBUTING.md

Contributing to PyFilesystem

Pull Requests are very welcome for this project!

For bug fixes or new features, please file an issue before submitting a pull request. If the change isn't trivial, it may be best to wait for feedback. For a quicker response, contact Will McGugan directly.

tox

Most of the guidelines that follow can be checked with a particular tox environment. Having it installed will help you develop and verify your code locally without having to wait for our Continuous Integration pipeline to finish.

Tests

New code should have unit tests. We strive to have near 100% coverage. Get in touch, if you need assistance with the tests. You shouldn't refrain from opening a Pull Request even if all the tests were not added yet, or if not all of them are passing yet.

Dependencies

The dependency for running the tests can be found in the tests/requirements.txt file. If you're using tox, you won't have to install them manually. Otherwise, they can be installed with pip:

$ pip install -r tests/requirements.txt

Running (with tox)

Simply run in the repository folder to execute the tests for all available environments:

$ tox

Since this can take some time, you can use a single environment to run tests only once, for instance to run tests only with Python 3.9:

$ tox -e py39

Running (without tox)

Tests are written using the standard unittest framework. You should be able to run them using the standard library runner:

$ python -m unittest discover -vv

Coding Guidelines

This project runs on Python2.7 and Python3.X. Python2.7 will be dropped at some point, but for now, please maintain compatibility. PyFilesystem2 uses the six library to write version-agnostic Python code.

Style

The code (including the tests) should follow PEP8. You can check for the code style with:

$ tox -e codestyle

This will invoke flake8 with some common plugins such as flake8-comprehensions.

Format

Please format new code with black, using the default settings. You can check whether the code is well-formatted with:

$ tox -e codeformat

Type annotations

The code is typechecked with mypy, and type annotations written as comments, to stay compatible with Python2. Run the typechecking with:

$ tox -e typecheck

Documentation

Dependencies

The documentation is built with Sphinx, using the ReadTheDocs theme. The dependencies are listed in docs/requirements.txt and can be installed with pip:

$ pip install -r docs/requirements.txt

Building

Run the following command to build the HTML documentation:

$ python setup.py build_sphinx

The documentation index will be written to the build/sphinx/html/ directory.

Style

The API reference is written in the Python source, using docstrings in Google format. The documentation style can be checked with:

$ tox -e docstyle