Introduce function API

db/functions/base.py

@@ -0,0 +1,261 @@
+"""
+This namespace defines the DbFunction abstract class and its subclasses. These subclasses
+represent functions that have identifiers, display names and hints, and their instances
+hold parameters. Each DbFunction subclass defines how its instance can be converted into an
+SQLAlchemy expression.
+
+Hints hold information about what kind of input the function might expect and what output
+can be expected from it. This is used to provide interface information without constraining its
+user.
+
+These classes might be used, for example, to define a filter for an SQL query, or to
+access hints on what composition of functions and parameters should be valid.
+"""
+
+from abc import ABC, abstractmethod
+
+from sqlalchemy import column, not_, and_, or_, func, literal
+from db.types.uri import URIFunction
+
+from db.functions import hints
+
+import importlib
+import inspect
+
+
+class DbFunction(ABC):
+    id = None
+    name = None
+    hints = None
+
+    def __init__(self, parameters):
+        if self.id is None:
+            raise ValueError('DbFunction subclasses must define an ID.')
+        if self.name is None:
+            raise ValueError('DbFunction subclasses must define a name.')
+        self.parameters = parameters
+
+    @property
+    def referenced_columns(self):
+        """Walks the expression tree, collecting referenced columns.
+        Useful when checking if all referenced columns are present in the queried relation."""
+        columns = set([])
+        for parameter in self.parameters:
+            if isinstance(parameter, ColumnReference):
+                columns.add(parameter.column)
+            elif isinstance(parameter, DbFunction):
+                columns.update(parameter.referenced_columns)
+        return columns
+
+    @staticmethod
+    @abstractmethod
+    def to_sa_expression():
+        return None
+
+
+class Literal(DbFunction):
+    id = 'literal'
+    name = 'Literal'
+    hints = tuple([
+        hints.parameter_count(1),
+        hints.parameter(1, hints.literal),
+    ])
+
+    @staticmethod
+    def to_sa_expression(p):
+        return literal(p)
+
+
+class ColumnReference(DbFunction):
+    id = 'column_reference'
+    name = 'Column Reference'
+    hints = tuple([
+        hints.parameter_count(1),
+        hints.parameter(1, hints.column),
+    ])
+
+    @property
+    def column(self):
+        return self.parameters[0]
+
+    @staticmethod
+    def to_sa_expression(p):
+        return column(p)
+
+
+class List(DbFunction):
+    id = 'list'
+    name = 'List'
+
+    @staticmethod
+    def to_sa_expression(*ps):
+        return list(ps)
+
+
+class Empty(DbFunction):
+    id = 'empty'
+    name = 'Empty'
+    hints = tuple([
+        hints.returns(hints.boolean),
+        hints.parameter_count(1),
+    ])
+
+    @staticmethod
+    def to_sa_expression(p):
+        return p.is_(None)
+
+
+class Not(DbFunction):
+    id = 'not'
+    name = 'Not'
+    hints = tuple([
+        hints.returns(hints.boolean),
+        hints.parameter_count(1),
+    ])
+
+    @staticmethod
+    def to_sa_expression(*p):
+        return not_(*p)
+
+
+class Equal(DbFunction):
+    id = 'equal'
+    name = 'Equal'
+    hints = tuple([
+        hints.returns(hints.boolean),
+        hints.parameter_count(2),
+    ])
+
+    @staticmethod
+    def to_sa_expression(p1, p2):
+        return p1 == p2
+
+
+class Greater(DbFunction):
+    id = 'greater'
+    name = 'Greater'
+    hints = tuple([
+        hints.returns(hints.boolean),
+        hints.parameter_count(2),
+        hints.all_parameters(hints.comparable),
+    ])
+
+    @staticmethod
+    def to_sa_expression(p1, p2):
+        return p1 > p2
+
+
+class Lesser(DbFunction):
+    id = 'lesser'
+    name = 'Lesser'
+    hints = tuple([
+        hints.returns(hints.boolean),
+        hints.parameter_count(2),
+        hints.all_parameters(hints.comparable),
+    ])
+
+    @staticmethod
+    def to_sa_expression(p1, p2):
+        return p1 < p2
+
+
+class In(DbFunction):
+    id = 'in'
+    name = 'In'
+    hints = tuple([
+        hints.returns(hints.boolean),
+        hints.parameter_count(2),
+        hints.parameter(2, hints.array),
+    ])
+
+    @staticmethod
+    def to_sa_expression(p1, p2):
+        return p1.in_(p2)
+
+
+class And(DbFunction):
+    id = 'and'
+    name = 'And'
+    hints = tuple([
+        hints.returns(hints.boolean),
+    ])
+
+    @staticmethod
+    def to_sa_expression(*ps):
+        return and_(*ps)
+
+
+class Or(DbFunction):
+    id = 'or'
+    name = 'Or'
+    hints = tuple([
+        hints.returns(hints.boolean),
+    ])
+
+    @staticmethod
+    def to_sa_expression(*ps):
+        return or_(*ps)
+
+
+class StartsWith(DbFunction):
+    id = 'starts_with'
+    name = 'Starts With'
+    hints = tuple([
+        hints.returns(hints.boolean),
+        hints.parameter_count(2),
+        hints.all_parameters(hints.string_like),
+    ])
+
+    @staticmethod
+    def to_sa_expression(p1, p2):
+        return p1.like(f'{p2}%')
+
+
+class ToLowercase(DbFunction):
+    id = 'to_lowercase'
+    name = 'To Lowercase'
+    hints = tuple([
+        hints.parameter_count(1),
+        hints.all_parameters(hints.string_like),
+    ])
+
+    @staticmethod
+    def to_sa_expression(p1):
+        return func.lower(p1)
+
+
+class ExtractURIAuthority(DbFunction):
+    id = 'extract_uri_authority'
+    name = 'Extract URI Authority'
+    hints = tuple([
+        hints.parameter_count(1),
+        hints.parameter(1, hints.uri),
+    ])
+
+    @staticmethod
+    def to_sa_expression(p1):
+        return func.getattr(URIFunction.AUTHORITY)(p1)
+
+
+def _get_defining_module_members_that_satisfy(predicate):
+    # NOTE: the value returned by globals() (when it's called within a function) is set when the
+    # function is defined and does not change depending on where the function is called from.
+    # See https://docs.python.org/3/library/functions.html#globals
+    # If we wanted to move this function into another namespace, we would have to additionally
+    # pass it this namespace's globals().
+    defining_module_name = globals()['__name__']
+    defining_module = importlib.import_module(defining_module_name)
+    all_members_in_defining_module = inspect.getmembers(defining_module)
+    return tuple(
+        member
+        for _, member in all_members_in_defining_module
+        if predicate(member)
+    )
+
+
+def _is_concrete_db_function_subclass(member):
+    return inspect.isclass(member) and member != DbFunction and issubclass(member, DbFunction)
+
+
+# Enumeration of supported DbFunction subclasses; needed when parsing.
+supported_db_functions = _get_defining_module_members_that_satisfy(_is_concrete_db_function_subclass)

db/functions/exceptions.py

@@ -0,0 +1,10 @@
+class BadDbFunctionFormat(Exception):
+    pass
+
+
+class UnknownDbFunctionId(BadDbFunctionFormat):
+    pass
+
+
+class ReferencedColumnsDontExist(BadDbFunctionFormat):
+    pass

db/functions/hints.py

@@ -0,0 +1,42 @@
+from frozendict import frozendict
+
+
+def _make_hint(id, **rest):
+    return frozendict({"id": id, **rest})
+
+
+def parameter_count(count):
+    return _make_hint("parameter_count", count=count)
+
+
+def parameter(index, *hints):
+    return _make_hint("parameter", index=index, hints=hints)
+
+
+def all_parameters(*hints):
+    return _make_hint("all_parameters", hints=hints)
+
+
+def returns(*hints):
+    return _make_hint("returns", hints=hints)
+
+
+boolean = _make_hint("boolean")
+
+
+comparable = _make_hint("comparable")
+
+
+column = _make_hint("column")
+
+
+array = _make_hint("array")
+
+
+string_like = _make_hint("string_like")
+
+
+uri = _make_hint("uri")
+
+
+literal = _make_hint("literal")

db/functions/operations/apply.py

@@ -0,0 +1,48 @@
+from db.functions.base import DbFunction
+from db.functions.exceptions import ReferencedColumnsDontExist
+from db.functions.operations.deserialize import get_db_function_from_ma_function_spec
+
+
+def apply_ma_function_spec_as_filter(relation, ma_function_spec):
+    db_function = get_db_function_from_ma_function_spec(ma_function_spec)
+    return apply_db_function_as_filter(relation, db_function)
+
+
+def apply_db_function_as_filter(relation, db_function):
+    _assert_that_all_referenced_columns_exist(relation, db_function)
+    sa_expression = _db_function_to_sa_expression(db_function)
+    relation = relation.filter(sa_expression)
+    return relation
+
+
+def _assert_that_all_referenced_columns_exist(relation, db_function):
+    columns_that_exist = _get_columns_that_exist(relation)
+    referenced_columns = db_function.referenced_columns
+    referenced_columns_that_dont_exist = \
+        set.difference(referenced_columns, columns_that_exist)
+    if len(referenced_columns_that_dont_exist) > 0:
+        raise ReferencedColumnsDontExist(
+            "These referenced columns don't exist on the relevant relation: "
+            + f"{referenced_columns_that_dont_exist}"
+        )
+
+
+def _get_columns_that_exist(relation):
+    columns = relation.selected_columns
+    return set(column.name for column in columns)
+
+
+def _db_function_to_sa_expression(db_function):
+    """
+    Everything is considered to be either a DbFunction subclass or a literal.
+    """
+    if isinstance(db_function, DbFunction):
+        raw_parameters = db_function.parameters
+        parameters = [
+            _db_function_to_sa_expression(raw_parameter)
+            for raw_parameter in raw_parameters
+        ]
+        db_function_subclass = type(db_function)
+        return db_function_subclass.to_sa_expression(*parameters)
+    else:
+        return db_function