{"id":2781,"library":"sqlalchemy2-stubs","title":"SQLAlchemy 1.4 Typing Stubs","description":"sqlalchemy2-stubs provides interim PEP-484 typing stubs specifically for the SQLAlchemy 1.4 release series. It is an alpha-level project designed to work with a Mypy extension, replacing the older 'sqlalchemy-stubs' package. The project aims to enhance static type checking for SQLAlchemy 1.4 applications, but it is explicitly incompatible with SQLAlchemy 2.0, which features native inline typing. The current version is 0.0.2a38, and its release cadence is tied to the needs of SQLAlchemy 1.4 typing support.","status":"maintenance","version":"0.0.2a38","language":"en","source_language":"en","source_url":"https://github.com/sqlalchemy/sqlalchemy2-stubs","tags":["typing","stubs","mypy","sqlalchemy","orm","python3"],"install":[{"cmd":"pip install sqlalchemy2-stubs","lang":"bash","label":"Install only stubs"},{"cmd":"pip install 'sqlalchemy[mypy]' sqlalchemy2-stubs","lang":"bash","label":"Install with SQLAlchemy's Mypy extra"}],"dependencies":[{"reason":"These stubs are specifically for SQLAlchemy 1.4.","package":"sqlalchemy>=1.4,<2.0","optional":false},{"reason":"The stubs are designed to work with Mypy for static type checking.","package":"mypy","optional":false}],"imports":[{"note":"This is the typical import path for declarative_base in SQLAlchemy 1.x. In SQLAlchemy 2.0, it's typically 'from sqlalchemy.orm import DeclarativeBase'.","symbol":"declarative_base","correct":"from sqlalchemy.ext.declarative import declarative_base"},{"note":"Standard import for column definition.","symbol":"Column","correct":"from sqlalchemy import Column"},{"note":"Standard import for integer type.","symbol":"Integer","correct":"from sqlalchemy import Integer"},{"note":"Standard import for string type.","symbol":"String","correct":"from sqlalchemy import String"},{"note":"Mapped is part of the ORM module.","wrong":"from sqlalchemy.ext.declarative import Mapped","symbol":"Mapped","correct":"from sqlalchemy.orm import Mapped"}],"quickstart":{"code":"from typing import Optional\nfrom sqlalchemy import create_engine, Column, Integer, String\nfrom sqlalchemy.orm import Mapped, declarative_base, Session\n\nBase = declarative_base()\n\nclass User(Base):\n    __tablename__ = \"users\"\n    id: Mapped[int] = Column(Integer, primary_key=True)\n    name: Mapped[Optional[str]] = Column(String(50))\n    email: Mapped[str] = Column(String(50), nullable=False)\n\n    def __repr__(self) -> str:\n        return f\"<User(id={self.id}, name='{self.name}', email='{self.email}')>\"\n\n# Example usage (not requiring sqlalchemy2-stubs at runtime, but for type checking)\nif __name__ == '__main__':\n    engine = create_engine('sqlite:///:memory:')\n    Base.metadata.create_all(engine)\n\n    with Session(engine) as session:\n        new_user = User(name='Alice', email='alice@example.com')\n        session.add(new_user)\n        session.commit()\n        print(f\"Added user: {new_user}\")\n\n        retrieved_user = session.query(User).filter_by(name='Alice').first()\n        print(f\"Retrieved user: {retrieved_user}\")","lang":"python","description":"This quickstart demonstrates defining a SQLAlchemy 1.4 ORM model with `sqlalchemy2-stubs` compatible type annotations using `Mapped`. The `sqlalchemy2-stubs` package itself does not have runtime code but provides type hints for tools like Mypy. Ensure Mypy is configured to use the SQLAlchemy plugin for full benefits (e.g., in `mypy.ini` or `pyproject.toml`: `[mypy]\nplugins = sqlalchemy.ext.mypy.plugin`)."},"warnings":[{"fix":"Before upgrading to SQLAlchemy 2.0, or if you are using SQLAlchemy 2.0, uninstall `sqlalchemy2-stubs` using `pip uninstall sqlalchemy2-stubs`.","message":"The `sqlalchemy2-stubs` package is explicitly NOT compatible with SQLAlchemy 2.0. Upgrading to SQLAlchemy 2.0 requires manual uninstallation of `sqlalchemy2-stubs` because SQLAlchemy 2.0 includes inline type annotations that conflict with stub packages.","severity":"breaking","affected_versions":"All versions of sqlalchemy2-stubs when used with SQLAlchemy 2.0+"},{"fix":"For SQLAlchemy 1.4, use Mypy versions 1.10.1 or older. For SQLAlchemy 2.0, migrate to its native typing system and remove the Mypy plugin and stubs.","message":"The Mypy plugin associated with `sqlalchemy2-stubs` is deprecated in SQLAlchemy 2.0 and has known compatibility issues with Mypy versions 1.11.0 or greater, with support guaranteed only up to Mypy 1.10.1.","severity":"deprecated","affected_versions":"All versions of sqlalchemy2-stubs (for Mypy plugin compatibility)"},{"fix":"Ensure only one set of SQLAlchemy stubs (`sqlalchemy2-stubs` or `sqlalchemy-stubs`) is installed. For SQLAlchemy 1.4, `sqlalchemy2-stubs` is recommended.","message":"Do not install `sqlalchemy2-stubs` and the older `sqlalchemy-stubs` (from Dropbox) simultaneously. They occupy the same namespace and will cause conflicts and incorrect type checking results.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Maintain a clear separation of SQLAlchemy versions. For projects migrating to SQLAlchemy 2.0, a complete transition away from `sqlalchemy2-stubs` is necessary, and incremental migration with stubs installed is difficult and often problematic.","message":"Mixed environments (e.g., SQLAlchemy 1.x and 2.x codebases, or incremental migration attempts) where `sqlalchemy2-stubs` is present can lead to significant type errors, especially with imports like `declarative_base`.","severity":"gotcha","affected_versions":"All versions when used in mixed environments"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}