{"id":"b356bdafc46446dc","repo":"sqlalchemy/alembic","slug":"script-supports-at-least-python-lower-python-but","errorCode":null,"errorMessage":"Script supports at least python {lower_python} but less than {upper_python} right now.","messagePattern":"Script supports at least python (.+?) but less than (.+?) right now\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"tools/write_pyi.py","lineNumber":70,"sourceCode":"    \"sqlalchemy.sql.schema.\",\n    \"sqlalchemy.sql.selectable.\",\n    \"sqlalchemy.sql.type_api.\",\n    \"typing.\",\n]\nADDITIONAL_ENV = {\n    \"MigrationContext\": MigrationContext,\n    \"AutogenContext\": AutogenContext,\n    \"DefaultImpl\": DefaultImpl,\n    \"MigrationInfo\": MigrationInfo,\n}\n\n\ndef generate_pyi_for_proxy(\n    file_info: FileInfo, destination_path: Path, ignore_output: bool\n):\n    lower_python, upper_python = PYTHON_VERSIONS\n    if sys.version_info < lower_python or sys.version_info >= upper_python:\n        raise RuntimeError(\n            f\"Script supports at least python \"\n            f\"{\".\".join(str(x) for x in lower_python)} \"\n            f\"but less than {\".\".join(str(x) for x in upper_python)} \"\n            \"right now.\"\n        )\n\n    progname = Path(sys.argv[0]).as_posix()\n    # When using an absolute path on windows, this will generate the correct\n    # relative path that shall be written to the top comment of the pyi file.\n    if Path(progname).is_absolute():\n        progname = Path(progname).relative_to(Path().cwd()).as_posix()\n\n    file_info.read_file()\n\n    cls = file_info.target\n    with open(destination_path, \"w\") as buf:\n        file_info.write_before(buf, progname)\n","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/sqlalchemy/alembic/blob/44fb3450330204b222ff05135e1fbbbdb28c44db/tools/write_pyi.py#L52-L88","documentation":"Raised as RuntimeError in generate_pyi_for_proxy (tools/write_pyi.py:70) when the Python interpreter running the .pyi stub-generation tool is outside the supported window defined by PYTHON_VERSIONS ((3,14), (3,16)). The generator inspects type annotations and proxy internals that are version-specific, so running it on an unsupported interpreter would produce incorrect stubs; it refuses instead.","triggerScenarios":"Invoking tools/write_pyi.py (the Alembic maintainer stub-generation script) under Python 3.13 or earlier, or 3.16+, or any version outside [lower_python, upper_python). It is a development/maintainer tool, not part of normal Alembic usage.","commonSituations":"A contributor running the stub generator locally on their system Python which is older than the required dev version; CI using a different Python than the matrix expects; the PYTHON_VERSIONS constant was bumped in a newer Alembic but the local checkout is behind/ahead.","solutions":["Run the script under a supported Python version (install pyenv/uv python 3.14 or 3.15 within the window).","If you maintain a fork, update PYTHON_VERSIONS to match your generator interpreter.","Skip stub regeneration if you are not modifying proxied APIs — the checked-in .pyi files are sufficient.","Use `python3.14 tools/write_pyi.py` (or the in-range version) explicitly rather than the default `python`."],"exampleFix":"# before: running on system python 3.12\npython tools/write_pyi.py  # RuntimeError\n\n# after: use a supported version\npyenv install 3.15\npython3.15 tools/write_pyi.py","handlingStrategy":"validation","validationCode":"import sys\nPYTHON_VERSIONS = (3, 14), (3, 16)  # mirror tools/write_pyi.py\n\ndef python_in_range() -> bool:\n    lo, hi = PYTHON_VERSIONS\n    return lo <= sys.version_info[:2] < hi\n\nif not python_in_range():\n    raise SystemExit('Use Python >=3.14 and <3.16 to run write_pyi.py')","typeGuard":null,"tryCatchPattern":"try:\n    generate_pyi_for_proxy(file_info, dest, ignore_output=False)\nexcept RuntimeError as e:\n    if 'supports at least python' in str(e):\n        print('Install/run a supported Python (3.14 or 3.15) before regenerating stubs.')\n    raise","preventionTips":["Pin the dev/CI Python version to the window declared in PYTHON_VERSIONS.","Use pyenv/uv to install the exact required interpreter.","Only run write_pyi.py when actually changing proxied APIs; rely on committed .pyi otherwise."],"tags":["alembic","tooling","stubs","python-version","maintainer"],"analyzedSha":"44fb3450330204b222ff05135e1fbbbdb28c44db","analyzedAt":"2026-08-04T19:57:10.248Z","schemaVersion":2}