Typing Stubs for Flask-Migrate

Common errors

• error: Library stubs not installed for "flask_migrate"

  cause The `types-flask-migrate` package is not installed, or `mypy` cannot find it.
  fix Run `pip install types-flask-migrate`. Ensure your `mypy` configuration (if any) correctly points to your environment or `site-packages`.

• error: Module 'flask_migrate' has no attribute 'Migrate' (or similar attribute error for other symbols)

  cause This error typically indicates a version mismatch between `flask-migrate` and its type stubs (`types-flask-migrate`), or a typo in the imported symbol.
  fix Verify that both `flask-migrate` and `types-flask-migrate` are up-to-date by running `pip install --upgrade flask-migrate types-flask-migrate`. Double-check the spelling and casing of the imported symbol.

• error: Cannot find module named 'flask_migrate'

  cause The runtime library `flask-migrate` is not installed in the environment where `mypy` is running, or it's not on the Python path.
  fix Install the actual `flask-migrate` library: `pip install flask-migrate`. `types-flask-migrate` only provides type hints, not the runtime code.

Warnings

• gotcha Type stubs (like `types-flask-migrate`) must match the version of the runtime library (`flask-migrate`) as closely as possible. Significant version mismatches can lead to incorrect type errors or missing type information.
  Fix: Ensure `flask-migrate` and `types-flask-migrate` are up-to-date. If issues persist, check the `typeshed` GitHub issues for specific version compatibility notes.
• gotcha `types-flask-migrate` provides stubs for `flask_migrate`, but it does not include stubs for `Flask-SQLAlchemy` or `SQLAlchemy` directly. You'll likely need `types-flask-sqlalchemy` and `types-sqlalchemy` for full type coverage.
  Fix: Install `types-flask-sqlalchemy` and `types-sqlalchemy` if your project uses them to achieve comprehensive type checking.
• gotcha Type stubs from typeshed are sometimes incomplete for very new features or less common use cases in the underlying library. While generally comprehensive, edge cases might lack full typing.
  Fix: If encountering `mypy` errors due to missing stubs for specific `flask-migrate` features, consider contributing to `typeshed` or using `# type: ignore` as a temporary workaround with a comment explaining why.

Install

• pip install types-flask-migrate Install package

Imports

• Migrate

  from flask_migrate import Migrate

  This is a runtime import from the actual Flask-Migrate library, for which types-flask-migrate provides stubs.
• init

  from flask_migrate import init

  Commonly used Flask-Migrate command functions.

Quickstart

To use `types-flask-migrate`, install it alongside `flask-migrate` and `mypy`. The stubs provide type hints for your code that uses `flask-migrate`. There is no direct runtime import or usage of `types-flask-migrate` itself; it's consumed by type checkers. The example demonstrates a minimal Flask-Migrate setup that `mypy` would then analyze.

import os
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate

# Basic Flask application setup
app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = os.environ.get('DATABASE_URL', 'sqlite:///app.db')
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False
db = SQLAlchemy(app)

# Initialize Flask-Migrate
migrate = Migrate(app, db)

# Define a simple model (for demonstration)
class User(db.Model):
    id: int = db.Column(db.Integer, primary_key=True)
    name: str = db.Column(db.String(128))

# Example usage (not run at runtime, for type checking only)
# def create_db_and_migrate():
#     with app.app_context():
#         db.create_all()
#         # In a real app, you'd run 'flask db migrate' and 'flask db upgrade' via CLI

print('Flask-Migrate types loaded. Run `mypy your_app.py` to check types.')