clear-skies 1.19.22__py3-none-any.whl → 2.0.23__py3-none-any.whl

clearskies/query/__init__.py

@@ -0,0 +1,12 @@
+from clearskies.query.condition import Condition, ParsedCondition
+from clearskies.query.join import Join
+from clearskies.query.query import Query
+from clearskies.query.sort import Sort
+
+__all__ = [
+    "Condition",
+    "Join",
+    "ParsedCondition",
+    "Sort",
+    "Query",
+]

clearskies/query/condition.py

@@ -0,0 +1,228 @@
+class Condition:
+    """
+    Parses a condition string, e.g. "column=value" or "table.column<=other_value".
+
+    Allowed operators: ["<=>", "!=", "<=", ">=", ">", "<", "=", "in", "is not null", "is null", "is not", "is", "like"]
+
+    NOTE: Not all backends support all operators, so make sure the condition you are building works for your backend
+
+    This is safe to use with untrusted input because it expects a stringent and easy-to-verify format.  The incoming
+    string must be one of these patterns:
+
+     1. [column_name][operator][value]
+     2. [table_name].[column_name][operator][value]
+
+    SQL-like syntax is allowed, so:
+
+     1. Spaces are optionally allowed around the operator.
+     2. Backticks are optionally allowd around the table/column name.
+     3. Single quotes are optionally allowed around the values.
+     4. operators are case-insensitive.
+
+    In the case of an IN operator, the parser expects a series of comma separated values enclosed in parenthesis,
+    with each value optionally enclosed in single quotes.  This parsing is very simple and there is not currently a way
+    to escape commas or single quotes.
+
+    NOTE: operators (when they are english words, of course) are always output in all upper-case.
+
+    Some examples:
+
+    ```python
+    condition = Condition("id=asdf-qwerty")  # note: same results for: Condition("id = asdf-qwerty")
+    print(condition.table_name)  # prints ''
+    print(condition.column_name)  # prints 'id'
+    print(condition.operator)  # prints '='
+    print(condition.values)  # prints ['asdf-qwerty']
+    print(condition.parsed)  # prints 'id=%s'
+
+    condition = Condition("orders.status_id in ('ACTIVE', 'PENDING')")
+    print(condition.table_name)  # prints 'orders'
+    print(condition.column_name)  # prints 'status_id'
+    print(condition.operator)  # prints 'IN'
+    print(condition.values)  # prints ['ACTIVE', 'PENDING']
+    print(condition.parsed)  # prints 'status_id IN (%s, %s)'
+    ```
+    """
+
+    """
+    The name of the table this condition is searching on (if there is one).
+    """
+    table_name: str = ""
+
+    """
+    The name of the column the condition is searching.
+    """
+    column_name: str = ""
+
+    """
+    The operator we are searching with (e.g. '=', '<=', etc...)
+    """
+    operator: str = ""
+
+    """
+    The values the condition is searching for.
+
+    Note this is always a list, although most of the time there is only one value in the list.  Multiple values
+    are only present when searching with the IN operator.
+    """
+    values: list[str] = []
+
+    """
+    An SQL-ready string
+    """
+    parsed: str = ""
+
+    """
+    The original condition string
+    """
+    _raw_condition: str = ""
+
+    """
+    The list of operators we can match
+
+    Note: the order is very important because this list is used to find the operator in the condition string.
+    As a result, the order of the operators in this list is important.  The condition matching algorithm used
+    below will select whichever operator matches earlier in the string, but there are some operators that
+    start with the same characters: '<=>' and '<=', as well as 'is', 'is null', 'is not', etc...  This leaves
+    room for ambiguity since all of these operators will match at the same location.  In the event of a "tie" the
+    algorithm gives preference to the first matching operator.  Therefore, for ambiguous operators, we put the
+    longer one first, which means it matches first, and so a condition with a '<=>' operator won't accidentally
+    match to the '<=' operator.
+    """
+    operators: list[str] = [
+        "<=>",
+        "!=",
+        "<=",
+        ">=",
+        ">",
+        "<",
+        "=",
+        "in",
+        "is not null",
+        "is null",
+        "is not",
+        "is",
+        "like",
+        "not in",
+    ]
+
+    operator_lengths: dict[str, int] = {
+        "<=>": 3,
+        "<=": 2,
+        ">=": 2,
+        "!=": 2,
+        ">": 1,
+        "<": 1,
+        "=": 1,
+        "in": 4,
+        "is not null": 12,
+        "is null": 8,
+        "is not": 8,
+        "is": 4,
+        "like": 6,
+        "not in": 8,
+    }
+
+    # some operators require spaces around them
+    operators_for_matching: dict[str, str] = {
+        "like": " like ",
+        "in": " in ",
+        "not in": " not in ",
+        "is not null": " is not null",
+        "is null": " is null",
+        "is": " is ",
+        "is not": " is not ",
+    }
+
+    operators_with_simple_placeholders: dict[str, bool] = {
+        "<=>": True,
+        "<=": True,
+        ">=": True,
+        "!=": True,
+        "=": True,
+        "<": True,
+        ">": True,
+    }
+
+    operators_without_placeholders: dict[str, bool] = {
+        "is not null": True,
+        "is null": True,
+    }
+
+    def __init__(self, condition: str):
+        self._raw_condition = condition
+        lowercase_condition = condition.lower()
+        self.operator = ""
+        matching_index = len(condition)
+        # figure out which operator comes earliest in the string: make sure and check all so we match the
+        # earliest operator so we don't get unpredictable results for things like 'age=name<=5'.  We want
+        # our operator to **ALWAYS** match whatever comes first in the condition string.
+        for operator in self.operators:
+            try:
+                operator_for_match = self.operators_for_matching.get(operator, operator)
+                index = lowercase_condition.index(operator_for_match)
+            except ValueError:
+                continue
+            if index < matching_index:
+                matching_index = index
+                self.operator = operator
+
+        if not self.operator:
+            raise ValueError(f"No supported operators found in condition {condition}")
+
+        self.column_name = condition[:matching_index].strip().replace("`", "")
+        value = condition[matching_index + self.operator_lengths[self.operator] :].strip()
+        if value and (value[0] == "'" and value[-1] == "'"):
+            value = value.strip("'")
+        self.values = self._parse_condition_list(value) if self.operator == "in" else [value]
+        self.table_name = ""
+        if "." in self.column_name:
+            [self.table_name, self.column_name] = self.column_name.split(".")
+        column_for_parsed = f"{self.table_name}.{self.column_name}" if self.table_name else self.column_name
+
+        if self.operator in self.operators_without_placeholders:
+            self.values = []
+
+        self.operator = self.operator.upper()
+        self.parsed = self._with_placeholders(
+            column_for_parsed, self.operator, self.values, escape=False if self.table_name else True
+        )
+
+    def _parse_condition_list(self, value):
+        if value[0] != "(" and value[-1] != ")":
+            raise ValueError(f"Invalid search value {value} for condition.  For IN operator use `IN (value1,value2)`")
+
+        # note: this is not very smart and will mess things up if there are single quotes/commas in the data
+        return list(map(lambda value: value.strip().strip("'"), value[1:-1].split(",")))
+
+    def _with_placeholders(self, column, operator, values, escape=True, escape_character="`", placeholder="%s"):
+        quote = escape_character if escape else ""
+        column = column.replace("`", "")
+        upper_case_operator = operator.upper()
+        lower_case_operator = operator.lower()
+        if lower_case_operator in self.operators_with_simple_placeholders:
+            return f"{quote}{column}{quote}{upper_case_operator}{placeholder}"
+        if lower_case_operator in self.operators_without_placeholders:
+            return f"{quote}{column}{quote} {upper_case_operator}"
+        if lower_case_operator == "is" or lower_case_operator == "is not" or lower_case_operator == "like":
+            return f"{quote}{column}{quote} {upper_case_operator} {placeholder}"
+        if lower_case_operator == "not in":
+            return f"{quote}{column}{quote} NOT IN ({', '.join([placeholder for i in range(len(values))])})"
+
+        # the only thing left is "in" which has a variable number of placeholders
+        return f"{quote}{column}{quote} IN ({', '.join([placeholder for i in range(len(values))])})"
+
+
+class ParsedCondition(Condition):
+    def __init__(self, column_name: str, operator: str, values: list[str], table_name: str = ""):
+        self.column_name = column_name
+        if operator not in self.operators:
+            raise ValueError(f"Unknown operator '{operator}'")
+        self.operator = operator
+        self.values = values
+        self.table_name = table_name
+        column_for_parsed = f"{self.table_name}.{self.column_name}" if self.table_name else self.column_name
+        self.parsed = self._with_placeholders(
+            column_for_parsed, self.operator, self.values, escape=False if self.table_name else True
+        )
+        self._raw_condition = self.parsed

clearskies/query/join.py

@@ -0,0 +1,136 @@
+import re
+
+
+class Join:
+    """
+    Parses a join clause.
+
+    Note that this expects a few very specific pattern:
+
+     1. [TYPE] JOIN [right_table_name] ON [left_table_name].[left_column_name]=[right_table_name].[right_column_name]
+     2. [TYPE] JOIN [right_table_name] AS [alias] ON [alias].[left_column_name]=[right_table_name].[right_column_name]
+     3. [TYPE] JOIN [right_table_name] [alias] ON [alias].[left_column_name]=[right_table_name].[right_column_name]
+
+    NOTE: The allowed join types are ["INNER", "OUTER", "LEFT", "RIGHT"]
+
+    NOTE: backticks are optionally allowed around column and table names.
+
+    Examples:
+    ```python
+    join = Join("INNER JOIN orders ON users.id=orders.user_id")
+    print(f"{join.left_table_name}.{join.left_column_name}")  # prints 'users.id'
+    print(f"{join.right_table_name}.{join.right_column_name}")  # prints 'orders.user_id'
+    print(join.type)  # prints 'INNER'
+    print(join.alias)  # prints ''
+    print(join.unaliased_table_name)  # prints 'orders'
+
+    join = Join("JOIN some_long_table_name AS new_table ON old_table.id=new_table.old_id")
+    print(f"{join.left_table_name}.{join.left_column_name}")  # prints 'old_table.id'
+    print(f"{join.right_table_name}.{join.right_column_name}")  # prints 'new_table.old_id'
+    print(join.type)  # prints 'LEFT'
+    print(join.alias)  # prints 'new_table'
+    print(join.unaliased_table_name)  # prints 'some_long_table_name'
+    ```
+    """
+
+    """
+    The name of the table on the left side of the join
+    """
+    left_table_name: str = ""
+
+    """
+    The name of the column on the left side of the join
+    """
+    left_column_name: str = ""
+
+    """
+    The name of the table on the right side of the join
+    """
+    right_table_name: str = ""
+
+    """
+    The name of the column on the right side of the join
+    """
+    right_column_name: str = ""
+
+    """
+    The type of join (LEFT, RIGHT, INNER, OUTER)
+    """
+    join_type: str = ""
+
+    """
+    An alias for the joined table, if needed
+    """
+    alias: str = ""
+
+    """
+    The actual name of the right table, regardless of alias
+    """
+    unaliased_table_name: str = ""
+
+    """
+    The original join string
+    """
+    _raw_join: str = ""
+
+    """
+    The allowed join types
+    """
+    _allowed_types = ["INNER", "OUTER", "LEFT", "RIGHT"]
+
+    def __init__(self, join: str):
+        self._raw_join = join
+        # doing this the simple and stupid way, until that doesn't work.  Yes, it is ugly.
+        # Splitting this into two regexps for simplicity: this one does not check for an alias
+        matches = re.match(
+            "(\\w+\\s+)?join\\s+`?([^\\s`]+)`?\\s+on\\s+`?([^`]+)`?\\.`?([^`]+)`?\\s*=\\s*`?([^`]+)`?\\.`?([^`]+)`?",
+            join,
+            re.IGNORECASE,
+        )
+        if matches:
+            groups = matches.groups()
+            alias = ""
+            join_type = groups[0]
+            right_table = groups[1]
+            first_table = groups[2]
+            first_column = groups[3]
+            second_table = groups[4]
+            second_column = groups[5]
+        else:
+            matches = re.match(
+                "(\\w+\\s+)?join\\s+`?([^\\s`]+)`?\\s+(as\\s+)?(\\S+)\\s+on\\s+`?([^`]+)`?\\.`?([^`]+)`?\\s*=\\s*`?([^`]+)`?\\.`?([^`]+)`?",
+                join,
+                re.IGNORECASE,
+            )
+            if not matches:
+                raise ValueError(f"Specified join condition, '{join}' does not appear to be a valid join statement")
+            groups = matches.groups()
+            join_type = groups[0]
+            right_table = groups[1]
+            alias = groups[3]
+            first_table = groups[4]
+            first_column = groups[5]
+            second_table = groups[6]
+            second_column = groups[7]
+
+        # which is the left table and which is the right table?
+        match_by = alias if alias else right_table
+        if first_table == match_by:
+            self.left_table_name = second_table
+            self.left_column_name = second_column
+            self.right_table_name = first_table
+            self.right_column_name = first_column
+        elif second_table == match_by:
+            self.left_table_name = first_table
+            self.left_column_name = first_column
+            self.right_table_name = second_table
+            self.right_column_name = second_column
+        else:
+            raise ValueError(
+                f"Specified join condition, '{join}' was not understandable because the joined table "
+                + "is not referenced in the 'on' clause"
+            )
+
+        self.join_type = groups[0].strip().upper() if groups[0] else "INNER"
+        self.alias = alias
+        self.unaliased_table_name = right_table

clearskies/query/query.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Self
+
+if TYPE_CHECKING:
+    from clearskies import Model
+    from clearskies.query import Condition, Join, Sort
+
+
+class Query:
+    """
+    Track the various aspects of a query.
+
+    This is mostly just used by the Model class to keep track of a list request.
+    """
+
+    """
+    The model class
+    """
+    model_class: type[Model] = None  # type: ignore
+
+    """
+    The list of where conditions for the query.
+    """
+    conditions: list[Condition] = []
+
+    """
+    The conditions, but organized by column.
+    """
+    conditions_by_column: dict[str, list[Condition]] = {}
+
+    """
+    Joins for the query.
+    """
+    joins: list[Join] = []
+
+    """
+    The sort directives for the query
+    """
+    sorts: list[Sort] = []
+
+    """
+    The maximum number of records to return.
+    """
+    limit: int = 0
+
+    """
+    Pagination information (e.g. start/next_token/etc... the details depend on the backend.
+    """
+    pagination: dict[str, Any] = {}
+
+    """
+    A list of select statements.
+    """
+    selects: list[str] = []
+
+    """
+    Whether or not to just select all columns.
+    """
+    select_all: bool = True
+
+    """
+    The name of the column to group by.
+    """
+    group_by = ""
+
+    def __init__(
+        self,
+        model_class: type[Model],
+        conditions: list[Condition] = [],
+        joins: list[Join] = [],
+        sorts: list[Sort] = [],
+        limit: int = 0,
+        group_by: str = "",
+        pagination: dict[str, Any] = {},
+        selects: list[str] = [],
+        select_all: bool = True,
+    ):
+        self.model_class = model_class
+        self.conditions = [*conditions]
+        self.joins = [*joins]
+        self.sorts = [*sorts]
+        self.limit = limit
+        self.group_by = group_by
+        self.pagination = {**pagination}
+        self.selects = [*selects]
+        self.select_all = select_all
+        self.conditions_by_column = {}
+        if conditions:
+            for condition in conditions:
+                if condition.column_name not in self.conditions_by_column:
+                    self.conditions_by_column[condition.column_name] = []
+                self.conditions_by_column[condition.column_name].append(condition)
+
+    def as_kwargs(self):
+        """Return the properties of this query as a dictionary so it can be used as kwargs when creating another one."""
+        return {
+            "model_class": self.model_class,
+            "conditions": [*self.conditions],
+            "joins": [*self.joins],
+            "sorts": [*self.sorts],
+            "limit": self.limit,
+            "group_by": self.group_by,
+            "pagination": self.pagination,
+            "selects": [*self.selects],
+            "select_all": self.select_all,
+        }
+
+    def add_where(self, condition: Condition) -> Self:
+        self.validate_column(condition.column_name, "filter", table=condition.table_name)
+        new_kwargs = self.as_kwargs()
+        new_kwargs["conditions"].append(condition)
+        return self.__class__(**new_kwargs)
+
+    def add_join(self, join: Join) -> Self:
+        new_kwargs = self.as_kwargs()
+        new_kwargs["joins"].append(join)
+        return self.__class__(**new_kwargs)
+
+    def set_sort(self, sort: Sort, secondary_sort: Sort | None = None) -> Self:
+        self.validate_column(sort.column_name, "sort", table=sort.table_name)
+        new_kwargs = self.as_kwargs()
+        new_kwargs["sorts"] = [sort]
+        if secondary_sort:
+            new_kwargs["sorts"].append(secondary_sort)
+
+        return self.__class__(**new_kwargs)
+
+    def set_limit(self, limit: int) -> Self:
+        if not isinstance(limit, int):
+            raise TypeError(
+                f"The limit in a query must be of type int but I received a value of type '{limit.__class__.__name__}'"
+            )
+        return self.__class__(
+            **{
+                **self.as_kwargs(),
+                "limit": limit,
+            }
+        )
+
+    def set_group_by(self, column_name) -> Self:
+        self.validate_column(column_name, "group")
+        return self.__class__(
+            **{
+                **self.as_kwargs(),
+                "group_by": column_name,
+            }
+        )
+
+    def set_pagination(self, pagination: dict[str, Any]) -> Self:
+        return self.__class__(
+            **{
+                **self.as_kwargs(),
+                "pagination": pagination,
+            }
+        )
+
+    def add_select(self, select: str) -> Self:
+        new_kwargs = self.as_kwargs()
+        new_kwargs["selects"].append(select)
+        return self.__class__(**new_kwargs)
+
+    def set_select_all(self, select_all: bool) -> Self:
+        return self.__class__(
+            **{
+                **self.as_kwargs(),
+                "select_all": select_all,
+            }
+        )
+
+    def validate_column(self: Self, column_name: str, action: str, table: str | None = None) -> None:
+        # for now, only validate columns that belong to *our* table.
+        # in some cases we are explicitly told the column name
+        if table is not None:
+            # note that table may be '', in which case it is implicitly "our" table
+            if table != "" and table != self.model_class.destination_name():
+                return
+
+        # but in some cases we should check and see if it is included with the column name
+        column_name = column_name.replace("`", "")
+        if "." in column_name:
+            parts = column_name.split(".")
+            if parts[0] != self.model_class.destination_name():
+                return
+            column_name = column_name.split(".")[1]
+
+        model_columns = self.model_class.get_columns()
+        if column_name not in model_columns:
+            raise KeyError(
+                f"Cannot {action} by column '{column_name}' for model class {self.model_class.__name__} because this "
+                + "column does not exist for the model.  You can suppress this error by adding a matching column "
+                + "to your model definition"
+            )

clearskies/query/sort.py

@@ -0,0 +1,27 @@
+class Sort:
+    """Stores a sort directive."""
+
+    """
+    The name of the table to sort on.
+    """
+    table_name: str = ""
+
+    """
+    The name of the column to sort on.
+    """
+    column_name: str = ""
+
+    """
+    The direction to sort.
+    """
+    direction: str = ""
+
+    def __init__(self, table_name: str, column_name: str, direction: str):
+        if not column_name:
+            raise ValueError("Missing 'column_name' for sort")
+        direction = direction.upper().strip()
+        if direction != "ASC" and direction != "DESC":
+            raise ValueError(f"Invalid sort direction: should be ASC or DESC, not '{direction}'")
+        self.table_name = table_name
+        self.column_name = column_name
+        self.direction = direction

clearskies/schema.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from collections import OrderedDict
+from typing import TYPE_CHECKING, Self
+
+if TYPE_CHECKING:
+    from clearskies import Column
+
+
+class Schema:
+    """
+    Define a schema by extending and declaring columns.
+
+    ```python
+    from clearskies.schema import Schema
+    from clearskies.validators import Required, Unique
+
+    import clearskies.columns
+
+
+    class Person(Schema):
+        id = clearskies.columns.Uuid()
+        name = clearskies.columns.String(validators=[Required()])
+        date_of_birth = clearskies.columns.Datetime(validators=[Required(), InThePast()])
+        email = clearskies.columns.Email()
+    ```
+    """
+
+    id_column_name: str = ""
+    _columns: dict[str, Column] = {}
+
+    @classmethod
+    def destination_name(cls: type[Self]) -> str:
+        raise NotImplementedError()
+
+    def __init__(self):
+        self._data = {}
+
+    @classmethod
+    def get_columns(cls: type[Self], overrides={}) -> dict[str, Column]:
+        """
+        Return an ordered dictionary with the configuration for the columns.
+
+        Generally, this method is meant for internal use.  It just pulls the column configuration
+        information out of class attributes.  It doesn't return the fully prepared columns,
+        so you probably can't use the return value of this function.  For that, see
+        `model.columns()`.
+        """
+        # no caching if we have overrides
+        if cls._columns and not overrides:
+            return cls._columns
+
+        overrides = {**overrides}
+        columns: dict[str, Column] = OrderedDict()
+        for attribute_name in dir(cls):
+            attribute = getattr(cls, attribute_name)
+            # use duck typing instead of isinstance to decide which attribute is a column.
+            # We have to do this to avoid circular imports.
+            if not hasattr(attribute, "from_backend") and not hasattr(attribute, "to_backend"):
+                continue
+
+            if attribute_name in overrides:
+                columns[attribute_name] = overrides[attribute_name]
+                del overrides[attribute_name]
+            columns[attribute_name] = attribute
+
+        for attribute_name, column in overrides.items():
+            columns[attribute_name] = column  # type: ignore
+
+        if not overrides:
+            cls._columns = columns
+
+        # now go through and finalize everything.  We have to do this after setting cls._columns, because finalization
+        # sometimes depends on fetching the list of columns, so if we do it before caching the answer, we may end up
+        # creating circular loops.  I don't *think* this will cause painful side-effects, but we'll find out!
+        for column_name, column in cls._columns.items():
+            column.finalize_configuration(cls, column_name)
+
+        return columns
+
+    def __bool__(self):
+        return False