From f20b789f00c319bf96c13e35d423ddda9e75336e Mon Sep 17 00:00:00 2001 From: Phillip Cloud <417981+cpcloud@users.noreply.github.com> Date: Wed, 22 May 2024 09:58:06 -0400 Subject: [PATCH] docs: add API docs for operations --- docs/_quarto.yml | 29 ++++++++++++++++++ docs/support_matrix.py | 52 --------------------------------- docs/support_matrix.qmd | 60 ++++++++++++++++++++++++++++++++++++-- ibis/expr/types/generic.py | 2 +- 4 files changed, 88 insertions(+), 55 deletions(-) delete mode 100644 docs/support_matrix.py diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 1dbf6ffaa81c6..5e5065560fe30 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -125,6 +125,7 @@ website: contents: - auto: backends/*.qmd - support_matrix.qmd + - reference/operations.qmd - id: how-to title: "How-to" style: "docked" @@ -506,6 +507,34 @@ quartodoc: - name: NumericValue.point package: ibis.expr.types.numeric + - kind: page + path: operations + package: ibis.expr.operations + summary: + name: Operations + desc: Low level operation classes. Subject to change in non-major releases. + contents: + - analytic + - arrays + - core + - generic + - geospatial + - histograms + - json + - logical + - maps + - numeric + - reductions + - relations + - sortkeys + - strings + - structs + - subqueries + - temporal + - temporal_windows + - udf + - vectorized + - window - kind: page summary: name: Column selectors diff --git a/docs/support_matrix.py b/docs/support_matrix.py deleted file mode 100644 index 0fb11337dac9d..0000000000000 --- a/docs/support_matrix.py +++ /dev/null @@ -1,52 +0,0 @@ -from __future__ import annotations - -import pandas as pd - -import ibis -import ibis.expr.operations as ops - - -def make_support_matrix(): - """Construct the backend operation support matrix data.""" - - from ibis.backends.sql.compiler import ALL_OPERATIONS - - support_matrix_ignored_operations = (ops.ScalarParameter,) - - public_ops = ALL_OPERATIONS.difference(support_matrix_ignored_operations) - - assert public_ops - - support = {"Operation": [f"{op.__module__}.{op.__name__}" for op in public_ops]} - support.update( - (backend, list(map(getattr(ibis, backend).has_operation, public_ops))) - for backend in sorted(ep.name for ep in ibis.util.backend_entry_points()) - ) - - support_matrix = ( - pd.DataFrame(support) - .assign(splits=lambda df: df.Operation.str.findall("[a-zA-Z_][a-zA-Z_0-9]*")) - .assign( - Category=lambda df: df.splits.str[-2], - Operation=lambda df: df.splits.str[-1], - ) - .drop(["splits"], axis=1) - .set_index(["Category", "Operation"]) - .sort_index() - ) - all_visible_ops_count = len(support_matrix) - assert all_visible_ops_count - - coverage = pd.Index( - support_matrix.sum() - .map(lambda n: f"{n} ({round(100 * n / all_visible_ops_count)}%)") - .T - ) - support_matrix.columns = pd.MultiIndex.from_tuples( - list(zip(support_matrix.columns, coverage)), names=("Backend", "API coverage") - ) - return support_matrix - - -if __name__ == "__main__": - print(make_support_matrix()) # noqa: T201 diff --git a/docs/support_matrix.qmd b/docs/support_matrix.qmd index 73b8b45311e23..35060e7a7667c 100644 --- a/docs/support_matrix.qmd +++ b/docs/support_matrix.qmd @@ -19,7 +19,10 @@ varies. ::: {.callout-tip} Backends with low coverage are good places to start contributing! -Each backend implements operations differently, but this is usually very similar to other backends. If you want to start contributing to ibis, it's a good idea to start by adding missing operations to backends that have low operation coverage. +Each backend implements operations differently, but this is usually very +similar to other backends. If you want to start contributing to ibis, it's +a good idea to start by adding missing operations to backends that have low +operation coverage. ::: ::: @@ -58,9 +61,62 @@ dict(value=sql_backends, color="green", icon="database") ## {height=70%} +```{python} +#| echo: false +import pandas as pd + +import ibis +import ibis.expr.operations as ops + + +def make_support_matrix(): + """Construct the backend operation support matrix data.""" + + from ibis.backends.sql.compiler import ALL_OPERATIONS + + support_matrix_ignored_operations = (ops.ScalarParameter,) + + public_ops = ALL_OPERATIONS.difference(support_matrix_ignored_operations) + + assert public_ops + + support = {"Operation": [f"{op.__module__}.{op.__name__}" for op in public_ops]} + support.update( + (backend, list(map(getattr(ibis, backend).has_operation, public_ops))) + for backend in sorted(ep.name for ep in ibis.util.backend_entry_points()) + ) + + def make_link(parts): + module, op = parts[-2:] + return f'{op}' + + support_matrix = ( + pd.DataFrame(support) + .assign(splits=lambda df: df.Operation.str.findall("[a-zA-Z_][a-zA-Z_0-9]*")) + .assign( + Category=lambda df: df.splits.str[-2], + Operation=lambda df: df.splits.map(make_link), + ) + .drop(["splits"], axis=1) + .set_index(["Category", "Operation"]) + .sort_index() + ) + all_visible_ops_count = len(support_matrix) + assert all_visible_ops_count + + coverage = pd.Index( + support_matrix.sum() + .map(lambda n: f"{n} ({round(100 * n / all_visible_ops_count)}%)") + .T + ) + support_matrix.columns = pd.MultiIndex.from_tuples( + list(zip(support_matrix.columns, coverage)), names=("Backend", "API coverage") + ) + return support_matrix +``` + ```{python} from itables import show -from support_matrix import make_support_matrix matrix = make_support_matrix() diff --git a/ibis/expr/types/generic.py b/ibis/expr/types/generic.py index 6b4b66273c18a..5c00c51b0a899 100644 --- a/ibis/expr/types/generic.py +++ b/ibis/expr/types/generic.py @@ -1356,7 +1356,7 @@ def preview( max_rows Maximum number of rows to display max_length - Maximum length for pretty-printed arrays and maps. + Maximum length for pretty-printed arrays and maps. max_string Maximum length for pretty-printed strings. max_depth