Skip to main content

Python boilerplates

Various boilerplates used in almost all of my Python packages.

package version from PyPI build status from GitHub test coverage from Codecov grade from Codacy license

This package includes boilerplates for various common tasks in Python packages, such as building the package, testing the packaging process, storing the package config, logging for the package or creating a CLI.

Requirements

Python version 3.11 or later.

Python libraries as specified in requirements.txt.

Building and running tests additionally requires packages listed in requirements_test.txt.

Tested on Linux, macOS and Windows.

Available boilerplates

Setup boilerplate

Module boilerplates.setup provides a class Package that abstracts out many of the common tasks needed to set up the package. The class has a setup() class method that can be called from the if __name__ == '__main__' block in your setup.py file.

To avoid setup script boilerplate, create setup.py file with the minimal contents as given below and modify it according to the specifics of your package.

See the implementation of boilerplates.setup.Package for all other available options. Some fields don’t need to be entered and will be automatically initialised using various detectors. Also, some fields have default values. See DEFAULT_* constants in the boilerplates.setup for those values.

Example setup.py:

"""Setup script."""

import boilerplates.setup


class Package(boilerplates.setup.Package):
    """Package metadata."""

    name = ''
    description = ''
    url = 'https://github.com/mbdevpl/...'
    author = '...'
    author_email = '...'
    classifiers = [
        'Development Status :: 1 - Planning',
        'Programming Language :: Python :: 3.11',
        'Programming Language :: Python :: 3.12',
        'Programming Language :: Python :: 3.13',
        'Programming Language :: Python :: 3.14',
        'Programming Language :: Python :: 3.15',
        'Programming Language :: Python :: 3 :: Only']
    keywords = []


if __name__ == '__main__':
    Package.setup()

You will also need the following in your pyproject.toml file:

[build-system]
requires = ['boilerplates[setup] ~= <version>']

Packaging tests

As an extension of setup boilerplate, there’s an extra boilerplate for testing the packaging process, in a way that enables 100% code coverage, including the setup.py script.

In order to use it, all you need to do is create a file as follows in your tests directory.

Example test/test_packaging.py:

"""Tests for packaging."""

import boilerplates.packaging_tests


class Tests(boilerplates.packaging_tests.PackagingTests):
    pass

And, you will need to add the following to your requirements_test.txt file (or equivalent):

boilerplates[packaging-tests] ~= <version>

Config boilerplate

Module boilerplates.config provides few utility functions useful to handle local configuration.

Example usage:

import boilerplates.config

...

boilerplates.config.initialize_config_directory('app_name')

And, you will need to add the following to your requirements.txt file (or equivalent):

boilerplates[config] ~= <version>

Logging boilerplate

Assumptions for this boilerplate are that you want to use the standard built-in Python logging module (logging), and that your application probably has a CLI entry point or some executable script, as opposed to only being a library.

To reduce boilerplate necessary to setup logging for such application, add the following in your __main__.py:

"""Entry point of the command-line interface."""

import boilerplates.logging


class Logging(boilerplates.logging.Logging):
    """Logging configuration."""

    packages = ['package_name']


...


if __name__ == '__main__':
    Logging.configure()
    ...

More advanced usage could be (just changing the Logging class definition):

class Logging(boilerplates.logging.Logging):
    """Logging configuration."""

    packages = ['package_name']
    level_global = logging.INFO
    enable_file = True
    directory = 'package_name'

You can and should adjust the class fields to your needs, please take a look at the boilerplates.logging.Logging class implementation for details.

You may also use this boilerplate in tests even if your code is just a library. In such case, add the following to your test/__init__.py:

"""Initialization of tests."""

import logging

import boilerplates.logging


class TestsLogging(boilerplates.logging.Logging):
    """Logging configuration for tests."""

    packages = ['package_name']
    level_global = logging.INFO


TestsLogging.configure()

If you wish, you can make your test logging config be a variant of your application logging config, like so:

"""Initialization of tests."""

from my_package.__main__ import Logging


class TestsLogging(Logging):
    """Logging configuration for tests."""

    level_global = logging.DEBUG  # relevant if level_global is set to e.g. INFO in parent class
    enable_file = False  # relevant if enable_file is set to True in parent class

As for using the logging in your code, you can use it as usual, for example:

# in a standalone script:
_LOG = logging.getLogger(pathlib.Path(__file__).stem)
# in a standalone script that can also be imported:
_LOG = logging.getLogger(pathlib.Path(__file__).stem if __name__ == '__main__' else __name__)
# in __main__.py:
_LOG = logging.getLogger(pathlib.Path(__file__).parent.name)
# in usual module files:
_LOG = logging.getLogger(__name__)

And, you will need to add the following to your requirements.txt file (or equivalent):

boilerplates[logging] ~= <version>

Sentry boilerplate

This boilerplate aims at simplifying the process of setting up Sentry integration for your Python application.

Assumptions for this boilerplate are similar to logging boilerplate, in that you want to use the standard built-in Python logging module (logging), and that your application probably has a CLI entry point or some executable script, as opposed to only being a library.

Then, the example __main__.py file may look like:

"""Entry point of the command-line interface."""

import boilerplates.sentry

from ._version import VERSION


class Sentry(boilerplates.sentry.Sentry):
    """Sentry configuration."""

    release = VERSION


...


if __name__ == '__main__':
    Sentry.init()
    ...

You can and should adjust the class fields to your needs, please take a look at the boilerplates.sentry.Sentry class implementation for details.

And, you will need to add the following to your requirements.txt file (or equivalent):

boilerplates[sentry] ~= <version>

CLI boilerplate

This boilerplate aims at making CLIs easier to write, by providing a few utility functions.

Your example cli.py file which defines your command-line interface may look like:

"""Command-line interface definition."""

import argparse

import boilerplates.cli

def main(args=None):
    """Entry point of the command-line interface."""
    parser = argparse.ArgumentParser(
        prog='my-cli',
        description='''My command-line interface.''',
        epilog=boilerplates.cli.make_copyright_notice(
            2019, 2023, author='The Author', license_name='Apache License 2.0',
            url='https://github.com/...'))

    boilerplates.cli.add_version_option(parser, '1.0.1')
    boilerplates.cli.add_verbosity_group(parser)

    parsed_args = parser.parse_args(args)

    verbosity = boilerplates.cli.get_verbosity_level(parsed_args)
    ...

You can see the above example in action in the examples.ipynb notebook. Please see the boilerplates.cli module for details of the available features.

And then, an example __main__.py file may look like:

"""Entry point of the command-line interface."""

# PYTHON_ARGCOMPLETE_OK

from my_package import cli


if __name__ == '__main__':
    cli.main()

And, you will need to add the following to your requirements.txt file (or equivalent):

boilerplates[cli] ~= <version>

Then, the output of running python -m my_package -h will look like:

usage: my-cli [-h] [--version] [--verbose | --quiet | --verbosity LEVEL]

My command-line interface.

options:
-h, --help         show this help message and exit
--version          show program's version number and exit
--verbose, -v      be more verbose than by default (repeat up to 3 times for
                    stronger effect)
--quiet, -q        be more quiet than by default (repeat up to 2 times for
                    stronger effect)
--verbosity LEVEL  set verbosity level explicitly (normally from 0 to 5)

Copyright 2019-2023 by The Author. Apache License 2.0. https://github.com/...

And the output of running python -m my_package --version will look like:

my-cli 1.0.1, Python 3.11.0 (main, Feb 13 2023, 00:02:15) [GCC 12.1.0]

Git repo tests boilerplate

This boilerplate aims at making it easier to test your package in a context of a git repository.

It’s only useful if you create a Python package that operates on git repositories, and helps to create and modify synthetic git repositories for testing purposes.

To start using boilerplates.git_repo_tests, you can start with a file like this in your test folder, for example test/test_with_git_repo.py:

"""Perform tests on and in synthetic git repositories."""

import pathlib

import boilerplates.git_repo_tests


class Tests(boilerplates.git_repo_tests.GitRepoTests):

    ...

However, you will need to check the boilerplates.git_repo_tests.GitRepoTests class for details of available features.

And, you will need to add the following to your requirements_test.txt file (or equivalent):

boilerplates[git-repo-tests] ~= <version>

Metadata

Release files for boilerplates 1.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for boilerplates 1.3.0
File Size Uploaded Provenance Actions
boilerplates-1.3.0.tar.gz 42.8 kB With provenance Details for boilerplates-1.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for boilerplates 1.3.0
File Interpreter ABI Platform Actions
boilerplates-1.3.0-py3-none-any.whl Python 3 none any Details for boilerplates-1.3.0-py3-none-any.whl

Total release size: 80.3 kB

Release files / boilerplates-1.3.0.tar.gz

Download URL boilerplates-1.3.0.tar.gz
Size 42.8 kB
Tags Source
SHA-256 checksum
How to use checksums
839502f677872b9a8b74ba1dfa9b76e09e3619a2b86380df76eb2ce64a490fac
BLAKE2b-256 checksum
How to use checksums
22ea0bdbebe952eaf82574c79b295b58826d20e5b9ccd30748a6bd8d7c24d300
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / boilerplates-1.3.0-py3-none-any.whl

Download URL boilerplates-1.3.0-py3-none-any.whl
Size 37.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
91fd0d8a67530643b4b0589c5e2d0d820201e0dce5b91bfd8612fda0f379a752
BLAKE2b-256 checksum
How to use checksums
d3e7fc26ddacf3813454ae517a41b24482080163f097858760bdddf668522ce7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for boilerplates 1.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for boilerplates-1.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.3.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page