{"id":4830,"library":"types-sqlalchemy-utils","title":"Type Stubs for SQLAlchemy-Utils","description":"This package provides static type annotations for the `sqlalchemy-utils` library, enabling tools like MyPy to perform comprehensive type checking on code that uses `sqlalchemy-utils`'s custom data types and utilities. It currently covers various functions and types, though it is a partial stub package. The library maintains an active, albeit not rapid, release cadence, with the latest version (1.2.0) released in January 2026.","status":"active","version":"1.2.0","language":"en","source_language":"en","source_url":"https://github.com/cex-solutions/types-sqlalchemy-utils","tags":["type-stubs","sqlalchemy","typing","mypy","sqlalchemy-utils"],"install":[{"cmd":"pip install types-sqlalchemy-utils","lang":"bash","label":"Install"}],"dependencies":[{"reason":"This package provides type stubs for `sqlalchemy-utils`, which must be installed separately for runtime functionality.","package":"sqlalchemy-utils","optional":false},{"reason":"Provides core type stubs for SQLAlchemy itself, which `types-sqlalchemy-utils` builds upon.","package":"sqlalchemy2-stubs","optional":false},{"reason":"`sqlalchemy-utils` is built on SQLAlchemy, so it's an implicit dependency.","package":"sqlalchemy","optional":false}],"imports":[{"note":"Type stubs are not imported directly; they augment types for the `sqlalchemy-utils` library's symbols.","symbol":"ChoiceType","correct":"from sqlalchemy_utils import ChoiceType"},{"note":"Type stubs for `CountryType` (and others like `PhoneNumberType`) are provided for direct imports from `sqlalchemy_utils`.","symbol":"CountryType","correct":"from sqlalchemy_utils import CountryType"}],"quickstart":{"code":"import sqlalchemy as sa\nfrom sqlalchemy.orm import declarative_base, sessionmaker\nfrom sqlalchemy_utils import ChoiceType\nfrom enum import Enum\nfrom typing import cast\n\n# Define an Enum for choices\nclass UserRole(Enum):\n    ADMIN = 'admin'\n    EDITOR = 'editor'\n    VIEWER = 'viewer'\n\n# Base for declarative models\nBase = declarative_base()\n\nclass User(Base):\n    __tablename__ = 'users'\n    id = sa.Column(sa.Integer, primary_key=True)\n    # Use ChoiceType with the Enum; type annotation helps MyPy\n    role: UserRole = sa.Column(ChoiceType(UserRole, impl=sa.String(20)))\n    name: str = sa.Column(sa.String(255))\n\n    def __repr__(self):\n        return f\"<User(id={self.id}, name='{self.name}', role='{self.role.value}')>\"\n\n# Example Usage\nif __name__ == \"__main__\":\n    # In a real app, use environment variables for connection strings\n    # e.g., os.environ.get('DATABASE_URL', 'sqlite:///:memory:')\n    engine = sa.create_engine('sqlite:///:memory:')\n    Base.metadata.create_all(engine)\n    Session = sessionmaker(bind=engine)\n    session = Session()\n\n    # Create users with type-safe roles\n    user1 = User(name='Alice', role=UserRole.ADMIN)\n    user2 = User(name='Bob', role=UserRole.VIEWER)\n    \n    session.add_all([user1, user2])\n    session.commit()\n\n    # Query users\n    admin_user = session.query(User).filter_by(role=UserRole.ADMIN).first()\n    if admin_user:\n        # MyPy would know admin_user.role is UserRole due to type stubs\n        print(f\"Found admin: {admin_user}\")\n        print(f\"Admin role type: {type(admin_user.role)}\") # Should be <enum 'UserRole'>\n        # Access enum value (e.g., for comparison or display)\n        if admin_user.role == UserRole.ADMIN:\n            print(\"It's an admin!\")\n\n    session.close()\n\n# To run type checking with MyPy:\n# 1. Save the code above as `app.py`.\n# 2. Ensure `sqlalchemy`, `sqlalchemy-utils`, and `types-sqlalchemy-utils` are installed.\n# 3. Run: `mypy app.py`","lang":"python","description":"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."},"warnings":[{"fix":"Refer to the `types-sqlalchemy-utils` GitHub repository for current coverage and consider contributing missing stubs.","message":"This is a partial stub package, meaning it does not cover all functions and objects available in the `sqlalchemy-utils` library. Type checking might not be fully comprehensive for all features.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For SQLAlchemy 2.0+, `types-sqlalchemy-utils` should work seamlessly with the new typing system and `sqlalchemy2-stubs`. If using older SQLAlchemy versions, consult `sqlalchemy-stubs` documentation for compatibility.","message":"The official SQLAlchemy MyPy plugin for versions 1.x is deprecated in SQLAlchemy 2.0 and later, where an all-new typing system is featured. Ensure compatibility with your SQLAlchemy version. `types-sqlalchemy-utils` relies on `sqlalchemy2-stubs` for core SQLAlchemy typing.","severity":"breaking","affected_versions":"SQLAlchemy 2.0+"},{"fix":"Always import classes and functions from `sqlalchemy_utils` (e.g., `from sqlalchemy_utils import ChoiceType`), not `types_sqlalchemy_utils`.","message":"This package provides type annotations and is not meant for direct import in your application code. You should import actual components from the `sqlalchemy-utils` library. `types-sqlalchemy-utils` works in the background with your type checker to provide static analysis.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure both `pip install sqlalchemy-utils` and `pip install types-sqlalchemy-utils` are executed.","message":"The `sqlalchemy-utils` library itself must be installed separately at runtime for your application to function. `types-sqlalchemy-utils` only provides static type information.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}