pydantic-store 0.1.0__tar.gz

pydantic_store-0.1.0/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) 2025 mySociety
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.

pydantic_store-0.1.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: pydantic-store
+Version: 0.1.0
+Summary: Helper models and backports
+License: MIT
+License-File: LICENSE.md
+Author: mySociety
+Author-email: alex.parsons@mysociety.org
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: pydantic (>=2.0)
+Project-URL: Homepage, https://github.com/mysociety/pydantic-store
+Project-URL: Repository, https://github.com/mysociety/pydantic-store
+Description-Content-Type: text/markdown
+
+# pydantic-store
+
+A collection of Pydantic models and storage approaches for ease of reading to/from files or creating caches. 
+
+## Installation
+
+```bash
+pip install pydantic-store
+```
+
+### Optional Dependencies
+
+Additional dependencies needed for storing as YAML or TOML (not included to keep the dependency limited to pydantic)
+
+```bash
+# For YAML support
+pip install ruamel.yaml
+
+# For TOML writing support  
+pip install tomli-w
+
+# For TOML reading on Python < 3.11
+pip install tomli
+```
+
+## Quick Start
+
+```python
+from pydantic_store import BaseModel, ListModel, DictModel, JsonStore, PydanticDBM
+
+# Define your models
+class User(BaseModel):
+    name: str
+    age: int
+    email: str
+
+# Create and save to file
+user = User(name="Alice", age=30, email="alice@example.com")
+user.to_file("user.json")
+
+# Load from file
+loaded_user = User.from_file("user.json")
+```
+
+## Model Types
+
+### BaseModel
+
+Enhanced Pydantic BaseModel with file I/O capabilities.
+
+```python
+from pydantic_store import BaseModel
+
+class Config(BaseModel):
+    database_url: str
+    debug: bool = False
+    max_connections: int = 10
+
+# Save to different formats
+config = Config(database_url="postgresql://localhost/mydb")
+config.to_file("config.json")        # JSON format
+config.to_file("config.yaml")        # YAML format  
+config.to_file("config.toml")        # TOML format
+
+# Load from file (format auto-detected by extension)
+config = Config.from_file("config.yaml")
+```
+
+### RootModel
+
+A generic root model for wrapping single values with validation.
+
+```python
+from pydantic_store import RootModel
+
+class Port(RootModel[int]):
+    pass
+
+port = Port(8080)
+port.to_file("port.json")  # Saves: 8080
+loaded_port = Port.from_file("port.json")
+```
+
+### ListModel
+
+A list-like model that behaves like a Python list while providing Pydantic validation.
+
+```python
+from pydantic_store import ListModel
+
+TodoList = ListModel[str]
+
+todos = TodoList(["Buy groceries", "Walk the dog"])
+
+# Use like a regular list
+todos.append("Read a book")
+todos.extend(["Exercise", "Cook dinner"])
+print(len(todos))  # 5
+print(todos[0])    # "Buy groceries"
+
+# Persist to file
+todos.to_file("todos.json")
+
+# Load from file
+loaded_todos = TodoList.from_file("todos.json")
+```
+
+### DictModel  
+
+A dictionary-like model that behaves like a Python dict with validation.
+
+```python
+from pydantic_store import DictModel
+
+Settings = DictModel[str, int]
+
+settings = Settings({"timeout": 30, "retries": 3})
+
+# Use like a regular dict
+settings["max_workers"] = 4
+settings.update({"cache_size": 1000})
+print(settings.keys())
+print(len(settings))
+
+# Persist to file
+settings.to_file("settings.yaml")
+```
+
+### PydanticDBM
+
+A wrapper around the sqlite DBM backend (backported from 3.14) to store and retrieve pydantic models. 
+
+```python
+from pydantic_store import PydanticDBM
+from pydantic import BaseModel
+
+class User(BaseModel):
+    name: str
+    age: int
+
+UserDBM = PydanticDBM[User]
+
+# Method 1: Type subscription
+with UserDBM("users.db") as db:
+    user = User(name="Alice", age=30)
+    db["alice"] = user
+    retrieved_user = db["alice"]  # Automatically validated as User
+
+# Method 2: Explicit storage format
+with PydanticDBM("users.db", storage_format=User) as db:
+    db["bob"] = User(name="Bob", age=25)
+```
+
+### JsonStore
+
+A persistent dictionary that automatically saves changes to disk.
+
+```python
+from pydantic_store import JsonStore
+from pathlib import Path
+
+# Connect to a JSON file (creates if doesn't exist)
+store = JsonStore[str].connect(Path("data.json"))
+
+# Changes are automatically persisted
+store["user:1"] = "Alice"
+store["user:2"] = "Bob" 
+
+# Data is immediately written to data.json
+print(store["user:1"])  # "Alice"
+```
+
+### Supported Formats
+
+pydantic-store supports multiple file formats with automatic format detection:
+
+- **JSON**: Always available
+- **YAML**: Human-readable format (requires `ruamel.yaml`)
+- **TOML**: Configuration-friendly format (requires `tomli` for reading, `tomli-w` for writing)
+
+
+You can also specify the format:
+
+```python
+model.to_file("data.txt", file_format="json")
+```
+
+## Licence
+
+MIT Licence - see LICENSE.md for details.

pydantic_store-0.1.0/README.md

@@ -0,0 +1,190 @@
+# pydantic-store
+
+A collection of Pydantic models and storage approaches for ease of reading to/from files or creating caches. 
+
+## Installation
+
+```bash
+pip install pydantic-store
+```
+
+### Optional Dependencies
+
+Additional dependencies needed for storing as YAML or TOML (not included to keep the dependency limited to pydantic)
+
+```bash
+# For YAML support
+pip install ruamel.yaml
+
+# For TOML writing support  
+pip install tomli-w
+
+# For TOML reading on Python < 3.11
+pip install tomli
+```
+
+## Quick Start
+
+```python
+from pydantic_store import BaseModel, ListModel, DictModel, JsonStore, PydanticDBM
+
+# Define your models
+class User(BaseModel):
+    name: str
+    age: int
+    email: str
+
+# Create and save to file
+user = User(name="Alice", age=30, email="alice@example.com")
+user.to_file("user.json")
+
+# Load from file
+loaded_user = User.from_file("user.json")
+```
+
+## Model Types
+
+### BaseModel
+
+Enhanced Pydantic BaseModel with file I/O capabilities.
+
+```python
+from pydantic_store import BaseModel
+
+class Config(BaseModel):
+    database_url: str
+    debug: bool = False
+    max_connections: int = 10
+
+# Save to different formats
+config = Config(database_url="postgresql://localhost/mydb")
+config.to_file("config.json")        # JSON format
+config.to_file("config.yaml")        # YAML format  
+config.to_file("config.toml")        # TOML format
+
+# Load from file (format auto-detected by extension)
+config = Config.from_file("config.yaml")
+```
+
+### RootModel
+
+A generic root model for wrapping single values with validation.
+
+```python
+from pydantic_store import RootModel
+
+class Port(RootModel[int]):
+    pass
+
+port = Port(8080)
+port.to_file("port.json")  # Saves: 8080
+loaded_port = Port.from_file("port.json")
+```
+
+### ListModel
+
+A list-like model that behaves like a Python list while providing Pydantic validation.
+
+```python
+from pydantic_store import ListModel
+
+TodoList = ListModel[str]
+
+todos = TodoList(["Buy groceries", "Walk the dog"])
+
+# Use like a regular list
+todos.append("Read a book")
+todos.extend(["Exercise", "Cook dinner"])
+print(len(todos))  # 5
+print(todos[0])    # "Buy groceries"
+
+# Persist to file
+todos.to_file("todos.json")
+
+# Load from file
+loaded_todos = TodoList.from_file("todos.json")
+```
+
+### DictModel  
+
+A dictionary-like model that behaves like a Python dict with validation.
+
+```python
+from pydantic_store import DictModel
+
+Settings = DictModel[str, int]
+
+settings = Settings({"timeout": 30, "retries": 3})
+
+# Use like a regular dict
+settings["max_workers"] = 4
+settings.update({"cache_size": 1000})
+print(settings.keys())
+print(len(settings))
+
+# Persist to file
+settings.to_file("settings.yaml")
+```
+
+### PydanticDBM
+
+A wrapper around the sqlite DBM backend (backported from 3.14) to store and retrieve pydantic models. 
+
+```python
+from pydantic_store import PydanticDBM
+from pydantic import BaseModel
+
+class User(BaseModel):
+    name: str
+    age: int
+
+UserDBM = PydanticDBM[User]
+
+# Method 1: Type subscription
+with UserDBM("users.db") as db:
+    user = User(name="Alice", age=30)
+    db["alice"] = user
+    retrieved_user = db["alice"]  # Automatically validated as User
+
+# Method 2: Explicit storage format
+with PydanticDBM("users.db", storage_format=User) as db:
+    db["bob"] = User(name="Bob", age=25)
+```
+
+### JsonStore
+
+A persistent dictionary that automatically saves changes to disk.
+
+```python
+from pydantic_store import JsonStore
+from pathlib import Path
+
+# Connect to a JSON file (creates if doesn't exist)
+store = JsonStore[str].connect(Path("data.json"))
+
+# Changes are automatically persisted
+store["user:1"] = "Alice"
+store["user:2"] = "Bob" 
+
+# Data is immediately written to data.json
+print(store["user:1"])  # "Alice"
+```
+
+### Supported Formats
+
+pydantic-store supports multiple file formats with automatic format detection:
+
+- **JSON**: Always available
+- **YAML**: Human-readable format (requires `ruamel.yaml`)
+- **TOML**: Configuration-friendly format (requires `tomli` for reading, `tomli-w` for writing)
+
+
+You can also specify the format:
+
+```python
+model.to_file("data.txt", file_format="json")
+```
+
+## Licence
+
+MIT Licence - see LICENSE.md for details.

pydantic_store-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[tool.poetry]
+name = "pydantic-store"
+version = "0.1.0"
+description = "Helper models and backports"
+authors = ["mySociety <alex.parsons@mysociety.org>"]
+readme = "README.md"
+license = "MIT"
+homepage = "https://github.com/mysociety/pydantic-store"
+repository = "https://github.com/mysociety/pydantic-store"
+include = [
+    "LICENSE.md",
+]
+
+[tool.poetry_bumpversion.file."src/pydantic_store/__init__.py"]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+pydantic = ">=2.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.1.2"
+pytest-cov = "^3.0.0"
+pylint = "^2.12.2"
+ruff = "^0.4.4"
+pyright = "^1.1"
+toml = "^0.10.2"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"

pydantic_store-0.1.0/src/pydantic_store/__init__.py

@@ -0,0 +1,19 @@
+"""
+Helper models and backports
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BaseModel",
+    "RootModel",
+    "ListModel",
+    "DictModel",
+    "JsonStore",
+    "PydanticDBM",
+]
+
+from .dbm import PydanticDBM
+from .models import BaseModel, DictModel, JsonStore, ListModel, RootModel

pydantic_store-0.1.0/src/pydantic_store/dbm.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal, Optional, TypeVar, Union
+
+from pydantic import TypeAdapter
+
+from .dbm_sqlite import _Database  # type: ignore
+
+T = TypeVar("T")
+PathLike = Union[str, Path]
+FlagOptions = Literal["r", "w", "c", "n"]
+
+
+class PydanticDBM(_Database[T]):
+    default_storage_format = None
+
+    def __class_getitem__(cls, storage_format: type[T]):
+        class _child(cls):
+            default_storage_format = storage_format
+
+        _child.__name__ = cls.__name__
+
+        return _child
+
+    def __init__(
+        self,
+        path: PathLike,
+        /,
+        *,
+        flag: FlagOptions = "c",
+        mode: int = 0o600,
+        storage_format: Optional[type[T]] = None,
+    ):
+        super().__init__(path, flag=flag, mode=mode)
+        self.storage_format = storage_format or self.default_storage_format
+        if not self.storage_format:
+            raise ValueError(
+                "storage_format must be provided either as argument or class attribute"
+            )
+        self.type_adapter = TypeAdapter(self.storage_format)
+
+    def __getitem__(self, key: str) -> T:
+        return self.type_adapter.validate_json(super().__getitem__(key))  # type: ignore
+
+    def __setitem__(self, key: str, value: T) -> None:
+        super().__setitem__(key, self.type_adapter.dump_json(value))  # type: ignore
+
+
+def open(
+    filename: PathLike,
+    /,
+    flag: FlagOptions = "c",
+    mode: int = 0o600,
+    storage_format: type[T] = str,
+) -> PydanticDBM[T]:
+    return PydanticDBM(filename, flag=flag, mode=mode, storage_format=storage_format)

pydantic_store-0.1.0/src/pydantic_store/dbm_sqlite.py

@@ -0,0 +1,165 @@
+"""
+Backport of dbm.sqlite3 module for Pydantic IO.
+Added type annotations and generics support.
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+from collections.abc import Iterator, KeysView, MutableMapping
+from contextlib import closing, suppress
+from pathlib import Path
+from types import TracebackType
+from typing import Any, Literal, TypeVar, Union
+
+BUILD_TABLE = """
+  CREATE TABLE IF NOT EXISTS Dict (
+    key BLOB UNIQUE NOT NULL,
+    value BLOB NOT NULL
+  )
+"""
+GET_SIZE = "SELECT COUNT (key) FROM Dict"
+LOOKUP_KEY = "SELECT value FROM Dict WHERE key = CAST(? AS BLOB)"
+STORE_KV = "REPLACE INTO Dict (key, value) VALUES (CAST(? AS BLOB), CAST(? AS BLOB))"
+DELETE_KEY = "DELETE FROM Dict WHERE key = CAST(? AS BLOB)"
+ITER_KEYS = "SELECT key FROM Dict"
+
+
+class error(OSError):
+    pass
+
+
+_ERR_CLOSED = "DBM object has already been closed"
+_ERR_REINIT = "DBM object does not support reinitialization"
+
+
+def _normalize_uri(path: Union[str, os.PathLike[str]]) -> str:
+    path = Path(path)
+    uri = path.absolute().as_uri()
+    while "//" in uri:
+        uri = uri.replace("//", "/")
+    return uri
+
+
+T = TypeVar("T")
+
+
+class _Database(MutableMapping[str, T]):
+    def __init__(
+        self, path: Union[str, os.PathLike[str]], /, *, flag: str, mode: int
+    ) -> None:
+        if hasattr(self, "_cx"):
+            raise error(_ERR_REINIT)
+
+        path = os.fsdecode(path)
+        if flag == "r":
+            flag = "ro"
+        elif flag == "w":
+            flag = "rw"
+        elif flag == "c":
+            flag = "rwc"
+            Path(path).touch(mode=mode, exist_ok=True)
+        elif flag == "n":
+            flag = "rwc"
+            Path(path).unlink(missing_ok=True)
+            Path(path).touch(mode=mode)
+        else:
+            raise ValueError(f"Flag must be one of 'r', 'w', 'c', or 'n', not {flag!r}")
+
+        # We use the URI format when opening the database.
+        uri = _normalize_uri(path)
+        uri = f"{uri}?mode={flag}"
+        if flag == "ro":
+            # Add immutable=1 to allow read-only SQLite access even if wal/shm missing
+            uri += "&immutable=1"
+
+        try:
+            self._cx = sqlite3.connect(uri, isolation_level=None, uri=True)
+        except sqlite3.Error as exc:
+            raise error(str(exc))
+
+        if flag != "ro":
+            # This is an optimization only; it's ok if it fails.
+            with suppress(sqlite3.OperationalError):
+                self._cx.execute("PRAGMA journal_mode = wal")
+
+            if flag == "rwc":
+                self._execute(BUILD_TABLE)
+
+    def _execute(self, *args: Any, **kwargs: Any) -> closing[sqlite3.Cursor]:
+        if not self._cx:
+            raise error(_ERR_CLOSED)
+        try:
+            return closing(self._cx.execute(*args, **kwargs))
+        except sqlite3.Error as exc:
+            raise error(str(exc))
+
+    def __len__(self) -> int:
+        with self._execute(GET_SIZE) as cu:
+            row = cu.fetchone()
+        return row[0]
+
+    def __getitem__(self, key: str) -> T:
+        with self._execute(LOOKUP_KEY, (key,)) as cu:
+            row = cu.fetchone()
+        if not row:
+            raise KeyError(key)
+        return row[0]
+
+    def __setitem__(self, key: str, value: T) -> None:
+        self._execute(STORE_KV, (key, value))
+
+    def __delitem__(self, key: str) -> None:
+        with self._execute(DELETE_KEY, (key,)) as cu:
+            if not cu.rowcount:
+                raise KeyError(key)
+
+    def __iter__(self) -> Iterator[str]:
+        try:
+            with self._execute(ITER_KEYS) as cu:
+                for row in cu:
+                    yield row[0].decode("utf-8")
+        except sqlite3.Error as exc:
+            raise error(str(exc))
+
+    def close(self) -> None:
+        if self._cx:
+            self._cx.close()
+            self._cx = None
+
+    def keys(self) -> KeysView[str]:
+        return super().keys()
+
+    def __enter__(self) -> _Database[T]:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+def open(
+    filename: Union[str, os.PathLike[str]],
+    /,
+    flag: Literal["r", "w", "c", "n"] = "r",
+    mode: int = 0o666,
+) -> _Database[bytes]:
+    """Open a dbm.sqlite3 database and return the dbm object.
+
+    The 'filename' parameter is the name of the database file.
+
+    The optional 'flag' parameter can be one of ...:
+        'r' (default): open an existing database for read only access
+        'w': open an existing database for read/write access
+        'c': create a database if it does not exist; open for read/write access
+        'n': always create a new, empty database; open for read/write access
+
+    The optional 'mode' parameter is the Unix file access mode of the database;
+    only used when creating a new database. Default: 0o666.
+    """
+    return _Database(filename, flag=flag, mode=mode)

pydantic_store-0.1.0/src/pydantic_store/models.py

@@ -0,0 +1,387 @@
+"""
+Helper models and backports
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+import json
+from collections.abc import MutableMapping, MutableSequence
+from pathlib import Path
+from typing import (
+    Any,
+    Callable,
+    Iterable,
+    Literal,
+    Mapping,
+    Optional,
+    Protocol,
+    TypeVar,
+    Union,
+    overload,
+)
+
+from pydantic import BaseModel as PydanticBaseModel
+from pydantic import Field, PrivateAttr
+from pydantic import RootModel as PydanticRootModel
+from typing_extensions import Self
+
+# Optional imports for YAML and TOML support
+try:
+    from ruamel.yaml import YAML  # type: ignore
+
+    yaml = YAML()
+    yaml.preserve_quotes = True
+    yaml.width = 4096  # Avoid line wrapping
+except ImportError:
+    yaml = None  # type: ignore
+
+try:
+    import tomllib  # type: ignore
+except ImportError:
+    try:
+        import tomli as tomllib  # type: ignore
+    except ImportError:
+        tomllib = None  # type: ignore
+
+try:
+    import tomli_w  # type: ignore
+except ImportError:
+    tomli_w = None  # type: ignore
+
+ExtraValues = Literal["allow", "ignore", "forbid"]
+FileFormats = Literal["json", "yaml", "toml", "auto"]
+
+
+T = TypeVar("T")
+K = TypeVar("K")
+PathLike = Union[str, Path]
+IncEx = Union[
+    set[int],
+    set[str],
+    Mapping[int, Union["IncEx", bool]],
+    Mapping[str, Union["IncEx", bool]],
+]
+
+
+def file_format_from_file(file_path: Path) -> FileFormats:
+    ext = file_path.suffix.lower()
+    if ext == ".json":
+        return "json"
+    elif ext in {".yaml", ".yml"}:
+        return "yaml"
+    elif ext == ".toml":
+        return "toml"
+    else:
+        raise ValueError(f"Unsupported file extension: {ext}")
+
+
+class BaseModelLike(Protocol):
+    def model_dump(
+        self,
+        *,
+        include: IncEx | None = None,
+        exclude: IncEx | None = None,
+        context: Any | None = None,
+        by_alias: bool = False,
+        exclude_unset: bool = False,
+        exclude_defaults: bool = False,
+        exclude_none: bool = False,
+        round_trip: bool = False,
+        warnings: bool = True,
+        serialize_as_any: bool = False,
+    ) -> dict[str, Any]: ...
+
+    def model_dump_json(
+        self,
+        *,
+        indent: int | None = None,
+        ensure_ascii: bool = False,
+        include: IncEx | None = None,
+        exclude: IncEx | None = None,
+        context: Any | None = None,
+        by_alias: bool | None = None,
+        exclude_unset: bool = False,
+        exclude_defaults: bool = False,
+        exclude_none: bool = False,
+        exclude_computed_fields: bool = False,
+        round_trip: bool = False,
+        warnings: bool | Literal["none", "warn", "error"] = True,
+        fallback: Callable[[Any], Any] | None = None,
+        serialize_as_any: bool = False,
+    ) -> str: ...
+
+    @classmethod
+    def model_validate(
+        cls,
+        obj: Any,
+        *,
+        strict: bool | None = None,
+        extra: ExtraValues | None = None,
+        from_attributes: bool | None = None,
+        context: Any | None = None,
+        by_alias: bool | None = None,
+        by_name: bool | None = None,
+    ) -> Self: ...
+
+    @classmethod
+    def model_validate_json(
+        cls,
+        json_data: str | bytes | bytearray,
+        *,
+        strict: bool | None = None,
+        extra: ExtraValues | None = None,
+        context: Any | None = None,
+        by_alias: bool | None = None,
+        by_name: bool | None = None,
+    ) -> Self: ...
+
+
+TypeBaseModelLike = TypeVar("TypeBaseModelLike", bound=BaseModelLike)
+
+
+def yaml_to_json(yaml_str: str) -> str:
+    """
+    Convert a YAML string to a JSON string.
+
+    Args:
+        yaml_str: YAML string to convert
+
+    Returns:
+        JSON string representation
+
+    Raises:
+        ImportError: If ruamel.yaml is not available
+    """
+    if yaml is None:
+        raise ImportError(
+            "ruamel.yaml is required for YAML support. Install it with: pip install ruamel.yaml"
+        )
+    parsed_data = yaml.load(yaml_str)  # type: ignore
+    return json.dumps(parsed_data)
+
+
+def toml_to_json(toml_str: str) -> str:
+    """
+    Convert a TOML string to a JSON string.
+
+    Args:
+        toml_str: TOML string to convert
+
+    Returns:
+        JSON string representation
+
+    Raises:
+        ImportError: If tomllib/tomli is not available
+    """
+    if tomllib is None:
+        raise ImportError(
+            "tomllib (Python 3.11+) or tomli is required for TOML reading support. "
+            "For Python < 3.11, install with: pip install tomli"
+        )
+    parsed_data = tomllib.loads(toml_str)  # type: ignore
+    return json.dumps(parsed_data)
+
+
+class IOMixin:
+    def to_file(
+        self: BaseModelLike, file_path: PathLike, file_format: FileFormats = "auto"
+    ) -> None:
+        """
+        Save the model to a file in the specified format.
+
+        Args:
+            file_path: Path to the output file.
+            file_format: Format to save the file in ("json", "yaml", or "toml").
+
+        Raises:
+            ImportError: If the required library for the format is not installed.
+            ValueError: If an unsupported file format is specified.
+        """
+        file_path = Path(file_path)
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        if file_format == "auto":
+            file_format = file_format_from_file(file_path)
+
+        if file_format == "json":
+            txt = self.model_dump_json(indent=2)
+        elif file_format == "yaml":
+            if yaml is None:
+                raise ImportError(
+                    "ruamel.yaml is required for YAML support. Install it with: pip install ruamel.yaml"
+                )
+            # Convert to dict first, then to YAML
+            data = self.model_dump()
+            from io import StringIO
+
+            stream = StringIO()
+            yaml.dump(data, stream)  # type: ignore
+            txt = stream.getvalue()
+        elif file_format == "toml":
+            if tomli_w is None:
+                raise ImportError(
+                    "tomli-w is required for TOML writing support. Install it with: pip install tomli-w"
+                )
+            # Convert to dict first, then to TOML
+            data = self.model_dump()
+            # TOML requires a table (dict) at the root level, not arrays
+            if isinstance(data, list):
+                raise ValueError(
+                    "TOML format does not support arrays at the root level. "
+                    "Use JSON or YAML format for list/array data."
+                )
+            txt = tomli_w.dumps(data)  # type: ignore
+        else:
+            raise ValueError(f"Unsupported file format: {file_format}")
+
+        file_path.write_text(txt)  # type: ignore
+
+    @classmethod
+    def from_file(
+        cls: type[TypeBaseModelLike],
+        file_path: PathLike,
+        file_format: FileFormats = "auto",
+    ) -> TypeBaseModelLike:
+        """
+        Load the model from a file in the specified format.
+
+        Args:
+            file_path: Path to the input file.
+            file_format: Format of the input file ("json", "yaml", or "toml").
+
+        Returns:
+            An instance of the model.
+
+        Raises:
+            ImportError: If the required library for the format is not installed.
+            ValueError: If an unsupported file format is specified.
+        """
+        file_path = Path(file_path)
+
+        if file_format == "auto":
+            file_format = file_format_from_file(file_path)
+        if file_format == "json":
+            json_data = file_path.read_text()
+        elif file_format == "yaml":
+            yaml_data = file_path.read_text()
+            json_data = yaml_to_json(yaml_data)
+        elif file_format == "toml":
+            toml_data = file_path.read_text()
+            json_data = toml_to_json(toml_data)
+        else:
+            raise ValueError(f"Unsupported file format: {file_format}")
+
+        return cls.model_validate_json(json_data)
+
+
+class BaseModel(PydanticBaseModel, IOMixin): ...
+
+
+class RootModel(PydanticRootModel[T], IOMixin): ...
+
+
+class ListModel(RootModel[list[T]], MutableSequence[T]):
+    root: list[T] = Field(default_factory=list)  # type: ignore
+
+    def append(self, value: T) -> None:
+        self.root.append(value)
+
+    def extend(self, values: Iterable[T]) -> None:
+        self.root.extend(values)
+
+    @overload
+    def __getitem__(self, index: int) -> T: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> list[T]: ...
+
+    def __getitem__(self, index: int | slice) -> T | list[T]:
+        return self.root[index]
+
+    @overload
+    def __setitem__(self, index: int, value: T) -> None: ...
+
+    @overload
+    def __setitem__(self, index: slice, value: Iterable[T]) -> None: ...
+
+    def __setitem__(self, index: int | slice, value: T | Iterable[T]) -> None:
+        self.root[index] = value  # type: ignore
+
+    def __len__(self) -> int:
+        return len(self.root)
+
+    def __iter__(self):  # type: ignore
+        return iter(self.root)
+
+    def __contains__(self, item: object) -> bool:
+        return item in self.root
+
+    def insert(self, index: int, value: T) -> None:
+        self.root.insert(index, value)
+
+    def __delitem__(self, index: int | slice) -> None:
+        del self.root[index]
+
+
+class DictModel(RootModel[dict[K, T]], MutableMapping[K, T]):
+    root: dict[K, T] = Field(default_factory=dict)  # type: ignore
+
+    def __contains__(self, key: object) -> bool:
+        return key in self.root
+
+    def items(self):
+        return self.root.items()
+
+    def keys(self):
+        return self.root.keys()
+
+    def values(self):
+        return self.root.values()
+
+    def __getitem__(self, key: K) -> T:
+        return self.root[key]
+
+    def __setitem__(self, key: K, value: T) -> None:
+        self.root[key] = value
+
+    def __delitem__(self, key: K) -> None:
+        del self.root[key]
+
+    def __len__(self) -> int:
+        return len(self.root)
+
+    def __iter__(self):  # type: ignore
+        return iter(self.root)
+
+
+class JsonStore(DictModel[str, T]):
+    _file_path: Optional[Path] = PrivateAttr(default=None)
+
+    def __setitem__(self, key: str, value: T) -> None:
+        self.root[key] = value
+        self.save_store()
+
+    def __init__(
+        self,
+        *args: Any,
+        file_path: Optional[Path] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self._file_path = file_path
+
+    def save_store(self) -> None:
+        if self._file_path is None:
+            raise ValueError("File path is not set.")
+        self.to_file(self._file_path)
+
+    @classmethod
+    def connect(cls, file_path: Path) -> JsonStore[T]:
+        if not file_path.exists():
+            obj = cls(file_path=file_path)
+            obj.save_store()
+        obj = cls.from_file(file_path)
+        obj._file_path = file_path
+        return obj