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.

• Architecture Decision Records
• Project Scoping Document
• Data Dictionary
• ...

• 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

1. Clone the repository on your local machine
2. Change directory into the cloned project: cd python-boilerplate
3. Run the setup command make setup

When using this boilerplate code as a template for your own project, follow the steps below:

1. Complete all of the TODO items listed as comments in this README
2. Pick a new name for your package, then replace the word boilerplate with that new name in the following places:
   • pyproject.toml
   • src/boilerplate/ and all files within that directory
   • tests/ and all of the files within that directory
3. 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/
   

4. If the new code requires a package that is not already installed, add it to the project by using poetry add <package_name>
5. If you make any manual changes to the pyproject.toml file make sure you run: poetry lock && poetry install
6. 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.py
   
   

   NOTE

   • 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}

1. {Step 1 to complete use case}
2. {Step 2 to complete use case}
3. ...

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.

• @widal001

• Python Packaging Authority Sample Project
• Best README Template