fix: complete SQLAlchemy inheritance pattern support (STI, JTI, CTI)

[cofin]

Summary

This PR completes the implementation of SQLAlchemy inheritance pattern support in CommonTableAttributes, enabling proper handling of Single Table Inheritance (STI), Joined Table Inheritance (JTI), and Concrete Table Inheritance (CTI).

Changes

Core Implementation (advanced_alchemy/base.py)

1. Added __init_subclass__ hook (lines 209-277):

   • Detects STI children by checking if any parent has polymorphic_on in their __mapper_args__
   • Automatically sets cls.__tablename__ = None for STI children
   • Handles both explicit (with polymorphic_identity) and implicit (without) STI children
   • Properly distinguishes between base classes and child classes

2. Enhanced @declared_attr.__tablename__() method (lines 281-386):

   • Returns None for explicitly set None values (set by __init_subclass__)
   • Provides fallback STI detection for cases where parent doesn't have explicit tablename
   • Generates snake_case table names for non-STI classes

Supported Patterns

1. ✅ Single Table Inheritance (STI):

   • Child classes with polymorphic_identity share parent's table
   • Works with both auto-generated and explicit parent table names
   • Handles edge case of children without polymorphic_identity (with warning)

2. ✅ Joined Table Inheritance (JTI):

   • Child classes with explicit __tablename__ create joined tables
   • Proper foreign key relationships maintained

3. ✅ Concrete Table Inheritance (CTI):

   • Child classes with concrete=True create independent tables
   • No foreign keys to parent table

Related Issues

Supersedes PR #600

[github-actions]

Documentation preview will be available shortly at https://litestar-org.github.io/advanced-alchemy-docs-preview/611