Skip to content
Permalink
Browse files

Introduce packaging.tags (#156)

  • Loading branch information...
brettcannon authored and dstufft committed May 10, 2019
1 parent e78164b commit 76bc450c18c909f5167f518cd310db550da0e0cb
Showing with 1,016 additions and 2 deletions.
  1. +1 −0 .coveragerc
  2. +1 −1 .gitignore
  3. +1 −0 CHANGELOG.rst
  4. +4 −0 dev-requirements.txt
  5. +1 −0 docs/index.rst
  6. +101 −0 docs/tags.rst
  7. +354 −0 packaging/tags.py
  8. +1 −1 setup.py
  9. +552 −0 tests/test_tags.py
@@ -4,5 +4,6 @@ omit = packaging/_compat.py

[report]
exclude_lines =
pragma: no cover
@abc.abstractmethod
@abc.abstractproperty
@@ -6,7 +6,7 @@
.cache/
.coverage
.idea
.venv
.venv*

__pycache__/
_build/
@@ -11,6 +11,7 @@ Changelog
~~~~~~~~~~~~~~~~~

* Fix string representation of PEP 508 direct URL requirements with markers.
* Add the `packaging.tags` module.

This comment has been minimized.

Copy link
@di

di Jun 4, 2019

Member

@brettcannon This line is in the wrong place, 19.0 had already been released when you added this.

This comment has been minimized.

Copy link
@brettcannon

brettcannon Jun 4, 2019

Author Contributor

Technically it wasn't when I first opened the PR, but it took so long to merge no one noticed the outdated location. 😄

This comment has been minimized.

Copy link
@di

di Jun 4, 2019

Member

Hah, I realized that after I left this comment, but then I couldn't where I left my comment -- looks like because I left it on a commit and not on the PR 😅


* Better handling of file URLs

@@ -1,4 +1,8 @@
# Install our development requirements
black; python_version >= '3.6'
coverage
flake8
pep8-naming
pretend
pytest
tox
@@ -24,6 +24,7 @@ API
specifiers
markers
requirements
tags
utils


@@ -0,0 +1,101 @@
Tags
====

.. currentmodule:: packaging.tags

Wheels encode the Python interpreter, ABI, and platform that they support in
their filenames using *`platform compatibility tags`_*. This module provides
support for both parsing these tags as well as discovering what tags the
running Python interpreter supports.

Usage
-----

.. doctest::

>>> from packaging.tags import Tag, sys_tags
>>> import sys
>>> looking_for = Tag("py{major}".format(major=sys.version_info.major), "none", "any")
>>> supported_tags = list(sys_tags())
>>> looking_for in supported_tags
True
>>> really_old = Tag("py1", "none", "any")
>>> wheels = {really_old, looking_for}
>>> best_wheel = None
>>> for supported_tag in supported_tags:
... for wheel_tag in wheels:
... if supported_tag == wheel_tag:
... best_wheel = wheel_tag
... break
>>> best_wheel == looking_for
True
Reference
---------

.. attribute:: INTERPRETER_SHORT_NAMES

A dictionary mapping interpreter names to their `abbreviation codes`_
(e.g. ``"cpython"`` is ``"cp"``). All interpreter names are lower-case.

.. class:: Tag(interpreter, abi, platform)

A representation of the tag triple for a wheel. Instances are considered
immutable and thus are hashable. Equality checking is also supported.

:param str interpreter: The interpreter name, e.g. ``"py"``
(see :attr:`INTERPRETER_SHORT_NAMES` for mapping
well-known interpreter names to their short names).
:param str abi: The ABI that a wheel supports, e.g. ``"cp37m"``.
:param str platform: The OS/platform the wheel supports,
e.g. ``"win_amd64"``.

.. attribute:: interpreter

The interpreter name.

.. attribute:: abi

The supported ABI.

.. attribute:: platform

The OS/platform.


.. function:: parse_tag(tag)

Parse the provided *tag* into a set of :class:`Tag` instances.

The returning of a set is required due to the possibility that the tag is a
`compressed tag set`_, e.g. ``"py2.py3-none-any"``.

:param str tag: The tag to parse, e.g. ``"py3-none-any"``.


.. function:: sys_tags()

Create an iterable of tags that the running interpreter supports.

The iterable is ordered so that the best-matching tag is first in the
sequence. The exact preferential order to tags is interpreter-specific, but
in general the tag importance is in the order of:

1. Interpreter
2. Platform
3. ABI

This order is due to the fact that an ABI is inherently tied to the
platform, but platform-specific code is not necessarily tied to the ABI. The
interpreter is the most important tag as it dictates basic support for any
wheel.

The function returns an iterable in order to allow for the possible
short-circuiting of tag generation if the entire sequence is not necessary
and calculating some tags happens to be expensive.


.. _abbreviation codes: https://www.python.org/dev/peps/pep-0425/#python-tag
.. _compressed tag set: https://www.python.org/dev/peps/pep-0425/#compressed-tag-sets
.. _platform compatibility tags: https://packaging.python.org/specifications/platform-compatibility-tags/
.. _PEP 425: https://www.python.org/dev/peps/pep-0425/

0 comments on commit 76bc450

Please sign in to comment.
You can’t perform that action at this time.