Contributing Guide

Welcome to the filehandlers contributing guidelines! Please follow what is listed here to help keep the project simple, easy to maintain, and complete.

Style Guide

Code

When writing code, please follow PEP8 [1], the style guide written for any Python. One exception for this is our line length - PEP8 says 79 characters is the limit, but we have decided to extend that to a maximum of 100 characters per line. Also, wherever possible, please add Docstrings.

Docstrings

We mainly use normal reStructuredText Docstrings for filehandlers. However, for elements that have more then one field - for example if a function has the potential to throw multiple exceptions - we use Google [2] and/or NumPy [3] styled Docstrings. These are later converted by the Sphinx extension napoleon during documentation builds. Please add Docstrings to functions, classes, modules (at the top), exceptions and enumerators.

If you add a class that is not covered by the documentation currently (e.x. you create a method or class that is not in a method/class that has the :members: autodoc method), you will need to add a field so autodoc knows the include the Docstring(s). To do this, navigate to the API reference page and add this underneath all the other classes/methods:

For classes/enumerators

,.. autoclass:: ClassName
   ,:members:
   ,:special-members: __init__

For functions

,.. autofunction:: function_name

For exceptions

,.. autoexception:: ExceptionName

Notes

• Make sure to remove the commas, they prevent autodoc from trying to add a method here on this page!
• You do not need to add module Docstrings to the API reference page.

Building the package

Simply run python setup.py sdist bdist_wheel. If you are on Linux/macOS, change python to python3. The build shouldn’t be long. When it is complete, you can find the .tar.gz and .whl in the dist directory.

[1]	Python Enhancement Proposal #8

[2]	Google Docstring Guide

[3]	NumPy Docstring Guide