Sheet and fluent handles¶

Seed the declared set from detection (the hybrid mode, ADR 0011 §3): start from the model the detector recovers, then override specific features (edit the list via :attr:features, or re-declare) before :meth:build.

This states the automatic dimension source (#874), because that is what asking for detection means: you have asked for the engine's reading of the part, features and dimensions alike. It is not the implicit default the breaking change removed — a Sheet(part) still has to say — it is from_part's own meaning.

Because the choice is from_part's rather than a script line's, adding dimension(...) declarations overrides it rather than conflicting: detect the features, then declare exactly which of their measurements to draw. That is the natural way to take over a detected drawing, and requiring the caller to redeclare every feature by hand to reach it would be a poor trade (#921 review round 6). An explicit auto_dimensions() still conflicts — there the script has said both things.

Append a pre-built IR :class:~draftwright.model.Feature (escape hatch for the constructors this façade does not surface directly, e.g. PMI).

Returns a handle, like every declaration verb (#922). It matters here more than it looks: the ENVELOPE is emitted through this escape hatch rather than through :meth:envelope, so while add returned the sheet, sheet.dimension(env, "width") — ADR 0016's own worked example — could not be written against a generated script. Naming would have been uniform across the verbs and silently absent for one feature in the middle of the file, which is worse than being absent everywhere. A raw ControlFrame or DatumRef may name a handle as its origin; add resolves and token-binds that provenance exactly like the public GD&T verbs.

dimension(feature, role) — the ADR 0016 referential verb. See :meth:_authored_dimension for the semantics.

The signature is the real one again (#720): the transitional call-shape dispatch to :meth:measured_dimension was removed at 0.4.0, so dimension means one thing. That restores most of what the @overload pair provided — the parameter names and the DimensionIntent return a caller sees (#963) — without the dual shape.

One thing it does NOT restore: **removed means a type checker accepts any keyword rather than rejecting an unknown one (Codex #720 r1). That is the price of catching the legacy call at runtime to name its replacement; the alternative is a static error whose text is about argument counts. Worth revisiting once the break is old news, at which point **removed can go and the signature becomes exact.

feature/role default to a sentinel rather than being required so that a keyword-only legacy call (dimension(kind=…, value=…)) reaches the message below instead of a bare "missing 2 required positional arguments". The old shape never appeared in a release, so this refusal is the only notice it gets — a documented break (docs/deprecations.md).

Declare a drafting dimension from explicit measured values.

Named for what it carries (ADR 0016 / #873). dimension is referential on Drawing today and becomes so on :class:Sheet in #874 — it names a feature and a role, and the engine reads the value off the geometry. The verb that carries a number of its own needed a name saying so before that name could be reused. A measured dimension is the one place a value does NOT come from the part.

This is the concept-shaped Sheet API used by generated AP242 scripts: the source file may call the record PMI, but the editable script declares a dimension category, value, label, referenced model points, and optional structured tolerances. For ordinary geometry-backed edits prefer feature handles such as sheet.hole(...).tolerance(...). lower_bound and upper_bound are the mutually exclusive alternative to upper_tol/lower_tol for a limit range. source_id is the external record identity retained by generated imported-PMI scripts; hand-authored dimensions normally leave it blank. Delegates to :func:draftwright.model.declare.measured_dimension (#704), so build_drawing(model=…) callers can author the same feature without the façade.

A decoratable handle onto an existing feature — the hybrid seam (#463).

ref is a fluent handle this sheet issued, a feature index, a :class:Feature already in :attr:features (e.g. seeded by :meth:from_part), or the build123d object you built (matched by ⌀ + in-plane position). Returns the same fluent handle the declaration verbs do, so you can .fit(...) / .tolerance(...) — and, for a hole, .cbore(...) — a feature you did not declare from scratch. Raises if the object matches no feature or is ambiguous.

Declare a hole from the tool cylinder you subtracted (or explicit values). Returns a fluent handle: .through() (default) / .depth(d).

Declare a double-D bore from its cutter or explicit major ⌀ and A/F values.

Declare an external cylindrical diameter (a boss / OD) — the ⌀ is read off the object. Returns a handle: chain .tolerance(...) for a ± on the ⌀ (P2a).

Alias of :meth:diameter — an external cylindrical boss / OD.

Declare a regular polygonal-prism boss sized across flats and by height.

Declare whole regular polygonal-prism stock sized A/F and axially.

Declare one complete metric external spur involute gear requirement.

Declare one axial segment of a turned profile (its OD + length). A model with any step renders as a turned part. Returns a handle: .tolerance(...) tolerances the step length by default, .tolerance(..., on="diameter") its OD (P2a).

Declare a milled slot / reduced across-flats section (width + length).

Declare a blind rectangular recess — a floored slot/pocket (width × length × depth). From an object the depth axis defaults to the shortest bbox span; pass depth_axis= for a recess deeper than it is wide.

Declare a full-span floored channel (wall-to-wall width only).

Declare a bounded rectangular raised pad (footprint + X/Y location).

Its Z height is shared with the prismatic level ladder, so it is not independently double-dimensioned.

Declare a chamfer (bevelled edge) — sheet.chamfer(bevel_face) reads axis, legs and a point on the bevel off the oblique chamfer face, or explicit sheet.chamfer(axis="z", leg=6, at=(x, y, z)). leg = equal-leg 45° (C{leg}); leg1/leg2 = asymmetric.

Declare a fillet (rounded edge) — sheet.fillet(round_face) reads axis, radius and a point on the round off the cylindrical blend face, or explicit sheet.fillet(axis="z", radius=3, at=(x, y, z)). Called out R{radius} (grouped n× R for equal radii).

Declare a machined flat on round stock (#148b) — sheet.flat(flat_face) reads the leader point off the planar flat face (axis= and across= still required), or fully explicit sheet.flat(axis="z", across=15, at=(x, y, z)). Called out {across} A/F (across flats — flat-to-flat for a double-D / hex, the D height for a lone flat).

Declare a turned / circlip groove on round stock (#148c) — sheet.groove(floor_face) reads axis, width, diameter and the leader point off the reduced-OD floor face, or fully explicit sheet.groove(axis="z", width=3, diameter=16, at=(x, y, z)). Called out {width} WIDE × ø{diameter} (groove width + floor diameter).

Declare a thin slab's thickness (a base plate / wall / rib) — sheet.plate(slab_box) reads the thin axis + extent + centre off the slab, or explicit sheet.plate(axis="z", lo=0, hi=4, u=10, v=5). Only a multi-plate part dimensions plates (a single slab is the envelope).

Declare a turned body's axial furniture — OD, rotation axis, concentric bores (#945): sheet.rotational(od=30, bores=(16,), axis="z").

The last recognised kind without a declarative surface, which is why a generated script for a turned part could not declare its dimensions at all (#938).

Keyword-only, unlike its object-capable siblings — see :func:draftwright.model.rotational for why an object form would disagree with detection (#950).

Declare a prismatic height ladder + step-position shoulders (a rebated / stepped block) — sheet.step_level(part) reads base / interior levels / the (axis, position) shoulders / datum off the part, or explicit sheet.step_level(base=0, levels=(10,), shoulders=(("x", 30),)). A shoulder locates where a step changes height along a horizontal axis, so a stepped block is fully constrained (#555/#578).

Declare a hole pattern (bolt circle / linear array / grid) — build the member with :func:draftwright.model.hole.

Declare a linear/grid array of identical blind pockets (#841) — build the representative member with :func:draftwright.model.pocket. Renders as one grouped N× W × L × D DEEP callout + (n-1)× pitch dim(s), not N competing size dims.

Declare a linear/grid array of identical milled slots (#841) — build the representative member with :func:draftwright.model.slot. Renders as one grouped N× SLOT W × L leader + (n-1)× pitch dim(s), not N competing size dims.

Declare the overall bounding dimensions. Defaults to the whole part.

The no-argument form reuses an equal whole-part envelope already seeded by :meth:from_part; its returned handle therefore decorates and dimensions that detected feature instead of appending a duplicate. An explicit obj remains a distinct declaration, including when another envelope is already present.

Declare a datum feature symbol (ISO 5459). ref is a build123d planar face, or a feature handle / :class:Feature / index for a feature's axis. The target view + strip side are derived from the geometry; view/side override them (ADR 0011 P2c).

Declare a surface-finish symbol (ISO 1302, Ra) on ref — a build123d planar face or a feature. sheet.finish("3.2", top_face); view/side override the strip.

Declare a free-text manufacturing note (#488) on a leader to ref — a build123d planar face or a feature. The shop callouts detection can't infer: thread specs (sheet.note("M3x0.5 TAP", bore)), DEBURR, chip-relief, knurl. Placed like the GD&T items, clear of the views/title block; view/side override the derived strip.

Request a full section A–A (#841) — the part-level verb behind the auto section.

A section fires automatically only when a Z-axis hole/pattern has a counterbore, spotface, or blind bottom; a blind pocket has no such driving hole, so its floor and depth stay hidden-line-only. This forces a cut so that internal profile reads.

The cut plane is normal to Y. feature — a fluent handle / :class:Feature / index — cuts through that feature's centre (the natural "section through this pocket"); at=<y> cuts at an explicit Y; bare section() cuts through the part centre. The section renders last (its room check clears the right-of-side-view band), so declare it after the per-feature verbs. Chainable.

Ensure enlarged detail-view recovery is enabled (#42/#307/#841).

Automatic builds enable it by default; this verb is useful after constructing a Sheet(..., detail_view=False) or when an emitted declaration should state the choice explicitly. Adds a magnified crop of the step-height region when warranted (a no-op otherwise). Chainable. Not feature-targeted — for a blind pocket's floor/depth prefer :meth:section.

A GD&T feature-control-frame builder on ref — a feature handle / :class:Feature / index, or a build123d planar face. Chain one method per ISO 1101 characteristic (.position(0.1, to="A B") …); each stacks a frame on the target. The target view + strip are derived from the geometry; view/side override them (ADR 0011 P2c.2).

Declare a corner-block data table — positioned at :meth:build by the engine's generic auto-placer, clear of the views, title block, and annotations (the same machinery as the hole table), and lint-checked. rows is a sequence of equal-length row sequences (row 0 the header); cells are stringified. prefer is the page corner to sit nearest ("tr"/"tl"/"br"/"bl"). A table with no free corner records a table_dropped lint — it never overlaps. Revision blocks, BOMs and schedules all use this; :meth:notes is the single-column convenience over it.

Declare a manufacturing NOTES block — a single-column :meth:table of lines with a title header (None to omit) and optional 1 … auto-numbering::

sheet.notes(["BREAK ALL EDGES 0.3", "DEBURR", "M3x0.5 TAP"])

Soft deprecated (#1043) — prefer :meth:authored_dimensions in new code.

Supported, and not scheduled for removal: existing scripts keep working. But on this surface, authored dimensions are the right default, for three reasons:

• it is what draftwright itself emits — --script writes authored_dimensions() with a line per dimension, so the automatic path is the only form the tool never produces;
• omission means suppression (ADR 0016) only holds for an authored set. Under an automatic one you cannot express "not that one";
• an authored list is editable text. That is what makes "generate a script, then refine it" work, for a person or a model.

If you want the planner's choices as a starting point, generate them — draftwright yourmodule:part --script — and edit the result, rather than asking for them at runtime where they cannot be seen or changed.

Still asks for the planner's automatic set (ADR 0016). A build must say where its dimensions come from rather than defaulting silently (#874), and this is one of the two ways to say it. It is also what :meth:add_dimension augments.

build_drawing(part)'s automatic path is unaffected and carries no warning — that is the detected front door, and being automatic is its whole point.

Declare that the :meth:dimension lines in this script ARE the complete set.

The other half of :meth:auto_dimensions, and until #933 it did not exist: the authored source was entered implicitly, as a side effect of calling dimension() at least once. That left one thing unsayable — the complete set is empty — because absence of dimension(...) lines is also what a script with no source at all looks like, which _check_dimension_source must reject. So a valid PartModel carrying authored_dimensions=() built directly but could not be written as a script.

Calling dimension(...) still selects this source on its own; the verb only makes the choice sayable when there is nothing else to say it. Emitted scripts write it unconditionally, so an authored script states its source with a verb rather than with a comment a reader has to trust (ADR 0016 / #874).

Augment the planner's set with one more measurement (ADR 0016 / #872).

feature is a declared-feature handle (what :meth:hole, :meth:boss, … return), an index into :attr:features, or the IR feature itself. role names the measurement — "bore.diameter", "grid_pitch", … — and carries no number: the value is read from the geometry, so the size still lives in exactly one place.

Returns a :class:DimensionIntent.

Soft deprecated (#1043) — supported and not scheduled for removal, but it exists only to augment :meth:auto_dimensions, which is itself discouraged here. To add a measurement to an authored set, write a :meth:dimension line: same effect, and the result is visible in the script rather than computed at runtime.

Requesting a measurement the planner already emits is a deliberate no-op, not an error: a script should be able to ask without first knowing the rule set's mind.

axis disambiguates a role a feature carries more than once — today a grid pattern's two pitches. Omitting it there raises rather than picking one, because a silent coin toss between the row and column pitch is the kind of wrong a reader cannot see.

The IR the engine will draw (detection skipped) — for inspection. Wraps the declared features into a :class:PartModel without rendering a drawing (#453): the same wrapping :meth:build hands the engine (part bbox + corner datum + step- inferred orientation + the P2a decorations), so inspection pays no projection/anno cost and can't hit a layout/render failure. Wraps the solids body (as :func:_analyse does), so the bbox/datum match what build() draws even when the part carries bbox-extending non-solid geometry.

Gated on the dimension source like :meth:build (#874): this is the model the engine WOULD draw, so a sheet that cannot be built must not hand one out — otherwise build_drawing(part, model=sheet.model()) is a way around the check, and the two public surfaces disagree about the same sheet (the #707 class of divergence).

Build the :class:~draftwright.drawing.Drawing — detection skipped; only the declared features are drawn. Declared corner-block tables (:meth:table/:meth:notes) are placed last, clear of everything already on the sheet.

Build the drawing and write the requested formats — a format name or an iterable from ("svg", "dxf", "pdf", "png"), default PDF (matching the CLI); return {format: path}. dpi sets the PNG raster resolution. stem defaults to the drawing number, lower-cased.

formats=None means "unspecified", so it takes this method's default rather than being forwarded. On :meth:Drawing.export a None selects the deprecated legacy path, which would have returned a tuple — breaking the dict return documented above — and raised its warning against this line instead of the caller's (#987, Codex r5). Same attribution problem that moved make_drawing off that path.

A through hole (the default) — ⌀ only.

A blind hole d mm deep — adds a depth callout.

A ± tolerance on the bore ⌀: symmetric .tolerance(0.05) (→ ±0.05) or a limit pair .tolerance(0.0, 0.1) (→ +0.1 -0.0).

An ISO 286 fit class on the bore ⌀ — .fit("H7") renders ø8 H7 (the class, default) or, with show="deviation", the signed deviations ø8 +0.015/0 resolved for the bore's nominal ⌀. Raises for a class/size outside the built-in table (#29).

A counterbore on this hole. .cbore(cbore_cyl) reads its ⌀ + depth off the counterbore tool object (⌀ from the cylindrical face, depth from the part + tool along the hole axis — no numbers restated), or pass explicit .cbore(diameter=…, depth=…). An object supplies defaults; explicit kwargs override (#462).

A spotface on this hole — same as :meth:cbore but a shallow facing (#462).

A countersink on this hole (a flat-head screw seat, #575). .countersink(cone_tool) reads the major ⌀ + included angle off the build123d Cone you subtracted, or explicit .countersink(major=14, angle=90). Renders ⌵ Ø.. × ..° on the callout. An object supplies defaults; explicit kwargs override (#451).

A thread/tap spec folded onto this hole's callout (#764). .thread("M3x0.5") renders the tap/thread on the bore leader (e.g. ø2.5 THRU M3x0.5) — a structured aspect that round-trips, so .thread(...).finish(...) gives Ra-on-thread. A declaration-only aspect (threads are cosmetic, not modelled geometry — no recogniser).

A surface-finish symbol (Ra) on this hole's bore (ADR 0011 P2c). .finish("1.6") — the roughness text; view/side override the derived strip.

A free-text manufacturing note on a leader to this hole (#488). .note("M3x0.5 TAP") — the shop callout; view/side override the derived strip.

A ± tolerance on this dimension: symmetric .tolerance(0.05) (→ ±0.05) or a limit pair .tolerance(0.0, 0.1) (→ +0.1 -0.0). on picks the parameter for a multi-dim feature — a step's "length" (default) vs its "diameter" (OD).

An ISO 286 fit class on this feature's ⌀ (always the diameter — a fit is diametral, so a step's fit is on its OD, not its length). .fit("h6") renders ø12 h6 (the class, default) or show="deviation" the signed deviations ø12 0/-0.011 resolved for the nominal ⌀. Raises for a class/size outside the built-in table (#29).

A surface-finish symbol (Ra) on this feature's surface (ADR 0011 P2c). diameter(journal).finish("0.8"); view/side override the derived strip.

A free-text manufacturing note on a leader to this feature (#488). diameter(knurl).note("KNURL 0.8 STRAIGHT"); view/side override the strip.

A knurl callout on this diameter (#765) — diameter(shaft).knurl("0.8") → KNURL 0.8 STRAIGHT, or .knurl("0.8", "DIAMOND"). Named sugar over :meth:note (canonical formatting + discoverability): knurl is a text callout on a leader, not modelled geometry, so no IR/render — it flows through the same note path. view/ side override the derived strip.

An EXTERNAL thread spec appended to this OD's ⌀ callout (#859) — the turned analog of :meth:_Hole.thread. step(shaft).thread("M3x0.5") renders ø3 M3x0.5; a structured aspect on the feature, so .thread(...).finish(...) gives Ra-on-thread. Declaration-only (threads are cosmetic, rarely modelled as geometry — no recogniser).

A ± tolerance: symmetric .tolerance(0.05) (→ ±0.05) or a limit pair .tolerance(0.0, 0.1) (→ +0.1 -0.0). on targets ONE parameter by role (on="depth" on a pocket → a role-keyed decoration); omit on to tolerance every parameter of the feature alike (the kind-keyed form).

A free-text manufacturing note (#841). With no ref the note anchors to THIS feature — sheet.slot(...).note("5X OBROUND SLOT") — mirroring :meth:_Hole.note / :meth:_Dim.note (previously this raised, because the forwarded Sheet.note needs a target). An explicit ref (a face or feature) still forwards to :meth:Sheet.note, preserving the handle's forwarding contract for sheet.slot(...).note("DEBURR", face). Returns the handle (chainable); view/side override the derived strip.

Apply straightness tolerance tol; no datum reference is permitted.

Apply flatness tolerance tol; no datum reference is permitted.

Apply circularity tolerance tol; no datum reference is permitted.

Apply cylindricity tolerance tol; no datum reference is permitted.

Apply line-profile tolerance tol, optionally relative to datum(s) to.

Apply surface-profile tolerance tol, optionally relative to datum(s) to.

Apply angularity tolerance tol relative to datum(s) to.

Apply perpendicularity tolerance tol relative to datum(s) to.

Apply parallelism tolerance tol relative to datum(s) to.

Apply position tolerance tol relative to to; diameter selects the zone.

Apply concentricity tolerance tol relative to to; diameter selects the zone.

Apply symmetry tolerance tol relative to datum(s) to.

Apply circular-runout tolerance tol relative to datum(s) to.

Apply total-runout tolerance tol relative to datum(s) to.