fastapi-startkit 0.58.0__tar.gz → 0.60.0__tar.gz

{fastapi_startkit-0.58.0 → fastapi_startkit-0.60.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fastapi-startkit
-Version: 0.58.0
+Version: 0.60.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.58.0 → fastapi_startkit-0.60.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-startkit"
-version = "0.58.0"
+version = "0.60.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 = [

{fastapi_startkit-0.58.0 → fastapi_startkit-0.60.0}/src/fastapi_startkit/fastapi/commands/serve_command.py

@@ -11,6 +11,9 @@ from fastapi_startkit.support import Uri, Uriable
 if TYPE_CHECKING:
     from fastapi_startkit.application import Application
 
+# Values accepted by uvicorn's `ws` setting.
+WS_BACKENDS = ("auto", "none", "websockets", "websockets-sansio", "wsproto")
+
 
 class ServeCommand(Command):
     name = "serve"
@@ -45,6 +48,13 @@ class ServeCommand(Command):
             default=None,
             description="The application to serve (overrides fastapi config)",
         ),
+        option(
+            "ws",
+            None,
+            flag=False,
+            default=None,
+            description=f"The uvicorn WebSocket backend: {', '.join(WS_BACKENDS)} (overrides fastapi config)",
+        ),
     ]
 
     def config_value(self, key: str) -> Any:
@@ -72,11 +82,20 @@ class ServeCommand(Command):
 
         return uri.with_port(port) if port else uri
 
+    def resolve_ws(self) -> str:
+        """CLI flag > fastapi config > FastAPIConfig default ('auto')."""
+        return str(self.option("ws") or self.config_value("ws"))
+
     def handle(self) -> int:
         import uvicorn
 
         from fastapi_startkit.container import Container
 
+        ws = self.resolve_ws()
+        if ws not in WS_BACKENDS:
+            self.line_error(f"Invalid --ws backend '{ws}'. Allowed values: {', '.join(WS_BACKENDS)}.", style="error")
+            return 1
+
         url = self.resolve_url()
         reload = self.resolve_option("reload")
         app = self.resolve_option("app")
@@ -85,7 +104,7 @@ class ServeCommand(Command):
             "host": url.host(),
             "port": url.port(),
             "reload": reload,
-            "ws": "websockets-sansio",
+            "ws": ws,
         }
 
         if self.is_app_exist(app):

{fastapi_startkit-0.58.0 → fastapi_startkit-0.60.0}/src/fastapi_startkit/fastapi/config/fastapi.py

@@ -8,6 +8,8 @@ class FastAPIConfig:
     app_url: str = dataclasses.field(default_factory=lambda: env("APP_URL", "http://127.0.0.1:8000"))
     app: str = "bootstrap.application:app"
     reload: bool = dataclasses.field(default_factory=lambda: env("APP_RELOAD", True))
+    # 'auto' keeps the optional `websockets` package from being required at startup.
+    ws: str = dataclasses.field(default_factory=lambda: env("APP_WS", "auto"))
     reload_dirs: list | None = None
     reload_excludes: list = dataclasses.field(
         default_factory=lambda: [

{fastapi_startkit-0.58.0 → fastapi_startkit-0.60.0}/src/fastapi_startkit/logging/config/logging.py

@@ -7,6 +7,7 @@ from fastapi_startkit.logging.config import StackChannel, DailyChannel, Terminal
 @dataclasses.dataclass
 class LoggingConfig:
     default: str = dataclasses.field(default_factory=lambda: env("LOG_CHANNEL", "stack"))
+    level: str = dataclasses.field(default_factory=lambda: env("LOG_LEVEL", "info"))
 
     channels: dict = dataclasses.field(
         default_factory=lambda: {

{fastapi_startkit-0.58.0 → fastapi_startkit-0.60.0}/src/fastapi_startkit/logging/handler.py

@@ -1,5 +1,8 @@
 import logging
 
+# Framework-only severities have no stdlib equivalent; map them to the nearest one.
+_STDLIB_LEVELS = {"notice": "INFO", "alert": "CRITICAL", "emergency": "CRITICAL"}
+
 
 class LoggingHandler(logging.Handler):
     def emit(self, record: logging.LogRecord) -> None:
@@ -8,8 +11,9 @@ class LoggingHandler(logging.Handler):
         Logger.log(record.levelname, self.format(record))
 
     @staticmethod
-    def install():
+    def install(level: str | None = None):
         root_logger = logging.getLogger()
         if not any(isinstance(h, LoggingHandler) for h in root_logger.handlers):
             root_logger.addHandler(LoggingHandler())
-            root_logger.setLevel(logging.DEBUG)
+        if level:
+            root_logger.setLevel(_STDLIB_LEVELS.get(level.lower(), level.upper()))

{fastapi_startkit-0.58.0 → fastapi_startkit-0.60.0}/src/fastapi_startkit/logging/managers/LoggingManager.py

@@ -7,10 +7,11 @@ class LoggingManager:
         self,
         channel_factory: type[ChannelFactory] = ChannelFactory,
         driver_factory: type[DriverFactory] = DriverFactory,
+        level: str | None = None,
     ):
         self.channel_factory = channel_factory
         self.driver_factory = driver_factory
-        self.configure_python_logging()
+        self.configure_python_logging(level)
 
     def channel(self, channel: str):
         channel_class = self.channel_factory.make(channel)
@@ -19,7 +20,7 @@ class LoggingManager:
         return channel_class()
 
     @classmethod
-    def configure_python_logging(cls):
+    def configure_python_logging(cls, level: str | None = None):
         from ..handler import LoggingHandler
 
-        LoggingHandler.install()
+        LoggingHandler.install(level)

{fastapi_startkit-0.58.0 → fastapi_startkit-0.60.0}/src/fastapi_startkit/logging/providers/log_provider.py

@@ -17,7 +17,7 @@ class LogProvider(Provider):
 
         self.app.bind("LogChannelFactory", ChannelFactory)
         self.app.bind("LogDriverFactory", DriverFactory)
-        self.app.bind("LoggingManager", LoggingManager(ChannelFactory, DriverFactory))
+        self.app.bind("LoggingManager", LoggingManager(ChannelFactory, DriverFactory, config.get("level")))
 
     def boot(self):
         self.publishes({Path(__file__).resolve().parent.parent.joinpath("config/logging.py"): "config/logging.py"})

{fastapi_startkit-0.58.0 → fastapi_startkit-0.60.0}/src/fastapi_startkit/masoniteorm/config/config.py

@@ -1,5 +1,6 @@
 from typing import Optional, Dict, Any
 from pydantic.dataclasses import dataclass
+from pydantic.fields import Field
 from fastapi_startkit.environment.environment import env
 
 
@@ -8,6 +9,7 @@ class SQLiteConfig:
     driver: str = "sqlite"
     url: Optional[str] = env("DB_URL", None, cast=False)
     database: str = env("DB_DATABASE", "database.sqlite")
+    echo: bool = Field(default_factory=lambda: env("DB_ECHO", False))
     options: Optional[Dict[str, Any]] = None
 
 
@@ -23,6 +25,7 @@ class MySQLConfig:
     unix_socket: str = env("DB_SOCKET", "", cast=False)
     charset: str = env("DB_CHARSET", "utf8mb4")
     collation: str = env("DB_COLLATION", "utf8mb4_unicode_ci")
+    echo: bool = Field(default_factory=lambda: env("DB_ECHO", False))
     options: Optional[Dict[str, Any]] = None
 
 
@@ -37,4 +40,5 @@ class PostgresConfig:
     password: str = env("DB_PASSWORD", "", cast=False)
     charset: str = env("DB_CHARSET", "utf8")
     sslmode: str = env("DB_SSLMODE", "prefer")
+    echo: bool = Field(default_factory=lambda: env("DB_ECHO", False))
     options: Optional[Dict[str, Any]] = None

{fastapi_startkit-0.58.0 → fastapi_startkit-0.60.0}/src/fastapi_startkit/masoniteorm/connections/factory.py

@@ -64,7 +64,7 @@ class ConnectionFactory:
     @classmethod
     def create_engine(cls, cfg: dict) -> AsyncEngine:
         url = cls.build_url(cfg)
-        kwargs: dict[str, Any] = {"echo": True}
+        kwargs: dict[str, Any] = {"echo": bool(cfg.get("echo", False))}
         from fastapi_startkit.application import app
 
         if cast("Application", app()).is_testing():

{fastapi_startkit-0.58.0 → fastapi_startkit-0.60.0}/src/fastapi_startkit/masoniteorm/models/builder.py

@@ -1,5 +1,5 @@
 import inspect
-from collections.abc import Callable
+from collections.abc import Callable, Iterable
 from typing import TYPE_CHECKING, Any, Generic, Self, TypeVar, overload
 
 from fastapi_startkit.masoniteorm.expressions.expressions import (
@@ -29,6 +29,11 @@ TModel = TypeVar("TModel", bound="Model")
 # returns it, which the parent renders as a parenthesised subgroup.
 type WhereGroup[M: "Model"] = Callable[["QueryBuilder[M]"], "QueryBuilder[M]"]
 
+# select_sub()/add_select() subquery source: a builder, or a callable that
+# receives a fresh builder and returns the subquery.
+type Subquery = "QueryBuilder[Any] | Callable[[QueryBuilder[Any]], QueryBuilder[Any]]"
+type SelectEntry = "str | dict[str, str | Subquery]"
+
 
 class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
     operators = [
@@ -67,13 +72,13 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
         "!~~*",
     ]
 
-    def __init__(self, connection: "Connection", grammar, processor):
+    def __init__(self, connection: "Connection", grammar: Any, processor: Any):
         super().__init__()
         self.connection = connection
         self.grammar = grammar
         self.processor = processor
 
-        self._columns = []
+        self._columns: list[Any] = []
         self._table = ""
         self._limit = False
         self._offset = False
@@ -91,35 +96,35 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
         self._global_scopes = {}
         self._action = "select"
 
-    def set_action(self, action: str) -> "QueryBuilder":
+    def set_action(self, action: str) -> "Self":
         self._action = action
         return self
 
-    def set_model(self, model) -> "QueryBuilder":
+    def set_model(self, model: "TModel") -> "Self":
         self._model = model
         self._table = model.get_table_name()
         self._global_scopes = model._global_scopes
         return self
 
-    def with_(self, *eagers) -> "QueryBuilder":
+    def with_(self, *eagers) -> "Self":
         self._eager_relation.register(eagers)
         return self
 
     def get_table_name(self) -> str:
         return self._table
 
-    def table(self, table: str) -> "QueryBuilder":
+    def table(self, table: str) -> "Self":
         self._table = table
         return self
 
-    def where_in(self, column: str, values) -> "QueryBuilder":
+    def where_in(self, column: str, values: Iterable[Any]) -> "Self":
         if hasattr(values, "_items"):
-            values = values._items
+            values = getattr(values, "_items")
         values = list(values) if not isinstance(values, list) else values
         self._wheres.append(QueryExpression(column, "IN", values))
         return self
 
-    def select(self, *args) -> "QueryBuilder":
+    def select(self, *args: "str | list[str]") -> "Self":
         for arg in args:
             if isinstance(arg, list):
                 for column in arg:
@@ -129,14 +134,67 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
                     self._columns += (SelectExpression(column),)
         return self
 
-    def limit(self, limit: int) -> "QueryBuilder":
+    def select_sub(self, subquery: "Subquery", alias: str) -> "Self":
+        """Add ``(subquery) AS alias`` to the selection.
+
+        ``subquery`` is a builder, or a callable that receives a fresh table-less
+        builder and returns one.
+        """
+        if not isinstance(subquery, QueryBuilder) and callable(subquery):
+            subquery = subquery(QueryBuilder(self.connection, self.grammar, self.processor))
+        if not isinstance(subquery, QueryBuilder):
+            raise TypeError("select_sub() expects a QueryBuilder subquery or a callable returning one.")
+        self._columns.append(SubGroupExpression(subquery, alias))
+        return self
+
+    def add_select(self, *columns: "SelectEntry | list[SelectEntry]") -> "Self":
+        """Append columns to the current selection without replacing it.
+
+        Plain string columns are appended once. A ``{alias: subquery}`` entry
+        adds a correlated column via :meth:`select_sub`, first selecting
+        ``{table}.*`` when nothing is selected yet so the base columns survive.
+        A string value under a string key is still a plain column.
+        """
+        entries: list[SelectEntry] = []
+        for column in columns:
+            if isinstance(column, list):
+                entries.extend(column)
+            else:
+                entries.append(column)
+
+        for entry in entries:
+            pairs: Iterable[tuple[str | None, str | Subquery]] = (
+                entry.items() if isinstance(entry, dict) else [(None, entry)]
+            )
+            for alias, value in pairs:
+                if isinstance(value, str):
+                    if not self._is_selected(value):
+                        self._columns.append(SelectExpression(value))
+                    continue
+                if alias is None:
+                    raise TypeError(
+                        "add_select() received a subquery without a string alias; "
+                        "pass {alias: subquery} or use select_sub(subquery, alias)."
+                    )
+                if not self._columns:
+                    self.select(f"{self._table}.*")
+                self.select_sub(value, alias)
+        return self
+
+    def _is_selected(self, column: str) -> bool:
+        return any(
+            isinstance(existing, SelectExpression) and existing.alias is None and existing.column == column
+            for existing in self._columns
+        )
+
+    def limit(self, limit: int) -> "Self":
         self._limit = limit
         return self
 
-    async def find(self, primary_key: str | int, columns=None) -> "TModel | None":
+    async def find(self, primary_key: str | int, columns: "list[str] | str | None" = None) -> "TModel | None":
         return await self.where(self._model.__primary_key__, primary_key).first(columns)
 
-    async def find_or_fail(self, primary_key: str | int, columns=None) -> "TModel":
+    async def find_or_fail(self, primary_key: str | int, columns: "list[str] | str | None" = None) -> "TModel":
         """Return the record matching ``primary_key``.
 
         Raises:
@@ -149,7 +207,7 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
             raise ModelNotFoundException(f"{type(self._model).__name__} with primary key {primary_key!r} not found.")
         return result
 
-    async def first_or_fail(self, columns=None) -> "TModel":
+    async def first_or_fail(self, columns: "list[str] | str | None" = None) -> "TModel":
         from fastapi_startkit.masoniteorm.exceptions import ModelNotFoundException
 
         result = await self.first(columns)
@@ -157,7 +215,7 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
             raise ModelNotFoundException(f"{type(self._model).__name__} not found.")
         return result
 
-    async def first(self, columns=None) -> "TModel | None":
+    async def first(self, columns: "list[str] | str | None" = None) -> "TModel | None":
         if not columns:
             columns = []
 
@@ -170,7 +228,9 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
             columns = []
         return await self.get_models(columns)
 
-    async def get_models(self, columns=None):
+    async def get_models(self, columns: "list[str] | str | None" = None) -> "Collection[TModel]":
+        if not columns:
+            columns = []
         self.select(columns)
         models = await self.connection.select(self.to_qmark(), list(self.get_bindings()))
         collection = self._model.hydrate(models)
@@ -180,15 +240,15 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
 
         return collection
 
-    def get_bindings(self) -> tuple:
+    def get_bindings(self) -> tuple[Any, ...]:
         return self._bindings
 
-    def run_scopes(self) -> "QueryBuilder":
+    def run_scopes(self) -> "Self":
         for name, scope in self._global_scopes.get(self._action, {}).items():
             scope(self)
         return self
 
-    def without_global_scopes(self) -> "QueryBuilder":
+    def without_global_scopes(self) -> "Self":
         self._global_scopes = {}
         return self
 
@@ -218,11 +278,11 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
         self.run_scopes()
         return self.get_grammar().compile(self._action).to_sql()
 
-    def offset(self, offset: int) -> "QueryBuilder":
+    def offset(self, offset: int) -> "Self":
         self._offset = offset
         return self
 
-    def order_by(self, column, direction: str = "asc") -> "QueryBuilder":
+    def order_by(self, column: "str | QueryBuilder[Any]", direction: str = "asc") -> "Self":
         direction = direction.upper()
         if isinstance(column, QueryBuilder):
             self._order_by += (OrderByExpression(None, direction, builder=column),)
@@ -232,67 +292,67 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
             self._order_by += (OrderByExpression(col, direction),)
         return self
 
-    def order_by_raw(self, expression: str) -> "QueryBuilder":
+    def order_by_raw(self, expression: str) -> "Self":
         self._order_by += (OrderByExpression(expression, raw=True),)
         return self
 
-    def latest(self, column: str = "created_at") -> "QueryBuilder":
+    def latest(self, column: str = "created_at") -> "Self":
         return self.order_by(column, "desc")
 
-    def oldest(self, column: str = "created_at") -> "QueryBuilder":
+    def oldest(self, column: str = "created_at") -> "Self":
         return self.order_by(column, "asc")
 
-    def group_by(self, column: str) -> "QueryBuilder":
+    def group_by(self, column: str) -> "Self":
         for col in column.split(","):
             col = col.strip()
             self._group_by += (GroupByExpression(col),)
         return self
 
-    def group_by_raw(self, expression: str) -> "QueryBuilder":
+    def group_by_raw(self, expression: str) -> "Self":
         self._group_by += (GroupByExpression(expression, raw=True),)
         return self
 
-    def having(self, column: str, equality: str, value) -> "QueryBuilder":
+    def having(self, column: str, equality: str, value: Any) -> "Self":
         self._having += (HavingExpression(column, equality, value),)
         return self
 
-    def where_null(self, column: str) -> "QueryBuilder":
+    def where_null(self, column: str) -> "Self":
         self._wheres += (QueryExpression(column, "=", None, "NULL"),)
         return self
 
-    def where_not_null(self, column: str) -> "QueryBuilder":
+    def where_not_null(self, column: str) -> "Self":
         self._wheres += (QueryExpression(column, "=", None, "NOT NULL"),)
         return self
 
-    def or_where_null(self, column: str) -> "QueryBuilder":
+    def or_where_null(self, column: str) -> "Self":
         self._wheres += (QueryExpression(column, "=", None, "NULL", keyword="or"),)
         return self
 
-    def or_where_not_null(self, column: str) -> "QueryBuilder":
+    def or_where_not_null(self, column: str) -> "Self":
         self._wheres += (QueryExpression(column, "=", None, "NOT NULL", keyword="or"),)
         return self
 
-    def where_not_in(self, column: str, values) -> "QueryBuilder":
+    def where_not_in(self, column: str, values: Iterable[Any]) -> "Self":
         values = list(values) if not isinstance(values, list) else values
         self._wheres.append(QueryExpression(column, "NOT IN", values))
         return self
 
-    def between(self, column: str, low, high) -> "QueryBuilder":
+    def between(self, column: str, low: Any, high: Any) -> "Self":
         self._wheres += (BetweenExpression(column, low, high, "BETWEEN"),)
         return self
 
-    def not_between(self, column: str, low, high) -> "QueryBuilder":
+    def not_between(self, column: str, low: Any, high: Any) -> "Self":
         self._wheres += (BetweenExpression(column, low, high, "NOT BETWEEN"),)
         return self
 
-    def left_join(self, table: str, column1: str, equality: str, column2: str) -> "QueryBuilder":
+    def left_join(self, table: str, column1: str, equality: str, column2: str) -> "Self":
         return self.join(table, column1, equality, column2, clause="left")
 
-    def right_join(self, table: str, column1: str, equality: str, column2: str) -> "QueryBuilder":
+    def right_join(self, table: str, column1: str, equality: str, column2: str) -> "Self":
         # SQLite doesn't support RIGHT JOIN — use left join as fallback
         return self.join(table, column1, equality, column2, clause="right")
 
-    def distinct(self) -> "QueryBuilder":
+    def distinct(self) -> "Self":
         self._distinct = True
         return self
 
@@ -322,27 +382,27 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
     async def avg(self, column: str):
         return await self.aggregate("AVG", column)
 
-    async def delete(self, column=None, value=None):
+    async def delete(self, column: str | None = None, value: Any = None):
         if column is not None:
             self.where(column, value)
         self.set_action("delete")
         sql = self.to_qmark()
         return await self.connection.delete(sql, list(self.get_bindings()))
 
-    async def create(self, attributes: dict):
+    async def create(self, attributes: dict[str, Any]) -> "TModel":
         model = self._model.new_model_instance(attributes)
         await model.save()
 
         return model
 
-    async def first_or_create(self, search: dict, attributes: dict | None = None):
+    async def first_or_create(self, search: dict[str, Any], attributes: dict[str, Any] | None = None) -> "TModel":
         instance = await self.where(search).first()
         if instance is not None:
             return instance
 
         return await self.create({**(attributes or {}), **search})
 
-    async def update_or_create(self, search: dict, attributes: dict | None = None):
+    async def update_or_create(self, search: dict[str, Any], attributes: dict[str, Any] | None = None) -> "TModel":
         instance = await self.where(search).first()
         if instance is not None:
             if attributes:
@@ -351,7 +411,7 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
 
         return await self.create({**(attributes or {}), **search})
 
-    async def insert(self, values: dict | list) -> int | None:
+    async def insert(self, values: dict[str, Any] | list[dict[str, Any]]) -> int | None:
         self.set_action("bulk_create")
 
         if not values:
@@ -379,7 +439,7 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
 
         return await self.connection.insert_get_id(sql, bindings)
 
-    async def update(self, values: dict) -> int:
+    async def update(self, values: dict[str, Any]) -> int:
         updates = [UpdateQueryExpression(col, val) for col, val in values.items()]
         grammar = self.grammar()
         sql = grammar._compile_update(query=self, values=updates, qmark=True).to_sql()
@@ -492,7 +552,7 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
         # with .table(...) as usual.
         return self.connection.query().table(self._table)
 
-    def invalid_operator(self, operator):
+    def invalid_operator(self, operator: Any) -> bool:
         """Determine whether an operator is not supported by the builder."""
         return not isinstance(operator, str) or operator.lower() not in self.operators
 
@@ -538,20 +598,20 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
             self._wheres += ((QueryExpression(column, operator, value, "value")),)
         return self
 
-    def or_where(self, column, *args) -> "QueryBuilder":
+    def or_where(self, column: str, *args: Any) -> "Self":
         operator, value = self._extract_operator_value(*args)
         self._wheres += ((QueryExpression(column, operator, value, "value", keyword="or")),)
         return self
 
-    def where_raw(self, expression: str, bindings=()) -> "QueryBuilder":
+    def where_raw(self, expression: str, bindings: tuple[Any, ...] = ()) -> "Self":
         self._wheres += (QueryExpression(expression, "=", None, raw=True, bindings=bindings),)
         return self
 
-    def or_where_raw(self, expression: str, bindings=()) -> "QueryBuilder":
+    def or_where_raw(self, expression: str, bindings: tuple[Any, ...] = ()) -> "Self":
         self._wheres += (QueryExpression(expression, "=", None, raw=True, keyword="or", bindings=bindings),)
         return self
 
-    def join(self, table: str, column1: str, equality: str, column2: str, clause: str = "join") -> "QueryBuilder":
+    def join(self, table: str, column1: str, equality: str, column2: str, clause: str = "join") -> "Self":
         join_clause = JoinClause(table, clause=clause)
         join_clause.on(column1, equality, column2)
         self._joins += (join_clause,)
@@ -574,32 +634,32 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
             )
         return operator, column2
 
-    def where_column(self, column1: str, operator: str, column2: str | None = None) -> "QueryBuilder":
+    def where_column(self, column1: str, operator: str, column2: str | None = None) -> "Self":
         """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":
+    def or_where_column(self, column1: str, operator: str, column2: str | None = None) -> "Self":
         """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":
+    def when(self, condition: Any, callback: Callable[["Self"], Any]) -> "Self":
         if condition:
             callback(self)
         return self
 
-    def where_exists(self, builder: "QueryBuilder") -> "QueryBuilder":
+    def where_exists(self, builder: "QueryBuilder[Any]") -> "Self":
         self._wheres += (QueryExpression(None, "EXISTS", SubSelectExpression(builder)),)
         return self
 
-    def or_where_exists(self, builder: "QueryBuilder") -> "QueryBuilder":
+    def or_where_exists(self, builder: "QueryBuilder[Any]") -> "Self":
         self._wheres += (QueryExpression(None, "EXISTS", SubSelectExpression(builder), keyword="or"),)
         return self
 
-    def where_has(self, relation: str, callback=None) -> "QueryBuilder":
+    def where_has(self, relation: str, callback: Callable[..., Any] | None = None) -> "Self":
         related = getattr(self._model.__class__, relation)
         if callback:
             related.query_where_exists(self, callback, method="where_exists")
@@ -607,7 +667,7 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
             related.query_has(self, method="where_exists")
         return self
 
-    def or_where_has(self, relation: str, callback=None) -> "QueryBuilder":
+    def or_where_has(self, relation: str, callback: Callable[..., Any] | None = None) -> "Self":
         related = getattr(self._model.__class__, relation)
         if callback:
             related.query_where_exists(self, callback, method="or_where_exists")
@@ -616,7 +676,7 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
         return self
 
     @classmethod
-    def clean_bindings(cls, values):
+    def clean_bindings(cls, values: dict[str, Any] | list[dict[str, Any]]) -> list[Any]:
         if isinstance(values, dict):
             values = [values]
         return [val for row in values for val in row.values()]