Metadata-Version: 2.4
Name: wheel-filename
Version: 1.4.2
Summary: Parse wheel filenames
Project-URL: Source Code, https://github.com/wheelodex/wheel-filename
Project-URL: Bug Tracker, https://github.com/wheelodex/wheel-filename/issues
Author-email: John Thorvald Wodder II <wheel-filename@varonathe.org>
License-Expression: MIT
License-File: LICENSE
Keywords: filename,pep427,wheel
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: System :: Software Distribution
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/x-rst

|repostatus| |ci-status| |coverage| |pyversions| |license|

.. |repostatus| image:: https://www.repostatus.org/badges/latest/active.svg
    :target: https://www.repostatus.org/#active
    :alt: Project Status: Active — The project has reached a stable, usable
          state and is being actively developed.

.. |ci-status| image:: https://github.com/wheelodex/wheel-filename/actions/workflows/test.yml/badge.svg
    :target: https://github.com/wheelodex/wheel-filename/actions/workflows/test.yml
    :alt: CI Status

.. |coverage| image:: https://codecov.io/gh/wheelodex/wheel-filename/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/wheelodex/wheel-filename

.. |pyversions| image:: https://img.shields.io/pypi/pyversions/wheel-filename.svg
    :target: https://pypi.org/project/wheel-filename/

.. |license| image:: https://img.shields.io/github/license/wheelodex/wheel-filename.svg
    :target: https://opensource.org/licenses/MIT
    :alt: MIT License

`GitHub <https://github.com/wheelodex/wheel-filename>`_
| `PyPI <https://pypi.org/project/wheel-filename/>`_
| `Issues <https://github.com/wheelodex/wheel-filename/issues>`_
| `Changelog <https://github.com/wheelodex/wheel-filename/blob/master/CHANGELOG.md>`_

``wheel-filename`` lets you verify wheel_ filenames and parse them into their
component fields.

.. _wheel: https://packaging.python.org/en/latest/specifications
           /binary-distribution-format/

This package adheres strictly to the standard, with the following exceptions:

- Version components may be any sequence of the relevant set of characters;
  they are not verified for PEP 440 compliance.

- The ``.whl`` file extension is matched case-insensitively.


Installation
============
``wheel-filename`` requires Python 3.8 or higher.  Just use `pip
<https://pip.pypa.io>`_ for Python 3 (You have pip, right?) to install it::

    python3 -m pip install wheel-filename


Example
=======

>>> from wheel_filename import parse_wheel_filename
>>> pwf = parse_wheel_filename('pip-18.0-py2.py3-none-any.whl')
>>> str(pwf)
'pip-18.0-py2.py3-none-any.whl'
>>> pwf.project
'pip'
>>> pwf.version
'18.0'
>>> pwf.build is None
True
>>> pwf.python_tags
['py2', 'py3']
>>> pwf.abi_tags
['none']
>>> pwf.platform_tags
['any']
>>> list(pwf.tag_triples())
['py2-none-any', 'py3-none-any']


API
===

``parse_wheel_filename(filename)``
   Parses a wheel filename (a ``str``, ``bytes``, or ``os.PathLike``) and
   returns a ``ParsedWheelFilename`` instance.  Any leading directory
   components are stripped from the argument before processing.  If the
   filename is not a valid wheel filename, raises an ``InvalidFilenameError``.

``ParsedWheelFilename``
   A namedtuple representing the components of a wheel filename.  It has the
   following attributes and methods:

   ``project: str``
      The name of the project distributed by the wheel

   ``version: str``
      The version of the project distributed by the wheel

   ``build: Optional[str]``
      The wheel's build tag (``None`` if not defined)

   ``python_tags: List[str]``
      A list of Python tags for the wheel

   ``abi_tags: List[str]``
      A list of ABI tags for the wheel

   ``platform_tags: List[str]``
      A list of platform tags for the wheel

   ``str(pwf)``
      Stringifying a ``ParsedWheelFilename`` returns the original filename

   ``tag_triples() -> Iterator[str]``
      Returns an iterator of all simple tag triples formed from the
      compatibility tags in the filename

``InvalidFilenameError``
   A subclass of ``ValueError`` raised when an invalid wheel filename is passed
   to ``parse_wheel_filename()``.  It has a ``filename`` attribute containing
   the basename of the invalid filename.


Command
=======

*New in version 1.4.0*

``wheel-filename`` also provides a command of the same name that takes a wheel
filename (The actual wheel does not have to exist) and outputs the filename
components as JSON.

Example::

    $ wheel-filename pip-18.0-py2.py3-none-any.whl
    {
        "project": "pip",
        "version": "18.0",
        "build": null,
        "python_tags": [
            "py2",
            "py3"
        ],
        "abi_tags": [
            "none"
        ],
        "platform_tags": [
            "any"
        ]
    }
