fastapi-startkit 0.55.0__tar.gz → 0.57.0__tar.gz

{fastapi_startkit-0.55.0 → fastapi_startkit-0.57.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fastapi-startkit
-Version: 0.55.0
+Version: 0.57.0
 Summary: A modular, provider-driven framework for building async Python web applications with FastAPI — bundling a service container, configuration system, an async-first ORM, facades, and a Cleo-powered console.
 Keywords: fastapi,framework,async,web,asgi,orm,sqlalchemy,pydantic,ioc-container,dependency-injection,service-provider,cli,console,configuration,microservices,starter-kit,boilerplate
 Author: Bedram Tamang

{fastapi_startkit-0.55.0 → fastapi_startkit-0.57.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-startkit"
-version = "0.55.0"
+version = "0.57.0"
 description = "A modular, provider-driven framework for building async Python web applications with FastAPI — bundling a service container, configuration system, an async-first ORM, facades, and a Cleo-powered console."
 readme = "README.md"
 keywords = [
@@ -107,7 +107,9 @@ dev = [
     "faker>=40.13.0",
     "langchain>=1.0.0",
     "langchain-core>=1.0.0",
+    "basedpyright>=1.31.4",
     "pyright>=1.1.411",
+    "pytest-benchmark>=5.2.3",
 ]
 
 
@@ -121,7 +123,7 @@ fixable = ["F401"]
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401"]
 
-[tool.pyright]
+[tool.basedpyright]
 include = ["src/fastapi_startkit"]
 exclude = [
     "**/tests",
@@ -137,6 +139,10 @@ pythonVersion = "3.12"
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 norecursedirs = [".venv", "dist", "build", "__pycache__"]
+markers = [
+    "benchmark: performance benchmark, excluded by default (run with -m benchmark)",
+]
+addopts = "-m 'not benchmark'"
 
 [tool.coverage.run]
 source = ["src/fastapi_startkit"]

{fastapi_startkit-0.55.0 → fastapi_startkit-0.57.0}/src/fastapi_startkit/config/app.py

@@ -7,5 +7,5 @@ from fastapi_startkit.environment.environment import env
 class AppConfig:
     name: str = field(default_factory=lambda: os.getenv("APP_NAME", "FastAPI starter kit"))
     env: str = field(default_factory=lambda: os.getenv("APP_ENV", "development"))
-    debug: bool = field(default_factory=lambda: env("APP_DEBUG", "true"))
+    debug: bool = field(default_factory=lambda: env("APP_DEBUG", True))
     timezone: str = field(default_factory=lambda: os.getenv("APP_TIMEZONE", "UTC"))

{fastapi_startkit-0.55.0 → fastapi_startkit-0.57.0}/src/fastapi_startkit/container/container.py

@@ -1,7 +1,7 @@
 """Core of the IOC Container."""
 
 import inspect
-from typing import Any
+from typing import Any, ClassVar, TypeVar, overload
 
 from ..exceptions import (
     ContainerError,
@@ -9,6 +9,8 @@ from ..exceptions import (
     StrictContainerException,
 )
 
+T = TypeVar("T")
+
 
 class Container:
     """Core of the Service Container.
@@ -16,14 +18,14 @@ class Container:
     Performs bindings and resolving of objects to and from the container.
     """
 
-    _instance = None
+    _instance: ClassVar["Container | None"] = None
 
     @classmethod
-    def set_instance(cls, instance):
+    def set_instance(cls, instance: "Container") -> None:
         cls._instance = instance
 
     @classmethod
-    def instance(cls):
+    def instance(cls) -> "Container":
         if cls._instance is None:
             raise RuntimeError("Container not initialized")
         return cls._instance
@@ -103,11 +105,22 @@ class Container:
         obj = self.resolve(class_obj)
         self.bind(name, obj)
 
-    def make(self, name, *arguments):
+    @overload
+    def make(self, name: type[T], *arguments: Any) -> T: ...
+
+    @overload
+    def make(self, name: str, *arguments: Any) -> Any: ...
+
+    def make(self, name: type[T] | str, *arguments: Any) -> Any:
         """Retrieve a class from the container by key.
 
+        A class key resolves to an instance of that class, so `make(Foo)` is
+        typed as `Foo`. A string key carries no static type information, so it
+        stays `Any` and callers annotate the binding themselves. The return is
+        never `None`: a missing key raises instead.
+
         Arguments:
-            name {string} -- Key in the container that you want to get.
+            name {string | type} -- Key in the container that you want to get.
 
         Raises:
             MissingContainerBindingNotFound -- Raised if the key is not in the container.

{fastapi_startkit-0.55.0 → fastapi_startkit-0.57.0}/src/fastapi_startkit/environment/environment.py

@@ -2,9 +2,15 @@
 
 import os
 import sys
+from typing import Any, Literal, TypeVar, overload
+
 from dotenv import load_dotenv
 
 
+T = TypeVar("T")
+EnvValue = str | int | bool
+
+
 class Environment:
     @staticmethod
     def resolve_environment(base_path=None, env: str | None = None):
@@ -63,11 +69,45 @@ class Environment:
                 break
 
 
-def env(value, default="", cast=True):
-    """Helper to retrieve the value of an environment variable or returns
-    a default value. In addition, if type can be inferred then the value can be casted to the
-    inferred type."""
-    env_var = os.getenv(value, default)
+@overload
+def env(val: str, default: T, cast: Literal[False]) -> str | T: ...
+
+
+@overload
+def env(val: str, default: Literal[""], cast: Literal[True] = True) -> EnvValue: ...
+
+
+@overload
+def env(val: str, default: None, cast: Literal[True] = True) -> EnvValue | None: ...
+
+
+@overload
+def env(val: str, default: T, cast: Literal[True] = True) -> T: ...
+
+
+@overload
+def env(val: str, default: None, cast: bool) -> EnvValue | None: ...
+
+
+@overload
+def env(val: str, default: T, cast: bool) -> EnvValue | T: ...
+
+
+@overload
+def env(val: str) -> EnvValue: ...
+
+
+@overload
+def env(val: str, *, cast: Literal[False]) -> str: ...
+
+
+@overload
+def env(val: str, *, cast: bool) -> EnvValue: ...
+
+
+def env(val: str, default: Any = "", cast: bool = True) -> Any:
+    """Return an environment value, casting it to the supplied default's type when possible."""
+    env_var = os.getenv(val, default)
 
     if not cast:
         return env_var
@@ -75,18 +115,23 @@ def env(value, default="", cast=True):
     if env_var == "":
         env_var = default
 
-    if isinstance(env_var, bool):
-        return env_var
-    elif env_var is None:
-        return None
-    elif isinstance(env_var, int) or env_var.isnumeric():
-        return int(env_var)
-    elif env_var in ("false", "False"):
-        return False
-    elif env_var in ("true", "True"):
-        return True
-    else:
-        return env_var
+    if default in ("", None):
+        return value(env_var)
+
+    default_type = type(default)
+    if default_type is bool:
+        if isinstance(env_var, bool):
+            return env_var
+        if env_var in ("true", "True"):
+            return True
+        if env_var in ("false", "False"):
+            return False
+        raise ValueError(f"Cannot cast environment variable {val!r} to bool")
+
+    try:
+        return default_type(env_var)
+    except (TypeError, ValueError) as error:
+        raise ValueError(f"Cannot cast environment variable {val!r} to {default_type.__name__}") from error
 
 
 def value(env_var, default=""):

{fastapi_startkit-0.55.0 → fastapi_startkit-0.57.0}/src/fastapi_startkit/masoniteorm/collection/Collection.py

@@ -1,4 +1,5 @@
-from typing import TYPE_CHECKING, Any, Generator, Generic, TypeVar
+from collections.abc import Callable, Generator
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
 
 from fastapi_startkit.support.collection import Collection as BaseCollection
 
@@ -10,7 +11,7 @@ class Collection(BaseCollection, Generic[T]):
         # Typing-only element-access overrides so a Collection[User] yields
         # User (not Any) on iteration, indexing, and first(). Runtime behaviour
         # is supplied unchanged by the base class.
-        def first(self, callback=None) -> "T | None": ...
+        def first(self, callback: "Callable[[T], bool] | None" = None) -> "T | None": ...
         def __iter__(self) -> "Generator[T, Any, None]": ...
         def __getitem__(self, item) -> "T": ...
 

{fastapi_startkit-0.55.0 → fastapi_startkit-0.57.0}/src/fastapi_startkit/masoniteorm/expressions/expressions.py

@@ -100,13 +100,17 @@ class SelectExpression:
 class OrderByExpression:
     """A helper class to manage select expressions."""
 
-    def __init__(self, column, direction="ASC", raw=False, bindings=()):
-        self.column = column.strip()
-
+    def __init__(self, column, direction="ASC", raw=False, bindings=(), builder=None):
         self.raw = raw
-
         self.direction = direction
         self.bindings = bindings
+        self.builder = builder
+
+        if builder is not None:
+            self.column = None
+            return
+
+        self.column = column.strip()
 
         if raw is False:
             if self.column.endswith(" desc"):

fastapi_startkit-0.57.0/src/fastapi_startkit/masoniteorm/models/__init__.py

@@ -0,0 +1,6 @@
+from .model import Model
+from .caster import Caster
+from .registry import Registry
+from .fields import Field, ModelField
+
+__all__ = ["Model", "Caster", "Registry", "Field", "ModelField"]

{fastapi_startkit-0.55.0 → fastapi_startkit-0.57.0}/src/fastapi_startkit/masoniteorm/models/builder.py

@@ -1,5 +1,6 @@
 import inspect
-from typing import TYPE_CHECKING, Any, Generic, TypeVar
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Generic, Self, TypeVar, overload
 
 from fastapi_startkit.masoniteorm.expressions.expressions import (
     JoinClause,
@@ -24,6 +25,10 @@ if TYPE_CHECKING:
 
 TModel = TypeVar("TModel", bound="Model")
 
+# where(lambda q: q.where(...)) — the callable receives a nested builder and
+# returns it, which the parent renders as a parenthesised subgroup.
+type WhereGroup[M: "Model"] = Callable[["QueryBuilder[M]"], "QueryBuilder[M]"]
+
 
 class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
     operators = [
@@ -159,7 +164,7 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
         results = await self.select(columns).limit(1).get()
         return results.first()
 
-    async def get(self, columns=None) -> "Collection[TModel]":
+    async def get(self, columns: "list[str] | str | None" = None) -> "Collection[TModel]":
         # TODO: apply scopes
         if not columns:
             columns = []
@@ -217,8 +222,11 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
         self._offset = offset
         return self
 
-    def order_by(self, column: str, direction: str = "asc") -> "QueryBuilder":
+    def order_by(self, column, direction: str = "asc") -> "QueryBuilder":
         direction = direction.upper()
+        if isinstance(column, QueryBuilder):
+            self._order_by += (OrderByExpression(None, direction, builder=column),)
+            return self
         for col in column.split(","):
             col = col.strip()
             self._order_by += (OrderByExpression(col, direction),)
@@ -486,11 +494,27 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
         """Determine whether an operator is not supported by the builder."""
         return not isinstance(operator, str) or operator.lower() not in self.operators
 
-    def where(self, column, *args):
+    @overload
+    def where(self, column: str, /) -> "Self": ...
+
+    @overload
+    def where(self, column: str, value: Any, /) -> "Self": ...
+
+    @overload
+    def where(self, column: str, operator: str, value: Any, /) -> "Self": ...
+
+    @overload
+    def where(self, column: dict[str, Any], /) -> "Self": ...
+
+    @overload
+    def where(self, column: "WhereGroup[TModel]", /) -> "Self": ...
+
+    def where(self, column: "str | dict[str, Any] | WhereGroup[TModel]", *args: Any) -> "Self":
         """Specifies a where expression.
 
         Arguments:
-            column {string} -- The name of the column to search
+            column {string | dict | callable} -- The column to search, a dict of
+                column/value pairs, or a callable receiving a nested builder.
 
         Keyword Arguments:
             args {List} -- The operator and the value of the column to search. (default: {None})
@@ -531,8 +555,33 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
         self._joins += (join_clause,)
         return self
 
-    def where_column(self, column1: str, column2: str) -> "QueryBuilder":
-        self._wheres += (QueryExpression(column1, "=", column2, "value_equals"),)
+    _WHERE_COLUMN_OPERATORS = ("=", "!=", "<>", ">", ">=", "<", "<=")
+
+    def _normalize_where_column(self, operator: str, column2: str | None):
+        """Resolve the where_column arity.
+
+        Two-arg ``(col1, col2)`` defaults the operator to ``=``; three-arg
+        ``(col1, operator, col2)`` validates the operator.
+        """
+        if column2 is None:
+            return "=", operator
+        if operator not in self._WHERE_COLUMN_OPERATORS:
+            raise ValueError(
+                f"Invalid where_column operator {operator!r}. "
+                f"Expected one of: {', '.join(self._WHERE_COLUMN_OPERATORS)}"
+            )
+        return operator, column2
+
+    def where_column(self, column1: str, operator: str, column2: str | None = None) -> "QueryBuilder":
+        """Compare two columns (identifiers, never bound values), joined with AND."""
+        operator, column2 = self._normalize_where_column(operator, column2)
+        self._wheres += (QueryExpression(column1, operator, column2, "value_equals"),)
+        return self
+
+    def or_where_column(self, column1: str, operator: str, column2: str | None = None) -> "QueryBuilder":
+        """Compare two columns (identifiers, never bound values), joined with OR."""
+        operator, column2 = self._normalize_where_column(operator, column2)
+        self._wheres += (QueryExpression(column1, operator, column2, "value_equals", keyword="or"),)
         return self
 
     def when(self, condition, callback) -> "QueryBuilder":

{fastapi_startkit-0.55.0 → fastapi_startkit-0.57.0}/src/fastapi_startkit/masoniteorm/models/caster.py

@@ -4,8 +4,9 @@ import datetime
 from decimal import Decimal
 from enum import Enum
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, get_type_hints, Optional
+from typing import TYPE_CHECKING, Any, get_args, get_type_hints, Optional
 from pydantic.fields import FieldInfo
+from pydantic import BaseModel as PydanticModel
 from fastapi_startkit.carbon import Carbon
 
 if TYPE_CHECKING:
@@ -214,7 +215,7 @@ class Caster:
 
         # Ignore the builder
         annotations = {k: v for k, v in annotations.items() if k not in cls.IGNORE_CASTS}
-        from .fields import ModelField, FieldDescriptor
+        from .fields import FieldDescriptor, ModelField
 
         # 1. Collect all potential fields (annotations + descriptors)
         all_field_names = set(annotations.keys())
@@ -226,11 +227,30 @@ class Caster:
 
         casts = {}
         for field_name in all_field_names:
-            typ = annotations.get(field_name) or "str"
             descriptor = descriptors.get(field_name, None)
+            typ = annotations.get(field_name)
 
-            # AttributeField: use the type annotation as the model class
-            if isinstance(descriptor, ModelField):
+            # ``Field[int]()`` carries its runtime type in ``__orig_class__``.
+            # This lets models use typed descriptors without repeating an
+            # annotation solely for the casting layer.
+            if typ is None and isinstance(descriptor, FieldDescriptor):
+                generic_args = get_args(getattr(descriptor, "__orig_class__", None))
+                if generic_args:
+                    typ = generic_args[0]
+
+            # An unsubscripted field can still derive its cast from a concrete
+            # default, as in ``Field(default=False)``.
+            if typ is None and isinstance(descriptor, FieldDescriptor):
+                from pydantic_core import PydanticUndefined
+
+                if descriptor.field_info.default is not PydanticUndefined:
+                    typ = type(descriptor.field_info.default)
+
+            typ = typ or "str"
+
+            # Nested Pydantic models are stored as JSON and hydrated back into
+            # their declared type, e.g. ``address = Field[Address]()``.
+            if isinstance(descriptor, ModelField) or (isinstance(typ, type) and issubclass(typ, PydanticModel)):
                 casts[field_name] = ModelCast(model_class=typ)
                 continue
 

fastapi_startkit-0.57.0/src/fastapi_startkit/masoniteorm/models/fields.py

@@ -0,0 +1,160 @@
+from typing import Any, Callable, Generic, Protocol, Self, TypeVar, overload
+import warnings
+
+from pydantic import Field as BaseField
+from pydantic.fields import FieldInfo
+
+from fastapi_startkit.masoniteorm.models.observer import (
+    CreatedAtObserver,
+    UpdatedAtObserver,
+)
+
+
+T = TypeVar("T")
+
+
+class _AttributeModel(Protocol):
+    def get_attribute(self, key: str) -> Any: ...
+
+    def set_attribute(self, key: str, value: Any) -> None: ...
+
+
+class FieldDescriptor(Generic[T]):
+    """
+    A descriptor that wraps Pydantic's FieldInfo.
+    It allows us to store metadata that the Caster can later discover.
+    """
+
+    def __init__(self, field_info: FieldInfo) -> None:
+        self.field_info = field_info
+        self.name: str | None = None
+
+    def __set_name__(self, owner: type[_AttributeModel], name: str) -> None:
+        self.name = name
+
+    @overload
+    def __get__(self, instance: None, owner: type[_AttributeModel]) -> FieldInfo: ...
+
+    @overload
+    def __get__(self, instance: _AttributeModel, owner: type[_AttributeModel]) -> T: ...
+
+    def __get__(self, instance: _AttributeModel | None, owner: type[_AttributeModel]) -> T | FieldInfo:
+        if instance is None:
+            # When accessed on the class (e.g., User.name), return the FieldInfo
+            return self.field_info
+
+        # When accessed on the instance (e.g., user.name), retrieve from ORM storage
+        assert self.name is not None
+        return instance.get_attribute(self.name)
+
+    def __set__(self, instance: _AttributeModel, value: T) -> None:
+        # When setting (e.g., user.name = 'Joe'), update ORM storage
+        assert self.name is not None
+        instance.set_attribute(self.name, value)
+
+
+class Field(FieldDescriptor[T]):
+    """
+    Typed ORM field descriptor backed by Pydantic field metadata.
+
+    Required fields can state their type explicitly with ``Field[int]()``.
+    Fields with a default infer their type with ``Field(default=False)``.
+    """
+
+    @overload
+    def __init__(self, *, default: T, default_factory: None = None, **kwargs: Any) -> None: ...
+
+    @overload
+    def __init__(self, *, default_factory: Callable[[], T], **kwargs: Any) -> None: ...
+
+    @overload
+    def __init__(self, *args: Any, **kwargs: Any) -> None: ...
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(BaseField(*args, **kwargs))
+
+
+class ModelField(Generic[T]):
+    """Deprecated; scheduled for removal in 2.x. Use ``Field[Address]()`` instead."""
+
+    def __init__(self, default: T | None = None) -> None:
+        warnings.warn(
+            "ModelField is deprecated and will be removed in 2.x; use Field[YourModel]() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.default = default
+        self.name: str | None = None
+
+    def __set_name__(self, owner: type[_AttributeModel], name: str) -> None:
+        self.name = name
+
+    @overload
+    def __get__(self, instance: None, owner: type[_AttributeModel]) -> Self: ...
+
+    @overload
+    def __get__(self, instance: _AttributeModel, owner: type[_AttributeModel]) -> T: ...
+
+    def __get__(self, instance: _AttributeModel | None, owner: type[_AttributeModel]) -> T | Self:
+        if instance is None:
+            return self
+        assert self.name is not None
+        return instance.get_attribute(self.name)
+
+    def __set__(self, instance: _AttributeModel, value: T) -> None:
+        assert self.name is not None
+        instance.set_attribute(self.name, value)
+
+
+class DateTimeField:
+    def __init__(self, fmt: str = "YYYY-MM-DD HH:mm:ss", tz: str = "UTC"):
+        self.format = fmt
+        self.tz = tz
+
+    def __set_name__(self, owner, name):
+        self.name = name
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self
+
+        return instance.get_attribute(self.name)
+
+    # def __set__(self, instance, value):
+    #     instance.set_attribute(self.name, value)
+
+
+class CreatedAtField:
+    def __init__(self, fmt: str = "YYYY-MM-DD HH:mm:ss", tz: str = "UTC"):
+        self.format = fmt
+        self.tz = tz
+
+    def __set_name__(self, owner, name):
+        self.name = name
+        owner.observe(CreatedAtObserver(name, self.format, self.tz))
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self
+        return instance.get_attribute(self.name)
+
+    # def __set__(self, instance, value):
+    #     instance.set_value(self.name, value)
+
+
+class UpdatedAtField:
+    def __init__(self, fmt: str = "YYYY-MM-DD HH:mm:ss", tz: str = "UTC"):
+        self.format = fmt
+        self.tz = tz
+
+    def __set_name__(self, owner, name):
+        self.name = name
+        owner.observe(UpdatedAtObserver(name, self.format, self.tz))
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self
+        return instance.get_attribute(self.name)
+
+    def __set__(self, instance, value):
+        instance.set_attribute(self.name, value)

{fastapi_startkit-0.55.0 → fastapi_startkit-0.57.0}/src/fastapi_startkit/masoniteorm/models/model.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Self
+from typing import TYPE_CHECKING, Any, Self, dataclass_transform, overload
 
 import inflection
 import pendulum
@@ -9,15 +9,22 @@ from fastapi_startkit.carbon import Carbon
 from fastapi_startkit.masoniteorm.collection import Collection
 from fastapi_startkit.masoniteorm.connections.manager import DatabaseManager
 from fastapi_startkit.masoniteorm.models.attribute import Attribute
-from fastapi_startkit.masoniteorm.models.fields import CreatedAtField, UpdatedAtField
+from fastapi_startkit.masoniteorm.models.fields import (
+    CreatedAtField,
+    Field,
+    FieldDescriptor,
+    ModelField,
+    UpdatedAtField,
+)
 from fastapi_startkit.masoniteorm.models.registry import Registry
 from fastapi_startkit.masoniteorm.models.relationship import Relationship
 from fastapi_startkit.masoniteorm.observers import ObservesEvents
 
 if TYPE_CHECKING:
-    from fastapi_startkit.masoniteorm.models.builder import QueryBuilder
+    from fastapi_startkit.masoniteorm.models.builder import QueryBuilder, WhereGroup
 
 
+@dataclass_transform(field_specifiers=(Field, ModelField))
 class Model(Attribute, Relationship, ObservesEvents):
     db_manager: "DatabaseManager" = None
     __table__ = None
@@ -34,9 +41,16 @@ class Model(Attribute, Relationship, ObservesEvents):
         super().__init_subclass__(**kwargs)
         Registry.register(cls)
 
+        declared_fields = dict.fromkeys(
+            [
+                *cls.__annotations__,
+                *(name for name, value in vars(cls).items() if isinstance(value, FieldDescriptor)),
+            ]
+        )
+
         fillable = []
-        for name, _typ in cls.__annotations__.items():
-            attr = getattr(cls, name, None)
+        for name in declared_fields:
+            attr = vars(cls).get(name)
             from fastapi_startkit.masoniteorm.relationships.BaseRelationship import (
                 BaseRelationship,
             )
@@ -93,8 +107,28 @@ class Model(Attribute, Relationship, ObservesEvents):
     def with_(cls, *eagers) -> "QueryBuilder":
         return cls.query().with_(*eagers)
 
+    @overload
+    @classmethod
+    def where(cls, column: str, /) -> QueryBuilder[Self]: ...
+
+    @overload
+    @classmethod
+    def where(cls, column: str, value: Any, /) -> QueryBuilder[Self]: ...
+
+    @overload
+    @classmethod
+    def where(cls, column: str, operator: str, value: Any, /) -> QueryBuilder[Self]: ...
+
+    @overload
+    @classmethod
+    def where(cls, column: dict[str, Any], /) -> QueryBuilder[Self]: ...
+
+    @overload
+    @classmethod
+    def where(cls, column: WhereGroup[Self], /) -> QueryBuilder[Self]: ...
+
     @classmethod
-    def where(cls, column, *args) -> "QueryBuilder[Self]":
+    def where(cls, column: str | dict[str, Any] | WhereGroup[Self], *args: Any) -> QueryBuilder[Self]:
         return cls.query().where(column, *args)
 
     @classmethod
@@ -243,7 +277,7 @@ class Model(Attribute, Relationship, ObservesEvents):
         return await cls.query().first(columns)
 
     @classmethod
-    async def get(cls):
+    async def get(cls) -> Collection[Self]:
         return await cls.query().get()
 
     @classmethod