Package: boilerplates
Various boilerplates used in almost all of my Python packages.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.ContentsRequirementsAvailable boilerplatesSetup boilerplatePackaging testsConfig boilerplateLogging boilerplateCLI boilerplateGit repo tests boilerplateRequirementsPython version 3.8 or later.Python libraries as specified inrequirements.txt.Building and running tests additionally requires packages listed inrequirements_test.txt.Tested on Linux, macOS and Windows.Available boilerplatesSetup boilerplateModuleboilerplates.setupprovides a classPackagethat abstracts out
many of the common tasks needed to set up the package. The class has asetup()class method that can be called from theif __name__ == '__main__'block
in yoursetup.pyfile.To avoid setup script boilerplate, createsetup.pyfile with the minimal contents as given
below and modify it according to the specifics of your package.See the implementation ofboilerplates.setup.Packagefor 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.
SeeDEFAULT_*constants in theboilerplates.setupfor those values.Examplesetup.py:"""Setup script."""importboilerplates.setupclassPackage(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 yourpyproject.tomlfile:[build-system]requires=['boilerplates[setup] ~= <version>']Packaging testsAs an extension of setup boilerplate, there’s an extra boilerplate for testing the packaging process,
in a way that enables 100% code coverage, including thesetup.pyscript.In order to use it, all you need to do is create a file as follows in your tests directory.Exampletest/test_packaging.py:"""Tests for packaging."""importboilerplates.packaging_testsclassTests(boilerplates.packaging_tests.PackagingTests):passAnd, you will need to add the following to yourrequirements_test.txtfile (or equivalent):boilerplates[packaging_tests] ~= <version>Config boilerplateModuleboilerplates.configprovides few utility functions useful to handle local configuration.Example usage:importboilerplates.config...boilerplates.config.initialize_config_directory('app_name')And, you will need to add the following to yourrequirements.txtfile (or equivalent):boilerplates[config] ~= <version>Logging boilerplateAssumptions 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."""importboilerplates.loggingclassLogging(boilerplates.logging.Logging):"""Logging configuration."""packages=['package_name']...if__name__=='__main__':Logging.configure()...More advanced usage could be (just changing theLoggingclass definition):classLogging(boilerplates.logging.Logging):"""Logging configuration."""packages=['package_name']level_package=logging.INFOenable_file=Truedirectory='package_name'You can and should adjust the class fields to your needs, please take a look
at theboilerplates.logging.Loggingclass 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 yourtest/__init__.py:"""Initialization of tests."""importloggingimportboilerplates.loggingclassTestsLogging(boilerplates.logging.Logging):"""Logging configuration for tests."""packages=['package_name']level_package=logging.INFOTestsLogging.configure()If you wish, you can make your test logging config be a variant of your application logging config,
like so:"""Initialization of tests."""frommy_package.__main__importLoggingclassTestsLogging(Logging):"""Logging configuration for tests."""enable_file=FalseAs 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__).stemif__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 yourrequirements.txtfile (or equivalent):boilerplates[logging] ~= <version>CLI boilerplateThis boilerplate aims at making CLIs easier to write, by providing a few utility functions.Your examplecli.pyfile which defines your command-line interface may look like:"""Command-line interface definition."""importargparseimportboilerplates.clidefmain(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 theexamples.ipynbnotebook.
Please see theboilerplates.climodule for details of the available features.And then, an example__main__.pyfile may look like:"""Entry point of the command-line interface."""# PYTHON_ARGCOMPLETE_OKfrommy_packageimportcliif__name__=='__main__':cli.main()And, you will need to add the following to yourrequirements.txtfile (or equivalent):boilerplates[cli] ~= <version>Then, the output of runningpython-mmy_pacakge-hwill 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 runningpython-mmy_pacakge--versionwill 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 boilerplateThis 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 usingboilerplates.git_repo_tests, you can start with a file like this
in your test folder, for exampletest/test_with_git_repo.py:"""Perform tests on and in synthetic git repositories."""importpathlibimportboilerplates.git_repo_testsclassTests(boilerplates.git_repo_tests.GitRepoTests):...However, you will need to check theboilerplates.git_repo_tests.GitRepoTestsclass
for details of available features.And, you will need to add the following to yourrequirements_test.txtfile (or equivalent):boilerplates[git_repo_tests] ~= <version>