Table of Contents
Python Boilerplate provides a common file structure for a Python project and encourages best practices in python development, including some simple code quality checks set up and some idiomatic examples of python data structures and functions. This project is a template that can be used as a foundation for future projects.
- poetry - Dependency management library that makes creating and installing packages more streamlined.
- pytest - Simplifies the design and execution of both unit and integration testing.
- black - Autoformats code for consistent styling.
- ruff - Checks that code follows idiomatic best practices for Python.
- pylint - Applies a few additional checks that aren't covered by ruff.
- pre-commit - Runs code quality checks before code is committed.
- Python installed on your local machine, a version between 3.7 and 3.9
- Poetry installed on your local machine
In order to check that you have both Python and Poetry installed, run the following in your command line, and the output should look something like this:
NOTE: in all of the code blocks below, lines preceded with $ indicate commands you should enter in your command line (excluding the $ itself), while lines preceded with > indicate the expected output from the previous command.
$ python --version && poetry --version
> Python 3.9.0
> Poetry version 1.1.6
TROUBLESHOOTING: If you receive an error message, or the version of python you have installed is not between 3.7 and 3.9, consider using a tool like pyenv (on Mac/Linux) or pyenv-win (on Windows) to manage multiple python installations.
If you have python installed but not poetry, follow these installation instructions:
- Clone the repository on your local machine
- Change directory into the cloned project:
cd python-boilerplate - Run the setup command
make setup
When using this boilerplate code as a template for your own project, follow the steps below:
- Complete all of the
TODOitems listed as comments in this README - Pick a new name for your package, then replace the word
boilerplatewith that new name in the following places:pyproject.tomlsrc/boilerplate/and all files within that directorytests/and all of the files within that directory
- All new python code should be added either as a single module or collection of modules under the
src/{your_package_name}/directory. For reference:pyproject.toml src/ your_package_name/ main.py your_new_module_1.py your_new_module_2/ your_new_module_2_1.py your_new_module_2_2.py tests/ - If the new code requires a package that is not already installed, add it to the project by using
poetry add <package_name> - If you make any manual changes to the
pyproject.tomlfile make sure you run:poetry lock && poetry install - Each new method or function you write needs to be accompanied by a test which calls that method or function. These unit and/or integration tests should be added to the
tests/directory using a file structure that mirrors the modules you are contributing to. For reference:tests/ conftest.py test_main.py test_your_new_module_1.py your_new_module_2/ test_your_new_module_2_1.py test_your_new_module_2_2.pyNOTE
- CI/CD checks will only pass if more than 90% of the code base is executed by the tests
- Pytest requires the following naming conventions for test discovery
{1-2 sentence summary of this use case}
- {Step 1 to complete use case}
- {Step 2 to complete use case}
- ...
The vision for this template is to simplify the process of creating open source python projects with high quality codebase and mechanisms that promote smart and collaborative project governance. This project aims to fulfill this vision by:
- Adopting a common python package file structure
- Implementing basic linting and code quality checks
- Reinforcing compliance with those code quality checks using CI/CD
- Providing templates for things like documentation, issues, and pull requests
- Offering pythonic implementation examples of common data structures and scripting tasks like:
- Creating classes, methods, and functions
- Setting up unit and integration testing
- Reading and writing to files
Contributions are always welcome! We encourage contributions in the form of discussion on issues in this repo and pull requests for improvements to documentation and code.
See CONTRIBUTING.md for ways to get started.
Distributed under the MIT License. See LICENSE for more information.