Utilities

A set of small, helper utilities for dealing with Python packages.

Reference

packaging.utils.BuildTag = tuple[()] | tuple[int, str]

A wheel build tag: an empty tuple, or a (build number, build tag suffix) pair.

Added in version 20.9.

exception packaging.utils.InvalidName

An invalid distribution name; users should refer to the packaging user guide.

Added in version 23.2.

exception packaging.utils.InvalidSdistFilename

An invalid sdist filename was found, users should refer to the packaging user guide.

Added in version 20.9.

exception packaging.utils.InvalidWheelFilename

An invalid wheel filename was found, users should refer to PEP 427.

Added in version 20.9.

class packaging.utils.NormalizedName

A typing.NewType of str, representing a normalized name.

Added in version 20.4.

alias of str

packaging.utils.canonicalize_name(name, *, validate=False)

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.

If validate is true, then the function will check if name is a valid distribution name before normalizing.

Parameters:

  • name (str) – The name to normalize.

  • validate (bool) – Check whether the name is a valid distribution name.

Raises:

InvalidName – If validate is true and the name is not an acceptable distribution name.

Return type:

NormalizedName

>>> from packaging.utils import canonicalize_name
>>> canonicalize_name("Django")
'django'
>>> canonicalize_name("oslo.concurrency")
'oslo-concurrency'
>>> canonicalize_name("requests")
'requests'

Added in version 16.2.

Changed in version 20.4: The return type was changed to NormalizedName.

Changed in version 23.2: Added the validate keyword parameter.

packaging.utils.canonicalize_version(version, *, strip_trailing_zero=True)

Return a canonical form of a version as a string.

This function takes a string representing a package version (or a Version instance), and returns the normalized form of it. By default, it strips trailing zeros from the release segment.

>>> from packaging.utils import canonicalize_version
>>> canonicalize_version('1.0.1')
'1.0.1'

Per PEP 625, versions may have multiple canonical forms, differing only by trailing zeros.

>>> canonicalize_version('1.0.0')
'1'
>>> canonicalize_version('1.0.0', strip_trailing_zero=False)
'1.0.0'

Invalid versions are returned unaltered.

>>> canonicalize_version('foo bar baz')
'foo bar baz'

>>> canonicalize_version('1.4.0.0.0')
'1.4'

Added in version 17.1.

Changed in version 21.0: The return type was narrowed to str.

Changed in version 22.0: Added the strip_trailing_zero keyword parameter.

Parameters:
Return type:

str

packaging.utils.is_normalized_name(name)

Check if a name is a normalized project name (i.e. a valid name that canonicalize_name() would roundtrip to the same value).

The roundtrip only characterizes normalized names for valid names. A name must start and end with an ASCII letter or digit, which canonicalize_name() does not enforce: it leaves a leading or trailing hyphen in place, so such a name roundtrips without being normalized.

Parameters:

name (str) – The name to check.

Return type:

bool

>>> from packaging.utils import canonicalize_name, is_normalized_name
>>> is_normalized_name("requests")
True
>>> is_normalized_name("Django")
False
>>> canonicalize_name("_not_legal")
'-not-legal'
>>> is_normalized_name("-not-legal")  # roundtrips, but not a valid name
False

Added in version 23.2.

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), if it does not contain a dash separating the name and the version of the distribution, if the project name is empty, or if the version portion is not a valid version.

Return type:

tuple[NormalizedName, Version]

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

Added in version 20.9.

Changed in version 21.0: Added support for .zip source distributions.

Changed in version 23.2: Raises InvalidSdistFilename when the version component is invalid.

Changed in version 26.3: Raises InvalidSdistFilename on an empty project name.

packaging.utils.parse_wheel_filename(filename, *, validate_order=False)

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 of Version. 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 a frozen set of Tag instances (as the tag string format allows multiple tags to be combined into a single string).

If validate_order is true, compressed tag set components are checked to be in sorted order as required by PEP 425.

Parameters:

  • filename (str) – The name of the wheel file.

  • validate_order (bool) – Check whether compressed tag set components are in sorted order.

Raises:

InvalidWheelFilename – If the filename in question does not follow the wheel specification.

Return type:

tuple[NormalizedName, Version, tuple[()] | tuple[int, str], frozenset[Tag]]

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

Added in version 20.9.

Changed in version 23.2: Raises InvalidWheelFilename when the version component is invalid.

Added in version 26.1: The validate_order parameter.

Changed in version 26.3: Raises InvalidWheelFilename when an interpreter component is not an identifier, a tag set component is empty, or the project name is empty.