ferro-orm 0.3.4__tar.gz → 0.4.0__tar.gz

{ferro_orm-0.3.4 → ferro_orm-0.4.0}/CHANGELOG.md

@@ -1,6 +1,19 @@
 # CHANGELOG
 
 
+## v0.4.0 (2026-04-27)
+
+### Bug Fixes
+
+- Correct BackRef type hinting for all/first
+  ([`6171923`](https://github.com/syn54x/ferro-orm/commit/617192328d77a8159c671ed6e469dc489c462e42))
+
+### Features
+
+- Redesign relationship declarations
+  ([`911e77d`](https://github.com/syn54x/ferro-orm/commit/911e77d15a63df893543bfe6500c5283e8f066f3))
+
+
 ## v0.3.4 (2026-04-25)
 
 ### Bug Fixes

{ferro_orm-0.3.4 → ferro_orm-0.4.0}/Cargo.lock

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

{ferro_orm-0.3.4 → ferro_orm-0.4.0}/Cargo.toml

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

{ferro_orm-0.3.4 → ferro_orm-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferro-orm
-Version: 0.3.4
+Version: 0.4.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: alembic>=1.18.1 ; extra == 'alembic'
 Requires-Dist: sqlalchemy>=2.0.46 ; extra == 'alembic'

{ferro_orm-0.3.4 → ferro_orm-0.4.0}/docs/api/relationships.md

@@ -9,16 +9,23 @@ Complete reference for relationship types.
       show_source: false
       heading_level: 3
 
-## ManyToManyField
+## Relation
 
-::: ferro.base.ManyToManyField
+::: ferro.query.builder.Relation
     options:
       show_source: false
       heading_level: 3
 
 ## BackRef
 
-::: ferro.query.builder.BackRef
+::: ferro.fields.BackRef
+    options:
+      show_source: false
+      heading_level: 3
+
+## ManyToMany
+
+::: ferro.fields.ManyToMany
     options:
       show_source: false
       heading_level: 3

{ferro_orm-0.3.4 → ferro_orm-0.4.0}/docs/coming-soon.md

@@ -425,21 +425,21 @@ Document the exception hierarchy and import paths:
 - `docs/guide/relationships.md` (lines 176-289)
 
 **Description:**
-Many-to-many relationships are defined with `ManyToManyField`, but the join tables are not automatically created during `auto_migrate=True`.
+Many-to-many relationships are defined with `ManyToMany(...)`, but the join tables are not automatically created during `auto_migrate=True`.
 
 **Example (Partially Working):**
 ```python
 from typing import Annotated
 
-from ferro import BackRef, Field, ManyToManyField, Model
+from ferro import BackRef, Field, ManyToMany, Model, Relation
 
 class Post(Model):
     id: int | None = Field(default=None, primary_key=True)
-    tags: Annotated[list["Tag"], ManyToManyField(related_name="posts")] = None
+    tags: Relation[list["Tag"]] = ManyToMany(related_name="posts")
 
 class Tag(Model):
     id: int | None = Field(default=None, primary_key=True)
-    posts: BackRef[list["Post"]] | None = None
+    posts: Relation[list["Post"]] = BackRef()
 
 # Models created, but join table 'post_tags' is NOT auto-created
 # This causes errors when trying to use M2M methods:
@@ -467,7 +467,7 @@ Documentation states that one-to-one reverse relations automatically return a si
 ```python
 class User(Model):
     id: int
-    profile: BackRef["Profile"] | None = None
+    profile: "Profile" = BackRef()
 
 class Profile(Model):
     id: int

{ferro_orm-0.3.4 → ferro_orm-0.4.0}/docs/getting-started/tutorial.md

@@ -26,14 +26,14 @@ Let's create a blog with users, posts, and comments:
 import asyncio
 from datetime import datetime
 from typing import Annotated
-from ferro import Model, Field, ForeignKey, BackRef, connect
+from ferro import Model, Field, ForeignKey, BackRef, Relation, connect
 
 class User(Model):
     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
+    posts: Relation[list["Post"]] = BackRef()
+    comments: Relation[list["Comment"]] = BackRef()
 
 class Post(Model):
     id: int | None = Field(default=None, primary_key=True)
@@ -42,7 +42,7 @@ class Post(Model):
     published: bool = False
     created_at: datetime = datetime.now()
     author: Annotated[User, ForeignKey(related_name="posts")]
-    comments: BackRef[list["Comment"]] | None = None
+    comments: Relation[list["Comment"]] = BackRef()
 
 class Comment(Model):
     id: int | None = Field(default=None, primary_key=True)
@@ -305,14 +305,14 @@ Here's the full tutorial code:
 import asyncio
 from datetime import datetime
 from typing import Annotated
-from ferro import Model, Field, ForeignKey, BackRef, connect
+from ferro import Model, Field, ForeignKey, BackRef, Relation, connect
 
 class User(Model):
     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
+    posts: Relation[list["Post"]] = BackRef()
+    comments: Relation[list["Comment"]] = BackRef()
 
 class Post(Model):
     id: int | None = Field(default=None, primary_key=True)
@@ -321,7 +321,7 @@ class Post(Model):
     published: bool = False
     created_at: datetime = datetime.now()
     author: Annotated[User, ForeignKey(related_name="posts")]
-    comments: BackRef[list["Comment"]] | None = None
+    comments: Relation[list["Comment"]] = BackRef()
 
 class Comment(Model):
     id: int | None = Field(default=None, primary_key=True)

{ferro_orm-0.3.4 → ferro_orm-0.4.0}/docs/guide/migrations.md

@@ -301,7 +301,7 @@ class Post(Model):
 
 ```python
 class Student(Model):
-    courses: Annotated[list["Course"], ManyToManyField(related_name="students")]
+    courses: Relation[list["Course"]] = ManyToMany(related_name="students")
 
 # Automatically generates join table:
 # CREATE TABLE student_courses (

{ferro_orm-0.3.4 → ferro_orm-0.4.0}/docs/guide/models-and-fields.md

@@ -159,7 +159,7 @@ class OrgMembership(Model):
 
 **Wire format:** Declarations use nested tuples in Python; the schema JSON sent to the Rust engine uses nested lists (`ferro_composite_uniques`) because JSON has no tuple type.
 
-**Many-to-many join tables:** When you use `ManyToManyField` without a custom `through` table, Ferro creates a default join table with two foreign-key columns. That table automatically gets a composite unique on those two columns so the same link cannot be stored twice. If you already have duplicate rows in such a table, adding this constraint in a migration may require a data cleanup step first.
+**Many-to-many join tables:** When you use `ManyToMany(...)` without a custom `through` table, Ferro creates a default join table with two foreign-key columns. That table automatically gets a composite unique on those two columns so the same link cannot be stored twice. If you already have duplicate rows in such a table, adding this constraint in a migration may require a data cleanup step first.
 
 See also [Schema management / migrations](migrations.md) for how composite uniques appear in Alembic metadata.
 

{ferro_orm-0.3.4 → ferro_orm-0.4.0}/docs/guide/relationships.md

@@ -8,12 +8,12 @@ Relationships in Ferro are **lazy** — data is never fetched until you explicit
 
 ### API Styles
 
-Like scalar field constraints ([assignment vs `Annotated[..., Field(...)]`](models-and-fields.md#field-constraints)), relationships can be declared in two equivalent styles:
+Like scalar field constraints ([assignment vs `Annotated[..., Field(...)]`](models-and-fields.md#field-constraints)), relationship metadata can be declared in two equivalent styles:
 
-- **Annotated-style** (`BackRef`): Type-first approach using `typing.Annotated`
-- **Pydantic-style** (`Field(back_ref=True)`): Familiar `Field()` syntax
+- **Helper-style** (`BackRef()`, `ManyToMany(...)`): Recommended relationship helpers
+- **Field-style** (`Field(back_ref=True)`, `Field(many_to_many=True, ...)`): Lower-level `Field()` syntax
 
-Choose one style and use it consistently. Do not mix `BackRef` and `back_ref=True` on the same field.
+Collection relationships are typed with `Relation[list[T]]`, which reflects the lazy query-like object returned at runtime.
 
 ### Lazy Loading Behavior
 
@@ -51,16 +51,16 @@ erDiagram
     }
 ```
 
-### Annotated-style (with `BackRef`)
+### Helper-style (with `BackRef()`)
 
 ```python
 from typing import Annotated
-from ferro import Model, ForeignKey, BackRef
+from ferro import Model, ForeignKey, BackRef, Relation
 
 class Author(Model):
     id: int
     name: str
-    posts: BackRef[list["Post"]] | None = None
+    posts: Relation[list["Post"]] = BackRef()
 
 class Post(Model):
     id: int
@@ -68,15 +68,15 @@ class Post(Model):
     author: Annotated[Author, ForeignKey(related_name="posts")]
 ```
 
-### Pydantic-style (with `Field(back_ref=True)`)
+### Field-style (with `Field(back_ref=True)`)
 
 ```python
-from ferro import Model, ForeignKey, Field
+from ferro import Model, ForeignKey, Field, Relation
 
 class Author(Model):
     id: int
     name: str
-    posts: list["Post"] | None = Field(default=None, back_ref=True)
+    posts: Relation[list["Post"]] = Field(back_ref=True)
 
 class Post(Model):
     id: int
@@ -84,7 +84,7 @@ class Post(Model):
     author: Annotated[Author, ForeignKey(related_name="posts")]
 ```
 
-You can also use `Annotated` with `Field`: `posts: Annotated[list["Post"] | None, Field(back_ref=True)] = None`
+You can also use `Annotated` with `Field`: `posts: Annotated[Relation[list["Post"]], Field(back_ref=True)]`
 
 ### Shadow Fields
 
@@ -152,7 +152,7 @@ from ferro import Model, ForeignKey, BackRef
 class User(Model):
     id: int
     username: str
-    profile: BackRef["Profile"] | None = None  # Note: singular, not list
+    profile: "Profile" = BackRef()  # Note: singular relationships do not use Relation
 
 class Profile(Model):
     id: int
@@ -183,7 +183,7 @@ profile_user = await profile.user  # Returns User instance
 
 ## Many-to-Many
 
-Defined using `ManyToManyField`. Ferro automatically manages the hidden join table required for this relationship.
+Defined using `ManyToMany(...)`. Ferro automatically manages the hidden join table required for this relationship.
 
 ```mermaid
 erDiagram
@@ -198,37 +198,36 @@ erDiagram
     }
 ```
 
-### Annotated-style (with `BackRef`)
+### Helper-style (with `ManyToMany()` / `BackRef()`)
 
 ```python
-from typing import Annotated
-from ferro import Model, ManyToManyField, BackRef
+from ferro import Model, ManyToMany, BackRef, Relation
 
 class Student(Model):
     id: int
     name: str
-    courses: Annotated[list["Course"], ManyToManyField(related_name="students")] = None
+    courses: Relation[list["Course"]] = ManyToMany(related_name="students")
 
 class Course(Model):
     id: int
     title: str
-    students: BackRef[list["Student"]] | None = None
+    students: Relation[list["Student"]] = BackRef()
 ```
 
-### Pydantic-style (with `Field(back_ref=True)`)
+### Field-style (with `Field(...)`)
 
 ```python
-from ferro import Model, ManyToManyField, Field
+from ferro import Model, Field, Relation
 
 class Student(Model):
     id: int
     name: str
-    courses: Annotated[list["Course"], ManyToManyField(related_name="students")] = None
+    courses: Relation[list["Course"]] = Field(many_to_many=True, related_name="students")
 
 class Course(Model):
     id: int
     title: str
-    students: list["Student"] | None = Field(default=None, back_ref=True)
+    students: Relation[list["Student"]] = Field(back_ref=True)
 ```
 
 ### Join Table
@@ -308,7 +307,7 @@ class Employee(Model):
     id: int
     name: str
     manager: Annotated["Employee", ForeignKey(related_name="reports")] | None = None
-    reports: BackRef[list["Employee"]] | None = None
+    reports: Relation[list["Employee"]] = BackRef()
 
 # Usage
 manager = await Employee.create(name="Jane")

{ferro_orm-0.3.4 → ferro_orm-0.4.0}/docs/howto/testing.md

@@ -74,7 +74,7 @@ If no external Postgres URL is set and local PostgreSQL server binaries are unav
 
 ### Bridge-Boundary Regressions
 
-When a bug involves values crossing the Python/Rust bridge, preserve the public API shape in the regression test. These issues often depend on whether a value travels as JSON (`Query.all()`, `Query.count()`, `Query.update()`, `Query.delete()`) or as a typed Python value passed directly to Rust (`ManyToManyField.add()`, `.remove()`, `.clear()`).
+When a bug involves values crossing the Python/Rust bridge, preserve the public API shape in the regression test. These issues often depend on whether a value travels as JSON (`Query.all()`, `Query.count()`, `Query.update()`, `Query.delete()`) or as a typed Python value passed directly to Rust (`ManyToMany(...).add()`, `.remove()`, `.clear()`).
 
 Use these conventions:
 

{ferro_orm-0.3.4 → ferro_orm-0.4.0}/docs/index.md

@@ -29,12 +29,12 @@
 ```python
 import asyncio
 from typing import Annotated
-from ferro import Model, Field, ForeignKey, BackRef, connect
+from ferro import Model, Field, ForeignKey, BackRef, Relation, connect
 
 class Author(Model):
     id: int | None = Field(default=None, primary_key=True)
     name: str
-    posts: BackRef[list["Post"]] | None = None
+    posts: Relation[list["Post"]] = BackRef()
 
 class Post(Model):
     id: int | None = Field(default=None, primary_key=True)

{ferro_orm-0.3.4 → ferro_orm-0.4.0}/docs/migration-sqlalchemy.md

@@ -89,11 +89,11 @@ class Post(Base):
 # Ferro
 from typing import Annotated
 
-from ferro import BackRef, Field, ForeignKey, Model
+from ferro import BackRef, Field, ForeignKey, Model, Relation
 
 class User(Model):
     id: int | None = Field(default=None, primary_key=True)
-    posts: BackRef[list["Post"]] | None = None
+    posts: Relation[list["Post"]] = BackRef()
 
 class Post(Model):
     id: int | None = Field(default=None, primary_key=True)

{ferro_orm-0.3.4 → ferro_orm-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ferro-orm"
-version = "0.3.4"
+version = "0.4.0"
 description = "A high-performance, Rust-backed ORM for Python."
 readme = "README.md"
 authors = [

{ferro_orm-0.3.4 → ferro_orm-0.4.0}/scripts/demo_queries.py

@@ -19,8 +19,9 @@ from ferro import (
     BackRef,
     FerroField,
     ForeignKey,
-    ManyToManyField,
+    ManyToMany,
     Model,
+    Relation,
     connect,
     transaction,
 )
@@ -40,7 +41,7 @@ class Category(Model):
     id: Annotated[int | None, FerroField(primary_key=True)] = None
     name: str
     # Reverse lookup marker (Zero-Boilerplate)
-    products: BackRef[list["Product"]] = None
+    products: Relation[list["Product"]] = BackRef()
 
 
 class Product(Model):
@@ -59,13 +60,13 @@ class Product(Model):
 class Actor(Model):
     id: Annotated[int | None, FerroField(primary_key=True)] = None
     name: str
-    movies: Annotated[list["Movie"], ManyToManyField(related_name="actors")] = None
+    movies: Relation[list["Movie"]] = ManyToMany(related_name="actors")
 
 
 class Movie(Model):
     id: Annotated[int | None, FerroField(primary_key=True)] = None
     title: str
-    actors: BackRef[list[Actor]] = None
+    actors: Relation[list[Actor]] = BackRef()
 
 
 async def run_demo():

{ferro_orm-0.3.4 → ferro_orm-0.4.0}/src/ferro/__init__.py

@@ -17,10 +17,10 @@ from ._core import (
 from ._core import (
     connect as _core_connect,
 )
-from .base import FerroField, FerroNullable, ForeignKey, ManyToManyField
-from .fields import Field
+from .base import FerroField, FerroNullable, ForeignKey
+from .fields import BackRef, Field, ManyToMany
 from .models import Model, transaction
-from .query import BackRef
+from .query import Relation
 
 # Set up the Ferro logger
 _logger = logging.getLogger("ferro")
@@ -58,8 +58,9 @@ __all__ = [
     "FerroNullable",
     "Field",
     "ForeignKey",
-    "ManyToManyField",
     "BackRef",
+    "ManyToMany",
+    "Relation",
     "version",
     "create_tables",
     "reset_engine",

{ferro_orm-0.3.4 → ferro_orm-0.4.0}/src/ferro/base.py

@@ -140,7 +140,9 @@ class ForeignKey:
         self.unique = unique
         self.nullable = _validate_nullable_option(nullable, "ForeignKey")
         if str(self.on_delete).upper() == "SET NULL" and self.nullable is False:
-            raise ValueError("ForeignKey(on_delete='SET NULL') requires nullable=True or 'infer'")
+            raise ValueError(
+                "ForeignKey(on_delete='SET NULL') requires nullable=True or 'infer'"
+            )
         #: First type argument of ``Annotated[..., ForeignKey]``; set by the metaclass
         #: for Alembic nullability inference (forward fields are not in ``model_fields``).
         self.relation_annotation: Any | None = None
@@ -160,8 +162,8 @@ def foreign_key_allows_none(metadata: "ForeignKey") -> bool | None:
     return annotation_allows_none(relation_annotation)
 
 
-class ManyToManyField:
-    """Describe metadata for a many-to-many relationship
+class ManyToManyRelation:
+    """Describe internal metadata for a many-to-many relationship
 
     Attributes:
 
@@ -178,7 +180,7 @@ class ManyToManyField:
         >>>
         >>> class Post(Model):
         ...     id: Annotated[int, FerroField(primary_key=True)]
-        ...     tags: Annotated[list[int], ManyToManyField("posts")]
+        ...     tags: Relation[list["Tag"]] = ManyToMany(related_name="posts")
     """
 
     def __init__(self, related_name: str, through: str | None = None):
@@ -196,7 +198,7 @@ class ManyToManyField:
             >>>
             >>> class User(Model):
             ...     id: Annotated[int, FerroField(primary_key=True)]
-            ...     teams: Annotated[list[int], ManyToManyField("members", through="team_members")]
+            ...     teams: Relation[list["Team"]] = ManyToMany(related_name="members", through="team_members")
         """
         self.to = None  # Resolved later
         self.related_name = related_name

{ferro_orm-0.3.4 → ferro_orm-0.4.0}/src/ferro/fields.py

@@ -33,6 +33,9 @@ def Field(
     unique: bool = ...,
     index: bool = ...,
     back_ref: bool = ...,
+    many_to_many: bool = ...,
+    related_name: str | None = ...,
+    through: str | None = ...,
     nullable: FerroNullable = ...,
     alias: str | None = ...,
     alias_priority: int | None = ...,
@@ -81,6 +84,9 @@ def Field(
     unique: bool = ...,
     index: bool = ...,
     back_ref: bool = ...,
+    many_to_many: bool = ...,
+    related_name: str | None = ...,
+    through: str | None = ...,
     nullable: FerroNullable = ...,
     alias: str | None = ...,
     alias_priority: int | None = ...,
@@ -129,6 +135,9 @@ def Field(
     unique: bool = ...,
     index: bool = ...,
     back_ref: bool = ...,
+    many_to_many: bool = ...,
+    related_name: str | None = ...,
+    through: str | None = ...,
     nullable: FerroNullable = ...,
     alias: str | None = ...,
     alias_priority: int | None = ...,
@@ -176,6 +185,9 @@ def Field(
     unique: bool = ...,
     index: bool = ...,
     back_ref: bool = ...,
+    many_to_many: bool = ...,
+    related_name: str | None = ...,
+    through: str | None = ...,
     nullable: FerroNullable = ...,
     default_factory: Callable[[], Any] | Callable[[dict[str, Any]], Any],
     alias: str | None = ...,
@@ -224,6 +236,9 @@ def Field(
     unique: bool = ...,
     index: bool = ...,
     back_ref: bool = ...,
+    many_to_many: bool = ...,
+    related_name: str | None = ...,
+    through: str | None = ...,
     nullable: FerroNullable = ...,
     default_factory: Callable[[], _T] | Callable[[dict[str, Any]], _T],
     alias: str | None = ...,
@@ -272,6 +287,9 @@ def Field(
     unique: bool = ...,
     index: bool = ...,
     back_ref: bool = ...,
+    many_to_many: bool = ...,
+    related_name: str | None = ...,
+    through: str | None = ...,
     nullable: FerroNullable = ...,
     alias: str | None = ...,
     alias_priority: int | None = ...,
@@ -319,6 +337,9 @@ def Field(
     unique: bool | Any = _Unset,
     index: bool | Any = _Unset,
     back_ref: bool | Any = _Unset,
+    many_to_many: bool | Any = _Unset,
+    related_name: str | None | Any = _Unset,
+    through: str | None | Any = _Unset,
     nullable: FerroNullable | Any = _Unset,
     default_factory: Callable[[], Any]
     | Callable[[dict[str, Any]], Any]
@@ -369,8 +390,11 @@ def Field(
         unique: Add a **single-column** uniqueness constraint for this column in Ferro.
             Multi-column uniqueness is declared with ``__ferro_composite_uniques__`` on the model.
         index: Request an index for this column in Ferro.
-        back_ref: Mark this field as a reverse relationship (same as BackRef in the type).
-            Do not use together with a BackRef annotation on the same field.
+        back_ref: Mark this field as a reverse relationship. This is the lower-level
+            equivalent of assigning ``BackRef()`` as the field default.
+        many_to_many: Mark this field as a many-to-many relationship.
+        related_name: Reverse relationship field name used by many-to-many relationships.
+        through: Optional join table name used by many-to-many relationships.
         nullable: Alembic ``Column.nullable`` override for :func:`~ferro.migrations.get_metadata`.
             ``\"infer\"`` (default) derives nullability from the field annotation.
         default_factory: A callable to generate the default value. The callable can either take 0 arguments
@@ -451,6 +475,12 @@ def Field(
         ferro_kwargs["index"] = index
     if back_ref is not _Unset:
         ferro_kwargs["back_ref"] = back_ref
+    if many_to_many is not _Unset:
+        ferro_kwargs["many_to_many"] = many_to_many
+    if related_name is not _Unset:
+        ferro_kwargs["related_name"] = related_name
+    if through is not _Unset:
+        ferro_kwargs["through"] = through
     if nullable is not _Unset:
         _validate_nullable_option(nullable, "Field")
         ferro_kwargs["nullable"] = nullable
@@ -512,4 +542,37 @@ def Field(
     )
 
 
-__all__ = ["Field", "FERRO_FIELD_EXTRA_KEY"]
+class BackRef:
+    """Declare a reverse relationship field.
+
+    ``BackRef()`` is a convenience wrapper around ``Field(back_ref=True)``.
+    """
+
+    def __new__(cls, **kwargs: Any) -> Any:
+        return Field(back_ref=True, **kwargs)
+
+    @classmethod
+    def __class_getitem__(cls, _item: Any) -> Any:
+        raise TypeError(
+            "BackRef[...] is no longer a type annotation. Use "
+            "Relation[list[T]] = BackRef() for collection back-references."
+        )
+
+
+def ManyToMany(
+    *,
+    related_name: str,
+    through: str | None = None,
+    **kwargs: Any,
+) -> Any:
+    """Declare a many-to-many relationship field."""
+
+    return Field(
+        many_to_many=True,
+        related_name=related_name,
+        through=through,
+        **kwargs,
+    )
+
+
+__all__ = ["Field", "BackRef", "ManyToMany", "FERRO_FIELD_EXTRA_KEY"]