plain.postgres 0.104.0__tar.gz → 0.105.0__tar.gz

{plain_postgres-0.104.0 → plain_postgres-0.105.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.postgres
-Version: 0.104.0
+Version: 0.105.0
 Summary: Model your data and store it in a database.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-Expression: BSD-3-Clause

{plain_postgres-0.104.0 → plain_postgres-0.105.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,19 @@
 # plain-postgres changelog
 
+## [0.105.0](https://github.com/dropseed/plain/releases/plain-postgres@0.105.0) (2026-05-25)
+
+### What's changed
+
+- **Field constructors in `plain.postgres.types` are now typed as parameterized descriptors.** Stubs return `XField[T]` (e.g. `TextField[str]`, `IntegerField[int | None]` when `allow_null=True`) instead of the primitive value. Combined with `Field[T]`'s overloaded `__get__`, class-level access (`User.email`) sees the descriptor and instance access (`user.email`) sees the value — no annotation needed on model declarations. ([229ecdbbfa](https://github.com/dropseed/plain/commit/229ecdbbfa))
+- **`Field.__set__` is now typed as `value: T`** instead of `Any`, so a type checker flags `row.name = 123` on a `TextField` at the call site. Runtime conversion via `to_python()` is unchanged. ([229ecdbbfa](https://github.com/dropseed/plain/commit/229ecdbbfa))
+- **`ForeignKeyField` overloads split by `to=` argument shape.** Passing a model class (`to=Author`) returns `_ForeignKeyDescriptor[T, V]` and accepts bare-PK assignment (`book.author = 5`) via `__set__`. Passing a string forward reference (`to="Author"`) returns the bare value type and requires an LHS annotation so the type can bind. ([229ecdbbfa](https://github.com/dropseed/plain/commit/229ecdbbfa))
+- `JSONField` and `EncryptedJSONField` keep explicit annotations on model declarations — their runtime classes aren't generic, so the stubs return `Any`. ([229ecdbbfa](https://github.com/dropseed/plain/commit/229ecdbbfa))
+
+### Upgrade instructions
+
+- **Drop primitive type annotations on model field declarations.** `name: str = types.TextField()` will now fail type checking because the right-hand side is typed `TextField[str]`, not `str`. Change to `name = types.TextField()` — type checkers still infer `str` at instance access through the descriptor's `__get__`. Runtime is unchanged either way.
+- **Keep explicit annotations for `JSONField` / `EncryptedJSONField`** — these still return `Any` from the stubs, so the declared type is what flows through. Example: `parameters: dict[str, Any] | None = types.JSONField(required=False, allow_null=True)`.
+
 ## [0.104.0](https://github.com/dropseed/plain/releases/plain-postgres@0.104.0) (2026-05-22)
 
 ### What's changed

{plain_postgres-0.104.0 → plain_postgres-0.105.0}/plain/postgres/agents/.claude/rules/plain-postgres.md

@@ -7,13 +7,32 @@ paths:
 
 ## Field Imports
 
-Import fields via `from plain.postgres import types` and annotate with Python types:
+Import fields via `from plain.postgres import types`. Don't add primitive
+annotations — the field stubs return typed descriptors that resolve to the
+right value type on instance access:
 
 ```python
 from plain.postgres import types
 
-name: str = types.TextField(max_length=100)
-car: Car = types.ForeignKeyField("Car", on_delete=postgres.CASCADE)
+name = types.TextField(max_length=100)
+car = types.ForeignKeyField(Car, on_delete=postgres.CASCADE)
+```
+
+For string forward references (`"self"`, `"OtherModel"`), the type checker
+can't infer the target type from the string — annotate explicitly so
+instance access keeps its type:
+
+```python
+parent: TreeNode | None = types.ForeignKeyField("self", on_delete=postgres.CASCADE, allow_null=True)
+```
+
+For `JSONField` and `EncryptedJSONField`, the stub returns `Any` (the
+runtime class isn't generic over its value shape), so annotate explicitly
+to preserve typing:
+
+```python
+parameters: dict[str, Any] | None = types.JSONField(required=False, allow_null=True)
+config: dict | None = types.EncryptedJSONField(required=False, allow_null=True)
 ```
 
 Do NOT import field classes directly from `plain.postgres` or `plain.postgres.fields`.

{plain_postgres-0.104.0 → plain_postgres-0.105.0}/plain/postgres/base.py

@@ -83,7 +83,7 @@ class ModelState:
 
 class Model(metaclass=ModelBase):
     # Every model gets an automatic id field
-    id: int = types.PrimaryKeyField()
+    id = types.PrimaryKeyField()
 
     # Descriptors for other model behavior
     query: QuerySet[Self] = QuerySet()

{plain_postgres-0.104.0 → plain_postgres-0.105.0}/plain/postgres/fields/base.py

@@ -437,12 +437,18 @@ class Field[T](RegisterLookupMixin):
 
         return cast(T, data.get(field_name))
 
-    def __set__(self, instance: Model, value: Any) -> None:
+    def __set__(self, instance: Model, value: T) -> None:
         """
         Descriptor __set__ for attribute assignment.
 
         Validates and converts the value using to_python(), then stores it
         in instance.__dict__[name].
+
+        The parameter is typed `T` (the field's value type) so a type checker
+        rejects assigning incompatible types — `row.name = 123` on a
+        TextField is caught at the call site. The runtime is more permissive
+        (to_python converts strings → ints etc.), but encouraging explicit
+        conversion at the boundary is the better default.
         """
         # Safety check: ensure field has been properly initialized
         if not hasattr(self, "column"):
@@ -454,12 +460,17 @@ class Field[T](RegisterLookupMixin):
 
         # Convert/validate the value. The DATABASE_DEFAULT sentinel is stored
         # as-is so the INSERT compiler can emit `DEFAULT` in the VALUES clause.
-        if value is not None and value is not DATABASE_DEFAULT:
-            value = self.to_python(value)
+        # Use a separate local so the parameter's narrow `T` type isn't
+        # widened by to_python's `T | None` return.
+        stored: Any
+        if value is None or value is DATABASE_DEFAULT:
+            stored = value
+        else:
+            stored = self.to_python(value)
 
         # Store in instance dict
         assert self.name is not None
-        instance.__dict__[self.name] = value
+        instance.__dict__[self.name] = stored
 
     def __delete__(self, instance: Model) -> None:
         """

{plain_postgres-0.104.0 → plain_postgres-0.105.0}/plain/postgres/fields/binary.py

@@ -15,7 +15,9 @@ if TYPE_CHECKING:
     from plain.postgres.sql.compiler import SQLCompiler
 
 
-class BinaryField(ColumnField[bytes | memoryview]):
+class BinaryField[
+    T: (bytes | memoryview, bytes | memoryview | None) = bytes | memoryview
+](ColumnField[T]):
     db_type_sql = "bytea"
     empty_values = [None, b""]
     _default_empty_value = b""

{plain_postgres-0.104.0 → plain_postgres-0.105.0}/plain/postgres/fields/boolean.py

@@ -7,7 +7,7 @@ from plain import exceptions
 from .base import DefaultableField
 
 
-class BooleanField(DefaultableField[bool]):
+class BooleanField[T: (bool, bool | None) = bool](DefaultableField[T]):
     db_type_sql = "boolean"
     empty_strings_allowed = False
 

{plain_postgres-0.104.0 → plain_postgres-0.105.0}/plain/postgres/fields/duration.py

@@ -13,7 +13,9 @@ if TYPE_CHECKING:
     from plain.postgres.connection import DatabaseConnection
 
 
-class DurationField(DefaultableField[datetime.timedelta]):
+class DurationField[
+    T: (datetime.timedelta, datetime.timedelta | None) = datetime.timedelta
+](DefaultableField[T]):
     """Store timedelta objects using PostgreSQL's interval type."""
 
     db_type_sql = "interval"

{plain_postgres-0.104.0 → plain_postgres-0.105.0}/plain/postgres/fields/encrypted.py

@@ -178,7 +178,9 @@ class EncryptedFieldMixin:
         return errors
 
 
-class EncryptedTextField(EncryptedFieldMixin, ColumnField[str]):
+class EncryptedTextField[T: (str, str | None) = str](
+    EncryptedFieldMixin, ColumnField[T]
+):
     """A text field that encrypts its value before storing in the database.
 
     Values are encrypted using Fernet (AES-128-CBC + HMAC-SHA256) with a key

{plain_postgres-0.104.0 → plain_postgres-0.105.0}/plain/postgres/fields/network.py

@@ -15,7 +15,7 @@ if TYPE_CHECKING:
     from plain.postgres.connection import DatabaseConnection
 
 
-class GenericIPAddressField(DefaultableField[str]):
+class GenericIPAddressField[T: (str, str | None) = str](DefaultableField[T]):
     db_type_sql = "inet"
     empty_strings_allowed = False
 

{plain_postgres-0.104.0 → plain_postgres-0.105.0}/plain/postgres/fields/numeric.py

@@ -16,7 +16,7 @@ if TYPE_CHECKING:
     from plain.postgres.connection import DatabaseConnection
 
 
-class FloatField(DefaultableField[float]):
+class FloatField[T: (float, float | None) = float](DefaultableField[T]):
     db_type_sql = "double precision"
     empty_strings_allowed = False
 
@@ -44,7 +44,7 @@ class FloatField(DefaultableField[float]):
             )
 
 
-class IntegerField(DefaultableField[int]):
+class IntegerField[T: (int, int | None) = int](DefaultableField[T]):
     db_type_sql = "integer"
     integer_range: tuple[int, int] = (-2147483648, 2147483647)
     psycopg_type: type = numeric.Int4
@@ -118,19 +118,21 @@ class IntegerField(DefaultableField[int]):
             )
 
 
-class BigIntegerField(IntegerField):
+class BigIntegerField[T: (int, int | None) = int](IntegerField[T]):
     db_type_sql = "bigint"
     integer_range = (-9223372036854775808, 9223372036854775807)
     psycopg_type = numeric.Int8
 
 
-class SmallIntegerField(IntegerField):
+class SmallIntegerField[T: (int, int | None) = int](IntegerField[T]):
     db_type_sql = "smallint"
     integer_range = (-32768, 32767)
     psycopg_type = numeric.Int2
 
 
-class DecimalField(DefaultableField[decimal.Decimal]):
+class DecimalField[T: (decimal.Decimal, decimal.Decimal | None) = decimal.Decimal](
+    DefaultableField[T]
+):
     db_type_sql = "numeric(%(max_digits)s,%(decimal_places)s)"
     empty_strings_allowed = False
 

{plain_postgres-0.104.0 → plain_postgres-0.105.0}/plain/postgres/fields/temporal.py

@@ -69,7 +69,9 @@ def _check_if_value_fixed(
     return []
 
 
-class DateField(DefaultableField[datetime.date]):
+class DateField[T: (datetime.date, datetime.date | None) = datetime.date](
+    DefaultableField[T]
+):
     db_type_sql = "date"
     empty_strings_allowed = False
 
@@ -149,7 +151,9 @@ class DateField(DefaultableField[datetime.date]):
         return value
 
 
-class DateTimeField(ColumnField[datetime.datetime]):
+class DateTimeField[
+    T: (datetime.datetime, datetime.datetime | None) = datetime.datetime
+](ColumnField[T]):
     db_type_sql = "timestamp with time zone"
     empty_strings_allowed = False
 
@@ -302,7 +306,9 @@ class DateTimeField(ColumnField[datetime.datetime]):
         return value
 
 
-class TimeField(DefaultableField[datetime.time]):
+class TimeField[T: (datetime.time, datetime.time | None) = datetime.time](
+    DefaultableField[T]
+):
     db_type_sql = "time without time zone"
     empty_strings_allowed = False
 

{plain_postgres-0.104.0 → plain_postgres-0.105.0}/plain/postgres/fields/text.py

@@ -13,7 +13,7 @@ if TYPE_CHECKING:
     from plain.postgres.functions.random import RandomString
 
 
-class TextField(ChoicesField[str]):
+class TextField[T: (str, str | None) = str](ChoicesField[T]):
     db_type_sql = "text"
 
     def __init__(
@@ -87,15 +87,15 @@ class TextField(ChoicesField[str]):
         return self.to_python(value)
 
 
-class EmailField(TextField):
+class EmailField[T: (str, str | None) = str](TextField[T]):
     default_validators = [validators.validate_email]
 
 
-class URLField(TextField):
+class URLField[T: (str, str | None) = str](TextField[T]):
     default_validators = [validators.URLValidator()]
 
 
-class RandomStringField(ColumnField[str]):
+class RandomStringField[T: (str, str | None) = str](ColumnField[T]):
     """Text column whose value is a Postgres-generated random hex string.
 
     The column carries a ``DEFAULT`` that evaluates per row, so raw SQL and

{plain_postgres-0.104.0 → plain_postgres-0.105.0}/plain/postgres/fields/timezones.py

@@ -47,7 +47,9 @@ def _get_canonical_timezones() -> frozenset[str]:
     )
 
 
-class TimeZoneField(ChoicesField[zoneinfo.ZoneInfo]):
+class TimeZoneField[
+    T: (zoneinfo.ZoneInfo, zoneinfo.ZoneInfo | None) = zoneinfo.ZoneInfo
+](ChoicesField[T]):
     """
     A model field that stores timezone names as strings but provides ZoneInfo objects.
 

{plain_postgres-0.104.0 → plain_postgres-0.105.0}/plain/postgres/fields/uuid.py

@@ -14,7 +14,7 @@ if TYPE_CHECKING:
     from plain.postgres.expressions import Func
 
 
-class UUIDField(ColumnField[UUID]):
+class UUIDField[T: (UUID, UUID | None) = UUID](ColumnField[T]):
     db_type_sql = "uuid"
     empty_strings_allowed = False
 

{plain_postgres-0.104.0 → plain_postgres-0.105.0}/plain/postgres/types.py

@@ -2,19 +2,19 @@
 Typed field imports for better IDE and type checker support.
 
 This module provides the same field classes as plain.postgres.fields,
-but with a companion .pyi stub file that makes type checkers interpret
-field assignments as their primitive Python types.
+with a companion .pyi stub file that types each constructor as the
+typed descriptor (`XField[T]`). Combined with the descriptor's overloaded
+`__get__`, type checkers see the field reference at the class level and
+the primitive value at instance access — no annotation needed.
 
 Usage:
     from plain.postgres import types
 
     @postgres.register_model
     class User(postgres.Model):
-        email: str = types.EmailField()
-        age: int = types.IntegerField()
-        is_active: bool = types.BooleanField(default=True)
-
-This is optional - you can continue using untyped field definitions.
+        email = types.EmailField()
+        age = types.IntegerField()
+        is_active = types.BooleanField(default=True)
 """
 
 # Re-export scalar field types