typeshed_stats 22.11.0__py3-none-any.whl

typeshed_stats/__init__.py

@@ -0,0 +1,18 @@
+"""Library and command-line tool for getting stats on various typeshed packages."""
+
+__all__ = [
+    "__title__",
+    "__summary__",
+    "__about__",
+    "__author__",
+    "__email__",
+    "__license__",
+    "__version__",
+]
+
+__title__ = "typeshed-stats"
+__summary__ = __about__ = __doc__
+__author__ = "Alex Waygood"
+__email__ = "alex.waygood@gmail.com"
+__license__ = "MIT"
+__version__ = "22.11.0"

typeshed_stats/__main__.py

@@ -0,0 +1,13 @@
+"""Library and command-line tool for getting stats on various typeshed packages."""
+
+import sys
+
+if sys.version_info < (3, 10):
+    raise ImportError("Python 3.10+ is required!")
+
+__all__: list[str] = []
+
+if __name__ == "__main__":  # pragma: no cover
+    from ._cli import main
+
+    main()

typeshed_stats/_cli.py

@@ -0,0 +1,312 @@
+"""Command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from collections.abc import Callable, Sequence
+from contextlib import ExitStack
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Annotated, Literal, TypeAlias, cast, get_args
+
+from .gather import PackageName, PackageStats, gather_stats, tmpdir_typeshed
+from .serialize import stats_to_csv, stats_to_html, stats_to_json, stats_to_markdown
+
+__all__ = ["OutputOption", "SUPPORTED_EXTENSIONS", "main"]
+
+
+def _format_stats_for_pprinting(
+    stats: Sequence[PackageStats],
+) -> dict[PackageName, PackageStats]:
+    # *Don't* stringify this one
+    # It makes it harder for pprint or rich to format it nicely
+    return {info_bundle.package_name: info_bundle for info_bundle in stats}
+
+
+_CF: TypeAlias = Annotated[
+    Callable[[Sequence[PackageStats]], object],
+    "Function for converting a sequence of PackageStats into a certain format",
+]
+
+
+class OutputOption(Enum):
+    """Enumeration of the different output options on the command line."""
+
+    PPRINT = ".txt", cast(_CF, _format_stats_for_pprinting)
+    JSON = ".json", cast(_CF, stats_to_json)
+    CSV = ".csv", cast(_CF, stats_to_csv)
+    MARKDOWN = ".md", cast(_CF, stats_to_markdown)
+    HTML = ".html", cast(_CF, stats_to_html)
+
+    @property
+    def file_extension(self) -> str:
+        """File extension associated with this file type."""
+        return self.value[0]
+
+    def convert(self, stats: Sequence[PackageStats]) -> object:
+        """Convert a sequence of `PackageStats` objects into the specified format."""
+        converter_function = self.value[1]
+        return converter_function(stats)
+
+    def __repr__(self) -> str:
+        """repr(self)."""
+        return f"OutputOption.{self.name}(extension={self.file_extension!r})"
+
+    @classmethod
+    def from_file_extension(cls, extension: str) -> OutputOption:
+        """Return the enum member associated with a particular file extension."""
+        try:
+            return next(member for member in cls if member.file_extension == extension)
+        except StopIteration:
+            raise ValueError(f"Unsupported file extension {extension!r}") from None
+
+
+SUPPORTED_EXTENSIONS = {option.file_extension for option in OutputOption}
+
+
+def _write_stats(
+    formatted_stats: object, writefile: Path | None, logger: logging.Logger
+) -> None:
+    if writefile is None:
+        pprint: Callable[[object], None]
+        try:
+            from rich import print as pprint  # type: ignore[no-redef]
+        except ImportError:
+            if isinstance(formatted_stats, str):
+                pprint = print
+            else:
+                from pprint import pprint  # type: ignore[no-redef]
+
+        pprint(formatted_stats)
+    else:
+        newline = "" if writefile.suffix == ".csv" else "\n"
+        if not isinstance(formatted_stats, str):
+            formatted_stats = str(formatted_stats)
+        with writefile.open("w", newline=newline, encoding="utf-8") as f:
+            f.write(formatted_stats)
+        logger.info(f'Output successfully written to "{writefile}"!')
+
+
+_LoggingLevels: TypeAlias = Literal[
+    "NOTSET", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"
+]
+
+
+def _get_argument_parser() -> argparse.ArgumentParser:
+    """Parse arguments and do basic argument validation.
+
+    *Don't* do any querying of whether paths actually exist, etc.
+    Leave that to _validate_options().
+    """
+    parser = argparse.ArgumentParser(
+        prog="typeshed-stats", description="Tool to gather stats on typeshed"
+    )
+    parser.add_argument(
+        "packages",
+        type=str,
+        nargs="*",
+        action="extend",
+        help=(
+            "Packages to gather stats on"
+            " (defaults to all third-party packages, plus the stdlib)"
+        ),
+    )
+    parser.add_argument(
+        "--log",
+        choices=get_args(_LoggingLevels),
+        default="INFO",
+        help="Specify the level of logging (defaults to logging.INFO)",
+        dest="logging_level",
+    )
+
+    output_options = parser.add_mutually_exclusive_group()
+    output_options.add_argument(
+        "--pprint",
+        action="store_const",
+        const=OutputOption.PPRINT,
+        dest="output_option",
+        help="Pretty-print Python representations of the data (default output)",
+    )
+    output_options.add_argument(
+        "--to-json",
+        action="store_const",
+        const=OutputOption.JSON,
+        dest="output_option",
+        help="Print output as JSON to the terminal",
+    )
+    output_options.add_argument(
+        "--to-csv",
+        action="store_const",
+        const=OutputOption.CSV,
+        dest="output_option",
+        help="Print output in csv format to the terminal",
+    )
+    output_options.add_argument(
+        "--to-markdown",
+        action="store_const",
+        const=OutputOption.MARKDOWN,
+        dest="output_option",
+        help="Print output as formatted MarkDown to the terminal",
+    )
+    output_options.add_argument(
+        "--to-html",
+        action="store_const",
+        const=OutputOption.HTML,
+        dest="output_option",
+        help="Print output as formatted HTML to the terminal",
+    )
+    output_options.add_argument(
+        "-f",
+        "--to-file",
+        type=Path,
+        help=(
+            "Write output to WRITEFILE instead of printing to the terminal."
+            " The file format will be inferred by the file extension."
+            f" The file extension must be one of {SUPPORTED_EXTENSIONS}."
+        ),
+        dest="writefile",
+    )
+
+    parser.add_argument(
+        "-o",
+        "--overwrite",
+        action="store_true",
+        help=(
+            "Overwrite the path passed to `--file` if it already exists"
+            " (defaults to False)"
+        ),
+    )
+
+    typeshed_options = parser.add_mutually_exclusive_group(required=True)
+    typeshed_options.add_argument(
+        "-t",
+        "--typeshed-dir",
+        type=Path,
+        help="Path to a local clone of typeshed, to be used as the basis for analysis",
+    )
+    typeshed_options.add_argument(
+        "-d",
+        "--download-typeshed",
+        action="store_true",
+        help=(
+            "Download a fresh copy of typeshed into a temporary directory,"
+            " and use that as the basis for analysis"
+        ),
+    )
+
+    return parser
+
+
+# Has to be a dataclass (attrs does class-level defaults differently)
+@dataclass(init=False)
+class _CmdArgs:
+    logging_level: _LoggingLevels
+    packages: list[str]
+    typeshed_dir: Path | None
+    download_typeshed: bool
+    overwrite: bool
+    writefile: Path | None
+    # OutputOption defaults to PPRINT if no argument was specified on the command line
+    output_option: OutputOption = OutputOption.PPRINT
+
+
+def _determine_output_option(
+    args: _CmdArgs, *, parser: argparse.ArgumentParser
+) -> OutputOption:
+    writefile = args.writefile
+    if not writefile:
+        return args.output_option
+    if not writefile.suffix:
+        parser.error(f"{writefile!r} has no file extension!")
+    if writefile.suffix not in SUPPORTED_EXTENSIONS:
+        parser.error(
+            f"Unrecognised file extension {writefile.suffix!r} passed to --file"
+            f" (choose from {SUPPORTED_EXTENSIONS})"
+        )
+    if not (writefile.parent.exists() and writefile.parent.is_dir()):
+        parser.error(
+            f'"{writefile}" is an invalid argument:'
+            f" {writefile.parent} does not exist as a directory!"
+        )
+    if writefile.exists() and not args.overwrite:
+        parser.error(
+            f'"{writefile}" already exists!'
+            "\n(Note: use --overwite"
+            " if your intention was to overwrite an existing file)"
+        )
+    return OutputOption.from_file_extension(writefile.suffix)
+
+
+def _validate_packages(
+    package_names: list[str], typeshed_dir: Path, *, parser: argparse.ArgumentParser
+) -> None:
+    stubs_dir = typeshed_dir / "stubs"
+    for package_name in package_names:
+        if package_name != "stdlib":
+            package_dir = stubs_dir / package_name
+            if not (package_dir.exists() and package_dir.is_dir()):
+                parser.error(f"{package_name!r} does not have stubs in typeshed!")
+
+
+def _validate_typeshed_dir(
+    typeshed_dir: Path, *, parser: argparse.ArgumentParser
+) -> None:
+    for folder in typeshed_dir, (typeshed_dir / "stdlib"), (typeshed_dir / "stubs"):
+        if not (folder.exists() and folder.is_dir()):
+            parser.error(f'"{typeshed_dir}" is not a valid typeshed directory')
+
+
+def _setup_logger(str_level: _LoggingLevels) -> logging.Logger:
+    assert str_level in get_args(_LoggingLevels)
+    logger = logging.getLogger("typeshed_stats")
+    level = getattr(logging, str_level)
+    assert isinstance(level, int)
+    logger.setLevel(level)
+    handler = logging.StreamHandler()
+    handler.setLevel(level)
+    logger.addHandler(handler)
+    return logger
+
+
+def _run(argv: Sequence[str] | None = None) -> None:
+    parser = _get_argument_parser()
+    args: _CmdArgs = parser.parse_args(argv, namespace=_CmdArgs())
+    logger = _setup_logger(args.logging_level)
+
+    with ExitStack() as stack:
+        if args.download_typeshed:
+            logger.info("Cloning typeshed into a temporary directory...")
+            typeshed_dir = stack.enter_context(tmpdir_typeshed())
+        else:
+            assert args.typeshed_dir is not None
+            typeshed_dir = args.typeshed_dir
+            _validate_typeshed_dir(typeshed_dir, parser=parser)
+
+        packages: list[str] | None = args.packages or None
+        if packages:
+            _validate_packages(packages, typeshed_dir, parser=parser)
+
+        output_option = _determine_output_option(args, parser=parser)
+
+        logger.info("Gathering stats...")
+        stats = gather_stats(packages, typeshed_dir=typeshed_dir)
+
+    logger.info("Formatting stats...")
+    formatted_stats = output_option.convert(stats)
+    logger.info("Writing stats...")
+    _write_stats(formatted_stats, args.writefile, logger)
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """CLI entry point."""
+    try:
+        _run(argv)
+    except KeyboardInterrupt:
+        sys.stderr.write("Interrupted!")
+        code = 2
+    else:
+        code = 0
+    raise SystemExit(code)

typeshed_stats/gather.py

@@ -0,0 +1,583 @@
+"""Tools for gathering stats about typeshed packages."""
+
+import ast
+import asyncio
+import json
+import os
+import re
+import sys
+import urllib.parse
+from collections import Counter
+from collections.abc import Iterable, Iterator, Mapping, Sequence
+from contextlib import AsyncExitStack, contextmanager
+from enum import Enum
+from functools import cache
+from pathlib import Path
+from typing import Any, Protocol, TypeAlias, TypeVar, final
+
+import aiohttp
+import attrs
+from packaging.specifiers import SpecifierSet
+from packaging.version import Version
+
+if sys.version_info < (3, 10):
+    raise ImportError("Python 3.10+ is required!")
+
+if sys.version_info >= (3, 11):
+    import tomllib  # pragma: no cover
+else:
+    import tomli as tomllib  # pragma: no cover
+
+
+__all__ = [
+    "AnnotationStats",
+    "PackageName",
+    "PackageStats",
+    "PackageStatus",
+    "PyrightSetting",
+    "StubtestSetting",
+    "gather_annotation_stats_on_file",
+    "gather_annotation_stats_on_package",
+    "gather_stats",
+    "gather_stats_on_package",
+    "get_package_size",
+    "get_package_status",
+    "get_pyright_strictness",
+    "get_stubtest_setting",
+]
+
+PackageName: TypeAlias = str
+_NiceReprEnumSelf = TypeVar("_NiceReprEnumSelf", bound="_NiceReprEnum")
+
+
+class _NiceReprEnum(Enum):
+    """Base class for several public-API enums in this package."""
+
+    def __new__(cls: type[_NiceReprEnumSelf], doc: str) -> _NiceReprEnumSelf:
+        assert isinstance(doc, str)
+        member = object.__new__(cls)
+        member._value_ = member.__doc__ = doc
+        return member
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}.{self.name}"
+
+    @property
+    def formatted_name(self) -> str:
+        return " ".join(self.name.split("_")).lower()
+
+
+@attrs.define
+class _SingleAnnotationAnalyzer(ast.NodeVisitor):
+    Any_in_annotation: bool = False
+    Incomplete_in_annotation: bool = False
+
+    def visit_Name(self, node: ast.Name) -> None:
+        match node.id:
+            case "Any":
+                self.Any_in_annotation = True
+            case "Incomplete":
+                self.Incomplete_in_annotation = True
+            case _:
+                pass
+
+    def visit_Attribute(self, node: ast.Attribute) -> None:
+        match node.value, node.attr:
+            case [ast.Name("typing"), "Any"]:
+                self.Any_in_annotation = True
+            case [ast.Name("_typeshed"), "Incomplete"]:
+                self.Incomplete_in_annotation = True
+            case _:
+                pass
+        self.generic_visit(node)
+
+
+class _SingleAnnotationAnalysis(Protocol):
+    Any_in_annotation: bool
+    Incomplete_in_annotation: bool
+
+
+def _analyse_annotation(annotation: ast.AST) -> _SingleAnnotationAnalysis:
+    analyser = _SingleAnnotationAnalyzer()
+    analyser.visit(annotation)
+    return analyser
+
+
+@final
+@attrs.define
+class AnnotationStats:
+    """Stats on the annotations for a source file or a directory of source files."""
+
+    annotated_parameters: int = 0
+    unannotated_parameters: int = 0
+    annotated_returns: int = 0
+    unannotated_returns: int = 0
+    explicit_Incomplete_parameters: int = 0
+    explicit_Incomplete_returns: int = 0
+    explicit_Any_parameters: int = 0
+    explicit_Any_returns: int = 0
+    annotated_variables: int = 0
+    explicit_Any_variables: int = 0
+    explicit_Incomplete_variables: int = 0
+
+
+class _AnnotationStatsCollector(ast.NodeVisitor):
+    """AST Visitor for collecting stats on a single stub file."""
+
+    def __init__(self) -> None:
+        self.stats = AnnotationStats()
+        self._class_nesting = 0
+        self._function_decorators: frozenset[str] = frozenset()
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(stats={self.stats})"
+
+    @property
+    def in_class(self) -> bool:
+        """Return `True` if we're currently visiting a class definition."""
+        return bool(self._class_nesting)
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        self._class_nesting += 1
+        self.generic_visit(node)
+        self._class_nesting -= 1
+
+    def visit_AnnAssign(self, node: ast.AnnAssign) -> None:
+        self.stats.annotated_variables += 1
+        analysis = _analyse_annotation(node.annotation)
+        if analysis.Any_in_annotation:
+            self.stats.explicit_Any_variables += 1
+        if analysis.Incomplete_in_annotation:
+            self.stats.explicit_Incomplete_variables += 1
+        self.generic_visit(node)
+
+    def visit_arg(self, node: ast.arg) -> None:
+        self.generic_visit(node)
+
+        # We don't want self/cls/metacls/mcls arguments to count towards the statistics
+        if self.in_class and "staticmethod" not in self._function_decorators:
+            if "classmethod" in self._function_decorators:
+                if node.arg in {"cls", "metacls", "mcls"}:
+                    return
+            elif node.arg == "self":
+                return
+
+        annotation = node.annotation
+        if annotation is None:
+            self.stats.unannotated_parameters += 1
+        else:
+            self.stats.annotated_parameters += 1
+            analysis = _analyse_annotation(annotation)
+            if analysis.Any_in_annotation:
+                self.stats.explicit_Any_parameters += 1
+            if analysis.Incomplete_in_annotation:
+                self.stats.explicit_Incomplete_parameters += 1
+
+    def _visit_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        returns = node.returns
+        if returns is None:
+            self.stats.unannotated_returns += 1
+        else:
+            self.stats.annotated_returns += 1
+            analysis = _analyse_annotation(returns)
+            if analysis.Any_in_annotation:
+                self.stats.explicit_Any_returns += 1
+            if analysis.Incomplete_in_annotation:
+                self.stats.explicit_Incomplete_returns += 1
+
+        old_function_decorators = self._function_decorators
+        self._function_decorators = frozenset(
+            decorator.id
+            for decorator in node.decorator_list
+            if isinstance(decorator, ast.Name)
+        )
+        self.generic_visit(node)
+        self._function_decorators = old_function_decorators
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self._visit_function(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self._visit_function(node)
+
+
+def gather_annotation_stats_on_file(path: Path | str) -> AnnotationStats:
+    """Gather annotation stats on a single typeshed stub file.
+
+    Args:
+        path: The location of the file to be analysed.
+
+    Returns:
+        An `AnnotationStats` object containing data
+        about the annotations in the file.
+    """
+    visitor = _AnnotationStatsCollector()
+    with open(path, encoding="utf-8") as file:
+        visitor.visit(ast.parse(file.read()))
+    return visitor.stats
+
+
+@cache
+def _get_package_directory(package_name: PackageName, typeshed_dir: Path | str) -> Path:
+    if package_name == "stdlib":
+        return Path(typeshed_dir, "stdlib")
+    return Path(typeshed_dir, "stubs", package_name)
+
+
+def gather_annotation_stats_on_package(
+    package_name: PackageName, *, typeshed_dir: Path | str
+) -> AnnotationStats:
+    """Aggregate annotation stats on a typeshed stubs package.
+
+    Args:
+        package_name: The name of the stubs package to analyze.
+        typeshed_dir: A path pointing to the location of a typeshed directory
+          in which to find the stubs package source.
+
+    Returns:
+        An `AnnotationStats` object containing data
+        about the annotations in the package.
+    """
+    package_directory = _get_package_directory(package_name, typeshed_dir)
+    file_results = [
+        gather_annotation_stats_on_file(path)
+        for path in package_directory.rglob("*.pyi")
+    ]
+    # Sum all the statistics together, to get the statistics for the package as a whole
+    #
+    # TODO: we're throwing away information here.
+    # It might be nice to have a way to get per-file stats, especially for the stdlib.
+    package_stats: Counter[str] = sum(
+        [Counter(attrs.asdict(result)) for result in file_results], start=Counter()
+    )
+    return AnnotationStats(**package_stats)
+
+
+@cache
+def _get_package_metadata(
+    package_name: PackageName, typeshed_dir: Path | str
+) -> Mapping[str, Any]:
+    package_directory = _get_package_directory(package_name, typeshed_dir)
+    with open(package_directory / "METADATA.toml", "rb") as f:
+        return tomllib.load(f)
+
+
+class StubtestSetting(_NiceReprEnum):
+    """Enumeration of the various possible settings typeshed uses for stubtest in CI."""
+
+    SKIPPED = "Stubtest is skipped in CI for this package."
+    MISSING_STUBS_IGNORED = (
+        "The `--ignore-missing-stub` stubtest setting is used in CI."
+    )
+    ERROR_ON_MISSING_STUB = (
+        "Objects missing from the stub cause stubtest to emit an error in CI."
+    )
+
+
+def get_stubtest_setting(
+    package_name: str, *, typeshed_dir: Path | str
+) -> StubtestSetting:
+    """Get the setting typeshed uses in CI when stubtest is run on a certain package.
+
+    Args:
+        package_name: The name of the package to find the stubtest setting for.
+        typeshed_dir: A path pointing to a typeshed directory,
+          from which to retrieve the stubtest setting.
+
+    Returns:
+        A member of the `StubtestSetting` enumeration
+        (see the docs on `StubtestSetting` for details).
+    """
+    if package_name == "stdlib":
+        return StubtestSetting.ERROR_ON_MISSING_STUB
+    metadata = _get_package_metadata(package_name, typeshed_dir)
+    stubtest_settings = metadata.get("tool", {}).get("stubtest", {})
+    if stubtest_settings.get("skip", False):
+        return StubtestSetting.SKIPPED
+    ignore_missing_stub_used = stubtest_settings.get("ignore_missing_stub", True)
+    return StubtestSetting[
+        "MISSING_STUBS_IGNORED" if ignore_missing_stub_used else "ERROR_ON_MISSING_STUB"
+    ]
+
+
+class PackageStatus(_NiceReprEnum):
+    """The various states of freshness/staleness a stubs package can be in."""
+
+    STDLIB = (
+        "These are the stdlib stubs. Typeshed's stdlib stubs are generally fairly"
+        " up to date, and tested against all currently supported Python versions"
+        " in CI."
+    )
+    NOT_ON_PYPI = (
+        "The upstream for this package doesn't exist on PyPI,"
+        " so whether or not these stubs are up to date or not is unknown."
+    )
+    OBSOLETE = "Upstream has added type hints; these typeshed stubs are now obsolete."
+    NO_LONGER_UPDATED = (
+        "Upstream has not added type hints,"
+        " but these stubs are no longer updated for some other reason."
+    )
+    OUT_OF_DATE = (
+        "These stubs are out of date. In CI, stubtest tests these stubs against an"
+        " older version of this package than the latest that's available."
+    )
+    UP_TO_DATE = (
+        "These stubs should be fairly up to date. In CI, stubtest tests these stubs"
+        " against the latest version of the package that's available."
+    )
+
+
+async def _get_pypi_data(
+    package_name: str, session: aiohttp.ClientSession | None
+) -> dict[str, Any]:
+    pypi_data_url = f"https://pypi.org/pypi/{urllib.parse.quote(package_name)}/json"
+    async with AsyncExitStack() as stack:
+        if session is None:
+            # see https://github.com/python/mypy/issues/13936
+            # for why we need the tmp_var to keep mypy happy
+            tmp_var = await stack.enter_async_context(aiohttp.ClientSession())
+            session = tmp_var
+        async with session.get(pypi_data_url) as response:
+            response.raise_for_status()
+            response_json = await response.json()
+    assert isinstance(response_json, dict)
+    return response_json
+
+
+async def get_package_status(
+    package_name: str,
+    *,
+    typeshed_dir: Path | str,
+    session: aiohttp.ClientSession | None = None,
+) -> PackageStatus:
+    """Retrieve information on how up to date a stubs package is.
+
+    If stubtest tests these stubs against the latest version of the runtime
+    in typeshed's CI, it's a fair bet that the stubs are relatively up to date.
+    If stubtest tests these stubs against an older version, however,
+    the stubs may be out of date.
+
+    This function makes network requests to PyPI in order to determine what the
+    latest version of the runtime is, and then compares this against
+    the metadata of the stubs package.
+
+    Args:
+        package_name: The name of the stubs package to analyze.
+        typeshed_dir: A path pointing to a typeshed directory
+          in which to find the stubs package.
+        session (optional): An `aiohttp.ClientSession` instance, to be used
+          for making a network requests, or `None`. If `None` is provided
+          for this argument, a new `aiohttp.ClientSession` instance will be
+          created to make the network request.
+
+    Returns:
+        A member of the `PackageStatus` enumeration
+        (see the docs on `PackageStatus` for details).
+    """
+    if package_name == "stdlib":
+        # This function isn't really relevant for the stdlib stubs
+        return PackageStatus.STDLIB
+
+    if package_name == "gdb":
+        return PackageStatus.NOT_ON_PYPI
+
+    metadata = _get_package_metadata(package_name, typeshed_dir)
+
+    if "obsolete_since" in metadata:
+        return PackageStatus.OBSOLETE
+
+    if metadata.get("no_longer_updated", False):
+        return PackageStatus.NO_LONGER_UPDATED
+
+    typeshed_pinned_version = SpecifierSet(f"=={metadata['version']}")
+    pypi_data = await _get_pypi_data(package_name, session)
+    pypi_version = Version(pypi_data["info"]["version"])
+    status = "UP_TO_DATE" if pypi_version in typeshed_pinned_version else "OUT_OF_DATE"
+    return PackageStatus[status]
+
+
+def get_package_size(package_name: str, *, typeshed_dir: Path | str) -> int:
+    """Get the total number of lines of code for a stubs package in typeshed.
+
+    Args:
+        package_name: The name of the stubs package to find the line number for.
+        typeshed_dir: A path pointing to a typeshed directory
+          in which to find the stubs package.
+
+    Returns:
+        The number of lines of code the stubs package contains.
+    """
+    return sum(
+        len(stub.read_text(encoding="utf-8").splitlines())
+        for stub in _get_package_directory(package_name, typeshed_dir).rglob("*.pyi")
+    )
+
+
+@cache
+def _get_pyright_strict_excludelist(typeshed_dir: Path | str) -> frozenset[Path]:
+    # Read pyrightconfig.stricter.json;
+    # do some pre-processing so that it can be passed to json.loads()
+    config_path = Path(typeshed_dir, "pyrightconfig.stricter.json")
+    with config_path.open(encoding="utf-8") as file:
+        # strip comments from the file
+        lines = [line for line in file if not line.strip().startswith("//")]
+    # strip trailing commas from the file
+    valid_json = re.sub(r",(\s*?[\}\]])", r"\1", "\n".join(lines))
+    pyright_config = json.loads(valid_json)
+    assert isinstance(pyright_config, dict)
+    excludelist = pyright_config.get("exclude", [])
+    return frozenset(Path(typeshed_dir, item) for item in excludelist)
+
+
+class PyrightSetting(_NiceReprEnum):
+    """The various possible pyright settings typeshed uses in CI."""
+
+    STRICT = "All files are tested with the stricter pyright settings in CI."
+    NOT_STRICT = "All files are excluded from the stricter pyright settings in CI."
+    STRICT_ON_SOME_FILES = (
+        "Some files are tested with the stricter pyright settings in CI;"
+        " some are excluded."
+    )
+
+
+def get_pyright_strictness(
+    package_name: PackageName, *, typeshed_dir: Path | str
+) -> PyrightSetting:
+    """Get the setting typeshed uses in CI when pyright is run on a certain package.
+
+    Args:
+        package_name: The name of the package to find the stubtest setting for.
+        typeshed_dir: A path pointing to a typeshed directory,
+          from which to retrieve the stubtest setting.
+
+    Returns:
+        A member of the `PyrightSetting` enumeration
+        (see the docs on `PyrightSetting` for details).
+    """
+    package_directory = _get_package_directory(package_name, typeshed_dir)
+    excluded_paths = _get_pyright_strict_excludelist(typeshed_dir)
+    if package_directory in excluded_paths:
+        return PyrightSetting.NOT_STRICT
+    if any(
+        excluded_path in package_directory.parents for excluded_path in excluded_paths
+    ):
+        return PyrightSetting.NOT_STRICT
+    if any(
+        package_directory in excluded_path.parents for excluded_path in excluded_paths
+    ):
+        return PyrightSetting.STRICT_ON_SOME_FILES
+    return PyrightSetting.STRICT
+
+
+@final
+@attrs.define
+class PackageStats:
+    """Statistics about a single stubs package in typeshed."""
+
+    package_name: PackageName
+    number_of_lines: int
+    package_status: PackageStatus
+    stubtest_setting: StubtestSetting
+    pyright_setting: PyrightSetting
+    annotation_stats: AnnotationStats
+
+
+async def gather_stats_on_package(
+    package_name: PackageName,
+    *,
+    typeshed_dir: Path | str,
+    session: aiohttp.ClientSession | None = None,
+) -> PackageStats:
+    """Gather miscellaneous statistics about a single stubs package in typeshed.
+
+    This function calls `get_package_status()`,
+    which makes network requests to PyPI.
+    See the docs on `get_package_status()` for details.
+
+    Args:
+        package_name: The name of the package to gather statistics on.
+        typeshed_dir: A path pointing to a typeshed directory,
+          in which the source code for the stubs package can be found.
+        session (optional): An `aiohttp.ClientSession` instance, to be used
+          for making a network requests, or `None`. If `None` is provided
+          for this argument, a new `aiohttp.ClientSession` instance will be
+          created to make the network request.
+
+    Returns:
+        An instance of the `PackageStats` class.
+    """
+    return PackageStats(
+        package_name=package_name,
+        number_of_lines=get_package_size(package_name, typeshed_dir=typeshed_dir),
+        package_status=await get_package_status(
+            package_name, typeshed_dir=typeshed_dir, session=session
+        ),
+        stubtest_setting=get_stubtest_setting(package_name, typeshed_dir=typeshed_dir),
+        pyright_setting=get_pyright_strictness(package_name, typeshed_dir=typeshed_dir),
+        annotation_stats=gather_annotation_stats_on_package(
+            package_name, typeshed_dir=typeshed_dir
+        ),
+    )
+
+
+async def _gather_stats(
+    packages: Iterable[str], *, typeshed_dir: Path | str
+) -> Sequence[PackageStats]:
+    conn = aiohttp.TCPConnector(limit_per_host=10)
+    async with aiohttp.ClientSession(connector=conn) as session:
+        tasks = (
+            gather_stats_on_package(
+                package_name, typeshed_dir=typeshed_dir, session=session
+            )
+            for package_name in packages
+        )
+        return await asyncio.gather(*tasks, return_exceptions=True)
+
+
+def gather_stats(
+    packages: Iterable[str] | None = None, *, typeshed_dir: Path | str
+) -> Sequence[PackageStats]:
+    """Concurrently gather statistics on multiple packages.
+
+    Note: this function calls `asyncio.run()` to start an asyncio event loop.
+    It is therefore not suitable to be called from inside functions
+    that are themselves called as part of an asyncio event loop.
+
+    Args:
+        packages: An iterable of package names to be analysed, or None.
+          If `None`, defaults to all third-party stubs, plus the stubs for the stdlib.
+        typeshed_dir: The path to a local clone of typeshed.
+
+    Returns:
+        A sequence of `PackageStats` objects. Each `PackageStats` object
+        contains information representing an analysis of a certain stubs package
+        in typeshed.
+    """
+    if packages is None:
+        packages = os.listdir(Path(typeshed_dir, "stubs")) + ["stdlib"]
+    results = asyncio.run(_gather_stats(packages, typeshed_dir=typeshed_dir))
+    for result in results:
+        if isinstance(result, BaseException):
+            raise result
+    return results
+
+
+@contextmanager
+def tmpdir_typeshed() -> Iterator[Path]:
+    """Context manager to clone typeshed into a tempdir, and then yield the tempdir."""
+    import subprocess
+    from tempfile import TemporaryDirectory
+
+    args = [
+        "git",
+        "clone",
+        "https://github.com/python/typeshed",
+        "--depth",
+        "1",
+        "--quiet",
+    ]
+
+    with TemporaryDirectory() as td:
+        args.append(td)
+        subprocess.run(args, check=True)
+        yield Path(td)

typeshed_stats/serialize.py

@@ -0,0 +1,138 @@
+"""Tools for serializing and deserializing `PackageStats` objects."""
+
+from collections.abc import Sequence
+from functools import cache
+from operator import attrgetter
+
+import attrs
+import cattrs
+
+from typeshed_stats.gather import AnnotationStats, PackageStats, _NiceReprEnum
+
+__all__ = [
+    "stats_from_csv",
+    "stats_from_json",
+    "stats_to_csv",
+    "stats_to_html",
+    "stats_to_json",
+    "stats_to_markdown",
+]
+
+_CATTRS_CONVERTER = cattrs.Converter()
+_unstructure = _CATTRS_CONVERTER.unstructure
+_structure = _CATTRS_CONVERTER.structure
+
+_CATTRS_CONVERTER.register_unstructure_hook(_NiceReprEnum, attrgetter("name"))
+_CATTRS_CONVERTER.register_structure_hook(_NiceReprEnum, lambda d, t: t[d])  # type: ignore[index,no-any-return]
+
+
+def stats_to_json(stats: Sequence[PackageStats]) -> str:
+    """Convert stats on multiple stubs packages to JSON format."""
+    import json
+
+    return json.dumps(_unstructure(stats), indent=2)
+
+
+def stats_from_json(data: str) -> list[PackageStats]:
+    """Load `PackageStats` objects from JSON format."""
+    import json
+
+    return _structure(json.loads(data), list[PackageStats])
+
+
+def stats_to_csv(stats: Sequence[PackageStats]) -> str:
+    """Convert stats on multiple stubs packages to csv format."""
+    import csv
+    import io
+
+    converted_stats = _unstructure(stats)
+    for info in converted_stats:
+        info |= info["annotation_stats"]
+        del info["annotation_stats"]
+    fieldnames = converted_stats[0].keys()
+    csvfile = io.StringIO(newline="")
+    writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
+    writer.writeheader()
+    for info in converted_stats:
+        writer.writerow(info)
+    return csvfile.getvalue()
+
+
+@cache
+def _annotation_stats_fields() -> tuple[str, ...]:
+    return tuple(f.name for f in attrs.fields(AnnotationStats))
+
+
+def stats_from_csv(data: str) -> list[PackageStats]:
+    """Load `PackageStats` objects from csv format."""
+    import csv
+    import io
+
+    csvfile = io.StringIO(data, newline="")
+    stats = list(csv.DictReader(csvfile))
+    annotation_stats_fields = _annotation_stats_fields()
+    converted_stats = []
+    for stat in stats:
+        converted_stat, annotation_stats = {}, {}
+        for key, val in stat.items():
+            if key in annotation_stats_fields:
+                annotation_stats[key] = val
+            else:
+                converted_stat[key] = val
+        converted_stat["annotation_stats"] = annotation_stats
+        converted_stats.append(converted_stat)
+    return _structure(converted_stats, list[PackageStats])
+
+
+def stats_to_markdown(stats: Sequence[PackageStats]) -> str:
+    """Generate MarkDown describing statistics on multiple stubs packages."""
+    import textwrap
+
+    template = textwrap.dedent(
+        """
+        ## Stats on typeshed's stubs for `{package_name}`
+
+        ### Number of lines
+        {number_of_lines}
+
+        ### Package status: *{package_status.formatted_name}*
+        {package_status.value}
+
+        ### Stubtest settings in CI: *{stubtest_setting.formatted_name}*
+        {stubtest_setting.value}
+
+        ### Pyright settings in CI: *{pyright_setting.formatted_name}*
+        {pyright_setting.value}
+
+        ### Statistics on the annotations in typeshed's stubs for `{package_name}`
+        - Parameters (excluding `self`, `cls`, `metacls` and `mcls`):
+            - Annotated parameters: {annotated_parameters}
+            - Unannotated parameters: {unannotated_parameters}
+            - Explicit `Any` parameters: {explicit_Any_parameters}
+            - Explicitly `Incomplete` (or partially `Incomplete`) parameters: {explicit_Incomplete_parameters}
+        - Returns:
+            - Annotated returns: {annotated_returns}
+            - Unannotated returns: {unannotated_returns}
+            - Explicit `Any` returns: {explicit_Any_returns}
+            - Explicitly `Incomplete` (or partially `Incomplete`) returns: {explicit_Incomplete_returns}
+        - Variables:
+            - Annotated variables: {annotated_variables}
+            - Explicit `Any` variables: {explicit_Any_variables}
+            - Explicitly `Incomplete` (or partially `Incomplete`) variables: {explicit_Incomplete_variables}
+        """
+    )
+
+    def format_package(package_stats: PackageStats) -> str:
+        package_as_dict = attrs.asdict(package_stats)
+        kwargs = package_as_dict | package_as_dict["annotation_stats"]
+        del kwargs["annotation_stats"]
+        return template.format(**kwargs)
+
+    return "\n<hr>\n".join(format_package(info) for info in stats)
+
+
+def stats_to_html(stats: Sequence[PackageStats]) -> str:
+    """Generate HTML describing statistics on multiple stubs packages."""
+    import markdown
+
+    return markdown.markdown(stats_to_markdown(stats))

typeshed_stats-22.11.0.dist-info/METADATA

@@ -0,0 +1,81 @@
+Metadata-Version: 2.1
+Name: typeshed_stats
+Version: 22.11.0
+Summary: Script to gather stats on the status of various typeshed packages
+Project-URL: Homepage, https://github.com/AlexWaygood/typeshed-stats
+Project-URL: Bug Tracker, https://github.com/AlexWaygood/typeshed-stats/issues
+Author-email: Alex Waygood <alex.waygood@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: stubs,typeshed,typing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: aiohttp[speedups]
+Requires-Dist: attrs>=21.3.0
+Requires-Dist: cattrs
+Requires-Dist: packaging
+Requires-Dist: tomli; python_version < '3.11'
+Provides-Extra: everything
+Requires-Dist: markdown; extra == 'everything'
+Requires-Dist: rich; extra == 'everything'
+Provides-Extra: html
+Requires-Dist: markdown; extra == 'html'
+Provides-Extra: rich
+Requires-Dist: rich; extra == 'rich'
+Description-Content-Type: text/markdown
+
+<div align=center>
+
+# typeshed-stats
+
+A CLI tool and library to gather stats on typeshed
+
+[![website](https://img.shields.io/website?down_color=red&down_message=Offline&style=for-the-badge&up_color=green&up_message=Running&url=https%3A%2F%2Falexwaygood.github.io%2Ftypeshed-stats%2F)](https://alexwaygood.github.io/typeshed-stats/)[![build status](https://img.shields.io/github/workflow/status/AlexWaygood/typeshed-stats/tests/main?label=Tests&style=for-the-badge)](https://github.com/AlexWaygood/typeshed-stats/actions/workflows/check.yml)[![Coveralls](https://img.shields.io/coveralls/github/AlexWaygood/typeshed-stats?style=for-the-badge)](https://coveralls.io/github/AlexWaygood/typeshed-stats)
+<br>
+[![Checked with mypy](https://img.shields.io/badge/mypy-checked-blue?style=for-the-badge)](http://mypy-lang.org/)[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge)](https://github.com/psf/black)[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=for-the-badge&labelColor=ef8336)](https://pycqa.github.io/isort/)[![license](https://img.shields.io/github/license/AlexWaygood/typeshed-stats?style=for-the-badge)](https://opensource.org/licenses/MIT)
+
+<hr>
+<br>
+</div>
+
+## What's this project for?
+
+This project is for easy gathering of statistics relating to typeshed's stubs.
+
+Some examples of things you can do from the command line:
+- Create a `.csv` file with stats on all typeshed stubs: `typeshed-stats --typeshed-dir <PATH_TO_TYPESHED_CLONE> --to-file stats.csv` (the `.csv` file extension will be automatically detected by the script to identify the format required).
+- Pretty-print stats on typeshed stubs for emoji and redis to the terminal, in JSON format: `typeshed-stats --typeshed-dir <PATH_TO_TYPESHED_CLONE> --to-json emoji redis`
+- Generate a MarkDown file detailing stats on typeshed's stubs for protobuf and the stdlib: `typeshed-stats --typeshed-dir <PATH_TO_TYPESHED_CLONE> --to-file stats.md stdlib protobuf`
+
+Example usage of the Python-level API:
+```python
+from typeshed_stats.gather import tmpdir_typeshed, gather_stats
+
+with tmpdir_typeshed() as typeshed:
+    stats = gather_stats(typeshed_dir=typeshed)
+```
+
+## How can I use this?
+
+1. Run `pip install git+https://github.com/AlexWaygood/typeshed-stats.git#egg=typeshed-stats[everything]` to install the package
+2. Run `typeshed-stats --help` for information about various options
+
+## Are there any examples of things this script can produce?
+I'm glad you asked! They're in the `examples/` folder in this repo.
+(These examples are generated using the `regenerate_examples.py` script in the repository root.)
+
+## How do I run tests/linters?
+1. Clone the repo and `cd` into it
+2. Create and activate a virtual environment
+3. Run `pip install -r requirements-dev.txt`
+4. Run `pip install -e .[everything]`
+5. Either run the linters/tests individually (see the `.github/workflows` directory for details about what's run in CI) or use the `runtests.py` convenience script to run them all in succession.

typeshed_stats-22.11.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+typeshed_stats/__init__.py,sha256=fqeGnjOfi2-Es1ELyM48ionTOBYX2dGySLyaOI5-XEc,398
+typeshed_stats/__main__.py,sha256=4EiLdxGt9zGsjMqqD0fu33kC4DtkGmH7wqQu8HMKwYE,291
+typeshed_stats/_cli.py,sha256=iiNYpQzZiE5d-hSYnnawI0ST_dJOeCcA136kSGuUhN8,10305
+typeshed_stats/gather.py,sha256=niv6E14BjWDO4MjIBEGn4aMpMj0395fT8K1BmgzYqRU,20599
+typeshed_stats/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+typeshed_stats/serialize.py,sha256=FYSVamxt2PoiMjnOgEeMq336bM3bQqBKWjeCY6rvop8,4741
+typeshed_stats-22.11.0.dist-info/METADATA,sha256=3r1WAZKYpdZO7T1rBfH9Xy5l7YPpevhk4OmBAHc-dlY,4371
+typeshed_stats-22.11.0.dist-info/WHEEL,sha256=NaLmgHHW_f9jTvv_wRh9vcK7c7EK9o5fwsIXMOzoGgM,87
+typeshed_stats-22.11.0.dist-info/entry_points.txt,sha256=wzOEKjVv36kiGkT1qzSjE_RV0F9pn7MT33KwCoM7Pvo,60
+typeshed_stats-22.11.0.dist-info/licenses/LICENSE,sha256=2bm9uFabQZ3Ykb_SaSU_uUbAj2-htc6WJQmS_65qD00,1073
+typeshed_stats-22.11.0.dist-info/RECORD,,

typeshed_stats-22.11.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.11.1
+Root-Is-Purelib: true
+Tag: py3-none-any

typeshed_stats-22.11.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+typeshed-stats = typeshed_stats._cli:main

typeshed_stats-22.11.0.dist-info/licenses/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2018 The Python Packaging Authority
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.