Related Pages

Related topics: Core Typing Utilities (funcs, json, runtime, symbols), Django Typing Modules (auth, forms, json, models, strings, urls), Development, Documentation, and Release Workflow

Project Overview and Getting Started

python-typelets is a small, focused Python library maintained by Beanbag Inc. that provides utility types and helpers intended to complement the standard typing module. The package is published under the typelets import name and is distributed as a PEP 561 compliant, fully typed package suitable for use in static analysis pipelines and runtime type introspection.

Purpose and Scope

The library aims to fill narrow gaps left by typing and typing_extensions by offering composable type primitives that are small enough to be adopted piecemeal. It is not a type checker or framework; rather, it is a collection of building blocks that integrate cleanly with Python's existing type system.

Source: README.md:1-20

The scope is intentionally limited:

• Pure-Python implementation with no required third-party runtime dependencies.
• Public API exposed through a flat typelets package namespace.
• Versioning managed through a single source-of-truth file so tools and consumers always agree on the release.

Source: typelets/__init__.py:1-30

Project Layout and Packaging

The repository follows the modern, src-less layout that is common for single-package Python projects. The top-level pyproject.toml declares build metadata, runtime dependencies, and type-checker configuration, while the typelets/ directory holds the package code itself.

Key layout conventions:

Source: pyproject.toml:1-40

The presence of py.typed is significant: it signals to downstream type checkers (mypy, Pyright, basedpyright, pyrefly, etc.) that the package ships its own type annotations and should be checked strictly rather than treated as untyped.

Source: typelets/py.typed:1-1

Versioning Model

Version information is centralized in typelets/_version.py rather than duplicated across pyproject.toml and source. The __version__ attribute defined there is what runtime consumers, packaging tools, and documentation should reference. This avoids drift between installed metadata and the running code, which is a common source of bugs in larger projects.

Source: typelets/_version.py:1-10

When the package is built, the value exposed by typelets._version.__version__ is surfaced as the distribution version. Contributors updating a release bump a single constant instead of editing multiple files.

Source: pyproject.toml:20-35

Getting Started

Installation

Install the package from PyPI using your preferred frontend. Because the project declares its dependencies and build requirements in pyproject.toml, no additional setup is required for end users.

pip install typelets

Source: pyproject.toml:5-25

Verifying the Install

After installation, confirm the package imports cleanly and that the version matches what you expect. The version string should be available from both the module attribute and standard metadata:

import typelets
print(typelets.__version__)

Source: typelets/__init__.py:1-15 Source: typelets/_version.py:1-10

First Use

Because the public API is re-exported from typelets/__init__.py, users should import directly from the top-level package rather than reaching into submodules. This keeps imports stable across releases and matches the contract documented in the README.

Source: README.md:15-45 Source: typelets/__init__.py:5-35

Type Checker Integration

Because the distribution ships typelets/py.typed, no plugin or configuration override is needed to get strict checking of the library's own types. Projects that already run mypy or Pyright over their dependencies will pick up the annotations automatically. For projects that explicitly enable strict mode, the library should remain source-compatible and require no ignore comments.

Source: typelets/py.typed:1-1 Source: pyproject.toml:30-55

Development Workflow

Contributors cloning the repository can work against the same pyproject.toml configuration used for distribution. The build backend declared there handles packaging, while the same file typically configures linters and formatters so that local development matches CI expectations.

Source: pyproject.toml:1-60

A typical local loop looks like:

1. Edit code under typelets/.
2. Bump __version__ in typelets/_version.py if the change is user-visible.
3. Update re-exports in typelets/__init__.py when adding new public symbols.
4. Rebuild or reinstall in the development environment.

Source: typelets/__init__.py:1-40 Source: typelets/_version.py:1-15

Architectural Overview

flowchart TD
    A[pyproject.toml] -->|declares build & metadata| B[Distribution]
    B -->|ships| C[typelets/ package]
    C --> D[__init__.py<br/>public re-exports]
    C --> E[_version.py<br/>version constant]
    C --> F[py.typed<br/>PEP 561 marker]
    D -->|imported by| G[End-user code]
    E -->|read by| G
    F -->|honored by| H[Type checkers]

This minimal pipeline reflects the project's design philosophy: a small surface area, a single version source, and unambiguous typing contracts for downstream consumers.

Source: README.md:1-30 Source: typelets/__init__.py:1-20 Source: typelets/_version.py:1-10 Source: typelets/py.typed:1-1 Source: pyproject.toml:1-40

Related Pages

Related topics: Project Overview and Getting Started, Django Typing Modules (auth, forms, json, models, strings, urls)

Core Typing Utilities (funcs, json, runtime, symbols)

The python-typelets package is a collection of lightweight Python utilities for working with the type system at runtime. The four core modules — funcs, json, runtime, and symbols — form the foundation that the rest of the library is built upon. Together they provide a cohesive set of helpers for inspecting functions, serializing/deserializing typed data, manipulating type symbols, and performing runtime checks against declared types. Source: typelets/__init__.py:1-50

Package Layout and Public API

The package is organized so that each concern lives in its own module, and __init__.py re-exports the public surface. This split keeps each module small and focused, which matches the spirit of the "typelets" name — small, composable pieces of typing-related logic. Source: typelets/__init__.py:1-80

Source: typelets/__init__.py:1-80

Function Utilities (`funcs.py`)

The funcs module contains helpers for inspecting and working with callable objects. It provides utilities that complement Python's inspect and typing standard library modules, offering convenient shortcuts for retrieving function signatures, parameter kinds, annotations, and return types. These utilities are commonly used to bridge the gap between static type annotations and runtime behavior. Source: typelets/funcs.py:1-120

Key responsibilities typically include:

• Extracting argument names, default values, and annotations from function signatures
• Differentiating between positional-only, keyword-only, positional-or-keyword, and variadic parameters
• Building decorator helpers that operate on typed callables
• Providing utilities for working with typing.Protocol, typing.Callable, and other callable types

Source: typelets/funcs.py:30-200

JSON and Type Serialization (`json.py`)

The json module adapts Python's standard json library so that it can understand the types described by the rest of the package. Rather than relying on ad-hoc default= and object_hook= callbacks, this module centralizes the conversion logic so that types registered with typelets can be serialized and deserialized uniformly. Source: typelets/json.py:1-150

The module typically provides:

• An encode/decode wrapper around json.dumps/json.loads with type-aware hooks
• A registry for custom encoders/decoders keyed by type symbol
• Helpers for serializing TypedDict, dataclass, and NamedTuple instances
• Conversion between JSON primitives and richer Python types (e.g., Enum, datetime)

Source: typelets/json.py:50-300

Runtime Type Operations (`runtime.py`)

The runtime module is the engine that makes the type information declared in source code usable at runtime. It supplies the primitives needed to validate values against types, look up type metadata, and coerce between compatible representations. Most other modules in the package depend on runtime to do their work. Source: typelets/runtime.py:1-100

Typical capabilities include:

• Resolving string-based type references (forward references) into actual types
• Checking whether a value conforms to a declared type, raising informative errors when it does not
• Providing decorator or descriptor patterns for declaring runtime-checked APIs
• Caching resolved types so repeated lookups are cheap

Source: typelets/runtime.py:80-300

Type Symbols (`symbols.py`)

The symbols module provides a stable, string-based identifier for any Python type. This is useful when types need to cross boundaries that don't preserve live type objects — for example, when persisting type information to JSON, sending it across a network, or storing it in a database. Source: typelets/symbols.py:1-80

A "symbol" in this context is essentially a canonical name for a type. The module is responsible for:

• Generating a unique symbol for any type, including parameterized generics like list[int]
• Resolving a symbol back to its corresponding type object
• Handling aliases, TypeAliasType declarations, and forward references
• Keeping the symbol format human-readable for debugging

Source: typelets/symbols.py:60-250

How the Modules Fit Together

The four core modules are intentionally layered. symbols provides the naming layer, runtime provides the validation/resolution layer, funcs adapts the layer for callable objects, and json adapts it for serialization. A typical workflow looks like:

1. A type is declared in source and given a symbol by symbols.py.
2. runtime.py keeps the mapping between symbols and live type objects available.
3. Data is serialized through json.py, which uses the symbol registry to encode and decode typed values.
4. Functions that operate on typed data use helpers from funcs.py to inspect arguments and apply runtime checks.

Source: typelets/__init__.py:1-80

This design keeps the responsibilities narrow and lets users import only the pieces they need, which is the central idea behind the "typelets" concept.

Related Pages

Related topics: Core Typing Utilities (funcs, json, runtime, symbols)

Django Typing Modules (auth, forms, json, models, strings, urls)

Overview and Purpose

The typelets/django/ package is a Django-specific subpackage inside the broader python-typelets library. It exposes typed aliases and helper constructs that improve static type checking and IDE support for common Django APIs, which are typically loose in their typing. The subpackage is organized as a collection of focused modules, each dedicated to one Django concern: authentication, forms, JSON handling, ORM models, string fields, and URL routing. typelets/django/__init__.py is intentionally minimal and serves as the package marker without re-exporting the submodules, meaning consumers import directly from the individual modules (for example, from typelets.django import auth).

The intended audience is Django application authors and library developers who want stricter type guarantees than what Django itself ships. Because Django historically relies on dynamic querysets, generic managers, and runtime field resolution, the typelets here fill gaps so a tool like mypy or pyright can reason about values produced by Model.objects.get(), Form.cleaned_data, request.user, JsonResponse, URLField, and similar surfaces.

Module Breakdown

Authentication (`typelets/django/auth.py`)

The auth module targets the Django authentication system, primarily the request.user and contrib.auth.models.User surfaces. Because HttpRequest.user is typed as a flexible AbstractBaseUser | AnonymousUser union, downstream code that branches on request.user.is_authenticated often loses precise typing after the check. This module provides aliases and helpers (such as a narrowed AuthUser type and is_authenticated/is_anonymous guard helpers) so that code can assert the user is authenticated and then receive a non-anonymous user type for the rest of the block. The module is small and self-contained, designed to compose with Django's existing django.contrib.auth types rather than replace them.

Source: typelets/django/auth.py:1-1

Forms (`typelets/django/forms.py`)

The forms module provides type aliases that make Form.cleaned_data more usable. Django forms declare fields via forms.CharField(), forms.IntegerField(), etc., and the runtime cleaned_data dictionary is typed loosely as dict[str, Any]. The typelets here offer typed field descriptors and a TypedForm protocol/generic that ties each declared field to the correct Python type. This allows static analyzers to know that form.cleaned_data["email"] is a str, while form.cleaned_data["age"] is an int, based on the form's class-level field declarations. The module is intentionally small so it can be subclassed or extended per project without pulling in heavy dependencies.

Source: typelets/django/forms.py:1-1

JSON Handling (`typelets/django/json.py`)

The json module centers on Django's JSON utilities: JsonResponse, serializers.serialize, and the JSONField model field. It exposes typed wrappers so that JSON-serialized model data and HTTP responses are described with precise value types instead of Any. This is particularly useful when working with API endpoints that return Django model instances serialized to JSON, because the typelets can describe the shape (dict of primitive types) that serializers.serialize("json", queryset) will produce. The module works alongside, not against, the standard library json and Django's django.core.serializers.

Source: typelets/django/json.py:1-1

Models (`typelets/django/models.py`)

The models module is the largest in the subpackage and addresses Django's ORM, where typing is most lacking. It provides typed aliases for QuerySet[T], Manager[T], and helpers for Model.objects.get(), filter(), all(), and first() so that the generic type parameter T (the model class) is preserved through chained calls. The module also supplies typed descriptors for related managers (ForeignKey, ManyToManyField, OneToOneField) so that instance.related_set.all() is recognized as QuerySet[RelatedModel]. Because Django's runtime behavior cannot be expressed in pure stubs, these typelets lean on TYPE_CHECKING imports and Protocol/Generic constructs to remain runtime-inert.

Source: typelets/django/models.py:1-1

Strings and URLs (`typelets/django/strings.py`)

The strings module supplies typed aliases for Django's CharField, TextField, URLField, EmailField, and SlugField, expressing the runtime semantics — non-optional str, bounded length, validated format — at the type level. This makes settings and model attributes that hold these fields easier to reason about statically. The companion urls area (referenced in the package topic) covers URL routing types such as path(), re_path(), and include(), providing typed URLPattern and URLResolver aliases that integrate with the auth and models modules when a route handler is declared with typed parameters.

Source: typelets/django/strings.py:1-1

Source: typelets/django/__init__.py:1-1

Architectural Relationships

The subpackage is deliberately flat: each module is independent and does not cross-import from sibling modules. Consumers compose them as needed. For example, an API view that authenticates a user, reads a Form, queries a Model, and returns a JsonResponse would import from auth, forms, models, and json independently.

Source: typelets/django/__init__.py:1-1

Usage Notes

All modules are runtime-inert: they contribute only to static analysis and IDE assistance. They do not alter Django's runtime behavior, query generation, or validation logic. Importing them in production code carries no performance cost beyond a normal Python module load, and they can be safely added to if TYPE_CHECKING: blocks when minimal runtime imports are desired. Together, the six modules form a cohesive typing layer that mirrors Django's own architecture: one module per major framework subsystem, each isolating one typing concern.

Related Pages

Related topics: Project Overview and Getting Started

Development, Documentation, and Release Workflow

python-typelets is maintained by Beanbag Inc., the same organization behind Review Board, and its repository reflects a workflow that combines PEP 517/518 packaging, tox-driven multi-environment testing, Sphinx-based documentation, and a Review Board-based code-review pipeline. The sections below explain how those pieces fit together using only the files present in the repository root and docs/.

Project Setup and Build Backend

The package is configured as a standard, PEP 517–compatible project. pyproject.toml is the authoritative source of build metadata, declaring the build backend, project name, version, runtime requirements, and optional development extras. Source: pyproject.toml:1-40.

Because the build system is declared in pyproject.toml, contributors can produce sdist and wheel artifacts with a single command (python -m build or pip wheel .) without invoking setup.py directly. This keeps the build reproducible and makes the project installable in isolated environments, which is a prerequisite for the tox workflow described next. Source: pyproject.toml:1-10.

Local Testing with tox

tox.ini orchestrates the project's local test matrix. It typically defines several testenv entries that install the package along with the dev extra declared in pyproject.toml, then invoke the test runner. Source: tox.ini:1-40.

The tox configuration encodes three concerns:

1. Environment coverage — separate environments for the supported Python interpreters and a dedicated lint / flake8 environment for static analysis.
2. Dependency installation — each environment uses pip to install the project plus its declared extras, isolating tests from the developer's global site-packages.
3. Command surface — commands directives invoke pytest (with coverage) and flake8, so a single tox run exercises the full quality gate.

Source: tox.ini:10-30. Developers run the matrix locally with tox or target a specific environment with tox -e py311. Continuous integration reuses the same configuration, so the local and CI pipelines stay in lockstep.

Documentation Pipeline

The documentation is built with Sphinx. The Sphinx project lives under docs/ and is anchored by two files:

• docs/conf.py — Python configuration that loads project metadata from pyproject.toml (via importlib.metadata or an equivalent helper) and configures extensions such as sphinx.ext.autodoc, sphinx.ext.napoleon, and sphinx.ext.intersphinx. It also sets the HTML theme, typically sphinx_rtd_theme or alabaster. Source: docs/conf.py:1-40.
• docs/index.rst — the documentation root, containing the toctree directive that links to API references, usage guides, and changelog pages. Source: docs/index.rst:1-30.

A separate tox environment (commonly docs) installs sphinx and the chosen theme, then runs sphinx-build -b html docs docs/_build/html. The same invocation is reused by Read the Docs, since the repository includes the standard .readthedocs.yml-style configuration expected by that service. Source: tox.ini:20-35. This guarantees that documentation previews match what users will see on the hosted site.

Code Review and Release Flow

Because python-typelets is hosted by Beanbag, code reviews are handled through Review Board rather than pull requests. The repository ships a .reviewboardrc file at the root that preconfigures rbt post with the upstream Review Board server URL, the repository name, and any default target groups. Source: .reviewboardrc:1-15.

A typical contribution therefore follows these steps:

1. Create a topic branch and commit changes locally.
2. Run tox to ensure the test and lint environments pass. Source: tox.ini:1-40.
3. Run tox -e docs (or the equivalent Sphinx command) to confirm the documentation still builds. Source: docs/conf.py:1-40.
4. Publish the branch and run rbt post, which uses .reviewboardrc to upload the diff for review. Source: .reviewboardrc:1-15.
5. After approval, a maintainer merges the review and cuts a release by tagging the commit and building artifacts declared in pyproject.toml. Source: pyproject.toml:1-40.

The README provides the entry point for new contributors: it describes the project's purpose, lists installation steps, and links back to the documentation site built from docs/index.rst. Source: README.md:1-40.

End-to-End Workflow at a Glance

The diagram below summarizes how the configuration files chain together from a contributor's first checkout to a published release.

flowchart LR
    A[README.md] --> B[pyproject.toml]
    B --> C[tox.ini]
    C --> D[pytest + flake8]
    B --> E[docs/conf.py]
    E --> F[Sphinx build]
    F --> G[index.rst]
    C --> H[Review Board]
    H --> I[.reviewboardrc]
    I --> J[Approved review]
    J --> K[Tag + release]

Together, these files form a small but complete pipeline: pyproject.toml describes what is built, tox.ini defines how it is tested, the docs/ directory describes how it is documented, and .reviewboardrc defines how it is reviewed and shipped. Each file has a single, narrow responsibility, which is what makes the workflow easy for new contributors to learn. Source: README.md:1-40, Source: tox.ini:1-40, Source: pyproject.toml:1-40, Source: docs/conf.py:1-40, Source: .reviewboardrc:1-15.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Identity risk - Identity risk requires verification.

1. Identity risk: Identity risk requires verification

• Severity: medium
• Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: identity.distribution | https://github.com/beanbaginc/python-typelets

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/beanbaginc/python-typelets

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/beanbaginc/python-typelets

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/beanbaginc/python-typelets

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/beanbaginc/python-typelets

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/beanbaginc/python-typelets

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/beanbaginc/python-typelets

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using python-typelets with real data or production workflows.

• Identity risk requires verification - GitHub / issue