b3dkit 0.1.5__tar.gz → 0.4.0__tar.gz

b3dkit-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,72 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install and test
+        run: |
+          python -m pip install --upgrade pip build
+          python -m pip install -e ".[dev]"
+          pytest -q
+
+      - name: Check the tag matches the packaged version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version=$(python -c "import re,pathlib;print(re.search(r'^version = \"([^\"]+)\"',pathlib.Path('pyproject.toml').read_text(),re.M).group(1))")
+          if [ "$tag" != "$version" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match pyproject version $version"
+            exit 1
+          fi
+          echo "tag and version agree: $version"
+
+      - name: Build
+        run: python -m build
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write        # required for PyPI Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  smoke-test:
+    # Install the published artifact from PyPI and build something, mirroring the
+    # post-upload check the retired build.sh performed by hand.
+    needs: publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Wait for PyPI to serve the new version
+        run: sleep 60
+      - name: Install from PyPI and build a part
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          python -m pip install --upgrade pip
+          python -m pip install "b3dkit==$version"
+          python -c "from b3dkit import Divot; assert Divot().is_valid; print('smoke test OK')"

b3dkit-0.4.0/.github/workflows/test.yml

@@ -0,0 +1,99 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: test-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+        build123d: [latest]
+        include:
+          # One job pinned at the declared dependency floor. b3dkit 0.1.5 shipped
+          # code that could not run against its own advertised minimum; this job
+          # is what stops that from happening again.
+          - python-version: "3.12"
+            build123d: floor
+
+    name: py${{ matrix.python-version }} / build123d ${{ matrix.build123d }}
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Pin build123d to the declared floor
+        if: matrix.build123d == 'floor'
+        run: |
+          floor=$(python -c "import re,pathlib;print(re.search(r'build123d>=([0-9.]+)',pathlib.Path('pyproject.toml').read_text()).group(1))")
+          echo "Installing build123d==$floor"
+          python -m pip install "build123d==$floor"
+
+      - name: Show resolved versions
+        run: python -c "import sys,build123d;print(sys.version);print('build123d',build123d.__version__)"
+
+      - name: Run tests
+        run: pytest --cov=b3dkit --cov-report=term-missing --junitxml=junit.xml
+
+      - name: Fail if any test was skipped
+        # A green suite that silently skips is how the broken 0.10.0 floor reached
+        # PyPI: 27 tests were skipped and nothing complained.
+        if: always()
+        run: |
+          python - <<'PY'
+          import sys, xml.etree.ElementTree as ET
+          suite = ET.parse("junit.xml").getroot()
+          skipped = sum(int(s.get("skipped", 0)) for s in suite.iter("testsuite"))
+          if skipped:
+              print(f"::error::{skipped} test(s) skipped; the skip budget is zero")
+              sys.exit(1)
+          print("No skipped tests.")
+          PY
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+      - 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/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.5
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+        stages: [manual]
+
+  - repo: https://github.com/psf/black
+    rev: 25.9.0
+    hooks:
+      - id: black
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-toml
+      - id: check-yaml
+      - id: check-merge-conflict

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.1.5 → 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