tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

utils.rst (2841B)

      1 Utilities
      2 =========
      3 
      4 .. currentmodule:: packaging.utils
      5 
      6 
      7 A set of small, helper utilities for dealing with Python packages.
      8 
      9 
     10 Reference
     11 ---------
     12 
     13 .. function:: canonicalize_name(name)
     14 
     15    This function takes a valid Python package name, and returns the normalized
     16    form of it.
     17 
     18    :param str name: The name to normalize.
     19 
     20    .. doctest::
     21 
     22        >>> from packaging.utils import canonicalize_name
     23        >>> canonicalize_name("Django")
     24        'django'
     25        >>> canonicalize_name("oslo.concurrency")
     26        'oslo-concurrency'
     27        >>> canonicalize_name("requests")
     28        'requests'
     29 
     30 .. function:: canonicalize_version(version)
     31 
     32    This function takes a string representing a package version (or a
     33    :class:`~packaging.version.Version` instance), and returns the
     34    normalized form of it.
     35 
     36    :param str version: The version to normalize.
     37 
     38    .. doctest::
     39 
     40        >>> from packaging.utils import canonicalize_version
     41        >>> canonicalize_version('1.4.0.0.0')
     42        '1.4'
     43 
     44 .. function:: parse_wheel_filename(filename)
     45 
     46    This function takes the filename of a wheel file, and parses it,
     47    returning a tuple of name, version, build number, and tags.
     48 
     49    The name part of the tuple is normalized. The version portion is an
     50    instance of :class:`~packaging.version.Version`. The build number
     51    is ``()`` if there is no build number in the wheel filename,
     52    otherwise a two-item tuple of an integer for the leading digits and
     53    a string for the rest of the build number. The tags portion is an
     54    instance of :class:`~packaging.tags.Tag`.
     55 
     56    :param str filename: The name of the wheel file.
     57 
     58    .. doctest::
     59 
     60        >>> from packaging.utils import parse_wheel_filename
     61        >>> from packaging.tags import Tag
     62        >>> from packaging.version import Version
     63        >>> name, ver, build, tags = parse_wheel_filename("foo-1.0-py3-none-any.whl")
     64        >>> name
     65        'foo'
     66        >>> ver == Version('1.0')
     67        True
     68        >>> tags == {Tag("py3", "none", "any")}
     69        True
     70        >>> not build
     71        True
     72 
     73 .. function:: parse_sdist_filename(filename)
     74 
     75    This function takes the filename of a sdist file (as specified
     76    in the `Source distribution format`_ documentation), and parses
     77    it, returning a tuple of the normalized name and version as
     78    represented by an instance of :class:`~packaging.version.Version`.
     79 
     80    :param str filename: The name of the sdist file.
     81 
     82    .. doctest::
     83 
     84        >>> from packaging.utils import parse_sdist_filename
     85        >>> from packaging.version import Version
     86        >>> name, ver = parse_sdist_filename("foo-1.0.tar.gz")
     87        >>> name
     88        'foo'
     89        >>> ver == Version('1.0')
     90        True
     91 
     92 .. _Source distribution format: https://packaging.python.org/specifications/source-distribution-format/#source-distribution-file-name