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.
- 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, preferably a version between 3.7 and 3.9
In order to check which version of python you have 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
> Python 3.9.0
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.
- 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 - Create a new virtual environment:
python -m venv env - Activate the virtual environment
- On Mac/Linux:
source env/bin/activate - On Windows:
.\env\Scripts\activate
- On Mac/Linux:
- Install this package in editable mode by running
pip install -e .which makes changes made to scripts within this package available without re-installing it. - Install the other dependencies required to contribute to the project:
pip -r requirements.txt - Install
pre-committo autoformat your code:pre-commit install - Execute all tests by running
toxAll 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:setup.pytox.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:setup.py 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 listed in the
requirementst.txtadd that dependency to the following locations in this package:- Add the name of the package to the list of packages passed to
install_requiresinsetup.pylike so:import os from setuptools import find_packages from setuptools import setup # ... setup( # ... install_requires=[ "pandas", # needs to be a string ], include_package_data=True, package_dir={'': 'src'}, packages=find_packages(where="src"), ) - Add the name and version to
requirements.txtlike so:# ... pytest-cov==2.12.1 pandas==1.2.4
- Add the name of the package to the list of packages passed to
- 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.