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
Placementvalue whose mutations are reported toon_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, soobj.Shaperound-trips between core and its ownPart.Shapeclass. 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§
- Extension
Method - A module’s extension method (
changeAttacherType,configLinkProperty, …). - Extension
Provider - A module’s
addExtensionhook: install an extension’s properties on objectid. Returns whether the extension was provided (a missing object isfalse). Registered by name ("Part::AttachExtensionPython", …) so core and this binding need no knowledge of the module. - Extension
ToPython - Convert a module-owned value to Python;
Noneif the value is not this module’s (the caller then falls back to an opaqueNone). - Python
ToExtension - Recognise a Python value as a module-owned value;
Noneif it is not. - SubElement
ToPython - Convert a sub-element name (
Edge1,Face3) of a module-owned value to Python;Noneif the name is not a sub-element of this value.