docs(sdk): document per-document origin Python bindings (#406)
All checks were successful
Build and Test / build (pull_request) Successful in 33m50s

- Add Per-Document Origin API section to kcsdk-python.md covering
  document_origin, set_document_origin, clear_document_origin, and
  find_owning_origin with parameter tables and usage example
- Add 4 per-document functions to kindred_sdk wrappers table showing
  the doc.Name extraction pattern
- Add Python Exposure subsection to cpp-origin-manager.md cross-
  referencing both kcsdk and kindred_sdk layers
This commit is contained in:
2026-03-05 10:20:22 -06:00
parent d656455d00
commit fc2baa1afd
2 changed files with 70 additions and 0 deletions

View File

@@ -158,6 +158,14 @@ documents to mark them with the origin that created them.
Remove a document from the association cache. Called when a document is
closed to prevent stale pointers.
### Python Exposure
All four document-origin methods are exposed to Python through two layers:
1. **`kcsdk` (pybind11)** — `document_origin(doc_name)`, `set_document_origin(doc_name, origin_id)`, `clear_document_origin(doc_name)`, `find_owning_origin(doc_name)`. These accept the document's internal `Name` string and return origin info dicts. See [KCSDK Python API — Per-Document Origin API](./kcsdk-python.md#per-document-origin-api).
2. **`kindred_sdk` wrappers** — same names but accept an `App.Document` object instead of a name string. The wrapper extracts `doc.Name` and delegates to `kcsdk`. Addons should use this layer. See [KCSDK Python API — Wrappers Table](./kcsdk-python.md#other-kindred_sdk-wrappers).
## Signals
All signals use the [fastsignals](https://github.com/nicktrandafil/fastsignals)

View File

@@ -180,6 +180,64 @@ Return IDs of all registered panel providers as `list[str]`.
Return names of all registered providers (across all provider types) as `list[str]`.
## Per-Document Origin API
These functions manage explicit associations between open documents and origins. They are used by the file commands (Save, Commit, Push) to determine which origin backend handles a given document.
### document_origin(doc_name)
Get the origin associated with a document. Checks explicit association first, then falls back to ownership detection (`ownsDocument`).
| Parameter | Type | Description |
|-----------|------|-------------|
| `doc_name` | `str` | FreeCAD document name (internal `Name` property) |
Returns an origin info dict (`id`, `label`, `capabilities`, …) or `None`.
### set_document_origin(doc_name, origin_id)
Explicitly associate a document with an origin. Used when creating new documents to mark them with the origin that created them.
| Parameter | Type | Description |
|-----------|------|-------------|
| `doc_name` | `str` | FreeCAD document name |
| `origin_id` | `str` | Registered origin ID (e.g. `"silo"`, `"local"`) |
Returns `True` on success, `False` if the document or origin ID is not found.
### clear_document_origin(doc_name)
Remove the explicit origin association for a document. After clearing, origin queries fall back to ownership detection.
| Parameter | Type | Description |
|-----------|------|-------------|
| `doc_name` | `str` | FreeCAD document name |
### find_owning_origin(doc_name)
Scan all registered origins via their `ownsDocument` method. Unlike `document_origin`, this bypasses the explicit association cache and always re-queries.
| Parameter | Type | Description |
|-----------|------|-------------|
| `doc_name` | `str` | FreeCAD document name |
Returns an origin info dict or `None`.
```python
import kcsdk
# Look up which origin handles the active document
info = kcsdk.document_origin("MyPart")
if info:
print(f"Document handled by: {info['id']}")
# Force-associate a document with the Silo origin
kcsdk.set_document_origin("MyPart", "silo")
# Re-detect without cache
owner = kcsdk.find_owning_origin("MyPart")
```
## `kindred_sdk` Convenience Wrappers
The `kindred_sdk` Python package wraps the `kcsdk` C++ module with input validation, error handling, and fallback to legacy APIs.
@@ -224,6 +282,10 @@ These mirror the `kcsdk` functions with added type validation and try/except err
| `kindred_sdk.refresh_context()` | `kcsdk.refresh()` |
| `kindred_sdk.register_origin()` | `FreeCADGui.addOrigin()` |
| `kindred_sdk.unregister_origin()` | `FreeCADGui.removeOrigin()` |
| `kindred_sdk.document_origin(doc)` | `kcsdk.document_origin(doc.Name)` |
| `kindred_sdk.set_document_origin(doc, id)` | `kcsdk.set_document_origin(doc.Name, id)` |
| `kindred_sdk.clear_document_origin(doc)` | `kcsdk.clear_document_origin(doc.Name)` |
| `kindred_sdk.find_owning_origin(doc)` | `kcsdk.find_owning_origin(doc.Name)` |
| `kindred_sdk.get_theme_tokens()` | YAML palette lookup |
| `kindred_sdk.load_palette()` | `Palette` object from YAML |
| `kindred_sdk.create_version()` | Kindred Create version string |