b3dkit 0.3.2__tar.gz → 0.4.0__tar.gz

{b3dkit-0.3.2 → b3dkit-0.4.0}/.github/workflows/test.yml

@@ -79,3 +79,21 @@ jobs:
       - run: python -m pip install --upgrade pip ruff black
       - run: ruff check .
       - run: black --check .
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install documentation dependencies only
+        # No build123d here on purpose: mkdocstrings reads the source with
+        # griffe, which analyses statically. If this job ever needs a CAD
+        # kernel, something has started importing the package to build docs.
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r docs/requirements.txt
+      - name: Build the site
+        run: mkdocs build --strict

b3dkit-0.4.0/CHANGELOG.md

@@ -0,0 +1,116 @@
+# Changelog
+
+All notable changes to b3dkit are documented here. This project follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+[Semantic Versioning](https://semver.org/). b3dkit is `0.x`, so breaking changes
+ship in minor releases.
+
+## [Unreleased]
+
+## [0.4.0] - 2026-09-08
+
+### Removed
+
+- **`TwistSnapConnector` no longer accepts `tolerance` or `wall_width`.** Both
+  were read by nothing. All fit clearance lives on the socket, which opens its
+  bore to `connector_radius + tolerance`; applying it on the connector as well
+  would have doubled the gap. Geometry is unchanged.
+- **`HexCylindrical` no longer accepts `rotation` or `align`.** Both were inert.
+  Its cutters are positioned against the surface they wrap, so moving them off
+  it is never useful. Rotate the `cylindrical` argument instead.
+- **`thumb_radius` removed from `high_top_slide_box`**, where it was threaded
+  through four signatures and read by nothing. It remains live in `slide_box`.
+- `docs/conf.py` and `docs/Makefile`, dead Sphinx configuration that was being
+  served as static assets on the published site.
+
+### Added
+
+- **`dovetail_split(part, start, end, **kwargs) -> tuple[Part, Part]`** builds a
+  mating pair from one argument set, so the two halves cannot diverge.
+- **Generated API reference.** Signatures and arguments now come from the source
+  via mkdocstrings and cannot drift from it.
+- **`py.typed`**, so downstream type checkers see b3dkit's annotations, and
+  `b3dkit.__version__`.
+- Input validation on `high_top_slide_box`: dimensions leaving less than
+  `wall_thickness` above `top_height + rail_height` previously produced a part
+  in three pieces and now raise.
+- `CONTRIBUTING.md`, this changelog, CI across Python 3.11-3.13, and a release
+  workflow publishing through PyPI Trusted Publishing.
+
+### Changed
+
+- **`dovetail_subpart` rejects arguments the chosen style would discard.** Each
+  style uses only a subset of the shaping arguments; the rest were accepted and
+  silently ignored. Passing one now raises `ValueError` naming the styles it
+  applies to.
+- **`Point` is stricter and immutable.** `Point((3, 4))` now works, where a
+  tuple was previously mis-parsed into `Point(x=(3, 4), y=None)`; `Point(3)` and
+  `Point()` raise instead of building a half-initialised point;
+  `axial_distance_to` raises for any axis but `Axis.X` or `Axis.Y`, where it
+  previously returned the Y distance for all of them; assigning to `x` or `y`
+  raises.
+- **`anti_chamfer` refuses the wrong builder.** It identified itself as
+  `"chamfer"` in build123d's internal dispatch table, inheriting permission to
+  run inside a `BuildSketch`, where it completed silently and did the wrong
+  thing. It now raises and applies to `BuildPart` only.
+- **`slide_box()` no longer packs or colours its result.** Print orientation is
+  kept; bed layout and viewer tint were presentation baked into geometry. Call
+  build123d's `pack()` yourself if you want the parts arranged.
+- **Eight Part objects now validate their builder context** — `BallMount`,
+  `BallSocket`, `SquareNutSinkhole`, `Divot`, `HexWall`, `HexCylindrical`,
+  `TwistSnapConnector`, `TwistSnapSocket`. Using one inside a `BuildSketch`
+  previously produced no error and the wrong output.
+- **`ocp_vscode` is now an optional `[viewer]` extra.** No library code path used
+  it; all nine imports fed only `__main__` demo blocks. Installing b3dkit no
+  longer pulls a viewer, web server and tessellation stack.
+- **Python 3.11 or newer** is required. `ocp_tessellate`, reached through
+  `ocp_vscode`, imports `typing.NotRequired`, which is 3.11+.
+- Documentation builds no longer install the package, so ReadTheDocs stops
+  pulling the OpenCascade wheels to render Markdown.
+
+### Fixed
+
+- **`dovetail_subpart` silently ignored four documented arguments.**
+  `linear_offset`, `tail_angle_offset`, `length_ratio` and `depth_ratio` were
+  accepted, passed one level down and dropped, so the module reported full line
+  coverage while four public knobs did nothing. Introduced when `subpart_section`
+  was extracted in "initial T Slot dovetail support". Callers who passed none of
+  them get identical geometry; callers who passed any get the geometry they
+  asked for.
+- **Every documented example now runs.** The documentation described functions
+  that never existed (`heatsink_insert_cut`, `nut_cut`, `screw_cut`,
+  `socket_subpart`, `half_part`), imported others from the wrong module, listed
+  `anti_chamfer`'s arguments in the wrong order, and gave the dovetail
+  `tolerance` default as 0.05 where the source says 0.025.
+
+### Renamed
+
+| Old | New | Notes |
+|---|---|---|
+| `DovetailPart` | `DovetailSubpart` | The old name read as a build123d `Part`, which is the function's return type |
+| `section=` | `subpart=` | `section` collides with build123d's own slice operation |
+| `slide_tolerance=` | `tolerance=` | One module used two names and three defaults for one concept |
+| `nut_legnth=` | `nut_length=` | Misspelled keyword argument |
+| `subpart_section` | `_subpart_slab` | Private; it lofts a Z-slab |
+
+Ten dovetail internals and `slider_template` became private. Nothing outside the
+package used them.
+
+`from b3dkit import *` no longer re-exports build123d. The namespace went from
+129 names, 72 of them third-party, to the library's own. Import `Box`, `Mode`,
+`Part` and friends from `build123d`.
+
+## [0.3.2] - 2026-09-06
+
+First release through the automated pipeline. Contains the dovetail argument
+forwarding fix, the `__all__` export surface, the `DovetailSubpart` rename and
+the Python 3.11 floor.
+
+## [0.1.5] and earlier
+
+See the git history. b3dkit began as `fb-library`; the rename accompanied a
+rewrite that reworked names and usage to feel closer to native build123d.
+
+[Unreleased]: https://github.com/x0pherl/b3dkit/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/x0pherl/b3dkit/releases/tag/v0.4.0
+[0.3.2]: https://github.com/x0pherl/b3dkit/releases/tag/v0.3.2

b3dkit-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,109 @@
+# Contributing to b3dkit
+
+Thank you for considering a contribution. Bug reports, fixes, docs and tests are
+all welcome.
+
+If you are unsure where to start, open an issue and describe your idea. Early
+feedback prevents rework.
+
+## Development Setup
+
+1. Fork and clone the repository.
+2. Create and activate a virtual environment (Python 3.11 or newer).
+3. Install with the development extras:
+
+```bash
+pip install -e ".[dev]"
+```
+
+4. Run the tests:
+
+```bash
+pytest --cov
+```
+
+The `dev` extra pulls in `ocp_vscode` so the tests that execute each module's
+`__main__` demo can run. The library itself never imports it — see
+[Dependencies](#dependencies).
+
+## Testing Standards
+
+Tests are required for substantive changes.
+
+- **Coverage floor is 90%**, measured on library code. It is a floor, not a
+  target, and there is no ratchet: a change that lowers coverage while deleting
+  a test that asserted nothing is an improvement.
+- **Every test must be able to fail.** No test should pass without asserting on
+  a value the code produced. Tests that exist only to execute lines for coverage
+  credit are worse than no test, because they make the coverage number lie.
+- **Assert on geometry, not just validity.** `is_valid` is true for nearly any
+  closed solid, including one built with every argument ignored. Prefer volume,
+  bounding box, solid count, or a raised exception. Where a change should alter
+  geometry, assert that it *differs* from the default; where it should not,
+  assert that it does not.
+- **Bug fixes need a test that fails before the fix.**
+- Run `pytest` before opening a pull request.
+
+Two invariants are enforced mechanically rather than by review, because this
+project is largely self-reviewed:
+
+- `tests/test_public_api.py` walks `__all__` and checks that every export is
+  b3dkit's own, is documented, and follows the Part object contract.
+- `tests/test_docs.py` executes every fenced `python` block in `README.md` and
+  `docs/`, in document order.
+
+## Documentation Standards
+
+Documentation is part of the change, not a follow-up. Update it in the same
+commit.
+
+- **Signatures and arguments are generated** by mkdocstrings from the source.
+  Do not hand-write them in `docs/`; a second copy is what let the old
+  documentation drift from the code.
+- **Prose pages carry what the reference cannot**: what something is for, how to
+  choose between two options, print settings, tolerances, troubleshooting.
+- **Examples must run.** They are executed by the test suite.
+- **State units.** All linear dimensions are in millimeters and all angles in
+  degrees; say so for any argument where it could be ambiguous.
+- Build the site locally with `mkdocs build --strict`.
+
+## Dependencies
+
+The library imports `build123d` and nothing else. `ocp_vscode` is an optional
+`[viewer]` extra used only by the `__main__` demo blocks, so that installing
+b3dkit headlessly does not pull a viewer, web server and tessellation stack.
+
+If you add an import to library code, ask whether it belongs in
+`dependencies` or in an extra.
+
+## build123d Compatibility
+
+b3dkit declares a minimum build123d version and CI runs one job pinned at
+exactly that floor. Please keep it honest: if you use an API added in a newer
+release, raise the floor in `pyproject.toml` in the same change. b3dkit 0.1.5
+shipped code that could not run against its own advertised minimum, which is
+what that CI job exists to prevent.
+
+Do not add an upper bound. Caps propagate into every downstream resolution and
+convert a runtime failure into an install failure for everyone.
+
+## Public API
+
+`b3dkit.__all__` is the public API. Anything not listed is an implementation
+detail and may change. When adding an export, add it to the module's `__all__`
+and to the package's, and give it a docstring — the contract tests check both.
+
+## Versioning
+
+b3dkit is `0.x`, so breaking changes ship in minor releases. Each release is
+tagged `vX.Y.Z`, matching the version in `pyproject.toml`; the release workflow
+refuses to publish if they disagree.
+
+## Pull Request Checklist
+
+- [ ] Tests added or updated, and each can fail
+- [ ] `pytest` passes
+- [ ] `ruff check .` and `black --check .` pass
+- [ ] Documentation updated in the same commit
+- [ ] `mkdocs build --strict` passes if you touched `docs/`
+- [ ] PR describes what changed and why

b3dkit-0.4.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: b3dkit
+Version: 0.4.0
+Summary: build123d libraries and utilities
+Project-URL: Homepage, https://github.com/x0pherl/b3dkit
+Project-URL: Issues, https://github.com/x0pherl/b3dkit/issues
+Project-URL: Documentation, https://b3dkit.readthedocs.io
+Project-URL: Changelog, https://github.com/x0pherl/b3dkit/blob/main/CHANGELOG.md
+Author: x0pherl
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 3d-printing,build123d,cad,opencascade,parametric
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: build123d>=0.11.0
+Provides-Extra: dev
+Requires-Dist: ocp-vscode>=3.1.1; extra == 'dev'
+Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.2; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: markdown-include>=0.8.1; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.7.6; extra == 'docs'
+Requires-Dist: mkdocs>=1.6.1; extra == 'docs'
+Provides-Extra: maintain
+Requires-Dist: build>=1.4.0; extra == 'maintain'
+Requires-Dist: hatch-vcs>=0.5.0; extra == 'maintain'
+Requires-Dist: hatchling>=1.29.0; extra == 'maintain'
+Requires-Dist: twine>=6.2.0; extra == 'maintain'
+Provides-Extra: viewer
+Requires-Dist: ocp-vscode>=3.1.1; extra == 'viewer'
+Description-Content-Type: text/markdown
+
+# b3dkit
+
+Utilities for [build123d](https://github.com/gumyr/build123d) parts that have to be
+**printed and assembled**: splitting parts too big for the bed, snapping them
+together, fastening them, and venting them.
+
+All linear dimensions are in millimeters and all angles are in degrees, matching
+build123d.
+
+## Installation
+
+```bash
+pip install b3dkit
+```
+
+Requires Python 3.11+ and build123d 0.11+. To run the `__main__` demo in each
+module, which previews parts in VS Code, install the viewer extra:
+
+```bash
+pip install b3dkit[viewer]
+```
+
+## What's in it
+
+| | |
+|---|---|
+| **dovetail** | Splits a `Part` into two that slide together with tight tolerances, for parts larger than your build volume. Includes a "snugtail" style suited to 3D printing, which wraps three sides for a large friction and glue surface. |
+| **click_fit** | A tapered divot that prints and assembles better than a half sphere, letting parts click into place. |
+| **twist_snap** | A connector and socket that lock with a twist, for joints meant to be opened repeatedly. |
+| **ball_socket** | A ball mount and matching socket. |
+| **bolt_fittings** | Bolt holes, countersinks, nut traps and heat-set insert recesses, sized for M3 by default. |
+| **hexwall** | A honeycomb of hexagonal holes, flat or wrapped around a cone or cylinder, for venting and lightening. |
+| **basic_shapes** | Rounded, polygonal, diamond and teardrop cylinders, plus the trigonometry helpers that place them. |
+| **antichamfer** | Extends a face outward with a taper, like a foot or flat crown moulding. |
+| **slide_box**, **high_top_slide_box** | Boxes with sliding lids. |
+| **Point** | A lightweight 2D point with the geometry helpers the rest of the library needs. |
+
+## Example
+
+```python
+from build123d import Align, Box, BuildPart, Mode
+from b3dkit import DovetailStyle, Point, dovetail_split
+
+with BuildPart(mode=Mode.PRIVATE) as oversized:
+    Box(50, 40, 50, align=(Align.CENTER, Align.CENTER, Align.MIN))
+
+# split it into a mating pair that fits the bed
+tail, socket = dovetail_split(
+    oversized.part,
+    Point(0, -20),
+    Point(0, 20),
+    style=DovetailStyle.SNUGTAIL,
+)
+```
+
+## Documentation
+
+Full documentation, including a generated API reference, is at
+[b3dkit.readthedocs.io](https://b3dkit.readthedocs.io).
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first to
+discuss what you would like to change.
+
+## History
+
+b3dkit began as `fb-library`, a way to isolate common utilities from
+[Fender-Bender](https://github.com/x0pherl/fender-bender). It outgrew that
+project, and was renamed during a rewrite that reworked names and usage to feel
+closer to native build123d.
+
+## License
+
+Licensed under the terms of the [MIT](https://choosealicense.com/licenses/mit/)
+license.

b3dkit-0.4.0/README.md

@@ -0,0 +1,76 @@
+# b3dkit
+
+Utilities for [build123d](https://github.com/gumyr/build123d) parts that have to be
+**printed and assembled**: splitting parts too big for the bed, snapping them
+together, fastening them, and venting them.
+
+All linear dimensions are in millimeters and all angles are in degrees, matching
+build123d.
+
+## Installation
+
+```bash
+pip install b3dkit
+```
+
+Requires Python 3.11+ and build123d 0.11+. To run the `__main__` demo in each
+module, which previews parts in VS Code, install the viewer extra:
+
+```bash
+pip install b3dkit[viewer]
+```
+
+## What's in it
+
+| | |
+|---|---|
+| **dovetail** | Splits a `Part` into two that slide together with tight tolerances, for parts larger than your build volume. Includes a "snugtail" style suited to 3D printing, which wraps three sides for a large friction and glue surface. |
+| **click_fit** | A tapered divot that prints and assembles better than a half sphere, letting parts click into place. |
+| **twist_snap** | A connector and socket that lock with a twist, for joints meant to be opened repeatedly. |
+| **ball_socket** | A ball mount and matching socket. |
+| **bolt_fittings** | Bolt holes, countersinks, nut traps and heat-set insert recesses, sized for M3 by default. |
+| **hexwall** | A honeycomb of hexagonal holes, flat or wrapped around a cone or cylinder, for venting and lightening. |
+| **basic_shapes** | Rounded, polygonal, diamond and teardrop cylinders, plus the trigonometry helpers that place them. |
+| **antichamfer** | Extends a face outward with a taper, like a foot or flat crown moulding. |
+| **slide_box**, **high_top_slide_box** | Boxes with sliding lids. |
+| **Point** | A lightweight 2D point with the geometry helpers the rest of the library needs. |
+
+## Example
+
+```python
+from build123d import Align, Box, BuildPart, Mode
+from b3dkit import DovetailStyle, Point, dovetail_split
+
+with BuildPart(mode=Mode.PRIVATE) as oversized:
+    Box(50, 40, 50, align=(Align.CENTER, Align.CENTER, Align.MIN))
+
+# split it into a mating pair that fits the bed
+tail, socket = dovetail_split(
+    oversized.part,
+    Point(0, -20),
+    Point(0, 20),
+    style=DovetailStyle.SNUGTAIL,
+)
+```
+
+## Documentation
+
+Full documentation, including a generated API reference, is at
+[b3dkit.readthedocs.io](https://b3dkit.readthedocs.io).
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first to
+discuss what you would like to change.
+
+## History
+
+b3dkit began as `fb-library`, a way to isolate common utilities from
+[Fender-Bender](https://github.com/x0pherl/fender-bender). It outgrew that
+project, and was renamed during a rewrite that reworked names and usage to feel
+closer to native build123d.
+
+## License
+
+Licensed under the terms of the [MIT](https://choosealicense.com/licenses/mit/)
+license.

b3dkit-0.4.0/docs/CONTRIBUTING.md

@@ -0,0 +1 @@
+{!CONTRIBUTING.md!}

{b3dkit-0.3.2 → b3dkit-0.4.0}/docs/antichamfer.md

@@ -10,12 +10,25 @@ The `antichamfer` module provides functionality to create anti-chamfers. An anti
 
 #### arguments
 
- - length: the depth of the anti-chamfer (how far to offset inward from the original face)
- - length2: the width of the taper at the bottom (optional, defaults to length if not specified)
- - face: the face or faces to apply the anti-chamfer to (can be a single Face or an iterable of Faces)
+`anti_chamfer(face, length, length2=None) -> Part`
+
+ - `face`: the face or faces to apply the anti-chamfer to (a single `Face` or an iterable of `Face`)
+ - `length`: how far the anti-chamfer extends outward from the original face, in mm
+ - `length2`: the width of the taper measured across the face, in mm (optional, defaults to `length`)
 
 The function creates a tapered extrusion that extends outward from the specified faces. The taper angle is calculated based on the ratio of length2 to length, creating different bevel profiles depending on these values.
 
+#### builder context
+
+`anti_chamfer` applies to `BuildPart` only; calling it inside a `BuildSketch` or `BuildLine` raises `RuntimeError`. Inside a `BuildPart` the context object is replaced with the result. Outside any builder it returns a new `Part` and leaves its input alone.
+
+Like build123d's own `chamfer` and `fillet`, it takes no `mode` argument.
+
+#### raises
+
+ - `ValueError`: if no faces are given, if any object passed is not a `Face`, or if the faces do not belong to a `Part`
+ - `RuntimeError`: if called inside a builder other than `BuildPart`
+
 ## Usage Notes
 
 - When length2 is not specified, the anti-chamfer creates a 45-degree bevel
@@ -44,7 +57,6 @@ result = anti_chamfer(
     base_part.faces().filter_by(Axis.Z)[-1],  # top face
     2.0,  # length
     2.0,  # length2
-    
 )
 
 # Apply anti-chamfer to multiple faces with different taper

b3dkit-0.4.0/docs/basic_shapes.md

@@ -0,0 +1,129 @@
+# Basic Shapes
+
+Utility functions for creating and manipulating basic 3D shapes and geometric calculations. These functions extend build123d's capabilities with shapes and operations commonly used in 3D design.
+
+## Geometric Calculation
+
+### adjacent_length
+
+Calculates the adjacent side length of a right triangle given the angle and opposite side length.
+
+### apothem_to_radius
+
+**Arguments**
+- `apothem` (float): The apothem of the polygon
+- `side_count` (int): The number of sides of the poygon.
+
+### circular_intersection
+
+calculates the circumradius of a regular polygon given its apothem
+    
+Finds the intersection point along one axis given a coordinate on the other axis of a circle's perimeter.
+
+**Raises:**
+- `ValueError`: If coordinate is greater than radius or negative
+
+### distance_to_circle_edge
+
+Calculates the distance from a given point to the edge of a circle in a specified direction.
+
+**Raises:**
+- `ValueError`: If the ray does not meet the circle at all
+
+### opposite_length
+
+Calculates the opposite side length of a right triangle given the angle and adjacent side length.
+
+### radius_to_apothem
+
+## Part Classes
+
+### DiamondCylinder
+Part Object: DiamondCylinder
+
+Creates an extruded diamond (4-sided polygon) that behaves like a cylinder. This is a convenience wrapper for `PolygonalCylinder` with 4 sides.
+
+**Arc Size Behavior:**
+- `arc_size=360` produces the full diamond profile
+- `arc_size<360` clips the XY profile and reduces volume while preserving Z behavior from `height` and `stretch[2]`
+
+### DiamondTorus
+
+Part Object: DiamondTorus
+
+Creates a torus by sweeping a diamond (square rotated 45°) along a circular path.
+
+Creates a torus by sweeping a diamond (square rotated 45°) along a circular path.
+
+        or MAX of object. Defaults to (Align.CENTER, Align.CENTER, Align.CENTER)
+- `mode` (Mode, optional): combine mode. Defaults to Mode.ADD
+
+### PolygonalCylinder
+
+Part Object: PolygonalCylinder
+
+Creates an extruded regular polygon that behaves like a cylinder.
+
+**Arc Size Behavior:**
+- `arc_size=360` keeps the full regular polygonal profile
+- `arc_size<360` clips the XY profile and reduces volume while preserving Z behavior from `height` and `stretch[2]`
+
+### RoundedCylinder
+
+Part Object: RoundedCylinder
+
+Creates a cylinder with rounded (filleted) top and bottom edges.
+
+        or MAX of object. Defaults to (Align.CENTER, Align.CENTER, Align.CENTER)
+- `mode` (Mode, optional): combine mode. Defaults to Mode.ADD
+
+**Raises:**
+- `ValueError`: If height is not greater than radius * 2
+
+### TeardropCylinder
+
+Part Object: TeardropCylinder
+
+Creates a 3D teardrop-shaped cylinder by extruding a teardrop sketch. Particularly useful for creating holes that print well on FDM printers without supports.
+
+### Teardrop
+
+Sketch Object: Teardrop
+
+Creates a 2D teardrop-shaped sketch. The shape is useful for 3D printing holes that minimize overhangs.
+
+        or MAX of object. Defaults to (Align.CENTER, Align.CENTER)
+- `mode` (Mode, optional): combine mode. Defaults to Mode.ADD
+
+## Examples
+
+```python
+from build123d import BuildPart, Mode
+from b3dkit import (
+    DiamondTorus,
+    RoundedCylinder,
+    TeardropCylinder,
+    adjacent_length,
+    opposite_length,
+)
+
+# A cylinder with rounded ends
+rounded_cyl = RoundedCylinder(radius=10, height=30)
+
+# A torus swept from a diamond profile
+torus = DiamondTorus(major_radius=20, minor_radius=3)
+
+# A teardrop hole, which prints without support when the axis is horizontal
+with BuildPart() as part:
+    RoundedCylinder(radius=5, height=30)   # height must exceed radius * 2
+    TeardropCylinder(
+        radius=5,
+        peak_distance=6,
+        height=15,
+        mode=Mode.SUBTRACT,
+    )
+
+# Right-triangle helpers, useful when laying out tapers
+opp = opposite_length(30, 10)   # 30 degree angle, adjacent side of 10
+adj = adjacent_length(45, 5)    # 45 degree angle, opposite side of 5
+```