typings🏷️

Type stubs for third-party libraries, written by hand. Some of these libraries ship no types at all. Others ship types that basedpyright and ty reject in strict mode.

Quick Start

# Mac:
#   # Required for quick install.
#   brew install uv

# Ubuntu/Debian:
#   # Required for quick install.
#   sudo apt-get install -y curl
#   curl -LsSf https://astral.sh/uv/install.sh | sh

uv add --dev rekursiv-ai-typings

# Alternatively: python -m pip install rekursiv-ai-typings

There is nothing to configure. Each library's stubs install as a separate <pkg>-stubs package (the standard PEP 561 layout), and both checkers look for those automatically.

Example

import yaml

data = yaml.safe_load("a: 1")
reveal_type(data)  # object, not Any

Features

Override one library

If you want your own stubs for a library instead of ours, put them in your project and they take priority. Name the directory <pkg>-stubs:

typings/<pkg>-stubs/__init__.pyi

Then tell both checkers where to look:

[tool.basedpyright]
stubPath = "typings"

[tool.ty.environment]
extra-paths = ["typings"]

The -stubs suffix matters. If you name the directory <pkg>, ty ignores it and uses ours.

Partial stubs

Some stubs cover only part of a library: fastapi, starlette, lxml, curl_cffi, lark, optax, sklearn, and torch. Each of these is marked partial, so for any module we don't stub, the checkers fall back to the library's own types.

Triton on macOS

triton only installs on Linux. On macOS, basedpyright reports reportMissingModuleSource on every import triton. To fix that, this package also installs placeholder .py files for triton. Add their location to extraPaths:

[tool.basedpyright]
extraPaths = [".venv/share/rekursiv-ai-typings"]

The placeholders only make the import resolve. The types still come from our stubs.

Patched standard library

rekursiv-ai-typeshed, in typeshed/, is a separate package from this repo. It fixes the standard-library stubs so that x ** 0.5 is a float rather than Any. See typeshed/README.md.