Doramagic Project Pack · Human Manual

python-typelets

Type hints and utility objects for Python and Django projects.

Overview and Module Architecture

Related topics: General Python Typing Utilities, Django Typing Extensions

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Type-only declarations

Continue reading this section for the full explanation and source context.

Section Generic, consumer-supplied extension points

Continue reading this section for the full explanation and source context.

Section Optional runtime helper

Continue reading this section for the full explanation and source context.

Related topics: General Python Typing Utilities, Django Typing Extensions

Overview and Module Architecture

Purpose and Scope

Typelets is a Python typing utility module that augments built-in Python types and types provided by third-party libraries, with a strong emphasis on the Django web framework. The project was originally developed to support the Review Board codebase and has been extracted into a reusable package under the Beanbag organization.

According to README.md, Typelets is published on PyPI as the typelets package and follows semantic versioning. The module is intentionally *not* a runtime library in the traditional sense — most of its public surface consists of TypeAlias declarations and lightweight runtime helpers used to express static type information.

High-Level Architecture

The package is organized into two tiers:

  1. General Python types under the top-level typelets namespace.
  2. Django-specific types under the typelets.django sub-namespace, which depend on Django being importable and build upon the general tier.

The top-level package entry point (typelets/__init__.py) re-exports only version-related symbols (VERSION, __version__, __version_info__, get_package_version, get_version_string, is_release) sourced from typelets/_version.py. This means no type aliases are re-exported from the package root; consumers must import them from their specific submodule, for example:

from typelets.json import JSONDict
from typelets.django.forms import FormData

The following diagram summarizes how the modules relate:

graph TD
    A[typelets/__init__.py] --> B[typelets/_version.py]
    C[typelets/funcs.py] --> C1[ParamSpec, MethodDirective]
    D[typelets/json.py] --> D1[JSONValue, JSONDict, SerializableJSONValue]
    E[typelets/symbols.py] --> E1[UNSET, Unsettable]
    F[typelets/runtime.py] --> F1[raise_invalid_type]
    G[typelets/django/json.py] --> D
    H[typelets/django/urls.py] --> H1[AnyURL]
    I[typelets/django/forms.py] --> I1[FormData, FormFiles]
    J[typelets/django/strings.py] --> J1[StrOrPromise, StrPromise]
    K[typelets/django/models.py] --> K1[ModelAnyPK, ModelIntPK]
    G --> J

Submodule Catalog

The following table summarizes each public submodule, the types it exposes, and the layer (general vs. Django-specific) it belongs to. This information is assembled from each module's leading docstring and TypeAlias declarations.

SubmoduleLayerKey Public NamesSource
typelets.funcsGeneralKwargsDict, TParams, TReturn_co, TOwner, MethodDirectivetypelets/funcs.py
typelets.jsonGeneralJSONValue, JSONDict, JSONDictImmutable, JSONList, JSONListImmutable, BaseSerializableJSONValue, BaseSerializableJSONDict, BaseSerializableJSONDictImmutable, BaseSerializableJSONList, BaseSerializableJSONListImmutabletypelets/json.py
typelets.runtimeGeneralraise_invalid_typetypelets/runtime.py
typelets.symbolsGeneralUNSET, UnsetSymbol.UNSET, Unsettabletypelets/symbols.py
typelets.django.authDjangoUser-related typesREADME.md
typelets.django.formsDjangoFormData, FormFilestypelets/django/forms.py
typelets.django.jsonDjangoSerializableDjangoJSONValue, SerializableDjangoJSONDict, …typelets/django/json.py
typelets.django.modelsDjangoModelAnyPK, ModelIntPKtypelets/django/models.py
typelets.django.stringsDjangoStrOrPromise, StrPromisetypelets/django/strings.py
typelets.django.urlsDjangoAnyURLtypelets/django/urls.py

Design Conventions and Dependencies

Type-only declarations

Nearly every file uses from __future__ import annotations and the TYPE_CHECKING guard pattern. For example, typelets/funcs.py imports Callable, Concatenate, and TypeAlias under if TYPE_CHECKING: so the typing_extensions backports are evaluated only by static analyzers, not at runtime. This keeps Typelets usable on any modern Python version without forcing a hard dependency on typing_extensions at import time.

Generic, consumer-supplied extension points

The JSON layer (typelets/json.py) deliberately exposes *base* types parameterized by a TypeVar (_T) — BaseSerializableJSONValue, BaseSerializableJSONDict, etc. Consumers define their own TypeAlias against these generics to inject additional serializable types such as datetime or UUID. The Django JSON submodule (typelets/django/json.py) is itself a concrete instantiation of this pattern: it parameterizes the base types with a union of Decimal, StrPromise, UUID, date, datetime, time, and timedelta.

Optional runtime helper

The only meaningfully runtime-impacting utility is raise_invalid_type in typelets/runtime.py. It accepts Never as its first parameter so a type checker treats the call as the terminus of a branch (like assert_never), while still allowing the developer to choose the exception type (defaulting to ValueError) and a custom message — useful for public APIs where AssertionError would be a poor signal.

Versioning

typelets/_version.py stores the version as a six-element tuple (Major, Minor, Micro, tag, release_num, released). The current build is (1, 2, 0, 'alpha', 0, False). get_version_string() produces a human-readable string such as 1.2 alpha 0 (dev), while get_package_version() produces a PEP 440 / PyPI-compatible identifier such as 1.2a0. is_release() returns the released flag, which controls whether the display version is suffixed with (dev).

Documentation build

doc-requirements.txt pins the documentation stack: beanbag-docutils~=2.4 for the Beanbag Sphinx extensions, furo for the theme, sphinx-copybutton for clipboard buttons, and sphinx~=7.3.0. The hosted output lives at typelets.readthedocs.io, which is where every submodule's Version Added annotation links back to.

Common Failure Modes

A few patterns that can trip up first-time consumers:

  • Importing from the top-level package fails. Because typelets/__init__.py does not re-export any type aliases, from typelets import JSONDict will raise ImportError. Always import from the specific submodule.
  • Django submodules require Django installed. Any import under typelets.django.* will fail with ModuleNotFoundError if Django is not present in the environment. Importing the general tier is safe even without Django.
  • raise_invalid_type is typed as returning Never. Static analyzers may complain if the calling site does not already treat the surrounding branch as unreachable. The function is documented as a replacement for typing.assert_never in API code where AssertionError is inappropriate.

See Also

Source: https://github.com/beanbaginc/python-typelets / Human Manual

General Python Typing Utilities

Related topics: Overview and Module Architecture, Django Typing Extensions

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Core Type Variables

Continue reading this section for the full explanation and source context.

Section KwargsDict

Continue reading this section for the full explanation and source context.

Section MethodDirective

Continue reading this section for the full explanation and source context.

Related topics: Overview and Module Architecture, Django Typing Extensions

General Python Typing Utilities

Overview

python-typelets is a Python typing utility module designed to augment the standard and third-party types provided by Python and its ecosystem. It originated as supporting infrastructure for Review Board and is published for broader reuse under the MIT license. Source: README.md

The repository is organized into two broad categories: general Python utilities (covered on this page) and Django-specific utilities. The general utilities are split across four modules:

ModulePurpose
typelets.funcsTyping for callable signatures, methods, and keyword arguments
typelets.jsonTyping for JSON structures and JSON-serializable application data
typelets.symbolsSentinels and type aliases for marking unset / unsettable values
typelets.runtimeHelpers for runtime type-checking with static-typing compatibility

These are all exposed through the package top-level import: typelets/__init__.py re-exports only the version metadata (VERSION, __version__, get_version_string, is_release, etc.), while the modules above are intended to be imported by their subpath (for example, from typelets.funcs import KwargsDict). Source: typelets/__init__.py

flowchart LR
    A[typelets.funcs] -->|Function & method typing| B[Static Type Checkers]
    C[typelets.json] -->|JSON structure & serializable value typing| B
    D[typelets.symbols] -->|Unset sentinel & Unsettable alias| B
    E[typelets.runtime] -->|raise_invalid_type type-guard| B
    A -.uses.-> A
    C -.generic over.-> C

Function Typing (`typelets.funcs`)

The funcs module provides primitives for typing functions, methods, and their parameters.

Core Type Variables

Three reusable TypeVar/ParamSpec aliases anchor the module:

  • TParams = ParamSpec('TParams') — a ParamSpec representing an arbitrary callable's parameter list. Source: typelets/funcs.py
  • TReturn_co = TypeVar('TReturn_co', covariant=True) — a covariant return type.
  • TOwner = TypeVar('TOwner', bound=object) — the owner class of a method.

`KwargsDict`

KwargsDict: TypeAlias = Dict[str, Any] is the canonical typing for "a dictionary of keyword arguments". It lets callers and callees share a single, unambiguous type when functions accept arbitrary keyword arguments. Source: typelets/funcs.py

`MethodDirective`

MethodDirective is a Protocol[TOwner, TParams, TReturn_co] that acts as a typed descriptor-like placeholder for a method on a class. It exposes an __self__: TOwner attribute and overloads __get__ so that accessing the directive returns either Callable[Concatenate[TOwner, TParams], TReturn_co] (unbound) or Callable[TParams, TReturn_co] (bound). This is useful when returning "a method of class X" from a function while preserving full static typing. Source: typelets/funcs.py

`BaseParamsFromFunc`

BaseParamsFromFunc(Generic[TParams]) is the base class for objects whose __call__ signature should be re-typed to match another function or method. It is meant to be paired with the type_func_params_as and type_method_params_as decorators (not shown in the provided source, but referenced in the docstring). The class is generic over TParams, so a subclass can inherit the ParamSpec of a target function. Source: typelets/funcs.py

The docstring enumerates five rules that subclasses must follow when implementing __call__:

  1. Include self even if the wrapped function does not.
  2. Always annotate the return type as Any regardless of the decorated function.
  3. Preserve positional-only / and variadic * markers from the wrapped function.
  4. Always end the signature with *args: TParams.args, **kwargs: TParams.kwargs.
  5. Positional-only markers combined with class decoration may require # type: ignore.

JSON Typing (`typelets.json`)

The json module provides a hierarchy of type aliases describing JSON-shaped data and an extension point for JSON-serializable application types.

Native JSON Types

The base types describe values that JSON natively supports:

  • JSONValue: TypeAlias = Union[JSONDict, JSONDictImmutable, JSONList, JSONListImmutable, None, bool, float, int, str] — any JSON-encodable value. Source: typelets/json.py
  • JSONDict: TypeAlias = Dict[str, JSONValue] — a mutable string-keyed JSON object.
  • JSONDictImmutable: TypeAlias = Mapping[str, JSONValue] — an immutable variant, recommended for return types where mutation should be discouraged.

The accompanying JSONList / JSONListImmutable aliases (referenced in the union) provide the equivalent for list-shaped JSON.

Extensible Serializable Types

A second tier of aliases is parameterized by an application-defined type variable _T:

  • BaseSerializableJSONValue[_T] — adds _T to the JSONValue union.
  • BaseSerializableJSONDict[_T]Dict[str, BaseSerializableJSONValue[_T]].
  • BaseSerializableJSONDictImmutable[_T] — the immutable mapping variant.
  • BaseSerializableJSONList[_T] / BaseSerializableJSONListImmutable[_T] — list variants.

Consumers are expected to create their own concrete alias from these bases, for example:

SerializableJSONValue = BaseSerializableJSONValue[Union[datetime, UUID]]
SerializableJSONDict = BaseSerializableJSONDict[Union[datetime, UUID]]

This pattern keeps the native JSON contract strict while letting consumers document exactly which extra types their serializers accept. Source: typelets/json.py

Symbols (`typelets.symbols`)

The symbols module centralizes sentinel values that distinguish "no value provided" from falsy or None values.

  • UnsetSymbol is an Enum with a single member UNSET = '<UNSET>'.
  • The exported UNSET constant is typed Final[Literal[UnsetSymbol.UNSET]], so static type checkers narrow it precisely to that enum member. Source: typelets/symbols.py
  • Unsettable[_T]: TypeAlias = Union[Literal[UnsetSymbol.UNSET], _T] lets a function declare a parameter that can be either explicitly unset or a real value of type _T. The docstring example annotates an __init__(self, value: Unsettable[str]) parameter.

This is especially useful for __init__ methods and configuration APIs that must distinguish "argument omitted" from "argument passed as None" or False.

Runtime Utilities (`typelets.runtime`)

The runtime module exposes a single helper, raise_invalid_type(value: Never, message: str, exception_type: type[Exception] = ValueError) -> Never. Source: typelets/runtime.py

It is designed to act as a type guard in code paths that static checkers consider unreachable. Unlike typing.assert_never, which raises AssertionError, raise_invalid_type lets callers choose the exception class and message, making it more appropriate for public API argument validation. Because its parameter is annotated Never, a type checker treats every call site as one that definitely raises, so subsequent code in the same branch is considered unreachable without any runtime check.

Common Patterns and Failure Modes

  • Decorating classes with BaseParamsFromFunc can trigger type errors when the wrapped function uses positional-only arguments; the module's docstring recommends a targeted # type: ignore on the decorator line. Source: typelets/funcs.py
  • JSON serializable types require a parallel alias per container shape — BaseSerializableJSONValue, BaseSerializableJSONDict, and BaseSerializableJSONDictImmutable must each be specialized if you want consistent coverage. Source: typelets/json.py
  • UNSET comparison relies on UnsetSymbol.UNSET being a singleton; do not instantiate the enum elsewhere.
  • raise_invalid_type is purely a static-typing convenience — it still raises whatever exception class you pass at runtime, so behavior in tests depends on the supplied exception_type. Source: typelets/runtime.py

See Also

Source: https://github.com/beanbaginc/python-typelets / Human Manual

Django Typing Extensions

Related topics: Overview and Module Architecture, General Python Typing Utilities

Section Related Pages

Continue reading this section for the full explanation and source context.

Related topics: Overview and Module Architecture, General Python Typing Utilities

Django Typing Extensions

Overview

The typelets.django subpackage augments Python and typing_extensions with Django-aware type aliases. These aliases are used to give static type checkers (and reviewers reading annotations) a more precise picture of the values exchanged with Django's runtime, including localized strings, URL routing objects, form payloads, model primary keys, authenticated users, and JSON-serializable values.

The Django subpackage is one of two top-level groups advertised by the project. According to README.md:9-25, Typelets also ships general-purpose Python helpers (funcs, json, runtime, symbols); the Django modules complement those by re-binding Django's runtime types into stable, importable aliases.

All six Django modules are short, declarative, and rely on typing_extensions.TypeAlias (introduced in PEP 613), so they participate cleanly in from __future__ import annotations style code. The package does not implement any runtime behavior beyond re-exporting the alias; each module is a pure typing shim.

Module Catalog

The six Django modules are small and self-contained. The table below summarizes the public alias each one contributes.

ModulePublic AliasUnderlying TypePurpose
typelets.django.authAnyUserUnion[AbstractBaseUser, AnonymousUser]Authenticated or anonymous user
typelets.django.formsFormDataMapping[str, Any]Posted form data dict
typelets.django.formsFormFilesMultiValueDict[str, UploadedFile]Posted form files
typelets.django.jsonSerializableDjangoJSONValueBaseSerializableJSONValue[_SerializableJSONValueTypes]JSON values supported by DjbletsJSONEncoder
typelets.django.jsonSerializableDjangoJSONDictBaseSerializableJSONDict[_SerializableJSONValueTypes]Dict of such values
typelets.django.jsonSerializableDjangoJSONListImmutableBaseSerializableJSONListImmutable[_SerializableJSONValueTypes]Immutable list of such values
typelets.django.modelsModelAnyPKAnyAny Django primary key
typelets.django.modelsModelIntPKintInteger Django primary key
typelets.django.stringsStrOrPromiseUnion[str, _StrPromise]Eager or lazy localized string
typelets.django.stringsStrPromise_StrPromiseLazy localized string
typelets.django.urlsAnyURLUnion[URLPattern, URLResolver]URL pattern or resolver

Sources: typelets/django/auth.py:14-15, typelets/django/forms.py:18-26, typelets/django/json.py:32-49, typelets/django/models.py:24-42, typelets/django/strings.py:35-43, typelets/django/urls.py:21-26.

Localized Strings (`typelets.django.strings`)

Django exposes eager translations through gettext and lazy translations through gettext_lazy. The lazy form returns a Promise whose str() form is only realized when needed. Source: typelets/django/strings.py:9-22.

This module declares StrOrPromise to capture both forms, and StrPromise to indicate a lazy, unresolved string. The implementation uses TYPE_CHECKING to import Django's private _StrOrPromise and _StrPromise for static analysis, while falling back to a NewType('StrPromise', Promise) shim at runtime:

if TYPE_CHECKING:
    from django.utils.functional import _StrOrPromise, _StrPromise
else:
    from django.utils.functional import Promise
    _StrPromise: TypeAlias = NewType('StrPromise', Promise)
    _StrOrPromise: TypeAlias = Union[str, _StrPromise]

The comment in the source explains the reason for the runtime shim: "The main reason we're using NewType here is to avoid Sphinx thinking this is an attribute during doc generation" — Source: typelets/django/strings.py:14-19. The result is that annotations stay readable (s: StrOrPromise = gettext_lazy('...')) without forcing runtime imports of Django's private names.

Forms, Models, Authentication, and URLs

typelets.django.forms provides FormData (Mapping[str, Any]) and FormFiles (MultiValueDict[str, UploadedFile]). They mirror the shape of the data and files keyword arguments that Django passes to Form.__init__ and views, letting callers annotate functions that consume raw POST payloads precisely. Source: typelets/django/forms.py:18-26.

typelets.django.models exposes two primary-key aliases. ModelAnyPK is the documented replacement for Django's default Any primary-key annotation, while ModelIntPK documents codebases that have committed to integer keys. The docstring on each alias is explicit: "Django primary keys default to typing.Any, which doesn't particularly help code stay readable" — Source: typelets/django/models.py:16-22, 36-42.

typelets.django.auth provides the AnyUser alias as Union[AbstractBaseUser, AnonymousUser], which mirrors what Django's request.user returns at runtime. This avoids forcing callers to spell out the union at every call site. Source: typelets/django/auth.py:14-15.

typelets.django.urls defines AnyURL: TypeAlias = Union[URLPattern, URLResolver]. The module's example uses path('/', my_view) and path('/', include(...)) interchangeably, which is exactly the situation in which django.urls.path returns either type depending on whether an include is present. Source: typelets/django/urls.py:21-26.

Django-Aware JSON Serialization

typelets.django.json extends the generic JSON types from typelets.json with Django-aware leaf types. The leaf set is _SerializableJSONValueTypes = Union[Decimal, StrPromise, UUID, date, datetime, time, timedelta], and three public aliases are derived from the parameterized BaseSerializable* families. Source: typelets/django/json.py:23-49.

The relationship between the generic JSON types and the Django-aware variants can be visualized as follows:

graph LR
  BaseSerializableJSONValue --> SerializableDjangoJSONValue
  BaseSerializableJSONDict --> SerializableDjangoJSONDict
  BaseSerializableJSONListImmutable --> SerializableDjangoJSONListImmutable
  SerializableDjangoJSONValue --> SerializableDjangoJSONDict
  SerializableDjangoJSONValue --> SerializableDjangoJSONListImmutable
  StrPromise --> SerializableDjangoJSONValue
  Decimal --> SerializableDjangoJSONValue
  UUID --> SerializableDjangoJSONValue
  date --> SerializableDjangoJSONValue
  datetime --> SerializableDjangoJSONValue
  time --> SerializableDjangoJSONValue
  timedelta --> SerializableDjangoJSONValue

These aliases are designed to match the surface area of djblets.util.serializers.DjbletsJSONEncoder, the encoder that ships with the sister project Djblets. Each alias docstring references that encoder explicitly — Source: typelets/django/json.py:32-49.

Usage Patterns and Common Pitfalls

Two patterns repeat across the modules:

  1. Type-narrowing on returns. JSONDictImmutable and BaseSerializableJSONListImmutable are immutable variants. The docstrings on SerializableDjangoJSONDictImmutable (referenced from the immutable list alias) recommend using these when "returning data from a function that should not be changed" — Source: typelets/django/json.py:42-49. Choosing the immutable variant signals intent to reviewers and to type checkers.
  1. Avoiding Django's Any defaults. Both ModelAnyPK and ModelIntPK exist to escape Django's default Any-typed primary-key annotations. ModelIntPK is the strict choice when the codebase has committed to integer primary keys. Source: typelets/django/models.py:14-42.

A common pitfall is using StrOrPromise in places that strictly require a str. Because lazy promises are not strings until rendered, downstream code that does s + other or s.startswith(...) without forcing evaluation will fail at runtime. The intended usage pattern shown in the source is to assign from gettext and gettext_lazy interchangeably and let Django handle the resolution — Source: typelets/django/strings.py:39-43.

Finally, the Django subpackage is deliberately separate from the generic modules so that projects that don't depend on Django can still import the generic aliases without pulling Django in.

See Also

  • Typelets JSON Typing Extensions — generic JSON aliases that the Django JSON module builds on.
  • Typelets Function Typing Extensions — ParamSpec-based helpers in typelets.funcs.
  • Typelets Symbols and Runtime Utilities — UNSET/Unsettable and raise_invalid_type.

Sources: typelets/django/auth.py:14-15, typelets/django/forms.py:18-26, typelets/django/json.py:32-49, typelets/django/models.py:24-42, typelets/django/strings.py:35-43, typelets/django/urls.py:21-26.

Versioning, Releases, and Contributing

Related topics: Overview and Module Architecture

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Release State Diagram

Continue reading this section for the full explanation and source context.

Related topics: Overview and Module Architecture

Versioning, Releases, and Contributing

This page documents how the Typelets project is versioned, how releases are produced and distributed, and how external contributors can submit changes for review. The information is derived directly from the package's version module, its public re-exports, and its README.

Version Scheme

Typelets follows Semantic Versioning, as stated in README.md ("Typelets follows semantic versioning, meaning no surprises when you upgrade"). Source: README.md.

The canonical version is declared as a single tuple constant in typelets/_version.py:

VERSION: tuple[int, int, int, str, int, bool] = (1, 2, 0, 'alpha', 0, False)

This tuple encodes (Major, Minor, Micro, tag, release_num, released). Each slot has a specific role:

SlotTypeMeaning
0 — MajorintBreaking-change counter.
1 — MinorintBackwards-compatible feature counter.
2 — MicrointBackwards-compatible bug-fix counter.
3 — tagstrPre-release marker: 'alpha', 'beta', 'rc', or 'final'.
4 — release_numintCounter for the active pre-release tag.
5 — releasedboolWhether the current build is a published release.

The tag value is the primary branch indicator: pre-release builds use alpha, beta, or rc, while stable builds use final. Source: typelets/_version.py:18-19.

Release State Diagram

stateDiagram-v2
    [*] --> alpha: development starts
    alpha --> beta: feature freeze
    beta --> rc: stabilization
    rc --> final: publish to PyPI
    final --> final: bug-fix micro bumps
    final --> alpha: next major/minor cycle

Version Helpers and Module Exports

Three helper functions in typelets/_version.py translate the internal tuple into strings used by humans, packaging tools, and runtime checks.

  • get_version_string() builds a display-friendly version. For the current build it returns "1.2 alpha 0 (dev)". The (dev) suffix is appended whenever is_release() is False. Release-candidate builds are rendered with an RC suffix (e.g. 1.2 RC1). Source: typelets/_version.py:24-46.
  • get_package_version() returns a PEP 440–compatible identifier for upload to PyPI. alpha becomes the suffix a, beta becomes b, and rc is preserved. The current package version is therefore 1.2a0. Source: typelets/_version.py:49-69.
  • is_release() simply returns the boolean stored at VERSION[5]. Source: typelets/_version.py:72-80.

Two module-level constants are derived from the tuple for convenience: __version_info__ = VERSION[:-1] (everything except the released flag) and __version__ = get_package_version(). These, together with the helpers and the raw VERSION tuple, are re-exported through typelets/__init__.py, which lists them in both __all__ and __autodoc_excludes__ to keep them out of the generated API reference. Source: typelets/__init__.py:1-22.

Installation and Release Artifacts

Typelets is published to PyPI under the name typelets. Installation is performed with the standard Python package manager:

$ pip install typelets

Source: README.md ("To install typelets, run: $ pip install typelets"). The version that pip resolves comes directly from get_package_version() in typelets/_version.py:49-69, which means the metadata uploaded to PyPI always matches the in-source VERSION tuple.

The project is distributed under the MIT license. Source: README.md ("Typelets is available under the MIT license").

Development Dependencies

The repository ships a dev-requirements.txt that pins the toolchain used during development and continuous integration. Django is pinned per Python version (~=3.2 on Python 3.8 and ~=4.2 on 3.9+), alongside django-stubs for type checking and pytest for tests. Source: dev-requirements.txt.

Contributing Workflow

Typelets does not accept pull requests on GitHub. Instead, changes are posted to the Beanbag Review Board server at https://reviews.reviewboard.org/ using RBTools. Source: README.md ("Contributions to Typelets can be made on our Review Board server at https://reviews.reviewboard.org/").

The documented workflow is:

``console $ pip install rbtools ``

``console $ rbt post ``

``console $ rbt post -u ``

  1. Install RBTools into the development environment:
  2. Create a branch in the local Git clone and make the desired changes to the relevant module (for example, editing one of the public type aliases in typelets/django/models.py or the JSON type hierarchy in typelets/json.py).
  3. Post the change for review:
  4. Update the change after revisions with the -u flag:

Source: README.md ("Download RBTools … Create a branch in your Git clone and make your changes. Post the change for review: $ rbt post. To update your change: $ rbt post -u").

The VERSION tuple in typelets/_version.py and the exported __version__ constant are the two pieces of metadata that reviewers will check when evaluating release-impact changes, so any change that affects the public API should be reflected in the version tag and release notes before posting.

See Also

Source: https://github.com/beanbaginc/python-typelets / Human Manual

Doramagic Pitfall Log

Source-linked risks stay visible on the manual page so the preview does not read like a recommendation.

medium Identity risk requires verification

May increase setup, validation, or first-run risk for the user.

medium Capability evidence risk requires verification

May increase setup, validation, or first-run risk for the user.

medium Maintenance risk requires verification

May increase setup, validation, or first-run risk for the user.

medium Security or permission risk requires verification

May increase setup, validation, or first-run risk for the user.

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

Source: Doramagic discovery, validation, and Project Pack records

Community Discussion Evidence

These external discussion links are review inputs, not standalone proof that the project is production-ready.

Sources 1

Count of project-level external discussion links exposed on this manual page.

Use Review before install

Open the linked issues or discussions before treating the pack as ready for your environment.

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.

Source: Project Pack community evidence and pitfall evidence