tortoise-extensions 0.0.1__py3-none-any.whl

tortoise_extensions/__init__.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: ISC
+# Copyright: 2026 NiceBots.xyz
+"""Extension field types for Tortoise ORM."""
+
+try:
+    from tortoise_extensions._version import __version__
+except ImportError:
+    __version__ = "0.0.0+dev"
+
+__all__ = ["__version__"]

tortoise_extensions/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.0.1'
+__version_tuple__ = version_tuple = (0, 0, 1)
+
+__commit_id__ = commit_id = None

tortoise_extensions/pydantic.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: ISC
+# Copyright: 2026 NiceBots.xyz
+"""Pydantic-backed JSON field for Tortoise ORM."""
+
+from typing import Any, override
+
+from pydantic import BaseModel
+from tortoise.fields.data import JSONField
+from tortoise.models import Model
+
+
+class PydanticJSONField[T: BaseModel](JSONField[dict[str, object]]):
+    """JSONField that round-trips values through a Pydantic model.
+
+    On save, serializes ``BaseModel`` instances with ``model_dump(mode="json")``
+    before JSON encoding. On load, validates decoded data with the configured
+    Pydantic model, including:
+
+    - JSON strings or bytes (typical for SQLite).
+    - Plain dicts returned by PostgreSQL JSONB drivers such as asyncpg.
+
+    Examples:
+        >>> class MyModel(Model):
+        ...     data: PydanticJSONField[MyPydanticModel] = PydanticJSONField(
+        ...         MyPydanticModel, default=MyPydanticModel
+        ...     )
+    """
+
+    def __init__(self, model_class: type[T], **kwargs: Any) -> None:
+        """Initialize the field.
+
+        Args:
+            model_class: Pydantic model class used for validation.
+            **kwargs: Additional arguments forwarded to ``JSONField``.
+        """
+        self._pydantic_model: type[T] = model_class
+        super().__init__(**kwargs)
+
+    @override
+    def to_python_value(self, value: Any) -> T | None:  # pyright: ignore[reportExplicitAny, reportIncompatibleMethodOverride]
+        """Convert a database value to a Pydantic model instance.
+
+        Args:
+            value: Raw value from the database driver.
+
+        Returns:
+            A validated Pydantic model, or ``None`` when the value is null.
+        """
+        if value is None:
+            return None
+        if isinstance(value, self._pydantic_model):
+            return value
+        if isinstance(value, (str, bytes)):
+            raw = value if isinstance(value, str) else value.decode()
+            return self._pydantic_model.model_validate_json(raw)
+        return self._pydantic_model.model_validate(value)
+
+    @override
+    def to_db_value(self, value: Any, instance: type[Model] | Model) -> str | None:  # pyright: ignore[reportExplicitAny]
+        """Convert a Python value to a JSON string for storage.
+
+        Args:
+            value: Model instance or JSON-serializable data.
+            instance: Tortoise model class or instance (unused).
+
+        Returns:
+            Encoded JSON string, or ``None`` when the value is null.
+        """
+        if isinstance(value, BaseModel):
+            value = value.model_dump(mode="json")
+        return super().to_db_value(value, instance)
+
+
+__all__ = ["PydanticJSONField"]

tortoise_extensions/s3.py

@@ -0,0 +1,279 @@
+# SPDX-License-Identifier: ISC
+# Copyright: 2026 NiceBots.xyz
+"""S3-backed field for Tortoise ORM (via the ``obstore`` package)."""
+
+import sys
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, override
+
+from obstore.store import ObjectStore, S3Store
+from tortoise import fields
+from tortoise.exceptions import ConfigurationError
+from tortoise.models import Model
+
+if sys.version_info >= (3, 14):
+    from uuid import uuid7
+else:
+    from uuid6 import uuid7
+
+if TYPE_CHECKING:
+    from obstore.store import S3Config
+
+_stores: dict[str, ObjectStore] = {}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class S3Storage:
+    """Connection settings for one S3-compatible endpoint.
+
+    Attributes:
+        endpoint: Host and optional port, without scheme (e.g. ``"minio:9000"``).
+        bucket: Bucket holding the objects.
+        access_key: Access key ID.
+        secret_key: Secret access key.
+        region: Signing region, or ``None`` to let ``obstore`` resolve it.
+        ssl: Use ``https`` when ``True``, plain ``http`` when ``False``.
+    """
+
+    endpoint: str
+    bucket: str
+    access_key: str
+    secret_key: str
+    region: str | None = None
+    ssl: bool = True
+
+    def __post_init__(self) -> None:
+        """Validate the endpoint.
+
+        Raises:
+            ValueError: If the endpoint contains a scheme, which ``ssl`` controls.
+        """
+        if "://" in self.endpoint:
+            raise ValueError("S3Storage.endpoint must not contain a scheme, use `ssl` instead")
+
+    def to_store(self) -> S3Store:
+        """Build the ``obstore`` store for these settings.
+
+        Returns:
+            A configured ``S3Store``.
+        """
+        config: S3Config = {
+            "endpoint": f"{'https' if self.ssl else 'http'}://{self.endpoint}",
+            "access_key_id": self.access_key,
+            "secret_access_key": self.secret_key,
+        }
+        if self.region is not None:
+            config["region"] = self.region
+        return S3Store(self.bucket, config=config, client_options={"allow_http": not self.ssl})
+
+
+def init_storages(storages: Mapping[str, S3Storage | ObjectStore]) -> None:
+    """Register the named storages used by ``S3Field``, replacing any previous ones.
+
+    Names are Tortoise app labels (the default storage of every model in that app)
+    or free names referenced through ``S3Field(storage=...)``.
+
+    Args:
+        storages: Storage settings, or ready ``obstore`` stores, by name.
+    """
+    _stores.clear()
+    _stores.update(
+        {name: value.to_store() if isinstance(value, S3Storage) else value for name, value in storages.items()}
+    )
+
+
+def get_store(name: str) -> ObjectStore:
+    """Return a registered store.
+
+    Args:
+        name: Storage name.
+
+    Returns:
+        The registered store.
+
+    Raises:
+        ConfigurationError: If no storage is registered under ``name``.
+    """
+    try:
+        return _stores[name]
+    except KeyError:
+        raise ConfigurationError(f"S3 storage {name!r} is not initialized, see `init_storages`") from None
+
+
+@dataclass(slots=True)
+class S3Object:
+    """Handle on an object stored in S3, as loaded from an ``S3Field``.
+
+    An empty handle (``key is None``) maps to ``NULL`` and can still be written to.
+    Writing to an empty handle generates a key, so the model must be saved afterwards.
+
+    Attributes:
+        storage: Name of the storage holding the object.
+        key: Object key, or ``None`` when nothing is stored.
+    """
+
+    storage: str
+    key: str | None = None
+
+    @property
+    def is_empty(self) -> bool:
+        """Whether the handle has no key (no I/O performed)."""
+        return self.key is None
+
+    async def read(self) -> bytes | None:
+        """Download the object.
+
+        Returns:
+            The object content, or ``None`` when the handle is empty.
+        """
+        if self.key is None:
+            return None
+        result = await get_store(self.storage).get_async(self.key)
+        return bytes(await result.bytes_async())
+
+    async def write(self, data: bytes, *, key: str | None = None) -> str:
+        """Upload ``data``, generating a UUID7 key when the handle has none.
+
+        Args:
+            data: Content to store.
+            key: Explicit key to write to, replacing the current one.
+
+        Returns:
+            The key written to.
+        """
+        target = key or self.key or uuid7().hex
+        await get_store(self.storage).put_async(target, data)
+        self.key = target
+        return target
+
+    async def delete(self) -> None:
+        """Delete the object and empty the handle. Does nothing when already empty."""
+        if self.key is None:
+            return
+        await get_store(self.storage).delete_async(self.key)
+        self.key = None
+
+    async def exists(self) -> bool:
+        """Check whether the object exists in the storage.
+
+        Returns:
+            ``False`` when the handle is empty or the object is missing.
+        """
+        if self.key is None:
+            return False
+        try:
+            await get_store(self.storage).head_async(self.key)
+        except FileNotFoundError:
+            return False
+        return True
+
+    async def read_or(self, default: bytes) -> bytes:
+        """Download the object, falling back to ``default`` without writing it.
+
+        Args:
+            default: Value returned when the handle is empty or the object is missing.
+
+        Returns:
+            The object content, or ``default``.
+        """
+        try:
+            data = await self.read()
+        except FileNotFoundError:
+            return default
+        return default if data is None else data
+
+    async def get_or_write(self, value: bytes | Callable[[], Awaitable[bytes]]) -> bytes:
+        """Download the object, writing ``value`` first when it is empty or missing.
+
+        Args:
+            value: Content to store, or an async factory only awaited when needed.
+
+        Returns:
+            The stored content.
+        """
+        try:
+            data = await self.read()
+        except FileNotFoundError:
+            data = None
+        if data is not None:
+            return data
+        data = value if isinstance(value, bytes) else await value()
+        await self.write(data)
+        return data
+
+
+class S3Field(fields.Field[S3Object]):
+    """Field storing an S3 object key, loaded as an ``S3Object`` handle.
+
+    The storage is ``storage`` when given, otherwise the model's Tortoise app label.
+    ``NULL`` columns and new instances load as empty, writable handles.
+
+    Examples:
+        >>> class Attachment(Model):
+        ...     file = S3Field(null=True)
+        ...     thumb = S3Field(storage="cdn", null=True)
+    """
+
+    SQL_TYPE = "VARCHAR(1024)"
+    field_type = S3Object
+
+    def __init__(self, storage: str | None = None, **kwargs: Any) -> None:  # pyright: ignore[reportExplicitAny]
+        """Initialize the field.
+
+        Args:
+            storage: Storage name overriding the model's app label.
+            **kwargs: Tortoise field options.
+        """
+        self._storage: str | None = storage
+        kwargs.setdefault("default", self._empty)
+        super().__init__(**kwargs)
+
+    @property
+    def storage_name(self) -> str:
+        """Storage name resolved from the override or the model's app label.
+
+        Raises:
+            ConfigurationError: If neither is available (Tortoise not initialized).
+        """
+        if self._storage is not None:
+            return self._storage
+        app = self.model._meta.app if self.model else None  # noqa: SLF001 # pyright: ignore[reportPrivateUsage, reportUnnecessaryComparison]
+        if app is None:
+            raise ConfigurationError(f"{self.model_field_name!r} has no storage, pass one or initialize Tortoise")
+        return app
+
+    def _empty(self) -> S3Object:
+        return S3Object(self.storage_name)
+
+    @override
+    def to_python_value(self, value: Any) -> S3Object:  # pyright: ignore[reportExplicitAny]
+        """Convert a database value to an ``S3Object`` handle.
+
+        Args:
+            value: Stored key, handle, or ``None``.
+
+        Returns:
+            A handle, empty when the value is ``None``.
+        """
+        if isinstance(value, S3Object):
+            return value
+        return S3Object(self.storage_name, None if value is None else str(value))
+
+    @override
+    def to_db_value(self, value: Any, instance: type[Model] | Model) -> str | None:  # pyright: ignore[reportExplicitAny]
+        """Convert a handle or key to its database representation.
+
+        Args:
+            value: Handle, raw key, or ``None``.
+            instance: Tortoise model class or instance (unused).
+
+        Returns:
+            The object key, or ``None`` when empty.
+        """
+        if isinstance(value, S3Object):
+            return value.key
+        return None if value is None else str(value)
+
+
+__all__ = ["S3Field", "S3Object", "S3Storage", "get_store", "init_storages"]

tortoise_extensions/uuid6.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: ISC
+# Copyright: 2026 NiceBots.xyz
+"""UUID v6+ field for Tortoise ORM (via the ``uuid6`` package)."""
+
+from typing import Any, override
+
+from tortoise import fields
+from tortoise.models import Model
+from uuid6 import UUID, uuid7
+
+
+class FutureUUIDField(fields.Field[UUID], UUID):  # pyright: ignore[reportUnsafeMultipleInheritance]
+    """UUID field compatible with UUID v6+ and the ``uuid6`` package.
+
+    Stores UUIDs as ``CHAR(36)`` on most backends and as native ``UUID`` on
+    PostgreSQL. When used as a primary key without an explicit ``default``,
+    assigns UUID7 via ``uuid6.uuid7``.
+
+    Examples:
+        >>> class Item(Model):
+        ...     id: FutureUUIDField = FutureUUIDField(primary_key=True)
+        ...     class Meta:
+        ...         table = "items"
+    """
+
+    SQL_TYPE = "CHAR(36)"
+
+    class _db_postgres:
+        SQL_TYPE = "UUID"
+
+    def __init__(self, **kwargs: Any) -> None:  # pyright: ignore[reportExplicitAny]
+        """Initialize the field.
+
+        Args:
+            **kwargs: Tortoise field options. Primary keys without ``default``
+                receive ``uuid7`` automatically.
+        """
+        if kwargs.pop("pk", False):
+            kwargs["primary_key"] = True
+        if kwargs.get("primary_key") and "default" not in kwargs:
+            kwargs["default"] = uuid7
+        super().__init__(**kwargs)
+
+    @override
+    def to_db_value(self, value: Any, instance: type[Model] | Model) -> str | None:  # pyright: ignore[reportExplicitAny]
+        """Convert a UUID to its string database representation.
+
+        Args:
+            value: UUID value or other supported input.
+            instance: Tortoise model class or instance (unused).
+
+        Returns:
+            String UUID, or ``None`` when the value is falsy.
+        """
+        return value and str(value)
+
+    @override
+    def to_python_value(self, value: Any) -> UUID | None:  # pyright: ignore[reportExplicitAny]
+        """Convert a database value to a ``uuid6.UUID`` instance.
+
+        Args:
+            value: Raw value from the database driver.
+
+        Returns:
+            Parsed UUID, or ``None`` when the value is null.
+        """
+        if value is None:
+            return None
+        if isinstance(value, UUID):
+            return value
+        return UUID(str(value))
+
+
+__all__ = ["FutureUUIDField"]

tortoise_extensions-0.0.1.dist-info/METADATA

@@ -0,0 +1,148 @@
+Metadata-Version: 2.5
+Name: tortoise-extensions
+Version: 0.0.1
+Summary: Extension field types for Tortoise ORM
+Project-URL: Documentation, https://docs.nicebots.xyz/tortoise-extensions/
+Project-URL: Repository, https://github.com/nicebots-xyz/tortoise-extensions
+Project-URL: Issues, https://github.com/nicebots-xyz/tortoise-extensions/issues
+Project-URL: Source Archive, https://github.com/nicebots-xyz/tortoise-extensions/archive/be1848c93a01c69d6ccce132b5820ad41b5337ee.zip
+Author-email: Paillat-dev <me@paillat.dev>
+License-Expression: ISC
+License-File: LICENSE
+Keywords: fields,orm,pydantic,s3,tortoise,uuid6
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: ISC License (ISCL)
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.12
+Requires-Dist: tortoise-orm<1.0.0,>=0.25.4
+Provides-Extra: pydantic
+Requires-Dist: pydantic~=2.0; extra == 'pydantic'
+Provides-Extra: s3
+Requires-Dist: obstore~=0.12.1; extra == 's3'
+Requires-Dist: uuid6>=2024.0.0; (python_version < '3.14') and extra == 's3'
+Provides-Extra: uuid6
+Requires-Dist: uuid6>=2024.0.0; extra == 'uuid6'
+Description-Content-Type: text/markdown
+
+<!--
+SPDX-License-Identifier: ISC
+Copyright: 2026 NiceBots.xyz
+-->
+# tortoise-extensions
+
+Optional extension field types for [Tortoise ORM](https://tortoise.github.io/). This package targets **Tortoise ORM 0.25.4 and later, but before 1.0** — Tortoise 1.x is not supported yet.
+
+## Install
+
+Base package (requires Tortoise ORM in the supported range):
+
+```bash
+pip install tortoise-extensions
+```
+
+Optional extras:
+
+```bash
+pip install tortoise-extensions[pydantic]
+pip install tortoise-extensions[uuid6]
+pip install tortoise-extensions[s3]
+pip install tortoise-extensions[pydantic,uuid6,s3]
+```
+
+## Usage
+
+### Pydantic JSON (`pydantic` extra)
+
+```python
+from pydantic import BaseModel
+from tortoise.models import Model
+
+from tortoise_extensions.pydantic import PydanticJSONField
+
+
+class Settings(BaseModel):
+    theme: str = "dark"
+
+
+class AppConfig(Model):
+    settings: PydanticJSONField[Settings] = PydanticJSONField(Settings, default=Settings)
+
+    class Meta:
+        table = "app_configs"
+```
+
+`PydanticJSONField` round-trips through your Pydantic model: it accepts dicts from PostgreSQL JSONB, JSON strings from SQLite, and serializes models with `model_dump(mode="json")` on save.
+
+### UUID v6+ (`uuid6` extra)
+
+```python
+from tortoise.models import Model
+
+from tortoise_extensions.uuid6 import FutureUUIDField
+
+
+class Item(Model):
+    id: FutureUUIDField = FutureUUIDField(primary_key=True)
+
+    class Meta:
+        table = "items"
+```
+
+Primary keys without an explicit `default` receive a UUID7 from the [`uuid6`](https://pypi.org/project/uuid6/) package. PostgreSQL uses the native `UUID` column type; other backends store `CHAR(36)`.
+
+### S3 objects (`s3` extra)
+
+```python
+from tortoise.models import Model
+
+from tortoise_extensions.s3 import S3Field
+
+
+class Attachment(Model):
+    file = S3Field(null=True)
+
+    class Meta:
+        table = "attachments"
+```
+
+The column stores an object key and loads as an `S3Object` handle (`read`, `write`, `delete`, `get_or_write`, ...) backed by [`obstore`](https://pypi.org/project/obstore/). Storages are registered per Tortoise app with `init_storages`, each with its own `ssl` setting. See the [usage docs](https://docs.nicebots.xyz/tortoise-extensions/usage/) for details.
+
+## Contributing a new extension
+
+1. **Open an issue first** — describe the field behavior, SQL types per backend, which Tortoise versions you need, and the proposed optional-extra name (e.g. `pip install tortoise-extensions[myextra]`).
+2. After maintainers agree on the design, open a PR that includes:
+   - Implementation in `src/tortoise_extensions/<module>.py`
+   - Tests under `tests/`
+   - An entry in `[project.optional-dependencies]` if the field needs third-party packages
+   - README and docs updates for the new field
+   - ISC SPDX headers on new files (`licensor-config.yaml` applies)
+3. Run `pdm run quality` locally before pushing.
+
+## Documentation
+
+Published at [docs.nicebots.xyz/tortoise-extensions](https://docs.nicebots.xyz/tortoise-extensions/).
+
+```bash
+pdm install -G docs
+pdm run docs:build
+pdm run docs:preview
+pdm run docs:dev
+```
+
+## Development
+
+```bash
+pdm install -G dev -G test -G docs
+pdm run quality
+```
+
+Public APIs use [Google-style docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings); `ruff` enforces this via `convention = "google"`.
+
+## License
+
+ISC.

tortoise_extensions-0.0.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+tortoise_extensions/__init__.py,sha256=53rMk6fOZ73lLLyfN4mw3jjKCgwJ-RG-2vr9KX4sfo0,248
+tortoise_extensions/_version.py,sha256=8OsTLsIVB9D0HdPTmt5rVwyVUBe9xTVGkRslXicxzkM,520
+tortoise_extensions/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tortoise_extensions/pydantic.py,sha256=lqazG4Ek91KmSzhg-hpMOOXPmO2-wOxJkKe2YsqJC4g,2643
+tortoise_extensions/s3.py,sha256=R6-4bmtGHf4jKBTweJ-5MVCMVoELbeFht6FqvCQGMfs,9001
+tortoise_extensions/uuid6.py,sha256=LqoCktYxjvxhtpbJ3mwd40PbxNkKCJJ1I_pfM5QN-Pg,2358
+tortoise_extensions-0.0.1.dist-info/METADATA,sha256=NJsKaLKkZRm8bjpoyEU-VRn4uVKmlrVtmASFndrgi8E,4759
+tortoise_extensions-0.0.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+tortoise_extensions-0.0.1.dist-info/licenses/LICENSE,sha256=lh4wKPdjQxcYj8MlbyIUjEoaTk6SkcKOiVpNJsJnMl0,743
+tortoise_extensions-0.0.1.dist-info/RECORD,,

tortoise_extensions-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

tortoise_extensions-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 NiceBots.xyz
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
+OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.