Python Project Template

A template for Python projects that includes documentation, tests and installable scripts.

Project Structure

The following is a summary of the directory structure which was created with the tree command. We will explain each of the directories and files in more detail in the following sections.

.
├── docs
│   ├── conf.py
│   ├── how_to_use.md
│   ├── images
│   │   ├── pulsar_plot_all.png
│   │   ├── pulsar_plot_source.png
│   │   └── pulsar_plot_south.png
│   ├── index.rst
│   ├── installation.md
│   ├── Makefile
│   ├── my_project_modules.rst
│   └── requirements.txt
├── .github
│   └── workflows
│       ├── pytest.yml
│       └── sphinx_docs.yml
├── .gitignore
├── initial_script.py
├── my_package
│   ├── data
│   │   └── pulsars.csv
│   ├── __init__.py
│   ├── data_processing.py
│   ├── load_data.py
│   ├── my_file.py
│   ├── plotting.py
│   └── scripts
│       └── __init__.py
│       ├── filter_and_plot.py
│       ├── hello_world.py
├── README.md
├── setup.py
└── tests
    ├── test_data
    │   └── test_source_input.csv
    └── test_data_processing.py

docs

The docs directory contains the documentation for your project and contains the following files.

• This conf.py file which is used by Sphinx to configure the documentation build.
• The Makefile is used to build the documentation.
• The requirements.txt file is where you can add the python dependencies required to generate the documentation.
• The index.rst file is the home page of the documentation and is where you can add a description of your project and a contents page.
• The installation.md file is where you can add instructions for installing your project.
• The how_to_use.md file is where you can add instructions and examples of how to use your project.
• The images directory is where you can add images that are used in your documentation.
• The my_project_modules.rst file is where you can add a description of each of the modules in your project. These are automatically generated by Sphinx using your functions' docstrings.

.github/workflows

The .github/workflows directory contains the GitHub Actions workflows for running tests and building the documentation.

• The pytest.yml file is the GitHub Actions workflow for running tests. You can edit the file to test different python versions or to launch the action on a pull request.
• The sphinx_docs.yml file is the GitHub Actions workflow for building the documentation. This will update the gh-pages branch with the latest documentation which you can view on the github pages URL.

.gitignore

The .gitignore file is used to specify files and directories that should be ignored by git (won't see them on the git status command or be able to git add them). This is useful for ignoring files that are generated by your project (e.g. the __pycache__ or build directories) or files that contain sensitive information (e.g. passwords).

initial_script.py

The initial_script.py is an example of a proof of concept script that can read in some data and make a plot. This filter_and_plot.py script in the my_package/scripts directory is an improved version as it can be installed using setup.py to put it on the $PATH so you can use it on the command line.

my_package

The my_package directory is where you can put all of your python code that you would like to install (rename this directory based on what you want to name your project).

• The __init__.py is an empty file is required to make the directory a python package. Once this is put on the $PYTHONPATH you can import this package and its modules (e.g. import my_package).
• The data directory is where you can put any data files that your project needs to run. This is useful for storing data that is used by multiple scripts in your project without having to set environment variables. These file paths are loaded with load_data.py module.
• The data_processing.py module contains functions that are used to load and filter the data.
• The load_data.py module contains functions that are used to load the data from the data directory.
• The my_file.py module contains a simple example function used by the hello_world script.
• The plotting.py module contains functions that are used to plot the data.
• The scripts directory is where you can put any scripts that you would like to install on the $PATH so you can use them on the command line. These scripts are installed using setup.py and can be run from the command line (e.g. filter_and_plot.py).

my_package/scripts

The my_package/scripts directory is where you can put any scripts that you would like to install on the $PATH so you can use them on the command line.

• The __init__.py is an empty file is required to make the scripts importable.
• The filter_and_plot.py script is an improved version of the initial_script.py which has command line arguments.
• The hello_world.py script is a simple example to help you understand the directory structure and how to use a setup.py.

README.md

The README.md file is a markdown file that is used to describe your project. This is the file that is displayed on the GitHub repository page.

setup.py

The setup.py file is used to install your project on the $PYTHONPATH so you can import it and use it in other projects. You can also define dependencies that are required to run your project and scripts that you would like to install on the $PATH so you can use them on the command line.

tests

The tests directory is where you can put all of your tests for your project. The pytest command will automatically find and run all of the tests in this directory (or anything that starts with test_) and run them. These tests are run automatically by GitHub Actions when you push to GitHub (using .github/workflows/pytest.yml).

• The test_data_processing.py file contains tests for the data_processing.py module.
• The test_data directory contains data files that are used by the tests.
• The test_source_input.csv file is a subset of the pulsars.csv file that is used to test the data_processing.py module.