voltwire-db-types-json 0.0.1__tar.gz

voltwire_db_types_json-0.0.1/.gitignore

@@ -0,0 +1,221 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Local tool state
+.omc/

voltwire_db_types_json-0.0.1/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.5
+Name: voltwire-db-types-json
+Version: 0.0.1
+Summary: Custom SQLAlchemy JSONB column types backed by Pydantic models
+Author-email: Hermann Steidel <hsteidel.software@gmail.com>
+License-Expression: MIT
+Requires-Python: <4.0,>=3.13
+Requires-Dist: pydantic<3,>=2.9
+Requires-Dist: sqlalchemy<3,>=2.0
+Description-Content-Type: text/markdown
+
+<img src="https://raw.githubusercontent.com/hsteidel/voltwire/main/assets/icons/db-types-json.svg" alt="" width="56" height="56" align="left">
+
+# voltwire-db-types-json
+
+Custom SQLAlchemy column types for PostgreSQL JSONB columns, backed by Pydantic models. Handles serialisation, deserialisation, and validation transparently — your columns read and write Pydantic model instances directly.
+
+## Installation
+
+```bash
+pip install voltwire-db-types-json
+# or with Poetry:
+poetry add voltwire-db-types-json
+```
+
+## Types
+
+### `JSONBList[T]` — JSONB array as a list of Pydantic models
+
+Returns an empty list when the column value is `NULL`.
+
+```python
+from pydantic import BaseModel
+from sqlalchemy.orm import mapped_column, Mapped
+from voltwire.db.types.json import JSONBList
+
+class Tag(BaseModel):
+    name: str
+    colour: str
+
+class Article(Base):
+    __tablename__ = "articles"
+    tags: Mapped[list[Tag]] = mapped_column(JSONBList(Tag), default=list)
+```
+
+### `JSONBObject[T]` — JSONB object as a single Pydantic model
+
+Returns `None` when the column value is `NULL` or validation fails (logs an error, does not raise).
+
+```python
+from voltwire.db.types.json import JSONBObject
+
+class Address(BaseModel):
+    street: str
+    city: str
+
+class User(Base):
+    __tablename__ = "users"
+    address: Mapped[Address | None] = mapped_column(JSONBObject(Address), nullable=True)
+```
+
+## Logging
+
+Validation errors in `JSONBObject` are logged to the `voltwire.db.types.json.types` logger namespace and return `None` rather than raising — this prevents a single bad row from crashing the application.
+
+```python
+import logging
+logging.getLogger("voltwire.db.types.json").setLevel(logging.DEBUG)
+```

voltwire_db_types_json-0.0.1/README.md

@@ -0,0 +1,58 @@
+<img src="https://raw.githubusercontent.com/hsteidel/voltwire/main/assets/icons/db-types-json.svg" alt="" width="56" height="56" align="left">
+
+# voltwire-db-types-json
+
+Custom SQLAlchemy column types for PostgreSQL JSONB columns, backed by Pydantic models. Handles serialisation, deserialisation, and validation transparently — your columns read and write Pydantic model instances directly.
+
+## Installation
+
+```bash
+pip install voltwire-db-types-json
+# or with Poetry:
+poetry add voltwire-db-types-json
+```
+
+## Types
+
+### `JSONBList[T]` — JSONB array as a list of Pydantic models
+
+Returns an empty list when the column value is `NULL`.
+
+```python
+from pydantic import BaseModel
+from sqlalchemy.orm import mapped_column, Mapped
+from voltwire.db.types.json import JSONBList
+
+class Tag(BaseModel):
+    name: str
+    colour: str
+
+class Article(Base):
+    __tablename__ = "articles"
+    tags: Mapped[list[Tag]] = mapped_column(JSONBList(Tag), default=list)
+```
+
+### `JSONBObject[T]` — JSONB object as a single Pydantic model
+
+Returns `None` when the column value is `NULL` or validation fails (logs an error, does not raise).
+
+```python
+from voltwire.db.types.json import JSONBObject
+
+class Address(BaseModel):
+    street: str
+    city: str
+
+class User(Base):
+    __tablename__ = "users"
+    address: Mapped[Address | None] = mapped_column(JSONBObject(Address), nullable=True)
+```
+
+## Logging
+
+Validation errors in `JSONBObject` are logged to the `voltwire.db.types.json.types` logger namespace and return `None` rather than raising — this prevents a single bad row from crashing the application.
+
+```python
+import logging
+logging.getLogger("voltwire.db.types.json").setLevel(logging.DEBUG)
+```

voltwire_db_types_json-0.0.1/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "voltwire-db-types-json"
+version = "0.0.1"
+description = "Custom SQLAlchemy JSONB column types backed by Pydantic models"
+authors = [{name = "Hermann Steidel", email = "hsteidel.software@gmail.com"}]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.13,<4.0"
+dependencies = [
+    "sqlalchemy>=2.0,<3",
+    "pydantic>=2.9,<3",
+]
+
+[dependency-groups]
+dev = ["pytest>=8.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/voltwire"]

voltwire_db_types_json-0.0.1/src/voltwire/db/types/json/__init__.py

@@ -0,0 +1,8 @@
+from voltwire.db.types.json.types import JSONBList, JSONBObject
+
+__version__ = "0.0.0"
+
+__all__ = [
+    "JSONBList",
+    "JSONBObject",
+]

voltwire_db_types_json-0.0.1/src/voltwire/db/types/json/types.py

@@ -0,0 +1,83 @@
+import logging
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel, ValidationError
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.types import TypeDecorator
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class JSONBList(TypeDecorator, Generic[T]):
+    """SQLAlchemy column type for a JSONB array, deserialized as a list of Pydantic models.
+
+    Returns an empty list when the column value is ``NULL``.
+
+    Example::
+
+        class Tag(BaseModel):
+            name: str
+            colour: str
+
+        class Article(Base):
+            tags: Mapped[list[Tag]] = mapped_column(JSONBList(Tag), default=list)
+    """
+
+    impl = JSONB
+
+    def __init__(self, item_class: type[T]):
+        super().__init__()
+        self.item_class = item_class
+
+    def process_result_value(self, value, dialect) -> list[T]:
+        if value is None:
+            return []
+        return [self.item_class.model_validate(item) for item in value]
+
+    def process_bind_param(self, value: list[T] | None, dialect):
+        if value is None:
+            return None
+        return [item.model_dump(mode="json") for item in value]
+
+
+class JSONBObject(TypeDecorator, Generic[T]):
+    """SQLAlchemy column type for a JSONB object, deserialised as a single Pydantic model.
+
+    Returns ``None`` when the column value is ``NULL`` or validation fails (logs an error).
+
+    Example::
+
+        class Address(BaseModel):
+            street: str
+            city: str
+
+        class User(Base):
+            address: Mapped[Address | None] = mapped_column(JSONBObject(Address), nullable=True)
+    """
+
+    impl = JSONB
+    cache_ok = True
+
+    def __init__(self, item_class: type[T]):
+        super().__init__()
+        self.item_class = item_class
+
+    def process_result_value(self, value, dialect) -> T | None:
+        if value is None:
+            return None
+        try:
+            return self.item_class.model_validate(value)
+        except ValidationError as e:
+            logger.error(
+                "JSONBObject validation failed for %s - returning None to prevent crash: %s",
+                self.item_class.__name__,
+                e,
+            )
+            return None
+
+    def process_bind_param(self, value: T | None, dialect):
+        if value is None:
+            return None
+        return value.model_dump(mode="json")

voltwire_db_types_json-0.0.1/tests/test_json_types.py

@@ -0,0 +1,64 @@
+from pydantic import BaseModel
+
+from voltwire.db.types.json import JSONBList, JSONBObject
+
+
+# --- Fixtures ---
+
+class Tag(BaseModel):
+    name: str
+    colour: str
+
+
+class Address(BaseModel):
+    street: str
+    city: str
+
+
+# --- JSONBList ---
+
+class TestJSONBList:
+    def test_process_result_value_deserialises_list(self):
+        col = JSONBList(Tag)
+        result = col.process_result_value([{"name": "python", "colour": "blue"}], dialect=None)
+        assert result == [Tag(name="python", colour="blue")]
+
+    def test_process_result_value_returns_empty_list_for_null(self):
+        col = JSONBList(Tag)
+        assert col.process_result_value(None, dialect=None) == []
+
+    def test_process_bind_param_serialises_list(self):
+        col = JSONBList(Tag)
+        result = col.process_bind_param([Tag(name="python", colour="blue")], dialect=None)
+        assert result == [{"name": "python", "colour": "blue"}]
+
+    def test_process_bind_param_returns_none_for_null(self):
+        col = JSONBList(Tag)
+        assert col.process_bind_param(None, dialect=None) is None
+
+
+# --- JSONBObject ---
+
+class TestJSONBObject:
+    def test_process_result_value_deserialises_object(self):
+        col = JSONBObject(Address)
+        result = col.process_result_value({"street": "1 Main St", "city": "Springfield"}, dialect=None)
+        assert result == Address(street="1 Main St", city="Springfield")
+
+    def test_process_result_value_returns_none_for_null(self):
+        col = JSONBObject(Address)
+        assert col.process_result_value(None, dialect=None) is None
+
+    def test_process_result_value_returns_none_on_validation_error(self):
+        col = JSONBObject(Address)
+        result = col.process_result_value({"bad": "data"}, dialect=None)
+        assert result is None
+
+    def test_process_bind_param_serialises_object(self):
+        col = JSONBObject(Address)
+        result = col.process_bind_param(Address(street="1 Main St", city="Springfield"), dialect=None)
+        assert result == {"street": "1 Main St", "city": "Springfield"}
+
+    def test_process_bind_param_returns_none_for_null(self):
+        col = JSONBObject(Address)
+        assert col.process_bind_param(None, dialect=None) is None

voltwire_db_types_json-0.0.1/tests/test_sample.py

@@ -0,0 +1,6 @@
+from voltwire.db.types.json import __version__
+
+
+def test_version():
+    assert isinstance(__version__, str)
+    assert len(__version__) > 0