fix(docs): escape type names in changelog to fix rst reference error

The trailing underscore in `SyncServiceT_…` was being interpreted as
an RST reference target, causing the doc build to fail with
"Unknown target name: syncservicet".

Author: cofin

advanced_alchemy/base.py

@@ -3,7 +3,7 @@
 import contextlib
 import datetime
 import re
-from collections.abc import Iterator
+from collections.abc import Iterator, Mapping
 from typing import TYPE_CHECKING, Any, Optional, Protocol, Union, cast, runtime_checkable
 from uuid import UUID
 
@@ -216,64 +216,42 @@ def __init_subclass__(cls, **kwargs: Any) -> None:
         they share the parent's table. This hook enforces that rule.
 
         The detection logic identifies STI children by checking:
-        1. Class has ``polymorphic_identity`` in ``__mapper_args__`` (explicit STI child marker)
+        1. Class doesn't explicitly define ``__tablename__`` in its own ``__dict__``
         2. AND doesn't have ``concrete=True`` (which would make it CTI)
-        3. AND doesn't have ``polymorphic_on`` itself (which would make it a base)
-        4. AND doesn't explicitly define ``__tablename__`` in its own ``__dict__``
+        3. AND doesn't define ``polymorphic_on`` in its own ``__mapper_args__`` (which would make it a base)
+        4. AND inherits from a parent that defines ``polymorphic_on`` in ``__mapper_args__`` (STI hierarchy)
 
-        For children without ``polymorphic_identity`` but with a parent that has
-        ``polymorphic_on``, SQLAlchemy treats them as abstract intermediate classes
-        and will issue a warning. We don't modify ``__tablename__`` for these cases.
+        For intermediate classes without ``polymorphic_identity`` but with a parent that has
+        ``polymorphic_on``, SQLAlchemy can emit a warning. When an intermediate class should
+        not be instantiated, set ``polymorphic_abstract=True`` in ``__mapper_args__`` or mark it
+        with ``__abstract__ = True``.
 
         This allows both usage patterns:
         1. Auto-generated names (don't set ``__tablename__`` on parent)
         2. Explicit names (set ``__tablename__`` on parent, STI still works)
         """
-        # IMPORTANT: Modify the class BEFORE calling super().__init_subclass__()
-        # because super() triggers SQLAlchemy's declarative processing
-        mapper_args = getattr(cls, "__mapper_args__", {})
-
-        # Skip if this class explicitly defines its own __tablename__
         if "__tablename__" in cls.__dict__:
             super().__init_subclass__(**kwargs)
             return
 
-        # Skip if this is CTI (concrete table inheritance)
-        if mapper_args.get("concrete", False):
+        cls_dict = cast("Mapping[str, Any]", cls.__dict__)
+        own_mapper_args = cls_dict.get("__mapper_args__")
+        own_mapper_args_dict = cast("dict[str, Any]", own_mapper_args) if isinstance(own_mapper_args, dict) else {}
+
+        if own_mapper_args_dict.get("concrete", False):
+            super().__init_subclass__(**kwargs)
+            return
+
+        if "polymorphic_on" in own_mapper_args_dict:
             super().__init_subclass__(**kwargs)
             return
 
-        # Check if this class might be an STI child
-        # An STI child either has polymorphic_identity in its own __mapper_args__,
-        # or inherits from a parent with polymorphic_on
-        is_potential_sti_child = False
-
-        # Check if THIS class (not inherited) defines polymorphic_on
-        # If it does, it's a base class, not a child
-        if "__mapper_args__" in cls.__dict__:
-            own_mapper_args = cls.__dict__["__mapper_args__"]
-            if "polymorphic_on" in own_mapper_args:
-                # This is a base class, not a child - skip
-                super().__init_subclass__(**kwargs)
-                return
-
-        # Check if any parent has polymorphic_on (indicates we're in an STI hierarchy)
         for parent in cls.__mro__[1:]:
-            if not hasattr(parent, "__mapper_args__"):
-                continue
-            parent_mapper_args = getattr(parent, "__mapper_args__", {})
-            if "polymorphic_on" in parent_mapper_args:
-                # We're inheriting from a polymorphic base, so we're an STI child
-                is_potential_sti_child = True
+            parent_mapper_args = getattr(parent, "__mapper_args__", None)
+            if isinstance(parent_mapper_args, dict) and "polymorphic_on" in parent_mapper_args:
+                cls.__tablename__ = None  # type: ignore[misc]
                 break
 
-        if is_potential_sti_child and "__tablename__" not in cls.__dict__:
-            # For STI children that inherited an explicit __tablename__ from a parent,
-            # we need to explicitly set it to None so SQLAlchemy knows to use the parent's table.
-            # This overrides the inherited string value.
-            cls.__tablename__ = None  # type: ignore[misc]
-
-        # Now call super() which triggers SQLAlchemy's declarative system
         super().__init_subclass__(**kwargs)
 
     if TYPE_CHECKING:
@@ -359,40 +337,20 @@ class Manager(Employee):
                         __tablename__ = "manager"  # Independent table
                         __mapper_args__ = {"concrete": True}
             """
-            # Check if class explicitly defines __tablename__ in its own __dict__
-            if "__tablename__" in cls.__dict__:
-                value = cls.__dict__["__tablename__"]
-                # If explicitly set to None (e.g., by __init_subclass__ for STI), return None
-                if value is None:
-                    return None
-                return value
+            cls_dict = cast("Mapping[str, Any]", cls.__dict__)
+            if "__tablename__" in cls_dict:
+                return cast("Optional[str]", cls_dict["__tablename__"])
 
-            # Check if this is an STI child class that needs auto-detection
-            # This handles cases where the parent didn't explicitly set __tablename__
             mapper_args = getattr(cls, "__mapper_args__", {})
+            mapper_args_dict = cast("dict[str, Any]", mapper_args) if isinstance(mapper_args, dict) else {}
+            if mapper_args_dict.get("concrete", False) or "polymorphic_on" in mapper_args_dict:
+                return table_name_regexp.sub(r"_\1", cls.__name__).lower()
 
-            # Skip STI detection if this class defines polymorphic_on (it's a base, not a child)
-            if "polymorphic_on" not in mapper_args:
-                is_sti_child = False
-
-                # Check explicit STI marker
-                if "polymorphic_identity" in mapper_args:
-                    is_sti_child = True
-                else:
-                    # Check if any parent has polymorphic_on (indicates STI hierarchy)
-                    for parent in cls.__mro__[1:]:
-                        if not hasattr(parent, "__mapper_args__"):
-                            continue
-                        parent_mapper_args = getattr(parent, "__mapper_args__", {})
-                        if "polymorphic_on" in parent_mapper_args:
-                            is_sti_child = True
-                            break
-
-                if is_sti_child:
-                    # This is an STI child - return None to use parent's table
+            for parent in cls.__mro__[1:]:
+                parent_mapper_args = getattr(parent, "__mapper_args__", None)
+                if isinstance(parent_mapper_args, dict) and "polymorphic_on" in parent_mapper_args:
                     return None
 
-            # Generate table name from class name using snake_case conversion
             return table_name_regexp.sub(r"_\1", cls.__name__).lower()
 
 

docs/changelog.rst

@@ -21,7 +21,7 @@
         Cause:
         We added the `sa.PasslibHasher = PasslibHasher` and `sa.PwdlibHasher = PwdlibHasher` types in `script.py.mako`. As a result, when a user installs only Advanced Alchemy and creates a migration, these files are imported. Since they reference types from `passlib` and `pwdlib`, which are not installed by default, the import fails and triggers this error.
 
-    .. change:: add missing type parameter to AsyncServiceT_co and SyncServiceT_…
+    .. change:: add missing type parameter to ``AsyncServiceT_co`` and ``SyncServiceT_co``
         :type: bugfix
         :pr: 612
 

pyproject.toml

@@ -220,6 +220,7 @@ filterwarnings = [
   "ignore::DeprecationWarning:google.gcloud",
   "ignore::DeprecationWarning:google.iam",
   "ignore::DeprecationWarning:google",
+  "ignore:You are using a Python version \\(.*\\) which Google will stop supporting.*:FutureWarning:google.api_core._python_version_support",
   "ignore::DeprecationWarning:websockets.connection",
   "ignore::DeprecationWarning:websockets.legacy",
   "ignore:Accessing argon2.__version__ is deprecated:DeprecationWarning:passlib.handlers.argon2",

tests/integration/test_inheritance.py

@@ -7,18 +7,15 @@
 """
 
 import datetime
-from typing import TYPE_CHECKING, Any, Optional
+from typing import Optional
 
 import pytest
 from sqlalchemy import ForeignKey, MetaData, select
-from sqlalchemy.orm import DeclarativeBase, Mapped, Session, mapped_column
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 
 from advanced_alchemy import base
 
-if TYPE_CHECKING:
-    pass
-
-
 # ============================================================================
 # Single Table Inheritance (STI) Tests
 # ============================================================================
@@ -117,7 +114,7 @@ class SeniorManager(Manager):
 
 @pytest.mark.integration
 @pytest.mark.sqlite
-def test_sti_crud_operations(session: Session, sqlite_engine: Any) -> None:
+def test_sti_crud_operations(sqlite_engine: Engine) -> None:
     """STI: CRUD operations work correctly with polymorphic models."""
     from sqlalchemy.orm import Session as SessionType
 
@@ -242,7 +239,7 @@ class Engineer(Employee):
 
 @pytest.mark.integration
 @pytest.mark.sqlite
-def test_jti_crud_operations(session: Session, sqlite_engine: Any) -> None:
+def test_jti_crud_operations(sqlite_engine: Engine) -> None:
     """JTI: CRUD operations with joined tables."""
     from sqlalchemy.orm import Session as SessionType
 
@@ -356,7 +353,7 @@ class Engineer(Employee):
 
 @pytest.mark.integration
 @pytest.mark.sqlite
-def test_cti_crud_operations(session: Session, sqlite_engine: Any) -> None:
+def test_cti_crud_operations(sqlite_engine: Engine) -> None:
     """CTI: CRUD operations with concrete tables."""
     from sqlalchemy.orm import Session as SessionType
 
@@ -489,6 +486,10 @@ class StandaloneModel(base.CommonTableAttributes, LocalBase):
 
 
 @pytest.mark.integration
+@pytest.mark.filterwarnings(
+    "ignore:Mapper\\[Manager\\(employee_no_poly_id\\)\\] does not indicate a 'polymorphic_identity'.*:"
+    "sqlalchemy.exc.SAWarning"
+)
 def test_sti_without_polymorphic_identity_on_child() -> None:
     """STI child without explicit polymorphic_identity still uses parent table."""
     test_metadata = MetaData()

tests/unit/test_base.py

@@ -58,11 +58,11 @@ def test_identity_primary_key_generates_identity_ddl() -> None:
     class TestMixin(IdentityPrimaryKey):
         pass
 
-    class TestModel(TestMixin, BigIntBase):
+    class IdentityPrimaryKeyModel(TestMixin, BigIntBase):
         __tablename__ = "test_identity"
 
     # Get the CREATE TABLE statement
-    create_stmt = CreateTable(cast(Table, TestModel.__table__))
+    create_stmt = CreateTable(cast(Table, IdentityPrimaryKeyModel.__table__))
 
     # Test with PostgreSQL dialect
     pg_ddl = str(create_stmt.compile(dialect=postgresql.dialect()))  # type: ignore[no-untyped-call,unused-ignore]
@@ -78,11 +78,11 @@ def test_identity_audit_base_generates_identity_ddl() -> None:
     """Test that IdentityAuditBase generates proper IDENTITY DDL for PostgreSQL."""
     from advanced_alchemy.base import IdentityAuditBase
 
-    class TestModel(IdentityAuditBase):
+    class IdentityAuditBaseModel(IdentityAuditBase):
         __tablename__ = "test_identity_audit"
 
     # Get the CREATE TABLE statement
-    create_stmt = CreateTable(cast(Table, TestModel.__table__))
+    create_stmt = CreateTable(cast(Table, IdentityAuditBaseModel.__table__))
 
     # Test with PostgreSQL dialect
     pg_ddl = str(create_stmt.compile(dialect=postgresql.dialect()))  # type: ignore[no-untyped-call,unused-ignore]
@@ -101,11 +101,11 @@ def test_bigint_primary_key_still_uses_sequence() -> None:
     class TestMixin(BigIntPrimaryKey):
         pass
 
-    class TestModel(TestMixin, BigIntBase):
+    class BigIntPrimaryKeyModel(TestMixin, BigIntBase):
         __tablename__ = "test_bigint"
 
     # Get the CREATE TABLE statement
-    create_stmt = CreateTable(cast(Table, TestModel.__table__))
+    create_stmt = CreateTable(cast(Table, BigIntPrimaryKeyModel.__table__))
 
     # Test with PostgreSQL dialect
     pg_ddl = str(create_stmt.compile(dialect=postgresql.dialect()))  # type: ignore[no-untyped-call,unused-ignore]
@@ -114,18 +114,18 @@ class TestModel(TestMixin, BigIntBase):
     assert "GENERATED" not in pg_ddl
     assert "IDENTITY" not in pg_ddl.upper()
     # The sequence is defined on the column but rendered separately
-    assert TestModel.__table__.c.id.default is not None
-    assert TestModel.__table__.c.id.default.name == "test_bigint_id_seq"
+    assert BigIntPrimaryKeyModel.__table__.c.id.default is not None
+    assert BigIntPrimaryKeyModel.__table__.c.id.default.name == "test_bigint_id_seq"
 
 
 def test_identity_ddl_for_oracle() -> None:
     """Test Identity DDL generation for Oracle."""
     from advanced_alchemy.base import IdentityAuditBase
 
-    class TestModel(IdentityAuditBase):
+    class OracleIdentityAuditBaseModel(IdentityAuditBase):
         __tablename__ = "test_oracle"
 
-    create_stmt = CreateTable(cast(Table, TestModel.__table__))
+    create_stmt = CreateTable(cast(Table, OracleIdentityAuditBaseModel.__table__))
     oracle_ddl = str(create_stmt.compile(dialect=oracle.dialect()))  # type: ignore[no-untyped-call,unused-ignore]
 
     # Oracle should generate IDENTITY
@@ -136,10 +136,10 @@ def test_identity_ddl_for_mssql() -> None:
     """Test Identity DDL generation for SQL Server."""
     from advanced_alchemy.base import IdentityAuditBase
 
-    class TestModel(IdentityAuditBase):
+    class MSSQLIdentityAuditBaseModel(IdentityAuditBase):
         __tablename__ = "test_mssql"
 
-    create_stmt = CreateTable(cast(Table, TestModel.__table__))
+    create_stmt = CreateTable(cast(Table, MSSQLIdentityAuditBaseModel.__table__))
     mssql_ddl = str(create_stmt.compile(dialect=mssql.dialect()))  # type: ignore[no-untyped-call,unused-ignore]
 
     # SQL Server should generate IDENTITY
@@ -150,12 +150,12 @@ def test_identity_works_with_sqlite() -> None:
     """Test that Identity columns work with SQLite (fallback to autoincrement)."""
     from advanced_alchemy.base import IdentityAuditBase
 
-    class TestModel(IdentityAuditBase):
+    class SQLiteIdentityAuditBaseModel(IdentityAuditBase):
         __tablename__ = "test_sqlite"
 
     # Create an in-memory SQLite engine
     engine = create_engine("sqlite:///:memory:")
-    cast(Table, TestModel.__table__).create(engine)
+    cast(Table, SQLiteIdentityAuditBaseModel.__table__).create(engine)
 
     # Should not raise any errors
     assert True  # If we get here, it worked