kakaorm 0.3.0__tar.gz

kakaorm-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,92 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[aiosqlite,dev]"
+
+      - name: Lint (ruff)
+        run: ruff check kakaorm/
+
+      - name: Run tests
+        run: pytest --tb=short -q
+
+  test-mysql:
+    name: Test MySQL
+    runs-on: ubuntu-latest
+
+    services:
+      mysql:
+        image: mysql:8.0
+        env:
+          MYSQL_ROOT_PASSWORD: root
+          MYSQL_DATABASE: test_db
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd="mysqladmin ping -h 127.0.0.1 --silent"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=5
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[aiomysql,dev]" cryptography
+
+      - name: Run MySQL tests
+        env:
+          KAKAORM_MYSQL_URL: mysql+aiomysql://root:root@127.0.0.1:3306/test_db
+        run: pytest tests/test_mysql.py --tb=short -v
+
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: |
+          pip install build
+          python -m build
+
+      - name: Upload dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

kakaorm-0.3.0/.gitignore

@@ -0,0 +1,69 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+parts/
+var/
+sdist/
+wheels/
+*.egg-link
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+.pytype/
+.pyre/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Distribution / packaging
+pip-wheel-metadata/
+share/python-wheels/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Environment variables
+.env
+.env.*
+!.env.example
+
+# Logs
+*.log
+logs/
+
+# Database files
+*.db
+*.sqlite
+*.sqlite3
+
+# Build artifacts
+*.spec

kakaorm-0.3.0/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-06-01
+
+### Added
+
+- **SoftDeleteModel** — Logical deletion base class:
+  - `delete()` sets `deleted_at` instead of physically removing the record
+  - `deleted_at` column is added automatically
+  - Default queries exclude soft-deleted records (`deleted_at IS NULL`)
+  - `include_deleted()` — include soft-deleted records in queries
+  - `only_deleted()` — query only soft-deleted records
+  - `restore()` — cancel logical deletion (instance and QuerySet level)
+  - `purge()` — physically delete soft-deleted records
+  - `count()`, `update()`, `aggregate()` respect the deletion filter automatically
+- **ArchiveModel** — Archive deletion base class:
+  - `delete()` moves the record to `archive_{table}` within a transaction (INSERT + DELETE)
+  - Archive table is created separately via `engine.create_archive_table(Model)`
+  - Default queries target the main table only
+  - `include_deleted()` — UNION ALL across main and archive tables
+  - `only_deleted()` — query the archive table only
+  - `restore()` — move record back from archive to main table (instance and QuerySet level)
+  - `purge()` — physically delete from the archive table
+- **`engine.create_archive_table()`** — Creates `archive_{table}` with the same schema as the main table plus an `archived_at` timestamp column
+- **autogenerate archive support** — `autogenerate()` now detects `ArchiveModel` subclasses and includes the archive table in the diff plan automatically
+
+### Changed
+
+- `Migrator.plan()` expands `ArchiveModel` subclasses to also plan their corresponding archive tables
+
+[0.3.0]: https://github.com/AyumuTakai/KakaORM/releases/tag/v0.3.0
+
+## [0.2.0] - 2026-06-01
+
+### Added
+
+- **CTE (WITH clause)** — Complex query support via `with_cte()` method
+- **Eager loading (prefetch)** — N+1 problem elimination with `prefetch()` method for all relationship types
+- **Migration downgrade** — Rollback capability via `downgrade()` method with automatic reverse SQL generation
+- **Migration autogenerate** — Automatic migration file generation via `autogenerate()` from model-DB diffs
+- **Migration CLI** — Command-line interface via `kakaorm` command:
+  - `kakaorm init` — Initialize migrations directory
+  - `kakaorm makemigrations` — Auto-generate migration files
+  - `kakaorm migrate` — Apply or rollback migrations
+  - `kakaorm showmigrations` — View migration history
+- **Window Functions** — SQL window functions support:
+  - `RowNumber()`, `Rank()`, `DenseRank()` for ranking
+  - `Lag()`, `Lead()` for offset functions
+  - `Sum().over()`, `Avg().over()`, `Min().over()`, `Max().over()` for aggregate windows
+- **FastAPI Integration Guide** — Comprehensive documentation with 3 example implementations:
+  - `fastapi_advanced.py` — Dependency injection and multi-model patterns
+  - `fastapi_pagination.py` — Pagination and filtering
+  - `fastapi_testing.py` — Testing strategies
+
+### Changed
+
+- Enhanced `QuerySet._parse_exprs()` to recognize and handle window functions
+- Extended `AggFunc` with `.over()` method for aggregate window support
+- Improved `Pydantic v2` integration documentation
+
+### Fixed
+
+- None reported
+
+[0.2.0]: https://github.com/AyumuTakai/KakaORM/releases/tag/v0.2.0
+
+## [0.1.0] - 2026-06-01
+
+### Added
+
+- `Model` base class with `AsyncORMMeta` metaclass for declarative model definitions
+- Column types: `IntColumn`, `StrColumn`, `FloatColumn`, `BoolColumn`, `DateTimeColumn`, `DateColumn`, `TimeColumn`, `DecimalColumn`, `ForeignKey`
+- User-defined primary keys (`primary_key=True` on any column)
+- `QuerySet` lazy query builder with chainable API: `where()`, `order_by()`, `limit()`, `offset()`, `select()`, `group_by()`, `having()`
+- WHERE operators: `==`, `!=`, `>=`, `>`, `<=`, `<`, `IS NULL`, `LIKE`, `ILIKE`, `IN`, `NOT IN`, `BETWEEN`
+- Boolean operators: `&` (AND), `|` (OR), `~` (NOT)
+- Aggregate functions: `Count`, `Sum`, `Avg`, `Max`, `Min`
+- `CASE WHEN` expression support in SELECT and UPDATE
+- JOIN support: `join()` (INNER), `left_join()` (LEFT OUTER)
+- Subquery support: `WHERE col IN (SELECT ...)` via `Subquery`
+- Bulk operations: `bulk_create()`, `QuerySet.update()`, `QuerySet.delete()`, `truncate()`
+- `INSERT ... SELECT` via `QuerySet.insert_into()`
+- UPDATE column-reference expressions: `Post.all().update(views=Post.views + 1)`
+- Event hooks: `before_insert`, `after_insert`, `before_update`, `after_update`, `before_delete`, `after_delete`
+- Relationship descriptors: `has_many()`, `has_one()`, `belongs_to()`
+- Composite indexes via `Meta.indexes`
+- CHECK constraints via `check=` column option
+- Explicit transaction support via `engine.transaction()` context manager
+- Raw SQL access: `engine.fetch()`, `engine.execute()`, `engine.fetchval()`
+- `Migrator` — diff-based schema migration (ADD COLUMN, DROP COLUMN, ADD CONSTRAINT)
+- `VersionedMigrator` — migration history tracked in `kakaorm_migrations` table
+- `DROP TABLE CASCADE` support
+- Pydantic v2 protocol: `model_dump()`, `model_validate()`, `__get_pydantic_core_schema__()`, `__get_pydantic_json_schema__()` — enables direct use as FastAPI `response_model`
+- Engine backends: `AsyncpgEngine` (PostgreSQL/asyncpg), `Psycopg3Engine` (PostgreSQL/psycopg3), `AioSQLiteEngine` (SQLite/aiosqlite), `AioMySQLEngine` (MySQL-MariaDB/aiomysql)
+- `connect()` factory function with URL-based engine selection
+- Security: column-name whitelist validation on `update()` and `insert_into()`
+- `py.typed` marker for PEP 561 compliance
+
+[0.1.0]: https://github.com/AyumuTakai/KakaORM/releases/tag/v0.1.0

kakaorm-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayumu Takai
+
+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.