Исключение UnmappedInstanceError

Исключение UnmappedInstanceError наследуется от SQLAlchemyError и возбуждается, когда ORM-операция пытается работать с объектом, класс которого не был отображён на таблицу. Например, это происходит при добавлении в сессию экземпляра обычного класса Python или экземпляра декларативной модели, у которой отсутствует маппинг.

Чаще всего исключение возникает при вызове метода add у сессии или при работе с атрибутами, требующими наличия инструментов ORM у объекта.

Синтаксис

from sqlalchemy.orm.exc import UnmappedInstanceError

Пример

Давайте попробуем добавить в сессию экземпляр обычного класса, не отображённого на таблицу:

from sqlalchemy import create_engine
from sqlalchemy.orm import Session
from sqlalchemy.orm.exc import UnmappedInstanceError

class Article:
	def __init__(self, title):
		self.title = title

engine = create_engine('sqlite:///:memory:')

with Session(engine) as session:
	article = Article('article')
	try:
		session.add(article)
		session.commit()
	except UnmappedInstanceError as exc:
		print(type(exc).__name__)
		print(exc)

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

"UnmappedInstanceError"
"Class 'Article' is not mapped"

Пример

Давайте рассмотрим корректный вариант с декларативной моделью, отображённой на таблицу:

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]
	status: Mapped[str]
	num: Mapped[int]

Теперь объект успешно добавляется в сессию:

from sqlalchemy import create_engine
from sqlalchemy.orm import Session
from models import Base, Article

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

with Session(engine) as session:
	article = Article(
		title='article',
		text='text',
		status='draft',
		num=1
	)
	session.add(article)
	session.commit()
	print(article.id)

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

"1"

Пример

Давайте перехватим исключение и выведем информативное сообщение об ошибке:

from sqlalchemy import create_engine
from sqlalchemy.orm import Session
from sqlalchemy.orm.exc import UnmappedInstanceError

class User:
	pass

engine = create_engine('sqlite:///:memory:')

with Session(engine) as session:
	user = User()
	try:
		session.add(user)
	except UnmappedInstanceError:
		print('Object is not mapped to any table')

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

"Object is not mapped to any table"

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

класс UnmappedClassError,
который возбуждается, когда не отображён сам класс
класс SQLAlchemyError,
который является базовым для всех исключений SQLAlchemy
класс InvalidRequestError,
который сигнализирует о некорректном запросе к сессии
класс DetachedInstanceError,
который возникает при работе с отсоединённым объектом