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

check_python_versions/utils.py

@@ -0,0 +1,142 @@
+"""
+Assorted utilities that didn't fit elsewhere.
+
+Yes, this is a sign of bad design.  Maybe someday I'll clean it up.
+"""
+
+import difflib
+import logging
+import os
+import stat
+import subprocess
+import sys
+from contextlib import contextmanager
+from typing import (
+    Any,
+    Iterator,
+    List,
+    Sequence,
+    TextIO,
+    Tuple,
+    TypeVar,
+    Union,
+    cast,
+)
+
+
+log = logging.getLogger('check-python-versions')
+
+
+T = TypeVar('T')
+OneOrMore = Union[T, Sequence[T]]
+OneOrTuple = Union[T, Tuple[T, ...]]
+
+
+FileObjectWithName = TextIO  # also has a .name attribute
+FileOrFilename = Union[str, FileObjectWithName]
+FileLines = List[str]
+
+
+def get_indent(line: str) -> str:
+    """Return the indentation part of a line of text."""
+    return line[:-len(line.lstrip())]
+
+
+def warn(msg: str) -> None:
+    """Print a warning to standard error."""
+    print(msg, file=sys.stderr)
+
+
+def is_file_object(filename_or_file_object: FileOrFilename) -> bool:
+    """Is this a file-like object?"""
+    return hasattr(filename_or_file_object, 'read')
+
+
+def file_name(filename_or_file_object: FileOrFilename) -> str:
+    """Return the name of the file."""
+    if is_file_object(filename_or_file_object):
+        return cast(TextIO, filename_or_file_object).name
+    else:
+        return str(filename_or_file_object)
+
+
+@contextmanager
+def open_file(filename_or_file_object: FileOrFilename) -> Iterator[TextIO]:
+    """Context manager for opening files."""
+    if is_file_object(filename_or_file_object):
+        yield cast(TextIO, filename_or_file_object)
+    else:
+        with open(cast(str, filename_or_file_object)) as fp:
+            yield fp
+
+
+def pipe(*cmd: str, **kwargs: Any) -> str:
+    """Run a subprocess and return its standard output.
+
+    Keyword arguments are passed directly to `subprocess.Popen`.
+
+    Standard input and standard error are not redirected.
+    """
+    if 'cwd' in kwargs:
+        log.debug('EXEC cd %s && %s', kwargs['cwd'], ' '.join(cmd))
+    else:
+        log.debug('EXEC %s', ' '.join(cmd))
+    p = subprocess.Popen(cmd, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE,
+                         **kwargs)
+    return cast(bytes, p.communicate()[0]).decode('UTF-8', 'replace')
+
+
+def confirm_and_update_file(filename: str, new_lines: FileLines) -> None:
+    """Update a file with new content, after asking for confirmation."""
+    if (show_diff(filename, new_lines)
+            and confirm(f"Write changes to {filename}?")):
+        mode = stat.S_IMODE(os.stat(filename).st_mode)
+        tempfile = filename + '.tmp'
+        with open(tempfile, 'w') as f:
+            if hasattr(os, 'fchmod'):
+                os.fchmod(f.fileno(), mode)
+            else:  # pragma: windows
+                # Windows, what else?
+                os.chmod(tempfile, mode)
+            f.writelines(new_lines)
+        try:
+            os.rename(tempfile, filename)
+        except FileExistsError:  # pragma: windows
+            # No atomic replace on Windows
+            os.unlink(filename)
+            os.rename(tempfile, filename)
+
+
+def show_diff(
+    filename_or_file_object: FileOrFilename,
+    new_lines: FileLines
+) -> bool:
+    """Show the difference between two versions of a file."""
+    with open_file(filename_or_file_object) as f:
+        old_lines = f.readlines()
+    print_diff(old_lines, new_lines, f.name)
+    return old_lines != new_lines
+
+
+def print_diff(a: List[str], b: List[str], filename: str) -> None:
+    """Show the difference between two versions of a file."""
+    print(''.join(difflib.unified_diff(
+        a, b,
+        filename, filename,
+        "(original)", "(updated)",
+    )))
+
+
+def confirm(prompt: str) -> bool:
+    """Ask the user to confirm an action."""
+    while True:
+        try:
+            answer = input(f'{prompt} [y/N] ').strip().lower()
+        except EOFError:
+            answer = ""
+        if answer == 'y':
+            print()
+            return True
+        if answer == 'n' or not answer:
+            print()
+            return False

check_python_versions/versions.py

@@ -0,0 +1,158 @@
+"""Python version business logic."""
+
+import re
+from typing import Collection, List, NamedTuple, Optional, Set, Union
+
+
+#
+# Information about Python releases that needs to be constantly updated as
+# Python makes new releases.
+#
+
+MAX_PYTHON_1_VERSION = 6  # i.e. 1.6
+MAX_PYTHON_2_VERSION = 7  # i.e. 2.7
+CURRENT_PYTHON_3_VERSION = 14  # i.e. 3.14
+
+MAX_MINOR_FOR_MAJOR = {
+    1: MAX_PYTHON_1_VERSION,
+    2: MAX_PYTHON_2_VERSION,
+    3: CURRENT_PYTHON_3_VERSION,
+}
+
+
+VERSION_RX = re.compile('^([^-0-9]*)([0-9]*)([.][0-9]+)?(.*)$')
+
+
+class Version(NamedTuple):
+    """A simplified Python version number.
+
+    Primarily needed so we can sort lists of version numbers correctly, i.e.
+    2.7, 3.0, 3.1, 3.2, ..., 3.9, 3.10, ...
+
+    Can have an optional prefix, e.g. PyPy3.6 is Version(prefix='PyPy',
+    major=3, minor=6).
+
+    Can have an optional suffix, e.g. 3.10-dev is Version(major=3, minor=10,
+    suffix='-dev').
+
+    Any string can be round-tripped to a Version and back via
+    Version.from_string() and Version.__str__.
+    """
+
+    prefix: str = ''
+    major: int = -1  # I'd've preferred to use None, but it complicates sorting
+    minor: int = -1
+    suffix: str = ''
+
+    @classmethod
+    def from_string(cls, v: str) -> 'Version':
+        m = VERSION_RX.match(v)
+        assert m is not None
+        prefix, major, minor, suffix = m.groups()
+        return cls(
+            prefix,
+            int(major) if major else -1,
+            int(minor[1:]) if minor else -1,
+            suffix,
+        )
+
+    def __repr__(self) -> str:
+        return 'Version({})'.format(', '.join(part for part in [
+            f'prefix={self.prefix!r}' if self.prefix else '',
+            f'major={self.major!r}' if self.major != -1 else '',
+            f'minor={self.minor!r}' if self.minor != -1 else '',
+            f'suffix={self.suffix!r}' if self.suffix else '',
+        ] if part))
+
+    def __str__(self) -> str:
+        major = '' if self.major == -1 else f'{self.major}'
+        minor = '' if self.minor == -1 else f'.{self.minor}'
+        return f'{self.prefix}{major}{minor}{self.suffix}'
+
+
+VersionSet = Set[Version]
+VersionList = Collection[Version]
+SortedVersionList = List[Version]
+
+
+def is_important(v: Union[Version, str]) -> bool:
+    """Is the version important for matching purposes?
+
+    Different sources can express support for different versions, e.g.
+    classifiers can express support for "PyPy" but python_requires can't.
+    Also some CI systems allow testing on unreleased Python versions that
+    cannot be listed in classifiers, so their presence should not cause
+    mismatch errors.
+    """
+    if not isinstance(v, Version):
+        v = Version.from_string(v)
+    upcoming_release = Version(major=3, minor=CURRENT_PYTHON_3_VERSION + 1)
+    return (
+        not v.prefix.startswith(('PyPy', 'Jython')) and v.prefix != 'nightly'
+        and '-dev' not in v.suffix
+        and '-alpha' not in v.suffix
+        and '-beta' not in v.suffix
+        and '-rc' not in v.suffix
+        and v != upcoming_release
+    )
+
+
+def important(versions: Collection[Version]) -> VersionSet:
+    """Filter out unimportant versions.
+
+    See `is_important` for what consitutes "important".
+    """
+    return {
+        v for v in versions
+        if is_important(v)
+    }
+
+
+def pypy_versions(versions: Collection[Version]) -> VersionSet:
+    """Filter PyPy versions."""
+    return {
+        v for v in versions
+        if v.prefix.startswith('PyPy')
+    }
+
+
+def expand_pypy(versions: Collection[Version]) -> SortedVersionList:
+    """Determine whether PyPy support means PyPy2 or PyPy3 or both.
+
+    Some data sources (like setup.py classifiers) allow you to indicate PyPy
+    support without specifying whether you mean PyPy2 or PyPy3.  Other data
+    sources (like all CI systems) are more explicit.  To make these version
+    lists directly comparable we need to look at supported CPython versions and
+    translate that knowledge into PyPy versions.
+    """
+    supports_pypy = any(v.prefix == 'PyPy' for v in versions)
+    if not supports_pypy:
+        return sorted(versions)
+    supports_py2 = any(v.major == 2 for v in versions)
+    supports_py3 = any(v.major == 3 for v in versions)
+    return sorted(
+        [v for v in versions if v.prefix != 'PyPy'] +
+        ([Version.from_string('PyPy')] if supports_py2 else []) +
+        ([Version.from_string('PyPy3')] if supports_py3 else [])
+    )
+
+
+def update_version_list(
+    versions: VersionList,
+    add: Optional[VersionList] = None,
+    drop: Optional[VersionList] = None,
+    update: Optional[VersionList] = None,
+) -> SortedVersionList:
+    """Compute a new list of supported versions.
+
+    ``add`` will add to supported versions.
+    ``drop`` will remove from supported versions.
+    ``update`` will specify supported versions.
+
+    You may combine ``add`` and ``drop``.  It doesn't make sense to combine
+    ``update`` with either ``add`` or ``drop``.
+    """
+    if update:
+        return sorted(update)
+    else:
+        return sorted(set(versions).union(add or ()).difference(drop or ()))