create/docs/src/reference/kcsdk-python.md

KCSDK Python API Reference

The kcsdk module provides Python access to the Kindred Create addon SDK. It is built with pybind11 and installed alongside the Create module.

The kindred_sdk package (mods/sdk/kindred_sdk/) provides convenience wrappers that route through kcsdk when available, falling back to legacy FreeCADGui.* bindings. Addons should prefer kindred_sdk over importing kcsdk directly.

import kcsdk            # C++ bindings (low-level)
import kindred_sdk      # Python wrappers (recommended)

Module constants

Name	Value	Description
API_VERSION_MAJOR	1	KCSDK API major version

Enums

DockArea

Dock widget placement area. Values match Qt::DockWidgetArea.

Value	Integer	Description
DockArea.Left	1	Left dock area
DockArea.Right	2	Right dock area
DockArea.Top	4	Top dock area
DockArea.Bottom	8	Bottom dock area

PanelPersistence

Whether a dock panel's visibility survives application restarts.

Value	Description
PanelPersistence.Session	Visible until application close
PanelPersistence.Persistent	Saved to preferences and restored on next launch

Editing Context API

These functions manage the context-aware UI system. Contexts control which toolbars are visible based on the current editing state.

register_context(id, label, color, toolbars, match, priority=50)

Register an editing context.

Parameter	Type	Description
id	str	Unique identifier (e.g. "myaddon.edit")
label	str	Display label template. Supports {name} placeholder
color	str	Hex color for breadcrumb (e.g. "#f38ba8")
toolbars	list[str]	Toolbar names to show when active
match	callable	Zero-arg callable returning True when active
priority	int	Higher values checked first. Default 50

kcsdk.register_context(
    "myworkbench.edit",
    "Editing {name}",
    "#89b4fa",
    ["MyToolbar", "StandardViews"],
    lambda: is_my_object_in_edit(),
    priority=60,
)

unregister_context(id)

Remove a previously registered editing context.

register_overlay(id, toolbars, match)

Register an editing overlay. Overlays add toolbars to whatever context is currently active when match() returns True.

Parameter	Type	Description
id	str	Unique overlay identifier
toolbars	list[str]	Toolbar names to append
match	callable	Zero-arg callable returning True when the overlay applies

unregister_overlay(id)

Remove a previously registered overlay.

inject_commands(context_id, toolbar_name, commands)

Inject additional commands into an existing context's toolbar.

Parameter	Type	Description
context_id	str	Target context identifier
toolbar_name	str	Toolbar within that context
commands	list[str]	Command names to add

kcsdk.inject_commands("partdesign.body", "PartDesign", ["MyAddon_CustomFeature"])

current_context()

Return the current editing context as a dict, or None.

Keys: id, label, color, toolbars, breadcrumb, breadcrumbColors.

refresh()

Force re-resolution of the editing context.

Panel Provider API

These functions manage dock panel registration. Panels are created through the IPanelProvider interface and managed by DockWindowManager.

IPanelProvider

Abstract base class for dock panel providers. Subclass in Python to create custom panels.

Three methods must be implemented:

class MyPanel(kcsdk.IPanelProvider):
    def id(self):
        return "myaddon.panel"

    def title(self):
        return "My Panel"

    def create_widget(self):
        from PySide import QtWidgets
        label = QtWidgets.QLabel("Hello from my addon")
        return label

Optional methods with defaults:

Method	Return type	Default	Description
preferred_area()	DockArea	DockArea.Right	Dock placement area
persistence()	PanelPersistence	PanelPersistence.Session	Visibility persistence
context_affinity()	str	"" (always visible)	Only show in named context

class SidePanel(kcsdk.IPanelProvider):
    def id(self): return "myaddon.side"
    def title(self): return "Side Panel"
    def create_widget(self):
        from PySide import QtWidgets
        return QtWidgets.QTreeWidget()
    def preferred_area(self):
        return kcsdk.DockArea.Left
    def context_affinity(self):
        return "partdesign.body"  # only visible in PartDesign body context

register_panel(provider)

Register a dock panel provider. The provider is stored in the registry until create_panel() is called to instantiate the actual dock widget.

Parameter	Type	Description
provider	IPanelProvider	Panel provider instance

unregister_panel(id)

Remove a registered panel provider and destroy its dock widget if created.

create_panel(id)

Instantiate the dock widget for a registered panel. Calls the provider's create_widget() once and embeds the result in a QDockWidget via DockWindowManager. Skips silently if the panel already exists.

create_all_panels()

Instantiate dock widgets for all registered panels.

registered_panels()

Return IDs of all registered panel providers as list[str].

available()

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.

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.

kindred_sdk.register_dock_panel(object_name, title, widget_factory, area="right", delay_ms=0)

High-level dock panel registration. Creates an anonymous IPanelProvider internally and schedules creation via QTimer.

Parameter	Type	Default	Description
object_name	str		Qt object name (used as panel ID)
title	str		Dock widget title
widget_factory	callable		Zero-arg callable returning a QWidget
area	str	"right"	"left", "right", "top", or "bottom"
delay_ms	int	0	Defer creation by this many milliseconds

from kindred_sdk import register_dock_panel
from PySide import QtWidgets

register_dock_panel(
    "MyAddonPanel",
    "My Addon",
    lambda: QtWidgets.QLabel("Hello"),
    area="left",
    delay_ms=2000,
)

Other kindred_sdk Wrappers

These mirror the kcsdk functions with added type validation and try/except error handling:

Function	Maps to
kindred_sdk.register_context()	kcsdk.register_context()
kindred_sdk.unregister_context()	kcsdk.unregister_context()
kindred_sdk.register_overlay()	kcsdk.register_overlay()
kindred_sdk.unregister_overlay()	kcsdk.unregister_overlay()
kindred_sdk.inject_commands()	kcsdk.inject_commands()
kindred_sdk.current_context()	kcsdk.current_context()
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
kindred_sdk.freecad_version()	FreeCAD version tuple

Architecture

Python Addon Code
       |
kindred_sdk (mods/sdk/)          <- convenience wrappers + validation
       |
kcsdk.so (pybind11 module)       <- C++ API bindings
       |
libKCSDK.so (C++ shared library) <- SDKRegistry + provider interfaces
       |
FreeCADGui (EditingContextResolver, DockWindowManager, OriginManager, ...)

When kcsdk is not available (console mode, build not installed), kindred_sdk falls back to legacy FreeCADGui.* Python bindings.

Related

• Writing an Addon
• Package.xml Schema Extensions
• Create Module Bootstrap