docs(sdk): document per-document origin Python bindings (#406)
All checks were successful
Build and Test / build (pull_request) Successful in 33m50s
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:
@@ -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 |
|
||||
|
||||
Reference in New Issue
Block a user