Update docstring to suggest raw string (#1186)

* Update docstring to suggest raw string

When escaping the `:` for `op.execute` if a normal string is used, you need to escape the backslash, eg. `'\\:colon_value'` or using a raw string.
For the docs I feel it is nicer to show the raw string.

* Update stub documentation

Change-Id: Ia605c6c036fe82cebff9b427333404f1c59ea74d

---------

Co-authored-by: CaselIT <cfederico87@gmail.com>

diff --git a/alembic/op.pyi b/alembic/op.pyi
index 4e80a00aeaf8765ea5f5b8acca58a5aa60022a8d..5c089e83c0335666c92bf986d107d2d469f7d39a 100644 (file)
--- a/alembic/op.pyi
+++ b/alembic/op.pyi
@@ -1009,7 +1009,7 @@ def execute(
     literal SQL string contains a colon, it must be escaped with a
     backslash, as::
 
-       op.execute("INSERT INTO table (foo) VALUES ('\:colon_value')")
+       op.execute(r"INSERT INTO table (foo) VALUES ('\:colon_value')")
 
 
     :param sqltext: Any legal SQLAlchemy expression, including:

diff --git a/alembic/operations/ops.py b/alembic/operations/ops.py
index 808d1fb8c8a300845d51664b70d733f1aaf56ea1..3cdd170d35ede485d9cfdb57e539518601990cf9 100644 (file)
--- a/alembic/operations/ops.py
+++ b/alembic/operations/ops.py
@@ -2388,7 +2388,7 @@ class ExecuteSQLOp(MigrateOperation):
         literal SQL string contains a colon, it must be escaped with a
         backslash, as::
 
-           op.execute("INSERT INTO table (foo) VALUES ('\:colon_value')")
+           op.execute(r"INSERT INTO table (foo) VALUES ('\:colon_value')")
 
 
         :param sqltext: Any legal SQLAlchemy expression, including:

diff --git a/tools/write_pyi.py b/tools/write_pyi.py
index e3feb363096d1ee9a2f3dc8fee0cf040dde4bc97..376163b1d5aada147b4ed62865f90a407db445a7 100644 (file)
--- a/tools/write_pyi.py
+++ b/tools/write_pyi.py
@@ -13,6 +13,7 @@ sys.path.append(str(Path(__file__).parent.parent))
 if True:  # avoid flake/zimports messing with the order
     from alembic.operations.base import Operations
     from alembic.runtime.environment import EnvironmentContext
+    from alembic.runtime.migration import MigrationContext
     from alembic.script.write_hooks import console_scripts
     from alembic.util.compat import inspect_formatargspec
     from alembic.util.compat import inspect_getfullargspec
@@ -40,6 +41,7 @@ TRIM_MODULE = [
     "sqlalchemy.sql.dml.",
 ]
 CONTEXT_MANAGERS = {"op": ["batch_alter_table"]}
+ADDITIONAL_ENV = {"MigrationContext": MigrationContext}
 
 
 def generate_pyi_for_proxy(
@@ -92,6 +94,7 @@ def generate_pyi_for_proxy(
             **sa.sql.schema.__dict__,
             **sa.__dict__,
             **sa.types.__dict__,
+            **ADDITIONAL_ENV,
             **ops.__dict__,
             **module.__dict__,
         }