sqlalchemy 2.0.51: exc.SQLAlchemyError

# sqlalchemy.exc.SQLAlchemyError API

This sample pins `sqlalchemy` 2.0.51 and verifies `sqlalchemy.exc.SQLAlchemyError` as the base exception class across Core and ORM layers.

The contract verifies:
- `SQLAlchemyError` inherits from built-in `Exception`.
- Instantiating `SQLAlchemyError` directly preserves the error message.
- Core and DBAPI exception classes (such as `ArgumentError`, `NoSuchTableError`, `DBAPIError`, `OperationalError`, `IntegrityError`, `CompileError`, `StatementError`) inherit from `SQLAlchemyError`.
- ORM exception classes (such as `NoResultFound`, `MultipleResultsFound`) inherit from `SQLAlchemyError`.
- Catching `SQLAlchemyError` intercepts Core statement execution failures, preserving underlying DBAPI driver details on `.orig`.
- Catching `SQLAlchemyError` intercepts ORM query execution exceptions (such as `NoResultFound` from `scalar_one()`).
- Catching `SQLAlchemyError` intercepts engine configuration errors (`ArgumentError`).

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify sqlalchemy.exc.SQLAlchemyError in pkg:pypi/sqlalchemy@2.0.51
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:pypi/sqlalchemy@2.0.51
Demonstrate these symbols/APIs:
  - sqlalchemy.exc.SQLAlchemyError

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:f87355f4375703b4cc223312267eefaf2c0540e6229c9673140e7bd663be6cba","contract":["SQLAlchemyError is the base exception class for all SQLAlchemy errors and inherits from built-in Exception.","Direct instantiation of SQLAlchemyError preserves the exception message.","Core and DBAPI exceptions including ArgumentError, NoSuchTableError, and OperationalError inherit from SQLAlchemyError.","ORM exceptions including NoResultFound and MultipleResultsFound inherit from SQLAlchemyError.","Catching SQLAlchemyError intercepts Core-level statement failures and wraps DBAPI errors with orig attribute preserved.","Catching SQLAlchemyError intercepts ORM scalar query exceptions and engine configuration failures."],"goal":"verify sqlalchemy.exc.SQLAlchemyError in pkg:pypi/sqlalchemy@2.0.51","kind":"HOW","packages":["pkg:pypi/sqlalchemy@2.0.51"],"schemaVersion":1,"symbols":["sqlalchemy.exc.SQLAlchemyError"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"pypi","executionContext":"python","language":"python","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"pip","runtime":"python","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/sqlalchemy@2.0.51"],"schemaVersion":1,"subject":"pkg:pypi/sqlalchemy@2.0.51","symbols":["sqlalchemy.exc.SQLAlchemyError"],"verifierAdapter":"python@1"}

sqlalchemy==2.0.51

{
  "schemaVersion": 1,
  "goal": "verify sqlalchemy.exc.SQLAlchemyError in pkg:pypi/sqlalchemy@2.0.51",
  "kind": "HOW",
  "packages": [
    "pkg:pypi/sqlalchemy@2.0.51"
  ],
  "symbols": [
    "sqlalchemy.exc.SQLAlchemyError"
  ]
}

import sqlalchemy as sa
from sqlalchemy import (
    MetaData,
    Table,
    Column,
    Integer,
    String,
    create_engine,
    select,
)
from sqlalchemy import exc
from sqlalchemy.orm import (
    DeclarativeBase,
    Mapped,
    mapped_column,
    Session,
)

# 1. Base exception inheritance: SQLAlchemyError inherits from Exception
assert issubclass(exc.SQLAlchemyError, Exception), "SQLAlchemyError must inherit from Exception"

# 2. Direct instantiation preserves message
err = exc.SQLAlchemyError("custom error message")
assert str(err) == "custom error message", "Direct instantiation must preserve message"

# 3. Core and DBAPI exception hierarchy
assert issubclass(exc.ArgumentError, exc.SQLAlchemyError), "ArgumentError must subclass SQLAlchemyError"
assert issubclass(exc.NoSuchTableError, exc.SQLAlchemyError), "NoSuchTableError must subclass SQLAlchemyError"
assert issubclass(exc.DBAPIError, exc.SQLAlchemyError), "DBAPIError must subclass SQLAlchemyError"
assert issubclass(exc.OperationalError, exc.SQLAlchemyError), "OperationalError must subclass SQLAlchemyError"
assert issubclass(exc.IntegrityError, exc.SQLAlchemyError), "IntegrityError must subclass SQLAlchemyError"
assert issubclass(exc.CompileError, exc.SQLAlchemyError), "CompileError must subclass SQLAlchemyError"
assert issubclass(exc.NoReferencedTableError, exc.SQLAlchemyError), "NoReferencedTableError must subclass SQLAlchemyError"
assert issubclass(exc.StatementError, exc.SQLAlchemyError), "StatementError must subclass SQLAlchemyError"

# 4. ORM exception hierarchy
assert issubclass(exc.NoResultFound, exc.SQLAlchemyError), "NoResultFound must subclass SQLAlchemyError"
assert issubclass(exc.MultipleResultsFound, exc.SQLAlchemyError), "MultipleResultsFound must subclass SQLAlchemyError"

# 5. Catching Core statement failure intercepts DBAPIError and preserves .orig
engine = create_engine("sqlite:///:memory:")
caught_core = False
try:
    with engine.connect() as conn:
        conn.execute(sa.text("SELECT * FROM non_existent_table"))
except exc.SQLAlchemyError as e:
    caught_core = True
    assert isinstance(e, exc.DBAPIError), f"Expected DBAPIError, got {type(e)}"
    assert hasattr(e, "orig")
    assert e.orig is not None
assert caught_core, "Failed to intercept Core statement error with SQLAlchemyError"

# 6. Catching ORM scalar query error intercepts NoResultFound
class Base(DeclarativeBase):
    pass

class Item(Base):
    __tablename__ = "items"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(50))

Base.metadata.create_all(engine)

caught_orm = False
try:
    with Session(engine) as session:
        session.execute(select(Item).where(Item.id == 999)).scalar_one()
except exc.SQLAlchemyError as e:
    caught_orm = True
    assert isinstance(e, exc.NoResultFound), f"Expected NoResultFound, got {type(e)}"
assert caught_orm, "Failed to intercept ORM NoResultFound with SQLAlchemyError"

# 7. Catching configuration error intercepts ArgumentError
caught_arg = False
try:
    create_engine("invalid_scheme://")
except exc.SQLAlchemyError as e:
    caught_arg = True
    assert isinstance(e, exc.ArgumentError), f"Expected ArgumentError, got {type(e)}"
assert caught_arg, "Failed to intercept ArgumentError with SQLAlchemyError"

print("CONTRACT PASS: sqlalchemy.exc.SQLAlchemyError verified offline")