Setup PyDough AST backreferences and hidden backreferences

pydough/pydough_ast/collections/__init__.py

@@ -9,13 +9,11 @@
     "GlobalContext",
     "CollectionAccess",
     "SubCollection",
-    "CompoundSubCollection",
 ]
 
 from .collection_ast import PyDoughCollectionAST
 from .table_collection import TableCollection
 from .sub_collection import SubCollection
-from .compound_sub_collection import CompoundSubCollection
 from .calc import Calc
 from .global_context import GlobalContext
 from .collection_access import CollectionAccess

pydough/pydough_ast/collections/back_reference_collection.py

@@ -0,0 +1,71 @@
+"""
+TODO: add file-level docstring
+"""
+
+__all__ = ["BackReferenceCollection"]
+
+from typing import Dict, Tuple
+from pydough.pydough_ast.abstract_pydough_ast import PyDoughAST
+from .collection_ast import PyDoughCollectionAST
+from pydough.pydough_ast.errors import PyDoughASTException
+from .collection_access import CollectionAccess
+
+
+class BackReferenceCollection(CollectionAccess):
+    """
+    The AST node implementation class representing a subcollection of an
+    ancestor collection.
+    """
+
+    def __init__(
+        self,
+        parent: PyDoughCollectionAST,
+        term_name: str,
+        back_levels: int,
+    ):
+        if not (isinstance(back_levels, int) and back_levels > 0):
+            raise PyDoughASTException(
+                f"Expected number of levels in BACK to be a positive integer, received {back_levels!r}"
+            )
+        self._term_name: str = term_name
+        self._back_levels: int = back_levels
+        for _ in range(back_levels):
+            self._ancestor = self._ancestor.ancestor_context
+            if self._ancestor is None:
+                msg: str = "1 level" if back_levels == 1 else f"{back_levels} levels"
+                raise PyDoughASTException(
+                    f"Cannot reference back {msg} above {parent!r}"
+                )
+        self._collection_access: CollectionAccess = self._ancestor.get_term(term_name)
+        super().__init__(self._collection_access.collection, parent)
+
+    @property
+    def back_levels(self) -> int:
+        """
+        The number of levels upward that the backreference refers to.
+        """
+        return self._back_levels
+
+    @property
+    def term_name(self) -> str:
+        """
+        The name of the subcollection being accessed from the ancestor.
+        """
+        return self._term_name
+
+    @property
+    def collection_access(self) -> CollectionAccess:
+        """
+        The collection access property of the ancestor that BACK points to.
+        """
+        return self._collection_access
+
+    @property
+    def properties(self) -> Dict[str, Tuple[int | None, PyDoughAST]]:
+        return self.collection_access.properties
+
+    def to_string(self) -> str:
+        return f"BACK({self.back_levels}).{self._subcollection.to_string()}"
+
+    def to_tree_form(self) -> None:
+        raise NotImplementedError

pydough/pydough_ast/collections/compound_sub_collection.py

@@ -12,6 +12,10 @@
 from pydough.pydough_ast.abstract_pydough_ast import PyDoughAST
 from .collection_ast import PyDoughCollectionAST
 from .sub_collection import SubCollection
+from .hidden_back_reference_collection import HiddenBackReferenceCollection
+from pydough.pydough_ast.expressions.hidden_back_reference_expression import (
+    HiddenBackReferenceExpression,
+)
 
 
 class CompoundSubCollection(SubCollection):
@@ -160,6 +164,24 @@ def properties(self) -> Dict[str, Tuple[int | None, PyDoughAST]]:
                 raise PyDoughASTException(
                     f"Undefined inherited properties: {undefined_inherited}"
                 )
+            for alias, (location, original_name) in self._inheritance_sources.items():
+                calc_idx, expr = self._properties[alias]
+                ancestor: PyDoughCollectionAST = self._subcollection_chain[location]
+                back_levels: int = len(self.subcollection_chain) - location
+                if isinstance(expr, PyDoughCollectionAST):
+                    self._properties[alias] = (
+                        calc_idx,
+                        HiddenBackReferenceCollection(
+                            self, ancestor, alias, original_name, back_levels
+                        ),
+                    )
+                else:
+                    self._properties[alias] = (
+                        calc_idx,
+                        HiddenBackReferenceExpression(
+                            self, ancestor, alias, original_name, back_levels
+                        ),
+                    )
         return self._properties
 
     def to_tree_form(self) -> None:

pydough/pydough_ast/collections/hidden_back_reference_collection.py

@@ -0,0 +1,48 @@
+"""
+TODO: add file-level docstring
+"""
+
+__all__ = ["HiddenBackReferenceCollection"]
+
+
+from .collection_ast import PyDoughCollectionAST
+from .back_reference_collection import BackReferenceCollection
+from .collection_access import CollectionAccess
+
+
+class HiddenBackReferenceCollection(BackReferenceCollection):
+    """
+    The AST node implementation class representing a subcollection of an
+    ancestor collection.
+    """
+
+    def __init__(
+        self,
+        compound: PyDoughCollectionAST,
+        ancestor: PyDoughCollectionAST,
+        alias: str,
+        term_name: str,
+        back_levels: int,
+    ):
+        self._term_name: str = term_name
+        self._back_levels: int = back_levels
+        self._ancestor: PyDoughCollectionAST = ancestor
+        self._subcollection: PyDoughCollectionAST = self._ancestor.get_term(term_name)
+        self._alias: str = alias
+        self._collection_access: CollectionAccess = self._ancestor.get_term(term_name)
+        super(BackReferenceCollection, self).__init__(
+            self._collection_access.collection, ancestor
+        )
+
+    @property
+    def alias(self) -> str:
+        """
+        The alias that the back reference uses.
+        """
+        return self._alias
+
+    def to_string(self) -> str:
+        return f"{self.parent.to_string()}.{self.alias}"
+
+    def to_tree_string(self) -> str:
+        raise NotImplementedError

pydough/pydough_ast/expressions/__init__.py

@@ -8,10 +8,12 @@
     "Literal",
     "ExpressionFunctionCall",
     "Reference",
+    "BackReferenceExpression",
 ]
 
 from .expression_ast import PyDoughExpressionAST
 from .column_property import ColumnProperty
 from .literal import Literal
 from .expression_function_call import ExpressionFunctionCall
 from .reference import Reference
+from .back_reference_expression import BackReferenceExpression

pydough/pydough_ast/expressions/back_reference_expression.py

@@ -0,0 +1,76 @@
+"""
+TODO: add file-level docstring
+"""
+
+__all__ = ["BackReferenceExpression"]
+
+from . import PyDoughExpressionAST
+from pydough.types import PyDoughType
+from pydough.pydough_ast.collections import PyDoughCollectionAST
+from pydough.pydough_ast.errors import PyDoughASTException
+from .reference import Reference
+
+
+class BackReferenceExpression(Reference):
+    """
+    The AST node implementation class representing a reference to a term in
+    the ancestor context.
+    """
+
+    def __init__(
+        self, collection: PyDoughCollectionAST, term_name: str, back_levels: int
+    ):
+        if not (isinstance(back_levels, int) and back_levels > 0):
+            raise PyDoughASTException(
+                f"Expected number of levels in BACK to be a positive integer, received {back_levels!r}"
+            )
+        self._collection: PyDoughCollectionAST = collection
+        self._term_name: str = term_name
+        self._back_levels: int = back_levels
+        self._ancestor: PyDoughCollectionAST = collection
+        for _ in range(back_levels):
+            self._ancestor = self._ancestor.ancestor_context
+            if self._ancestor is None:
+                msg: str = "1 level" if back_levels == 1 else f"{back_levels} levels"
+                raise PyDoughASTException(
+                    f"Cannot reference back {msg} above {collection!r}"
+                )
+        self._expression: PyDoughExpressionAST = self._ancestor.get_term(term_name)
+
+    @property
+    def back_levels(self) -> int:
+        """
+        The number of levels upward that the backreference refers to.
+        """
+        return self._back_levels
+
+    @property
+    def ancestor(self) -> PyDoughCollectionAST:
+        """
+        The specific ancestor collection that the ancestor refers to.
+        """
+        return self._ancestor
+
+    @property
+    def expression(self) -> PyDoughExpressionAST:
+        """
+        The original expression that the reference refers to.
+        """
+        return self._expression
+
+    @property
+    def pydough_type(self) -> PyDoughType:
+        return self.expression.pydough_type
+
+    @property
+    def is_aggregation(self) -> bool:
+        return self.expression.is_aggregation
+
+    def requires_enclosing_parens(self, parent: PyDoughExpressionAST) -> bool:
+        return False
+
+    def to_string(self) -> str:
+        return f"BACK({self.back_levels}).{self.term_name}"
+
+    def equals(self, other: "BackReferenceExpression") -> bool:
+        return super().equals(other) and self.ancestor.equals(other.ancestor)

pydough/pydough_ast/expressions/hidden_back_reference_expression.py

@@ -0,0 +1,42 @@
+"""
+TODO: add file-level docstring
+"""
+
+__all__ = ["HiddenBackReferenceExpression"]
+
+from . import PyDoughExpressionAST
+from pydough.pydough_ast.collections import PyDoughCollectionAST
+from .back_reference_expression import BackReferenceExpression
+
+
+class HiddenBackReferenceExpression(BackReferenceExpression):
+    """
+    The AST node implementation class representing a reference to a term in
+    the ancestor context through the lens of a compound relationship's
+    inherited properties.
+    """
+
+    def __init__(
+        self,
+        collection: PyDoughCollectionAST,
+        ancestor: PyDoughCollectionAST,
+        alias: str,
+        term_name: str,
+        back_levels: int,
+    ):
+        self._collection: PyDoughCollectionAST = collection
+        self._alias: str = alias
+        self._term_name: str = term_name
+        self._back_levels: int = back_levels
+        self._ancestor: PyDoughCollectionAST = ancestor
+        self._expression: PyDoughExpressionAST = self._ancestor.get_term(term_name)
+
+    @property
+    def alias(self) -> str:
+        """
+        The alias that the back reference uses.
+        """
+        return self._alias
+
+    def to_string(self) -> str:
+        return f"HiddenBackReferenceExpression[{self.back_levels}:{self.term_name}]"

pydough/pydough_ast/node_builder.py

@@ -19,6 +19,7 @@
     ExpressionFunctionCall,
     ColumnProperty,
     Reference,
+    BackReferenceExpression,
 )
 from .pydough_operators import PyDoughOperatorAST, builtin_registered_operators
 from .errors import PyDoughASTException
@@ -132,6 +133,28 @@ def build_reference(self, collection: PyDoughCollectionAST, name: str) -> Refere
         """
         return Reference(collection, name)
 
+    def build_back_reference_expression(
+        self, collection: PyDoughCollectionAST, name: str, levels: int
+    ) -> Reference:
+        """
+        Creates a new reference to an expression from an ancestor collection.
+
+        Args:
+            `collection`: the collection that the back reference comes from.
+            `name`: the name of the expression being referenced.
+            `levels`: the number of levels back from `collection` the reference
+            refers to.
+
+        Returns:
+            The newly created PyDough Back Reference.
+
+        Raises:
+            `PyDoughASTException`: if `name` does not refer to an expression in
+            the ancestor collection, or the collection does not have `levels`
+            many ancestors.
+        """
+        return BackReferenceExpression(collection, name, levels)
+
     def build_global_context(self) -> GlobalContext:
         """
         Creates a new global context for the graph.