Packaging

Summary

Package:

pyTooling

Doc-string:

documented

File	Expected	Covered	Uncovered	Coverage
__init__.py	56	54	2	96.4%
Overall (1 files)	56	54	2	96.4%

Source

pyTooling/Packaging/__init__.pydocumentedundocumentedignoredexcludednot counted

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

.. hint::

   See :ref:`high-level help <PACKAGING>` for explanations and usage examples.

.. seealso::

   :mod:`pyTooling.Versioning`
      |rarr| The version numbers read from a package's dunder variables.
   :mod:`pyTooling.Licensing`
      |rarr| The license names translated for setuptools.
   :mod:`pyTooling.Testing`
      |rarr| Testing the console scripts a package installs.
"""
...

__all__ = [
	"STATUS", "DEFAULT_LICENSE", "DEFAULT_PY_VERSIONS", "DEFAULT_CLASSIFIERS", "DEFAULT_README", "DEFAULT_REQUIREMENTS",
	"DEFAULT_DOCUMENTATION_REQUIREMENTS", "DEFAULT_TEST_REQUIREMENTS", "DEFAULT_PACKAGING_REQUIREMENTS",
	"DEFAULT_VERSION_FILE"
]

@export
class PackagingError(ToolingException):
	"""Base-exception of all exceptions raised by :mod:`pyTooling.Packaging`."""

@export
class DirectReferenceWarning(CriticalWarning):
	"""
	A requirement of an extra names its distribution by a URL, a direct reference (``name @ URL``).

	The Python Package Index rejects a package whose metadata contains a direct reference, therefore
	:func:`DescribePythonPackage` leaves such a requirement out of the extra.

	.. important::

	   As a critical warning, it must be collected by a :class:`~pyTooling.Warning.WarningCollector` up the
	   call-hierarchy, otherwise :exc:`~pyTooling.Warning.UnhandledCriticalWarningError` is raised.
	"""

	_requirement: str             #: The requirement left out, as stated.
	_extra:       str             #: The extra the requirement was left out of.
	_filePath:    Nullable[Path]  #: The requirements file stating it; ``None`` for parameter 'additionalRequirements'.

	def __init__(
		self,
		message: str,
		/, *,
		requirement: str,
		extra: str,
		filePath: Nullable[Path]
	) -> None:
		"""
		Initializes the warning with the requirement left out, its extra and where it was stated.

		:param message:     The warning's message.
		:param requirement: The requirement left out, as stated.
		:param extra:       The extra the requirement was left out of.
		:param filePath:    The requirements file stating it; ``None`` for parameter 'additionalRequirements'.
		"""
		...

	@readonly
	def Requirement(self) -> str:
		"""
		Read-only property to access the requirement left out, as stated (:attr:`_requirement`).

		:returns: The requirement.
		"""
		...

	@readonly
	def Extra(self) -> str:
		"""
		Read-only property to access the extra the requirement was left out of (:attr:`_extra`).

		:returns: The extra's name.
		"""
		...

	@readonly
	def FilePath(self) -> Nullable[Path]:
		"""
		Read-only property to access the requirements file stating the requirement (:attr:`_filePath`).

		:returns: The file's path, or ``None`` for a requirement from parameter 'additionalRequirements'.
		"""
		...

@export
class Readme:
	"""Encapsulates the READMEs file content and MIME type."""

	_content:  str   #: Content of the README file
	_mimeType: str   #: MIME type of the README content

	def __init__(self, content: str, mimeType: str) -> None:
		"""
		Initializes a README file wrapper.

		:param content:  Raw content of the README file.
		:param mimeType: MIME type of the README file.
		"""
		...

	@readonly
	def Content(self) -> str:
		"""
		Read-only property to access the README's content.

		:returns: Raw content of the README file.
		"""
		...

	@readonly
	def MimeType(self) -> str:
		"""
		Read-only property to access the README's MIME type.

		:returns: The MIME type of the README file.
		"""
		...

@export
def loadReadmeFile(readmeFile: Path) -> Readme:
	"""
	Read the README file, so it can be used as long description for the package.

	Supported formats:

	  * Plain text (``*.txt``)
	  * Markdown (``*.md``)
	  * ReStructured Text (``*.rst``)

	:param readmeFile:         Path to the `README` file as an instance of :class:`Path`.
	:returns:                  A tuple containing the file content and the MIME type.
	:raises TypeError:         If parameter 'readmeFile' is not of type :class:`~pathlib.Path`.
	:raises ValueError:        If README file has an unsupported format.
	:raises FileNotFoundError: If README file does not exist.
	"""
	...

@export
def loadRequirementsFile(requirementsFile: Path, indent: int = 0, debug: bool = False) -> list[str]:
	"""
	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 :class:`set` and back to a :class:`list`.

	   .. code-block:: Python

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

	:param requirementsFile:   Path to the ``requirements.txt`` file as an instance of :class:`Path`.
	:param indent:             Optional, indentation level used for the debug output of nested requirements files.
	:param debug:              Optional, if ``True``, print found dependencies and recursion.
	:returns:                  A list of dependencies.
	:raises TypeError:         If parameter 'requirementsFile' is not of type :class:`~pathlib.Path`.
	:raises FileNotFoundError: If requirements file does not exist.
	"""
	...

	def _loadRequirementsFile(requirementsFile: Path, indent: int) -> list[str]:
		"""
		Recursive variant of :func:`loadRequirementsFile`.

		:param requirementsFile:   Path to the requirements file to read.
		:param indent:             Indentation level used for the debug output of nested requirements files.
		:returns:                  List of requirements read from that file and every file it includes.
		:raises FileNotFoundError: If the requirements file doesn't exist.
		"""
		...

	...

@export
class VersionInformation(metaclass=ExtendedType, slots=True):
	"""Encapsulates version information extracted from a Python source file."""

	_author: str          #: Author name(s).
	_copyright: str       #: Copyright information.
	_email: str           #: Author's email address.
	_keywords: list[str]  #: Keywords.
	_license: str         #: License name.
	_description: str     #: Description of the package.
	_version: str         #: Version number.

	def __init__(
		self,
		author: str,
		email: str,
		copyright: str,
		license: str,
		version: str,
		description: str,
		keywords: Iterable[str]
	) -> None:
		"""
		Initializes a Python package (version) information instance.

		:param author:      Author of the Python package.
		:param email:       The author's email address
		:param copyright:   The copyright notice of the Package.
		:param license:     The Python package's license.
		:param version:     The Python package's version.
		:param description: The Python package's short description.
		:param keywords:    The Python package's list of keywords.
		"""
		...

	@readonly
	def Author(self) -> str:
		"""
		Read-only property to access the name(s) of the package author(s) (:attr:`_author`).

		:returns: Name(s) of the package author(s).
		"""
		...

	@readonly
	def Copyright(self) -> str:
		"""
		Read-only property to access the package's copyright information (:attr:`_copyright`).

		:returns: Copyright information.
		"""
		...

	@readonly
	def Description(self) -> str:
		"""
		Read-only property to access the package description (:attr:`_description`).

		:returns: Package description text.
		"""
		...

	@readonly
	def Email(self) -> str:
		"""
		Read-only property to access the author's email address (:attr:`_email`).

		:returns: Email address of the author.
		"""
		...

	@readonly
	def Keywords(self) -> list[str]:
		"""
		Read-only property to access the package's keywords (:attr:`_keywords`).

		:returns: List of keywords.
		"""
		...

	@readonly
	def License(self) -> str:
		"""
		Read-only property to access the package's license (:attr:`_license`).

		:returns: License name.
		"""
		...

	@readonly
	def Version(self) -> str:
		"""
		Read-only property to access the package's version number (:attr:`_version`).

		:returns: Version number.
		"""
		...

	def __str__(self) -> str:
		"""
		Return a string representation of this version information.

		:returns: The version number.
		"""
		...

def _extractDescription(docString: Nullable[str]) -> str:
	"""
	Read a package's short description from the first paragraph of its module doc-string.

	A package's short description **is** the summary of its module doc-string - the first paragraph - so the two are
	one text in two places, and :func:`~pyTooling.Documentation.splitDocString` reads it.

	It is folded into a single line, because a short description is one line of plain text while a doc-string is
	wrapped to the source file's line length. Strong emphasis around the whole paragraph is removed for the same
	reason: ``**An abstract VHDL language model.**`` is markup for the rendered documentation, and nothing renders it
	where a short description is displayed.

	:param docString:           The module's doc-string, or ``None`` if it has none.
	:returns:                   The description as a single line, or an empty string if there is no doc-string.
	:raises DocumentationError: If the first paragraph is too long to be a description.

	.. seealso::

	   :func:`~pyTooling.Documentation.splitDocString`
	      |rarr| Reads the first paragraph, and rejects one that is too long to be a summary.
	"""
	...

@export
def extractVersionInformation(sourceFile: Path) -> VersionInformation:
	"""
	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__``

	The package's short description is not a dunder variable - it is the first paragraph of the source file's module
	doc-string, which is where a package already describes itself.

	:param sourceFile:        Path to a Python source file as an instance of :class:`Path`.
	:returns:                 An instance of :class:`VersionInformation` with gathered variable contents.
	:raises TypeError:        If parameter 'sourceFile' is not of type :class:`~pathlib.Path`.
	:raises PackagingError:   If the given file doesn't exist.
	:raises PackagingError:   If the given file can't be parsed as Python source code.
	:raises PackagingError:   If a dunder variable has an unexpected format.
	:raises AssertionError:   If a dunder variable is missing in the given file.
	"""
	...

STATUS: dict[str, str] = {
	"planning":  "1 - Planning",
	"pre-alpha": "2 - Pre-Alpha",
	"alpha":     "3 - Alpha",
	"beta":      "4 - Beta",
	"stable":    "5 - Production/Stable",
	"mature":    "6 - Mature",
	"inactive":  "7 - Inactive"
}
"""
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

.. seealso::

   `Python package classifiers <https://pypi.org/classifiers/>`__
"""

DEFAULT_LICENSE = Apache_2_0_License
"""
Default license (Apache License, 2.0) used by :func:`DescribePythonPackage` and :func:`DescribePythonPackageHostedOnGitHub`
if parameter ``license`` is not assigned.
"""

DEFAULT_PY_VERSIONS = ("3.11", "3.12", "3.13", "3.14", "3.15")
"""
A tuple of supported CPython versions used by :func:`DescribePythonPackage` and :func:`DescribePythonPackageHostedOnGitHub`
if parameter ``pythonVersions`` is not assigned.

.. seealso::

   `Status of Python versions <https://devguide.python.org/versions/>`__
"""

DEFAULT_CLASSIFIERS = (
		"Operating System :: OS Independent",
		"Intended Audience :: Developers",
		"Topic :: Utilities"
	)
"""
A list of Python package classifiers used by :func:`DescribePythonPackage` and :func:`DescribePythonPackageHostedOnGitHub`
if parameter ``classifiers`` is not assigned.

.. seealso::

   `Python package classifiers <https://pypi.org/classifiers/>`__
"""

DEFAULT_README = Path("README.md")
"""
Path to the README file used by :func:`DescribePythonPackage` and :func:`DescribePythonPackageHostedOnGitHub`
if parameter ``readmeFile`` is not assigned.
"""

DEFAULT_REQUIREMENTS = Path("requirements.txt")
"""
Path to the requirements file used by :func:`DescribePythonPackage` and :func:`DescribePythonPackageHostedOnGitHub`
if parameter ``requirementsFile`` is not assigned.
"""

DEFAULT_DOCUMENTATION_REQUIREMENTS = Path("doc/requirements.txt")
"""
Path to the README requirements file used by :func:`DescribePythonPackage` and :func:`DescribePythonPackageHostedOnGitHub`
if parameter ``documentationRequirementsFile`` is not assigned.
"""

DEFAULT_TEST_REQUIREMENTS = Path("tests/requirements.txt")
"""
Path to the README requirements file used by :func:`DescribePythonPackage` and :func:`DescribePythonPackageHostedOnGitHub`
if parameter ``unittestRequirementsFile`` is not assigned.
"""

DEFAULT_PACKAGING_REQUIREMENTS = Path("build/requirements.txt")
"""
Path to the package requirements file used by :func:`DescribePythonPackage` and :func:`DescribePythonPackageHostedOnGitHub`
if parameter ``packagingRequirementsFile`` is not assigned.
"""

DEFAULT_VERSION_FILE = Path("__init__.py")

_DIRECT_REFERENCE_PATTERN = re_compile(r"^\s*[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?\s*(?:\[[^\]]*\])?\s*@")

def _removeDirectReferences(requirements: Iterable[str], extra: str, filePath: Nullable[Path]) -> list[str]:
	"""
	Remove direct references (``name @ URL``) from the requirements of an extra.

	The Python Package Index rejects a package whose metadata contains a direct reference. Each removed requirement is
	reported as a :exc:`DirectReferenceWarning` to a :class:`~pyTooling.Warning.WarningCollector`.

	:param requirements:                   Requirements of the extra.
	:param extra:                          Name of the extra.
	:param filePath:                       The requirements file the requirements were read from, or ``None`` for
	                                       parameter 'additionalRequirements'.
	:returns:                              The requirements, which aren't direct references.
	:raises UnhandledCriticalWarningError: If a requirement is a direct reference and no
	                                       :class:`~pyTooling.Warning.WarningCollector` collects the warning.
	"""
	...

def _collectEntryPoints(
	consoleScripts: Nullable[dict[str, str]],
	guiScripts: Nullable[dict[str, str]],
	pytestPlugins: Nullable[dict[str, str]]
) -> Nullable[dict[str, list[str]]]:
	"""
	Collect what a package advertises into setuptools' entry point groups.

	Each parameter names one kind of thing a package can offer, so a caller says *what* it provides and this
	function knows *how* it is declared - which group it belongs to, and setuptools' ``"name = entry.point"``
	spelling.

	:param consoleScripts: Command line programs, declared as ``console_scripts``.
	:param guiScripts:     Windowed programs, declared as ``gui_scripts``.
	:param pytestPlugins:  Pytest plugins, declared as ``pytest11``.
	:returns:              A dictionary mapping a group to its entry point lines, or ``None`` if a package
	                       advertises nothing.
	"""
	...

@export
def DescribePythonPackage(
	packageName: str,
	projectURL: str,
	sourceCodeURL: str,
	documentationURL: str,
	issueTrackerCodeURL: str,
	description: Nullable[str] = None,
	keywords: Nullable[Iterable[str]] = None,
	license: License = DEFAULT_LICENSE,
	readmeFile: Path = DEFAULT_README,
	requirementsFile: Path = DEFAULT_REQUIREMENTS,
	documentationRequirementsFile: Path = DEFAULT_DOCUMENTATION_REQUIREMENTS,
	unittestRequirementsFile: Path = DEFAULT_TEST_REQUIREMENTS,
	packagingRequirementsFile: Path = DEFAULT_PACKAGING_REQUIREMENTS,
	additionalRequirements: Nullable[dict[str, list[str]]] = None,
	sourceFileWithVersion: Nullable[Path] = DEFAULT_VERSION_FILE,
	classifiers: Iterable[str] = DEFAULT_CLASSIFIERS,
	developmentStatus: str = "stable",
	pythonVersions: Sequence[str] = DEFAULT_PY_VERSIONS,
	consoleScripts: Nullable[dict[str, str]] = None,
	guiScripts: Nullable[dict[str, str]] = None,
	pytestPlugins: Nullable[dict[str, str]] = None,
	dataFiles: Nullable[dict[str, list[str]]] = None,
	debug: bool = False
) -> dict[str, Any]:
	"""
	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``

	.. topic:: Handling of namespace packages

	   If parameter ``packageName`` contains a dot, a namespace package is assumed. Then
	   :func:`setuptools.find_namespace_packages` is used to discover package files. |br|
	   Otherwise, the package is considered a normal package and :func:`setuptools.find_packages` is used.

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

	   * ``build``, ``build.*``
	   * ``dist``, ``dist.*``
	   * ``doc``, ``doc.*``
	   * ``tests``, ``tests.*``

	.. topic:: Handling of minimal Python version

	   The minimal required Python version is selected from parameter ``pythonVersions``.

	.. topic:: 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__``: :class:`str`
	   * ``__copyright__``: :class:`str`
	   * ``__email__``: :class:`str`
	   * ``__keywords__``: :class:`typing.Iterable`[:class:`str`]
	   * ``__license__``: :class:`str`
	   * ``__version__``: :class:`str`

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

	.. topic:: 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. |br|
	     See also :meth:`pyTooling.Licensing.License.PythonClassifier`

	   Python versions
	     Always add ``Programming Language :: Python :: 3 :: Only``. |br|
	     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.

	.. topic:: 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.

	   A requirement with a direct reference (``name @ URL``, e.g. ``pyTooling.Sphinx @ git+https://...@dev``) is left out
	   of every extra, because the Python Package Index rejects a package whose metadata contains one. Each one is
	   reported as a critical :exc:`DirectReferenceWarning` to a :class:`~pyTooling.Warning.WarningCollector`; without
	   a collector up the call-hierarchy, :exc:`~pyTooling.Warning.UnhandledCriticalWarningError` is raised. So a project
	   can name a dependency, which isn't on PyPI yet, by its repository in e.g. ``doc/requirements.txt`` - the
	   documentation build installs it - and still be released, if its :file:`setup.py` collects the warnings. The base
	   requirements (``requirementsFile``) are kept as they are: without one of them, the package wouldn't work.

	.. topic:: 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.

	.. topic:: Handling of the description

	   If parameter ``description`` is not specified, the first paragraph of the module doc-string in
	   ``sourceFileWithVersion`` is used, so a package describes itself in one place. An explicitly passed description
	   always wins - including an empty one.

	:param packageName:                    Name of the Python package.
	:param projectURL:                     URL to the Python project.
	:param sourceCodeURL:                  URL to the Python source code.
	:param documentationURL:               URL to the package's documentation.
	:param issueTrackerCodeURL:            URL to the projects issue tracker (ticket system).
	:param description:                    Optional, short description of the package. (Default: the first paragraph
	                                       of the module doc-string in ``sourceFileWithVersion``.) The long description
	                                       is read from the README file.
	:param keywords:                       Optional, a list of keywords.
	:param license:                        Optional, the package's license. (Default: ``Apache License, 2.0``, see
	                                       :const:`DEFAULT_LICENSE`)
	:param readmeFile:                     Optional, the path to the README file. (Default: ``README.md``, see
	                                       :const:`DEFAULT_README`)
	:param requirementsFile:               Optional, the path to the project's requirements file. (Default:
	                                       ``requirements.txt``, see :const:`DEFAULT_REQUIREMENTS`)
	:param documentationRequirementsFile:  Optional, the path to the project's requirements file for documentation.
	                                       (Default: ``doc/requirements.txt``, see
	                                       :const:`DEFAULT_DOCUMENTATION_REQUIREMENTS`)
	:param unittestRequirementsFile:       Optional, the path to the project's requirements file for unit tests. (Default:
	                                       ``tests/requirements.txt``, see :const:`DEFAULT_TEST_REQUIREMENTS`)
	:param packagingRequirementsFile:      Optional, the path to the project's requirements file for packaging. (Default:
	                                       ``build/requirements.txt``, see :const:`DEFAULT_PACKAGING_REQUIREMENTS`)
	:param additionalRequirements:         Optional, a dictionary of a lists with additional requirements. (default: None)
	:param sourceFileWithVersion:          Optional, the path to the project's source file containing dunder variables
	                                       like ``__version__``. (Default: ``__init__.py``, see
	                                       :const:`DEFAULT_VERSION_FILE`)
	:param classifiers:                    Optional, a list of package classifiers. (Default: 3 classifiers, see
	                                       :const:`DEFAULT_CLASSIFIERS`)
	:param developmentStatus:              Optional, development status of the package. (Default: stable, see
	                                       :const:`STATUS` for supported status values)
	:param pythonVersions:                 Optional, a list of supported Python 3 version. (Default: all currently
	                                       maintained CPython versions, see :const:`DEFAULT_PY_VERSIONS`)
	:param consoleScripts:                 Optional, a dictionary mapping command line names to entry points, declared
	                                       as ``console_scripts``. (Default: None)
	:param guiScripts:                     Optional, like ``consoleScripts``, but declared as ``gui_scripts`` - on
	                                       Windows such a program starts without a console window. (Default: None)
	:param pytestPlugins:                  Optional, a dictionary mapping plugin names to entry points, declared as
	                                       ``pytest11``. The classifier ``Framework :: Pytest`` is added with it.
	                                       (Default: None)
	:param dataFiles:                      Optional, a dictionary mapping package names to lists of additional data files.
	:param debug:                          Optional, if ``True``, enable extended outputs for debugging.
	:returns:                              A dictionary suitable for :func:`setuptools.setup`.
	:raises TypeError:                     If parameter 'license' is not of type :class:`~pyTooling.Licensing.License`.
	:raises TypeError:                     If parameter 'readmeFile' is not of type :class:`~pathlib.Path`.
	:raises TypeError:                     If parameter 'requirementsFile' is not of type :class:`~pathlib.Path`.
	:raises TypeError:                     If parameter 'documentationRequirementsFile' is not of type
	                                       :class:`~pathlib.Path`.
	:raises TypeError:                     If parameter 'unittestRequirementsFile' is not of type :class:`~pathlib.Path`.
	:raises TypeError:                     If parameter 'packagingRequirementsFile' is not of type :class:`~pathlib.Path`.
	:raises TypeError:                     If parameter 'sourceFileWithVersion' is not of type :class:`~pathlib.Path`.
	:raises MissingDependencyError:        If package 'setuptools' is not available.
	:raises FileNotFoundError:             If README file doesn't exist.
	:raises FileNotFoundError:             If requirements file doesn't exist.
	:raises FileNotFoundError:             If package file with dunder variables doesn't exist.
	:raises ValueError:                    If developmentStatus uses an unsupported value. (See :const:`STATUS`)
	:raises ValueError:                    If the content type of the README file is not supported. (See
	                                       :func:`loadReadmeFile`)
	:raises FileNotFoundError:             If the README file doesn't exist. (See :func:`loadReadmeFile`)
	:raises FileNotFoundError:             If the requirements file doesn't exist. (See :func:`loadRequirementsFile`)
	:raises Exception:                     If the package's directory doesn't exist, or if a requirements file is
	                                       malformed.
	:raises PackagingError:                If no description was given and the package file has no module doc-string.
	:raises UnhandledCriticalWarningError: If an extra's requirement is a direct reference and no
	                                       :class:`~pyTooling.Warning.WarningCollector` collects the
	                                       :exc:`DirectReferenceWarning`.
	"""
	...

	def _naturalSorting(array: Iterable[str]) -> list[str]:
		"""
		A simple natural sorting implementation.

		:param array: The strings to sort.
		:returns:     The strings, sorted with embedded numbers compared numerically.
		"""
		def _toInt(text: str) -> Union[str, int]:
			"""
			Try to convert a :class:`str` to :class:`int` if possible, otherwise preserve the string.

			:param text: The text to convert.
			:returns:    The converted integer, or the unchanged string.
			"""
			...

		def _createKey(text: str) -> tuple[Union[str, float], ...]:
			"""
			Split the text into a tuple of multiple :class:`str` and :class:`int` fields, so embedded numbers can be sorted by
			their value.

			:param text: The text to split.
			:returns:    Tuple of string and integer fields, usable as a sort key.
			"""
			...

		...

	...

@export
def DescribePythonPackageHostedOnGitHub(
	packageName: str,
	gitHubNamespace: str,
	gitHubRepository: Nullable[str] = None,
	projectURL: Nullable[str] = None,
	description: Nullable[str] = None,
	keywords: Nullable[Iterable[str]] = None,
	license: License = DEFAULT_LICENSE,
	readmeFile: Path = DEFAULT_README,
	requirementsFile: Path = DEFAULT_REQUIREMENTS,
	documentationRequirementsFile: Path = DEFAULT_DOCUMENTATION_REQUIREMENTS,
	unittestRequirementsFile: Path = DEFAULT_TEST_REQUIREMENTS,
	packagingRequirementsFile: Path = DEFAULT_PACKAGING_REQUIREMENTS,
	additionalRequirements: Nullable[dict[str, list[str]]] = None,
	sourceFileWithVersion: Path = DEFAULT_VERSION_FILE,
	classifiers: Iterable[str] = DEFAULT_CLASSIFIERS,
	developmentStatus: str = "stable",
	pythonVersions: Sequence[str] = DEFAULT_PY_VERSIONS,
	consoleScripts: Nullable[dict[str, str]] = None,
	guiScripts: Nullable[dict[str, str]] = None,
	pytestPlugins: Nullable[dict[str, str]] = None,
	dataFiles: Nullable[dict[str, list[str]]] = None,
	debug: bool = False
) -> dict[str, Any]:
	"""
	Helper function to describe a Python package when the source code is hosted on GitHub.

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

	:param packageName:                    Name of the Python package.
	:param gitHubNamespace:                Name of the GitHub namespace (organization or user).
	:param gitHubRepository:               Optional, name of the GitHub repository.
	:param projectURL:                     Optional, URL to the Python project.
	:param description:                    Optional, short description of the package. (Default: the first paragraph
	                                       of the module doc-string in ``sourceFileWithVersion``.) The long description
	                                       is read from the README file.
	:param keywords:                       Optional, a list of keywords.
	:param license:                        Optional, the package's license. (Default: ``Apache License, 2.0``, see
	                                       :const:`DEFAULT_LICENSE`)
	:param readmeFile:                     Optional, the path to the README file. (Default: ``README.md``, see
	                                       :const:`DEFAULT_README`)
	:param requirementsFile:               Optional, the path to the project's requirements file. (Default:
	                                       ``requirements.txt``, see :const:`DEFAULT_REQUIREMENTS`)
	:param documentationRequirementsFile:  Optional, the path to the project's requirements file for documentation.
	                                       (Default: ``doc/requirements.txt``, see
	                                       :const:`DEFAULT_DOCUMENTATION_REQUIREMENTS`)
	:param unittestRequirementsFile:       Optional, the path to the project's requirements file for unit tests. (Default:
	                                       ``tests/requirements.txt``, see :const:`DEFAULT_TEST_REQUIREMENTS`)
	:param packagingRequirementsFile:      Optional, the path to the project's requirements file for packaging. (Default:
	                                       ``build/requirements.txt``, see :const:`DEFAULT_PACKAGING_REQUIREMENTS`)
	:param additionalRequirements:         Optional, a dictionary of a lists with additional requirements. (default: None)
	:param sourceFileWithVersion:          Optional, the path to the project's source file containing dunder variables
	                                       like ``__version__``. (Default: ``__init__.py``, see
	                                       :const:`DEFAULT_VERSION_FILE`)
	:param classifiers:                    Optional, a list of package classifiers. (Default: 3 classifiers, see
	                                       :const:`DEFAULT_CLASSIFIERS`)
	:param developmentStatus:              Optional, development status of the package. (Default: stable, see
	                                       :const:`STATUS` for supported status values)
	:param pythonVersions:                 Optional, a list of supported Python 3 version. (Default: all currently
	                                       maintained CPython versions, see :const:`DEFAULT_PY_VERSIONS`)
	:param consoleScripts:                 Optional, a dictionary mapping command line names to entry points, declared
	                                       as ``console_scripts``. (Default: None)
	:param guiScripts:                     Optional, like ``consoleScripts``, but declared as ``gui_scripts`` - on
	                                       Windows such a program starts without a console window. (Default: None)
	:param pytestPlugins:                  Optional, a dictionary mapping plugin names to entry points, declared as
	                                       ``pytest11``. The classifier ``Framework :: Pytest`` is added with it.
	                                       (Default: None)
	:param dataFiles:                      Optional, a dictionary mapping package names to lists of additional data files.
	:param debug:                          Optional, if ``True``, enable extended outputs for debugging.
	:returns:                              A dictionary suitable for :func:`setuptools.setup`.
	:raises TypeError:                     If parameter 'license' is not of type :class:`~pyTooling.Licensing.License`.
	:raises TypeError:                     If parameter 'readmeFile' is not of type :class:`~pathlib.Path`.
	:raises TypeError:                     If parameter 'requirementsFile' is not of type :class:`~pathlib.Path`.
	:raises TypeError:                     If parameter 'documentationRequirementsFile' is not of type
	                                       :class:`~pathlib.Path`.
	:raises TypeError:                     If parameter 'unittestRequirementsFile' is not of type :class:`~pathlib.Path`.
	:raises TypeError:                     If parameter 'packagingRequirementsFile' is not of type :class:`~pathlib.Path`.
	:raises TypeError:                     If parameter 'sourceFileWithVersion' is not of type :class:`~pathlib.Path`.
	:raises MissingDependencyError:        If package 'setuptools' is not available.
	:raises FileNotFoundError:             If README file doesn't exist.
	:raises FileNotFoundError:             If requirements file doesn't exist.
	:raises FileNotFoundError:             If package file with dunder variables doesn't exist.
	:raises ValueError:                    If developmentStatus uses an unsupported value. (See :const:`STATUS`)
	:raises ValueError:                    If the content type of the README file is not supported. (See
	                                       :func:`loadReadmeFile`)
	:raises FileNotFoundError:             If the README file doesn't exist. (See :func:`loadReadmeFile`)
	:raises FileNotFoundError:             If the requirements file doesn't exist. (See :func:`loadRequirementsFile`)
	:raises PackagingError:                If no description was given and the package file has no module doc-string.
	:raises UnhandledCriticalWarningError: If an extra's requirement is a direct reference and no
	                                       :class:`~pyTooling.Warning.WarningCollector` collects the
	                                       :exc:`DirectReferenceWarning`.
	"""
	...