sgalchemy 0.1.0__tar.gz

sgalchemy-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+dist/
+.eggs/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage*
+.pytest_cache/
+.cache/
+
+# Type checker / linter caches
+.pyright/
+.mypy_cache/
+.ruff_cache/
+pyrightconfig.json
+
+# Editors
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

sgalchemy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the sgalchemy authors
+
+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.

sgalchemy-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.5
+Name: sgalchemy
+Version: 0.1.0
+Summary: SQLAlchemy-style ORM for Autodesk Flow Production Tracking
+Project-URL: Documentation, https://github.com/dactylo/sgalchemy/tree/main/docs
+Project-URL: Homepage, https://github.com/dactylo/sgalchemy
+Project-URL: Issues, https://github.com/dactylo/sgalchemy/issues
+Project-URL: Repository, https://github.com/dactylo/sgalchemy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: flow-production-tracking,orm,shotgrid,shotgun,sqlalchemy
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: api
+Requires-Dist: sg-python-api<0.2,>=0.1; extra == 'api'
+Provides-Extra: async
+Requires-Dist: sg-python-api[async]<0.2,>=0.1; extra == 'async'
+Provides-Extra: official
+Requires-Dist: shotgun-api3>=3.10.2; extra == 'official'
+Description-Content-Type: text/markdown
+
+# sgalchemy
+
+sgalchemy is a SQLAlchemy-style ORM for Autodesk Flow Production Tracking. It gives pipeline code
+typed entity classes reflected from your site's schema, `select()` queries with relationship
+loaders, and a `Session` that keeps one object per record and sends your changes only when you call
+`commit()`. You decide when the network is used: reading an attribute never makes a hidden provider
+call.
+
+This documentation uses SG for Flow Production Tracking, formerly named Shotgun and ShotGrid.
+
+## Why use it?
+
+Calling the provider API directly means working with dictionaries: you choose field lists for each
+`find()`, track which records changed, and assemble `batch()` requests yourself. sgalchemy handles
+that bookkeeping while keeping every provider call explicit.
+
+The SQLAlchemy concepts are familiar, but SG is not a relational database, and sgalchemy follows
+the provider where the two differ:
+
+- Schema loading is explicit. Call `load_schema()` before you use entity classes; sgalchemy caches
+  the schema on disk so later runs can skip the fetch.
+- Queries never send pending changes. `commit()` is the only write boundary.
+- Reading a field or relationship that a query did not load raises an error instead of calling the
+  network. Synchronous code can opt into `lazyload()`.
+- A commit is atomic only when it compiles to one transactional `batch()` call. Revives, thumbnail
+  uploads, and creates that link to other new records need extra calls, so a failure can leave part
+  of a commit applied. [Sessions and writes](https://github.com/dactylo/sgalchemy/blob/v0.1.0/docs/sessions.md) explains how to recover.
+
+## Installation
+
+You need Python 3.11 or newer and one compatible SG API provider. From a checkout, install
+sgalchemy with the extra for your provider. For Autodesk's provider, run:
+
+```sh
+python -m pip install '.[official]'
+```
+
+Choose exactly one extra, and replace `official` in the command to pick another:
+
+- `official` installs Autodesk's `shotgun-api3` for synchronous and threaded async engines.
+- `api` installs `sg-python-api` for synchronous and threaded async engines.
+- `async` installs `sg-python-api` with its native async client, which also supports native async
+  engines.
+
+If your application already supplies a compatible API client, install the base package with
+`python -m pip install .` and install the client separately.
+
+## Quick start
+
+This example queries in-progress shots and creates one shot. It authenticates with a session token
+that your application supplies in `SHOTGUN_SESSION_TOKEN`; see
+[Connections and authentication](https://github.com/dactylo/sgalchemy/blob/v0.1.0/docs/authentication.md) for other credentials. Replace the site
+URL and the status and code values with your studio's, and add any other fields your site requires
+for a new shot. Run it against a test site: the commit creates a real record.
+
+```python
+import os
+
+from sgalchemy import Session, create_engine, select
+
+engine = create_engine(
+    'https://example.shotgunstudio.com',
+    session_token=os.environ['SHOTGUN_SESSION_TOKEN'],
+)
+try:
+    engine.load_schema()
+    from sgalchemy.entities import Shot
+
+    with Session(engine) as session:
+        shots = session.scalars(select(Shot).where(Shot.sg_status_list == 'ip'))
+        print(f'{len(shots)} shots in progress')
+
+        new_shot = Shot.new(code='sq010_sh020')
+        session.add(new_shot)
+        session.commit()
+        print(new_shot)
+finally:
+    engine.dispose()
+```
+
+The script prints the number of matching shots, then the new shot with its server ID, such as
+`Shot(id=1234, code='sq010_sh020')`.
+
+`load_schema()` fetches the site schema, or reads a fresh cached copy, before you import entity
+classes. The query does not send the pending create; `session.commit()` does. Leaving the `with`
+block closes the session and discards any work you did not commit. If a commit fails after a
+provider call, [check what was applied](https://github.com/dactylo/sgalchemy/blob/v0.1.0/docs/sessions.md#recover-from-a-failed-commit) before you
+retry.
+
+To give your type checker the reflected fields of `Shot`, generate site-specific stubs; see
+[typed stubs](https://github.com/dactylo/sgalchemy/blob/v0.1.0/docs/tooling.md#generate-typed-stubs).
+
+## Documentation
+
+| If you want to...                                           | Read                                                            |
+| ----------------------------------------------------------- | --------------------------------------------------------------- |
+| Choose credentials and recover when SG rejects them         | [Connections and authentication](https://github.com/dactylo/sgalchemy/blob/v0.1.0/docs/authentication.md)        |
+| Write queries and load related entities                     | [Queries and relationships](https://github.com/dactylo/sgalchemy/blob/v0.1.0/docs/relationships.md)              |
+| Commit changes, upload thumbnails, or use session factories | [Sessions and writes](https://github.com/dactylo/sgalchemy/blob/v0.1.0/docs/sessions.md)                         |
+| Recover from a failed or partial commit                     | [Failed commits](https://github.com/dactylo/sgalchemy/blob/v0.1.0/docs/sessions.md#recover-from-a-failed-commit) |
+| Use sgalchemy from asyncio code                             | [Async usage](https://github.com/dactylo/sgalchemy/blob/v0.1.0/docs/async.md)                                    |
+| Type-check with stubs, manage the schema cache, or test     | [Typing, schema cache, and testing](https://github.com/dactylo/sgalchemy/blob/v0.1.0/docs/tooling.md)            |
+| See changes by version                                      | [Changelog](https://github.com/dactylo/sgalchemy/blob/v0.1.0/CHANGELOG.md)                                       |
+
+## Development
+
+See the [development guide](https://github.com/dactylo/sgalchemy/blob/v0.1.0/docs/development.md) for the required tools, CI, and dependency locks.
+With those tools installed, run:
+
+```sh
+make setup
+make check
+```
+
+The checks never contact a live SG site unless you configure the opt-in live test.
+
+## License
+
+sgalchemy is available under the [MIT License](https://github.com/dactylo/sgalchemy/blob/v0.1.0/LICENSE). It is an independent project and is not
+affiliated with or endorsed by Autodesk. Flow Production Tracking is a product of Autodesk, Inc.

sgalchemy-0.1.0/README.md

@@ -0,0 +1,120 @@
+# sgalchemy
+
+sgalchemy is a SQLAlchemy-style ORM for Autodesk Flow Production Tracking. It gives pipeline code
+typed entity classes reflected from your site's schema, `select()` queries with relationship
+loaders, and a `Session` that keeps one object per record and sends your changes only when you call
+`commit()`. You decide when the network is used: reading an attribute never makes a hidden provider
+call.
+
+This documentation uses SG for Flow Production Tracking, formerly named Shotgun and ShotGrid.
+
+## Why use it?
+
+Calling the provider API directly means working with dictionaries: you choose field lists for each
+`find()`, track which records changed, and assemble `batch()` requests yourself. sgalchemy handles
+that bookkeeping while keeping every provider call explicit.
+
+The SQLAlchemy concepts are familiar, but SG is not a relational database, and sgalchemy follows
+the provider where the two differ:
+
+- Schema loading is explicit. Call `load_schema()` before you use entity classes; sgalchemy caches
+  the schema on disk so later runs can skip the fetch.
+- Queries never send pending changes. `commit()` is the only write boundary.
+- Reading a field or relationship that a query did not load raises an error instead of calling the
+  network. Synchronous code can opt into `lazyload()`.
+- A commit is atomic only when it compiles to one transactional `batch()` call. Revives, thumbnail
+  uploads, and creates that link to other new records need extra calls, so a failure can leave part
+  of a commit applied. [Sessions and writes](docs/sessions.md) explains how to recover.
+
+## Installation
+
+You need Python 3.11 or newer and one compatible SG API provider. From a checkout, install
+sgalchemy with the extra for your provider. For Autodesk's provider, run:
+
+```sh
+python -m pip install '.[official]'
+```
+
+Choose exactly one extra, and replace `official` in the command to pick another:
+
+- `official` installs Autodesk's `shotgun-api3` for synchronous and threaded async engines.
+- `api` installs `sg-python-api` for synchronous and threaded async engines.
+- `async` installs `sg-python-api` with its native async client, which also supports native async
+  engines.
+
+If your application already supplies a compatible API client, install the base package with
+`python -m pip install .` and install the client separately.
+
+## Quick start
+
+This example queries in-progress shots and creates one shot. It authenticates with a session token
+that your application supplies in `SHOTGUN_SESSION_TOKEN`; see
+[Connections and authentication](docs/authentication.md) for other credentials. Replace the site
+URL and the status and code values with your studio's, and add any other fields your site requires
+for a new shot. Run it against a test site: the commit creates a real record.
+
+```python
+import os
+
+from sgalchemy import Session, create_engine, select
+
+engine = create_engine(
+    'https://example.shotgunstudio.com',
+    session_token=os.environ['SHOTGUN_SESSION_TOKEN'],
+)
+try:
+    engine.load_schema()
+    from sgalchemy.entities import Shot
+
+    with Session(engine) as session:
+        shots = session.scalars(select(Shot).where(Shot.sg_status_list == 'ip'))
+        print(f'{len(shots)} shots in progress')
+
+        new_shot = Shot.new(code='sq010_sh020')
+        session.add(new_shot)
+        session.commit()
+        print(new_shot)
+finally:
+    engine.dispose()
+```
+
+The script prints the number of matching shots, then the new shot with its server ID, such as
+`Shot(id=1234, code='sq010_sh020')`.
+
+`load_schema()` fetches the site schema, or reads a fresh cached copy, before you import entity
+classes. The query does not send the pending create; `session.commit()` does. Leaving the `with`
+block closes the session and discards any work you did not commit. If a commit fails after a
+provider call, [check what was applied](docs/sessions.md#recover-from-a-failed-commit) before you
+retry.
+
+To give your type checker the reflected fields of `Shot`, generate site-specific stubs; see
+[typed stubs](docs/tooling.md#generate-typed-stubs).
+
+## Documentation
+
+| If you want to...                                           | Read                                                            |
+| ----------------------------------------------------------- | --------------------------------------------------------------- |
+| Choose credentials and recover when SG rejects them         | [Connections and authentication](docs/authentication.md)        |
+| Write queries and load related entities                     | [Queries and relationships](docs/relationships.md)              |
+| Commit changes, upload thumbnails, or use session factories | [Sessions and writes](docs/sessions.md)                         |
+| Recover from a failed or partial commit                     | [Failed commits](docs/sessions.md#recover-from-a-failed-commit) |
+| Use sgalchemy from asyncio code                             | [Async usage](docs/async.md)                                    |
+| Type-check with stubs, manage the schema cache, or test     | [Typing, schema cache, and testing](docs/tooling.md)            |
+| See changes by version                                      | [Changelog](CHANGELOG.md)                                       |
+
+## Development
+
+See the [development guide](docs/development.md) for the required tools, CI, and dependency locks.
+With those tools installed, run:
+
+```sh
+make setup
+make check
+```
+
+The checks never contact a live SG site unless you configure the opt-in live test.
+
+## License
+
+sgalchemy is available under the [MIT License](LICENSE). It is an independent project and is not
+affiliated with or endorsed by Autodesk. Flow Production Tracking is a product of Autodesk, Inc.

sgalchemy-0.1.0/pyproject.toml

@@ -0,0 +1,160 @@
+# ==========================================================
+# Build System
+# ==========================================================
+[build-system]
+build-backend = "hatchling.build"
+requires = [ "editables~=0.3", "hatch-fancy-pypi-readme>=25.1", "hatchling>=1.27" ]
+
+# ==========================================================
+# Project Metadata
+# ==========================================================
+[project]
+name = "sgalchemy"
+version = "0.1.0"
+description = "SQLAlchemy-style ORM for Autodesk Flow Production Tracking"
+keywords = [ "flow-production-tracking", "orm", "shotgrid", "shotgun", "sqlalchemy" ]
+license = "MIT"
+license-files = [ "LICENSE" ]
+requires-python = ">=3.11"
+classifiers = [
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+  "Typing :: Typed",
+]
+dynamic = [ "readme" ]
+dependencies = []
+optional-dependencies.api = [
+  "sg-python-api>=0.1,<0.2",
+]
+optional-dependencies.async = [
+  "sg-python-api[async]>=0.1,<0.2",
+]
+optional-dependencies.official = [
+  "shotgun-api3>=3.10.2",
+]
+urls.Documentation = "https://github.com/dactylo/sgalchemy/tree/main/docs"
+urls.Homepage = "https://github.com/dactylo/sgalchemy"
+urls.Issues = "https://github.com/dactylo/sgalchemy/issues"
+urls.Repository = "https://github.com/dactylo/sgalchemy"
+scripts.sgalchemy = "sgalchemy._cli:main"
+
+[dependency-groups]
+dev = [
+  "mdformat",
+  "mdformat-config",
+  "mdformat-frontmatter",
+  "mdformat-gfm",
+  "mdformat-pyproject",
+  "mdformat-ruff",
+  "mdformat-shfmt",
+  "pyproject-fmt",
+  "ruff",
+  { include-group = "test" },
+]
+test = [
+  "pyright",
+  "pytest",
+  "pytest-xdist>=3.2",
+]
+
+[tool.hatch]
+metadata.hooks.fancy-pypi-readme.content-type = "text/markdown"
+metadata.hooks.fancy-pypi-readme.fragments = [ { path = "README.md" } ]
+build.targets.wheel.packages = [ "src/sgalchemy" ]
+build.targets.sdist.include = [ "/README.md", "/src/sgalchemy" ]
+
+# Keep checkout links relative; package links target this release.
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
+pattern = '(!\[[^\]\n]*\]\()(?![A-Za-z][A-Za-z0-9+.-]*:|[/#])(?:\./)?([^\s)]+)(\))'
+replacement = '\1https://raw.githubusercontent.com/dactylo/sgalchemy/v$HFPR_VERSION/\2\3'
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.substitutions]]
+pattern = '(?<!!)(\[[^\]\n]+\]\()(?![A-Za-z][A-Za-z0-9+.-]*:|[/#])(?:\./)?([^\s)]+)(\))'
+replacement = '\1https://github.com/dactylo/sgalchemy/blob/v$HFPR_VERSION/\2\3'
+
+[tool.uv]
+# CI supplies the native Taplo CLI; its Python package lacks Linux/Windows ARM wheels.
+exclude-dependencies = [
+  { package = { name = "mdformat-config", version = "0.2.1" }, dependencies = [ "taplo" ] },
+]
+
+# ==========================================================
+# Ruff Configuration
+# ==========================================================
+[tool.ruff]
+target-version = "py311"
+line-length = 99
+format.quote-style = "single"
+format.exclude = [ "*.md" ]
+lint.select = [ "ALL" ]
+lint.ignore = [
+  "COM812", # Conflicts with the Ruff formatter
+  "CPY001", # Copyright notices are not required
+  "EM101",  # Exception must not use string literal
+  "EM102",  # Exception must not use f-string literal
+  "FBT001", # Boolean positional arg in function definition
+  "FBT002", # Boolean default value in function definition
+  "Q000",   # Conflicts with the Ruff formatter
+  "Q003",   # Conflicts with the Ruff formatter
+  "T201",   # print() found
+  "TRY003", # Avoid specifying long messages outside exception class
+]
+lint.per-file-ignores."src/sgalchemy/_core/_engine.py" = [ "SLF001" ]
+lint.per-file-ignores."src/sgalchemy/_orm/_async_session.py" = [ "SLF001" ]
+lint.per-file-ignores."src/sgalchemy/_orm/_uow.py" = [ "SLF001" ]
+lint.per-file-ignores."tests/**/*.py" = [
+  "D",       # No docstrings required in tests
+  "INP001",  # pytest rootdir-style tests directory has no __init__.py by design
+  "PLR2004", # Allow magic values in tests
+  "S101",    # Allow asserts in tests
+  "S603",    # Allow subprocess calls in tests
+  "S607",    # Allow partial executable paths in tests
+  "SLF001",  # Tests intentionally inspect and patch private state
+]
+lint.isort.known-first-party = [ "sgalchemy" ]
+lint.pydocstyle.convention = "google"
+
+[tool.pyproject-fmt]
+max_supported_python = "3.15"
+
+# ==========================================================
+# Pyright Configuration
+# ==========================================================
+[tool.pyright]
+pythonVersion = "3.11"  # Keep in sync with tool.ruff.target-version
+typeCheckingMode = "strict"
+extraPaths = [ ".", "src" ]
+executionEnvironments = [
+  { root = "tests", reportPrivateUsage = "none" },
+  { root = "." },
+]
+
+# ==========================================================
+# Pytest Configuration
+# ==========================================================
+[tool.pytest]
+ini_options.testpaths = [ "tests" ]
+ini_options.pythonpath = [ "src" ]
+ini_options.addopts = [ "-q", "--strict-markers", "--tb=short" ]
+ini_options.markers = [
+  "live: requires explicit Flow Production Tracking test-site configuration",
+  "mockgun_gap: exercises behavior Mockgun cannot emulate; skipped against the Mockgun backend",
+  "native_async: exercises native async provider behavior",
+  "provider_contract: exercises the selected real provider without credentials",
+  "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+]
+ini_options.faulthandler_timeout = 300
+
+[tool.defsort]
+method-bodies = "across-categories"
+
+# ==========================================================
+# Mdformat Configuration (Requires mdformat-pyproject)
+# ==========================================================
+[tool.mdformat]
+wrap = 99  # Keep in sync with tool.ruff.line-length
+number = true

sgalchemy-0.1.0/src/sgalchemy/__init__.py

@@ -0,0 +1,101 @@
+"""Build reflected queries and manage explicit entity reads and writes.
+
+Create an engine, call its `load_schema()` method, and obtain reflected classes
+from `engine.entities`. Async engines require awaited schema preparation.
+Queries never autoflush staged changes; call `Session.commit()` or await
+`AsyncSession.commit()` explicitly.
+
+Factories use the process default Registry unless an explicit Registry or
+`bind_default=False` selects isolation. Importing this package installs the
+synchronous `Entity.find()` callback; `connect()` configures its default
+session. Importing the package performs no provider or schema-cache I/O.
+"""
+
+from sgalchemy._core._async_engine import AsyncEngine, create_async_engine
+from sgalchemy._core._engine import Engine, create_engine
+from sgalchemy._core._expressions import FieldExpr, and_, func, or_, raw
+from sgalchemy._core._options import defer, joinedload, lazyload, load_only, selectinload
+from sgalchemy._core._registry import (
+    Entity,
+    InspectionInfo,
+    Registry,
+    default_registry,
+    inspect,
+    set_default_registry,
+)
+from sgalchemy._core._result import Result, Row
+from sgalchemy._core._statement import Select, select
+from sgalchemy._errors import (
+    CommitError,
+    CompilationError,
+    RefreshRequiredError,
+    RelationshipTargetUnavailableError,
+    RetiredEntityWriteError,
+    SchemaUnavailableError,
+    SgalchemyError,
+    StaleObjectError,
+    UnfetchedFieldError,
+)
+from sgalchemy._orm import (
+    AsyncScopedSession,
+    AsyncSession,
+    AsyncSessionFactory,
+    ScopedSession,
+    Session,
+    SessionFactory,
+    async_scoped_session,
+    async_sessionmaker,
+    connect,
+    scoped_session,
+    sessionmaker,
+)
+from sgalchemy._shotgun import AsyncShotgunLike, ShotgunLike
+
+__all__ = [
+    'AsyncEngine',
+    'AsyncScopedSession',
+    'AsyncSession',
+    'AsyncSessionFactory',
+    'AsyncShotgunLike',
+    'CommitError',
+    'CompilationError',
+    'Engine',
+    'Entity',
+    'FieldExpr',
+    'InspectionInfo',
+    'RefreshRequiredError',
+    'Registry',
+    'RelationshipTargetUnavailableError',
+    'Result',
+    'RetiredEntityWriteError',
+    'Row',
+    'SchemaUnavailableError',
+    'ScopedSession',
+    'Select',
+    'Session',
+    'SessionFactory',
+    'SgalchemyError',
+    'ShotgunLike',
+    'StaleObjectError',
+    'UnfetchedFieldError',
+    'and_',
+    'async_scoped_session',
+    'async_sessionmaker',
+    'connect',
+    'create_async_engine',
+    'create_engine',
+    'default_registry',
+    'defer',
+    'func',
+    'inspect',
+    'joinedload',
+    'lazyload',
+    'load_only',
+    'or_',
+    'raw',
+    'scoped_session',
+    'select',
+    'selectinload',
+    'sessionmaker',
+    'set_default_registry',
+]

sgalchemy-0.1.0/src/sgalchemy/__main__.py

@@ -0,0 +1,8 @@
+"""Run the supported `python -m sgalchemy` command-line entry point."""
+
+import sys
+
+from sgalchemy._cli import main
+
+if __name__ == '__main__':
+    sys.exit(main())