Skip to main content

Conventions and contracts

Public imports​

Prefer the top-level namespace for common operations:

import cadflow as cad

with cad.Model() as model:
    body = model.box(40.0, 25.0, 6.0)

Use a public domain module when it makes ownership explicit:

from cadflow.flexible import FlexibleMaterial, FlexiblePanel
from cadflow.inspect import brep
from cadflow.scene import SceneCompileOptions, compile_scene

An import is public when it appears in this reference or in a module's explicit export list. Paths below cadflow._engine are implementation details and may change without migration aliases.

Ownership and lifetime​

Model owns a NativeSession unless an existing session is passed to its constructor. Each native Shape carries both that session and an opaque handle. Consequently:

  • use a shape only while its session is open;
  • pass shapes from the same session to booleans, distances, and contact queries;
  • do not persist a ShapeHandle as a durable external identifier;
  • export geometry or structured metadata before closing the session.

Closing a Model with an injected session does not close the injected session. The caller retains that responsibility.

Value and update semantics​

Core Shape operations return new handles and do not mutate the source geometry. Most product and engineering-domain records are immutable dataclasses. Update helpers return replacement values:

assembly = cad.make_assembly_rassembly("fixture")
assembly = cad.add_component_rassembly(assembly, part, component_id="base")

Failing to assign the return value is a common source of apparently missing changes. Runtime objects such as Model, Graph, GraphSession, and builders may maintain explicit internal state; their pages say so.

Numbers, coordinates, and units​

The compact native geometry API accepts plain float values. Length values use the active model convention; angles named degrees are degrees. Three-dimensional vectors and points are ordered (x, y, z).

The expression and engineering APIs carry explicit dimensions or unit labels. Do not infer a unit from a field name when the object exposes length_unit, force_unit, time_unit, temperature_unit, or a dimension value. Convert at subsystem boundaries and record the chosen unit system in exported artifacts.

All geometric dimensions expected to be positive should be finite. Tolerances are non-negative and usually measured in the same length unit as the input geometry.

Indices and references​

Native face and edge collections use deterministic, zero-based indices for one shape in one runtime build. These indices are suitable for immediate feature operations, but they are not stable product identifiers after topology-changing edits. Use semantic tags, connector IDs, component IDs, or explicit geometry references when state must survive reconstruction.

Graph node references are also zero-based integers and may only reference earlier nodes. Model JSON uses string node IDs and validates graph ownership.

Paths and external effects​

Methods named export_*, write_*, save_*, and some render_* functions write files. Import and load functions read external data and may reject missing, malformed, or unsupported content. Use explicit, application-controlled paths; validate that expected artifacts exist and are non-empty before delivery.

JSON and deterministic data​

Public to_dict() and serialization functions return JSON-safe values unless documented otherwise. Scene and replay APIs provide canonicalization and strict parsing helpers where byte-level determinism matters. Treat deserialized data from an untrusted source as input: enforce size limits, parse strictly, and validate the domain schema before execution.

Optional dependencies​

Some domains need additional Python packages, native libraries, or external CAD applications. Importability does not guarantee that every operation is available. Inspect capabilities() or the domain's capability record before dispatching optional work.

Stability​

CadFlow 0.1.0 is Alpha. Public names are documented, but signatures and serialized schemas may still evolve. Pin exact versions for production, check generated signature drift, and test geometric or artifact equivalence during upgrades.