base

Common base classes for SQLAlchemy declarative models.

class advanced_alchemy.base.AdvancedDeclarativeBase

Bases: DeclarativeBase

A subclass of declarative base that allows for overriding of the registry.

Inherits from sqlalchemy.orm.DeclarativeBase.

registry

The registry for the declarative base.

Type:

sqlalchemy.orm.registry

__metadata_registry__

The metadata registry.

Type:

MetadataRegistry

__bind_key__

The bind key for the metadata.

Type:

Optional[str]

registry: ClassVar[_RegistryType] = <sqlalchemy.orm.decl_api.registry object>

Refers to the _orm.registry in use where new _orm.Mapper objects will be associated.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

Parameters:

• self (Any)

• kwargs (Any)

Return type:

None

metadata: ClassVar[MetaData] = MetaData()

Refers to the _schema.MetaData collection that will be used for new _schema.Table objects.

See also

Accessing Table and Metadata

class advanced_alchemy.base.BasicAttributes

Bases: object

Basic attributes for SQLAlchemy tables and queries.

Provides a method to convert the model to a dictionary representation.

to_dict()

Converts the model to a dictionary, excluding specified fields. :no-index:

Parameters:

exclude (set[str] | None)

Return type:

dict[str, Any]

to_dict(exclude=None)

Convert model to dictionary.

Returns:

A dict representation of the model

Return type:

Dict[str, Any]

Parameters:

exclude (set[str] | None)

class advanced_alchemy.base.BigIntAuditBase

Bases: CommonTableAttributes, BigIntPrimaryKey, AuditColumns, AdvancedDeclarativeBase, AsyncAttrs

Base for declarative models with BigInt primary keys and audit columns.

See also

CommonTableAttributes advanced_alchemy.mixins.BigIntPrimaryKey advanced_alchemy.mixins.AuditColumns AdvancedDeclarativeBase AsyncAttrs

class advanced_alchemy.base.BigIntBase

Bases: BigIntPrimaryKey, CommonTableAttributes, AdvancedDeclarativeBase, AsyncAttrs

Base for all SQLAlchemy declarative models with BigInt primary keys.

See also

advanced_alchemy.mixins.BigIntPrimaryKey CommonTableAttributes AdvancedDeclarativeBase AsyncAttrs

class advanced_alchemy.base.BigIntBaseT

Type variable for BigIntBase.

alias of TypeVar(‘BigIntBaseT’, bound=BigIntBase)

class advanced_alchemy.base.CommonTableAttributes

Bases: BasicAttributes

Common attributes for SQLAlchemy tables.

Inherits from BasicAttributes and provides a mechanism to infer table names from class names while respecting SQLAlchemy’s inheritance patterns.

This mixin supports all three SQLAlchemy inheritance patterns: - Single Table Inheritance (STI): Child classes automatically use parent’s table - Joined Table Inheritance (JTI): Child classes have their own tables with foreign keys - Concrete Table Inheritance (CTI): Child classes have independent tables

__tablename__

The inferred table name, or None for Single Table Inheritance children.

Type:

str | None

classmethod __init_subclass__(**kwargs)

Hook called when a subclass is created.

This method intercepts class creation to correctly handle __tablename__ for Single Table Inheritance (STI) hierarchies. When a parent class explicitly defines __tablename__, subclasses would normally inherit that string value. For STI, child classes must have __tablename__ resolve to None to indicate 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) 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__

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.

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)

Return type:

None

Parameters:

kwargs (Any)

class advanced_alchemy.base.DefaultBase

Bases: CommonTableAttributes, AdvancedDeclarativeBase, AsyncAttrs

Base for all SQLAlchemy declarative models. No primary key is added.

See also

CommonTableAttributes AdvancedDeclarativeBase AsyncAttrs

class advanced_alchemy.base.IdentityAuditBase

Bases: CommonTableAttributes, IdentityPrimaryKey, AuditColumns, AdvancedDeclarativeBase, AsyncAttrs

Base for declarative models with database IDENTITY primary keys and audit columns.

This model uses the database native IDENTITY feature for generating primary keys instead of using database sequences.

See also

CommonTableAttributes advanced_alchemy.mixins.IdentityPrimaryKey advanced_alchemy.mixins.AuditColumns AdvancedDeclarativeBase AsyncAttrs

class advanced_alchemy.base.IdentityBase

Bases: IdentityPrimaryKey, CommonTableAttributes, AdvancedDeclarativeBase, AsyncAttrs

Base for all SQLAlchemy declarative models with database IDENTITY primary keys.

This model uses the database native IDENTITY feature for generating primary keys instead of using database sequences.

See also

advanced_alchemy.mixins.IdentityPrimaryKey CommonTableAttributes AdvancedDeclarativeBase AsyncAttrs

class advanced_alchemy.base.IdentityBaseT

Type variable for IdentityBase.

alias of TypeVar(‘IdentityBaseT’, bound=IdentityBase)

class advanced_alchemy.base.ModelProtocol

Bases: Protocol

The base SQLAlchemy model protocol.

__table__

The table associated with the model.

Type:

sqlalchemy.sql.FromClause

__mapper__

The mapper for the model.

Type:

sqlalchemy.orm.Mapper

__name__

The name of the model.

Type:

str

to_dict(exclude=None)

Convert model to dictionary.

Returns:

A dict representation of the model

Return type:

Dict[str, Any]

Parameters:

exclude (set[str] | None)

__init__(*args, **kwargs)

class advanced_alchemy.base.NanoIDAuditBase

Bases: CommonTableAttributes, NanoIDPrimaryKey, AuditColumns, AdvancedDeclarativeBase, AsyncAttrs

Base for declarative models with Nano ID primary keys and audit columns.

See also

CommonTableAttributes advanced_alchemy.mixins.NanoIDPrimaryKey advanced_alchemy.mixins.AuditColumns AdvancedDeclarativeBase AsyncAttrs

class advanced_alchemy.base.NanoIDBase

Bases: NanoIDPrimaryKey, CommonTableAttributes, AdvancedDeclarativeBase, AsyncAttrs

Base for all SQLAlchemy declarative models with Nano ID primary keys.

See also

advanced_alchemy.mixins.NanoIDPrimaryKey CommonTableAttributes AdvancedDeclarativeBase AsyncAttrs

class advanced_alchemy.base.NanoIDBaseT

Type variable for NanoIDBase.

alias of TypeVar(‘NanoIDBaseT’, bound=NanoIDBase)

class advanced_alchemy.base.SQLQuery

Bases: BasicAttributes, AdvancedDeclarativeBase, AsyncAttrs

Base for all SQLAlchemy custom mapped objects.

See also

BasicAttributes AdvancedDeclarativeBase AsyncAttrs

class advanced_alchemy.base.UUIDAuditBase

Bases: CommonTableAttributes, UUIDPrimaryKey, AuditColumns, AdvancedDeclarativeBase, AsyncAttrs

Base for declarative models with UUID v4 primary keys and audit columns.

See also

CommonTableAttributes advanced_alchemy.mixins.UUIDPrimaryKey advanced_alchemy.mixins.AuditColumns AdvancedDeclarativeBase AsyncAttrs

class advanced_alchemy.base.UUIDBase

Bases: UUIDPrimaryKey, CommonTableAttributes, AdvancedDeclarativeBase, AsyncAttrs

Base for all SQLAlchemy declarative models with UUID v4 primary keys.

See also

CommonTableAttributes advanced_alchemy.mixins.UUIDPrimaryKey AdvancedDeclarativeBase AsyncAttrs

class advanced_alchemy.base.UUIDBaseT

Type variable for UUIDBase.

alias of TypeVar(‘UUIDBaseT’, bound=UUIDBase)

class advanced_alchemy.base.UUIDv6AuditBase

Bases: CommonTableAttributes, UUIDv6PrimaryKey, AuditColumns, AdvancedDeclarativeBase, AsyncAttrs

Base for declarative models with UUID v6 primary keys and audit columns.

See also

CommonTableAttributes advanced_alchemy.mixins.UUIDv6PrimaryKey advanced_alchemy.mixins.AuditColumns AdvancedDeclarativeBase AsyncAttrs

class advanced_alchemy.base.UUIDv6Base

Bases: UUIDv6PrimaryKey, CommonTableAttributes, AdvancedDeclarativeBase, AsyncAttrs

Base for all SQLAlchemy declarative models with UUID v6 primary keys.

See also

advanced_alchemy.mixins.UUIDv6PrimaryKey CommonTableAttributes AdvancedDeclarativeBase AsyncAttrs

class advanced_alchemy.base.UUIDv6BaseT

Type variable for UUIDv6Base.

alias of TypeVar(‘UUIDv6BaseT’, bound=UUIDv6Base)

class advanced_alchemy.base.UUIDv7AuditBase

Bases: CommonTableAttributes, UUIDv7PrimaryKey, AuditColumns, AdvancedDeclarativeBase, AsyncAttrs

Base for declarative models with UUID v7 primary keys and audit columns.

See also

CommonTableAttributes advanced_alchemy.mixins.UUIDv7PrimaryKey advanced_alchemy.mixins.AuditColumns AdvancedDeclarativeBase AsyncAttrs

class advanced_alchemy.base.UUIDv7Base

Bases: UUIDv7PrimaryKey, CommonTableAttributes, AdvancedDeclarativeBase, AsyncAttrs

Base for all SQLAlchemy declarative models with UUID v7 primary keys.

See also

advanced_alchemy.mixins.UUIDv7PrimaryKey CommonTableAttributes AdvancedDeclarativeBase AsyncAttrs

class advanced_alchemy.base.UUIDv7BaseT

Type variable for UUIDv7Base.

alias of TypeVar(‘UUIDv7BaseT’, bound=UUIDv7Base)

advanced_alchemy.base.convention: _NamingSchemaTD | Mapping[Any, str | Callable[[Constraint, Table], str]] = {'ck': 'ck_%(table_name)s_%(constraint_name)s', 'fk': 'fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s', 'ix': 'ix_%(column_0_label)s', 'pk': 'pk_%(table_name)s', 'uq': 'uq_%(table_name)s_%(column_0_name)s'}

Templates for automated constraint name generation.

advanced_alchemy.base.create_registry(custom_annotation_map=None)

Create a new SQLAlchemy registry.

Parameters:

• custom_annotation_map (dict, optional) – Custom type annotations to use for the registry.

• custom_annotation_map (dict[Any, type[TypeEngine] | TypeEngine] | None)

Returns:

A new SQLAlchemy registry with the specified type annotations.

Return type:

sqlalchemy.orm.registry

advanced_alchemy.base.merge_table_arguments(cls, table_args=None)

Merge Table Arguments.

This function helps merge table arguments when using mixins that include their own table args, making it easier to append additional information such as comments or constraints to the model.

Parameters:

• cls (type[sqlalchemy.orm.DeclarativeBase]) – The model that will get the table args.

• table_args (TableArgsType, optional) – Additional information to add to table_args.

• cls (type[DeclarativeBase])

• table_args (Tuple[Any, ...] | Dict[str, Any] | None)

Returns:

Merged table arguments.

Return type:

TableArgsType

advanced_alchemy.base.table_name_regexp = re.compile('((?<=[a-z0-9])[A-Z]|(?!^)[A-Z](?=[a-z]))')

Regular expression for table name