yapcad.dsl.runtime package
Submodules
yapcad.dsl.runtime.builtins module
Built-in function registry for DSL interpreter.
Maps DSL function names to yapCAD implementations.
- TODO: Add missing 2D curve primitives:
ellipse(center, major, minor, rotation?) -> ellipse
parabola(vertex, focus) -> parabola
hyperbola(center, a, b) -> hyperbola
Types are defined in types.py but constructors not yet implemented. See yapCAD core: yapcad.geom.Ellipse, yapcad.geom.conic_arc
- TODO: Move involute_gear to yapcad.stdlib.gears package
High-level parametric constructions (gears, fasteners) should be DSL modules in a standard library, not hardcoded builtins. This allows: - Multiple implementations (figgear vs other algorithms) - User customization and extension - Proper namespace management (use gears.involute)
- TODO: Add fastener primitives via yapcad.stdlib.fasteners package
hex_bolt(standard, size, length) using existing fastener catalog
hex_nut(standard, size)
washer(standard, size)
threaded_hole(standard, size, depth, tapped?)
See: yapcad.contrib.fasteners for existing implementation
- class yapcad.dsl.runtime.builtins.BuiltinFunction(name: str, signature: FunctionSignature, implementation: Callable[[...], Value], doc: str = '')[source]
Bases:
objectA built-in function with its implementation and type signature.
- signature: FunctionSignature
- class yapcad.dsl.runtime.builtins.BuiltinRegistry[source]
Bases:
objectRegistry of all built-in functions.
Functions are registered by name and can be looked up for execution.
- get_function(name: str) BuiltinFunction | None[source]
Look up a function by name.
- get_method(type_name: str, method_name: str) BuiltinFunction | None[source]
Look up a method by type and method name.
- register(func: BuiltinFunction) None[source]
Register a function.
- register_method(type_name: str, func: BuiltinFunction) None[source]
Register a method for a specific type.
- yapcad.dsl.runtime.builtins.call_builtin(name: str, args: List[Value]) Value[source]
Call a built-in function by name.
Raises RuntimeError if function not found.
- yapcad.dsl.runtime.builtins.call_method(type_name: str, method_name: str, receiver: Value, args: List[Value]) Value[source]
Call a method on a value.
Raises RuntimeError if method not found.
- yapcad.dsl.runtime.builtins.get_builtin_registry() BuiltinRegistry[source]
Get the global built-in function registry.
yapcad.dsl.runtime.context module
Execution context for DSL interpreter.
Manages variable scopes, tracks execution state, and collects errors/warnings.
- class yapcad.dsl.runtime.context.ExecutionContext(current_scope: ~yapcad.dsl.runtime.context.Scope = <factory>, module_name: str = '', command_name: str = '', parameters: ~typing.Dict[str, ~typing.Any] = <factory>, emit_result: ~yapcad.dsl.runtime.values.EmitResult | None = None, require_failures: ~typing.List[~yapcad.dsl.runtime.values.RequireFailure] = <factory>, diagnostics: ~yapcad.dsl.errors.DiagnosticCollector = <factory>, source_lines: ~typing.List[str] = <factory>, _should_return: bool = False, _return_value: ~yapcad.dsl.runtime.values.Value | None = None)[source]
Bases:
objectThe full execution context for interpreting DSL code.
Tracks: - Variable scopes - Require failures - Emit result - Diagnostics (errors/warnings) - Module/command being executed
- add_error(message: str, span: SourceSpan) None[source]
Add an error diagnostic.
- add_require_failure(message: str, expression_text: str = None) None[source]
Record a require constraint failure.
- add_warning(message: str, span: SourceSpan) None[source]
Add a warning diagnostic.
- diagnostics: DiagnosticCollector
- emit_result: EmitResult | None = None
- new_scope(name: str = 'block')[source]
Context manager to create a new nested scope.
- Usage:
- with ctx.new_scope(“for-loop”):
# variables defined here are local to this scope ctx.set_variable(“i”, int_val(0))
- require_failures: List[RequireFailure]
- class yapcad.dsl.runtime.context.Scope(variables: ~typing.Dict[str, ~yapcad.dsl.runtime.values.Value] = <factory>, parent: ~yapcad.dsl.runtime.context.Scope | None = None, name: str = 'anonymous')[source]
Bases:
objectA single scope containing variable bindings.
Scopes form a chain via the parent field for lexical scoping.
- set(name: str, value: Value) None[source]
Set a variable in this scope (shadowing parent if exists).
- yapcad.dsl.runtime.context.create_context(module_name: str, command_name: str, parameters: Dict[str, Value], source: str = '') ExecutionContext[source]
Create a new execution context for a command invocation.
- Parameters:
module_name – The module being executed
command_name – The command being executed
parameters – Parameter values passed to the command
source – The source code (for error messages)
- Returns:
A fresh ExecutionContext with parameters bound in scope
yapcad.dsl.runtime.interpreter module
Tree-walking interpreter for DSL execution.
Evaluates AST nodes to produce geometry and other values.
- class yapcad.dsl.runtime.interpreter.ExecutionResult(success: bool, emit_result: ~yapcad.dsl.runtime.values.EmitResult | None = None, require_failures: ~typing.List[~yapcad.dsl.runtime.values.RequireFailure] = <factory>, provenance: ~yapcad.dsl.runtime.provenance.Provenance | None = None, error_message: str | None = None)[source]
Bases:
objectResult of executing a command.
- emit_result: EmitResult | None = None
- provenance: Provenance | None = None
- require_failures: List[RequireFailure]
- class yapcad.dsl.runtime.interpreter.Interpreter(transforms: List[Callable[[Module], Module]] = None)[source]
Bases:
objectTree-walking interpreter for DSL execution.
Evaluates AST nodes by dispatching to type-specific methods.
- execute(module: Module, command_name: str, parameters: Dict[str, Any], source: str = '') ExecutionResult[source]
Execute a command from a module.
- Parameters:
module – The parsed and type-checked module
command_name – Name of the command to execute
parameters – Parameter values (raw Python values, not wrapped)
source – Original source code for error messages
- Returns:
ExecutionResult with geometry and provenance
- yapcad.dsl.runtime.interpreter.compile_and_run(source: str, command_name: str, parameters: Dict[str, Any]) ExecutionResult[source]
High-level API to compile and run DSL source code in one call.
This is the simplest way to execute DSL code:
from yapcad.dsl import compile_and_run
- result = compile_and_run(‘’’
module my_design; command MAKE_BOX(w: float, h: float, d: float) -> solid {
emit box(w, h, d);
}
‘’’, “MAKE_BOX”, {“w”: 10.0, “h”: 20.0, “d”: 5.0})
- if result.success:
geometry = result.geometry
- else:
print(f”Error: {result.error_message}”)
- Parameters:
source – DSL source code as a string
command_name – Name of the command to execute
parameters – Parameter values (raw Python values)
- Returns:
ExecutionResult with geometry, provenance, and any errors
yapcad.dsl.runtime.provenance module
Provenance tracking for DSL execution.
Captures invocation metadata for audit trails and reproducibility.
- class yapcad.dsl.runtime.provenance.Provenance(module_name: str, command_name: str, version: str = '0.0.0', parameters: ~typing.Dict[str, ~typing.Any] = <factory>, source_signature: str = '', timestamp: str = <factory>, extra: ~typing.Dict[str, ~typing.Any] = <factory>)[source]
Bases:
objectProvenance information for a DSL command execution.
This metadata is attached to emitted geometry to enable: - Reproducibility: Re-run with same parameters - Audit trail: Track what generated each piece of geometry - Version control: Detect if source changed
- yapcad.dsl.runtime.provenance.compute_source_signature(source: str) str[source]
Compute a signature for source code.
Uses SHA-256 hash of the normalized source.
- yapcad.dsl.runtime.provenance.create_provenance(module_name: str, command_name: str, parameters: Dict[str, Any], source: str = '', version: str = '0.0.0', **extra: Any) Provenance[source]
Create a Provenance record for a command execution.
- Parameters:
module_name – Name of the DSL module
command_name – Name of the command being executed
parameters – Parameter values passed to the command
source – Original source code (for signature)
version – Version of the module
**extra – Additional metadata to include
- Returns:
A Provenance record
yapcad.dsl.runtime.values module
Runtime value wrappers for DSL interpreter.
Values wrap Python/yapCAD objects with DSL type metadata for runtime type checking and provenance tracking.
- class yapcad.dsl.runtime.values.EmitResult(value: ~yapcad.dsl.runtime.values.Value, metadata: ~typing.Dict[str, ~typing.Any] = <factory>)[source]
Bases:
objectResult of an emit statement - the final output of a command.
Contains the emitted geometry plus any metadata attached via with {…}.
- class yapcad.dsl.runtime.values.RequireFailure(message: str, expression_text: str | None = None)[source]
Bases:
objectRepresents a failed require constraint.
Used to collect all require failures during execution rather than stopping at the first one.
- class yapcad.dsl.runtime.values.Value(data: Any, type: Type)[source]
Bases:
objectA runtime value with DSL type information.
The data field holds the actual Python/yapCAD object. The type field holds the DSL type for runtime validation.
- yapcad.dsl.runtime.values.check_type(value: Value, expected: Type) bool[source]
Check if a value’s type is assignable to expected type.
- yapcad.dsl.runtime.values.coerce_numeric(value: Value) Value[source]
Coerce int to float if needed.
- yapcad.dsl.runtime.values.list_val(items: List[Value], element_type: Type) Value[source]
Create a list value from a list of Values.
- yapcad.dsl.runtime.values.none_val(inner_type: Type) Value[source]
Create a None value for an optional type.
- yapcad.dsl.runtime.values.path3d_val(path_data: Any) Value[source]
Create a path3d value (3D curve/spine for sweeps).
- yapcad.dsl.runtime.values.point_val(coords: Any, is_2d: bool = False) Value[source]
Create a point value (2D or 3D).
- yapcad.dsl.runtime.values.unwrap_value(v: Value) Any[source]
Extract the raw Python/yapCAD data from a Value.
- yapcad.dsl.runtime.values.unwrap_values(values: List[Value]) List[Any][source]
Extract raw data from a list of Values.
Module contents
DSL Runtime - Tree-walking interpreter for DSL execution.
This module provides: - Interpreter: Executes DSL commands to generate geometry - Value: Runtime value wrappers with type metadata - ExecutionContext: Variable scope management - Provenance: Invocation metadata for audit trails - BuiltinRegistry: Built-in function implementations
- class yapcad.dsl.runtime.BuiltinFunction(name: str, signature: FunctionSignature, implementation: Callable[[...], Value], doc: str = '')[source]
Bases:
objectA built-in function with its implementation and type signature.
- signature: FunctionSignature
- class yapcad.dsl.runtime.BuiltinRegistry[source]
Bases:
objectRegistry of all built-in functions.
Functions are registered by name and can be looked up for execution.
- get_function(name: str) BuiltinFunction | None[source]
Look up a function by name.
- get_method(type_name: str, method_name: str) BuiltinFunction | None[source]
Look up a method by type and method name.
- register(func: BuiltinFunction) None[source]
Register a function.
- register_method(type_name: str, func: BuiltinFunction) None[source]
Register a method for a specific type.
- class yapcad.dsl.runtime.EmitResult(value: ~yapcad.dsl.runtime.values.Value, metadata: ~typing.Dict[str, ~typing.Any] = <factory>)[source]
Bases:
objectResult of an emit statement - the final output of a command.
Contains the emitted geometry plus any metadata attached via with {…}.
- class yapcad.dsl.runtime.ExecutionContext(current_scope: ~yapcad.dsl.runtime.context.Scope = <factory>, module_name: str = '', command_name: str = '', parameters: ~typing.Dict[str, ~typing.Any] = <factory>, emit_result: ~yapcad.dsl.runtime.values.EmitResult | None = None, require_failures: ~typing.List[~yapcad.dsl.runtime.values.RequireFailure] = <factory>, diagnostics: ~yapcad.dsl.errors.DiagnosticCollector = <factory>, source_lines: ~typing.List[str] = <factory>, _should_return: bool = False, _return_value: ~yapcad.dsl.runtime.values.Value | None = None)[source]
Bases:
objectThe full execution context for interpreting DSL code.
Tracks: - Variable scopes - Require failures - Emit result - Diagnostics (errors/warnings) - Module/command being executed
- add_error(message: str, span: SourceSpan) None[source]
Add an error diagnostic.
- add_require_failure(message: str, expression_text: str = None) None[source]
Record a require constraint failure.
- add_warning(message: str, span: SourceSpan) None[source]
Add a warning diagnostic.
- diagnostics: DiagnosticCollector
- emit_result: EmitResult | None = None
- new_scope(name: str = 'block')[source]
Context manager to create a new nested scope.
- Usage:
- with ctx.new_scope(“for-loop”):
# variables defined here are local to this scope ctx.set_variable(“i”, int_val(0))
- require_failures: List[RequireFailure]
- class yapcad.dsl.runtime.ExecutionResult(success: bool, emit_result: ~yapcad.dsl.runtime.values.EmitResult | None = None, require_failures: ~typing.List[~yapcad.dsl.runtime.values.RequireFailure] = <factory>, provenance: ~yapcad.dsl.runtime.provenance.Provenance | None = None, error_message: str | None = None)[source]
Bases:
objectResult of executing a command.
- emit_result: EmitResult | None = None
- provenance: Provenance | None = None
- require_failures: List[RequireFailure]
- class yapcad.dsl.runtime.Interpreter(transforms: List[Callable[[Module], Module]] = None)[source]
Bases:
objectTree-walking interpreter for DSL execution.
Evaluates AST nodes by dispatching to type-specific methods.
- execute(module: Module, command_name: str, parameters: Dict[str, Any], source: str = '') ExecutionResult[source]
Execute a command from a module.
- Parameters:
module – The parsed and type-checked module
command_name – Name of the command to execute
parameters – Parameter values (raw Python values, not wrapped)
source – Original source code for error messages
- Returns:
ExecutionResult with geometry and provenance
- class yapcad.dsl.runtime.Provenance(module_name: str, command_name: str, version: str = '0.0.0', parameters: ~typing.Dict[str, ~typing.Any] = <factory>, source_signature: str = '', timestamp: str = <factory>, extra: ~typing.Dict[str, ~typing.Any] = <factory>)[source]
Bases:
objectProvenance information for a DSL command execution.
This metadata is attached to emitted geometry to enable: - Reproducibility: Re-run with same parameters - Audit trail: Track what generated each piece of geometry - Version control: Detect if source changed
- class yapcad.dsl.runtime.RequireFailure(message: str, expression_text: str | None = None)[source]
Bases:
objectRepresents a failed require constraint.
Used to collect all require failures during execution rather than stopping at the first one.
- class yapcad.dsl.runtime.Scope(variables: ~typing.Dict[str, ~yapcad.dsl.runtime.values.Value] = <factory>, parent: ~yapcad.dsl.runtime.context.Scope | None = None, name: str = 'anonymous')[source]
Bases:
objectA single scope containing variable bindings.
Scopes form a chain via the parent field for lexical scoping.
- set(name: str, value: Value) None[source]
Set a variable in this scope (shadowing parent if exists).
- class yapcad.dsl.runtime.Value(data: Any, type: Type)[source]
Bases:
objectA runtime value with DSL type information.
The data field holds the actual Python/yapCAD object. The type field holds the DSL type for runtime validation.
- yapcad.dsl.runtime.call_builtin(name: str, args: List[Value]) Value[source]
Call a built-in function by name.
Raises RuntimeError if function not found.
- yapcad.dsl.runtime.call_method(type_name: str, method_name: str, receiver: Value, args: List[Value]) Value[source]
Call a method on a value.
Raises RuntimeError if method not found.
- yapcad.dsl.runtime.check_type(value: Value, expected: Type) bool[source]
Check if a value’s type is assignable to expected type.
- yapcad.dsl.runtime.compile_and_run(source: str, command_name: str, parameters: Dict[str, Any]) ExecutionResult[source]
High-level API to compile and run DSL source code in one call.
This is the simplest way to execute DSL code:
from yapcad.dsl import compile_and_run
- result = compile_and_run(‘’’
module my_design; command MAKE_BOX(w: float, h: float, d: float) -> solid {
emit box(w, h, d);
}
‘’’, “MAKE_BOX”, {“w”: 10.0, “h”: 20.0, “d”: 5.0})
- if result.success:
geometry = result.geometry
- else:
print(f”Error: {result.error_message}”)
- Parameters:
source – DSL source code as a string
command_name – Name of the command to execute
parameters – Parameter values (raw Python values)
- Returns:
ExecutionResult with geometry, provenance, and any errors
- yapcad.dsl.runtime.compute_source_signature(source: str) str[source]
Compute a signature for source code.
Uses SHA-256 hash of the normalized source.
- yapcad.dsl.runtime.create_context(module_name: str, command_name: str, parameters: Dict[str, Value], source: str = '') ExecutionContext[source]
Create a new execution context for a command invocation.
- Parameters:
module_name – The module being executed
command_name – The command being executed
parameters – Parameter values passed to the command
source – The source code (for error messages)
- Returns:
A fresh ExecutionContext with parameters bound in scope
- yapcad.dsl.runtime.create_provenance(module_name: str, command_name: str, parameters: Dict[str, Any], source: str = '', version: str = '0.0.0', **extra: Any) Provenance[source]
Create a Provenance record for a command execution.
- Parameters:
module_name – Name of the DSL module
command_name – Name of the command being executed
parameters – Parameter values passed to the command
source – Original source code (for signature)
version – Version of the module
**extra – Additional metadata to include
- Returns:
A Provenance record
- yapcad.dsl.runtime.execute(module: Module, command_name: str, parameters: Dict[str, Any], source: str = '') ExecutionResult[source]
Execute a command from a module.
This is a convenience wrapper around Interpreter.execute().
- yapcad.dsl.runtime.get_builtin_registry() BuiltinRegistry[source]
Get the global built-in function registry.
- yapcad.dsl.runtime.list_val(items: List[Value], element_type: Type) Value[source]
Create a list value from a list of Values.
- yapcad.dsl.runtime.none_val(inner_type: Type) Value[source]
Create a None value for an optional type.
- yapcad.dsl.runtime.point_val(coords: Any, is_2d: bool = False) Value[source]
Create a point value (2D or 3D).
- yapcad.dsl.runtime.unwrap_value(v: Value) Any[source]
Extract the raw Python/yapCAD data from a Value.
- yapcad.dsl.runtime.unwrap_values(values: List[Value]) List[Any][source]
Extract raw data from a list of Values.
- yapcad.dsl.runtime.vector_val(coords: Any, is_2d: bool = False) Value[source]
Create a vector value (2D or 3D).