catalog: product, assembly and std operations say what every parameter is

The product operators keep taking py::object (they check the type inside the operation), now as
Typed<Name> (typed_args.hpp), which accepts anything as before and prints the type in the signature:
Part, Assembly, Part | Assembly, Placement, ConnectorRef, ScalarLimit | None, str ids, Length
radii (phase_offset is a pitch-circle arc length), Angle drive angles, Point3 / Direction3 frames,
dict[str, Direction3] explode directions. The std factories wrap their double / int arguments as
Shown<T, Name> (converted exactly as T) to read Length, Angle, Count; fastener styles are Literal.
apply_tag_rselection (ShapeSelector | Sequence[AnyShape], Literal enums), load_brep_region (str |
os.PathLike), render_screenshot_rpath and the Python make_ball_bearing_rassembly are annotated with
simplecadapi.types.

catalog.classify: split unions before matching Literal/Sequence (a Literal-first union gave garbage
choices); new kinds path, scalar_limit, <kind>_map, joined union kinds (enum|numbers, query|shape);
str-enum defaults read as their value. SDK_DEFECTS 21-24.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
NiJingzhe
2026-11-04 04:58:19 +08:00
parent c6149f483d
commit cbebe6f74a
9 changed files with 429 additions and 113 deletions
+108 -44
View File
@@ -4,8 +4,10 @@
//
// Every operator takes py::object for the arguments whose type Python checks inside its wrapped
// body, and converts them inside guard_operation, so a wrong type is the operation's
// SimpleCADError exactly as in Python (see bind_product_args.hpp).
// SimpleCADError exactly as in Python (see bind_product_args.hpp). The py::object arrives as a
// `Typed<Name>` (typed_args.hpp), so the signature still says what each argument is.
#include "bind_product_args.hpp"
#include "typed_args.hpp"
#include "scad/reactive/registry.hpp"
@@ -15,6 +17,71 @@ using namespace scad;
using namespace scad::product_binding;
using sp::guard_operation;
// What each argument is, for the signature; the bodies still receive the py::object and check it themselves.
namespace names {
using py::detail::const_name;
using scad::pybind::kOr;
using scad::pybind::kOrNone;
using scad::pybind::type_name;
SCAD_SIGNATURE_NAME(Text, const_name("str"));
SCAD_SIGNATURE_NAME(TextOrNone, const_name("str | None"));
SCAD_SIGNATURE_NAME(Number, const_name("float | Expr"));
SCAD_SIGNATURE_NAME(NumberOrNone, const_name("float | Expr | None"));
SCAD_SIGNATURE_NAME(Bool, const_name("bool"));
SCAD_SIGNATURE_NAME(Color, const_name("collections.abc.Sequence[float] | None"));
SCAD_SIGNATURE_NAME(Length, scad::pybind::LengthTag::name);
SCAD_SIGNATURE_NAME(LengthOrNone, scad::pybind::LengthTag::name + kOrNone);
SCAD_SIGNATURE_NAME(AngleOrNone, scad::pybind::AngleTag::name + kOrNone);
SCAD_SIGNATURE_NAME(Point, scad::pybind::PointTag::name);
SCAD_SIGNATURE_NAME(PointOrNone, scad::pybind::PointTag::name + kOrNone);
SCAD_SIGNATURE_NAME(Direction, scad::pybind::DirectionTag::name);
SCAD_SIGNATURE_NAME(DirectionOrNone, scad::pybind::DirectionTag::name + kOrNone);
SCAD_SIGNATURE_NAME(Directions, const_name("dict[str, ") + scad::pybind::DirectionTag::name + const_name("] | None"));
SCAD_SIGNATURE_NAME(Weights, const_name("dict[str, float | Expr] | None"));
SCAD_SIGNATURE_NAME(Solid, type_name<scad::Solid>());
SCAD_SIGNATURE_NAME(Face, type_name<scad::Face>());
SCAD_SIGNATURE_NAME(Edge, type_name<scad::Edge>());
SCAD_SIGNATURE_NAME(Vertex, type_name<scad::Vertex>());
SCAD_SIGNATURE_NAME(Part, type_name<sp::Part>());
SCAD_SIGNATURE_NAME(Assembly, type_name<sp::Assembly>());
SCAD_SIGNATURE_NAME(Item, type_name<sp::Part>() + kOr + type_name<sp::Assembly>());
SCAD_SIGNATURE_NAME(Placement, type_name<sp::Placement>());
SCAD_SIGNATURE_NAME(Material, type_name<sp::Material>());
SCAD_SIGNATURE_NAME(Connector, type_name<sp::Connector>());
SCAD_SIGNATURE_NAME(Ref, type_name<sp::ConnectorRef>());
SCAD_SIGNATURE_NAME(Limit, type_name<sp::ScalarLimit>() + kOrNone);
} // namespace names
using scad::pybind::Typed;
using TextArg = Typed<names::Text>;
using NameArg = Typed<names::TextOrNone>; // anything str() takes: a display name
using TextOrNoneArg = Typed<names::TextOrNone>;
using NumberArg = Typed<names::Number>;
using NumberOrNoneArg = Typed<names::NumberOrNone>;
using BoolArg = Typed<names::Bool>; // any object, read by its truth value
using ColorArg = Typed<names::Color>;
using LengthArg = Typed<names::Length>;
using LengthOrNoneArg = Typed<names::LengthOrNone>;
using AngleOrNoneArg = Typed<names::AngleOrNone>;
using PointArg = Typed<names::Point>;
using PointOrNoneArg = Typed<names::PointOrNone>;
using DirectionArg = Typed<names::Direction>;
using DirectionOrNoneArg = Typed<names::DirectionOrNone>;
using DirectionsArg = Typed<names::Directions>;
using WeightsArg = Typed<names::Weights>;
using SolidArg = Typed<names::Solid>;
using FaceArg = Typed<names::Face>;
using EdgeArg = Typed<names::Edge>;
using VertexArg = Typed<names::Vertex>;
using PartArg = Typed<names::Part>;
using AssemblyArg = Typed<names::Assembly>;
using ItemArg = Typed<names::Item>;
using PlacementArg = Typed<names::Placement>;
using MaterialArg = Typed<names::Material>;
using ConnectorArg = Typed<names::Connector>;
using RefArg = Typed<names::Ref>;
using LimitArg = Typed<names::Limit>;
const sp::Assembly& assembly_arg(const py::object& value) {
return typed<sp::Assembly>(value, "assembly must be an Assembly");
}
@@ -46,8 +113,8 @@ Scalar3 point_arg(const py::object& value, const char* field) {
void bind_structure(py::module_& m) {
m.def(
"make_material_rmaterial",
[](const py::object& material_id, const py::object& name, const py::object& density,
const py::object& density_unit, const py::object& color) {
[](const TextArg& material_id, const NameArg& name, const NumberOrNoneArg& density,
const TextOrNoneArg& density_unit, const ColorArg& color) {
return guard_operation("make_material_rmaterial", [&] {
sp::OptionalString unit;
if (!density_unit.is_none())
@@ -65,7 +132,7 @@ void bind_structure(py::module_& m) {
m.def(
"make_placement_rplacement",
[](const py::object& origin, const py::object& x_axis, const py::object& y_axis) {
[](const PointArg& origin, const DirectionArg& x_axis, const DirectionArg& y_axis) {
return guard_operation("make_placement_rplacement", [&] {
return sp::make_placement_rplacement(point_arg(origin, "origin"), point_arg(x_axis, "x_axis"),
point_arg(y_axis, "y_axis"));
@@ -79,7 +146,7 @@ void bind_structure(py::module_& m) {
m.def(
"make_part_rpart",
[](const py::object& part_id, const py::object& body, const py::object& name) {
[](const TextArg& part_id, const SolidArg& body, const NameArg& name) {
return guard_operation("make_part_rpart", [&] {
return sp::make_part_rpart(text(part_id, "part_id"), typed<Solid>(body, "body must be a Solid"),
optional_name(name));
@@ -89,7 +156,7 @@ void bind_structure(py::module_& m) {
"Wrap exactly one Solid as a semantic single-body Part.");
m.def(
"assign_material_rpart",
[](const py::object& part, const py::object& material) {
[](const PartArg& part, const MaterialArg& material) {
return guard_operation("assign_material_rpart", [&] {
return sp::assign_material_rpart(part_arg(part),
typed<sp::Material>(material, "material must be a Material"));
@@ -99,7 +166,7 @@ void bind_structure(py::module_& m) {
m.def(
"make_assembly_rassembly",
[](const py::object& assembly_id, const py::object& name) {
[](const TextArg& assembly_id, const NameArg& name) {
return guard_operation("make_assembly_rassembly", [&] {
return sp::make_assembly_rassembly(text(assembly_id, "assembly_id"), optional_name(name));
});
@@ -107,8 +174,8 @@ void bind_structure(py::module_& m) {
py::arg("assembly_id"), py::arg("name") = py::none(), "Create an empty assembly product structure.");
m.def(
"add_component_rassembly",
[](const py::object& assembly, const py::object& item, const py::object& component_id,
const py::object& placement, const py::object& name) {
[](const AssemblyArg& assembly, const ItemArg& item, const TextArg& component_id, const PlacementArg& placement,
const NameArg& name) {
return guard_operation("add_component_rassembly", [&] {
const sp::Assembly& target = assembly_arg(assembly);
const sp::Item chosen = item_of(item);
@@ -120,7 +187,7 @@ void bind_structure(py::module_& m) {
"Add a placed Part or subassembly component instance to an Assembly.");
m.def(
"place_component_rassembly",
[](const py::object& assembly, const py::object& component_id, const py::object& placement) {
[](const AssemblyArg& assembly, const TextArg& component_id, const PlacementArg& placement) {
return guard_operation("place_component_rassembly", [&] {
const sp::Assembly& target = assembly_arg(assembly);
return sp::place_component_rassembly(target, text(component_id, "component_id"), placement_arg(placement));
@@ -130,8 +197,8 @@ void bind_structure(py::module_& m) {
"Move an existing assembly component by replacing its placement.");
m.def(
"explode_rassembly",
[](const py::object& assembly, const py::object& factor, const py::object& center, const py::object& axis,
const py::object& directions, const py::object& weights) {
[](const AssemblyArg& assembly, const NumberArg& factor, const PointOrNoneArg& center,
const DirectionOrNoneArg& axis, const DirectionsArg& directions, const WeightsArg& weights) {
return guard_operation("explode_rassembly", [&] {
const sp::Assembly& target = assembly_arg(assembly);
std::map<std::string, Vec3> direction_map;
@@ -162,7 +229,7 @@ void bind_structure(py::module_& m) {
void bind_connectors(py::module_& m) {
m.def(
"make_face_connector_rconnector",
[](const py::object& connector_id, const py::object& face, const py::object& name, const py::object& flip) {
[](const TextArg& connector_id, const FaceArg& face, const NameArg& name, const BoolArg& flip) {
return guard_operation("make_face_connector_rconnector", [&] {
const Face& target = typed<Face>(face, "face must be a Face");
return sp::make_face_connector_rconnector(text(connector_id, "connector_id"), target, optional_name(name),
@@ -174,7 +241,7 @@ void bind_connectors(py::module_& m) {
"Set flip=True to negate the Z axis (point it opposite to the normal).");
m.def(
"make_edge_connector_rconnector",
[](const py::object& connector_id, const py::object& edge, const py::object& name, const py::object& flip) {
[](const TextArg& connector_id, const EdgeArg& edge, const NameArg& name, const BoolArg& flip) {
return guard_operation("make_edge_connector_rconnector", [&] {
const Edge& target = typed<Edge>(edge, "edge must be an Edge");
return sp::make_edge_connector_rconnector(text(connector_id, "connector_id"), target, optional_name(name),
@@ -187,7 +254,7 @@ void bind_connectors(py::module_& m) {
"Set flip=True to negate the Z axis.");
m.def(
"make_vertex_connector_rconnector",
[](const py::object& connector_id, const py::object& vertex, const py::object& name, const py::object& flip) {
[](const TextArg& connector_id, const VertexArg& vertex, const NameArg& name, const BoolArg& flip) {
return guard_operation("make_vertex_connector_rconnector", [&] {
const Vertex& target = typed<Vertex>(vertex, "vertex must be a Vertex");
return sp::make_vertex_connector_rconnector(text(connector_id, "connector_id"), target, optional_name(name),
@@ -199,7 +266,7 @@ void bind_connectors(py::module_& m) {
"flip has no effect on vertex connectors (no direction).");
m.def(
"make_placement_connector_rconnector",
[](const py::object& connector_id, const py::object& placement, const py::object& name) {
[](const TextArg& connector_id, const PlacementArg& placement, const NameArg& name) {
return guard_operation("make_placement_connector_rconnector", [&] {
const sp::Placement& frame = placement_arg(placement);
return sp::make_placement_connector_rconnector(text(connector_id, "connector_id"), frame,
@@ -210,7 +277,7 @@ void bind_connectors(py::module_& m) {
"Create a connector anchored to an explicit local placement frame.");
m.def(
"add_connector_rpart",
[](const py::object& part, const py::object& connector) {
[](const PartArg& part, const ConnectorArg& connector) {
return guard_operation("add_connector_rpart", [&] {
const sp::Part& target = part_arg(part);
return sp::add_connector_rpart(target, typed<sp::Connector>(connector, "connector must be a Connector"));
@@ -219,8 +286,8 @@ void bind_connectors(py::module_& m) {
py::arg("part"), py::arg("connector"), "Attach a connector datum frame to a Part definition.");
m.def(
"set_public_connector_rassembly",
[](const py::object& assembly, const py::object& public_id, const py::object& component_id,
const py::object& connector_id, const py::object& name) {
[](const AssemblyArg& assembly, const TextArg& public_id, const TextArg& component_id,
const TextArg& connector_id, const NameArg& name) {
return guard_operation("set_public_connector_rassembly", [&] {
const sp::Assembly& target = assembly_arg(assembly);
return sp::set_public_connector_rassembly(target, text(public_id, "public_connector_id"),
@@ -233,7 +300,7 @@ void bind_connectors(py::module_& m) {
"Expose an existing connector on a direct child component.");
m.def(
"make_connector_ref_rconnectorref",
[](const py::object& component_id, const py::object& connector_id) {
[](const TextArg& component_id, const TextArg& connector_id) {
return guard_operation("make_connector_ref_rconnectorref", [&] {
return sp::make_connector_ref_rconnectorref(text(component_id, "component_id"),
text(connector_id, "connector_id"));
@@ -242,7 +309,7 @@ void bind_connectors(py::module_& m) {
py::arg("component_id"), py::arg("connector_id"), "Reference a connector through a component instance.");
m.def(
"make_scalar_limit_rscalarlimit",
[](const py::object& lower_value, const py::object& upper_value) {
[](const NumberArg& lower_value, const NumberArg& upper_value) {
return guard_operation("make_scalar_limit_rscalarlimit", [&] {
return sp::make_scalar_limit_rscalarlimit(scalar(lower_value, "lower_value"),
scalar(upper_value, "upper_value"));
@@ -257,7 +324,7 @@ void bind_connectors(py::module_& m) {
void bind_constraints(py::module_& m) {
m.def(
"ground_component_rassembly",
[](const py::object& assembly, const py::object& component_id) {
[](const AssemblyArg& assembly, const TextArg& component_id) {
return guard_operation("ground_component_rassembly", [&] {
const sp::Assembly& target = assembly_arg(assembly);
return sp::ground_component_rassembly(target, text(component_id, "component_id"));
@@ -266,7 +333,7 @@ void bind_constraints(py::module_& m) {
py::arg("assembly"), py::arg("component_id"), "Ground a component at its current authored placement.");
m.def(
"unground_component_rassembly",
[](const py::object& assembly, const py::object& component_id) {
[](const AssemblyArg& assembly, const TextArg& component_id) {
return guard_operation("unground_component_rassembly", [&] {
const sp::Assembly& target = assembly_arg(assembly);
return sp::unground_component_rassembly(target, text(component_id, "component_id"));
@@ -285,8 +352,8 @@ void bind_constraints(py::module_& m) {
m.def(
"add_fixed_constraint_rassembly",
[ref](const py::object& assembly, const py::object& constraint_id, const py::object& a, const py::object& b,
const py::object& name) {
[ref](const AssemblyArg& assembly, const TextArg& constraint_id, const RefArg& a, const RefArg& b,
const NameArg& name) {
return sp::add_fixed_constraint_rassembly(constraint_assembly("add_fixed_constraint_rassembly", assembly),
text(constraint_id, "constraint_id"), ref(a, "connector_a"),
ref(b, "connector_b"), optional_name(name));
@@ -295,9 +362,8 @@ void bind_constraints(py::module_& m) {
py::arg("name") = py::none(), "Constrain two component connectors to the same frame.");
m.def(
"add_revolute_constraint_rassembly",
[ref, limit](const py::object& assembly, const py::object& constraint_id, const py::object& a,
const py::object& b, const py::object& drive_angle_degrees, const py::object& angle_limit,
const py::object& name) {
[ref, limit](const AssemblyArg& assembly, const TextArg& constraint_id, const RefArg& a, const RefArg& b,
const AngleOrNoneArg& drive_angle_degrees, const LimitArg& angle_limit, const NameArg& name) {
return sp::add_revolute_constraint_rassembly(
constraint_assembly("add_revolute_constraint_rassembly", assembly), text(constraint_id, "constraint_id"),
ref(a, "connector_a"), ref(b, "connector_b"), optional_scalar(drive_angle_degrees, "drive_angle_degrees"),
@@ -308,9 +374,8 @@ void bind_constraints(py::module_& m) {
"Constrain two connectors as a revolute axis pair.");
m.def(
"add_prismatic_constraint_rassembly",
[ref, limit](const py::object& assembly, const py::object& constraint_id, const py::object& a,
const py::object& b, const py::object& drive_distance, const py::object& distance_limit,
const py::object& name) {
[ref, limit](const AssemblyArg& assembly, const TextArg& constraint_id, const RefArg& a, const RefArg& b,
const LengthOrNoneArg& drive_distance, const LimitArg& distance_limit, const NameArg& name) {
return sp::add_prismatic_constraint_rassembly(
constraint_assembly("add_prismatic_constraint_rassembly", assembly), text(constraint_id, "constraint_id"),
ref(a, "connector_a"), ref(b, "connector_b"), optional_scalar(drive_distance, "drive_distance"),
@@ -321,9 +386,9 @@ void bind_constraints(py::module_& m) {
"Constrain two connectors as a prismatic slider pair.");
m.def(
"add_gear_constraint_rassembly",
[ref](const py::object& assembly, const py::object& constraint_id, const py::object& a, const py::object& b,
const py::object& pitch_radius_a, const py::object& pitch_radius_b, const py::object& phase_offset,
const py::object& name) {
[ref](const AssemblyArg& assembly, const TextArg& constraint_id, const RefArg& a, const RefArg& b,
const LengthArg& pitch_radius_a, const LengthArg& pitch_radius_b, const LengthOrNoneArg& phase_offset,
const NameArg& name) {
return sp::add_gear_constraint_rassembly(constraint_assembly("add_gear_constraint_rassembly", assembly),
text(constraint_id, "constraint_id"), ref(a, "connector_a"),
ref(b, "connector_b"), scalar(pitch_radius_a, "pitch_radius_a"),
@@ -335,9 +400,9 @@ void bind_constraints(py::module_& m) {
py::arg("name") = py::none(), "Couple two revolute axes as meshing gears with inverse rotation.");
m.def(
"add_belt_constraint_rassembly",
[ref](const py::object& assembly, const py::object& constraint_id, const py::object& a, const py::object& b,
const py::object& pulley_radius_a, const py::object& pulley_radius_b, const py::object& phase_offset,
const py::object& name) {
[ref](const AssemblyArg& assembly, const TextArg& constraint_id, const RefArg& a, const RefArg& b,
const LengthArg& pulley_radius_a, const LengthArg& pulley_radius_b, const LengthOrNoneArg& phase_offset,
const NameArg& name) {
return sp::add_belt_constraint_rassembly(constraint_assembly("add_belt_constraint_rassembly", assembly),
text(constraint_id, "constraint_id"), ref(a, "connector_a"),
ref(b, "connector_b"), scalar(pulley_radius_a, "pulley_radius_a"),
@@ -349,9 +414,8 @@ void bind_constraints(py::module_& m) {
py::arg("name") = py::none(), "Couple two revolute axes as belt-linked pulleys with same-direction rotation.");
m.def(
"add_rack_pinion_constraint_rassembly",
[ref](const py::object& assembly, const py::object& constraint_id, const py::object& rack,
const py::object& pinion, const py::object& pitch_radius, const py::object& phase_offset,
const py::object& name) {
[ref](const AssemblyArg& assembly, const TextArg& constraint_id, const RefArg& rack, const RefArg& pinion,
const LengthArg& pitch_radius, const LengthOrNoneArg& phase_offset, const NameArg& name) {
return sp::add_rack_pinion_constraint_rassembly(
constraint_assembly("add_rack_pinion_constraint_rassembly", assembly), text(constraint_id, "constraint_id"),
ref(rack, "connector_a"), ref(pinion, "connector_b"), scalar(pitch_radius, "pitch_radius"),
@@ -365,7 +429,7 @@ void bind_constraints(py::module_& m) {
void bind_solving(py::module_& m) {
m.def(
"solve_assembly_constraints_rassembly",
[](const py::object& assembly, const py::object& strict) {
[](const AssemblyArg& assembly, const BoolArg& strict) {
return guard_operation("solve_assembly_constraints_rassembly", [&] {
return sp::solve_assembly_constraints_rassembly(assembly_ptr_arg(assembly), truthy(strict));
});
@@ -383,7 +447,7 @@ void bind_solving(py::module_& m) {
"``inspect_assembly_constraints_rassembly``.");
m.def(
"measure_constraint_residual_rconstraintresidual",
[](const py::object& assembly, const py::object& constraint_id) {
[](const AssemblyArg& assembly, const TextArg& constraint_id) {
return sp::measure_constraint_residual_rconstraintresidual(assembly_arg(assembly),
text(constraint_id, "constraint_id"));
},
@@ -391,13 +455,13 @@ void bind_solving(py::module_& m) {
"Measure residual for one assembly constraint without mutating the assembly.");
m.def(
"inspect_assembly_constraints_rconstraintreport",
[](const py::object& assembly) {
[](const AssemblyArg& assembly) {
return sp::inspect_assembly_constraints_rconstraintreport(assembly_arg(assembly));
},
py::arg("assembly"), "Inspect all assembly constraint residuals without mutating the assembly.");
m.def(
"make_compound_from_assembly_rcompound",
[](const py::object& assembly) {
[](const AssemblyArg& assembly) {
return guard_operation("make_compound_from_assembly_rcompound",
[&] { return sp::make_compound_from_assembly_rcompound(assembly_arg(assembly)); });
},