Skip to main content

Crate ferrocad_py

Crate ferrocad_py 

Source
Expand description

§ferrocad_py

The PyO3 extension that exposes ferrocad_core to Python as the ferrocad module. It contains no model logic of its own — it wraps the core types as #[pyclass]es and adapts FreeCAD’s Python surface (document/object/property APIs, Base value types, observers, transactions).

This is an implementation detail of the ferrocad distribution. Users do not import it directly: the pure-Python python/FreeCAD facade imports ferrocad and re-exports the App-level API under the FreeCAD namespace, so workbench scripts keep writing import FreeCAD.

The documentation is organised following Diátaxis.

§How-to guide: use it from Python

import FreeCAD                       # the facade
doc = FreeCAD.newDocument("Demo")
obj = doc.addObject("App::FeaturePython", "Box")
obj.addProperty("App::PropertyLength", "Height")
obj.Height = "25 mm"
doc.recompute()

The same code runs against upstream FreeCAD and against FerroCAD; only the backend behind import FreeCAD differs.

§Explanation

Each core document or object is shared with Python behind an Arc<Mutex<..>>. Observer arguments are backed by a global identity cache so the same object compares equal with is across calls. Because the types are built with the abi3 stable ABI, one binary works across CPython versions.

The crate is compiled as a cdylib extension module (not published docs); the Rust-level API reference here is thin by design — the interesting surface is the Python API, documented on the FreeCAD facade and by the upstream FreeCAD documentation.

§Implemented capabilities

Follows ferrocad_core: the Base/App surface through M4 slices 1–16, plus the MVP slices A1 (object state / property status), B1 (name/label semantics), and A2 (PropertyEnumeration and type validation). See the repository docs/record/milestones.md for the per-slice record.

Functions§

ferrocad
placement_with_hook
Build a live Placement value whose mutations are reported to on_change.
register_extension_converter
Register the Python conversions for a module-owned property type, keyed by its registered type name (e.g. Part::PropertyPartShape). A workbench module calls this at import, so obj.Shape round-trips between core and its own Part.Shape class. Core stays free of any knowledge of the module’s value.
register_extension_method
Register a method that an extension makes available on the objects carrying it. The method is looked up by walking the object’s own extension set, so a module never edits this crate to expose it.
register_extension_provider
Register the properties an extension installs via addExtension(name).
register_sub_element_resolver
Register how a module’s own property value resolves a sub-element name to a Python object (Part::PropertyPartShape + Edge1 -> Part.Edge).

Type Aliases§

ExtensionMethod
A module’s extension method (changeAttacherType, configLinkProperty, …).
ExtensionProvider
A module’s addExtension hook: install an extension’s properties on object id. Returns whether the extension was provided (a missing object is false). Registered by name ("Part::AttachExtensionPython", …) so core and this binding need no knowledge of the module.
ExtensionToPython
Convert a module-owned value to Python; None if the value is not this module’s (the caller then falls back to an opaque None).
PythonToExtension
Recognise a Python value as a module-owned value; None if it is not.
SubElementToPython
Convert a sub-element name (Edge1, Face3) of a module-owned value to Python; None if the name is not a sub-element of this value.