Add PDOC_ALLOW_EXEC escape hatch, fix #450 (#451)

* add PDOC_ALLOW_EXEC escape hatch, fix #450

* [autofix.ci] apply automated fixes

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

CHANGELOG.md

@@ -5,6 +5,9 @@
  - Fix handling of type annotations in nested classes.
    ([#440](https://github.com/mitmproxy/pdoc/issues/440), [@mhils](https://github.com/mhils))
  - `Doc.type` is now `Doc.kind` to avoid confusion with `builtins.type`.
+ - The new `PDOC_ALLOW_EXEC` environment variable provides an escape hatch for
+   modules that cannot be imported without executing subprocesses.
+   ([#450](https://github.com/mitmproxy/pdoc/issues/450), [@mhils](https://github.com/mhils))
 
 # 2022-09-20: pdoc 12.2.0
 

pdoc/extract.py

@@ -179,7 +179,14 @@ def __init__(self, *args, **kwargs):  # pragma: no cover
                 "git",
             )
         )
-        if not command_allowed:
+        if not command_allowed and os.environ.get("PDOC_ALLOW_EXEC", "") == "":
+            # sys.stderr is patched, so we need to unpatch it for printing a warning.
+            with patch("sys.stderr", new=sys.__stderr__):
+                warnings.warn(
+                    f"Suppressed execution of {args[0]!r} during import. "
+                    f"Set PDOC_ALLOW_EXEC=1 as an environment variable to allow subprocess execution.",
+                    stacklevel=2,
+                )
             kwargs["executable"] = self._noop_exe
         super().__init__(*args, **kwargs)