Expose various function in tags publicly

.pre-commit-config.yaml

@@ -8,7 +8,7 @@ repos:
   - id: trailing-whitespace
 
 - repo: https://github.com/pre-commit/mirrors-mypy
-  rev: v0.720
+  rev: v0.740
   hooks:
   - id: mypy
     exclude: '^(docs|tasks|tests)|setup\.py'

docs/tags.rst

@@ -38,6 +38,7 @@ Reference
     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
@@ -65,17 +66,18 @@ Reference
 
 .. function:: parse_tag(tag)
 
-    Parse the provided *tag* into a set of :class:`Tag` instances.
+    Parses 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"``.
+    Returning a set is required due to the possibility that the tag is a
+    `compressed tag set`_, e.g. ``"py2.py3-none-any"`` which supports both
+    Python 2 and Python 3.
 
     :param str tag: The tag to parse, e.g. ``"py3-none-any"``.
 
 
-.. function:: sys_tags(warn=False)
+.. function:: sys_tags(*, warn=False)
 
-    Create an iterable of tags that the running interpreter supports.
+    Yields the 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
@@ -92,11 +94,108 @@ Reference
 
     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.
+    and tag calculation happens to be expensive.
 
     :param bool warn: Whether warnings should be logged. Defaults to ``False``.
 
 
+.. function:: interpreter_name()
+
+    Returns the running interpreter's name.
+
+    This typically acts as the prefix to the :attr:`~Tag.interpreter` tag.
+
+
+.. function:: interpreter_version(*, warn=False)
+
+    Returns the running interpreter's version.
+
+    This typically acts as the suffix to the :attr:`~Tag.interpreter` tag.
+
+
+.. function:: mac_platforms(version=None, arch=None)
+
+    Yields the :attr:`~Tag.platform` tags for macOS.
+
+    :param tuple version: A two-item tuple presenting the version of macOS.
+                          Defaults to the current system's version.
+    :param str arch: The CPU architecture. Defaults to the architecture of the
+                     current system, e.g. ``"x86_64"``.
+
+    .. note::
+        Equivalent support for the other major platforms is purposefully not
+        provided:
+
+        - On Windows, platform compatibility is statically specified
+        - On Linux, code must be run on the system itself to determine
+          compatibility
+
+
+.. function:: compatible_tags(python_version=None, interpreter=None, platforms=None)
+
+    Yields the tags for an interpreter compatible with the Python version
+    specified by ``python_version``.
+
+    The specific tags generated are:
+
+    - ``py*-none-<platform>``
+    - ``<interpreter>-none-any`` if ``interpreter`` is provided
+    - ``py*-none-any``
+
+    :param Sequence python_version: A one- or two-item sequence representing the
+                                 compatible version of Python. Defaults to
+                                 ``sys.version_info[:2]``.
+    :param str interpreter: The name of the interpreter (if known), e.g.
+                            ``"cp38"``. Defaults to the current interpreter.
+    :param Iterable platforms: Iterable of compatible platforms. Defaults to the
+                               platforms compatible with the current system.
+
+.. function:: cpython_tags(python_version=None, abis=None, platforms=None, *, warn=False)
+
+    Yields the tags for the CPython interpreter.
+
+    The specific tags generated are:
+
+    - ``cp<python_version>-<abi>-<platform>``
+    - ``cp<python_version>-abi3-<platform>``
+    - ``cp<python_version>-none-<platform>``
+    - ``cp<older version>-abi3-<platform>`` where "older version" is all older
+      minor versions down to Python 3.2 (when ``abi3`` was introduced)
+
+    If ``python_version`` only provides a major-only version then only
+    user-provided ABIs via ``abis`` and the ``none`` ABI will be used.
+
+    :param Sequence python_version: A one- or two-item sequence representing the
+                                 targetted Python version. Defaults to
+                                 ``sys.version_info[:2]``.
+    :param Iterable abis: Iterable of compatible ABIs. Defaults to the ABIs
+                          compatible with the current system.
+    :param Iterable platforms: Iterable of compatible platforms. Defaults to the
+                               platforms compatible with the current system.
+    :param bool warn: Whether warnings should be logged. Defaults to ``False``.
+
+.. function:: generic_tags(interpreter=None, abis=None, platforms=None, *, warn=False)
+
+    Yields the tags for an interpreter which requires no specialization.
+
+    This function should be used if one of the other interpreter-specific
+    functions provided by this module is not appropriate (i.e. not calculating
+    tags for a CPython interpreter).
+
+    The specific tags generated are:
+
+    - ``<interpreter>-<abi>-<platform>``
+
+    The ``"none"`` ABI will be added if it was not explicitly provided.
+
+    :param str interpreter: The name of the interpreter. Defaults to being
+                            calculated.
+    :param Iterable abis: Iterable of compatible ABIs. Defaults to the ABIs
+                          compatible with the current system.
+    :param Iterable platforms: Iterable of compatible platforms. Defaults to the
+                               platforms compatible with the current system.
+    :param bool warn: Whether warnings should be logged. Defaults to ``False``.
+
 .. _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/