Hologram Library

0.0.16 · active · verified Sat Apr 11

Hologram is a Python library that generates JSON schemas from standard Python dataclasses. It provides a `JsonSchemaMixin` that, when added to a dataclass, enables automatic schema generation and object parsing from JSON data. The current version is 0.0.16, with releases being infrequent.

Warnings

gotcha Hologram is in a `0.0.x` versioning stage and has infrequent releases (last release May 2022). This may mean slower adoption of new Python features, types, or addressing breaking changes in dependent libraries (like `jsonschema`).
Fix: Review the GitHub repository's issues and PRs for current activity and known compatibility problems with newer Python versions or type hints before relying on it for critical projects. Consider contributing or forking if you require active maintenance.
gotcha For complex type hints or custom schema modifications (e.g., adding descriptions, examples, titles), understanding and correctly using `hologram.FieldSpec` is crucial. Omitting it for complex types might lead to generic or incorrect schema generation.
Fix: Always use `FieldSpec` for `Union`, `Optional` with default values where custom metadata is desired, and any other complex type requiring specific JSON schema attributes. Refer to the official documentation for advanced `FieldSpec` usage.
gotcha Hologram introduced optional `mashumaro` integration in v0.0.13, which is not the default serialization/deserialization path. If you intend to use `mashumaro` for its performance or specific features, you'll need to explicitly configure it, which might diverge from the basic `JsonSchemaMixin` usage.
Fix: If `mashumaro` is desired, consult `hologram`'s GitHub README or source code for examples on how to integrate `mashumaro`'s `DataClassDictMixin` with `JsonSchemaMixin` for your dataclasses.

Install

pip install hologram Install stable version

Imports

JsonSchemaMixin
```
from hologram import JsonSchemaMixin
```
The primary mixin for schema generation is directly available from the top-level 'hologram' package.
FieldSpec
```
from hologram import FieldSpec
```
ValidationError
```
from hologram import ValidationError
```

Quickstart

This quickstart demonstrates how to define dataclasses with `JsonSchemaMixin`, including optional fields, lists, unions with `FieldSpec`, and nested models. It then shows how to generate a JSON schema from the dataclass and parse a Python dictionary into a dataclass instance, leveraging Hologram's validation capabilities.

from dataclasses import dataclass, field
from typing import List, Optional, Union
from hologram import FieldSpec, JsonSchemaMixin

@dataclass
class SubModel(JsonSchemaMixin):
    id: int
    name: str

@dataclass
class MyModel(JsonSchemaMixin):
    id: int
    name: str
    optional_field: Optional[str] = None
    list_of_strings: List[str] = field(default_factory=list)
    union_field: Union[str, int] = FieldSpec(
        title='Union Field',
        description='This is a union field.'
    )
    nested_model: SubModel = field(default_factory=lambda: SubModel(id=1, name="default"))

# Generate JSON schema
schema = MyModel.json_schema()
print("Generated Schema:", schema)

# Parse object from dictionary
data = {'id': 1, 'name': 'test model', 'list_of_strings': ['a', 'b'], 'nested_model': {'id': 2, 'name': 'nested test'}} 
try:
    instance = MyModel.parse_object(data)
    print("Parsed Instance:", instance)
except Exception as e:
    print(f"Error parsing object: {e}")

view raw JSON →