boilerplates 0.3.0

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.8',
        'Programming Language :: Python :: 3.9',
        'Programming Language :: Python :: 3.10',
        'Programming Language :: Python :: 3.11',
        '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>']

"""Tests for packaging."""

import boilerplates.packaging_tests

class Tests(boilerplates.packaging_tests.PackagingTests):
    pass

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(logging_boilerplate.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_package = 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_package = logging.DEBUG


TestsLogging.configure_basic()

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."""

    enable_file = False

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>