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

check_python_versions/parsers/poetry_version_spec.py

@@ -0,0 +1,276 @@
+"""
+Tools for manipulating Poetry version constraints.
+
+These are documented at
+https://python-poetry.org/docs/dependency-specification/#version-constraints
+"""
+
+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_poetry_version_constraint(
+    s: str,
+    name: str = "tool.poetry.dependencies.python",
+    *,
+    filename: str = 'pyproject.toml',
+) -> Optional[SortedVersionList]:
+    """Compute Python versions allowed by Poetry version constraints."""
+
+    rx = re.compile(r'^(|[~^]|==|!=|<=|>=|<|>)\s*(\d+(?:\.\d+)*(?:\.\*)?)$')
+
+    class BadConstraint(Exception):
+        """The version clause is ill-formed."""
+
+    #
+    # 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 version check here because if the spec says,
+    # e.g., 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 caret_version(constraint: Constraint) -> CheckFn:
+        """^X.Y allows X.Y.* or X.(Y+n).*; ^X allows X.*."""
+        # Python version never have leading zeroes which allows us to simplify
+        # the spec interpretation -- we know that the first digit is always
+        # non-zero.
+        if constraint[-1] == '*':
+            raise BadConstraint('^ does not allow a .*')
+        return lambda candidate: (
+            candidate >= constraint[:2] and candidate[:1] <= constraint[:1])
+
+    @handler('~')
+    def tilde_version(constraint: Constraint) -> CheckFn:
+        """~X.Y allows X.Y.*; ^X allows X.*."""
+        # Python version never have leading zeroes which allows us to simplify
+        # the spec interpretation -- we know that the first digit is always
+        # non-zero.
+        if constraint[-1] == '*':
+            raise BadConstraint('~ does not allow a .*')
+        elif len(constraint) == 1:
+            return lambda candidate: candidate[:1] == constraint[:2]
+        else:
+            return lambda candidate: candidate == constraint[:2]
+
+    @handler('')
+    def plain_version(constraint: Constraint) -> CheckFn:
+        """Just 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 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
+
+    #
+    # 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 VersionSpecStyle(TypedDict):
+    prefer_caret_tilde: bool
+    comma: str
+    space: str
+
+
+def detect_poetry_version_spec_style(spec: str) -> VersionSpecStyle:
+    """Determine how a python_requires string was formatted.
+
+    The return value is a dict of kwargs that can be splatted
+    into compute_poetry_spec(..., **style).
+    """
+    comma = ', '
+    if ',' in spec and ', ' not in spec:
+        comma = ','
+    space = ''
+    if '> ' in spec or '= ' in spec or '^ ' in spec or '~ ' in spec:
+        space = ' '
+    prefer_caret_tilde = '^' in spec or '~' in spec
+    return dict(
+        comma=comma,
+        space=space,
+        prefer_caret_tilde=prefer_caret_tilde,
+    )
+
+
+def compute_poetry_spec(
+    new_versions: VersionList,
+    *,
+    comma: str = ", ",
+    space: str = "",
+    prefer_caret_tilde: bool = True,
+) -> str:
+    """Compute a constraint 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}:
+        if prefer_caret_tilde:
+            return f'~{space}{new_versions.pop()}'
+        else:
+            return f'{space}{new_versions.pop()}.*'
+    min_version = min(new_versions)
+    max_version = max(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 > max_version:
+                if major == max_version.major:
+                    specifiers.append(f'<{space}{ver}')
+                break
+            if ver >= min_version and ver not in new_versions:
+                specifiers.append(f'!={space}{ver}.*')
+    if len(specifiers) == 1 and prefer_caret_tilde:
+        specifiers = [f'^{space}{min_version}']
+    return comma.join(specifiers)

check_python_versions/parsers/python.py

@@ -0,0 +1,262 @@
+"""
+Tools for manipulating Python files.
+"""
+
+import ast
+import re
+import string
+from typing import List, Optional, Tuple, Union
+
+from ..utils import FileLines, OneOrMore, get_indent, warn
+
+
+AstValue = Union[str, List[str], Tuple[str, ...]]
+
+
+def to_literal(value: str, quote_style: str = '"') -> str:
+    """Convert a string value to a Python 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 \).  Except some
+    # PyPI classifiers do include ' so I need to handle that at least.
+    # And python_requires uses all sorts of comparisons like ~= 3.7.*
+    safe_chars = string.ascii_letters + string.digits + " .:,-=><!~*()/+'#"
+    assert all(
+        c in safe_chars for c in value
+    ), f'{value!r} has unexpected characters'
+    if quote_style == "'" and quote_style in value:
+        quote_style = '"'
+    assert quote_style not in value
+    return f'{quote_style}{value}{quote_style}'
+
+
+def update_call_arg_in_source(
+    source_lines: FileLines,
+    function: OneOrMore[str],
+    keyword: str,
+    new_value: Union[str, List[str]],
+    *,
+    filename: str = 'setup.py',
+) -> FileLines:
+    """Update a function call statement in Python source file.
+
+    Finds the first function all, removes the old value passed to a named
+    keyword argument and replaces it with a new value.
+
+    Tries to preserve existing formatting.
+
+    Returns the updated source.
+    """
+    if isinstance(function, str):
+        function = (function, )
+    lines = iter(enumerate(source_lines))
+    rx = re.compile(fr'^({"|".join(map(re.escape, function))})\s*\(')
+    for n, line in lines:
+        m = rx.match(line)
+        if m:
+            fname = m.group(1)
+            break
+    else:
+        warn(f'Did not find {function[0]}() call in {filename}')
+        return source_lines
+    eq = '='
+    rx = re.compile(
+        f'^(?P<indent>\\s*){re.escape(keyword)}(?P<eq>\\s*=\\s*)(?P<rest>.*)'
+    )
+    for n, line in lines:
+        m = rx.match(line)
+        if m:
+            first_match = m
+            eq = m.group('eq')
+            first_indent = m.group('indent')
+            break
+    else:
+        warn(f'Did not find {keyword}= argument in {fname}() call'
+             f' in {filename}')
+        return source_lines
+
+    quote_style = '"'
+    rest = first_match.group('rest')
+    joined = False
+
+    if isinstance(new_value, list):
+        start = n
+        indent = first_indent + ' ' * 4
+        if rest.startswith('[]'):
+            fix_closing_bracket = True
+            end = n + 1
+        else:
+            must_fix_indents = rest.rstrip() != '['
+            fix_closing_bracket = False
+            for n, line in lines:
+                stripped = line.lstrip()
+                if stripped.startswith(']'):
+                    end = n
+                    break
+                elif stripped:
+                    if not must_fix_indents:
+                        indent = get_indent(line)
+                    if stripped[0] in ('"', "'"):
+                        quote_style = stripped[0]
+                    if line.rstrip().endswith('],'):
+                        end = n + 1
+                        fix_closing_bracket = True
+                        break
+            else:
+                warn(
+                    f'Did not understand {keyword}= formatting'
+                    f' in {fname}() call in {filename}'
+                )
+                return source_lines
+    elif rest.endswith('.join(['):
+        joined = True
+        start = n
+        indent = first_indent + ' ' * 4
+        for n, line in lines:
+            stripped = line.lstrip()
+            if stripped.startswith(']'):
+                end = n + 1
+                fix_closing_bracket = True
+                break
+        else:
+            warn(
+                f'Did not understand {keyword}= formatting'
+                f' in {fname}() call in {filename}'
+            )
+            return source_lines
+    else:
+        start = n
+        end = n + 1
+
+    if isinstance(new_value, list):
+        return source_lines[:start] + [
+            f"{first_indent}{keyword}{eq}[\n"
+        ] + [
+            f"{indent}{to_literal(value, quote_style)},\n"
+            for value in new_value
+        ] + ([
+            f"{first_indent}],\n"
+        ] if fix_closing_bracket else [
+        ]) + source_lines[end:]
+    elif joined:
+        if rest.startswith("'"):
+            quote_style = "'"
+        comma = ', '
+        if comma not in new_value:
+            comma = ','
+        new_value = new_value.split(comma)
+        comma = to_literal(comma, quote_style)
+        return source_lines[:start] + [
+            f"{first_indent}{keyword}{eq}{comma}.join([\n"
+        ] + [
+            f"{indent}{to_literal(value, quote_style)},\n"
+            for value in new_value
+        ] + ([
+            f"{first_indent}]),\n"
+        ] if fix_closing_bracket else [
+        ]) + source_lines[end:]
+    else:
+        if rest.startswith("'"):
+            quote_style = "'"
+        new_value_quoted = to_literal(new_value, quote_style)
+        return source_lines[:start] + [
+            f"{first_indent}{keyword}{eq}{new_value_quoted},\n"
+        ] + source_lines[end:]
+
+
+def find_call_kwarg_in_ast(
+    tree: ast.AST,
+    funcname: OneOrMore[str],
+    keyword: str,
+    *,
+    filename: str,
+) -> Optional[ast.AST]:
+    """Find the value passed to a function call.
+
+    ``filename`` is used for error reporting.
+    """
+    if isinstance(funcname, str):
+        funcname = (funcname, )
+    for node in ast.walk(tree):
+        if (isinstance(node, ast.Call)
+                and any(name_matches(n, node.func) for n in funcname)):
+            for kwarg in node.keywords:
+                if kwarg.arg == keyword:
+                    return kwarg.value
+            else:
+                return None
+    else:
+        warn(f'Could not find {funcname[0]}() call in {filename}')
+        return None
+
+
+def name_matches(funcname: str, node: ast.AST) -> bool:
+    """Check if the AST node refers to a funcion named `funcname`."""
+    while '.' in funcname:
+        funcname, dot, attr = funcname.rpartition('.')
+        if not isinstance(node, ast.Attribute) or node.attr != attr:
+            return False
+        node = node.value
+    return isinstance(node, ast.Name) and node.id == funcname
+
+
+def eval_ast_node(
+    node: ast.AST,
+    keyword: str,
+    *,
+    filename: str = 'setup.py',
+) -> Optional[AstValue]:
+    """Partially evaluate an AST node.
+
+    ``keyword`` is used for error reporting.
+    """
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    if isinstance(node, (ast.List, ast.Tuple)):
+        values: List[str] = []
+        warned = False
+        for element in node.elts:
+            try:
+                value = ast.literal_eval(element)
+                if not isinstance(value, str):
+                    raise ValueError
+            except ValueError:
+                pass
+            else:
+                values.append(value)
+                continue
+            if not warned:
+                warn(f'Non-literal {keyword}= passed to setup() in {filename},'
+                     ' skipping some values')
+                warned = True
+        if warned and not values:
+            # no strings inside!
+            return None
+        if isinstance(node, ast.Tuple):
+            return tuple(values)
+        return values
+    if (isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute)
+            and isinstance(node.func.value, ast.Constant)
+            and isinstance(node.func.value.value, str)
+            and node.func.attr == 'join'):
+        try:
+            return node.func.value.value.join(ast.literal_eval(node.args[0]))
+        except ValueError:
+            pass
+    if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Add):
+        left = eval_ast_node(node.left, keyword, filename=filename)
+        right = eval_ast_node(node.right, keyword, filename=filename)
+        if left is not None and right is not None:
+            if type(left) is not type(right):
+                warn(f'{keyword}= in {filename} is computed by adding'
+                     ' incompatible types:'
+                     f' {type(left).__name__} and {type(right).__name__}')
+                return None
+            # Not sure how to make mypy accept this:
+            # https://github.com/python/mypy/issues/8831
+            return left + right  # type: ignore
+        if left is None and right is not None:
+            return right
+        if left is not None and right is None:
+            return left
+    warn(f'Non-literal {keyword}= passed to setup() in {filename}')
+    return None