diff --git a/docs/src/reference/cpp-origin-manager.md b/docs/src/reference/cpp-origin-manager.md index 4283cd2d2f..993a29d2e2 100644 --- a/docs/src/reference/cpp-origin-manager.md +++ b/docs/src/reference/cpp-origin-manager.md @@ -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) diff --git a/docs/src/reference/kcsdk-python.md b/docs/src/reference/kcsdk-python.md index 8477c921ef..360a95e75d 100644 --- a/docs/src/reference/kcsdk-python.md +++ b/docs/src/reference/kcsdk-python.md @@ -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 |