Typing Stubs for orjson

3.6.2 · active · verified Wed Apr 15

types-orjson provides type hints (typing stubs) for the high-performance `orjson` JSON library. It is part of the Python `typeshed` project, which maintains type stubs for various third-party packages. These stubs enable static type checkers like MyPy or Pyright to validate `orjson`'s API usage, enhancing code reliability and developer experience. The current version is 3.6.2, and updates are typically released in sync with `typeshed`'s update cycle or when `orjson` has significant API changes.

Warnings

gotcha Installing `types-orjson` alone is not enough. You must also install the actual `orjson` library for your code to run at runtime. `types-orjson` only provides type hints for `orjson`.
Fix: Ensure both `pip install orjson` and `pip install types-orjson` are executed.
gotcha `types-orjson` provides static type information for type checkers (e.g., MyPy, Pyright) only. It does not add any runtime functionality or change the behavior of `orjson` itself. Your code will function identically at runtime with or without `types-orjson` installed.
Fix: Understand that stubs are for development-time type validation, not runtime execution. Do not attempt to import from `types_orjson`.
breaking While `typeshed` strives to keep stubs up-to-date, significant API changes in `orjson` itself might lead to temporary inconsistencies or outdated type hints in `types-orjson` until the stubs are updated. This typically means your type checker might report errors even if the runtime code is correct for a new `orjson` version.
Fix: If facing type checking errors after updating `orjson`, check the `typeshed` GitHub for relevant issues or pull requests, or temporarily pin `orjson` to an older version compatible with the stubs.

Install

pip install types-orjson orjson Install stubs and orjson

Imports

orjson
wrong:
```
from types_orjson import ...
```
correct:
```
import orjson
```
You do not directly import from `types_orjson`. Install the package, and type checkers will automatically find its stubs when you import `orjson`.

Quickstart

This quickstart demonstrates how to use `orjson` with `types-orjson` installed. Type checkers will now understand the types returned by `orjson.loads` and expected by `orjson.dumps`, ensuring type safety in your code without needing direct `types-orjson` imports.

import orjson
from typing import Any, Dict

def process_data(data_str: str) -> Dict[str, Any]:
    # orjson.loads provides type hints thanks to types-orjson
    parsed_data: Dict[str, Any] = orjson.loads(data_str)
    
    # orjson.dumps provides type hints
    re_serialized_data: bytes = orjson.dumps(parsed_data, option=orjson.OPT_INDENT_2)
    print(re_serialized_data.decode())
    return parsed_data

if __name__ == '__main__':
    json_string = '{"name": "Alice", "age": 30, "city": "New York"}'
    result = process_data(json_string)
    print(f"Parsed data: {result}")
    # To verify types, run a type checker:
    # mypy your_script_name.py
    # or pyright your_script_name.py

view raw JSON →