grandschemathings

Automatic JSON serialization, deserialization, and schema generation for Python dataclasses.

The grandschemathings Python package provides automatic loading and saving of JSON based on Python objects, with validation against an automatically-generated schema. It is designed to make it easy to serialize and deserialize objects to and from JSON.

Repository: github.com/cambridgeconsultants/GrandSchemaThings

User Guide

System Requirements

• Python >= 3.13

Installation

Install from PyPI using pip:

pip install grandschemathings

Or, if you use uv or Poetry:

uv add grandschemathings
poetry add grandschemathings

Usage

Simple Usage Example

Here's a simple example to illustrate how you can use grandschemathings to serialize and deserialize an object.

from dataclasses import dataclass
from pathlib import Path

from grandschemathings import GrandSchemaThings


@dataclass
class MyData(GrandSchemaThings):
    name: str
    age: int


# Create an instance
data = MyData(name="Alice", age=30)

# Serialize to JSON file
data.to_file(Path("data.json"), pretty=True)

# Deserialize from JSON file
loaded_data = MyData.from_file(Path("data.json"))
print(loaded_data)

Complex Usage Example

This demonstrates how to handle nested objects and dictionaries with enum keys.

from dataclasses import dataclass
from enum import Enum
from pathlib import Path

from grandschemathings import GrandSchemaThings


class Hobby(Enum):
    READING = "reading"
    CYCLING = "cycling"
    COOKING = "cooking"
    GARDENING = "gardening"


@dataclass
class Address(GrandSchemaThings):
    street: str
    city: str
    postcode: str


@dataclass
class User(GrandSchemaThings):
    name: str
    age: int
    address: Address
    hobbies: dict[Hobby, int]


# Create an instance
user = User(
    name="Bob",
    age=25,
    address=Address(street="456 Elm St", city="Faketown", postcode="AB12 3CD"),
    hobbies={Hobby.READING: 5, Hobby.CYCLING: 3, Hobby.COOKING: 4, Hobby.GARDENING: 1},
)

# Serialize to JSON file
user.to_file(Path("user.json"), pretty=True)

# Deserialize from JSON file
loaded_user = User.from_file(Path("user.json"))
print(loaded_user)

API Reference

The following instance and class methods are available for GrandSchemaThings objects.

Developer Guide

Development Setup

To modify GrandSchemaThings, you can clone the repository and install the development dependencies using Poetry:

1. Install Poetry: If you haven't already got Poetry installed, follow the instructions on their website.
2. Clone the repository:

   git clone https://github.com/cambridgeconsultants/GrandSchemaThings.git
   cd grandschemathings
   

3. Install dependencies:

   poetry install
   

Running Tests

Run the validation suite:

poetry run validate

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.