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
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
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:
- General Python types under the top-level
typeletsnamespace. - Django-specific types under the
typelets.djangosub-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 --> JSubmodule 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.
| Submodule | Layer | Key Public Names | Source |
|---|---|---|---|
typelets.funcs | General | KwargsDict, TParams, TReturn_co, TOwner, MethodDirective | typelets/funcs.py |
typelets.json | General | JSONValue, JSONDict, JSONDictImmutable, JSONList, JSONListImmutable, BaseSerializableJSONValue, BaseSerializableJSONDict, BaseSerializableJSONDictImmutable, BaseSerializableJSONList, BaseSerializableJSONListImmutable | typelets/json.py |
typelets.runtime | General | raise_invalid_type | typelets/runtime.py |
typelets.symbols | General | UNSET, UnsetSymbol.UNSET, Unsettable | typelets/symbols.py |
typelets.django.auth | Django | User-related types | README.md |
typelets.django.forms | Django | FormData, FormFiles | typelets/django/forms.py |
typelets.django.json | Django | SerializableDjangoJSONValue, SerializableDjangoJSONDict, … | typelets/django/json.py |
typelets.django.models | Django | ModelAnyPK, ModelIntPK | typelets/django/models.py |
typelets.django.strings | Django | StrOrPromise, StrPromise | typelets/django/strings.py |
typelets.django.urls | Django | AnyURL | typelets/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 JSONDictwill raiseImportError. Always import from the specific submodule. - Django submodules require Django installed. Any import under
typelets.django.*will fail withModuleNotFoundErrorif Django is not present in the environment. Importing the general tier is safe even without Django. raise_invalid_typeis typed as returningNever. Static analyzers may complain if the calling site does not already treat the surrounding branch as unreachable. The function is documented as a replacement fortyping.assert_neverin API code whereAssertionErroris 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
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
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:
| Module | Purpose |
|---|---|
typelets.funcs | Typing for callable signatures, methods, and keyword arguments |
typelets.json | Typing for JSON structures and JSON-serializable application data |
typelets.symbols | Sentinels and type aliases for marking unset / unsettable values |
typelets.runtime | Helpers 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.-> CFunction 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')— aParamSpecrepresenting an arbitrary callable's parameter list. Source: typelets/funcs.pyTReturn_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__:
- Include
selfeven if the wrapped function does not. - Always annotate the return type as
Anyregardless of the decorated function. - Preserve positional-only
/and variadic*markers from the wrapped function. - Always end the signature with
*args: TParams.args, **kwargs: TParams.kwargs. - 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.pyJSONDict: 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_Tto theJSONValueunion.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.
UnsetSymbolis anEnumwith a single memberUNSET = '<UNSET>'.- The exported
UNSETconstant is typedFinal[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
BaseParamsFromFunccan trigger type errors when the wrapped function uses positional-only arguments; the module's docstring recommends a targeted# type: ignoreon the decorator line. Source: typelets/funcs.py - JSON serializable types require a parallel alias per container shape —
BaseSerializableJSONValue,BaseSerializableJSONDict, andBaseSerializableJSONDictImmutablemust each be specialized if you want consistent coverage. Source: typelets/json.py UNSETcomparison relies onUnsetSymbol.UNSETbeing a singleton; do not instantiate the enum elsewhere.raise_invalid_typeis purely a static-typing convenience — it still raises whatever exception class you pass at runtime, so behavior in tests depends on the suppliedexception_type. Source: typelets/runtime.py
See Also
- Typelets documentation on Read the Docs
typelets.django.auth—AnyUserfor logged-in or anonymous Django users. Source: typelets/django/auth.pytypelets.django.forms—FormDataandFormFilesfor form handling. Source: typelets/django/forms.pytypelets.django.json—SerializableDjangoJSONValuebuilt on top oftypelets.json. Source: typelets/django/json.pytypelets.django.models—ModelAnyPK/ModelIntPKaliases. Source: typelets/django/models.pytypelets.django.strings—StrOrPromise/StrPromise. Source: typelets/django/strings.pytypelets.django.urls—AnyURLforURLPattern | URLResolver. Source: typelets/django/urls.py
Source: https://github.com/beanbaginc/python-typelets / Human Manual
Django Typing Extensions
Related topics: Overview and Module Architecture, General Python Typing Utilities
Continue reading this section for the full explanation and source context.
Related Pages
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.
| Module | Public Alias | Underlying Type | Purpose |
|---|---|---|---|
typelets.django.auth | AnyUser | Union[AbstractBaseUser, AnonymousUser] | Authenticated or anonymous user |
typelets.django.forms | FormData | Mapping[str, Any] | Posted form data dict |
typelets.django.forms | FormFiles | MultiValueDict[str, UploadedFile] | Posted form files |
typelets.django.json | SerializableDjangoJSONValue | BaseSerializableJSONValue[_SerializableJSONValueTypes] | JSON values supported by DjbletsJSONEncoder |
typelets.django.json | SerializableDjangoJSONDict | BaseSerializableJSONDict[_SerializableJSONValueTypes] | Dict of such values |
typelets.django.json | SerializableDjangoJSONListImmutable | BaseSerializableJSONListImmutable[_SerializableJSONValueTypes] | Immutable list of such values |
typelets.django.models | ModelAnyPK | Any | Any Django primary key |
typelets.django.models | ModelIntPK | int | Integer Django primary key |
typelets.django.strings | StrOrPromise | Union[str, _StrPromise] | Eager or lazy localized string |
typelets.django.strings | StrPromise | _StrPromise | Lazy localized string |
typelets.django.urls | AnyURL | Union[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:
- Type-narrowing on returns.
JSONDictImmutableandBaseSerializableJSONListImmutableare immutable variants. The docstrings onSerializableDjangoJSONDictImmutable(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.
- Avoiding Django's
Anydefaults. BothModelAnyPKandModelIntPKexist to escape Django's defaultAny-typed primary-key annotations.ModelIntPKis 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 intypelets.funcs. - Typelets Symbols and Runtime Utilities —
UNSET/Unsettableandraise_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
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
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:
| Slot | Type | Meaning |
|---|---|---|
| 0 — Major | int | Breaking-change counter. |
| 1 — Minor | int | Backwards-compatible feature counter. |
| 2 — Micro | int | Backwards-compatible bug-fix counter. |
| 3 — tag | str | Pre-release marker: 'alpha', 'beta', 'rc', or 'final'. |
| 4 — release_num | int | Counter for the active pre-release tag. |
| 5 — released | bool | Whether 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 cycleVersion 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 wheneveris_release()isFalse. Release-candidate builds are rendered with anRCsuffix (e.g.1.2 RC1). Source: typelets/_version.py:24-46.get_package_version()returns a PEP 440–compatible identifier for upload to PyPI.alphabecomes the suffixa,betabecomesb, andrcis preserved. The current package version is therefore1.2a0. Source: typelets/_version.py:49-69.is_release()simply returns the boolean stored atVERSION[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 ``
- Install RBTools into the development environment:
- 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).
- Post the change for review:
- Update the change after revisions with the
-uflag:
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
- README.md — installation, documentation, and contribution overview.
- typelets/_version.py — version tuple and helper functions.
- typelets/__init__.py — public exports of version metadata.
- dev-requirements.txt — pinned development dependencies.
- Review Board documentation — RBTools usage reference for the contribution workflow.
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.
May increase setup, validation, or first-run risk for the user.
May increase setup, validation, or first-run risk for the user.
May increase setup, validation, or first-run risk for the user.
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.
Count of project-level external discussion links exposed on this manual page.
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.
- Identity risk requires verification - GitHub / issue
Source: Project Pack community evidence and pitfall evidence