"""``mgf.alembic`` — async-aware alembic ``env.py`` helper.

Replaceability (DP-08): the two load-bearing externals — ``alembic`` and
(async) ``sqlalchemy`` — are NOT swappable behind a seam, because this library
is *definitionally* an adapter for them; the "swap recipe" is simply "don't use
``configure_env`` — write your own ``env.py``" (the helper's whole value is
removing that boilerplate). ``mgf-sqlalchemy`` is the paired engine sibling.

Sibling of :mod:`mgf.common` under the ``mgf.*`` namespace. Houses the
async-aware ``configure_env`` helper that previously lived under
``mgf.common.alembic.*`` — extracted at mgf-common v0.30 / mgf-alembic
v0.1 per the federation split plan. Pairs with mgf-sqlalchemy
(extracted in the same release).

Every async-SQLAlchemy + alembic project repeats the same ~40-line
``env.py`` boilerplate:

  - Read the URL from settings (or alembic.ini).
  - Set up the offline path for SQL-emit-only mode.
  - Set up the async online path with ``async_engine_from_config``.
  - Wire ``do_run_migrations`` via ``connection.run_sync``.
  - Configure ``compare_type`` / ``compare_server_default`` for autogen.
  - Apply naming-convention to ``target_metadata``.
  - Plumb ``include_object`` / ``include_schemas`` for extension-table
    filtering (PAPER-22, shipped in mgf-common v0.19).

This module replaces all of that with one call:

.. code-block:: python

    # alembic/env.py
    from mgf.alembic import configure_env
    from myapp.config import MyAppSettings
    from myapp.db.base import Base


    settings = MyAppSettings()
    configure_env(
        database_url=settings.database_url,
        target_metadata=Base.metadata,
    )

That's the entire file. The helper detects offline vs online mode,
runs the migration, disposes the engine cleanly. Async drivers
(asyncpg, aiomysql, aiosqlite) are auto-detected from the URL
prefix; sync drivers fall through the synchronous path.

Install: ``pip install mgf-alembic`` (pulls
``mgf-common`` + ``mgf-sqlalchemy`` + ``alembic>=1.13``).

The helper is **callable-from-env.py**, not framework-shaped. Your
``alembic.ini`` is unchanged; your migrations directory is unchanged;
``alembic upgrade head`` / ``alembic revision --autogenerate`` work
exactly as before.

Closed-box invariant: ``mgf-alembic`` depends on ``mgf-common`` +
``mgf-sqlalchemy`` + ``alembic`` only. Consumers MUST import
``configure_env`` from ``mgf.alembic``, never reach into
``mgf.alembic._env``.
"""

from __future__ import annotations

from mgf.alembic._drift import DriftReport, detect_drift
from mgf.alembic._env import configure_env, run_async_migrations

__all__ = [
    "DriftReport",
    "__version__",
    "configure_env",
    "detect_drift",
    "run_async_migrations",
]

__version__ = "0.4.10"
