Anvil Python typing packs

Maintainer reference for the curated third-party typing data used by Anvil's server analysis. The npm package supplies static declaration maps and a manifest. It has no dependency on a particular Python checker and does not install Python libraries. Anvil's own API declarations remain in the Anvil repository.

The S3 delivery proposal describes a future hosting and publishing path, including the administrator work required. It does not change the current NumPy/pandas packaging or IDE integration.

Build and package

Use pnpm and Python 3.12 or later:

pnpm install --frozen-lockfile
pnpm build
pnpm test
pnpm pack --pack-destination .packages

pnpm build recreates dist/. It downloads the pinned wheels as ZIP archives, verifies their SHA-256 checksums, and extracts declarations without importing or executing their code. Verified downloads are cached under .cache/wheels/. Subsequent builds can use that cache offline. Both the cache and generated output are ignored by Git. The published package includes dist/ and third-party notices; consumers need neither Python nor the wheel downloads.

pnpm pack runs the build first. The tests install the resulting tarball into a clean consumer, verify the declaration contents and licence texts, and reject a modified wheel cache. CI uploads the installable tarball without publishing it.

Catalogue

catalogue.json owns the inputs:

• sources identifies the exact wheel URLs, archive checksums, source versions, import directories, Python requirements and licences.
• Each packs entry names a runtime distribution (id), the runtime version used to validate and select it (version), its source archives and other required packs.
• recipe: "numpy" retains NumPy's public stubs and the typed source helpers they import. Other current packs combine their listed declarations directly.

The typing-source version can differ from the runtime version: pandas-stubs is a source for the pandas runtime pack. Import names are derived from the extracted files and can differ from the distribution name.

The current profiles target dynamic downlinks running NumPy 2.5.4 and pandas 3.1.0. The catalogue is the authoritative version list; deprecated Full Python bundles do not determine the selected snapshots.

NumPy supplies its own matching declarations. The latest public pandas-stubs source is 3.0.5.260914. Its common DataFrame/Series APIs are checked against pandas 3.1.0, but this does not establish coverage of every new pandas 3.1 API. Preserve that source version in provenance rather than presenting it as a 3.1 stub release.

To update a profile, change its pinned sources and runtime version, rebuild, review the declaration changes and upstream licences, and update the expected content hashes in test/expected.json. Those hashes pin the reviewed declaration contents; changes require deliberate review. Use the browser consumer's semantic tests and completion performance gates before adopting a changed profile.

Package interface

Resolve @anvil-works/python-stubs/manifest.json. Its packs array contains:

| Field | Meaning | | --- | --- | | id | Runtime distribution name used for requirements matching. | | version | Runtime version used to validate and select this profile. | | modules | Top-level Python import names provided by the pack. | | dependencies | IDs of other required packs. | | url | Declaration-map asset path, relative to the manifest. | | sha256 | SHA-256 of the asset bytes; also present in its filename. | | files, bytes | Declaration count and uncompressed asset size. |

Each asset is a UTF-8 JSON object mapping relative Python paths to source text. It includes .pyi declarations and required typed .py helpers. sources in the manifest records the input archives; full licence texts live alongside it under LICENSES/. The consumer copies assets into its own static hosting and owns requirements matching, environment isolation and lazy loading.

A profile describes one known API version. A permissive requirement is not proof of the installed runtime version. Selection and unsupported-version policy belong to the consumer; package generation does not resolve an app's environment.

Publication

The Ty browser build consumes an exact npm version of @anvil-works/python-stubs. Publish the reviewed stub archive before the browser package so a clean browser build can install it without a sibling checkout.

For the current canary, build and test first:

pnpm install --frozen-lockfile --ignore-scripts
pnpm test
pnpm pack --pack-destination .packages

Publish that exact archive, preserving the bytes reviewed and pinned by the browser build:

npm publish .packages/anvil-works-python-stubs-0.1.0-canary.1.tgz --tag canary --access public --registry https://registry.npmjs.org

Use the canary tag; this release does not update latest. The browser package includes the selected declarations and notices, so IDE users do not install this package themselves. S3 delivery remains separate future work.