sustained 0.0.1__tar.gz

sustained-0.0.1/.gitignore

@@ -0,0 +1,137 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a parent script to a folder in a temporary
+#  directory. Only add PyInstaller folders to .gitignore if you are sure this is
+#  the only course of action.
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to the Pipenv docs, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   from different sources is a concern, you may want to ignore it.
+# Pipfile.lock
+
+# PEP 582; used by poetry and pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/

sustained-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,36 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+        name: isort (python)
+
+  - repo: https://github.com/psf/black
+    rev: 24.4.2
+    hooks:
+      - id: black
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: "v1.10.1"
+    hooks:
+      - id: mypy
+
+  - repo: local
+    hooks:
+      - id: unit-tests
+        name: Run unit tests
+        entry: python3 -m unittest discover -s tests
+        language: system
+        types: [python]
+        pass_filenames: false
+        always_run: true

sustained-0.0.1/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.

sustained-0.0.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,75 @@
+# 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/docs/filtering.md

@@ -0,0 +1,91 @@
+# Filtering Queries
+
+Sustained provides a dynamic API for adding `WHERE` clauses to your queries.
+
+[<-- Back to Index](./index.md)
+
+## Basic `where` Methods
+
+The most common way to filter is by using the `where`, `andWhere`, and `orWhere` methods. These are handled dynamically, so you can chain them as needed.
+
+A `where` clause takes three arguments: a column, an operator, and a value.
+
+```python
+from my_project import Movie
+
+# SELECT * FROM movies WHERE director = 'Quentin Tarantino'
+Movie.query().where('director', '=', 'Quentin Tarantino')
+
+# Chain multiple `where` clauses
+# SELECT * FROM movies WHERE release_year > 2000 AND rating > 8.5
+Movie.query().where('release_year', '>', 2000).andWhere('rating', '>', 8.5)
+
+# Use `orWhere` to add an alternative condition
+# SELECT * FROM movies WHERE genre = 'Sci-Fi' OR genre = 'Fantasy'
+Movie.query().where('genre', '=', 'Sci-Fi').orWhere('genre', '=', 'Fantasy')
+```
+> **Note:** The first `where` call in a chain cannot be an `orWhere`. It must be a plain `where` or `andWhere`.
+
+## `whereIn` and `whereNotIn`
+
+To filter against a list of values, use the `whereIn` and `whereNotIn` methods.
+
+### `whereIn`
+
+This generates a `WHERE col IN (...)` clause.
+
+```python
+# SELECT * FROM movies WHERE id IN (10, 25, 30)
+Movie.query().whereIn('id', [10, 25, 30])
+
+# You can also use `andWhereIn` and `orWhereIn`
+# SELECT * FROM movies WHERE release_year = 1999 AND genre IN ('Action', 'Sci-Fi')
+Movie.query().where('release_year', '=', 1999).andWhereIn('genre', ['Action', 'Sci-Fi'])
+```
+
+### `whereNotIn`
+
+This generates a `WHERE col NOT IN (...)` clause.
+
+```python
+# SELECT * FROM movies WHERE rating NOT IN (1, 2, 3)
+Movie.query().whereNotIn('rating', [1, 2, 3])
+```
+
+## Grouped `where` Clauses
+
+For complex logical groupings, you can pass a callable (like a lambda function) to any `where` method. The function will receive a temporary `QueryBuilder` instance that you can use to build the grouped condition.
+
+This is useful for creating conditions wrapped in parentheses, like `... AND (condition A OR condition B)`.
+
+```python
+# SELECT * FROM movies
+# WHERE genre = 'Action' AND (release_year < 1990 OR rating > 9.0)
+
+query = Movie.query().where('genre', '=', 'Action').andWhere(lambda q: (
+    q.where('release_year', '<', 1990).orWhere('rating', '>', 9.0)
+))
+```
+
+### Complex Grouping
+
+You can nest these groups as deeply as you need.
+
+```python
+# SELECT * FROM movies
+# WHERE status = 'available'
+# AND (
+#   (genre = 'Comedy' AND rating > 7) OR
+#   (genre = 'Drama' AND rating > 8)
+# )
+
+query = Movie.query()
+    .where('status', '=', 'available')
+    .andWhere(lambda q: (
+        q.where(lambda group1: (
+            group1.where('genre', '=', 'Comedy').andWhere('rating', '>', 7)
+        )).orWhere(lambda group2: (
+            group2.where('genre', '=', 'Drama').andWhere('rating', '>', 8)
+        ))
+    ))
+```

sustained-0.0.1/docs/index.md

@@ -0,0 +1,28 @@
+# Sustained Documentation
+
+Welcome to the documentation for Sustained, a Python query builder inspired by [Objection.js](https://vincit.github.io/objection.js/).
+
+This documentation provides a detailed guide on how to use the library to define models and build complex SQL queries in a programmatic way.
+
+## Getting Started
+
+If you are new to Sustained, it's recommended to read the guides in the following order:
+
+1.  **[Models](./models.md):** Learn how to define models that map to your database tables.
+2.  **[Queries](./queries.md):** Understand how to start queries and select data.
+3.  **[Filtering](./filtering.md):** Dive into the various `where` methods for filtering your results.
+4.  **[Relations and Joins](./relations.md):** Learn how to define relationships between models and join them in your queries.
+
+## API Reference
+
+The docstrings in the source code provide a comprehensive API reference. You can use Python's built-in `help()` function to get detailed information about any class or method.
+
+```python
+from sustained import Model, QueryBuilder
+
+# Get help on the Model class
+help(Model)
+
+# Get help on the QueryBuilder class
+help(QueryBuilder)
+```

sustained-0.0.1/docs/models.md

@@ -0,0 +1,100 @@
+# Defining Models
+
+
+The `Model` class is the foundation of sustained.py. Each model you create represents a database table.
+
+[<-- Back to Index](./index.md)
+
+## Basic Setup
+
+To define a model, create a class that inherits from `sustained.Model` and give it a `tableName`.
+
+```python
+from sustained import Model
+
+class Person(Model):
+    # This is the only required property.
+    tableName = 'persons'
+
+class Animal(Model):
+    tableName = 'animals'
+```
+
+### Namespace Properties
+
+For fully qualified table names, you can also specify `database` and `tableSchema`.
+
+```python
+class User(Model):
+    database = 'my_db'
+    tableSchema = 'public'
+    tableName = 'users'
+
+# This model will produce queries like:
+# SELECT * FROM my_db.public.users
+print(User.query())
+```
+These properties are used by the `QueryBuilder` to construct the `FROM` clause of your SQL queries.
+
+## Dynamic Model Creation
+
+In some cases, you might need to create models at runtime. The `create_model` function is provided for this purpose. It takes the desired class name and table name as arguments.
+
+```python
+from sustained import create_model, RelationType
+
+# A simple dynamic model
+Vehicle = create_model('Vehicle', 'vehicles')
+
+# You can use it immediately
+query = Vehicle.query().select('id', 'license_plate')
+print(query)
+# SELECT id, license_plate FROM vehicles
+
+
+# You can also define relations for dynamic models
+Person = create_model('Person', 'persons')
+
+Animal = create_model(
+    'Animal',
+    'animals',
+    mappings={
+        'owner': {
+            'relation': RelationType.BelongsToOneRelation,
+            'modelClass': Person,
+            'join': {'from': 'animals.ownerId', 'to': 'persons.id'}
+        }
+    }
+)
+
+# This works just like a statically defined model
+query = Animal.query().innerJoinRelated('owner')
+print(query)
+# SELECT * FROM animals INNER JOIN persons ON animals.ownerId = persons.id
+```
+
+## Column Name Access
+
+Model instances provide a convenient way to get fully-qualified column names for use in queries, which helps avoid ambiguity.
+
+```python
+person = Person()
+
+# Accessing an attribute on a model instance returns the qualified column name
+print(person.id)
+# "persons.id"
+
+# Use it in a select statement
+query = Person.query().select(person.firstName, person.lastName)
+print(query)
+# SELECT persons.firstName, persons.lastName FROM persons
+```
+
+If the model has a `database` or `tableSchema` defined, they will be included in the qualified name.
+
+```python
+user = User() # The model with `database` and `tableSchema`
+print(user.id)
+# "my_db.public.users.id"
+```
+This feature is particularly useful for writing complex joins and where clauses while ensuring you're always referencing the correct column.

sustained-0.0.1/docs/queries.md

@@ -0,0 +1,124 @@
+# Building Queries
+
+Once you have defined your models, you can start building queries using the `QueryBuilder`.
+
+[<-- Back to Index](./index.md)
+
+## Starting a Query
+
+All queries begin with the `query()` class method on a `Model` subclass. This returns a new `QueryBuilder` instance, which you can use to chain methods.
+
+```python
+from my_project import User
+
+# Get a query builder for the User model
+query_builder = User.query()
+```
+
+## Selecting Columns
+
+The `select()` method allows you to specify which columns your query should return.
+
+### Selecting Specific Columns
+
+Pass any number of column name strings to `select()`.
+
+```python
+# Builds: SELECT id, name, email FROM users
+query = User.query().select('id', 'name', 'email')
+```
+
+If `select()` is never called, the query will default to selecting all columns (`SELECT *`).
+
+### Using Column Name Access
+
+For clarity and to avoid ambiguity in joins, it's often a good idea to use the model's column access feature to get fully-qualified column names.
+
+```python
+user = User()
+person = Person()
+
+# Builds: SELECT users.id, persons.firstName FROM users...
+query = User.query().select(user.id, person.firstName)
+```
+
+## Joining Tables
+
+For simple joins where you don't have or need a pre-defined relation on your model, you can use the raw join methods. These methods are generated dynamically for each join type (`join`, `innerJoin`, `leftJoin`, `rightJoin`, etc.).
+
+They accept four arguments:
+1.  The table to join to.
+2.  The first column for the `ON` condition.
+3.  The operator for the `ON` condition.
+4.  The second column for the `ON` condition.
+
+```python
+# Builds: SELECT persons.*, animals.name FROM persons LEFT JOIN animals ON persons.id = animals.ownerId
+query = Person.query().leftJoin('animals', 'persons.id', '=', 'animals.ownerId')
+```
+
+### Complex Joins with Lambdas
+
+For joins that require multiple or complex `ON` conditions, you can pass a lambda function as the second argument to any of the `join` methods. This lambda receives a `JoinBuilder` object that you can use to construct the join conditions.
+
+The `JoinBuilder` has the following methods:
+*   `on(col1, op, col2)`: Adds the initial `ON` condition.
+*   `andOn(col1, op, col2)`: Adds an `AND` condition to the join.
+*   `orOn(col1, op, col2)`: Adds an `OR` condition to the join.
+
+```python
+# Builds:
+# SELECT * FROM users
+# JOIN accounts ON accounts.id = users.account_id AND accounts.enabled = 1 OR accounts.owner_id = users.id
+query = User.query().join(
+    'accounts',
+    lambda j: j.on('accounts.id', '=', 'users.account_id')
+    .andOn('accounts.enabled', '=', '1')
+    .orOn('accounts.owner_id', '=', 'users.id'),
+)
+```
+
+For more complex joins based on your data model, see the [Relations documentation](./relations.md).
+
+## Common Table Expressions (CTEs)
+
+You can add CTEs to your query using the `.with_()` method. Note the trailing underscore, which is necessary to avoid conflicting with Python's `with` keyword.
+
+The `.with_()` method takes two arguments:
+1.  An alias (string) for the CTE.
+2.  A `QueryBuilder` instance for the CTE's subquery.
+
+```python
+# Build a CTE for active users
+active_users_cte = User.query().select('id').where('status', '=', 'active')
+
+# Use the CTE in a main query to get their posts
+# (Assumes a Post model exists)
+posts_query = (
+    Post.query()
+    .with_('active_users', active_users_cte)
+    .join('active_users', 'posts.user_id', '=', 'active_users.id')
+    .select('posts.title')
+)
+
+# Builds:
+# WITH active_users AS (SELECT id FROM users WHERE status = 'active')
+# SELECT posts.title FROM posts JOIN active_users ON posts.user_id = active_users.id
+print(posts_query)
+```
+
+## Retrieving the SQL
+
+The `QueryBuilder` does not execute the query. It only builds the SQL string. To get the final SQL, simply convert the builder instance to a string.
+
+```python
+query = User.query().select('name').where('id', '=', 1)
+
+# Get the SQL string
+sql_string = str(query)
+
+print(sql_string)
+# "SELECT name FROM users WHERE id = 1"
+```
+
+This design allows you to use Sustained with any database driver. You build the query with Sustained, and then execute the resulting SQL string with your preferred library (e.g., `psycopg2`, `pyodbc`, etc.).