Mock Alchemy

Common errors

• TypeError: 'type' object is not subscriptable

  cause Attempting to run `mock-alchemy` 0.2.0 or newer on Python 2.7 or an unsupported Python 3 version that doesn't fully support type hints.
  fix Upgrade your Python environment to 3.7 or newer. If downgrading `mock-alchemy` is not an option, consider using `mock-alchemy` 0.1.x for Python 2.7 support.

• AttributeError: 'MagicMock' object has no attribute 'scalar'

  cause Trying to use the `.scalar()` method on a mock session with a `mock-alchemy` version older than 0.2.4.
  fix Upgrade `mock-alchemy` to version 0.2.4 or later. For improved `scalar()` behavior, upgrade to 0.2.5 or later.

• TypeError: Class 'Mapper' is not a collection type and is not a mapped class

  cause This error or similar SQLAlchemy API compatibility issues can occur when using SQLAlchemy 2.0+ with `mock-alchemy` versions older than 0.2.6.
  fix Upgrade `mock-alchemy` to version 0.2.6 or newer to ensure full compatibility with SQLAlchemy 2.0's API.

Warnings

• breaking Version 0.2.0 dropped support for Python 2.7 and older Python 3 versions (<3.7). Using `mock-alchemy>=0.2.0` with these Python versions will result in errors.
  Fix: Upgrade your Python interpreter to 3.7 or newer. For projects requiring Python 2.7, use `mock-alchemy` versions <0.2.0 (e.g., `0.1.x`).
• breaking Support for SQLAlchemy 2.0's API changes was fully implemented in version 0.2.6. Using SQLAlchemy 2.0+ with older `mock-alchemy` versions might lead to compatibility issues or unexpected behavior.
  Fix: Ensure `mock-alchemy` is version 0.2.6 or newer when working with SQLAlchemy 2.0+.
• gotcha The `scalar()` method for mocking queries was introduced in `v0.2.4`, and its implementation was improved in `v0.2.5`. Older versions will lack this functionality or have incorrect behavior.
  Fix: Upgrade to `mock-alchemy` version 0.2.5 or later for reliable `scalar()` method mocking.
• gotcha A bug in `get()` that caused it to fail with non-integer singular values was fixed in `v0.2.2`. Prior versions might not correctly handle such queries.
  Fix: Upgrade to `mock-alchemy` version 0.2.2 or later to ensure `get()` works with various singular value types.

Install

• pip install mock-alchemy Install stable version

Imports

• UnifiedAlchemyMagicMock
  wrong:

  from mock_alchemy import UnifiedAlchemyMagicMock

  correct:

  from mock_alchemy.mocking import UnifiedAlchemyMagicMock

  The main mocking class resides within the `mocking` submodule, not directly under `mock_alchemy`.

Quickstart

This quickstart demonstrates how to set up a mock SQLAlchemy session using `UnifiedAlchemyMagicMock`, add mock data, and perform common query operations like `filter`, `first`, `all`, `count`, and `delete` without connecting to a real database. It uses SQLAlchemy 2.0+ declarative syntax for the model.

from mock_alchemy.mocking import UnifiedAlchemyMagicMock
from sqlalchemy.orm import declarative_base, Mapped, mapped_column
from sqlalchemy import String, Integer

# Define a simple SQLAlchemy model using SQLAlchemy 2.0+ syntax
Base = declarative_base()

class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(Integer, primary_key=True)
    name: Mapped[str] = mapped_column(String)

# Create a mock session instance
session = UnifiedAlchemyMagicMock()

# Add some mock data to the session
session.add(User(id=1, name="Alice"))
session.add(User(id=2, name="Bob"))
session.add(User(id=3, name="Charlie"))

# Perform mock queries
user_alice = session.query(User).filter(User.name == "Alice").first()
print(f"Found user by name: {user_alice.name}")

all_users = session.query(User).all()
print(f"All users: {[u.name for u in all_users]}")

user_count = session.query(User).count()
print(f"Total users: {user_count}")

# Simulate a deletion
session.query(User).filter(User.id == 2).delete()
remaining_users = session.query(User).all()
print(f"Users after deletion: {[u.name for u in remaining_users]}")