ferro-orm 0.3.0__tar.gz → 0.3.1__tar.gz

{ferro_orm-0.3.0 → ferro_orm-0.3.1}/.github/PERMISSIONS.md

@@ -45,7 +45,37 @@ All workflows use explicit, fine-grained permissions (principle of least privile
 
 **Trigger:** Manual workflow dispatch
 
-**Permissions:**
+**Job graph (top to bottom is execution order):**
+
+```
+ci-gate        packaging-smoke
+        \      /
+      prepare-release                 (computes bump, writes release.patch; no pushes)
+     /    |    |    \
+build-wheels build-sdist test-wheels verify-docs
+                  \    |    /
+                promote-pypi           (PyPI Trusted Publishing; first irreversible step)
+                      |
+                 promote-git           (commit bump, push main, tag, create GH Release + assets)
+                      |
+                 promote-docs          (deploys MkDocs site pinned to the new tag)
+```
+
+Nothing is pushed, tagged, or published until every validation job above
+`promote-pypi` has succeeded. PyPI is published first so that if anything
+fails, `main` is never advanced to an "orphan" version.
+
+**Permissions (prepare-release):**
+```yaml
+permissions:
+  contents: read
+  issues: read
+  pull-requests: read
+```
+
+Prepare-release only needs read access because it just computes the bump and uploads a patch artifact — it does not push anything.
+
+**Permissions (promote-git):**
 ```yaml
 permissions:
   contents: write
@@ -53,32 +83,23 @@ permissions:
   pull-requests: write
 ```
 
-**Why These Permissions:**
-- `contents: write` - Allows the workflow to:
-  - Commit version bumps to pyproject.toml and Cargo.toml
+- `contents: write` - Allows the job to:
+  - Commit version bumps to `pyproject.toml` and `Cargo.toml`
   - Push commits to the `main` branch
-  - Create and push git tags (e.g., `v0.2.0`)
-  - Create GitHub releases
+  - Create and push git tags (e.g., `v0.3.1`)
+  - Create GitHub Releases
 
-- `issues: write` - Allows the workflow to:
-  - Update issue references in release notes
-  - Close issues automatically via commit messages
-  - Add labels or comments to issues
+- `issues: write` / `pull-requests: write` - Allows semantic-release to
+  update issue/PR references in generated release notes.
 
-- `pull-requests: write` - Allows the workflow to:
-  - Update PR references in release notes
-  - Close PRs automatically via commit messages
-  - Add labels or comments to PRs
-
-**What It Does:**
-- Analyzes conventional commits
-- Determines next version
-- Updates version in both Python and Rust files
-- Finalizes CHANGELOG.md
-- Creates git tag
-- Creates GitHub release
-- Triggers publish workflow
-- Reports whether release commits include `CHANGELOG.md`
+**What the release flow does:**
+- Analyzes conventional commits since the latest tag (fetched explicitly via `fetch-tags: true`)
+- Fails fast if the computed version collides with an existing tag (indicates a tag-fetch bug)
+- Bumps version in `pyproject.toml` and `Cargo.toml` and finalizes `CHANGELOG.md`
+- Validates the bumped tree across wheel builds, sdist, install smoke tests, and `mkdocs build`
+- Publishes to PyPI before touching `main`
+- Commits bump to `main`, creates the tag, creates the GitHub Release with generated notes, attaches wheels + sdist
+- Deploys the MkDocs site pinned to the new tag
 
 **Required Secrets:**
 - `RELEASE_DEPLOY_KEY` (private SSH key for a write-enabled deploy key)
@@ -88,15 +109,15 @@ permissions:
 
 ### 2. Build & Publish (jobs in `release.yml`)
 
-**Trigger:** Part of `release.yml` after the release job (no reusable workflow).
+**Trigger:** Part of `release.yml` — all build and publish jobs live in the same workflow file.
 
 Build, test, and publish jobs are defined directly in `release.yml` so PyPI Trusted Publishing receives a token with `workflow_ref: release.yml` (reusable workflows are not supported by PyPI).
 
 **Permissions:**
 
-**For build-wheels, build-sdist, test-wheels:** (default - read-only)
+**For build-wheels, build-sdist, test-wheels, verify-docs:** (default - read-only)
 
-**For publish-pypi job:**
+**For promote-pypi job:**
 ```yaml
 permissions:
   id-token: write
@@ -106,10 +127,10 @@ permissions:
 - `id-token: write` - Allows the job to request an OIDC token and authenticate with PyPI using Trusted Publishing.
 
 **What It Does:**
-- Builds wheels for multiple platforms from the release tag
-- Builds source distribution
-- Tests built packages
-- Publishes to PyPI using OIDC authentication
+- Builds wheels for multiple platforms against the patched (bumped) tree
+- Builds source distribution against the patched tree
+- Installs wheels and runs a smoke import + in-memory SQLite check
+- `promote-pypi` publishes the validated wheels + sdist to PyPI via OIDC
 
 ---
 
@@ -268,10 +289,18 @@ Permission to manage GitHub Pages deployments:
 **Cause:** Missing `id-token: write` permission
 
 **Solution:**
-- Ensure `publish-pypi` job has `id-token: write`
+- Ensure `promote-pypi` job has `id-token: write`
 - Verify PyPI trusted publisher is configured correctly
 - Check environment name matches (`pypi`)
 
+### Release says "0.3.0 has already been released!" for a version that was already shipped
+
+**Cause:** `actions/checkout@v4` runs `git fetch --no-tags` by default, even with `fetch-depth: 0`. Without tags, `semantic-release` picks an older baseline tag, computes a minor/patch bump, and lands on the same version number as a prior release.
+
+**Solution:**
+- The `prepare-release` job sets `fetch-tags: true` on its checkout step and then runs a `git describe` vs `semantic-release --print-last-released-tag` comparison as a guard. Both must be present.
+- If this check fails in a run, confirm no one has removed `fetch-tags: true` from the checkout step.
+
 ---
 
 ## Verification

{ferro_orm-0.3.0 → ferro_orm-0.3.1}/.github/workflows/release.yml

@@ -24,7 +24,7 @@ jobs:
 
   # Bump versions and changelog locally only; export a patch so every later job
   # validates the exact tree that would be released. Nothing is pushed until
-  # publish-github-release after wheels, sdist, tests, and docs all pass.
+  # promote-* jobs run, after wheels, sdist, tests, and docs all pass.
   prepare-release:
     name: Prepare release (no push)
     needs: [ci-gate, packaging-smoke]
@@ -48,6 +48,11 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          # actions/checkout@v4 passes --no-tags by default, even with
+          # fetch-depth: 0. semantic-release needs tags to pick the right
+          # baseline version; without them it may bump from an older tag and
+          # land on a version that has already been released.
+          fetch-tags: true
 
       - name: Set up Python
         uses: actions/setup-python@v5
@@ -63,6 +68,28 @@ jobs:
         run: |
           uv sync --only-group release --no-install-project --python 3.13
 
+      # Fail fast if the checkout did not materialize tags. Without this guard
+      # semantic-release silently picks an older baseline and can compute an
+      # already-released version (see PSR note: "No release will be made, X has
+      # already been released!").
+      - name: Verify tag visibility
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          GIT_LATEST_TAG="$(git describe --tags --abbrev=0 2>/dev/null || echo '')"
+          PSR_LATEST_TAG="$(uv run semantic-release version --print-last-released-tag 2>/dev/null | tail -n1 || echo '')"
+
+          echo "git describe --tags --abbrev=0       -> '${GIT_LATEST_TAG}'"
+          echo "semantic-release --print-last-released-tag -> '${PSR_LATEST_TAG}'"
+
+          if [[ -n "${GIT_LATEST_TAG}" && "${GIT_LATEST_TAG}" != "${PSR_LATEST_TAG}" ]]; then
+            echo "ERROR: git and semantic-release disagree on the latest tag."
+            echo "This usually means actions/checkout did not fetch tags."
+            echo "Confirm 'fetch-tags: true' on the checkout step."
+            exit 1
+          fi
+
       - name: Run semantic-release (local bump only)
         env:
           GH_TOKEN: ${{ secrets.RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
@@ -105,11 +132,21 @@ jobs:
           fi
 
           VERSION="$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")"
+          TAG="v${VERSION}"
+
+          # Final guard: if the tag already exists on the remote, bail before
+          # any irreversible promote-* step runs (PyPI, main push, GH Release).
+          if git ls-remote --tags origin "refs/tags/${TAG}" | grep -q .; then
+            echo "ERROR: tag ${TAG} already exists on the remote."
+            echo "This means semantic-release computed a version that is already released."
+            exit 1
+          fi
+
           echo "release_created=true" >> "$GITHUB_OUTPUT"
           echo "changelog_validated=passed" >> "$GITHUB_OUTPUT"
-          echo "release_tag=v${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "release_tag=${TAG}" >> "$GITHUB_OUTPUT"
           echo "release_version=${VERSION}" >> "$GITHUB_OUTPUT"
-          echo "Prepared v${VERSION} as patch against ${{ github.sha }}"
+          echo "Prepared ${TAG} as patch against ${{ github.sha }}"
 
       - name: Upload release patch
         if: steps.verify_release.outputs.release_created == 'true'
@@ -359,11 +396,50 @@ jobs:
         run: |
           uv run --no-sync mkdocs build
 
-  publish-github-release:
-    name: Commit, tag, and create GitHub Release
+  # ---------------------------------------------------------------------------
+  # Promote phase: every validation above has passed. Irreversible steps now
+  # run in a strict order:
+  #   promote-pypi  -> publishes to PyPI (first irreversible action)
+  #   promote-git   -> commits bump, pushes main, creates tag, creates GH Release
+  #   promote-docs  -> deploys MkDocs site pinned to the new tag
+  # If promote-pypi fails, main is untouched and the run can be re-triggered.
+  # ---------------------------------------------------------------------------
+
+  promote-pypi:
+    name: Publish to PyPI
     needs: [prepare-release, build-wheels, build-sdist, test-wheels, verify-docs]
     if: needs.prepare-release.outputs.release_created == 'true'
     runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ferro-orm
+    permissions:
+      id-token: write
+    steps:
+      - name: Download sdist
+        uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+      - name: Download wheels
+        uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+          verbose: true
+
+  promote-git:
+    name: Commit, tag, and create GitHub Release
+    needs: [prepare-release, promote-pypi]
+    if: needs.prepare-release.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
     permissions:
       contents: write
       issues: write
@@ -372,13 +448,15 @@ jobs:
       - name: Disable Git CRLF conversion before checkout
         shell: bash
         run: git config --global core.autocrlf false
+
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
           ref: ${{ needs.prepare-release.outputs.release_base_sha }}
           fetch-depth: 0
+          fetch-tags: true
           ssh-key: ${{ secrets.RELEASE_DEPLOY_KEY }}
-          # Required so the deploy key stays loaded for git push in the next step.
+          # Required so the deploy key stays loaded for git push below.
           persist-credentials: true
 
       - name: Download release patch
@@ -401,8 +479,10 @@ jobs:
           git config user.name "github-actions[bot]"
           git remote set-url origin "git@github.com:${{ github.repository }}.git"
 
+          # Re-check remote (prepare-release already checked, but the window
+          # between jobs is non-zero).
           if git ls-remote --tags origin "refs/tags/${TAG}" | grep -q .; then
-            echo "ERROR: tag ${TAG} already exists on the remote."
+            echo "ERROR: tag ${TAG} appeared on the remote between jobs."
             exit 1
           fi
 
@@ -412,7 +492,7 @@ jobs:
             -m "Automatically generated by python-semantic-release"
           git push origin "HEAD:refs/heads/${{ github.ref_name }}"
 
-          git tag "${TAG}"
+          git tag -a "${TAG}" -m "Release ${TAG}"
           git push origin "refs/tags/${TAG}"
 
       # semantic-release matches branch config (e.g. branches.main); detached HEAD fails with
@@ -430,57 +510,38 @@ jobs:
         with:
           enable-cache: true
 
-      - name: Set up Rust
-        uses: dtolnay/rust-toolchain@stable
-
-      - name: Cache Rust dependencies
-        uses: Swatinem/rust-cache@v2
-        with:
-          prefix-key: "v1-rust"
-
       - name: Install dependencies
         run: |
           uv sync --only-group release --no-install-project --python 3.13
 
-      - name: Publish GitHub release (assets + VCS release)
-        env:
-          GH_TOKEN: ${{ secrets.RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
-        run: |
-          uv run semantic-release publish --tag "${{ needs.prepare-release.outputs.release_tag }}"
-
-  publish-pypi:
-    name: Publish to PyPI
-    needs: [prepare-release, publish-github-release]
-    if: needs.prepare-release.outputs.release_created == 'true'
-    runs-on: ubuntu-latest
-    environment:
-      name: pypi
-      url: https://pypi.org/p/ferro-orm
-    permissions:
-      id-token: write
-    steps:
-      - name: Download sdist
+      # semantic-release publish only uploads assets to an existing GitHub
+      # Release. Create the release with generated notes first, then attach
+      # wheels + sdist from the validation jobs.
+      - name: Download sdist for GitHub Release assets
         uses: actions/download-artifact@v4
         with:
           name: sdist
           path: dist
 
-      - name: Download wheels
+      - name: Download wheels for GitHub Release assets
         uses: actions/download-artifact@v4
         with:
           pattern: wheels-*
           path: dist
           merge-multiple: true
 
-      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          skip-existing: true
-          verbose: true
+      - name: Create GitHub Release and upload assets
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          TAG="${{ needs.prepare-release.outputs.release_tag }}"
+          uv run semantic-release changelog --post-to-release-tag "$TAG"
+          uv run semantic-release publish --tag "$TAG"
 
-  deploy-docs:
+  promote-docs:
     name: Deploy Documentation
-    needs: [prepare-release, publish-pypi]
+    needs: [prepare-release, promote-git]
     if: needs.prepare-release.outputs.release_created == 'true'
     uses: ./.github/workflows/publish-docs.yml
     permissions:

{ferro_orm-0.3.0 → ferro_orm-0.3.1}/.gitignore

@@ -243,5 +243,4 @@ playground.ipynb
 IMPLEMENTATION.md
 Cargo.lock
 demo.db
-docs/superpowers/plans/2026-04-22-shadow-fk-types.md
-docs/superpowers/specs/2026-04-22-shadow-fk-types-design.md
+docs/superpowers

{ferro_orm-0.3.0 → ferro_orm-0.3.1}/CHANGELOG.md

@@ -1,7 +1,38 @@
 # CHANGELOG
 
 
-## v0.3.0 (2026-04-22)
+## v0.3.1 (2026-04-23)
+
+### Bug Fixes
+
+- Alembic autogenerate named SQLAlchemy enums for PostgreSQL
+  ([`25a00e8`](https://github.com/syn54x/ferro-orm/commit/25a00e84502ae1f8ba502718934d93eedfa4ce09))
+
+- **migrations**: Align nullable inference with field types
+  ([`885f0fe`](https://github.com/syn54x/ferro-orm/commit/885f0fe155dfa643e29b9425ff1ede62f3f0b269))
+
+- **migrations**: Propagate ForeignKey(unique=True) to Alembic metadata
+  ([#22](https://github.com/syn54x/ferro-orm/pull/22),
+  [`9329e8f`](https://github.com/syn54x/ferro-orm/commit/9329e8fba2f0efd201bea4545393654c7d1dd34e))
+
+### Continuous Integration
+
+- Fix release
+  ([`e2822f6`](https://github.com/syn54x/ferro-orm/commit/e2822f6c9bacc6fc955e56b2ca8e120cc22b0b72))
+
+- Fix release
+  ([`e5c1adc`](https://github.com/syn54x/ferro-orm/commit/e5c1adcc10eb44845ef95d78226840ecdbfd0ebd))
+
+- Fix release
+  ([`688d01b`](https://github.com/syn54x/ferro-orm/commit/688d01bdae0aff1f82e4a1bb60dd1b8ab35e1d01))
+
+### Documentation
+
+- Prefer Field over FerroField
+  ([`3385cfa`](https://github.com/syn54x/ferro-orm/commit/3385cfadf0951f80827dac1aa08f73430a02023f))
+
+
+## v0.3.0 (2026-04-23)
 
 ### Bug Fixes
 
@@ -18,9 +49,6 @@
 
 ### Continuous Integration
 
-- Fix release
-  ([`688d01b`](https://github.com/syn54x/ferro-orm/commit/688d01bdae0aff1f82e4a1bb60dd1b8ab35e1d01))
-
 - Fix release
   ([`249e460`](https://github.com/syn54x/ferro-orm/commit/249e46058bac87215920083a9d45557f3c58b62f))
 

{ferro_orm-0.3.0 → ferro_orm-0.3.1}/Cargo.lock

@@ -294,7 +294,7 @@ dependencies = [
 
 [[package]]
 name = "ferro"
-version = "0.3.0"
+version = "0.3.1"
 dependencies = [
  "dashmap",
  "once_cell",

{ferro_orm-0.3.0 → ferro_orm-0.3.1}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ferro"
-version = "0.3.0"
+version = "0.3.1"
 edition = "2024"
 readme = "README.md"
 

{ferro_orm-0.3.0 → ferro_orm-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferro-orm
-Version: 0.3.0
+Version: 0.3.1
 Requires-Dist: pydantic>=2.0
 License-File: LICENSE
 Summary: A high-performance, Rust-backed ORM for Python.
@@ -55,11 +55,10 @@ pip install "ferro-orm[alembic]"
 
 ```python
 import asyncio
-from typing import Annotated
-from ferro import Model, FerroField, connect
+from ferro import Field, Model, connect
 
 class User(Model):
-    id: Annotated[int, FerroField(primary_key=True)]
+    id: int | None = Field(default=None, primary_key=True)
     username: str
     is_active: bool = True
 

{ferro_orm-0.3.0 → ferro_orm-0.3.1}/README.md

@@ -45,11 +45,10 @@ pip install "ferro-orm[alembic]"
 
 ```python
 import asyncio
-from typing import Annotated
-from ferro import Model, FerroField, connect
+from ferro import Field, Model, connect
 
 class User(Model):
-    id: Annotated[int, FerroField(primary_key=True)]
+    id: int | None = Field(default=None, primary_key=True)
     username: str
     is_active: bool = True
 

{ferro_orm-0.3.0 → ferro_orm-0.3.1}/docs/TEST_RESULTS.md

@@ -27,7 +27,7 @@ All field types and constraints work as documented:
 - Basic model definition ✅
 - All documented field types (str, int, Decimal, date, dict, Enum) ✅
 - Enum field type with proper serialization/deserialization ✅
-- Field() Pydantic-style constraints ✅
+- Field() Pydantic-style constraints ✅ (preferred in user-facing docs)
 - FerroField() Annotated-style constraints ✅
 - Unique constraints ✅
 
@@ -131,8 +131,10 @@ await User.where(User.role.in_([UserRole.ADMIN.value, UserRole.MODERATOR.value])
 **Working Pattern**: Primary keys should be optional with None default:
 
 ```python
+from ferro import Field, Model
+
 class User(Model):
-    id: Annotated[int | None, FerroField(primary_key=True)] = None
+    id: int | None = Field(default=None, primary_key=True)
     username: str
 ```
 

ferro_orm-0.3.1/docs/api/fields.md

@@ -0,0 +1,21 @@
+# Fields API
+
+Complete reference for field types and metadata. In application models, use **`ferro.Field`** in either the **assignment** or **annotation** pattern described in the [models & fields guide](../guide/models-and-fields.md#field-constraints). **`FerroField`** is the lower-level metadata type; `Field(...)` is normalized into the same shape internally.
+
+## Field
+
+::: ferro.fields.Field
+    options:
+      show_source: false
+      heading_level: 3
+
+## FerroField
+
+::: ferro.base.FerroField
+    options:
+      show_source: false
+      heading_level: 3
+
+## See Also
+
+- [Models & Fields Guide](../guide/models-and-fields.md)

{ferro_orm-0.3.0 → ferro_orm-0.3.1}/docs/coming-soon.md

@@ -429,12 +429,16 @@ Many-to-many relationships are defined with `ManyToManyField`, but the join tabl
 
 **Example (Partially Working):**
 ```python
+from typing import Annotated
+
+from ferro import BackRef, Field, ManyToManyField, Model
+
 class Post(Model):
-    id: Annotated[int | None, FerroField(primary_key=True)] = None
+    id: int | None = Field(default=None, primary_key=True)
     tags: Annotated[list["Tag"], ManyToManyField(related_name="posts")] = None
 
 class Tag(Model):
-    id: Annotated[int | None, FerroField(primary_key=True)] = None
+    id: int | None = Field(default=None, primary_key=True)
     posts: BackRef[list["Post"]] | None = None
 
 # Models created, but join table 'post_tags' is NOT auto-created

{ferro_orm-0.3.0 → ferro_orm-0.3.1}/docs/concepts/architecture.md

@@ -192,9 +192,11 @@ sequenceDiagram
 
 Python model:
 ```python
+from ferro import Field, Model
+
 class User(Model):
-    id: Annotated[int, FerroField(primary_key=True)]
-    username: Annotated[str, FerroField(unique=True)]
+    id: int | None = Field(default=None, primary_key=True)
+    username: str = Field(unique=True)
     email: str
 ```
 

{ferro_orm-0.3.0 → ferro_orm-0.3.1}/docs/concepts/performance.md

@@ -102,10 +102,14 @@ await User.where(User.is_active == False).update(status="archived")
 ### 3. Index Frequently Filtered Fields
 
 ```python
+from datetime import datetime
+
+from ferro import Field, Model
+
 class User(Model):
-    email: Annotated[str, FerroField(unique=True, index=True)]
-    status: Annotated[str, FerroField(index=True)]
-    created_at: Annotated[datetime, FerroField(index=True)]
+    email: str = Field(unique=True, index=True)
+    status: str = Field(index=True)
+    created_at: datetime = Field(index=True)
 ```
 
 ### 4. Use `.exists()` Instead of `.count()`

{ferro_orm-0.3.0 → ferro_orm-0.3.1}/docs/getting-started/tutorial.md

@@ -26,17 +26,17 @@ Let's create a blog with users, posts, and comments:
 import asyncio
 from datetime import datetime
 from typing import Annotated
-from ferro import Model, FerroField, ForeignKey, BackRef, connect
+from ferro import Model, Field, ForeignKey, BackRef, connect
 
 class User(Model):
-    id: Annotated[int, FerroField(primary_key=True)]
-    username: Annotated[str, FerroField(unique=True)]
-    email: Annotated[str, FerroField(unique=True)]
+    id: int | None = Field(default=None, primary_key=True)
+    username: str = Field(unique=True)
+    email: str = Field(unique=True)
     posts: BackRef[list["Post"]] | None = None
     comments: BackRef[list["Comment"]] | None = None
 
 class Post(Model):
-    id: Annotated[int, FerroField(primary_key=True)]
+    id: int | None = Field(default=None, primary_key=True)
     title: str
     content: str
     published: bool = False
@@ -45,7 +45,7 @@ class Post(Model):
     comments: BackRef[list["Comment"]] | None = None
 
 class Comment(Model):
-    id: Annotated[int, FerroField(primary_key=True)]
+    id: int | None = Field(default=None, primary_key=True)
     text: str
     created_at: datetime = datetime.now()
     author: Annotated[User, ForeignKey(related_name="comments")]
@@ -305,17 +305,17 @@ Here's the full tutorial code:
 import asyncio
 from datetime import datetime
 from typing import Annotated
-from ferro import Model, FerroField, ForeignKey, BackRef, connect
+from ferro import Model, Field, ForeignKey, BackRef, connect
 
 class User(Model):
-    id: Annotated[int, FerroField(primary_key=True)]
-    username: Annotated[str, FerroField(unique=True)]
-    email: Annotated[str, FerroField(unique=True)]
+    id: int | None = Field(default=None, primary_key=True)
+    username: str = Field(unique=True)
+    email: str = Field(unique=True)
     posts: BackRef[list["Post"]] | None = None
     comments: BackRef[list["Comment"]] | None = None
 
 class Post(Model):
-    id: Annotated[int, FerroField(primary_key=True)]
+    id: int | None = Field(default=None, primary_key=True)
     title: str
     content: str
     published: bool = False
@@ -324,7 +324,7 @@ class Post(Model):
     comments: BackRef[list["Comment"]] | None = None
 
 class Comment(Model):
-    id: Annotated[int, FerroField(primary_key=True)]
+    id: int | None = Field(default=None, primary_key=True)
     text: str
     created_at: datetime = datetime.now()
     author: Annotated[User, ForeignKey(related_name="comments")]
@@ -367,7 +367,7 @@ if __name__ == "__main__":
 In this tutorial, you learned:
 
 ✅ How to define models with `Model` and type hints
-✅ How to add constraints with `FerroField` or `Field`
+✅ How to add constraints with `Field()` (assignment or `Annotated[..., Field(...)]`)
 ✅ How to create relationships with `ForeignKey` and `BackRef`
 ✅ How to connect to a database with `connect()`
 ✅ How to create records with `.create()`