tortoise-extensions 0.0.1__tar.gz

tortoise_extensions-0.0.1/.github/workflows/CI.yaml

@@ -0,0 +1,13 @@
+name: CI
+
+on:
+  push:
+    branches: ["master"]
+  pull_request:
+    branches: ["master"]
+
+jobs:
+  quality:
+    uses: ./.github/workflows/quality.yaml
+    permissions:
+      contents: read

tortoise_extensions-0.0.1/.github/workflows/quality.yaml

@@ -0,0 +1,35 @@
+name: Quality Checks
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Setup PDM
+        uses: pdm-project/setup-pdm@544d7237314ee09c256785bd360f6b30add38b37 # v4.6
+        with:
+          cache: true
+          python-version-file: "pyproject.toml"
+
+      - name: Install dependencies
+        run: pdm install --frozen-lockfile -G dev -G test -G docs
+
+      - name: Format Check
+        run: pdm run format:check
+
+      - name: Lint Check
+        run: pdm run lint
+
+      - name: Type Check
+        run: pdm run typecheck
+
+      - name: Tests
+        run: pdm run tests
+
+      - name: Build docs
+        run: pdm run docs:build

tortoise_extensions-0.0.1/.github/workflows/release.yaml

@@ -0,0 +1,102 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*.*.*"]
+
+jobs:
+  quality:
+    uses: ./.github/workflows/quality.yaml
+    permissions:
+      contents: read
+
+  get-version:
+    name: Get Version
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Setup PDM
+        uses: pdm-project/setup-pdm@544d7237314ee09c256785bd360f6b30add38b37 # v4.6
+        with:
+          cache: true
+          python-version-file: "pyproject.toml"
+
+      - name: Install dependencies
+        run: pdm install --frozen-lockfile
+
+      - name: Build package
+        run: pdm build
+
+      - name: Get version
+        id: version
+        run: |
+          VERSION=$(pdm run python -c "from tortoise_extensions._version import __version__; print(__version__)")
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+  publish:
+    name: Publish
+    runs-on: ubuntu-latest
+    needs: [quality, get-version]
+    permissions:
+      id-token: write
+      contents: read
+    environment:
+      name: pypi
+      url: https://pypi.org/project/tortoise-extensions/${{ needs.get-version.outputs.version }}/
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Setup PDM
+        uses: pdm-project/setup-pdm@544d7237314ee09c256785bd360f6b30add38b37 # v4.6
+        with:
+          cache: true
+          python-version-file: "pyproject.toml"
+
+      - name: Install dependencies
+        run: pdm install --frozen-lockfile
+
+      - name: Build and Publish
+        run: pdm publish
+
+  deploy-docs:
+    needs: [quality, publish]
+    name: Deploy docs
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Setup PDM
+        uses: pdm-project/setup-pdm@544d7237314ee09c256785bd360f6b30add38b37 # v4.6
+        with:
+          cache: true
+          python-version-file: "pyproject.toml"
+
+      - name: Install dependencies
+        run: pdm install --frozen-lockfile -G dev -G test -G docs
+
+      - name: Build docs
+        run: pdm run docs:build
+
+      - name: Upload docs
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5
+        with:
+          path: site
+
+      - name: Deploy docs
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
+        id: deployment

tortoise_extensions-0.0.1/.gitignore

@@ -0,0 +1,69 @@
+# 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
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# pdm
+.pdm-python
+.pdm-build/
+src/tortoise_extensions/_version.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Ruff
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# IDE
+.idea/
+.vscode/
+
+/site/

tortoise_extensions-0.0.1/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.

tortoise_extensions-0.0.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,117 @@
+<!--
+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/docs/api.md

@@ -0,0 +1,33 @@
+<!--
+SPDX-License-Identifier: ISC
+Copyright: 2026 NiceBots.xyz
+-->
+# API Reference
+
+## Pydantic
+
+::: tortoise_extensions.pydantic
+    options:
+      members:
+        - PydanticJSONField
+      show_submodules: false
+
+## UUID6
+
+::: tortoise_extensions.uuid6
+    options:
+      members:
+        - FutureUUIDField
+      show_submodules: false
+
+## S3
+
+::: tortoise_extensions.s3
+    options:
+      members:
+        - S3Field
+        - S3Object
+        - S3Storage
+        - init_storages
+        - get_store
+      show_submodules: false

tortoise_extensions-0.0.1/docs/contributing.md

@@ -0,0 +1,28 @@
+<!--
+SPDX-License-Identifier: ISC
+Copyright: 2026 NiceBots.xyz
+-->
+# Contributing
+
+## Proposing a new extension
+
+1. Open an issue describing the field behavior, SQL types per backend, Tortoise version requirements, and the proposed optional-extra name.
+2. Wait for maintainer feedback before starting implementation.
+
+## Pull requests
+
+Include:
+
+- Implementation in `src/tortoise_extensions/<module>.py`
+- Google-style docstrings on public APIs
+- Tests under `tests/`
+- Optional dependency entry in `pyproject.toml` when third-party packages are required
+- Updates to `docs/usage.md` and `docs/api.md` when user-facing behavior changes
+
+Run the quality gate locally:
+
+```bash
+pdm install -G dev -G test -G docs
+pdm run quality
+pdm run docs:build
+```

tortoise_extensions-0.0.1/docs/index.md

@@ -0,0 +1,37 @@
+<!--
+SPDX-License-Identifier: ISC
+Copyright: 2026 NiceBots.xyz
+-->
+# tortoise-extensions
+
+`tortoise-extensions` provides optional Tortoise ORM field types as install extras.
+
+Supported Tortoise ORM versions: **0.25.4 and later, but before 1.0**. Tortoise 1.x is not supported yet.
+
+## Install
+
+```bash
+pip install tortoise-extensions[pydantic,uuid6]
+```
+
+See [Usage](usage.md) for field-specific setup.
+
+## Quick example
+
+```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"
+```

tortoise_extensions-0.0.1/docs/usage.md

@@ -0,0 +1,90 @@
+<!--
+SPDX-License-Identifier: ISC
+Copyright: 2026 NiceBots.xyz
+-->
+# Usage
+
+Install the base package plus the extras you need:
+
+```bash
+pip install tortoise-extensions[pydantic]
+pip install tortoise-extensions[uuid6]
+pip install tortoise-extensions[s3]
+pip install tortoise-extensions[pydantic,uuid6,s3]
+```
+
+## Pydantic JSON field
+
+Requires the `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` validates JSON using your Pydantic model. It accepts dict values from PostgreSQL JSONB and JSON strings from SQLite.
+
+## UUID v6+ field
+
+Requires the `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` are assigned UUID7. PostgreSQL uses the native `UUID` column type; other backends use `CHAR(36)`.
+
+## S3 field
+
+Requires the `s3` extra.
+
+```python
+from tortoise.models import Model
+
+from tortoise_extensions.s3 import S3Field, S3Storage, init_storages
+
+
+class Attachment(Model):
+    file = S3Field(null=True)
+    thumb = S3Field(storage="cdn", null=True)
+
+
+init_storages(
+    {
+        "models": S3Storage(endpoint="s3.example.com", bucket="main", access_key="...", secret_key="..."),
+        "cdn": S3Storage(endpoint="minio:9000", bucket="cdn", access_key="...", secret_key="...", ssl=False),
+    }
+)
+
+record = await Attachment.create()
+await record.file.write(b"hello")
+await record.save()
+
+data = await record.file.read()
+thumb = await record.thumb.get_or_write(render_thumbnail)
+await record.save()
+```
+
+The column stores the object key (`VARCHAR(1024)`) and loads as an `S3Object` handle backed by [`obstore`](https://pypi.org/project/obstore/).

tortoise_extensions-0.0.1/licensor-config.yaml

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: ISC
+# Copyright: 2026 NiceBots.xyz
+holder: NiceBots.xyz
+spdx: ISC
+year: 2026