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:
@@ -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`.
|
||||
@@ -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`
|
||||
|
||||
@@ -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)
|
||||
```
|
||||
@@ -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`).
|
||||
@@ -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",
|
||||
|
||||
@@ -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
|
||||
):
|
||||
|
||||
Reference in New Issue
Block a user