Атрибут __mapper_args__ модели

Атрибут __mapper_args__ задается внутри декларативной модели и передает дополнительные параметры мапперу SQLAlchemy. Через него настраивают полиморфное наследование, порядок колонок, версионирование строк, а также другие опции, которые не выражаются через mapped_column. Значением атрибута выступает словарь, ключи которого соответствуют аргументам функции mapper.

Синтаксис

class Model(Base):
	__tablename__ = 'table_name'
	
	__mapper_args__ = {
		'key': value,
	}

Пример

Чаще всего атрибут __mapper_args__ применяют для настройки полиморфного наследования. Давайте создадим базовую модель Article и наследника DraftArticle, который хранится в той же таблице и различается по колонке status:

from sqlalchemy import create_engine, select
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, Session

class Base(DeclarativeBase):
	pass

class Article(Base):
	__tablename__ = 'articles'
	
	id: Mapped[int] = mapped_column(primary_key=True)
	title: Mapped[str]
	status: Mapped[str]
	
	__mapper_args__ = {
		'polymorphic_on': status,
		'polymorphic_identity': 'article',
	}

class DraftArticle(Article):
	__mapper_args__ = {
		'polymorphic_identity': 'draft',
	}

engine = create_engine('sqlite:///:memory:')
Base.metadata.create_all(engine)

with Session(engine) as session:
	session.add(Article(title='article 1', status='article'))
	session.add(DraftArticle(title='article 2', status='draft'))
	session.commit()
	
	res = session.scalars(select(Article)).all()
	for article in res:
		print(type(article).__name__, article.title)

Результат выполнения кода:

Article article 1
DraftArticle article 2

Пример

Еще одна распространенная задача - задать порядок колонок в таблице через ключ column_ordering. Это полезно, когда нужно, чтобы нужные поля шли первыми:

from sqlalchemy import create_engine, inspect
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column

class Base(DeclarativeBase):
	pass

class Article(Base):
	__tablename__ = 'articles'
	
	id: Mapped[int] = mapped_column(primary_key=True)
	title: Mapped[str]
	text: Mapped[str]
	
	__mapper_args__ = {
		'column_ordering': 'id, title, text',
	}

engine = create_engine('sqlite:///:memory:')
Base.metadata.create_all(engine)

inspector = inspect(engine)
res = [col['name'] for col in inspector.get_columns('articles')]
print(res)

Результат выполнения кода:

['id', 'title', 'text']

Пример

Ключ version_id_col включает оптимистичную блокировку строк: при каждом обновлении объекта колонка версии увеличивается автоматически:

from sqlalchemy import create_engine, Integer
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, Session

class Base(DeclarativeBase):
	pass

class Article(Base):
	__tablename__ = 'articles'
	
	id: Mapped[int] = mapped_column(primary_key=True)
	title: Mapped[str]
	version: Mapped[int] = mapped_column(Integer, nullable=False)
	
	__mapper_args__ = {
		'version_id_col': version,
	}

engine = create_engine('sqlite:///:memory:')
Base.metadata.create_all(engine)

with Session(engine) as session:
	article = Article(title='article 1', version=1)
	session.add(article)
	session.commit()
	
	article.title = 'article 2'
	session.commit()
	
	print(article.version)

Результат выполнения кода:

2

Смотрите также

атрибут __tablename__,
который задает имя таблицы модели
атрибут __table_args__,
который передает параметры таблицы
класс DeclarativeBase,
который служит базой декларативных моделей
функцию mapped_column,
которая описывает колонку модели