From: Tim Penhey <tim@penhey.net>
Date: Thu, 23 Feb 2023 21:17:57 +0000 (+1300)
Subject: Update docstring to suggest raw string (#1186)
X-Git-Tag: rel_1_10_0~10
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b53ec0004a08c40a25a4dbf047c51cd140971a9c;p=thirdparty%2Fsqlalchemy%2Falembic.git

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 4e80a00a..5c089e83 100644
--- 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 808d1fb8..3cdd170d 100644
--- 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 e3feb363..376163b1 100644
--- 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__,
         }