pyTooling.Packaging

A set of helper functions to describe a Python package for setuptools.

Hint

See high-level help for explanations and usage examples.

Variables

• STATUS

• DEFAULT_LICENSE

• DEFAULT_PY_VERSIONS

• DEFAULT_CLASSIFIERS

• DEFAULT_README

• DEFAULT_REQUIREMENTS

• DEFAULT_DOCUMENTATION_REQUIREMENTS

• DEFAULT_TEST_REQUIREMENTS

• DEFAULT_PACKAGING_REQUIREMENTS

• DEFAULT_VERSION_FILE

Functions

• loadReadmeFile(): Read the README file (e.g. in Markdown format), so it can be used as long description for the package.

• loadRequirementsFile(): Reads a requirements.txt file (recursively) and extracts all specified dependencies into an array.

• extractVersionInformation(): Extract double underscored variables from a Python source file, so these can be used for single-sourcing information.

• DescribePythonPackage(): Helper function to describe a Python package.

• DescribePythonPackageHostedOnGitHub(): Helper function to describe a Python package when the source code is hosted on GitHub.

Classes

• Readme: Encapsulates the READMEs file content and MIME type.

• VersionInformation: Encapsulates version information extracted from a Python source file.

---

Variables

pyTooling.Packaging.STATUS

A dictionary of supported development status values.

The mapping’s value will be appended to ``Development Status :: `` to form a package classifier.

1. Planning

2. Pre-Alpha

3. Alpha

4. Beta

5. Production/Stable

6. Mature

7. Inactive

See also

Python package classifiers

{'alpha': '3 - Alpha',
 'beta': '4 - Beta',
 'inactive': '7 - Inactive',
 'mature': '6 - Mature',
 'planning': '1 - Planning',
 'pre-alpha': '2 - Pre-Alpha',
 'stable': '5 - Production/Stable'}

pyTooling.Packaging.DEFAULT_LICENSE

Default license (Apache License, 2.0) used by DescribePythonPackage() and DescribePythonPackageHostedOnGitHub() if parameter license is not assigned.

Apache-2.0

pyTooling.Packaging.DEFAULT_PY_VERSIONS

A tuple of supported CPython versions used by DescribePythonPackage() and DescribePythonPackageHostedOnGitHub() if parameter pythonVersions is not assigned.

See also

Status of Python versions

('3.9', '3.10', '3.11', '3.12', '3.13')

pyTooling.Packaging.DEFAULT_CLASSIFIERS

A list of Python package classifiers used by DescribePythonPackage() and DescribePythonPackageHostedOnGitHub() if parameter classifiers is not assigned.

See also

Python package classifiers

('Operating System :: OS Independent',
 'Intended Audience :: Developers',
 'Topic :: Utilities')

pyTooling.Packaging.DEFAULT_README

Path to the README file used by DescribePythonPackage() and DescribePythonPackageHostedOnGitHub() if parameter readmeFile is not assigned.

PosixPath('README.md')

pyTooling.Packaging.DEFAULT_REQUIREMENTS

Path to the requirements file used by DescribePythonPackage() and DescribePythonPackageHostedOnGitHub() if parameter requirementsFile is not assigned.

PosixPath('requirements.txt')

pyTooling.Packaging.DEFAULT_DOCUMENTATION_REQUIREMENTS

Path to the README requirements file used by DescribePythonPackage() and DescribePythonPackageHostedOnGitHub() if parameter documentationRequirementsFile is not assigned.

PosixPath('doc/requirements.txt')

pyTooling.Packaging.DEFAULT_TEST_REQUIREMENTS

Path to the README requirements file used by DescribePythonPackage() and DescribePythonPackageHostedOnGitHub() if parameter unittestRequirementsFile is not assigned.

PosixPath('tests/requirements.txt')

pyTooling.Packaging.DEFAULT_PACKAGING_REQUIREMENTS

Path to the package requirements file used by DescribePythonPackage() and DescribePythonPackageHostedOnGitHub() if parameter packagingRequirementsFile is not assigned.

PosixPath('build/requirements.txt')

pyTooling.Packaging.DEFAULT_VERSION_FILE

Path subclass for non-Windows systems.

On a POSIX system, instantiating a Path should return this object.

PosixPath('__init__.py')

---

Functions

pyTooling.Packaging.loadReadmeFile(readmeFile)

Read the README file (e.g. in Markdown format), so it can be used as long description for the package.

Supported formats:

• Plain text (*.txt)

• Markdown (*.md)

• ReStructured Text (*.rst)

Parameters:

readmeFile (Path) – Path to the README file as an instance of Path.

Return type:

Readme

Returns:

A tuple containing the file content and the MIME type.

Raises:

• TypeError – If parameter ‘readmeFile’ is not of type ‘Path’.

• ValueError – If README file has an unsupported format.

• FileNotFoundError – If README file does not exist.

pyTooling.Packaging.loadRequirementsFile(requirementsFile, indent=0, debug=False)

Reads a requirements.txt file (recursively) and extracts all specified dependencies into an array.

Special dependency entries like Git repository references are translates to match the syntax expected by setuptools.

Hint

Duplicates should be removed by converting the result to a set and back to a list.

requirements = list(set(loadRequirementsFile(requirementsFile)))

Parameters:

• requirementsFile (Path) – Path to the requirements.txt file as an instance of Path.

• debug (bool) – If True, print found dependencies and recursion.

• indent (int)

Return type:

List[str]

Returns:

A list of dependencies.

Raises:

• TypeError – If parameter ‘requirementsFile’ is not of type ‘Path’.

• FileNotFoundError – If requirements file does not exist.

pyTooling.Packaging.extractVersionInformation(sourceFile)

Extract double underscored variables from a Python source file, so these can be used for single-sourcing information.

Supported variables:

• __author__

• __copyright__

• __email__

• __keywords__

• __license__

• __version__

Parameters:

sourceFile (Path) – Path to a Python source file as an instance of Path.

Return type:

VersionInformation

Returns:

An instance of VersionInformation with gathered variable contents.

Raises:

TypeError – If parameter ‘sourceFile’ is not of type Path.

pyTooling.Packaging.DescribePythonPackage(packageName, description, projectURL, sourceCodeURL, documentationURL, issueTrackerCodeURL, keywords=None, license=Apache - 2.0, readmeFile=PosixPath('README.md'), requirementsFile=PosixPath('requirements.txt'), documentationRequirementsFile=PosixPath('doc/requirements.txt'), unittestRequirementsFile=PosixPath('tests/requirements.txt'), packagingRequirementsFile=PosixPath('build/requirements.txt'), additionalRequirements=None, sourceFileWithVersion=PosixPath('__init__.py'), classifiers=('Operating System :: OS Independent', 'Intended Audience :: Developers', 'Topic :: Utilities'), developmentStatus='stable', pythonVersions=('3.9', '3.10', '3.11', '3.12', '3.13'), consoleScripts=None, dataFiles=None, debug=False)

Helper function to describe a Python package.

Hint

Some information will be gathered automatically from well-known files.

Examples: README.md, requirements.txt, __init__.py

Handling of namespace packages

If parameter packageName contains a dot, a namespace package is assumed. Then setuptools.find_namespace_packages() is used to discover package files.
Otherwise, the package is considered a normal package and setuptools.find_packages() is used.

In both cases, the following packages (directories) are excluded from search:

• build, build.*

• dist, dist.*

• doc, doc.*

• tests, tests.*

Handling of minimal Python version

The minimal required Python version is selected from parameter pythonVersions.

Handling of dunder variables

A Python source file specified by parameter sourceFileWithVersion will be analyzed with Pythons parser and the resulting AST will be searched for the following dunder variables:

• __author__: str

• __copyright__: str

• __email__: str

• __keywords__: typing.Iterable`[:class:`str]

• __license__: str

• __version__: str

The gathered information be used to add further mappings in the result dictionary.

Handling of package classifiers

To reduce redundantly provided parameters to this function (e.g. supported pythonVersions), only additional classifiers should be provided via parameter classifiers. The supported Python versions will be implicitly converted to package classifiers, so no need to specify them in parameter classifiers.

The following classifiers are implicitly handled:

license

The license specified by parameter license is translated into a classifier.
See also pyTooling.Licensing.License.PythonClassifier()

Python versions

Always add Programming Language :: Python :: 3 :: Only.
For each value in pythonVersions, one Programming Language :: Python :: Major.Minor is added.

Development status

The development status specified by parameter developmentStatus is translated to a classifier and added.

Handling of extra requirements

If additional requirement files are provided, e.g. requirements to build the documentation, then extra requirements are defined. These can be installed via pip install packageName[extraName]. If so, an extra called all is added, so developers can install all dependencies needed for package development.

doc

If parameter documentationRequirementsFile is present, an extra requirements called doc will be defined.

test

If parameter unittestRequirementsFile is present, an extra requirements called test will be defined.

build

If parameter packagingRequirementsFile is present, an extra requirements called build will be defined.

User-defined

If parameter additionalRequirements is present, an extra requirements for every mapping entry in the dictionary will be added.

all

If any of the above was added, an additional extra requirement called all will be added, summarizing all extra requirements.

Handling of keywords

If parameter keywords is not specified, the dunder variable __keywords__ from sourceFileWithVersion will be used. Otherwise, the content of the parameter, if not None or empty.

Parameters:

• packageName (str) – Name of the Python package.

• description (str) – Short description of the package. The long description will be read from README file.

• projectURL (str) – URL to the Python project.

• sourceCodeURL (str) – URL to the Python source code.

• documentationURL (str) – URL to the package’s documentation.

• issueTrackerCodeURL (str) – URL to the projects issue tracker (ticket system).

• keywords (Iterable[str]) – A list of keywords.

• license (License) – The package’s license. (Default: Apache License, 2.0, see DEFAULT_LICENSE)

• readmeFile (Path) – The path to the README file. (Default: README.md, see DEFAULT_README)

• requirementsFile (Path) – The path to the project’s requirements file. (Default: requirements.txt, see DEFAULT_REQUIREMENTS)

• documentationRequirementsFile (Path) – The path to the project’s requirements file for documentation. (Default: doc/requirements.txt, see DEFAULT_DOCUMENTATION_REQUIREMENTS)

• unittestRequirementsFile (Path) – The path to the project’s requirements file for unit tests. (Default: tests/requirements.txt, see DEFAULT_TEST_REQUIREMENTS)

• packagingRequirementsFile (Path) – The path to the project’s requirements file for packaging. (Default: build/requirements.txt, see DEFAULT_PACKAGING_REQUIREMENTS)

• additionalRequirements (Dict[str, List[str]]) – A dictionary of a lists with additional requirements. (default: None)

• sourceFileWithVersion (Optional[Path]) – The path to the project’s source file containing dunder variables like __version__. (Default: __init__.py, see DEFAULT_VERSION_FILE)

• classifiers (Iterable[str]) – A list of package classifiers. (Default: 3 classifiers, see DEFAULT_CLASSIFIERS)

• developmentStatus (str) – Development status of the package. (Default: stable, see STATUS for supported status values)

• pythonVersions (Sequence[str]) – A list of supported Python 3 version. (Default: all currently maintained CPython versions, see DEFAULT_PY_VERSIONS)

• consoleScripts (Dict[str, str]) – A dictionary mapping command line names to entry points. (Default: None)

• dataFiles (Dict[str, List[str]]) – A dictionary mapping package names to lists of additional data files.

• debug (bool) – Enable extended outputs for debugging.

Return type:

Dict[str, Any]

Returns:

A dictionary suitable for setuptools.setup().

Raises:

• ToolingException – If package ‘setuptools’ is not available.

• TypeError – If parameter ‘readmeFile’ is not of type Path.

• FileNotFoundError – If README file doesn’t exist.

• TypeError – If parameter ‘requirementsFile’ is not of type Path.

• FileNotFoundError – If requirements file doesn’t exist.

• TypeError – If parameter ‘documentationRequirementsFile’ is not of type Path.

• TypeError – If parameter ‘unittestRequirementsFile’ is not of type Path.

• TypeError – If parameter ‘packagingRequirementsFile’ is not of type Path.

• TypeError – If parameter ‘sourceFileWithVersion’ is not of type Path.

• FileNotFoundError – If package file with dunder variables doesn’t exist.

• TypeError – If parameter ‘license’ is not of type License.

• ValueError – If developmentStatus uses an unsupported value. (See STATUS)

• ValueError – If the content type of the README file is not supported. (See loadReadmeFile())

• FileNotFoundError – If the README file doesn’t exist. (See loadReadmeFile())

• FileNotFoundError – If the requirements file doesn’t exist. (See loadRequirementsFile())

pyTooling.Packaging.DescribePythonPackageHostedOnGitHub(packageName, description, gitHubNamespace, gitHubRepository=None, projectURL=None, keywords=None, license=Apache - 2.0, readmeFile=PosixPath('README.md'), requirementsFile=PosixPath('requirements.txt'), documentationRequirementsFile=PosixPath('doc/requirements.txt'), unittestRequirementsFile=PosixPath('tests/requirements.txt'), packagingRequirementsFile=PosixPath('build/requirements.txt'), additionalRequirements=None, sourceFileWithVersion=PosixPath('__init__.py'), classifiers=('Operating System :: OS Independent', 'Intended Audience :: Developers', 'Topic :: Utilities'), developmentStatus='stable', pythonVersions=('3.9', '3.10', '3.11', '3.12', '3.13'), consoleScripts=None, dataFiles=None, debug=False)

Helper function to describe a Python package when the source code is hosted on GitHub.

This is a wrapper for DescribePythonPackage(), because some parameters can be simplified by knowing the GitHub namespace and repository name: issue tracker URL, source code URL, …

Parameters:

• packageName (str) – Name of the Python package.

• description (str) – Short description of the package. The long description will be read from README file.

• gitHubNamespace (str) – Name of the GitHub namespace (organization or user).

• gitHubRepository (str) – Name of the GitHub repository.

• projectURL (str) – URL to the Python project.

• keywords (Iterable[str]) – A list of keywords.

• license (License) – The package’s license. (Default: Apache License, 2.0, see DEFAULT_LICENSE)

• readmeFile (Path) – The path to the README file. (Default: README.md, see DEFAULT_README)

• requirementsFile (Path) – The path to the project’s requirements file. (Default: requirements.txt, see DEFAULT_REQUIREMENTS)

• documentationRequirementsFile (Path) – The path to the project’s requirements file for documentation. (Default: doc/requirements.txt, see DEFAULT_DOCUMENTATION_REQUIREMENTS)

• unittestRequirementsFile (Path) – The path to the project’s requirements file for unit tests. (Default: tests/requirements.txt, see DEFAULT_TEST_REQUIREMENTS)

• packagingRequirementsFile (Path) – The path to the project’s requirements file for packaging. (Default: build/requirements.txt, see DEFAULT_PACKAGING_REQUIREMENTS)

• additionalRequirements (Dict[str, List[str]]) – A dictionary of a lists with additional requirements. (default: None)

• sourceFileWithVersion (Path) – The path to the project’s source file containing dunder variables like __version__. (Default: __init__.py, see DEFAULT_VERSION_FILE)

• classifiers (Iterable[str]) – A list of package classifiers. (Default: 3 classifiers, see DEFAULT_CLASSIFIERS)

• developmentStatus (str) – Development status of the package. (Default: stable, see STATUS for supported status values)

• pythonVersions (Sequence[str]) – A list of supported Python 3 version. (Default: all currently maintained CPython versions, see DEFAULT_PY_VERSIONS)

• consoleScripts (Dict[str, str]) – A dictionary mapping command line names to entry points. (Default: None)

• dataFiles (Dict[str, List[str]]) – A dictionary mapping package names to lists of additional data files.

• debug (bool) – Enable extended outputs for debugging.

Return type:

Dict[str, Any]

Returns:

A dictionary suitable for setuptools.setup().

Raises:

• ToolingException – If package ‘setuptools’ is not available.

• TypeError – If parameter ‘readmeFile’ is not of type Path.

• FileNotFoundError – If README file doesn’t exist.

• TypeError – If parameter ‘requirementsFile’ is not of type Path.

• FileNotFoundError – If requirements file doesn’t exist.

• TypeError – If parameter ‘documentationRequirementsFile’ is not of type Path.

• TypeError – If parameter ‘unittestRequirementsFile’ is not of type Path.

• TypeError – If parameter ‘packagingRequirementsFile’ is not of type Path.

• TypeError – If parameter ‘sourceFileWithVersion’ is not of type Path.

• FileNotFoundError – If package file with dunder variables doesn’t exist.

• TypeError – If parameter ‘license’ is not of type License.

• ValueError – If developmentStatus uses an unsupported value. (See STATUS)

• ValueError – If the content type of the README file is not supported. (See loadReadmeFile())

• FileNotFoundError – If the README file doesn’t exist. (See loadReadmeFile())

• FileNotFoundError – If the requirements file doesn’t exist. (See loadRequirementsFile())

---

Classes

class pyTooling.Packaging.Readme

Encapsulates the READMEs file content and MIME type.

Inheritance

__init__(content, mimeType)

Initializes a README file wrapper.

Parameters:

• content (str) – Raw content of the README file.

• mimeType (str) – MIME type of the README file.

Return type:

None

_content: str

Content of the README file

_mimeType: str

MIME type of the README content

property Content: str

Read-only property to access the README’s content.

Returns:

Raw content of the README file.

property MimeType: str

Read-only property to access the README’s MIME type.

Returns:

The MIME type of the README file.

class pyTooling.Packaging.VersionInformation

Encapsulates version information extracted from a Python source file.

Inheritance

__init__(author, email, copyright, license, version, description, keywords)

Initializes a Python package (version) information instance.

Parameters:

• author (str) – Author of the Python package.

• email (str) – The author’s email address

• copyright (str) – The copyright notice of the Package.

• license (str) – The Python package’s license.

• version (str) – The Python package’s version.

• description (str) – The Python package’s short description.

• keywords (Iterable[str]) – The Python package’s list of keywords.

Return type:

None

_author: str

Author name(s).

_email: str

Author’s email address.

_copyright: str

Copyright information.

_license: str

License name.

_version: str

Version number.

_description: str

Description of the package.

_keywords: List[str]

Keywords.

property Author: str

Name(s) of the package author(s).

property Copyright: str

Copyright information.

property Description: str

Package description text.

property Email: str

Email address of the author.

property Keywords: List[str]

List of keywords.

property License: str

License name.

property Version: str

Version number.