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 strctures 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.
- tox - Automates and standardizes the creation of testing environments.
- pytest - Simplifies the design and execution of both unit and integration testing.
- black - Autoformats code for consistent styling.
- flake8 - Checks that code complies with PEP8 style guidelines.
- pylint - Checks that code follows idiomatic best practices for Python.
- 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:
- Global install on Mac/Linux
- Global install on Windows
- Local install inside a virtual environment using
pipNOTE: This is not recommended because of potential package conflicts:- Create a virtual environment:
python -m venv env - Acvitate the virtual environment. NOTE: This virtual environment must be active any time you are working with this project:
- Mac/Linux:
source env/bin/activate - Windows:
env\Scripts\activate
- Mac/Linux:
- Install poetry:
pip install poetry
- Create a virtual environment:
- Clone the repository on your local machine:
git clone https://github.com/widal001/python-boilerplate.git - Change directory into the cloned project:
cd python-boilerplate - Install the package:
poetry install - Install
pre-committo autoformat your code:poetry run pre-commit install - Execute all tests:
poetry run tox - All tests should pass with an output that ends in something like this:
py39: commands succeeded lint: commands succeeded checkdeps: commands succeeded pytest: commands succeeded coverage: commands succeeded congratulations :)
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.tomltox.inisrc/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
For a more detailed breakdown of the feature roadmap and other development priorities please reference the following links:
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.