Add minimal test for descriptor behavior.

Couple more comments for some Any's that might get flagged.

Author: coleifer

stubs/peewee/@tests/test_cases/check_fields.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing_extensions import assert_type
+
+from peewee import BigBitField, BigBitFieldData, CharField, ForeignKeyField, IntegerField, Model
+
+
+class User(Model):
+    username = CharField()
+    age = IntegerField()
+    nickname = CharField(null=True)
+
+
+class Tweet(Model):
+    user = ForeignKeyField(User)
+    author = ForeignKeyField(User, null=True)
+
+
+class Event(Model):
+    flags = BigBitField()
+
+
+# A field is a descriptor that resolves differently depending on whether it is
+# accessed on the model class or on an instance. `Model.field` is the Field
+# object itself (used to build queries), while `instance.field` is the stored
+# Python value.
+assert_type(User.username, CharField[str])
+assert_type(User().username, str)
+
+assert_type(User.age, IntegerField[int])
+assert_type(User().age, int)
+
+# `null=True` allows the value to include None, both in the field's own
+# parameterization and in the value produced on attribute access.
+assert_type(User.nickname, CharField[str | None])
+assert_type(User().nickname, str | None)
+
+# Foreign keys resolve to the related model instance, or None when nullable.
+assert_type(Tweet.user, ForeignKeyField[User])
+assert_type(Tweet().user, User)
+assert_type(Tweet().author, User | None)
+
+# BigBitField is a special case: the instance descriptor yields a
+# BigBitFieldData wrapper rather than the underlying bytes.
+assert_type(Event.flags, BigBitField)
+assert_type(Event().flags, BigBitFieldData)
+
+# __set__ accepts the field's value type...
+user = User()
+user.username = "guido"
+user.age = 42
+user.nickname = None  # nullable field accepts None
+
+# ...and rejects incompatible values.
+user.age = "not an int"  # type: ignore
+user.username = None  # type: ignore  # non-null field rejects None

stubs/peewee/peewee.pyi

@@ -443,7 +443,7 @@ def Default(value) -> SQL: ...
 class Function(ColumnBase):
     no_coerce_functions: ClassVar[set[str]]
     name: str | None
-    arguments: tuple[Any, ...] | None
+    arguments: tuple[Any, ...] | None  # Positional SQL function args: values, columns, or other nodes
     def __init__(self, name, arguments, coerce: bool = True, python_value=None) -> None: ...
     # fn.COUNT(...), fn.SUM(...), etc. each build a Function node.
     def __getattr__(self, attr: str) -> Callable[..., Function]: ...
@@ -571,7 +571,7 @@ class BaseQuery(Node):
     def namedtuples(self, as_namedtuple: bool = True) -> Self: ...
     def objects(self, constructor=None) -> Self: ...
     def __sql__(self, ctx) -> None: ...
-    def sql(self) -> tuple[str, list[Any]]: ...
+    def sql(self) -> tuple[str, list[Any]]: ...  # Returns (sql, params), params are bound query values
     def execute(self, database=None): ...
     async def aexecute(self, database=None): ...
     def iterator(self, database=None): ...
@@ -1565,6 +1565,7 @@ class ForeignKeyField(Field[_V]):
         cls, model: type[_M], *args: Any, null: Literal[False] = ..., **kwargs: Unpack[_FKKwargs]
     ) -> ForeignKeyField[_M]: ...
     @overload
+    # Untyped fallback: model given as a name/"self"/deferred ref, so the related type isn't known.
     def __new__(cls, model: Any = ..., *args: Any, **kwargs: Unpack[_FKKwargs]) -> ForeignKeyField[Any]: ...
 
     @property