python-boilerplate

This template repository serves as a boilerplate for new python projects, and assumes that your project has the potential to be distributed as a package on PyPI, comes with a readthedocs page, and includes testing.

Contents

• Top level files
• src/ files
• src/ files
• docs/ files
• tests/ files
• Using the template
  • Building and Distribution
  • Running your tests

Last Updated: April 11th, 2022

The structure is as follows:

~/python-package-boilerplate/
    README.md
    LICENSE
    pyproject.toml
    setup.cfg
    .gitignore
    src/
        python_package_boilerplate/
            __init__.py
            module.py
    docs/
        build/
            ... 
        source/
            _static/
            _templates/
            conf.py
            index.rst
            install.rst
        make.bat
        Makefile
    tests/
        __init__.py
        tests_module.py

python-package-boilerplate/ files

README.md is the README file for your project, in Markdown.

LICENSE is the license your project is distributed under (the default for this template is MIT). FILL IN THE YEAR AND YOUR NAME!

pyproject.toml is specifies the build system, and in this template is filled out with default information¹.

setup.cfg is a configuration file used to configure setuptools and provide metadata about your project. Because this template assumes a src/ structure for the package (that is, the code for the package is included in a subdirectory named src/), setup.cfg instructs setuptools to look there for the package itself². If your package has dependencies, they should be put here under [options] like so³:

[options]
#...
install_requires =
    req1
    req2 ==1.1

This setup.cfg also assumes that the project you're working on requires Python 3.6 or greater, which is also under [options].

.gitignore includes a number of things that should not be pushed to the git repo for your project, this may need to be updated for your needs. A great template for putting together your own .gitignore file can be found here.

src/ files

This template assumes a src/ structure for your project, which has a few benefits, making your project easier to test and distribute for other users⁴.

python_package_boilerplate/ is the top level directory for the code of your project.

src/ is a subdirectory of python_package_boilerplate/

mypackage/ is a subdirectory of src/ and contains the actual code for your package.

__init__.py essentially let's python know that this directory indeed is a package, it's left empty for this boilerplate project.

module.py is your main module, assuming your package would be put into one module. Be sure to rename this to something better for your own project!

docs/ files

This directory contains some starter Sphinx documentation files. It assumes you have installed sphinx-autoapi and sphinx-rtd-theme which you can get by running the following:

pip install sphinx-autoapi
pip install sphinx_rtd_theme

build/ is the directory for the built files of your Sphinx documentation, you shouldn't touch anything here. It isn't present in this repository, but it will appear when you build the documentation.

source/ is the directory with the files you'll actually work with. As it is now, conf.py is set up appropriately to generate the Sphinx documentation with AutoAPI so that it pulls docstrings from your python code in 'src/'. Do whatever you need to do with this documentation!

A readthedocs tutorial can be found here.

When working on your documentation, it's very helpful to set it to autobuild so you don't need to rebuild and refresh your browser every time you make a change⁵. In order to do this, do the following:

pip install sphinx-autobuild
sphinx-autobuild [path/to/source/docs/] [path/to/build/html]

Then point your browser to http://localhost:8000

When pushing your repository to github, you can import it as a project on your readthedocs account and it should generate correctly.

tests/ files

__init__.py essentially let's python know that this directory is a package, it's left empty for the test directory too.

tests_module.py contains a very basic unit test, though depending on the size of your project, you may want to split your tests into multiple files. You can learn about the python unittest framework here and here.

Using the Template

Building and Distributing

Instructions for building and distributing your package can be found at this link.

Running your tests

Because this template assumes a src/ layout for unit tests, you must install your package as an "edtiable install"⁶ in order for the testing package to be able to find it in your $PYTHONPATH and run the tests properly. To do this, simply run the following from the top directory of the project within the environment you're using:

pip install -e .

Then, from within your tests/ directory you can run your tests like so:

python -m unittest tests_module

Footnotes

1. https://setuptools.pypa.io/en/latest/build_meta.html ↩

2. https://setuptools.pypa.io/en/latest/userguide/declarative_config.html#declarative-config ↩

3. https://setuptools.pypa.io/en/latest/userguide/dependency_management.html ↩

4. https://hynek.me/articles/testing-packaging/ ↩

5. https://frankwiles.com/posts/automatically-rebuild-sphinx-docs/ ↩

6. https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs ↩