generate .pyi files for proxied classes

Stub .pyi files have been added for the "dynamically"
generated Alembic modules ``alembic.op`` and ``alembic.context``, which
include complete function signatures and docstrings, so that the functions
in these namespaces will have both IDE support (vscode, pycharm, etc) as
well as support for typing tools like Mypy. The files themselves are
statically generated from their source functions within the source tree.

Still not available is sphinx autodoc from the .pyi file.  so
we might want to further modify this to write into the .py directly.

if we do *that*, we could almost get rid of ModuleClsProxy and
just generate proxying methods fully in op.py.  however, this won't work
for the "extending ops" use case.

Change-Id: I3f084040de25ed3f8e92a4e9d0bb83d69b78eac6

1 files changed, 52 insertions, 0 deletions

diff --git a/tests/test_stubs.py b/tests/test_stubs.py
new file mode 100644
index 0000000..c5186c3
--- /dev/null
+++ b/tests/test_stubs.py
@@ -0,0 +1,52 @@
+from pathlib import Path
+import subprocess
+import sys
+
+import alembic
+from alembic.testing import eq_
+from alembic.testing import skip_if
+from alembic.testing import TestBase
+
+_home = Path(__file__).parent.parent
+
+
+def requirements():
+    try:
+        import black  # noqa
+        import zimports  # noqa
+
+        return False
+    except Exception:
+        return True
+
+
+def run_command(file):
+    res = subprocess.run(
+        [
+            sys.executable,
+            str((_home / "tools" / "write_pyi.py").relative_to(_home)),
+            "--stdout",
+            "--file",
+            file,
+        ],
+        stdout=subprocess.PIPE,
+        cwd=_home,
+        encoding="utf-8",
+    )
+    return res
+
+
+class TestStubFiles(TestBase):
+    @skip_if(requirements, "black and zimports are required for this test")
+    def test_op_pyi(self):
+        res = run_command("op")
+        generated = res.stdout
+        expected = Path(alembic.__file__).parent / "op.pyi"
+        eq_(generated, expected.read_text())
+
+    @skip_if(requirements, "black and zimports are required for this test")
+    def test_context_pyi(self):
+        res = run_command("context")
+        generated = res.stdout
+        expected = Path(alembic.__file__).parent / "context.pyi"
+        eq_(generated, expected.read_text())