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
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
.
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