yapcad.fasteners package

Submodules

yapcad.fasteners.builders module

Fastener construction using catalog data.

This module builds fasteners using dimensions from YAML catalogs, delegating to the core thread generation in yapcad.threadgen.

yapcad.fasteners.builders.build_hex_bolt_from_catalog(thread_series: str, size: str, length: float, tolerance_class: str = '6g', thread_length: float | None = None, starts: int = 1, thread_arc_samples: int = 180, thread_samples_per_pitch: int = 6, catalog_path: Path | None = None)[source]

Build a hex bolt using catalog dimensions.

Parameters:

  • thread_series – “metric_coarse”, “unified_coarse”, etc.

  • size – Size designation from catalog

  • length – Shank length in mm

  • tolerance_class – Thread tolerance class

  • thread_length – Thread length in mm (or computed if None)

  • starts – Number of thread starts

  • thread_arc_samples – Angular samples for thread surface

  • thread_samples_per_pitch – Profile samples per pitch

  • catalog_path – Optional custom catalog path

Returns:

yapCAD solid representing the bolt

yapcad.fasteners.builders.build_hex_nut_from_catalog(thread_series: str, size: str, tolerance_class: str = '6H', handedness: str = 'right', starts: int = 1, thread_arc_samples: int = 180, thread_samples_per_pitch: int = 6, catalog_path: Path | None = None)[source]

Build a hex nut using catalog dimensions.

Parameters:

  • thread_series – “metric_coarse”, “unified_coarse”, etc.

  • size – Size designation from catalog

  • tolerance_class – Thread tolerance class

  • handedness – “right” or “left”

  • starts – Number of thread starts

  • thread_arc_samples – Angular samples for thread surface

  • thread_samples_per_pitch – Profile samples per pitch

  • catalog_path – Optional custom catalog path

Returns:

yapCAD solid representing the nut

yapcad.fasteners.catalog module

Fastener catalog loading with bundled data and external override support.

This module provides a flexible catalog system for fastener dimensions: - Bundled YAML data files for common metric and unified sizes - Environment variable override for custom data directories - User config directory support (~/.config/yapcad/fasteners/) - Explicit path override in API calls

Environment Variables:
YAPCAD_FASTENER_DATA: Colon-separated (or semicolon on Windows) paths

to directories containing custom YAML catalog files. These are searched before bundled data.

Example

export YAPCAD_FASTENER_DATA=”/path/to/my/fasteners:/another/path”

yapcad.fasteners.catalog.clear_cache() → None[source]

Clear all cached catalog data.

Call this if you modify external catalog files and want to reload.

yapcad.fasteners.catalog.get_bolt_data(thread_series: str, size: str, tolerance_class: str = '6g', custom_path: Path | None = None) → Dict[str, Any][source]

Get complete data for creating a hex bolt.

Parameters:

  • thread_series – Thread series name

  • size – Size designation

  • tolerance_class – Thread tolerance class (default “6g” for metric)

  • custom_path – Optional custom catalog path

Returns:

  • thread: dict with diameter, pitch, tolerances

  • head: dict with width_across_flats, height, etc.

Return type:

Dict with all data needed to create a bolt

Raises:

KeyError – If size not found or no bolt data available

yapcad.fasteners.catalog.get_nut_data(thread_series: str, size: str, tolerance_class: str = '6H', custom_path: Path | None = None) → Dict[str, Any][source]

Get complete data for creating a hex nut.

Parameters:

  • thread_series – Thread series name

  • size – Size designation

  • tolerance_class – Thread tolerance class (default “6H” for metric internal)

  • custom_path – Optional custom catalog path

Returns:

  • thread: dict with diameter, pitch, tolerances

  • body: dict with width_across_flats, thickness, etc.

Return type:

Dict with all data needed to create a nut

Raises:

KeyError – If size not found or no nut data available

yapcad.fasteners.catalog.get_thread_data(thread_series: str, size: str, tolerance_class: str | None = None, custom_path: Path | None = None) → Dict[str, Any][source]

Get thread dimension data for a specific size.

Parameters:

  • thread_series – Thread series name

  • size – Size designation (e.g., “M8”, “1/4-20”)

  • tolerance_class – Optional tolerance class to validate exists

  • custom_path – Optional custom catalog path

Returns:

  • nominal_diameter: float (mm)

  • pitch: float (mm)

  • basic_minor_diameter: float (mm)

  • basic_pitch_diameter: float (mm)

  • tolerances: dict of tolerance class data

  • hex_bolt: dict of bolt head dimensions (if present)

  • hex_nut: dict of nut dimensions (if present)

Return type:

Dict with thread dimensions

Raises:

KeyError – If size or tolerance_class not found

yapcad.fasteners.catalog.list_available_sizes(thread_series: str, custom_path: Path | None = None) → List[str][source]

List all available sizes for a thread series.

Parameters:

  • thread_series – Thread series name

  • custom_path – Optional custom catalog path

Returns:

List of size strings (e.g., [“M3”, “M4”, “M5”, …])

yapcad.fasteners.catalog.list_tolerance_classes(thread_series: str, custom_path: Path | None = None) → List[str][source]

List available tolerance classes for a thread series.

Parameters:

  • thread_series – Thread series name

  • custom_path – Optional custom catalog path

Returns:

List of tolerance class strings (e.g., [“6g”, “6H”, “4g6g”])

yapcad.fasteners.catalog.load_catalog(thread_series: str, custom_path: Path | None = None) → Dict[str, Any][source]

Load fastener catalog for a thread series.

Parameters:

  • thread_series – One of “metric_coarse”, “metric_fine”, “unified_coarse”, “unified_fine”

  • custom_path – Optional explicit path to YAML file (overrides search)

Returns:

  • schema_version: str

  • standard: str (e.g., “ISO 262”)

  • thread_series: str

  • tolerance_classes: dict of class definitions

  • sizes: dict of size data

  • _source_path: str (path catalog was loaded from)

Return type:

Parsed catalog dictionary containing

Raises:
Search order (unless custom_path specified):

  1. $YAPCAD_FASTENER_DATA directories

  2. ~/.config/yapcad/fasteners/

  3. Bundled data

Module contents

Fastener generation with catalog-based dimensions.

This package provides parametric fastener generation (hex bolts, hex nuts) with dimensions from YAML catalog files. Bundled catalogs cover common metric (ISO) and unified (ASME) sizes; users can extend with custom catalogs.

Quick Start:
>>> from yapcad.fasteners import metric_hex_bolt, metric_hex_nut
>>> bolt = metric_hex_bolt("M8", 25.0)
>>> nut = metric_hex_nut("M8")
Available Functions:
Metric (ISO):

metric_hex_bolt(size, length, tolerance_class=”6g”) metric_hex_nut(size, tolerance_class=”6H”)

Unified (ASME):

unified_hex_bolt(size, length, tolerance_class=”2A”) unified_hex_nut(size, tolerance_class=”2B”)

Catalog Customization:

Set YAPCAD_FASTENER_DATA environment variable to add custom catalog directories. These are searched before bundled data.

Example:

export YAPCAD_FASTENER_DATA=”/path/to/my/fasteners”

See docs/fastener_catalog_schema.md for YAML format specification.

class yapcad.fasteners.HexCapScrewSpec(diameter: float, thread_length: float, shank_length: float, head_height: float, head_flat_diameter: float, washer_thickness: float = 0.5, washer_diameter: float | None = None, shank_diameter: float | None = None, starts: int = 1, thread_arc_samples: int = 180, thread_samples_per_pitch: int = 6)[source]

Bases: object

Dimensions (all millimeters) for build_hex_cap_screw().

diameter: float
head_flat_diameter: float
head_height: float
shank_diameter: float | None = None
shank_length: float
starts: int = 1
thread_arc_samples: int = 180
thread_length: float
thread_samples_per_pitch: int = 6
washer_diameter: float | None = None
washer_thickness: float = 0.5
class yapcad.fasteners.HexNutSpec(diameter: 'float', pitch: 'float', width_flat: 'float', thickness: 'float', handedness: 'str' = 'right', starts: 'int' = 1, thread_arc_samples: 'int' = 180, thread_samples_per_pitch: 'int' = 6)[source]

Bases: object

diameter: float
handedness: str = 'right'
pitch: float
starts: int = 1
thickness: float
thread_arc_samples: int = 180
thread_samples_per_pitch: int = 6
width_flat: float
yapcad.fasteners.build_hex_cap_screw(profile: ThreadProfile, spec: HexCapScrewSpec)[source]

Create a watertight solid representing a hex cap screw.

Parameters:

  • profile – External thread profile describing nominal diameter/pitch.

  • spec – Geometry parameters (all millimeters).

yapcad.fasteners.build_hex_nut(profile: ThreadProfile, spec: HexNutSpec)[source]
yapcad.fasteners.clear_cache() → None[source]

Clear all cached catalog data.

Call this if you modify external catalog files and want to reload.

yapcad.fasteners.get_bolt_data(thread_series: str, size: str, tolerance_class: str = '6g', custom_path: Path | None = None) → Dict[str, Any][source]

Get complete data for creating a hex bolt.

Parameters:

  • thread_series – Thread series name

  • size – Size designation

  • tolerance_class – Thread tolerance class (default “6g” for metric)

  • custom_path – Optional custom catalog path

Returns:

  • thread: dict with diameter, pitch, tolerances

  • head: dict with width_across_flats, height, etc.

Return type:

Dict with all data needed to create a bolt

Raises:

KeyError – If size not found or no bolt data available

yapcad.fasteners.get_nut_data(thread_series: str, size: str, tolerance_class: str = '6H', custom_path: Path | None = None) → Dict[str, Any][source]

Get complete data for creating a hex nut.

Parameters:

  • thread_series – Thread series name

  • size – Size designation

  • tolerance_class – Thread tolerance class (default “6H” for metric internal)

  • custom_path – Optional custom catalog path

Returns:

  • thread: dict with diameter, pitch, tolerances

  • body: dict with width_across_flats, thickness, etc.

Return type:

Dict with all data needed to create a nut

Raises:

KeyError – If size not found or no nut data available

yapcad.fasteners.get_thread_data(thread_series: str, size: str, tolerance_class: str | None = None, custom_path: Path | None = None) → Dict[str, Any][source]

Get thread dimension data for a specific size.

Parameters:

  • thread_series – Thread series name

  • size – Size designation (e.g., “M8”, “1/4-20”)

  • tolerance_class – Optional tolerance class to validate exists

  • custom_path – Optional custom catalog path

Returns:

  • nominal_diameter: float (mm)

  • pitch: float (mm)

  • basic_minor_diameter: float (mm)

  • basic_pitch_diameter: float (mm)

  • tolerances: dict of tolerance class data

  • hex_bolt: dict of bolt head dimensions (if present)

  • hex_nut: dict of nut dimensions (if present)

Return type:

Dict with thread dimensions

Raises:

KeyError – If size or tolerance_class not found

yapcad.fasteners.list_available_sizes(thread_series: str, custom_path: Path | None = None) → List[str][source]

List all available sizes for a thread series.

Parameters:

  • thread_series – Thread series name

  • custom_path – Optional custom catalog path

Returns:

List of size strings (e.g., [“M3”, “M4”, “M5”, …])

yapcad.fasteners.list_tolerance_classes(thread_series: str, custom_path: Path | None = None) → List[str][source]

List available tolerance classes for a thread series.

Parameters:

  • thread_series – Thread series name

  • custom_path – Optional custom catalog path

Returns:

List of tolerance class strings (e.g., [“6g”, “6H”, “4g6g”])

yapcad.fasteners.load_catalog(thread_series: str, custom_path: Path | None = None) → Dict[str, Any][source]

Load fastener catalog for a thread series.

Parameters:

  • thread_series – One of “metric_coarse”, “metric_fine”, “unified_coarse”, “unified_fine”

  • custom_path – Optional explicit path to YAML file (overrides search)

Returns:

  • schema_version: str

  • standard: str (e.g., “ISO 262”)

  • thread_series: str

  • tolerance_classes: dict of class definitions

  • sizes: dict of size data

  • _source_path: str (path catalog was loaded from)

Return type:

Parsed catalog dictionary containing

Raises:
Search order (unless custom_path specified):

  1. $YAPCAD_FASTENER_DATA directories

  2. ~/.config/yapcad/fasteners/

  3. Bundled data

yapcad.fasteners.metric_hex_bolt(size: str, length: float, *, tolerance_class: str = '6g', thread_length: float | None = None, starts: int = 1, thread_arc_samples: int = 180, thread_samples_per_pitch: int = 6, catalog_path: Path | None = None)[source]

Create a metric hex bolt per ISO 4014/4017.

Parameters:

  • size – Thread size designation (e.g., “M8”, “M10”, “M12”)

  • length – Total shank length in mm

  • tolerance_class – Thread tolerance class (default “6g”) Common classes: “6g” (general), “4g6g” (close), “8g” (coarse)

  • thread_length – Override automatic thread length calculation (mm)

  • starts – Number of thread starts (default 1)

  • thread_arc_samples – Angular resolution for thread generation

  • thread_samples_per_pitch – Samples per pitch for thread profile

  • catalog_path – Optional path to custom catalog YAML file

Returns:

yapCAD solid representing the hex bolt

Raises:

KeyError – If size or tolerance_class not found in catalog

Examples

>>> bolt = metric_hex_bolt("M8", 25.0)
>>> bolt = metric_hex_bolt("M10", 40.0, tolerance_class="4g6g")
>>> bolt = metric_hex_bolt("M6", 20.0, thread_length=15.0)
yapcad.fasteners.metric_hex_cap_catalog()[source]
yapcad.fasteners.metric_hex_cap_screw(size: str, length: float, *, thread_length: float | None = None, starts: int = 1, thread_arc_samples: int = 180, thread_samples_per_pitch: int = 6)[source]

Return a hex screw for a metric size (e.g. 'M8').

yapcad.fasteners.metric_hex_nut(size: str, *, tolerance_class: str = '6H', handedness: str = 'right', starts: int = 1, thread_arc_samples: int = 180, thread_samples_per_pitch: int = 6, catalog_path: Path | None = None)[source]

Create a metric hex nut per ISO 4032.

Parameters:

  • size – Thread size designation (e.g., “M8”, “M10”)

  • tolerance_class – Thread tolerance class (default “6H” for internal) Common classes: “6H” (general), “5H” (close), “7H” (coarse)

  • handedness – “right” or “left” hand thread

  • starts – Number of thread starts (default 1)

  • thread_arc_samples – Angular resolution for thread generation

  • thread_samples_per_pitch – Samples per pitch for thread profile

  • catalog_path – Optional path to custom catalog YAML file

Returns:

yapCAD solid representing the hex nut

Raises:

KeyError – If size or tolerance_class not found in catalog

Examples

>>> nut = metric_hex_nut("M8")
>>> nut = metric_hex_nut("M10", tolerance_class="5H")
yapcad.fasteners.metric_hex_nut_catalog()[source]
yapcad.fasteners.unified_hex_bolt(size: str, length: float, *, tolerance_class: str = '2A', thread_length: float | None = None, starts: int = 1, thread_arc_samples: int = 180, thread_samples_per_pitch: int = 6, catalog_path: Path | None = None)[source]

Create a unified (UNC/UNF) hex bolt per ASME B18.2.1.

Parameters:

  • size – Thread size designation (e.g., “1/4-20”, “#10-24”, “1/2-13”)

  • length – Total shank length in inches (will be converted to mm internally)

  • tolerance_class – Thread class (default “2A”) Classes: “1A” (loose), “2A” (general), “3A” (close)

  • thread_length – Override automatic thread length in inches

  • starts – Number of thread starts (default 1)

  • thread_arc_samples – Angular resolution for thread generation

  • thread_samples_per_pitch – Samples per pitch for thread profile

  • catalog_path – Optional path to custom catalog YAML file

Returns:

yapCAD solid representing the hex bolt

Raises:

KeyError – If size or tolerance_class not found in catalog

Examples

>>> bolt = unified_hex_bolt("1/4-20", 1.0)  # 1 inch long
>>> bolt = unified_hex_bolt("1/2-13", 2.0, tolerance_class="3A")
yapcad.fasteners.unified_hex_cap_catalog()[source]
yapcad.fasteners.unified_hex_cap_screw(size: str, length_in: float, *, thread_length_in: float | None = None, starts: int = 1, thread_arc_samples: int = 180, thread_samples_per_pitch: int = 6)[source]

Return a hex screw for a UNC/UNF imperial size (e.g. '1/4-20').

yapcad.fasteners.unified_hex_nut(size: str, *, tolerance_class: str = '2B', handedness: str = 'right', starts: int = 1, thread_arc_samples: int = 180, thread_samples_per_pitch: int = 6, catalog_path: Path | None = None)[source]

Create a unified (UNC/UNF) hex nut per ASME B18.2.2.

Parameters:

  • size – Thread size designation (e.g., “1/4-20”, “#10-24”, “1/2-13”)

  • tolerance_class – Thread class (default “2B” for internal) Classes: “1B” (loose), “2B” (general), “3B” (close)

  • handedness – “right” or “left” hand thread

  • starts – Number of thread starts (default 1)

  • thread_arc_samples – Angular resolution for thread generation

  • thread_samples_per_pitch – Samples per pitch for thread profile

  • catalog_path – Optional path to custom catalog YAML file

Returns:

yapCAD solid representing the hex nut

Raises:

KeyError – If size or tolerance_class not found in catalog

Examples

>>> nut = unified_hex_nut("1/4-20")
>>> nut = unified_hex_nut("1/2-13", tolerance_class="3B")
yapcad.fasteners.unified_hex_nut_catalog()[source]