Add error handling class that can be subclassed to customize error messages (#389)

Resolves #388. Also heavily refactors a lot of the error-related code, including moving all of the exception utilities/classes to a common module, and removing the `.with_xxx` patterns (unnecessarily) being used for QDAG nodes.

Author: knassre-bodo

pydough/configs/pydough_configs.py

@@ -7,6 +7,8 @@
 from enum import Enum
 from typing import Any, Generic, TypeVar
 
+from pydough.errors import PyDoughSessionException
+
 T = TypeVar("T")
 
 
@@ -126,5 +128,5 @@ class PyDoughConfigs:
 
     def __setattr__(self, name: str, value: Any) -> None:
         if name not in dir(self):
-            raise AttributeError(f"Unrecognized PyDough config name: {name}")
+            raise PyDoughSessionException(f"Unrecognized PyDough config name: {name}")
         super().__setattr__(name, value)

pydough/configs/session.py

@@ -5,6 +5,7 @@
 - The active metadata graph.
 - Any PyDough configuration for function behavior.
 - Backend information (SQL dialect, Database connection, etc.)
+- The error builder used to create and format exceptions
 
 In the future this session will also contain other information
 such as any User Defined registration for additional backend
@@ -24,6 +25,7 @@
     empty_connection,
     load_database_context,
 )
+from pydough.errors import PyDoughErrorBuilder
 from pydough.metadata import GraphMetadata, parse_json_metadata_from_file
 
 from .pydough_configs import PyDoughConfigs
@@ -47,6 +49,7 @@ def __init__(self) -> None:
         self._database: DatabaseContext = DatabaseContext(
             connection=empty_connection, dialect=DatabaseDialect.ANSI
         )
+        self._error_builder: PyDoughErrorBuilder = PyDoughErrorBuilder()
 
     @property
     def metadata(self) -> GraphMetadata | None:
@@ -108,6 +111,26 @@ def database(self, context: DatabaseContext) -> None:
         """
         self._database = context
 
+    @property
+    def error_builder(self) -> PyDoughErrorBuilder:
+        """
+        Get the active error builder.
+
+        Returns:
+           The active error builder.
+        """
+        return self._error_builder
+
+    @error_builder.setter
+    def error_builder(self, builder: PyDoughErrorBuilder) -> None:
+        """
+        Set the active error builder context.
+
+        Args:
+            The error builder to set.
+        """
+        self._error_builder = builder
+
     def connect_database(self, database_name: str, **kwargs) -> DatabaseContext:
         """
         Create a new DatabaseContext and register it in the session. This returns

pydough/conversion/hybrid_translator.py

@@ -9,6 +9,7 @@
 import pydough.pydough_operators as pydop
 from pydough.configs import PyDoughConfigs
 from pydough.database_connectors import DatabaseDialect
+from pydough.errors import PyDoughSQLException
 from pydough.metadata import (
     CartesianProductMetadata,
     GeneralJoinMetadata,
@@ -810,7 +811,7 @@ def rewrite_quantile_call(
             or not isinstance(expr.args[1].literal.value, (int, float))
             or not (0.0 <= float(expr.args[1].literal.value) <= 1.0)
         ):
-            raise ValueError(
+            raise PyDoughSQLException(
                 f"Expected second argument to QUANTILE to be a numeric literal between 0 and 1, instead received {expr.args[1]!r}"
             )
 

pydough/conversion/hybrid_tree.py

@@ -605,7 +605,7 @@ def add_successor(self, successor: "HybridTree") -> None:
             `successor`: the HybridTree to be marked as one level below `self`.
         """
         if self._successor is not None:
-            raise Exception("Duplicate successor")
+            raise ValueError("Duplicate successor")
         self._successor = successor
         successor._parent = self
         # Shift the aggregation keys and rhs of join keys back by 1 level to

pydough/conversion/projection_pullup.py

@@ -455,8 +455,8 @@ def simplify_agg(
             # Otherwise, FUNC(key) -> key
             return key_ref, None
 
-    # If running a selection aggregation on a literal, can just return the
-    # input.
+    # If running a selection aggregation on a literal or a grouping key, can
+    # just return the input.
     if (
         agg.op
         in (
@@ -470,7 +470,7 @@ def simplify_agg(
         and len(agg.inputs) >= 1
     ):
         arg = agg.inputs[0]
-        if isinstance(arg, LiteralExpression):
+        if isinstance(arg, LiteralExpression) or arg in reverse_keys:
             return arg, None
     # In all other cases, we just return the aggregation as is.
     return out_ref, agg

pydough/conversion/relational_converter.py

@@ -1346,8 +1346,7 @@ def preprocess_root(
                 column_typ: PyDoughType = node.get_expr(column).pydough_type
                 final_terms.append((column, Reference(node, column, column_typ)))
         children: list[PyDoughCollectionQDAG] = []
-        final_calc: Calculate = Calculate(node, children).with_terms(final_terms)
-        return final_calc
+        return Calculate(node, children, final_terms)
 
 
 def make_relational_ordering(

pydough/database_connectors/builtin_databases.py

@@ -6,6 +6,8 @@
 import sqlite3
 import time
 
+from pydough.errors import PyDoughSessionException
+
 from .database_connector import DatabaseConnection, DatabaseContext, DatabaseDialect
 
 __all__ = [
@@ -43,7 +45,7 @@ def load_database_context(database_name: str, **kwargs) -> DatabaseContext:
             connection = load_mysql_connection(**kwargs)
             dialect = DatabaseDialect.MYSQL
         case _:
-            raise ValueError(
+            raise PyDoughSessionException(
                 f"Unsupported database: {database_name}. The supported databases are: {supported_databases}."
                 "Any other database must be created manually by specifying the connection and dialect."
             )
@@ -59,7 +61,7 @@ def load_sqlite_connection(**kwargs) -> DatabaseConnection:
         A database connection object for SQLite.
     """
     if "database" not in kwargs:
-        raise ValueError("SQLite connection requires a database path.")
+        raise PyDoughSessionException("SQLite connection requires a database path.")
     connection: sqlite3.Connection = sqlite3.connect(**kwargs)
     return DatabaseConnection(connection)
 

pydough/database_connectors/database_connector.py

@@ -3,17 +3,19 @@
 by leveraging PEP 249 (Python Database API Specification v2.0).
 https://peps.python.org/pep-0249/
 """
-# Copyright (C) 2024 Bodo Inc. All rights reserved.
+
+__all__ = ["DatabaseConnection", "DatabaseContext", "DatabaseDialect"]
 
 from dataclasses import dataclass
 from enum import Enum
 from typing import TYPE_CHECKING, cast
 
 import pandas as pd
 
-from .db_types import DBConnection, DBCursor, SnowflakeCursor
+import pydough
+from pydough.errors import PyDoughSessionException
 
-__all__ = ["DatabaseConnection", "DatabaseContext", "DatabaseDialect"]
+from .db_types import DBConnection, DBCursor, SnowflakeCursor
 
 
 class DatabaseConnection:
@@ -51,7 +53,9 @@ def execute_query_df(self, sql: str) -> pd.DataFrame:
             self.cursor.execute(sql)
         except Exception as e:
             print(f"ERROR WHILE EXECUTING QUERY:\n{sql}")
-            raise e
+            raise pydough.active_session.error_builder.sql_runtime_failure(
+                sql, e, True
+            ) from e
 
         # This is only for MyPy to pass and know about fetch_pandas_all()
         # NOTE: Code does not run in type checking mode, so we need to
@@ -119,7 +123,7 @@ def from_string(dialect: str) -> "DatabaseDialect":
         if dialect in DatabaseDialect.__members__:
             return DatabaseDialect.__members__[dialect]
         else:
-            raise ValueError(f"Unsupported dialect: {dialect}")
+            raise PyDoughSessionException(f"Unsupported dialect: {dialect}")
 
 
 @dataclass

pydough/database_connectors/empty_connection.py

@@ -9,6 +9,8 @@
 
 __all__ = ["empty_connection"]
 
+from pydough.errors import PyDoughSessionException
+
 from .database_connector import DatabaseConnection
 
 
@@ -22,16 +24,16 @@ def __init__(self):
         pass
 
     def commit(self):
-        raise ValueError("No SQL Database is specified.")
+        raise PyDoughSessionException("No SQL Database is specified.")
 
     def close(self):
-        raise ValueError("No SQL Database is specified.")
+        raise PyDoughSessionException("No SQL Database is specified.")
 
     def rollback(self):
-        raise ValueError("No SQL Database is specified.")
+        raise PyDoughSessionException("No SQL Database is specified.")
 
     def cursor(self, *args, **kwargs):
-        raise ValueError("No SQL Database is specified.")
+        raise PyDoughSessionException("No SQL Database is specified.")
 
 
 empty_connection: DatabaseConnection = DatabaseConnection(EmptyConnection())

pydough/errors/__init__.py

@@ -0,0 +1,27 @@
+"""
+Module for error handling in PyDough.
+"""
+
+__all__ = [
+    "PyDoughErrorBuilder",
+    "PyDoughException",
+    "PyDoughMetadataException",
+    "PyDoughQDAGException",
+    "PyDoughSQLException",
+    "PyDoughSessionException",
+    "PyDoughTestingException",
+    "PyDoughTypeException",
+    "PyDoughUnqualifiedException",
+]
+
+from .error_types import (
+    PyDoughException,
+    PyDoughMetadataException,
+    PyDoughQDAGException,
+    PyDoughSessionException,
+    PyDoughSQLException,
+    PyDoughTestingException,
+    PyDoughTypeException,
+    PyDoughUnqualifiedException,
+)
+from .pydough_error_builder import PyDoughErrorBuilder