ferrum-orm 0.1.6__tar.gz → 0.1.7__tar.gz

{ferrum_orm-0.1.6 → ferrum_orm-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferrum-orm
-Version: 0.1.6
+Version: 0.1.7
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
@@ -173,6 +173,24 @@ users = await (
 )
 ```
 
+### First-Class IDE Support
+
+Ferrum ships a PEP 561 `py.typed` marker, so editors and type checkers (`mypy`, `pyright`,
+`ty`) resolve its inline hints out of the box. `Model.objects` is typed as
+`QuerySet[YourModel]`, chaining preserves the model type, and terminals infer precise results —
+no casts:
+
+```python
+users: list[User] = await User.objects.filter(is_active=True).all(conn)   # list[User]
+user: User | None = await User.objects.first(conn)                        # User | None
+rows: list[dict[str, Any]] = await User.objects.values("id", "email").all(conn)
+ids: list[Any] = await User.objects.values_list("id", flat=True).all(conn)
+```
+
+`values()` / `values_list()` return dedicated `ValuesQuerySet`, `ValuesListQuerySet`, and
+`FlatValuesListQuerySet` variants (all exported from `ferrum`) so `all()` returns
+`list[dict[str, Any]]`, `list[tuple[Any, ...]]`, or `list[Any]` respectively.
+
 ### Rust-Powered Core
 
 Performance-critical components are implemented in Rust:

{ferrum_orm-0.1.6 → ferrum_orm-0.1.7}/README.md

@@ -101,6 +101,24 @@ users = await (
 )
 ```
 
+### First-Class IDE Support
+
+Ferrum ships a PEP 561 `py.typed` marker, so editors and type checkers (`mypy`, `pyright`,
+`ty`) resolve its inline hints out of the box. `Model.objects` is typed as
+`QuerySet[YourModel]`, chaining preserves the model type, and terminals infer precise results —
+no casts:
+
+```python
+users: list[User] = await User.objects.filter(is_active=True).all(conn)   # list[User]
+user: User | None = await User.objects.first(conn)                        # User | None
+rows: list[dict[str, Any]] = await User.objects.values("id", "email").all(conn)
+ids: list[Any] = await User.objects.values_list("id", flat=True).all(conn)
+```
+
+`values()` / `values_list()` return dedicated `ValuesQuerySet`, `ValuesListQuerySet`, and
+`FlatValuesListQuerySet` variants (all exported from `ferrum`) so `all()` returns
+`list[dict[str, Any]]`, `list[tuple[Any, ...]]`, or `list[Any]` respectively.
+
 ### Rust-Powered Core
 
 Performance-critical components are implemented in Rust:

{ferrum_orm-0.1.6 → ferrum_orm-0.1.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "ferrum-orm"
-version = "0.1.6"
+version = "0.1.7"
 description = "Next-generation async ORM for Python with a Rust-powered core"
 license = { text = "Apache-2.0" }
 readme = "README.md"

{ferrum_orm-0.1.6 → ferrum_orm-0.1.7}/python/ferrum/__init__.py

@@ -6,7 +6,7 @@ Import paths are stable API; internal module paths are not.
 
 from __future__ import annotations
 
-__version__ = "0.1.6"
+__version__ = "0.1.7"
 __all__ = [
     "CreateExtension",
     "CreateFunction",
@@ -30,6 +30,7 @@ __all__ = [
     "FerrumSchemaError",
     "FerrumTimeoutError",
     "Field",
+    "FlatValuesListQuerySet",
     "ForeignKey",
     "FullTextIndex",
     "Index",
@@ -43,6 +44,8 @@ __all__ = [
     "RetryPolicy",
     "TSVector",
     "Transaction",
+    "ValuesListQuerySet",
+    "ValuesQuerySet",
     "Vector",
     "clear_hooks",
     "connect",
@@ -101,7 +104,12 @@ from ferrum.models import (
     Vector,
 )
 from ferrum.observability import enable_metrics, enable_opentelemetry, get_metrics
-from ferrum.queryset import QuerySet
+from ferrum.queryset import (
+    FlatValuesListQuerySet,
+    QuerySet,
+    ValuesListQuerySet,
+    ValuesQuerySet,
+)
 from ferrum.runtime import RetryPolicy
 from ferrum.session import (
     current_setting as get_session_config,

{ferrum_orm-0.1.6 → ferrum_orm-0.1.7}/python/ferrum/models.py

@@ -19,7 +19,20 @@ import re
 import types as _types
 from datetime import date, datetime, time
 from decimal import Decimal
-from typing import Annotated, Any, ClassVar, Literal, Union, cast, get_args, get_origin
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    ClassVar,
+    Literal,
+    NoReturn,
+    TypeVar,
+    Union,
+    cast,
+    get_args,
+    get_origin,
+    overload,
+)
 from uuid import UUID
 
 from pydantic import BaseModel as _PydanticBaseModel
@@ -950,6 +963,13 @@ def _build_metadata(cls: type[_PydanticBaseModel]) -> ModelMetadata:
 # Manager descriptor
 # ---------------------------------------------------------------------------
 
+if TYPE_CHECKING:
+    from ferrum.queryset import QuerySet
+
+# Bound to the accessing model type via ``owner`` so ``User.objects`` infers
+# ``QuerySet[User]`` in IDEs / type checkers (PEP 561 descriptor idiom).
+_M = TypeVar("_M", bound="Model")
+
 
 class _Manager:
     """Descriptor that vends a fresh ``QuerySet`` bound to the model class.
@@ -962,7 +982,12 @@ class _Manager:
     ``ferrum.queryset`` (models is the lower layer; queryset depends on it).
     """
 
-    def __get__(self, obj: object, owner: type | None = None) -> Any:  # noqa: ANN401
+    @overload
+    def __get__(self, obj: None, owner: type[_M]) -> QuerySet[_M]: ...
+    @overload
+    def __get__(self, obj: Model, owner: type[_M]) -> NoReturn: ...
+
+    def __get__(self, obj: object, owner: type | None = None) -> Any:
         if obj is not None:
             raise AttributeError(
                 "'objects' is a class-level manager and cannot be accessed on a model instance."