stub_uploader

types-cachetools provides static type annotations for the cachetools library, letting mypy, pyright, and other type checkers understand cache decorators and the LRU/LFU/TTL/RR cache classes and their generic key/value types, without shipping any runtime code of its own — the installed package is nothing but .pyi stub files plus a METADATA.toml.

The stubs themselves aren’t authored in this repository; they live in the third-party stubs/cachetools directory of python/typeshed. This repository, typeshed-internal/stub_uploader, is the release-engineering automation that turns that source into the published PyPI distribution: it reads METADATA.toml, computes the next stub version against what’s already on PyPI, builds the wheel and sdist, generates a CHANGELOG.md entry from the typeshed git log, and uploads to PyPI on a daily GitHub Actions schedule (or on demand via a manual workflow).

What You Get

• A fully typed cachetools API — cache classes, decorators, and TTL/LRU/LFU/RR key functions with real generic signatures instead of Any
• Automatic daily publishing — update_stubs.yml rebuilds and uploads any stub package whose typeshed source changed since the last run
• Auto-generated CHANGELOG.md entries — update_changelog.py derives each release’s changelog from the typeshed git log for that stub directory
• Dependency-ordered uploads — metadata.sort_by_dependency topologically sorts distributions so a types-* package only uploads after the types-* packages it depends on
• A manual force-update path — the Force update workflow accepts a distribution-name regex so maintainers can rebuild and re-upload one or many stub packages outside the daily schedule

Common Use Cases

• Adding mypy/pyright coverage to a codebase that calls cachetools, by installing types-cachetools as a dev/type-checking dependency
• CI type-checking pipelines that pin types-cachetools alongside cachetools so builds fail on real type errors instead of silently treating the cache API as untyped
• Typeshed maintainers verifying a stubs/cachetools change gets published, by tracing it through get_changed.py, build_wheel.py, and the CHANGELOG.md entry this repo generates
• Auditing exactly which cachetools stub version was published and when, via data/uploaded_packages.txt and data/changelogs/cachetools.md in this repo

Under The Hood

Architecture The repo is a small procedural pipeline rather than a layered application: upload.py orchestrates build_wheel.py (wheel construction), get_version.py (version arithmetic against what’s already uploaded to PyPI), update_changelog.py (changelog generation from git history), and metadata.py (METADATA.toml parsing plus a topological sort_by_dependency for install order), while ts_data.py reads typeshed’s own per-package requirements data and const.py centralizes shared path and namespace constants. get_changed.py is the sole entry point that decides which distributions changed since data/last_typeshed_commit.sha1, and upload_changed.py / upload_some.py are the two CLI drivers — scheduled diff-based upload versus manual regex-selected force update — that both call into upload.upload(). There’s no database or persistent service; state is two flat files committed back to the repo by the GitHub Action itself, so durability comes from git history rather than infrastructure.

Tech Stack Pure Python 3.13, standard-library heavy (tomllib for METADATA.toml, graphlib.TopologicalSorter for dependency ordering, tarfile, argparse), plus requests for HTTP against PyPI and typeshed, packaging (Requirement/Specifier) for dependency and version-range parsing, build and setuptools>=82.0.1 to construct wheels and sdists, and twine to upload. There’s no web framework, ORM, or database — it’s a build/release tool whose entire deployment surface is GitHub Actions: check.yml runs mypy, pre-commit-configured linters, and pytest on every push; update_stubs.yml runs the daily 02:00 UTC upload; force_update.yml and test_api_token.yml are manual workflow_dispatch triggers for out-of-band re-uploads and PyPI-token validation.

Code Quality tests/ holds genuine unit and integration coverage — test_unit.py exercises strip_types_prefix, compute_stub_version/ensure_specificity version math, and Dependency/Metadata parsing; test_metadata.py and test_integration.py cover dependency validation and changelog parsing end to end — not just smoke tests. The check.yml workflow runs mypy, pytest, and pre-commit linters/formatters on every PR. Code is fully typed (from future import annotations, explicit Optional/LiteralString generics), uses dataclasses and a custom InvalidRequires exception for explicit failure modes rather than swallowed errors, and build_wheel.py in particular carries extensive docstrings explaining wheel-construction intent.

API Design For the end consumer of types-cachetools, the developer experience is close to zero-boilerplate: pip install types-cachetools and mypy/pyright auto-discover the bundled stubs with no import or config changes required. For maintainers of this automation, the surface is a small, well-documented two-command CLI — an automatic diff-based mode and a manual regex-selected force mode — both explained step by step in the README, with argparse-driven entry points and consistent function naming (upload_changed, upload_some, upload_distribution) across the modules.