check-python-versions 0.23.0__py3-none-any.whl

check_python_versions/parsers/requires_python.py

@@ -0,0 +1,239 @@
+"""
+Tools for manipulating requires-python PyPI classifiers.
+"""
+import re
+from typing import Callable, Dict, List, Optional, Tuple, TypedDict, Union
+
+from ..utils import warn
+from ..versions import (
+    MAX_MINOR_FOR_MAJOR,
+    SortedVersionList,
+    Version,
+    VersionList,
+)
+
+
+def parse_python_requires(
+    s: str,
+    name: str = "python_requires",
+    *,
+    filename: str = "setup.py",
+) -> Optional[SortedVersionList]:
+    """Compute Python versions allowed by a python_requires expression."""
+
+    # https://www.python.org/dev/peps/pep-0440/#version-specifiers
+    rx = re.compile(r'^(~=|==|!=|<=|>=|<|>|===)\s*(\d+(?:\.\d+)*(?:\.\*)?)$')
+
+    class BadConstraint(Exception):
+        """The version clause is ill-formed according to PEP 440."""
+
+    #
+    # This works as follows: we split the specifier on commas into a list
+    # of Constraints, each represented as a operator and a tuple of numbers
+    # with a possible trailing '*'.  PEP 440 calls them "clauses".
+    #
+
+    Constraint = Tuple[Union[str, int], ...]
+
+    #
+    # The we look up a handler for each operartor.  This handler takes a
+    # constraint and compiles it into a checker.  A checker is a function
+    # that takes a Python version number as a 2-tuple and returns True if
+    # that version passes its constraint.
+    #
+
+    VersionTuple = Tuple[int, int]
+    CheckFn = Callable[[VersionTuple], bool]
+    HandlerFn = Callable[[Constraint], CheckFn]
+
+    #
+    # Here we're defining the handlers for all the operators
+    #
+
+    handlers: Dict[str, HandlerFn] = {}
+
+    def handler(operator: str) -> Callable[[HandlerFn], None]:
+        def decorator(fn: HandlerFn) -> None:
+            handlers[operator] = fn
+        return decorator
+
+    #
+    # We are not doing a strict PEP-440 implementation here because if
+    # python_requires allows, say, Python 2.7.16, then we want to report that
+    # as Python 2.7.  In each handler ``candidate`` is a two-tuple (X, Y)
+    # that represents any Python version between X.Y.0 and X.Y.<whatever>.
+    #
+
+    @handler('~=')
+    def compatible_version(constraint: Constraint) -> CheckFn:
+        """~= X.Y more or less means >= X.Y and == X.Y.*"""
+        if len(constraint) < 2:
+            raise BadConstraint('~= requires a version with at least one dot')
+        if constraint[-1] == '*':
+            raise BadConstraint('~= does not allow a .*')
+        return lambda candidate: candidate == constraint[:2]
+
+    @handler('==')
+    def matching_version(constraint: Constraint) -> CheckFn:
+        """== X.Y means X.Y, no more, no less; == X[.Y].* is allowed."""
+        # we know len(candidate) == 2
+        if len(constraint) == 2 and constraint[-1] == '*':
+            return lambda candidate: candidate[0] == constraint[0]
+        elif len(constraint) == 1:
+            # == X should imply Python X.0
+            return lambda candidate: candidate == constraint + (0,)
+        else:
+            # == X.Y.* and == X.Y.Z both imply Python X.Y
+            return lambda candidate: candidate == constraint[:2]
+
+    @handler('!=')
+    def excluded_version(constraint: Constraint) -> CheckFn:
+        """!= X.Y is the opposite of == X.Y."""
+        # we know len(candidate) == 2
+        if constraint[-1] != '*':
+            # != X or != X.Y or != X.Y.Z all are meaningless for us, because
+            # there exists some W != Z where we allow X.Y.W and thus allow
+            # Python X.Y.
+            return lambda candidate: True
+        elif len(constraint) == 2:
+            # != X.* excludes the entirety of a major version
+            return lambda candidate: candidate[0] != constraint[0]
+        else:
+            # != X.Y.* excludes one particular minor version X.Y,
+            # != X.Y.Z.* does not exclude anything, but it's fine,
+            # len(candidate) != len(constraint[:-1] so it'll be equivalent to
+            # True anyway.
+            return lambda candidate: candidate != constraint[:-1]
+
+    @handler('>=')
+    def greater_or_equal_version(constraint: Constraint) -> CheckFn:
+        """>= X.Y allows X.Y.* or X.(Y+n).*, or (X+n).*."""
+        if constraint[-1] == '*':
+            raise BadConstraint('>= does not allow a .*')
+        # >= X, >= X.Y, >= X.Y.Z all work out nicely because in Python
+        # (3, 0) >= (3,)
+        return lambda candidate: candidate >= constraint[:2]
+
+    @handler('<=')
+    def lesser_or_equal_version(constraint: Constraint) -> CheckFn:
+        """<= X.Y is the opposite of > X.Y."""
+        if constraint[-1] == '*':
+            raise BadConstraint('<= does not allow a .*')
+        if len(constraint) == 1:
+            # <= X allows up to X.0
+            return lambda candidate: candidate <= constraint + (0,)
+        else:
+            # <= X.Y[.Z] allows up to X.Y
+            return lambda candidate: candidate <= constraint
+
+    @handler('>')
+    def greater_version(constraint: Constraint) -> CheckFn:
+        """> X.Y is equivalent to >= X.Y and != X.Y, I think."""
+        if constraint[-1] == '*':
+            raise BadConstraint('> does not allow a .*')
+        if len(constraint) == 1:
+            # > X allows X+1.0 etc
+            return lambda candidate: candidate[:1] > constraint
+        elif len(constraint) == 2:
+            # > X.Y allows X.Y+1 etc
+            return lambda candidate: candidate > constraint
+        else:
+            # > X.Y.Z allows X.Y
+            return lambda candidate: candidate >= constraint[:2]
+
+    @handler('<')
+    def lesser_version(constraint: Constraint) -> CheckFn:
+        """< X.Y is equivalent to <= X.Y and != X.Y, I think."""
+        if constraint[-1] == '*':
+            raise BadConstraint('< does not allow a .*')
+        # < X, < X.Y, < X.Y.Z all work out nicely because in Python
+        # (3, 0) > (3,), (3, 0) == (3, 0) and (3, 0) < (3, 0, 1)
+        return lambda candidate: candidate < constraint
+
+    @handler('===')
+    def arbitrary_version(constraint: Constraint) -> CheckFn:
+        """=== X.Y means X.Y, without any zero padding etc."""
+        if constraint[-1] == '*':
+            raise BadConstraint('=== does not allow a .*')
+        # === X does not allow anything
+        # === X.Y throws me into confusion; will pip compare Python's X.Y.Z ===
+        # X.Y and reject all possible values of Z?
+        # === X.Y.Z allows X.Y
+        return lambda candidate: candidate == constraint[:2]
+
+    #
+    # And now we can do what we planned: split and compile the constraints
+    # into checkers (which I also call "constraints", for maximum confusion).
+    #
+
+    constraints: List[CheckFn] = []
+    for specifier in map(str.strip, s.split(',')):
+        m = rx.match(specifier)
+        if not m:
+            warn(f'Bad {name} specifier in {filename}: {specifier}')
+            continue
+        op, arg = m.groups()
+        ver: Constraint = tuple(
+            int(segment) if segment != '*' else segment
+            for segment in arg.split('.')
+        )
+        try:
+            constraints.append(handlers[op](ver))
+        except BadConstraint as error:
+            warn(f'Bad {name} specifier in {filename}: {specifier} ({error})')
+
+    if not constraints:
+        return None
+
+    #
+    # And now we can check all the existing Python versions we know about
+    # and list those that pass all the requirements.
+    #
+
+    versions = []
+    for major in sorted(MAX_MINOR_FOR_MAJOR):
+        for minor in range(0, MAX_MINOR_FOR_MAJOR[major] + 1):
+            if all(constraint((major, minor)) for constraint in constraints):
+                versions.append(Version.from_string(f'{major}.{minor}'))
+    return versions
+
+
+class PythonRequiresStyle(TypedDict):
+    comma: str
+    space: str
+
+
+def detect_style(python_requires: str) -> PythonRequiresStyle:
+    """Determine how a python_requires string was formatted.
+
+    The return value is a dict of kwargs that can be splatted
+    into compute_python_requires(..., **style).
+    """
+    comma = ', '
+    if ',' in python_requires and ', ' not in python_requires:
+        comma = ','
+    space = ''
+    if '> ' in python_requires or '= ' in python_requires:
+        space = ' '
+    return dict(comma=comma, space=space)
+
+
+def compute_python_requires(
+    new_versions: VersionList,
+    *,
+    comma: str = ', ',
+    space: str = '',
+) -> str:
+    """Compute a value for python_requires that matches a set of versions."""
+    new_versions = set(new_versions)
+    latest_python = Version(major=3, minor=MAX_MINOR_FOR_MAJOR[3])
+    if len(new_versions) == 1 and new_versions != {latest_python}:
+        return f'=={space}{new_versions.pop()}.*'
+    min_version = min(new_versions)
+    specifiers = [f'>={space}{min_version}']
+    for major in sorted(MAX_MINOR_FOR_MAJOR):
+        for minor in range(0, MAX_MINOR_FOR_MAJOR[major] + 1):
+            ver = Version.from_string(f'{major}.{minor}')
+            if ver >= min_version and ver not in new_versions:
+                specifiers.append(f'!={space}{ver}.*')
+    return comma.join(specifiers)

check_python_versions/parsers/yaml.py

@@ -0,0 +1,221 @@
+"""
+Tools for manipulating YAML files.
+
+I want to preserve formatting and comments, therefore I cannot use a standard
+YAML parser and serializer.
+"""
+
+import string
+from typing import Any, Callable, Dict, List, Optional
+
+from ..utils import FileLines, OneOrMore, OneOrTuple, warn
+
+
+def quote_string(value: str, quote_style: str = '') -> str:
+    """Convert a string value to a YAML string literal."""
+    # Because I don't want to deal with quoting, I'll require all values
+    # to contain only safe characters (i.e. no ' or " or \).  This is fine
+    # because the only thing I want to quote is version numbers
+    safe_chars = string.ascii_letters + string.digits + ".-"
+    assert all(
+        c in safe_chars for c in value
+    ), f'{value!r} has unexpected characters'
+    try:
+        # 3.10 in yaml evaluates to 3.1 (a float), not '3.10' (a string)
+        if str(float(value)) != value:
+            quote_style = '"'
+    except ValueError:
+        pass
+    if quote_style:
+        assert quote_style not in value
+    return f'{quote_style}{value}{quote_style}'
+
+
+def update_yaml_list(
+    orig_lines: FileLines,
+    key: OneOrTuple[str],
+    new_value: List[Any],
+    *,
+    filename: str,
+    keep: Optional[Callable[[str], bool]] = None,
+    replacements: Optional[Dict[str, str]] = None,
+) -> FileLines:
+    """Update a list of values in a YAML document.
+
+    The document is represented as a list of lines (``orig_lines``), because
+    we want to preserve the exact formatting including comments.
+
+    ``key`` is a tuple that represents the traversal path from the root of
+    the document.  As a special case it can be a string instead of a 1-tuple
+    for top-level keys.
+
+    The new value of the list will consist of ``new_value``, plus whatever
+    old values need to be kept according to the ``keep`` callback.  Any of the
+    kept old values will also be optionally replaced with a replacement
+    from the ``replacements`` dict.
+
+    No YAML decoding is done for old values passed to ``keep()`` or
+    ``replacements.get()``.
+
+    No YAML escaping or formatting is done for new values or replacements.
+
+    ``filename`` is used for error reporting.
+
+    Returns an updated list of lines.
+    """
+    if not isinstance(key, tuple):
+        key = (key,)
+
+    lines = iter(enumerate(orig_lines))
+    current = 0
+    indents = [0]
+    for n, line in lines:
+        stripped = line.lstrip()
+        if not stripped or stripped.startswith('#'):
+            continue
+        indent = len(line) - len(stripped)
+        if current >= len(indents):
+            indents.append(indent)
+        elif indent > indents[current]:
+            continue
+        else:
+            while current > 0 and indent < indents[current]:
+                del indents[current]
+                current -= 1
+        if stripped.startswith(f'{key[current]}:'):
+            current += 1
+            if current == len(key):
+                break
+    else:
+        warn(f'Did not find {".".join(key)}: setting in {filename}')
+        return orig_lines
+
+    start = n
+    end = n + 1
+    indent = 2
+    list_indent = None
+    keep_before: List[str] = []
+    keep_after: List[str] = []
+    lines_to_keep = keep_before
+    kept_last: Optional[bool] = False
+    for n, line in lines:
+        stripped = line.lstrip()
+        line_indent = len(line) - len(stripped)
+        if list_indent is None and stripped.startswith('- '):
+            list_indent = line_indent
+        if stripped.startswith('- ') and line_indent == list_indent:
+            indent = line_indent
+            end = n + 1
+            value = stripped[2:].strip()
+            kept_last = keep and keep(value)
+            if kept_last:
+                if replacements and value in replacements:
+                    lines_to_keep.append(
+                        f"{' ' * indent}- {replacements[value]}\n"
+                    )
+                else:
+                    lines_to_keep.append(line)
+            lines_to_keep = keep_after
+        elif stripped.startswith('#'):
+            lines_to_keep.append(line)
+            end = n + 1
+        elif line_indent > indent:
+            if kept_last:
+                lines_to_keep.append(line)
+            end = n + 1
+        elif line != '\n':
+            break
+
+    new_lines = orig_lines[:start] + [
+        f"{' ' * indents[-1]}{key[-1]}:\n"
+    ] + keep_before + [
+        f"{' ' * indent}- {value}\n"
+        for value in new_value
+    ] + keep_after + orig_lines[end:]
+    return new_lines
+
+
+def drop_yaml_node(
+    orig_lines: FileLines,
+    key: str,
+    *,
+    filename: str,
+) -> FileLines:
+    """Drop a value from a YAML document.
+
+    The document is represented as a list of lines (``orig_lines``), because
+    we want to preserve the exact formatting including comments.
+
+    ``key`` is a string.  Currently only top-level nodes can be dropped.
+
+    ``filename`` is used for error reporting.
+
+    It is not an error if ``key`` is not present in the document.  In this
+    case ``orig_lines`` is returned unmodified.
+
+    Returns an updated list of lines.
+    """
+    lines = iter(enumerate(orig_lines))
+    where = None
+    for n, line in lines:
+        if line.startswith(f'{key}:'):
+            if where is not None:
+                warn(
+                    f"Duplicate {key}: setting in {filename}"
+                    f" (lines {where + 1} and {n + 1})"
+                )
+            where = n
+    if where is None:
+        return orig_lines
+
+    lines = iter(enumerate(orig_lines[where + 1:], where + 1))
+
+    start = where
+    end = start + 1
+    for n, line in lines:
+        if line and line[0] != ' ':
+            break
+        else:
+            end = n + 1
+    new_lines = orig_lines[:start] + orig_lines[end:]
+
+    return new_lines
+
+
+def add_yaml_node(
+    orig_lines: FileLines,
+    key: str,
+    value: str,
+    *,
+    before: Optional[OneOrMore[str]] = None,
+) -> FileLines:
+    """Add a value to a YAML document.
+
+    The document is represented as a list of lines (``orig_lines``), because
+    we want to preserve the exact formatting including comments.
+
+    ``key`` is a string.  Currently only top-level nodes can be added.
+
+    ``value`` is the new value, as a string.  No YAML escaping or formatting
+    is done.
+
+    ``before`` can specify a key or a set of keys.  If specified, the new
+    key will be added before the first of existing keys from this set.
+
+    Returns an updated list of lines.
+    """
+    lines = iter(enumerate(orig_lines))
+    where = len(orig_lines)
+    if before:
+        if isinstance(before, str):
+            before = (before, )
+        lines = iter(enumerate(orig_lines))
+        for n, line in lines:
+            if any(line == f'{key}:\n' for key in before):
+                where = n
+                break
+
+    new_lines = orig_lines[:where] + [
+        f'{key}: {value}\n'
+    ] + orig_lines[where:]
+    return new_lines

check_python_versions/sources/__init__.py

@@ -0,0 +1 @@
+"""Higher-level parsers for various file formats."""

check_python_versions/sources/all.py

@@ -0,0 +1,23 @@
+from .appveyor import Appveyor
+from .github import GitHubActions
+from .manylinux import Manylinux
+from .pyproject import PyProject, PyProjectPythonRequires
+from .setup_py import SetupClassifiers, SetupPythonRequires
+from .tox import Tox
+from .travis import Travis
+
+
+# The order here is only mildly important: it's used for presentation.
+# Note that SetupPythonRequires.title assumes it's included right after
+# SetupClassifiers!
+ALL_SOURCES = [
+    SetupClassifiers,
+    SetupPythonRequires,
+    PyProject,
+    PyProjectPythonRequires,
+    Tox,
+    Travis,
+    GitHubActions,
+    Appveyor,
+    Manylinux,
+]

check_python_versions/sources/appveyor.py

@@ -0,0 +1,191 @@
+"""
+Support for Appveyor.
+
+Appveyor is a hosted Continuous Integration solution that can be configured
+by dropping a file named ``appveyor.yml`` into your source repository.
+
+Appveyor can be configured through a web form as well, but
+check-python-manifest does not support checking that.
+
+The aforementioned web form can specify an alternative filename, but
+check-python-manifest does not support checking that.
+
+Appveyor does not directly support specifying Python interpreter versions,
+so most projects that test multiple Python versions do so by specifing the
+desired Python version in an environment variable.
+
+check-python-versions assumes this variable is called PYTHON and has either
+a Python version number, or the path to a Python installation
+("C:\\PythonX.Y").
+
+Alternatively, check-python-version looks for TOXENV, which lists names
+of Tox environments (pyXY).
+"""
+
+import ast
+from io import StringIO
+from typing import Optional, Set, cast
+
+import yaml
+
+from .base import Source
+from .tox import parse_envlist, tox_env_to_py_version
+from ..parsers.yaml import update_yaml_list
+from ..utils import FileLines, FileOrFilename, open_file, warn
+from ..versions import SortedVersionList, Version, VersionList
+
+
+APPVEYOR_YML = 'appveyor.yml'
+
+
+def get_appveyor_yml_python_versions(
+    filename: FileOrFilename = APPVEYOR_YML,
+) -> SortedVersionList:
+    """Extract supported Python versions from appveyor.yml."""
+
+    with open_file(filename) as fp:
+        conf = yaml.safe_load(fp)
+    # There's more than one way of doing this, I'm setting %PYTHON% to
+    # the directory that has a Python interpreter (C:\PythonXY)
+    versions = []
+    for env in conf['environment']['matrix']:
+        for var, value in env.items():
+            if var.lower() == 'python':
+                versions.append(appveyor_normalize_py_version(value))
+            elif var == 'TOXENV':
+                toxenvs = parse_envlist(value)
+                versions.extend(
+                    tox_env_to_py_version(e)
+                    for e in toxenvs if e.startswith('py'))
+    # The cast() is a workaround for https://github.com/python/mypy/issues/8526
+    return sorted(cast(Set[Version], set(versions) - {None}))
+
+
+def appveyor_normalize_py_version(ver: str) -> Optional[Version]:
+    """Determine Python version from PYTHON environment variable."""
+    ver = str(ver).lower().replace('\\', '/')
+    if ver.startswith('c:/python'):
+        ver = ver[len('c:/python'):]
+    if ver.endswith('/python.exe'):
+        ver = ver[:-len('/python.exe')]
+    elif ver.endswith('/'):
+        ver = ver[:-1]
+    if ver.endswith('-x64'):
+        ver = ver[:-len('-x64')]
+    if len(ver) >= 2 and ver[:2].isdigit():
+        return Version.from_string(f'{ver[0]}.{ver[1:]}')
+    else:
+        return None
+
+
+def appveyor_detect_py_version_pattern(ver: str) -> Optional[str]:
+    """Determine the format of the PYTHON environment variable.
+
+    Returns a format string suitable for formatting with placeholders
+    for major and minor version numbers.
+    """
+    ver = str(ver)
+    pattern = '{}'
+    for prefix in 'c:\\python', 'c:/python':
+        if ver.lower().startswith(prefix):
+            pos = len(prefix)
+            prefix, ver = ver[:pos], ver[pos:]
+            pattern = pattern.format(f'{prefix}{{}}')
+            break
+    if ver.endswith('\\'):
+        ver = ver[:-1]
+        pattern = pattern.format('{}\\')
+    if ver.lower().endswith('-x64'):
+        pos = -len('-x64')
+        ver, suffix = ver[:pos], ver[pos:]
+        pattern = pattern.format(f'{{}}{suffix}')
+    if len(ver) >= 2 and ver[:2].isdigit():
+        return pattern.format('{}{}')
+    else:
+        return None
+
+
+def escape(s: str) -> str:
+    """Escape a string for embedding inside a double-quoted YAML string."""
+    return s.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def update_appveyor_yml_python_versions(
+    filename: FileOrFilename,
+    new_versions: VersionList,
+) -> Optional[FileLines]:
+    """Update supported Python versions in appveyor.yml.
+
+    Does not touch the file but returns a list of lines with new file contents.
+    """
+    with open_file(filename) as fp:
+        orig_lines = fp.readlines()
+        fp.seek(0)
+        conf = yaml.safe_load(fp)
+
+    varname = 'PYTHON'
+    patterns = set()
+    for env in conf['environment']['matrix']:
+        for var, value in env.items():
+            if var.lower() == 'python':
+                varname = var
+                pattern = appveyor_detect_py_version_pattern(value)
+                if pattern is not None:
+                    patterns.add(pattern)
+                break
+
+    if not patterns:
+        warn(f"Did not recognize any PYTHON environments in {fp.name}")
+        return orig_lines
+
+    quote = any(f'{varname}: "' in line for line in orig_lines)
+
+    new_pythons = [
+        pattern.format(ver.major, ver.minor)
+        for ver in new_versions
+        for pattern in sorted(patterns)
+    ]
+
+    if quote:
+        new_environments = [
+            f'{varname}: "{escape(python)}"'
+            for python in new_pythons
+        ]
+    else:
+        new_environments = [
+            f'{varname}: {python}'
+            for python in new_pythons
+        ]
+
+    def keep_complicated(value: str) -> bool:
+        """Determine if an environment matrix line should be preserved."""
+        if value.lower().startswith('python:'):
+            ver = value.partition(':')[-1].strip()
+            if ver.startswith('"'):
+                ver = ast.literal_eval(ver)
+            nver = appveyor_normalize_py_version(ver)
+            if nver is not None:
+                return False
+        elif value.startswith('{') and value.endswith('}'):
+            env = yaml.safe_load(StringIO(value))
+            for var, value in env.items():
+                if var.lower() == 'python':
+                    nver = appveyor_normalize_py_version(value)
+                    if nver is not None and nver not in new_versions:
+                        return False
+        return True
+
+    new_lines = update_yaml_list(
+        orig_lines, ('environment', 'matrix'), new_environments,
+        keep=keep_complicated, filename=fp.name,
+    )
+    return new_lines
+
+
+Appveyor = Source(
+    filename=APPVEYOR_YML,
+    extract=get_appveyor_yml_python_versions,
+    update=update_appveyor_yml_python_versions,
+    check_pypy_consistency=False,
+    has_upper_bound=True,
+)