types-toml

types-toml is the PEP 561 stub-only distribution that provides static type annotations for the popular toml library. It ships the .pyi stub files maintained in the typeshed project, describing the signatures of toml’s load, loads, dump, and dumps functions along with its decoder and encoder classes.

Because the toml package itself is untyped, installing types-toml lets type checkers such as mypy and pyright understand TOML parsing and serialization calls, catching type errors and enabling accurate editor autocompletion without changing any runtime behavior.

What You Get

• Complete .pyi type stubs for the toml library’s public API
• Typed signatures for load, loads, dump, and dumps
• Type annotations for the decoder and encoder classes (TomlDecoder, TomlEncoder, and variants)
• Compatibility with mypy, pyright, and other PEP 561 aware type checkers
• Zero runtime footprint - the stubs affect only static analysis

Common Use Cases

• Adding type safety to a codebase that reads and writes TOML with the toml library
• Enabling accurate autocompletion and inline documentation for toml calls in editors
• Passing strict mypy or pyright checks in projects that depend on toml
• Documenting the expected argument and return types of TOML operations

Under The Hood

Architecture - types-toml is a stub-only distribution: it contains no executable code, only .pyi files that mirror the module structure of the toml package (a top-level init.pyi re-exporting the decoder and encoder submodules). The stubs are authored and maintained in the python/typeshed monorepo under stubs/toml and published as a standalone PyPI package by typeshed’s stub uploader.

Tech Stack - The package is pure typing metadata targeting the CPython type-checking ecosystem. It is generated and released from typeshed, whose tooling versions each stub against the upstream library (here tracking toml 0.10.x) and packages it for distribution.

Code Quality - typeshed enforces rigorous quality on its stubs through automated checks, including stubtest (which validates stubs against the real runtime module), flake8, and reviews by the typing community. This gives the annotations a high degree of fidelity to the actual toml API.

API Design - As a stubs package there is no runtime API to design; its value lies in accurately reflecting toml’s surface. Installation is transparent - once present, type checkers automatically pick up the stubs via PEP 561, requiring no imports or configuration in user code.