sg-widgets-qt 0.1.0__tar.gz

sg_widgets_qt-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.env.local
+.venv*
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+shots/**/*.png
+.qa/
+.idea/
+.DS_Store

sg_widgets_qt-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project follows
+[semantic versioning](https://semver.org/spec/v2.0.0.html). While the version is 0.x, a minor
+release may change a name, a prop or a signal.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-20
+
+First release, from the port of [sg-widgets](https://github.com/ksallee/sg-widgets).
+
+### Added
+
+- `sg_widgets_core`: field data types and their operators, the filter tree and its serialisation,
+  status logic, formatters, parsers, the query cache, the `SgClient` protocol, `ShotgunClient` on
+  shotgun_api3 and `MockClient` over generated fixtures. No Qt.
+- `sg_widgets_qt`: the theme with light and dark palettes, the painted primitives, and the widgets:
+  thumbnails, avatars, the field editors, the pickers for entities, fields, statuses and columns,
+  the entity table, grid, tree and card, the collection and search controls, and the filter editor.
+- The showcase, `python -m sg_widgets_qt.showcase`: one page per widget with a demo, the props,
+  signals, slots and keyboard tables, and the prose. It runs on the mock site, and on a live site
+  through `.env.local`.
+- `py.typed` in both packages.
+- Gates on every pull request and on pushes to `dev` and `main`: ruff, and pytest offscreen on
+  PySide6 and on PyQt5, on Python 3.9.
+- Release to PyPI by trusted publishing when a GitHub release is published.
+
+[Unreleased]: https://github.com/ksallee/sg-widgets-qt/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/ksallee/sg-widgets-qt/releases/tag/v0.1.0

sg_widgets_qt-0.1.0/LICENSE

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

sg_widgets_qt-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.5
+Name: sg-widgets-qt
+Version: 0.1.0
+Summary: Flow Production Tracking widgets for Qt, a port of sg-widgets on qtpy and shotgun_api3
+Project-URL: Homepage, https://github.com/ksallee/sg-widgets-qt
+Project-URL: Documentation, https://github.com/ksallee/sg-widgets-qt/tree/main/docs
+Project-URL: Issues, https://github.com/ksallee/sg-widgets-qt/issues
+Project-URL: Changelog, https://github.com/ksallee/sg-widgets-qt/blob/main/CHANGELOG.md
+Project-URL: Source, https://github.com/ksallee/sg-widgets-qt
+Author: Kevin Sallee
+License-Expression: MIT
+License-File: LICENSE
+Keywords: flow-production-tracking,pyqt,pyside,qt,shotgrid,shotgun,vfx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.9
+Requires-Dist: qtpy>=2.4
+Requires-Dist: shotgun-api3>=3.5
+Provides-Extra: pyqt5
+Requires-Dist: pyqt5; extra == 'pyqt5'
+Provides-Extra: pyside6
+Requires-Dist: pyside6; extra == 'pyside6'
+Description-Content-Type: text/markdown
+
+# sg-widgets-qt
+
+Flow Production Tracking (formerly ShotGrid) widgets for Qt: pickers, editors, tables, trees, grids
+and search. For pipeline developers writing tools inside Maya, Houdini, Nuke, RV or a standalone
+app.
+
+![An entity table grouped by status, with status badges and thumbnails](https://raw.githubusercontent.com/ksallee/sg-widgets-qt/main/docs/screenshots/entity-table-light.png)
+
+## Install
+
+```sh
+pip install sg-widgets-qt
+uv add sg-widgets-qt
+```
+
+Python 3.9 and up. The package brings `shotgun_api3` and `qtpy` and no Qt binding, because a DCC
+imports its own before your code runs. Outside a DCC, name a binding as an extra.
+
+```sh
+pip install "sg-widgets-qt[pyside6]"
+pip install "sg-widgets-qt[pyqt5]"
+```
+
+Every Qt import here goes through [qtpy](https://github.com/spyder-ide/qtpy), so one widget runs on
+PySide2, PySide6, PyQt5 and PyQt6, and on whichever of them the host imported first.
+
+## A first widget
+
+Three environment values point at a site: `FPT_API_SITE_URL`, `FPT_API_SCRIPT_NAME` and
+`FPT_API_API_KEY`.
+
+```python
+from qtpy.QtWidgets import QApplication
+from sg_widgets_core import ShotgunClient, create_sg_context
+from sg_widgets_qt.widgets.entity_picker import EntityPicker
+
+app = QApplication([])
+context = create_sg_context(ShotgunClient.from_env())
+picker = EntityPicker(entity_types=["Shot"], context=context)
+picker.value_changed.connect(lambda ref, row: print(ref))
+picker.show()
+app.exec_()
+```
+
+The context is built once and handed to every widget. The same picker runs on a generated site,
+with no credentials and no network.
+
+```python
+from sg_widgets_core import MockClient, create_sg_context
+
+context = create_sg_context(MockClient())
+picker = EntityPicker(entity_types=["Shot"], context=context)
+```
+
+## The showcase
+
+```sh
+python -m sg_widgets_qt.showcase
+```
+
+One page per widget, with a live demo, the props, signals, slots and keyboard tables, and the docs
+prose. The pages ship inside the package. The demos run on the mock, so the showcase needs no
+site; its toolbar offers Live where the three values above are set.
+
+## The widgets
+
+| | |
+|---|---|
+| ![An entity multi picker open on its results](https://raw.githubusercontent.com/ksallee/sg-widgets-qt/main/docs/screenshots/entity-multi-picker-light.png) | A picker searches the site, holds what was ticked as chips, and emits references. |
+| ![A filter editor holding one status condition](https://raw.githubusercontent.com/ksallee/sg-widgets-qt/main/docs/screenshots/filter-editor-light.png) | The filter editor builds a condition tree and serialises it for the API. |
+| ![A status picker open on the statuses of one project](https://raw.githubusercontent.com/ksallee/sg-widgets-qt/main/docs/screenshots/status-picker-light.png) | Statuses carry the site's own names, codes, colours and icons, per project. |
+| ![Global search, its results grouped by entity type](https://raw.githubusercontent.com/ksallee/sg-widgets-qt/main/docs/screenshots/global-search-light.png) | Global search reads across entity types and marks what matched. |
+| ![An entity grid of thumbnails](https://raw.githubusercontent.com/ksallee/sg-widgets-qt/main/docs/screenshots/entity-grid-light.png) | A table, a grid and a tree page a set, sort it, group it and edit a cell. |
+| ![The entity table in the dark theme](https://raw.githubusercontent.com/ksallee/sg-widgets-qt/main/docs/screenshots/entity-table-dark.png) | Every widget wears a light and a dark theme, or the host application's palette. |
+
+Every shot above reads a live site. [One page per
+widget](https://github.com/ksallee/sg-widgets-qt/tree/main/docs/widgets) says what each one takes
+and emits, beside
+[the introduction](https://github.com/ksallee/sg-widgets-qt/blob/main/docs/start/introduction.md),
+[install](https://github.com/ksallee/sg-widgets-qt/blob/main/docs/start/install.md) and
+[the core](https://github.com/ksallee/sg-widgets-qt/blob/main/docs/core/index.md).
+
+## How it relates to sg-widgets
+
+This is a port of [sg-widgets](https://github.com/ksallee/sg-widgets), whose React and Svelte
+widgets carry the same names, props and behaviour, and whose
+[documentation site](https://sg-widgets.vercel.app) is the reference for what a widget does; the
+pages here say where Qt or Python forced a difference. The framework-neutral half comes with it as
+`sg_widgets_core`, which holds the field data types, the operator vocabularies, the filter tree,
+status logic, the formatters, the parsers, the client protocol and a generated mock site, and
+imports no Qt, so it runs in a farm job as well as in a window. What either repo claims about the
+API is measured in [sg-groundtruth](https://github.com/ksallee/sg-groundtruth) and cited where it
+is relied on.
+
+## Status
+
+Alpha. 52 widgets, 27 core modules and 55 documentation pages are complete, on Python 3.9 through
+3.13 and on Qt 5.15 and Qt 6. Both packages carry `py.typed`. Names, props and signals can still
+change between 0.x releases, and the
+[changelog](https://github.com/ksallee/sg-widgets-qt/blob/main/CHANGELOG.md) records what changed.
+Ask for a widget, report a defect or say what reads wrong in the
+[issues](https://github.com/ksallee/sg-widgets-qt/issues).
+
+## Licence
+
+MIT. See [LICENSE](https://github.com/ksallee/sg-widgets-qt/blob/main/LICENSE).

sg_widgets_qt-0.1.0/README.md

@@ -0,0 +1,106 @@
+# sg-widgets-qt
+
+Flow Production Tracking (formerly ShotGrid) widgets for Qt: pickers, editors, tables, trees, grids
+and search. For pipeline developers writing tools inside Maya, Houdini, Nuke, RV or a standalone
+app.
+
+![An entity table grouped by status, with status badges and thumbnails](https://raw.githubusercontent.com/ksallee/sg-widgets-qt/main/docs/screenshots/entity-table-light.png)
+
+## Install
+
+```sh
+pip install sg-widgets-qt
+uv add sg-widgets-qt
+```
+
+Python 3.9 and up. The package brings `shotgun_api3` and `qtpy` and no Qt binding, because a DCC
+imports its own before your code runs. Outside a DCC, name a binding as an extra.
+
+```sh
+pip install "sg-widgets-qt[pyside6]"
+pip install "sg-widgets-qt[pyqt5]"
+```
+
+Every Qt import here goes through [qtpy](https://github.com/spyder-ide/qtpy), so one widget runs on
+PySide2, PySide6, PyQt5 and PyQt6, and on whichever of them the host imported first.
+
+## A first widget
+
+Three environment values point at a site: `FPT_API_SITE_URL`, `FPT_API_SCRIPT_NAME` and
+`FPT_API_API_KEY`.
+
+```python
+from qtpy.QtWidgets import QApplication
+from sg_widgets_core import ShotgunClient, create_sg_context
+from sg_widgets_qt.widgets.entity_picker import EntityPicker
+
+app = QApplication([])
+context = create_sg_context(ShotgunClient.from_env())
+picker = EntityPicker(entity_types=["Shot"], context=context)
+picker.value_changed.connect(lambda ref, row: print(ref))
+picker.show()
+app.exec_()
+```
+
+The context is built once and handed to every widget. The same picker runs on a generated site,
+with no credentials and no network.
+
+```python
+from sg_widgets_core import MockClient, create_sg_context
+
+context = create_sg_context(MockClient())
+picker = EntityPicker(entity_types=["Shot"], context=context)
+```
+
+## The showcase
+
+```sh
+python -m sg_widgets_qt.showcase
+```
+
+One page per widget, with a live demo, the props, signals, slots and keyboard tables, and the docs
+prose. The pages ship inside the package. The demos run on the mock, so the showcase needs no
+site; its toolbar offers Live where the three values above are set.
+
+## The widgets
+
+| | |
+|---|---|
+| ![An entity multi picker open on its results](https://raw.githubusercontent.com/ksallee/sg-widgets-qt/main/docs/screenshots/entity-multi-picker-light.png) | A picker searches the site, holds what was ticked as chips, and emits references. |
+| ![A filter editor holding one status condition](https://raw.githubusercontent.com/ksallee/sg-widgets-qt/main/docs/screenshots/filter-editor-light.png) | The filter editor builds a condition tree and serialises it for the API. |
+| ![A status picker open on the statuses of one project](https://raw.githubusercontent.com/ksallee/sg-widgets-qt/main/docs/screenshots/status-picker-light.png) | Statuses carry the site's own names, codes, colours and icons, per project. |
+| ![Global search, its results grouped by entity type](https://raw.githubusercontent.com/ksallee/sg-widgets-qt/main/docs/screenshots/global-search-light.png) | Global search reads across entity types and marks what matched. |
+| ![An entity grid of thumbnails](https://raw.githubusercontent.com/ksallee/sg-widgets-qt/main/docs/screenshots/entity-grid-light.png) | A table, a grid and a tree page a set, sort it, group it and edit a cell. |
+| ![The entity table in the dark theme](https://raw.githubusercontent.com/ksallee/sg-widgets-qt/main/docs/screenshots/entity-table-dark.png) | Every widget wears a light and a dark theme, or the host application's palette. |
+
+Every shot above reads a live site. [One page per
+widget](https://github.com/ksallee/sg-widgets-qt/tree/main/docs/widgets) says what each one takes
+and emits, beside
+[the introduction](https://github.com/ksallee/sg-widgets-qt/blob/main/docs/start/introduction.md),
+[install](https://github.com/ksallee/sg-widgets-qt/blob/main/docs/start/install.md) and
+[the core](https://github.com/ksallee/sg-widgets-qt/blob/main/docs/core/index.md).
+
+## How it relates to sg-widgets
+
+This is a port of [sg-widgets](https://github.com/ksallee/sg-widgets), whose React and Svelte
+widgets carry the same names, props and behaviour, and whose
+[documentation site](https://sg-widgets.vercel.app) is the reference for what a widget does; the
+pages here say where Qt or Python forced a difference. The framework-neutral half comes with it as
+`sg_widgets_core`, which holds the field data types, the operator vocabularies, the filter tree,
+status logic, the formatters, the parsers, the client protocol and a generated mock site, and
+imports no Qt, so it runs in a farm job as well as in a window. What either repo claims about the
+API is measured in [sg-groundtruth](https://github.com/ksallee/sg-groundtruth) and cited where it
+is relied on.
+
+## Status
+
+Alpha. 52 widgets, 27 core modules and 55 documentation pages are complete, on Python 3.9 through
+3.13 and on Qt 5.15 and Qt 6. Both packages carry `py.typed`. Names, props and signals can still
+change between 0.x releases, and the
+[changelog](https://github.com/ksallee/sg-widgets-qt/blob/main/CHANGELOG.md) records what changed.
+Ask for a widget, report a defect or say what reads wrong in the
+[issues](https://github.com/ksallee/sg-widgets-qt/issues).
+
+## Licence
+
+MIT. See [LICENSE](https://github.com/ksallee/sg-widgets-qt/blob/main/LICENSE).

sg_widgets_qt-0.1.0/docs/DESIGN.md

@@ -0,0 +1,72 @@
+# Design
+
+## Why a port
+
+The widgets in `~/dev/sg-widgets` encode what the Flow Production Tracking API does, measured by
+the sg-groundtruth corpus, behind one set of design rules. Pipeline tools in Maya, Houdini and
+Nuke need the same widgets, in the Python and Qt those hosts ship.
+
+## Stack
+
+Python 3.9 as the floor: Maya 2023, Houdini 19.5 and Nuke 14 ship it. `qtpy` so one source runs
+on PySide2 5.15, PySide6, PyQt5 and PyQt6. `shotgun_api3` because it is BSD licensed and runs on
+every host Python; `fpt-api` is AGPL and stays out. Those two are the whole runtime: annotations
+are strings under `from __future__ import annotations`, so nothing here needs `typing_extensions`.
+
+Dev: `uv`, `pytest`, `pytest-qt`, `pytest-timeout`, `ruff`. PySide6 6.7 is the last release for
+3.9. PyQt5 stands in for PySide2 in the second environment because PySide2 ships no arm64 wheel.
+`pytest-timeout` carries the two-minute per-test timeout in `pyproject.toml`: a widget waiting on
+a signal that never comes fails rather than hanging a run.
+
+## Publishing
+
+`py.typed` in both packages, so a consumer's type checker reads the annotations. The wheel carries
+the two packages, the icons and the fonts. The sdist carries what builds and checks that wheel and
+nothing else: the screenshots under `shots/` and the qa drives under `tools/drives/` are most of
+the tree and none of them is needed to build.
+
+`.github/workflows/gates.yml` runs ruff and the suite on both bindings on every pull request and on
+pushes to `dev` and `main`. It asks fontconfig for grayscale antialiasing first: where
+fontconfig asks for subpixel rendering, a widget painting itself and the delegate painting the same
+value rasterise one string two ways, and the face parity test reads that as drift. A Linux checkout
+wants the same setting. `.github/workflows/release.yml` builds, installs the wheel into a fresh
+environment, imports both packages offscreen and uploads to PyPI by trusted publishing when a
+GitHub release is published. No token is stored anywhere.
+
+## Two packages, one distribution
+
+`sg_widgets_core` has no Qt import, so a farm script or a test can use the filter tree, the
+formatters and the client. `sg_widgets_qt` holds the theme, the primitives, the widgets and the
+showcase. One wheel, because a DCC install is one `pip install`.
+
+The showcase draws its pages from `docs/`, which is where they are written and where
+`tools/export_docs.py` writes them. The wheel copies `docs/widgets`, `docs/core` and `docs/start`
+to `sg_widgets_qt/_docs`, so an installed showcase opens the sidebar a checkout opens.
+`sg_widgets_qt.showcase.paths` reads the package copy through `importlib.resources` and falls back
+to the checkout's `docs/`. It also resolves `.env.local` from the working directory upward, because
+nothing above `site-packages` belongs to the person running the showcase.
+
+## Threads
+
+`shotgun_api3.Shotgun` is not thread-safe. `ShotgunClient` keeps one connection per thread. The Qt
+layer runs every read on `QThreadPool` and hands the answer back through a signal; a ticket per
+query drops an answer a newer query replaced.
+
+Three pools, each four threads, so work of one kind never waits out work of another. Each stays
+small because a site rate limits, and none of them is `QThreadPool.globalInstance()`, so a host
+application's own work is untouched.
+
+| pool | carries |
+|---|---|
+| `workers.default_pool()` | Schema reads, facet counts, field writes, the demos. |
+| `entity_picker.search_pool()` | What a picker or a search types into. |
+| `images.image_pool()` | Thumbnails, avatars and the status sprite. |
+
+A page of rows asks for more pictures than any pool has threads, so the pictures read in a lane
+of their own: a field write submitted behind a table of thumbnails still lands at once.
+
+## Sync
+
+`sync/manifest.json` is the ledger: per item, the upstream files it ports and their content hash
+at the upstream commit last synced. `tools/sync_status.py` diffs it against the checkout;
+`/sync` ports what drifted.

sg_widgets_qt-0.1.0/docs/README.md

@@ -0,0 +1,74 @@
+# docs
+
+The widget, core and start pages, and the tables the showcase draws beside them. Three scripts
+produce them from `~/dev/sg-widgets`. Nothing under `docs/widgets/`, `docs/core/` or `docs/start/`
+is written by hand, with one exception named below.
+
+## What produces what
+
+| script | writes |
+|---|---|
+| `tools/export_props.mjs` | `docs/widgets/<name>.props.json`, `docs/widgets/_index.json` |
+| `tools/export_docs.py` | `docs/widgets/<name>.md`, `docs/core/<name>.md`, `docs/start/<name>.md` |
+| `tools/props_types.py` | the `py_type` of every prop row in `docs/widgets/*.props.json` |
+
+## The commands
+
+    cd ~/dev/sg-widgets && node ~/dev/sg-widgets-qt/tools/export_props.mjs
+    cd ~/dev/sg-widgets && ~/dev/sg-widgets-qt/.venv/bin/python ~/dev/sg-widgets-qt/tools/export_docs.py
+    .venv/bin/python tools/props_types.py
+
+The type pass runs after the props export, and reruns over whatever is on disk. Either exporter
+finds the upstream checkout in `SG_WIDGETS`, in the directory it was run from, or at
+`~/dev/sg-widgets`.
+
+## The props JSON
+
+One file per upstream props file, the `extends` chain resolved by the upstream's own `_resolve.ts`:
+
+    { "name", "page", "declares", "props": [], "events": [], "slots": [], "keyboard": [] }
+
+`page` is the page the rows are drawn on, which differs from `name` for an item that shares a page
+with another. A row carries `owner` where it comes from the item's base. Two names are changed for
+Python: a prop name is snake_case (`labelField` is `label_field`) and an event name is a Qt signal
+name (`onValueChange` is `value_changed`, `onOpenChange` is `open_changed`, `onError` is `error`).
+A `class / className` row is dropped, a Svelte-only row is dropped, and a React-only row is kept
+without the flag. Everything else is the upstream cell, verbatim.
+
+`py_type` sits beside `type` and is a mechanical translation, not a decision: `string` is `str`,
+`X[]` is `list[X]`, `X | null` is `Optional[X]`, `Record<K, V>` is `dict[K, V]`, a literal union is
+`Literal[...]`, a function is `Callable[...]`, and `EntityRef`, `SgContext`, `FilterGroup`,
+`WireGroup`, `CollectionColumn` and `PickerRow` stay as they are. `number` is `int` where the
+meaning counts something, `float` where it is a fraction, and `int | float` otherwise. A callback
+parameter with no type of its own is `Any`, except `row`, `query` and `open`.
+
+`_index.json` is the sidebar: `start` and `core` page names, the widgets `overview` page, and
+`widgets` as `[{ "category": "Foundations", "items": ["thumbnail", ...] }, ...]` in the order
+`apps/site/astro.config.mjs` gives. A page outside the sidebar, such as a page that names a
+renamed item, is exported but not listed.
+
+## The pages
+
+A `.md` page keeps its `title` and `description` as YAML, and its prose verbatim, including the
+API behaviour section and its corpus citations. The Astro islands become directives the showcase
+reads:
+
+    ::demo{name="entity-picker" title="…"}
+    ::props{name="entity-picker" kind="props"}
+
+`kind` is one of `props`, `events`, `slots` and `keyboard`. The install block becomes the import
+line, and a site link becomes a link to the page beside it.
+
+A paragraph that speaks of React, Svelte, Base UI, Bits UI, shadcn or the registry is followed by
+a line reading `::qt-note`. The prose is left as the upstream wrote it; the marker is where the Qt
+docs pass writes what differs here.
+
+## Editing, and what a rerun does
+
+The `.md` pages are the exception to "generated, never edited": each one is generated once and then
+edited, by the Qt docs pass that answers every `::qt-note`. A rerun therefore never overwrites a
+page that is already there. Where the conversion differs from the page on disk, it is written to
+`<name>.md.new` beside it and named on stdout, so the two are merged by hand and a Qt note survives
+a sync.
+
+The JSON files carry no hand edits and are overwritten on every run.

sg_widgets_qt-0.1.0/docs/core/client.md

@@ -0,0 +1,150 @@
+---
+title: Client
+description: The one interface every widget reads through, and what it writes.
+---
+
+A client is an `SgClient`, a protocol with one synchronous method per call. `ShotgunClient` speaks to
+a site through shotgun_api3, and `MockClient` answers from a generated site. The upstream
+`RestClient` and `ProxyClient` are not ported: they carry a token and a proxy endpoint through a
+browser, and a Qt application holds its own credentials and calls the Python API directly.
+
+```python
+from sg_widgets_core import ShotgunClient
+
+client = ShotgunClient.from_env()
+```
+
+`from_env` reads `FPT_API_SITE_URL`, `FPT_API_SCRIPT_NAME` and `FPT_API_API_KEY`. One
+`shotgun_api3.Shotgun` is built per thread, because a connection is not thread-safe.
+
+Every example below runs against the mock instead, so the writes land nowhere.
+
+```python
+from sg_widgets_core import MOCK_NOW, MockClient, create_query_cache
+
+client = create_query_cache(MockClient(seed=1, now=MOCK_NOW))
+```
+
+The cache remembers reads for `ttl_ms` and drops what a write makes stale: a row read of the type the
+write touched, and every note thread.
+
+## Reads
+
+### A note thread
+
+`thread_contents` answers a Note, its Attachments and its Replies as one list in time order. The
+author sits under `created_by` on a Note and an Attachment and under `user` on a Reply, and the
+row exposes it as `author` whichever key it came from. A Reply's author carries an avatar the other
+two do not.
+
+```python
+thread = client.thread_contents(11030, {"Note": ["subject", "sg_status_list"]})
+for row in thread:
+    print(row.type, row.created_at, row.author.name if row.author else None, row.content or "")
+```
+
+The second argument widens a row type by extra fields. It works on Note and Attachment; the Reply
+entry is accepted and changes nothing, so extra Reply fields come from a search on replies
+(`get_entity_notes_id_thread_contents`).
+
+### The event log
+
+`event_log` answers what changed, newest first. It is never cached. The cut is made on the project,
+the entity, the event type, the attribute and a date window; `meta` holds the old and new values
+and takes no filter, so the client lifts them out of each row.
+
+```python
+from sg_widgets_core import EntityRef, EventLogOptions
+
+result = client.event_log(
+    EventLogOptions(
+        entity=EntityRef(type="Shot", id=862),
+        attribute_name="sg_status_list",
+        page={"size": 5},
+    )
+)
+for event in result.data:
+    print(event.created_at, event.old_value, "->", event.new_value)
+```
+
+`event_log_filters` builds the same cut as a filter group, for a search of your own.
+
+```python
+from sg_widgets_core import event_log_filters
+
+filters = event_log_filters(
+    EventLogOptions(project_id=70, event_type=["Shotgun_Shot_Change", "Shotgun_Version_Change"])
+)
+```
+
+Ids at the head of the log are sparse and fill in later, so a cursor on the highest id seen drops
+events: re-scan a window behind the head or drive the feed from `created_at` and deduplicate on
+`id` (`025_event_log`).
+
+### What a person follows
+
+`following` answers every row one person follows, as a type and an id each, in one unpaged body.
+It takes a type to keep and a project to cut on. The person is a HumanUser: a script cannot ask
+what it follows (`get_entity_human_users_id_following`).
+
+```python
+from sg_widgets_core import FollowingOptions, SearchOptions
+
+followed = client.following(20, FollowingOptions(entity="Task", project_id=70))
+rows = client.search(
+    "Task",
+    SearchOptions(
+        filters={"logical_operator": "and", "conditions": [["id", "in", [ref.id for ref in followed]]]},
+        fields=["content", "sg_status_list"],
+    ),
+)
+```
+
+## Writes
+
+### A row
+
+`create` posts one row and answers it. `project` is the whole contract on a project-scoped type; the
+field the schema flags mandatory is optional, and the server fills the identity field when it is
+left out. An entity link is a `{type, id}` hash, never a bare id (`012_create_version`).
+
+```python
+note = client.create(
+    "Note",
+    {
+        "project": {"type": "Project", "id": 70},
+        "subject": "Key light reads flat",
+        "content": "Lift the fill on the left side.",
+        "note_links": [{"type": "Shot", "id": 862}],
+    },
+)
+reply = client.create("Reply", {"entity": {"type": "Note", "id": note.id}, "content": "On it."})
+```
+
+The answer echoes the server's defaults, so read them off `note.values`: a fresh Note is `unread` and
+`published` (`entity_types/Note`). A create takes `created_at` although the schema flags it
+read-only; a later update refuses it (`070_authored_timestamps`).
+
+### A file
+
+`upload` puts a file on a row in the three calls the API takes: a ticket, a PUT of the bytes to
+storage, and a completing POST. The field in the path picks the kind: `image` is a Thumbnail,
+another field an Attachment on that field, and no field a generic Attachment on the row
+(`recipes/001`).
+
+```python
+from sg_widgets_core import UploadFile
+
+uploaded = client.upload(
+    "Note",
+    note.id,
+    UploadFile(filename="key-light.txt", data=b"Lift the fill on the left side.\n", field="attachments"),
+)
+print(uploaded.upload_type, uploaded.etag)
+```
+
+`data` is the bytes themselves; a file on disk is `Path(name).read_bytes()`.
+
+The status of the PUT is the receipt; `etag` is present when the storage exposes one. A media field
+is not readable straight after: it answers a placeholder under `/images/status/transient/` on the
+site root until the transcode lands (`013_upload_media`).