Merging upstream version 10.4.2.

Signed-off-by: Daniel Baumann <daniel@debian.org>

pdoc/cli.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+
+from importlib import import_module
+from pathlib import Path
+from unittest import mock
+
+from pdoc.__main__ import cli, parser
+
+# Need this import or else import_module doesn't work
+import sqlglot
+
+
+def mocked_import(*args, **kwargs):
+    """Return a MagicMock if import fails for any reason"""
+    try:
+        return import_module(*args, **kwargs)
+    except Exception:
+        mocked_module = mock.MagicMock()
+        mocked_module.__name__ = args[0]
+        return mocked_module
+
+
+if __name__ == "__main__":
+    # Mock uninstalled dependencies so pdoc can still work
+    with mock.patch("importlib.import_module", side_effect=mocked_import):
+        opts = parser.parse_args()
+        opts.docformat = "google"
+        opts.modules = ["sqlglot"]
+        opts.footer_text = "Copyright (c) 2022 Toby Mao"
+        opts.template_directory = Path(__file__).parent.joinpath("templates").absolute()
+        opts.edit_url = ["sqlglot=https://github.com/tobymao/sqlglot/"]
+
+        with mock.patch("pdoc.__main__.parser", **{"parse_args.return_value": opts}):
+            cli()

pdoc/docs/expressions.md

@@ -0,0 +1,41 @@
+# Expressions
+
+Every AST node in SQLGlot is represented by a subclass of `Expression`. Each such expression encapsulates any necessary context, such as its child expressions, their names, or arg keys, and whether each child expression is optional or not.
+
+Furthermore, the following attributes are common across all expressions:
+
+#### key
+
+A unique key for each class in the `Expression` hierarchy. This is useful for hashing and representing expressions as strings.
+
+#### args
+
+A dictionary used for mapping child arg keys, to the corresponding expressions. A value in this mapping is usually either a single or a list of `Expression` instances, but SQLGlot doesn't impose any constraints on the actual type of the value.
+
+#### arg_types
+
+A dictionary used for mapping arg keys to booleans that determine whether the corresponding expressions are optional or not. Consider the following example:
+
+```python
+class Limit(Expression):
+    arg_types = {"this": False, "expression": True}
+
+```
+
+Here, `Limit` declares that it expects to have one optional and one required child expression, which can be referenced through `this` and `expression`, respectively. The arg keys are generally arbitrary, but there are helper methods for keys like `this`, `expression` and `expressions` that abstract away dictionary lookups and related checks. For this reason, these keys are common throughout SQLGlot's codebase.
+
+#### parent
+
+A reference to the parent expression (may be `None`).
+
+#### arg_key
+
+The arg key an expression is associated with, i.e. the name its parent expression uses to refer to it.
+
+#### comments
+
+A list of comments that are associated with a given expression. This is used in order to preserve comments when transpiling SQL code.
+
+#### type
+
+The data type of an expression, as inferred by SQLGlot's optimizer.

pdoc/templates/module.html.jinja2

@@ -0,0 +1,6 @@
+{% extends "default/module.html.jinja2" %}
+
+{% if module.docstring %}
+    {% macro module_name() %}
+    {% endmacro %}
+{% endif %}