Better names for utility functions.

Author: gitosaurus

src/nested_pandas/nestedframe/core.py

@@ -16,7 +16,7 @@
 from nested_pandas.series.dtype import NestedDtype
 
 from ..series.packer import pack_sorted_df_into_struct
-from .utils import check_expr_nesting
+from .utils import extract_nest_names
 
 
 class NestedPandasExprVisitor(PandasExprVisitor):
@@ -509,7 +509,7 @@ def query(self, expr: str, *, inplace: bool = False, **kwargs) -> NestedFrame |
         # At present, the query expression must be either entirely within a
         # single nest, or have nothing but base columns.  Mixed structures are not
         # supported, so preflight the expression.
-        nest_names = check_expr_nesting(expr)
+        nest_names = extract_nest_names(expr)
         if len(nest_names) > 1:
             raise ValueError("Queries cannot target multiple structs/layers, write a separate query for each")
         result = self.eval(expr, **kwargs)

src/nested_pandas/nestedframe/utils.py

@@ -4,17 +4,20 @@
 import ast
 
 
-def _actionable_splits(parents: list[ast.expr], node: ast.expr | None) -> dict[str, list]:
+def _subexprs_by_nest(parents: list[ast.expr], node: ast.expr | None) -> dict[str, list]:
     """
-    Given an expression which contains references to both base and nested columns,
-    return a dictionary of the sub-expressions that should be evaluated independently.
-    The key of the dictionary is the name of the nested column, and will be a blank
-    string in the case of base columns.  The value is a list of the parent nodes
-    that lead to sub-expressions that can be evaluated successfully.
+    Given an expression which contains references to both base and nested
+    columns, return a dictionary of the sub-expressions that should be
+    evaluated independently, keyed by nesting context.
 
-    While this is not in use today for automatically splitting expressions, it can
-    be used to detect whether an expression is suitably structured for evaluation:
-    the returned dictionary should have a single key.
+    The key of the dictionary is the name of the nested column, and will
+    be a blank string in the case of base columns.  The value is a list
+    of the parent nodes that lead to sub-expressions that can be evaluated
+    successfully.
+
+    While this is not in use today for automatically splitting expressions,
+    it can be used to detect whether an expression is suitably structured
+    for evaluation: the returned dictionary should have a single key.
     """
     if not isinstance(node, ast.expr):
         return {}
@@ -28,8 +31,8 @@ def _actionable_splits(parents: list[ast.expr], node: ast.expr | None) -> dict[s
         + getattr(node, "comparators", [])
     )
     result: dict[str, list] = {}
-    for s in sources:
-        child = _actionable_splits(parents, s)
+    for source in sources:
+        child = _subexprs_by_nest(parents, source)
         for k, v in child.items():
             result.setdefault(k, []).append(v)
     # After a complete traversal across sources, check for any necessary splits.
@@ -47,12 +50,12 @@ def _actionable_splits(parents: list[ast.expr], node: ast.expr | None) -> dict[s
     return result
 
 
-def check_expr_nesting(expr: str) -> set[str]:
+def extract_nest_names(expr: str) -> set[str]:
     """
     Given a string expression, parse it and visit the resulting AST, surfacing
     the nesting types.  The purpose is to identify expressions that attempt
     to mix base and nested columns, or columns from two different nests.
     """
     expr_tree = ast.parse(expr, mode="eval").body
-    separable = _actionable_splits([], expr_tree)
+    separable = _subexprs_by_nest([], expr_tree)
     return set(separable.keys())

tests/nested_pandas/utils/test_utils.py

@@ -2,7 +2,7 @@
 import pandas as pd
 import pytest
 from nested_pandas import NestedFrame
-from nested_pandas.nestedframe.utils import check_expr_nesting
+from nested_pandas.nestedframe.utils import extract_nest_names
 from nested_pandas.utils import count_nested
 
 
@@ -52,16 +52,16 @@ def test_check_expr_nesting():
     used to ensure that an expression-based query does not try to combine base and nested
     sub-expressions.
     """
-    assert check_expr_nesting("a > 2 & nested.c > 1") == {"", "nested"}
-    assert check_expr_nesting("(nested.c > 1) and (nested.d>2)") == {"nested"}
-    assert check_expr_nesting("-1.52e-5 < abc < 35.2e2") == {""}
-    assert check_expr_nesting("(n.a > 1) and ((b + c) > (d - 1e-8)) or n.q > c") == {"n", ""}
+    assert extract_nest_names("a > 2 & nested.c > 1") == {"", "nested"}
+    assert extract_nest_names("(nested.c > 1) and (nested.d>2)") == {"nested"}
+    assert extract_nest_names("-1.52e-5 < abc < 35.2e2") == {""}
+    assert extract_nest_names("(n.a > 1) and ((b + c) > (d - 1e-8)) or n.q > c") == {"n", ""}
 
-    assert check_expr_nesting("a.b > 2 & c.d < 5") == {"a", "c"}
+    assert extract_nest_names("a.b > 2 & c.d < 5") == {"a", "c"}
 
-    assert check_expr_nesting("a>3") == {""}
-    assert check_expr_nesting("a > 3") == {""}
-    assert check_expr_nesting("test.a>5&b==2") == {"test", ""}
-    assert check_expr_nesting("test.a > 5 & b == 2") == {"test", ""}
-    assert check_expr_nesting("(a.b > 3)&(a.c == 'f')") == {"a"}
-    assert check_expr_nesting("(a.b > 3) & (a.c == 'f')") == {"a"}
+    assert extract_nest_names("a>3") == {""}
+    assert extract_nest_names("a > 3") == {""}
+    assert extract_nest_names("test.a>5&b==2") == {"test", ""}
+    assert extract_nest_names("test.a > 5 & b == 2") == {"test", ""}
+    assert extract_nest_names("(a.b > 3)&(a.c == 'f')") == {"a"}
+    assert extract_nest_names("(a.b > 3) & (a.c == 'f')") == {"a"}