Utilities#
A set of small, helper utilities for dealing with Python packages.
Reference#
- class packaging.utils.NormalizedName#
A
typing.NewType
ofstr
, representing a normalized name.
- packaging.utils.canonicalize_name(name)#
This function takes a valid Python package or extra name, and returns the normalized form of it.
The return type is typed as
NormalizedName
. This allows type checkers to help require that a string has passed through this function before use.- Parameters:
name (str) – The name to normalize.
>>> from packaging.utils import canonicalize_name >>> canonicalize_name("Django") 'django' >>> canonicalize_name("oslo.concurrency") 'oslo-concurrency' >>> canonicalize_name("requests") 'requests'
- packaging.utils.canonicalize_version(version)#
This function takes a string representing a package version (or a
Version
instance), and returns the normalized form of it.- Parameters:
version (str) – The version to normalize.
>>> from packaging.utils import canonicalize_version >>> canonicalize_version('1.4.0.0.0') '1.4'
- packaging.utils.parse_wheel_filename(filename)#
This function takes the filename of a wheel file, and parses it, returning a tuple of name, version, build number, and tags.
The name part of the tuple is normalized and typed as
NormalizedName
. The version portion is an instance ofVersion
. The build number is()
if there is no build number in the wheel filename, otherwise a two-item tuple of an integer for the leading digits and a string for the rest of the build number. The tags portion is an instance ofTag
.- Parameters:
filename (str) – The name of the wheel file.
- Raises:
InvalidWheelFilename – If the filename in question does not follow conventions outlined in PEP 427.
>>> from packaging.utils import parse_wheel_filename >>> from packaging.tags import Tag >>> from packaging.version import Version >>> name, ver, build, tags = parse_wheel_filename("foo-1.0-py3-none-any.whl") >>> name 'foo' >>> ver == Version('1.0') True >>> tags == {Tag("py3", "none", "any")} True >>> not build True
- packaging.utils.parse_sdist_filename(filename)#
This function takes the filename of a sdist file (as specified in the Source distribution format documentation), and parses it, returning a tuple of the normalized name and version as represented by an instance of
Version
.- Parameters:
filename (str) – The name of the sdist file.
- Raises:
InvalidSdistFilename – If the filename does not end with an sdist extension (
.zip
or.tar.gz
), or if it does not contain a dash separating the name and the version of the distribution.
>>> from packaging.utils import parse_sdist_filename >>> from packaging.version import Version >>> name, ver = parse_sdist_filename("foo-1.0.tar.gz") >>> name 'foo' >>> ver == Version('1.0') True
- exception packaging.utils.InvalidWheelFilename#
Raised when a file name for a wheel is invalid.
- exception packaging.utils.InvalidSdistFilename#
Raised when a source distribution file name is considered invalid.