lazy-model

library0.4.0pypypi✓ verified 24d ago

lazy-model is a Python library that provides a lazy interface for parsing objects into Pydantic models. It defers the parsing and validation of individual fields until they are explicitly accessed, saving the raw data within the object initially. This approach can significantly improve performance and reduce memory consumption, especially for large or complex data structures where not all fields are always needed immediately. The library is currently at version 0.4.0 and appears to have an active, though not rapid, release cadence, with its latest release in August 2025.

serialization database

pip install lazy-model

package ↗

INSTALL

IMPORT

SIG · LAZY-MODEL

lazy-model

serializationpythonv0.4.0

Install

3.2s avg

Import

387ms

Disk

26MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.4.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.400s · 27.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.2s · import 0.374s · 28MB

26MB installed

● package 26MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

LazyModel

✓ from lazy_model import LazyModel

This example demonstrates how to define a `LazyModel` and use `lazy_parse` to defer field validation until access. It also shows that Pydantic validators still apply when a field is accessed for the first time.

from lazy_model import LazyModel from pydantic import validator class Sample(LazyModel): i: int s: str @validator("s") def s_upper(cls, v): return v.upper() # Create an instance with lazy parsing obj = Sample.lazy_parse({"i": "10", "s": "test"}) # At this point, 'i' and 's' are stored in a raw format (NAO - Not An Object) print(f"Initial object dict: {obj.__dict__}") # Accessing 's' triggers its parsing and validation print(f"Accessing s: {obj.s}") # Output: TEST print(f"After 's' access: {obj.__dict__}") # Accessing 'i' triggers its parsing and validation print(f"Accessing i: {obj.i}, type: {type(obj.i)}") # Output: 10, <class 'int'> print(f"After 'i' access: {obj.__dict__}") # Both fields are now parsed

Debug

Known issues

gotchaFields parsed with `lazy_parse` are not fully validated by Pydantic until they are first accessed. This means initial model instantiation might succeed even if some lazily loaded fields contain invalid data, with validation errors only surfacing upon field access.

fix

Be aware that Pydantic's full validation for lazy fields occurs on first access. If strict upfront validation is required for all fields, consider using standard Pydantic model instantiation or explicitly accessing all fields after lazy parsing to trigger their validation.

affects: All versions

gotchaThe underlying mechanism of `lazy-model` interacts with Pydantic's internal object representation. While the library handles this, direct manual manipulation of `__dict__` for fields intended to be lazy can lead to unexpected behavior or bypass the lazy loading/validation mechanism.

fix

Always interact with `LazyModel` instances and their fields through their public API and defined properties. Avoid directly manipulating `obj.__dict__` for lazily parsed fields unless you fully understand the implications and the library's internal workings.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'lazy_model'

The 'lazy-model' library has not been installed in your Python environment or there's a typo in the import statement.

fix

Install the library using pip: `pip install lazy-model`

from lazy_model import LazyModel

This isn't an error message itself, but a common search query indicating a user is trying to import the main class and might be looking for correct usage or encountering an issue with the import statement (e.g., ModuleNotFoundError or ImportError if using an incorrect sub-module).

fix

Ensure `lazy-model` is installed and the import path is correct. The primary class for lazy parsing is typically `LazyModel` from the top-level package: `from lazy_model import LazyModel`

pydantic.error_wrappers.ValidationError: 1 validation error for MyLazyModel

A Pydantic validation error occurs when a lazily-accessed field's underlying data does not conform to the type hints or validation rules defined in your Pydantic model. This error surfaces only when the field is first accessed.

fix

Inspect the `ValidationError` details to identify which field failed validation and why. Correct the input data or adjust your Pydantic model's field types and validators to match the expected data format. Example: `try: model = MyLazyModel(data) except ValidationError as e: print(e.errors())`

AttributeError: 'LazyModel' object has no attribute 'non_existent_field'

You are attempting to access a field or attribute on a `LazyModel` instance that does not exist in the raw input data provided to the model, nor is it defined as a field in the Pydantic model.

fix

Check your input data to ensure the field exists or verify your Pydantic model definition. If the field is optional, ensure it's handled gracefully (e.g., using `Optional[Type]`).

TypeError: 'dict' object is not callable

This often occurs if a `LazyModel` is initialized with a dictionary, and then an attempt is made to 'call' a dictionary key as if it were a method, or if a Pydantic model's field expects a callable but receives a non-callable value after lazy evaluation.

fix

Ensure you are accessing dictionary elements using square brackets (`my_lazy_model.my_field['key']`) and not parentheses (`my_lazy_model.my_field('key')`). Verify that any Pydantic fields expecting callable types are provided with actual callable objects, or that data accessed lazily is of the expected type before operations.

Upgrade

Version history

0.4.0latest on PyPI · released Aug 7, 2025

Audit

Dependencies

pydanticrequiredlazy-model is built on top of Pydantic models and requires it for its core functionality.

Agent activity

7 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/lazy-model/ ↗