Install & Compatibility
Where this runs
tested against v1.1.0 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ChoiceType
✓ from sqlalchemy_utils_stubs import ChoiceType
✗ from sqlalchemy_utils import ChoiceType
This quickstart demonstrates defining an SQLAlchemy model using `sqlalchemy-utils.ChoiceType` with an Enum. After installing `types-sqlalchemy-utils`, a type checker like MyPy will be able to correctly infer the type of the `role` column, ensuring type safety when assigning or comparing values. The code includes a simple database interaction to illustrate runtime behavior alongside the type-checking benefits.
import sqlalchemy as sa
from sqlalchemy.orm import declarative_base, sessionmaker
from sqlalchemy_utils import ChoiceType
from enum import Enum
from typing import cast
# Define an Enum for choices
class UserRole(Enum):
ADMIN = 'admin'
EDITOR = 'editor'
VIEWER = 'viewer'
# Base for declarative models
Base = declarative_base()
class User(Base):
__tablename__ = 'users'
id = sa.Column(sa.Integer, primary_key=True)
# Use ChoiceType with the Enum; type annotation helps MyPy
role: UserRole = sa.Column(ChoiceType(UserRole, impl=sa.String(20)))
name: str = sa.Column(sa.String(255))
def __repr__(self):
return f"<User(id={self.id}, name='{self.name}', role='{self.role.value}')>"
# Example Usage
if __name__ == "__main__":
# In a real app, use environment variables for connection strings
# e.g., os.environ.get('DATABASE_URL', 'sqlite:///:memory:')
engine = sa.create_engine('sqlite:///:memory:')
Base.metadata.create_all(engine)
Session = sessionmaker(bind=engine)
session = Session()
# Create users with type-safe roles
user1 = User(name='Alice', role=UserRole.ADMIN)
user2 = User(name='Bob', role=UserRole.VIEWER)
session.add_all([user1, user2])
session.commit()
# Query users
admin_user = session.query(User).filter_by(role=UserRole.ADMIN).first()
if admin_user:
# MyPy would know admin_user.role is UserRole due to type stubs
print(f"Found admin: {admin_user}")
print(f"Admin role type: {type(admin_user.role)}") # Should be <enum 'UserRole'>
# Access enum value (e.g., for comparison or display)
if admin_user.role == UserRole.ADMIN:
print("It's an admin!")
session.close()
# To run type checking with MyPy:
# 1. Save the code above as `app.py`.
# 2. Ensure `sqlalchemy`, `sqlalchemy-utils`, and `types-sqlalchemy-utils` are installed.
# 3. Run: `mypy app.py`
Upgrade
Version history
1.1.0latest on PyPI · released May 13, 2024
Audit
Dependencies
sqlalchemy-utilsrequiredThis package provides type stubs for `sqlalchemy-utils`, which must be installed separately for runtime functionality.
sqlalchemy2-stubsrequiredProvides core type stubs for SQLAlchemy itself, which `types-sqlalchemy-utils` builds upon.
sqlalchemyrequired`sqlalchemy-utils` is built on SQLAlchemy, so it's an implicit dependency.