docs: API pages for scad.ref (ref.<name>), ql.ref, ElementRef and ElementRefError

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
NiJingzhe
2026-11-04 13:33:22 +08:00
parent dc6aabd2ec
commit d137ec553d
16 changed files with 417 additions and 0 deletions
@@ -0,0 +1,26 @@
# ElementRef
## Class Definition
```python
class ElementRef(kind: str, feature: str = '', op: str = '', role: Optional[str] = None, ordinal: int = 0, topo: Optional[str] = None, between: Optional[Tuple[Union[str, 'ElementRef'], Union[str, 'ElementRef']]] = None, occurrence: int = 0, slot: int = 0, piece: Optional[int] = None, follow: str = 'identity', guard: Optional[Guard] = None, digest: Optional[str] = None, naming: int = 1)
```
*Source: ref.py*
## Import Surface
- top-level: `from simplecadapi import ElementRef`
## Description
A stable reference to one face, edge or vertex; ``repr()`` is the code that makes it.
Fields: ``kind``; ``feature`` and ``op`` (where the entity was born); then exactly one of ``role`` (its kernel
role, with ``ordinal`` saying which of the entities with that role), ``topo`` (its position in that output, for an
entity without a role; give a ``guard`` with it) or, for an edge, ``between`` (the two faces it lies between: role
names of faces of the same ``op``, or face references); ``occurrence`` (which of the feature's ``op`` nodes
upstream of the shape); ``slot`` (the output of that node); ``piece`` (the chosen piece when the entity has been
split); ``follow`` (``"identity"``, or ``"derived"`` to also follow into what it generated: an edge into its fillet
patch); ``guard``; ``digest`` (the parameters of the node, only when two nodes share its name); ``naming`` (the
naming version).
@@ -0,0 +1,19 @@
# ElementRefError
## Class Definition
```python
class ElementRefError(resolved: Resolution)
```
*Source: topology/element_ref.py*
## Import Surface
- top-level: `from simplecadapi import ElementRefError`
## Description
A reference that does not name exactly one entity: ``split`` (choose a piece) or ``lost``.
``status`` and ``candidates`` say which and what to choose from; ``resolved`` is the whole :class:`Resolution`.
+13
View File
@@ -325,6 +325,8 @@ This index includes generated docs for the public SimpleCAD API surface, includi
- [Constraint](Constraint.md) *(from product/constraint.py)* `top-level`
- [ConstraintReport](ConstraintReport.md) *(from product/constraint.py)* `top-level`
- [ConstraintResidual](ConstraintResidual.md) *(from product/constraint.py)* `top-level`
- [ElementRef](ElementRef.md) *(from ref.py)* `top-level`
- [ElementRefError](ElementRefError.md) *(from topology/element_ref.py)* `top-level`
- [GeometryRef](GeometryRef.md) *(from product/connector.py)* `top-level`
- [Material](Material.md) *(from product/material.py)* `top-level`
- [Part](Part.md) *(from product/part.py)* `top-level`
@@ -430,9 +432,20 @@ This index includes generated docs for the public SimpleCAD API surface, includi
- [placement_ticks](placement_ticks.md) *(from product/placement.py)* `submodule:product/placement`
- [project_rsketch](project_rsketch.md) *(from operators/sketch.py)* `top-level`
- [prop](prop.md) *(from ql.py)* `submodule:ql`
- [ql.ref](ql.ref.md) *(from ql.py)* `submodule:ql`
- [radial_pattern_rsolidlist](radial_pattern_rsolidlist.md) *(from operators/transform.py)* `top-level`
- [rebuild_curve_redge](rebuild_curve_redge.md) *(from operators/geometry.py)* `top-level`
- [rebuild_surface_rface](rebuild_surface_rface.md) *(from operators/geometry.py)* `top-level`
- [ref.coerce](ref.coerce.md) *(from ref.py)* `submodule:ref`
- [ref.edge](ref.edge.md) *(from ref.py)* `submodule:ref`
- [ref.edges](ref.edges.md) *(from ref.py)* `submodule:ref`
- [ref.face](ref.face.md) *(from ref.py)* `submodule:ref`
- [ref.faces](ref.faces.md) *(from ref.py)* `submodule:ref`
- [ref.of](ref.of.md) *(from ref.py)* `submodule:ref`
- [ref.parse](ref.parse.md) *(from ref.py)* `submodule:ref`
- [ref.resolve](ref.resolve.md) *(from ref.py)* `submodule:ref`
- [ref.vertex](ref.vertex.md) *(from ref.py)* `submodule:ref`
- [ref.vertices](ref.vertices.md) *(from ref.py)* `submodule:ref`
- [register_property_resolver](register_property_resolver.md) *(from ql.py)* `submodule:ql`
- [render_screenshot_rpath](render_screenshot_rpath.md) *(from operators/features.py)* `top-level`
- [sample_curve_rcurvature](sample_curve_rcurvature.md) *(from operators/geometry.py)* `top-level`
+38
View File
@@ -0,0 +1,38 @@
# ql.ref
## API Definition
```python
def ql.ref(reference: 'Union[ElementRef, Mapping[str, Any], str]') -> 'Any'
```
*Source: ql.py*
## Import Surface
- submodule: `from simplecadapi.ql import ref` or `simplecadapi.ql.ref`
## Description
A stable reference as a ``ql`` predicate (``scad.ql.ref``): keeps the entities it names in the scope.
The reference is resolved through the recorded history of the shape the selector is resolved against, once per
query run; a split reference (without ``piece``) or a lost one raises ``ElementRefError`` there, it never
matches nothing silently. The predicate stores the reference as data, so the selector serialises and replays.
## Parameters
### reference
- **Description**: An :class:`ElementRef`, its record (``to_dict()``) or its code (``'scad.ref.face(...)'``).
## Returns
SerializablePredicate: Use it in ``where(...)`` of a selector resolved against one shape.
## Examples
```python
>>> top = scad.ref.face("base", "make_box_rsolid", role="box.top")
>>> scad.ql.faces().where(scad.ql.ref(top)).exactly(1).resolve(part)
```
@@ -0,0 +1,17 @@
# ref.coerce
## API Definition
```python
def ref.coerce(reference: Any) -> ElementRef
```
*Source: ref.py*
## Import Surface
- stable references: `import simplecadapi as scad` then `scad.ref.coerce(...)`
## Description
An :class:`ElementRef` from a reference, its record (:meth:`ElementRef.to_dict`) or its code.
@@ -0,0 +1,31 @@
# ref.edge
## API Definition
```python
def ref.edge(feature: Optional[str] = None, op: Optional[str] = None, *, role: Optional[str] = None, ordinal: int = 0, topo: Optional[str] = None, between: Optional[Tuple[Union[str, ElementRef], Union[str, ElementRef]]] = None, occurrence: int = 0, slot: int = 0, piece: Optional[int] = None, follow: Follow = 'identity', guard: Optional[Guard] = None, digest: Optional[str] = None, naming: int = 1) -> ElementRef
```
*Source: ref.py*
## Import Surface
- stable references: `import simplecadapi as scad` then `scad.ref.edge(...)`
## Description
A reference to an edge: born in *feature* by *op*, or lying ``between`` two faces.
An edge is best named by the two faces it lies between: the faces' history is recorded by every operation, so the
edge is found again after booleans, blends and copies, and the name reads as what it is. ``between`` holds two
role names of faces made by *op* in *feature* (``("box.top", "box.front")``), or two face references (then
*feature* and *op* may be left out). The other arguments are :func:`face`'s (``guard`` size = length).
## Examples
```python
>>> rim = scad.ref.edge("base", "make_box_rsolid", between=("box.top", "box.front"))
>>> lip = scad.ref.edge(between=(scad.ref.face("base", "make_box_rsolid", role="box.top"),
... scad.ref.face("bore", "make_cylinder_rsolid", role="cylinder.side")))
>>> rounded = scad.fillet_rsolid(part, scad.ref.edges(rim, lip), 1.0)
```
@@ -0,0 +1,24 @@
# ref.edges
## API Definition
```python
def ref.edges(*refs: Union[ElementRef, Sequence[ElementRef]]) -> Any
```
*Source: ref.py*
## Import Surface
- stable references: `import simplecadapi as scad` then `scad.ref.edges(...)`
## Description
The selection of the edges the references name (see :func:`faces`).
## Examples
```python
>>> rims = scad.ref.edges(scad.ref.edge("base", "make_box_rsolid", topo="edge_1", guard=("LINE", (-20, 0, 10), 20)))
>>> rounded = scad.fillet_rsolid(base, rims, 1.0)
```
@@ -0,0 +1,78 @@
# ref.face
## API Definition
```python
def ref.face(feature: str, op: str, *, role: Optional[str] = None, ordinal: int = 0, topo: Optional[str] = None, occurrence: int = 0, slot: int = 0, piece: Optional[int] = None, follow: Follow = 'identity', guard: Optional[Guard] = None, digest: Optional[str] = None, naming: int = 1) -> ElementRef
```
*Source: ref.py*
## Import Surface
- stable references: `import simplecadapi as scad` then `scad.ref.face(...)`
## Description
A reference to a face born in *feature* by *op*.
## Parameters
### feature
- **Description**: The feature (cell) the face was made in: the editor's feature slug, or the cell's namespace.
### op
- **Description**: The operation that made it, as recorded (``"make_box_rsolid"``, ``"make_extrude_rsolid"``).
### role
- **Description**: Its kernel role (``"box.top"``, ``"extrusion.end"``); ``ordinal`` says which when several share it.
### ordinal
- **Description**: Which of the op's faces with that role (0 first).
### topo
- **Description**: For a face without a role: its position in the op's output (``"face_5"``); give a ``guard`` with it.
### occurrence
- **Description**: Which of the feature's *op* operations feeding the shape (0: the first).
### slot
- **Description**: The output of that operation (a multi-body result has one per body).
### piece
- **Description**: The chosen piece once the face has been split (in the order the split error lists them).
### follow
- **Description**: ``"identity"``; ``"derived"`` also follows into what the face generated.
### guard
- **Description**: ``(geometry type, (x, y, z), area[, normal])`` of the face when it was picked.
### digest
- **Description**: The operation's parameter digest, only when two operations share its name in the feature.
### naming
- **Description**: The naming version the reference was made under (1).
## Returns
ElementRef: The reference; resolve it with ``.one(shape)`` / ``.all(shape)`` / ``.resolve(shape)``.
## Examples
```python
>>> top = scad.ref.face("base", "make_box_rsolid", role="box.top")
>>> top.one(part).get_area()
```
@@ -0,0 +1,28 @@
# ref.faces
## API Definition
```python
def ref.faces(*refs: Union[ElementRef, Sequence[ElementRef]]) -> Any
```
*Source: ref.py*
## Import Surface
- stable references: `import simplecadapi as scad` then `scad.ref.faces(...)`
## Description
The selection of the faces the references name: ``ql.faces().where(ql.ref(r1) | ql.ref(r2) ...)``.
Pass it where an operation takes faces (``shell_rsolid(faces_to_remove=...)``, ``apply_tag_rselection``): the
operation resolves it in the shape it receives, and each reference raises ``ElementRefError`` there if it is split
(without ``piece``) or lost.
## Examples
```python
>>> opening = scad.ref.faces(scad.ref.face("base", "make_box_rsolid", role="box.top"))
>>> cup = scad.shell_rsolid(base, faces_to_remove=opening, thickness=1.0)
```
+47
View File
@@ -0,0 +1,47 @@
# ref.of
## API Definition
```python
def ref.of(entity: Any, shape: Any, *, follow: Follow = 'identity', guard: bool = True) -> ElementRef
```
*Source: ref.py*
## Import Surface
- stable references: `import simplecadapi as scad` then `scad.ref.of(...)`
## Description
The stable reference of *entity*, a face, edge or vertex of *shape* (or of a shape *shape* descends from).
The entity is traced back through the recorded history to where it was born, so a face picked on the finished
part is named by the box or extrusion that made it, not by the fillet that last trimmed it. An edge is named by
the two faces it lies between when that names it in *shape* (``between=``), else by its own birth.
## Parameters
### entity
- **Description**: The picked face / edge / vertex.
### shape
- **Description**: A recorded shape (made inside a ``GraphSession`` or a notebook cell) it belongs to.
### follow
- **Description**: Stored in the reference (see :func:`face`).
### guard
- **Description**: Store the entity's geometric fingerprint (the default; needed for an entity without a kernel role).
## Returns
ElementRef: ``repr()`` is the code that makes the same reference.
## Raises
- **ValueError**: *shape* was not recorded, or *entity* is not part of a recorded output upstream of it.
@@ -0,0 +1,17 @@
# ref.parse
## API Definition
```python
def ref.parse(text: str) -> ElementRef
```
*Source: ref.py*
## Import Surface
- stable references: `import simplecadapi as scad` then `scad.ref.parse(...)`
## Description
The reference spelled by *text* (what :meth:`ElementRef.code` writes).
@@ -0,0 +1,17 @@
# ref.resolve
## API Definition
```python
def ref.resolve(reference: Any, shape: Any) -> Resolution
```
*Source: ref.py*
## Import Surface
- stable references: `import simplecadapi as scad` then `scad.ref.resolve(...)`
## Description
``coerce(reference).resolve(shape)``.
@@ -0,0 +1,17 @@
# ref.vertex
## API Definition
```python
def ref.vertex(feature: str, op: str, *, role: Optional[str] = None, ordinal: int = 0, topo: Optional[str] = None, occurrence: int = 0, slot: int = 0, piece: Optional[int] = None, guard: Optional[Guard] = None, digest: Optional[str] = None, naming: int = 1) -> ElementRef
```
*Source: ref.py*
## Import Surface
- stable references: `import simplecadapi as scad` then `scad.ref.vertex(...)`
## Description
A reference to a vertex born in *feature* by *op* (the arguments are :func:`face`'s).
@@ -0,0 +1,17 @@
# ref.vertices
## API Definition
```python
def ref.vertices(*refs: Union[ElementRef, Sequence[ElementRef]]) -> Any
```
*Source: ref.py*
## Import Surface
- stable references: `import simplecadapi as scad` then `scad.ref.vertices(...)`
## Description
The selection of the vertices the references name (see :func:`faces`).
+1
View File
@@ -388,6 +388,7 @@
"project_rsketch": "simplecadapi.operators.sketch",
"projected_tag_binding": "simplecadapi.topology.tagging",
"prop": "simplecadapi.ql",
"ref": "simplecadapi.ql",
"radial_pattern_rsolidlist": "simplecadapi.operators.transform",
"raise_harness_error": "simplecadapi.errors",
"raise_loft_failure_if_diagnosed": "simplecadapi.operators._diagnostics",
+27
View File
@@ -25,6 +25,8 @@ DEFAULT_SOURCE_FILENAMES: tuple[str, ...] = (
"operators/selection.py",
"operators/features.py",
"ql.py",
"ref.py",
"topology/element_ref.py",
"recording/serializer.py",
"math.py",
"product/placement.py",
@@ -176,6 +178,11 @@ RUNTIME_EXPORTS = frozenset(
{"CellReport", "NotebookConfig", "NotebookRun", "notebook_id", "run_notebook", "use"}
)
# ``scad.ref`` (stable references): its functions are documented as ``ref.<name>`` (``faces`` / ``edges`` would
# otherwise share a page name with ``ql``'s).
REF_MODULE = "ref.py"
REF_FUNCTIONS = frozenset({"of", "face", "edge", "vertex", "faces", "edges", "vertices", "resolve", "coerce", "parse"})
MISSING = object()
@@ -386,6 +393,15 @@ class APIDocumentGenerator:
signature = re.sub(r"SupportsInt \| SupportsIndex", "int", signature)
signature = re.sub(r"SupportsFloat \| SupportsIndex", "float", signature)
head = "def" if kind == "function" else "class"
if module_name == "ql.py" and name == "ref": # not the scad.ref module of the same name
return ApiInfo(
name="ql.ref",
kind=kind,
signature=f"def ql.ref{signature}",
source_file=module_name,
parsed_doc=self._parse_docstring(docstring),
import_surface="submodule: `from simplecadapi.ql import ref` or `simplecadapi.ql.ref`",
)
return ApiInfo(
name=name,
kind=kind,
@@ -452,6 +468,17 @@ class APIDocumentGenerator:
exported_names: set[str],
) -> ApiInfo | None:
if isinstance(node, ast.FunctionDef):
if module_name == REF_MODULE:
if node.name not in REF_FUNCTIONS or not ast.get_docstring(node):
return None
return ApiInfo(
name=f"ref.{node.name}",
kind="function",
signature=self._get_function_signature(node).replace("def ", "def ref.", 1),
source_file=module_name,
parsed_doc=self._parse_docstring(ast.get_docstring(node) or ""),
import_surface=f"stable references: `import simplecadapi as scad` then `scad.ref.{node.name}(...)`",
)
if not self._should_include_function(
node.name, module_name, exported_names
):