Utilities

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

Reference

exception packaging.utils.InvalidName

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

exception packaging.utils.InvalidSdistFilename

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

exception packaging.utils.InvalidWheelFilename

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

class packaging.utils.NormalizedName

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

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'
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'
Parameters:
Return type:

str

packaging.utils.is_normalized_name(name)

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

Parameters:

name (str) – The name to check.

Return type:

bool

>>> from packaging.utils import is_normalized_name
>>> is_normalized_name("requests")
True
>>> is_normalized_name("Django")
False
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.

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

Parameters:

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

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