From 7a2201963d5b03bd1828d350ccaecb4eda30d30c Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Wed, 4 Jan 2023 08:24:08 +0100
Subject: Merging upstream version 10.4.2.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 pdoc/cli.py                       | 34 ++++++++++++++++++++++++++++++++
 pdoc/docs/expressions.md          | 41 +++++++++++++++++++++++++++++++++++++++
 pdoc/templates/module.html.jinja2 |  6 ++++++
 3 files changed, 81 insertions(+)
 create mode 100755 pdoc/cli.py
 create mode 100644 pdoc/docs/expressions.md
 create mode 100644 pdoc/templates/module.html.jinja2

(limited to 'pdoc')

diff --git a/pdoc/cli.py b/pdoc/cli.py
new file mode 100755
index 0000000..72a986d
--- /dev/null
+++ b/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()
diff --git a/pdoc/docs/expressions.md b/pdoc/docs/expressions.md
new file mode 100644
index 0000000..c82674b
--- /dev/null
+++ b/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.
diff --git a/pdoc/templates/module.html.jinja2 b/pdoc/templates/module.html.jinja2
new file mode 100644
index 0000000..e37ae01
--- /dev/null
+++ b/pdoc/templates/module.html.jinja2
@@ -0,0 +1,6 @@
+{% extends "default/module.html.jinja2" %}
+
+{% if module.docstring %}
+    {% macro module_name() %}
+    {% endmacro %}
+{% endif %}
-- 
cgit v1.2.3