sustained 0.0.1__py3-none-any.whl

sustained/__init__.py

@@ -0,0 +1,39 @@
+"""
+A Python query builder inspired by Objection.js.
+
+This package provides a set of classes that allow you to build SQL queries
+in a more programmatic and reusable way. The main components are:
+
+- Model: A base class for defining database models and their relations.
+- QueryBuilder: A class for constructing SQL queries.
+- RelationType: An Enum for defining the type of relationship between models.
+- create_model: A factory function for dynamically creating Model classes.
+"""
+
+from .builder import QueryBuilder
+from .model import Model, create_model
+from .types import (
+    BasicJoinMapping,
+    Join,
+    JoinMappingWithThrough,
+    RelationMapping,
+    RelationType,
+    ThroughJoinMapping,
+    ThroughJoinValue,
+)
+
+__all__ = [
+    # from types
+    "RelationType",
+    "BasicJoinMapping",
+    "ThroughJoinValue",
+    "ThroughJoinMapping",
+    "JoinMappingWithThrough",
+    "Join",
+    "RelationMapping",
+    # from builder
+    "QueryBuilder",
+    # from model
+    "Model",
+    "create_model",
+]

sustained/builder.py

@@ -0,0 +1,479 @@
+from __future__ import annotations
+
+import re
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Dict,
+    List,
+    Optional,
+    Tuple,
+    Type,
+    Union,
+    cast,
+)
+
+from .types import BasicJoinMapping, JoinMappingWithThrough
+
+if TYPE_CHECKING:
+    from .model import Model
+
+
+class JoinClauseBuilder:
+    """
+    A helper class for building complex JOIN ... ON clauses.
+    An instance of this is passed to the lambda in `...join(..., lambda j: ...)` calls.
+    """
+
+    def __init__(self):
+        self._conditions: List[Tuple[str, str]] = []
+
+    def on(self, col1: str, op: str, col2: str) -> "JoinClauseBuilder":
+        """Adds an ON condition. If this is not the first condition, it's treated as AND ON."""
+        conjunction = "AND" if self._conditions else ""
+        self._add_condition(conjunction, col1, op, col2)
+        return self
+
+    def andOn(self, col1: str, op: str, col2: str) -> "JoinClauseBuilder":
+        """Adds an AND ON condition."""
+        if not self._conditions:
+            raise RuntimeError(
+                "Cannot use 'andOn' for the first join condition. Use 'on' instead."
+            )
+        self._add_condition("AND", col1, op, col2)
+        return self
+
+    def orOn(self, col1: str, op: str, col2: str) -> "JoinClauseBuilder":
+        """Adds an OR ON condition."""
+        if not self._conditions:
+            raise RuntimeError(
+                "Cannot use 'orOn' for the first join condition. Use 'on' instead."
+            )
+        self._add_condition("OR", col1, op, col2)
+        return self
+
+    def _add_condition(self, conjunction: str, col1: str, op: str, col2: str):
+        condition_str = f"{col1} {op} {col2}"
+        self._conditions.append((conjunction, condition_str))
+
+    def __str__(self) -> str:
+        """Builds the final ON clause string."""
+        if not self._conditions:
+            raise RuntimeError("A join condition must be specified inside the lambda.")
+
+        # The first condition doesn't have a preceding conjunction
+        parts = [self._conditions[0][1]]
+        for conjunction, clause in self._conditions[1:]:
+            parts.append(f"{conjunction} {clause}")
+        return " ".join(parts)
+
+
+class QueryBuilder:
+    """
+    A builder for creating and executing SQL queries in a programmatic way.
+
+    This class is not meant to be instantiated directly. Instead, you should use
+    the `query()` class method on a `Model` subclass.
+    """
+
+    _JOIN_METHOD_MAP = {
+        "": "JOIN",
+        "inner": "INNER JOIN",
+        "left": "LEFT JOIN",
+        "leftOuter": "LEFT OUTER JOIN",
+        "right": "RIGHT JOIN",
+        "rightOuter": "RIGHT OUTER JOIN",
+        "full": "FULL JOIN",
+        "fullOuter": "FULL OUTER JOIN",
+        "cross": "CROSS JOIN",
+    }
+
+    def __init__(self, model_class: Type["Model"]):
+        """
+        Initializes the QueryBuilder.
+
+        Args:
+            model_class (Type[Model]): The `Model` subclass this query is based on.
+        """
+        self._model_class = model_class
+        self._selected_columns: List[str] = []
+        self._joins: List[str] = []
+        self._where_clauses: List[Tuple[str, str]] = []
+        self._with_clauses: List[Tuple[str, str]] = []
+
+    def select(self, *columns: str) -> "QueryBuilder":
+        """
+        Specifies the columns to be selected in the query.
+
+        Args:
+            *columns (str): A list of column names to select.
+
+        Returns:
+            QueryBuilder: The current QueryBuilder instance for chaining.
+        """
+        self._selected_columns.extend(columns)
+        return self
+
+    def with_(self, table_alias: str, subquery: "QueryBuilder") -> "QueryBuilder":
+        """
+        Adds a Common Table Expression (CTE) to the query.
+        NOTE: This method is named `with_` to avoid conflict with the Python `with` keyword.
+
+        Example:
+            cte_query = OtherModel.query().select("id", "name")
+            main_query = MyModel.query().with_("my_cte", cte_query).select("*")
+
+        Args:
+            table_alias (str): The alias for the CTE.
+            subquery (QueryBuilder): The query builder instance for the CTE's subquery.
+
+        Returns:
+            QueryBuilder: The current QueryBuilder instance for chaining.
+        """
+        self._with_clauses.append((table_alias, str(subquery)))
+        return self
+
+    def __str__(self) -> str:
+        """
+        Builds and returns the final SQL query string.
+
+        Returns:
+            str: The complete SQL query.
+        """
+        query_parts = []
+
+        if self._with_clauses:
+            cte_strs = [
+                f"{alias} AS ({subquery_str})"
+                for alias, subquery_str in self._with_clauses
+            ]
+            with_str = "WITH " + ", ".join(cte_strs)
+            query_parts.append(with_str)
+
+        cols = ", ".join(self._selected_columns) if self._selected_columns else "*"
+        model_cls = self._model_class
+        parts = []
+        if model_cls.database:
+            parts.append(model_cls.database)
+        if model_cls.tableSchema:
+            parts.append(model_cls.tableSchema)
+        if model_cls.tableName:
+            parts.append(model_cls.tableName)
+        full_table_name = ".".join(parts)
+
+        joins_str = " ".join(self._joins)
+
+        where_str = ""
+        if self._where_clauses:
+            where_str = "WHERE " + self._build_clause_list_string()
+
+        query_parts.append(f"SELECT {cols} FROM {full_table_name}")
+
+        if joins_str:
+            query_parts.append(joins_str)
+
+        if where_str:
+            query_parts.append(where_str)
+
+        return " ".join(query_parts)
+
+    def __getattr__(self, name: str) -> Callable:
+        """
+        Dynamically handles method calls for joins and where clauses.
+
+        This allows for methods like `where('id', '=', 1)`, `orWhere(...)`,
+        `innerJoinRelated('owner')`, etc., to be called on the query builder.
+
+        Supported join methods:
+            - `joinRelated`
+            - `innerJoinRelated`
+            - `leftJoinRelated`
+            - `leftOuterJoinRelated`
+            - `rightJoinRelated`
+            - `rightOuterJoinRelated`
+            - `fullJoinRelated`
+            - `fullOuterJoinRelated`
+            - `crossJoinRelated`
+
+        Supported where methods:
+            - `where`
+            - `andWhere`
+            - `orWhere`
+            - `whereIn`
+            - `andWhereIn`
+            - `orWhereIn`
+            - `whereNotIn`
+            - `andWhereNotIn`
+            - `orWhereNotIn`
+
+        Args:
+            name (str): The name of the method being called.
+
+        Returns:
+            Callable: A function that executes the corresponding join or where logic.
+
+        Raises:
+            AttributeError: If the method name is not a valid dynamic method.
+        """
+        # Handle all join methods (e.g., innerJoinRelated, leftJoin)
+        join_prefixes = "|".join(k for k in self._JOIN_METHOD_MAP.keys() if k)
+        join_match = re.match(
+            rf"^({join_prefixes})?(Join)(Related)?$", name, re.IGNORECASE
+        )
+
+        if join_match:
+            join_prefix, _, related_suffix = join_match.groups()
+            sql_join_type = self._JOIN_METHOD_MAP[join_prefix or ""]
+
+            if related_suffix:
+                # This is a ...joinRelated() call
+                def dynamic_join_caller(
+                    relation_name: str, alias: Optional[str] = None
+                ):
+                    self._join_related_internal(sql_join_type, relation_name, alias)
+                    return self
+
+                return dynamic_join_caller
+            else:
+                # This is a raw ...join() call
+                def dynamic_raw_join_caller(table: str, *args: Any):
+                    if len(args) == 3:
+                        # Static syntax: .join('table', 'col1', '=', 'col2')
+                        col1, op, col2 = args
+                        on_clause = f"{col1} {op} {col2}"
+                    elif len(args) == 1 and callable(args[0]):
+                        # Composable syntax: .join('table', lambda j: ...)
+                        join_builder_fn = args[0]
+                        join_builder = JoinClauseBuilder()
+                        join_builder_fn(join_builder)
+                        on_clause = str(join_builder)
+                    else:
+                        raise ValueError(
+                            "Invalid arguments for join method. Use `join(table, col1, op, col2)` or `join(table, lambda j: ...)`."
+                        )
+
+                    join_clause = f"{sql_join_type} {table} ON {on_clause}"
+                    self._joins.append(join_clause)
+                    return self
+
+                return dynamic_raw_join_caller
+
+        # Handle where methods (e.g., where, andWhereIn)
+        where_match = re.match(
+            r"^(or|and)?(Where|WhereIn|WhereNotIn)$", name, re.IGNORECASE
+        )
+        if where_match:
+            conjunction_str, where_type_str = where_match.groups()
+
+            if not self._where_clauses:
+                if conjunction_str and conjunction_str.lower() != "and":
+                    raise RuntimeError(
+                        f"Cannot start a where clause with '{conjunction_str}'."
+                    )
+                conjunction = ""
+            else:
+                conjunction = (conjunction_str or "and").upper()
+
+            where_type = where_type_str.lower()
+
+            def dynamic_where_caller(*args):
+                if where_type == "where":
+                    if len(args) == 1 and callable(args[0]):
+                        self._add_where_internal(conjunction, args[0])
+                    elif len(args) == 3:
+                        self._add_where_internal(conjunction, *args)
+                    else:
+                        raise ValueError(
+                            "Invalid arguments for 'where' method. Use `where(column, operator, value)` or `where(lambda q: ...)`."
+                        )
+                elif where_type == "wherein":
+                    self._add_where_in_internal(conjunction, "IN", *args)
+                elif where_type == "wherenotin":
+                    self._add_where_in_internal(conjunction, "NOT IN", *args)
+                return self
+
+            return dynamic_where_caller
+
+        raise AttributeError(
+            f"'{type(self).__name__}' object has no attribute '{name}'"
+        )
+
+    def _build_where_clause(self, column: str, operator: str, value: Any) -> str:
+        """Formats a single where clause condition."""
+        formatted_value = value
+        if isinstance(value, str):
+            escaped_value = value.replace("'", "''")
+            formatted_value = f"'{escaped_value}'"
+        return f"{column} {operator} {formatted_value}"
+
+    def _add_where_internal(
+        self,
+        conjunction: str,
+        column_or_callable: Any,
+        op: Optional[str] = None,
+        val: Optional[Any] = None,
+    ):
+        """Internal handler for adding `where` clauses."""
+        if not self._where_clauses and conjunction:
+            raise RuntimeError(f"Cannot use '{conjunction}' on the first where clause.")
+
+        if callable(column_or_callable):
+            # Handle grouped where clauses, e.g., where(lambda q: q.where(...))
+            temp_builder = QueryBuilder(self._model_class)
+            column_or_callable(temp_builder)
+            if temp_builder._where_clauses:
+                grouped_clause_str = temp_builder._build_clause_list_string()
+                self._where_clauses.append((conjunction, f"({grouped_clause_str})"))
+        else:
+            # We can assert op is not None because of the checks in __getattr__
+            assert op is not None
+            clause = self._build_where_clause(column_or_callable, op, val)
+            self._where_clauses.append((conjunction, clause))
+
+    def _add_where_in_internal(self, conjunction: str, op: str, col: str, vals: list):
+        """Internal handler for adding `WHERE IN` and `WHERE NOT IN` clauses."""
+        if not self._where_clauses and conjunction:
+            raise RuntimeError(f"Cannot use '{conjunction}' on the first where clause.")
+
+        formatted_values = []
+        for v in vals:
+            if isinstance(v, str):
+                formatted_values.append(f"'{v.replace("'", "''")}'")
+            else:
+                formatted_values.append(str(v))
+        values_str = ", ".join(formatted_values)
+        clause = f"{col} {op} ({values_str})"
+        self._where_clauses.append((conjunction, clause))
+
+    def _build_clause_list_string(self) -> str:
+        """Builds the complete WHERE clause string from all parts."""
+        if not self._where_clauses:
+            return ""
+
+        # The first clause doesn't have a preceding conjunction
+        parts = [self._where_clauses[0][1]]
+        for conjunction, clause in self._where_clauses[1:]:
+            parts.append(f"{conjunction} {clause}")
+        return " ".join(parts)
+
+    def _join_related_internal(
+        self, join_type: str, relation_name: str, alias: Optional[str] = None
+    ):
+        """Internal handler for adding a join based on a defined relation."""
+        relation = self._model_class.relationMappings.get(relation_name)
+        if not relation:
+            raise ValueError(
+                f"Relation '{relation_name}' not found in model '{self._model_class.__name__}'"
+            )
+
+        related_model_class = self._resolve_model_class(relation["modelClass"])
+        join_info = relation["join"]
+
+        if "through" in join_info:
+            # Cast to the more specific TypedDict to satisfy mypy
+            through_join_info = cast(JoinMappingWithThrough, join_info)
+            self._add_through_join(
+                join_type, through_join_info, related_model_class, alias
+            )
+        else:
+            basic_join_info = cast(BasicJoinMapping, join_info)
+            self._add_basic_join(join_type, basic_join_info, related_model_class, alias)
+
+    def _resolve_model_class(
+        self, model_class_ref: Union[Type["Model"], str]
+    ) -> Type["Model"]:
+        """Resolves a model class reference (string or class) to a class type."""
+        if isinstance(model_class_ref, str):
+            # Try to find the model class in the global scope.
+            # This is a simple mechanism for resolving string references.
+            if model_class_ref in globals():
+                return globals()[model_class_ref]
+            else:
+                raise ValueError(
+                    f"Could not resolve model class string '{model_class_ref}'"
+                )
+        return model_class_ref
+
+    def _add_basic_join(
+        self,
+        join_type: str,
+        join_info: BasicJoinMapping,
+        related_model_class: Type["Model"],
+        alias: Optional[str] = None,
+    ):
+        """Adds a basic (e.g., one-to-one, one-to-many) join to the query."""
+        final_related_table_name = related_model_class.tableName
+        assert (
+            final_related_table_name is not None
+        ), "Model used in a relation must have a tableName"
+
+        from_col = join_info["from"]
+        to_col = join_info["to"]
+        on_clause = f"{from_col} = {to_col}"
+
+        join_table_part = final_related_table_name
+        if alias:
+            join_table_part = f"{final_related_table_name} AS {alias}"
+            # If an alias is used, update the `ON` clause to reference it.
+            to_table, to_column = to_col.split(".")
+            if to_table == final_related_table_name:
+                on_clause = f"{from_col} = {alias}.{to_column}"
+
+        join_clause = f"{join_type} {join_table_part} ON {on_clause}"
+        self._joins.append(join_clause)
+
+    def _add_through_join(
+        self,
+        join_type: str,
+        join_info: JoinMappingWithThrough,
+        related_model_class: Type["Model"],
+        alias: Optional[str] = None,
+    ):
+        """Adds a many-to-many join using a 'through' table."""
+        related_table_name_from_model = related_model_class.tableName
+        assert (
+            related_table_name_from_model is not None
+        ), "Model used in a relation must have a tableName"
+
+        # First join: from the base model's table to the 'through' table.
+        from_col = join_info["from"]
+        through_from_mapping = join_info["through"]["from"]
+
+        through_table_ref = through_from_mapping["table"]
+        through_table_name: str
+        if isinstance(through_table_ref, str):
+            through_table_name = through_table_ref
+        else:
+            table_name = through_table_ref.tableName
+            assert (
+                table_name is not None
+            ), "Model used as a through table must have a tableName"
+            through_table_name = table_name
+
+        through_from_key = through_from_mapping["key"]
+
+        on_clause1 = f"{from_col} = {through_table_name}.{through_from_key}"
+        # The join to the through table is always an INNER JOIN.
+        join_clause1 = f"INNER JOIN {through_table_name} ON {on_clause1}"
+        self._joins.append(join_clause1)
+
+        # Second join: from the 'through' table to the final related model's table.
+        through_to_mapping = join_info["through"]["to"]
+        through_to_key = through_to_mapping["key"]
+        to_col = join_info["to"]
+
+        on_clause2 = f"{through_table_name}.{through_to_key} = {to_col}"
+
+        join_table_part = related_table_name_from_model
+        if alias:
+            join_table_part = f"{related_table_name_from_model} AS {alias}"
+            # If an alias is used, update the `ON` clause to reference it.
+            to_table, to_column = to_col.split(".")
+            if to_table == related_table_name_from_model:
+                on_clause2 = (
+                    f"{through_table_name}.{through_to_key} = {alias}.{to_column}"
+                )
+
+        join_clause2 = f"{join_type} {join_table_part} ON {on_clause2}"
+        self._joins.append(join_clause2)

sustained/model.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Dict, Optional, Type
+
+from .types import RelationMapping
+
+if TYPE_CHECKING:
+    from .builder import QueryBuilder
+
+
+class Model:
+    """
+    A base model class that mimics Objection.js models for defining database tables
+    and their relationships.
+
+    To use this, create a subclass and define the `tableName` and, optionally,
+    `relationMappings`, `tableSchema`, and `database`.
+
+    Attributes:
+        database (str, optional): The name of the database. Defaults to None.
+        tableName (str): The name of the table in the database. Defaults to None.
+        tableSchema (str, optional): The schema of the table. Defaults to None.
+        relationMappings (Dict[str, RelationMapping]): A dictionary defining
+            relationships to other models.
+    """
+
+    database: Optional[str] = None
+    tableName: Optional[str] = None
+    tableSchema: Optional[str] = None
+    relationMappings: Dict[str, RelationMapping] = {}
+
+    def __init__(self, **kwargs):
+        """
+        Initializes a model instance, allowing attributes to be set from
+        keyword arguments.
+        """
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+
+    def __repr__(self):
+        """Provides a developer-friendly representation of the model instance."""
+        attributes = ", ".join(f"{k}={v!r}" for k, v in self.__dict__.items())
+        return f"{self.__class__.__name__}({attributes})"
+
+    def __getattr__(self, name: str) -> str:
+        """
+        Provides attribute-style access to table columns, which returns a
+        fully-qualified column name string for use in queries.
+
+        Example:
+            If a `User` model has `tableName = 'users'`, then `User().id` would
+            return `'users.id'`.
+
+        Raises:
+            AttributeError: If the attribute does not exist or if `tableName`
+                            is not defined on the model.
+        """
+        cls = self.__class__
+        if name.startswith("__") and name.endswith("__"):
+            raise AttributeError(f"'{cls.__name__}' object has no attribute '{name}'")
+
+        database = getattr(cls, "database", None)
+        table_schema = getattr(cls, "tableSchema", None)
+        table_name = getattr(cls, "tableName", None)
+
+        # We must have a table name to provide a column reference.
+        if table_name:
+            parts = []
+            if database:
+                parts.append(database)
+            if table_schema:
+                parts.append(table_schema)
+            parts.append(table_name)
+            parts.append(name)
+            return ".".join(parts)
+
+        raise AttributeError(f"'{cls.__name__}' object has no attribute '{name}'")
+
+    @classmethod
+    def query(cls) -> "QueryBuilder":
+        """
+        Starts a new query for this model.
+
+        Returns:
+            QueryBuilder: A new QueryBuilder instance for this model.
+        """
+        from .builder import QueryBuilder
+
+        return QueryBuilder(cls)
+
+
+def create_model(
+    name: str,
+    table_name: str,
+    mappings: Optional[Dict[str, RelationMapping]] = None,
+    table_schema: Optional[str] = None,
+    database: Optional[str] = None,
+) -> Type[Model]:
+    """
+    Dynamically creates a `Model` subclass.
+
+    This is useful when you need to define models programmatically instead of
+    declaratively.
+
+    Args:
+        name (str): The name of the new model class (e.g., "Animal").
+        table_name (str): The database table name for the model.
+        mappings (Dict[str, RelationMapping], optional): A dictionary of
+            relation mappings. Defaults to None.
+        table_schema (str, optional): The database schema. Defaults to None.
+        database (str, optional): The database name. Defaults to None.
+
+    Returns:
+        Type[Model]: A new class that inherits from `Model`.
+
+    Example:
+        .. code-block:: python
+
+            Person = create_model('Person', 'persons')
+
+            Animal = create_model(
+                'Animal',
+                'animals',
+                mappings={
+                    'owner': {
+                        'relation': RelationType.BelongsToOneRelation,
+                        'modelClass': Person,
+                        'join': {'from': 'animals.ownerId', 'to': 'persons.id'}
+                    }
+                }
+            )
+
+            query = Animal.query().select('name').joinRelated('owner')
+    """
+    if mappings is None:
+        mappings = {}
+
+    model_attrs = {"tableName": table_name, "relationMappings": mappings}
+
+    if table_schema:
+        model_attrs["tableSchema"] = table_schema
+    if database:
+        model_attrs["database"] = database
+
+    return type(name, (Model,), model_attrs)

sustained/types.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING, Dict, Type, TypedDict, Union
+
+if TYPE_CHECKING:
+    from .model import Model
+
+
+class RelationType(Enum):
+    """
+    Defines the types of relations between models, mirroring Objection.js relation types.
+    """
+
+    BelongsToOneRelation = "BelongsToOneRelation"
+    HasManyRelation = "HasManyRelation"
+    HasOneRelation = "HasOneRelation"
+    ManyToManyRelation = "ManyToManyRelation"
+
+
+BasicJoinMapping = TypedDict(
+    "BasicJoinMapping",
+    {
+        "from": str,
+        "to": str,
+    },
+)
+"""Defines a basic join between two tables."""
+
+ThroughJoinValue = TypedDict(
+    "ThroughJoinValue",
+    {
+        "table": Union[Type["Model"], str],
+        "key": str,
+    },
+)
+"""Specifies the intermediate table and key for a through relation."""
+
+ThroughJoinMapping = TypedDict(
+    "ThroughJoinMapping",
+    {
+        "from": ThroughJoinValue,
+        "to": ThroughJoinValue,
+    },
+)
+"""Defines the 'from' and 'to' parts of a 'through' clause in a many-to-many relation."""
+
+JoinMappingWithThrough = TypedDict(
+    "JoinMappingWithThrough",
+    {
+        "from": str,
+        "through": ThroughJoinMapping,
+        "to": str,
+    },
+)
+"""Defines a many-to-many join that includes an intermediate 'through' table."""
+
+Join = Union[BasicJoinMapping, JoinMappingWithThrough]
+"""A union of possible join mapping types."""
+
+
+class RelationMapping(TypedDict):
+    """
+    Describes a relationship between two models.
+
+    Attributes:
+        relation (RelationType): The type of the relation.
+        modelClass (Union[Type["Model"], str]): The related model class or its name.
+        join (Join): The join mapping that defines how the tables are connected.
+    """
+
+    relation: RelationType
+    modelClass: Union[Type["Model"], str]
+    join: Join

sustained-0.0.1.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: sustained
+Version: 0.0.1
+Summary: A Python query builder inspired by Objection.js
+Project-URL: Homepage, https://github.com/wetherc/sustained
+Project-URL: Issues, https://github.com/wetherc/sustained/issues
+Author-email: Christopher Wetherill <git@tbmh.org>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+
+# Sustained.py
+
+A Python query builder inspired by [Objection.js](https://vincit.github.io/objection.js/).
+
+## Installation
+
+This package is not available on PyPI and must be installed from source.
+
+```bash
+pip install .
+```
+
+## Usage
+
+```python
+from sustained import Model, RelationType, create_model
+
+class Person(Model):
+    database = 'my_db'
+    tableSchema = 'public'
+    tableName = 'persons'
+
+class Animal(Model):
+    tableName = 'animals'
+
+    relationMappings = {
+        'owner': {
+            'relation': RelationType.BelongsToOneRelation,
+            'modelClass': Person,
+            'join': {
+                'from': 'animals.ownerId',
+                'to': 'persons.id'
+            }
+        }
+    }
+
+# Build a query
+query = Animal.query().select('animals.name', 'persons.name').leftOuterJoinRelated('owner')
+
+print(query)
+# SELECT animals.name, persons.name FROM animals LEFT OUTER JOIN persons ON animals.ownerId = persons.id
+
+
+# Build a more complex query with a CTE and a raw join
+active_owners = Person.query().select('id').where('status', '=', 'active')
+
+query = (
+    Animal.query()
+    .with_('active_owners', active_owners)
+    .join('active_owners', 'animals.ownerId', '=', 'active_owners.id')
+    .select('animals.name')
+)
+
+print(query)
+# WITH active_owners AS (SELECT id FROM persons WHERE status = 'active') SELECT animals.name FROM animals JOIN active_owners ON animals.ownerId = active_owners.id
+```
+
+## Development
+
+This project uses `pre-commit` to enforce code quality and run tests before committing code.
+
+### Pre-commit Hooks Setup
+
+1.  **Install pre-commit:**
+    ```bash
+    pip install pre-commit
+    ```
+
+2.  **Install the Git hooks:**
+    From the root of the project directory, run:
+    ```bash
+    pre-commit install
+    ```
+
+Now, the pre-commit hooks (including `black`, `isort`, `mypy`, and unit tests) will run automatically on every commit.

sustained-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+sustained/__init__.py,sha256=-mugN3a1eK-C0585KOW4DBfcxzpZGVQUv4mun3Oo_Ps,1001
+sustained/builder.py,sha256=JJqzBOxAAShAV1kyIlXp4WvfRKAO0hMwiV8Cp02_Bak,17990
+sustained/model.py,sha256=afzdOJzJnJH26k8W_B0nBBAfbD0BeRHvgfVcoOI5Lqk,4765
+sustained/types.py,sha256=u5sHFG3QM8qAvYOtsCjYJdvX8r1BFJzx6ya-97ydhxY,1843
+sustained-0.0.1.dist-info/METADATA,sha256=4aMKH4ddejwQaxAOnJI4xEbaCdVPXpx5_hxzgwd7tO4,2380
+sustained-0.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sustained-0.0.1.dist-info/licenses/LICENSE,sha256=ESYyLizI0WWtxMeS7rGVcX3ivMezm-HOd5WdeOh-9oU,1056
+sustained-0.0.1.dist-info/RECORD,,

sustained-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sustained-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.