alchemiq 0.1.0__tar.gz

alchemiq-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug report
+about: Report a problem with alchemiq
+title: ""
+labels: bug
+assignees: ""
+---
+
+## Description
+
+A clear description of what went wrong.
+
+## Reproduction
+
+Minimal code or steps that trigger the bug:
+
+```python
+# ...
+```
+
+## Expected behaviour
+
+What you expected to happen.
+
+## Environment
+
+- alchemiq version:
+- Python version:
+- Database and version (PostgreSQL or ClickHouse):
+- Relevant extras (fastapi, outbox, redis, and so on):
+
+## Additional context
+
+Traceback, logs, or anything else that helps.

alchemiq-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentation
+    url: https://alchemiq.readthedocs.io
+    about: Guides and API reference.
+  - name: Questions and discussion
+    url: https://github.com/TrifoN-off/alchemiq/discussions
+    about: Ask usage questions here instead of opening an issue.

alchemiq-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Suggest an idea or improvement
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+What are you trying to do, and what is missing or awkward today?
+
+## Proposed solution
+
+What you would like alchemiq to do. An API sketch is welcome.
+
+## Alternatives
+
+Other approaches you considered.
+
+## Additional context
+
+Links, prior art, or related issues.

alchemiq-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+## Summary
+
+What does this change do, and why?
+
+## Type of change
+
+- [ ] Bug fix (`fix:`)
+- [ ] New feature (`feat:`)
+- [ ] Breaking change (`feat!:` or `BREAKING CHANGE:`)
+- [ ] Docs, tests, or chore (no release)
+
+## Checklist
+
+- [ ] The local gate is green (lint, format, types, tests, docs).
+- [ ] New behaviour has tests; coverage stays at 90 or above.
+- [ ] Docstrings and the matching `docs/guide/` page are updated.
+- [ ] The PR title follows Conventional Commits.

alchemiq-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,100 @@
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Sync (all extras + dev)
+        run: uv sync --all-extras --group dev
+      - name: Ruff lint
+        run: uv run --no-sync ruff check
+      - name: Ruff format check
+        run: uv run --no-sync ruff format --check
+      - name: Type check (ty)
+        run: uv run --no-sync ty check
+
+  typing:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Sync (all extras + dev)
+        run: uv sync --all-extras --group dev
+      - name: ty (src + typing fixture)
+        run: uv run --no-sync ty check
+      - name: mypy (consumer fixture)
+        run: uv run --no-sync mypy --follow-imports=silent tests/typing/models.py
+      - name: pyright (consumer fixture)
+        run: uv run --no-sync pyright --project tests/typing
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - name: Sync (all extras + dev)
+        run: uv sync --all-extras --group dev
+      - name: Unit tests
+        run: uv run --no-sync pytest -m unit --cov=alchemiq --cov-report=
+      - name: Integration tests (PostgreSQL + Redis)
+        run: uv run --no-sync pytest -m integration --cov=alchemiq --cov-report= --cov-append
+      # File by file: a single-process `pytest -m clickhouse` run flakes on
+      # container/event-loop isolation (session container x per-test loop under
+      # testcontainers); Ryuk's port mapping flakes in the same setup.
+      - name: ClickHouse tests (file by file)
+        env:
+          TESTCONTAINERS_RYUK_DISABLED: "true"
+        run: |
+          for f in tests/clickhouse/test_*.py; do
+            uv run --no-sync pytest "$f" --cov=alchemiq --cov-report= --cov-append -q
+          done
+      - name: Coverage gate
+        run: uv run --no-sync coverage report --fail-under=90
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Twine metadata check
+        run: uvx twine check dist/*
+      - name: Assert packaged data files
+        run: |
+          python -m zipfile -l dist/*.whl | grep -q 'alchemiq/py.typed'
+          python -m zipfile -l dist/*.whl | grep -q 'alchemiq/migrations/postgres/_template/script.py.mako'
+      - name: Clean-venv core import (no extras)
+        run: |
+          uv venv --python 3.12 /tmp/ve
+          uv pip install --python /tmp/ve dist/*.whl
+          /tmp/ve/bin/python -c "import alchemiq; print(alchemiq.__version__)"
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Sync (all extras + docs)
+        run: uv sync --all-extras --group docs
+      - name: Build docs (warnings as errors)
+        run: uv run --no-sync sphinx-build -W --keep-going -b html docs docs/_build/html

alchemiq-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,29 @@
+name: Release
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Semantic release (version, changelog, tag, GitHub release, build)
+        id: release
+        uses: python-semantic-release/python-semantic-release@v9.21.1
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Publish to PyPI (Trusted Publishing / OIDC)
+        if: steps.release.outputs.released == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1

alchemiq-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# IDE / editor 
+.vscode/
+.idea/
+
+# OS files
+.DS_Store
+
+# Coverage artifacts
+.coverage
+.coverage.*
+
+# Sphinx build output
+docs/_build/

alchemiq-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

alchemiq-0.1.0/.readthedocs.yaml

@@ -0,0 +1,10 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  commands:
+    - pip install uv
+    - uv sync --all-extras --group docs
+    - uv run --no-sync sphinx-build -W --keep-going -b html docs $READTHEDOCS_OUTPUT/html

alchemiq-0.1.0/CHANGELOG.md

@@ -0,0 +1,89 @@
+# 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.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> **Note:** From this point forward, changelog entries are managed automatically
+> by [Python Semantic Release](https://python-semantic-release.readthedocs.io/).
+> Do not edit entries below the `[Unreleased]` section manually.
+
+<!-- PSR inserts new releases above this line -->
+
+## v0.1.0 (2026-07-05)
+
+### Features
+
+- Initial public release
+  ([`d088fb1`](https://github.com/TrifoN-off/alchemiq/commit/d088fb162f8fb127416330a3644c01856beb1fc3))
+
+
+## [0.1.0] - 2026-06-29
+
+### Added
+
+- **Models & field types** - declarative `Model` base with annotation-first field
+  types: `Email`, `Phone`, `Password`, `Encrypted`, `Money`, `Slug`, `URL`,
+  `UUID4`, `UUID7`, `NanoID`, `Bounded`, `Positive`, `NonNegative`, `Percent`,
+  `RoundedDecimal`, `JSON`, `Array`, `Enum`, `Maybe[T]`, `PK`, `Field`,
+  `FieldType` (custom field protocol), `CreatedAt`, `UpdatedAt`, `DateTimeTz`,
+  `Date`, `Time`, `UnixTimestamp`.
+- **Native-column interop** - `Mapped[T] = mapped_column(...)` passthrough
+  registered in `__alchemiq_fields__` with post-mapping reconciliation;
+  first-class filter / serialize / FastAPI-schema / primary-key support
+  including custom PKs.
+- **Relationships** - `ForeignKey[Model]`, `OneToOne[Model]`, `ManyToMany[Model]`
+  sugar (auto join-table generation); native `relationship()` escape-hatch via
+  `NATIVE_RELATIONSHIP` sentinel.
+- **Q objects & QuerySet** - chainable `Q` expressions for complex `AND`/`OR`
+  filters; `QuerySet` with `.filter()`, `.exclude()`, `.order_by()`,
+  `.distinct()`, `.only()` (column projection), `.select_related()`,
+  `.prefetch_related()`, `.limit()`, `.offset()`, `.count()`, `.exists()`,
+  `.aggregate()`, `.explain(analyze=, format=)`.
+- **Repository** - async `Repository[Model]` with `get`, `filter`, `create`,
+  `update`, `delete`, `bulk_create`, `bulk_upsert` (PostgreSQL `ON CONFLICT`),
+  `aggregate` (`Count`, `Sum`, `Avg`, `Min`, `Max`), cursor/keyset pagination
+  (`cursor_paginate`, returns `CursorPage`), offset pagination (returns `Page`),
+  and `.explain()` passthrough; repo-level `cache=`/`cache_clear`/`cache_evict`.
+- **Unit of Work** - `async with UnitOfWork() as uow` coordinating session,
+  transaction, `commit()`, `rollback()`, and repository access.
+- **Soft delete** - `Meta.soft_delete = True` adds `deleted_at`; `restore()`,
+  `hard_delete()`; automatic exclusion from queries, relationship loads, and
+  traversal joins; `with_deleted()` / `only_deleted()` escapes.
+- **Signals** - `pre_create`, `post_create`, `pre_update`, `post_update`,
+  `pre_delete`, `post_delete` lifecycle decorators; imperative `connect` /
+  `disconnect`; async dispatch.
+- **Optimistic locking** - `Meta.versioned = True` adds `_version` column;
+  keyword-only `expected_version` on `update`/`delete`; raises
+  `ConcurrentModificationError` (-> HTTP 409); `version_of(obj)` accessor.
+- **Serialization** - `to_dict()` serializes a model instance to a plain dict;
+  `to_schema()` returns a Pydantic class mirroring the model's columns;
+  `to_pydantic()` converts an instance to a validated schema DTO;
+  `Maybe[T]` partial-update sentinel with `Some`/`Nothing` unwrapping.
+- **Configurable password hashing** - `Password` field ships with scrypt by
+  default (Python stdlib, no extra); `configure_password_hashing("argon2" | "bcrypt")`
+  switches the global scheme at startup (`[argon2]` / `[bcrypt]` extras);
+  `check_password` dispatches on the stored hash's algorithm prefix
+  for seamless multi-scheme migration without bulk re-hashing.
+- **FastAPI integration** - `crud_router()` generating standard REST endpoints;
+  provider DI; health-check router; `install_exception_handlers`.
+- **Outbox & relay** - transactional outbox pattern with `OutboxMessage`,
+  `OutboxEvent`, `Relay` background worker, `Publisher`/`publish`,
+  `PublishError`, `TransientPublishError`; at-least-once delivery.
+- **FastStream publishing** - broker-agnostic `FastStreamPublisher` adapter;
+  consumer dependency injection; lifespan integration.
+- **Caching** - `CacheBackend` / `InMemoryCache` / `configure_cache` /
+  `reset_cache`; repository-level `cache=` parameter, `cache_clear`, `cache_evict`.
+- **ClickHouse support** - `ClickHouseModel` base; `ClickHouseRepository`;
+  async engine bootstrap; read-path `.explain()`; `LowCardinality` and other
+  CH-native field types.
+- **Migrations & unified CLI** - Alembic-backed `alchemiq` sub-commands
+  (`makemigrations`, `migrate`, `rollback`, `history`, `showsql`);
+  `alchemiq` top-level dispatcher.
+- **`alchemiq init` scaffolding** - guided skeleton generator (stdlib-only,
+  no extra deps) for single-app and monorepo layouts via `.tmpl` templates.
+- **Health checks** - `check_health()` returning `HealthReport` /
+  `ComponentHealth`.
+
+[0.1.0]: https://github.com/TrifoN-off/alchemiq/releases/tag/v0.1.0

alchemiq-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+trifonov.nikit@gmail.com. All complaints will be reviewed and investigated
+promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][mozilla coc].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][faq]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[mozilla coc]: https://github.com/mozilla/diversity
+[faq]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

alchemiq-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing to alchemiq
+
+Thanks for your interest in improving alchemiq. This guide covers the local
+setup, the checks every change must pass, and how releases work.
+
+## Development setup
+
+alchemiq uses [uv](https://docs.astral.sh/uv/) for environment and dependency
+management, and targets Python 3.12 and newer.
+
+```bash
+git clone git@github.com:TrifoN-off/alchemiq.git
+cd alchemiq
+uv sync --all-extras --group dev
+```
+
+## The local gate
+
+Run the full gate before opening a pull request. Sync first, then use
+`--no-sync` so the optional extras stay installed.
+
+```bash
+uv sync --all-extras --group dev
+
+# Lint, format, types
+uv run --no-sync ruff check
+uv run --no-sync ruff format --check
+uv run --no-sync ty check
+uv run --no-sync mypy --follow-imports=silent tests/typing/models.py
+uv run --no-sync pyright --project tests/typing
+
+# Tests (run the markers separately)
+uv run --no-sync pytest -m unit        --cov=alchemiq --cov-report=
+uv run --no-sync pytest -m integration --cov=alchemiq --cov-report= --cov-append
+
+# ClickHouse tests run file by file
+export TESTCONTAINERS_RYUK_DISABLED=true
+for f in tests/clickhouse/test_*.py; do
+  uv run --no-sync pytest "$f" --cov=alchemiq --cov-report= --cov-append -q
+done
+
+uv run --no-sync coverage report --fail-under=90
+
+# Docs (warnings are errors)
+uv sync --all-extras --group docs
+uv run --no-sync sphinx-build -W --keep-going -b html docs docs/_build/html
+```
+
+Integration and ClickHouse tests need Docker; they start PostgreSQL and
+ClickHouse through testcontainers.
+
+## Commit messages
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/).
+Python Semantic Release derives the version and changelog from them, so the
+prefix matters:
+
+| Prefix | Effect (while on 0.x) |
+|---|---|
+| `fix:` | patch release |
+| `feat:` | minor release |
+| `feat!:` or `BREAKING CHANGE:` | minor while on 0.x |
+| `docs:` `test:` `chore:` `ci:` `refactor:` | no release |
+
+Do not bump the version or edit `CHANGELOG.md` by hand; the release pipeline
+owns both.
+
+## Pull requests
+
+1. Branch off `main`.
+2. Keep the change focused, and add tests for new behaviour (coverage stays at
+   90 or above).
+3. Update the matching `docs/guide/` page and docstrings in the same PR.
+4. Make sure the local gate is green.
+5. Open the PR with a Conventional Commit style title.
+
+## Public API
+
+The public surface is whatever `alchemiq.__all__` (and each integration
+subpackage's `__all__`) exports. Adding to it is a `feat:`; changing or removing
+from it is a breaking change.

alchemiq-0.1.0/LICENSE

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