Install & Compatibility
Where this runs
tested against v0.2.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 1.036s · 42.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.2s · import 0.895s · 41MB
41MB installed
● package 41MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
UnifiedAlchemyMagicMock
✓ from mock_alchemy.mocking import UnifiedAlchemyMagicMock
✗ from mock_alchemy import UnifiedAlchemyMagicMock
The main mocking class resides within the `mocking` submodule, not directly under `mock_alchemy`.
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]}")
Errors
Common errors & fixes
TypeError: 'type' object is not subscriptable
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.
fixUpgrade 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'
Trying to use the `.scalar()` method on a mock session with a `mock-alchemy` version older than 0.2.4.
fixUpgrade `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
This error or similar SQLAlchemy API compatibility issues can occur when using SQLAlchemy 2.0+ with `mock-alchemy` versions older than 0.2.6.
fixUpgrade `mock-alchemy` to version 0.2.6 or newer to ensure full compatibility with SQLAlchemy 2.0's API.
Upgrade
Version history
0.2.6latest on PyPI · released Mar 26, 2023
Audit
Dependencies
SQLAlchemyrequiredCore dependency for mocking its objects and API.