Wrong type for sqltext argument of op.execute

[lanzz]

Describe the bug
Documentation for op.execute describes the sqltext argument thus:

Parameters: sqltext – Any legal SQLAlchemy expression, including:

• a string
• a sqlalchemy.sql.expression.text() construct.
• a sqlalchemy.sql.expression.insert() construct.
• a sqlalchemy.sql.expression.update(), sqlalchemy.sql.expression.insert(), or sqlalchemy.sql.expression.delete() construct.
• Any “executable” described in SQLAlchemy Core documentation, noting that no result set is returned.

But the sqltext argument is actually declared as sqltext: str | TextClause | Update — TextClause and Update are the only SQL expressions it is typed to accept, and any attempt to use any other expression type (e.g. an Insert or Delete) will cause mypy to not validate the call, and IDE typecheckers (e.g. VS Code's Pylance) to highlight an error.

Also, sqlalchemy.sql.expression.insert() is listed once as its own bullet point, and a second time in a separate bullet point, together with ...update() and ...delete().

Expected behavior
op.execute should be declared to accept all of the documented types of SQL expressions. Using expressions documented as acceptable should not produce mypy errors.

To Reproduce

# in migration script:
...
def upgrade() -> None:
    table = op.create_table(...)
    op.execute(table.insert().values(...))
...

Error

$ mypy alembic/versions/...version_filename....py 
...version_filename....py:52: error: Argument 1 to "execute" has incompatible type "Insert"; expected "str | TextClause | Update"  [arg-type]
Found 1 error in 1 file (checked 1 source file)

Versions.

• OS: macOS 13.4.1
• Python: 3.11.4
• Alembic: 1.11.1
• SQLAlchemy: 2.0.19
• Database: irrelevant
• DBAPI: irrelevant

Have a nice day!

[zzzeek]

cc @CaselIT that annotation looks like it was generated from a tool of some kind, it's completely wrong

[CaselIT]

it was generated from the test in the initial typing of alembic, so it's most likely not really correct :)

[sqla-tester]

Mihail Milushev has proposed a fix for this issue in the main branch:

Accept insert and delete expressions in op.execute https://gerrit.sqlalchemy.org/c/sqlalchemy/alembic/+/4835

[sqla-tester]

Mihail Milushev has proposed a fix for this issue in the main branch:

Improve typing of op.execute https://gerrit.sqlalchemy.org/c/sqlalchemy/alembic/+/4835