Could the Free Function API and the Workplane API with the same function names be designed to have consistent parameter interfaces as much as possible?

[huskier]

Could the Free Function API and the Workplane API with the same function names be designed to have consistent parameter interfaces as much as possible? Here is a table of inconsistencies between the Free Function API and the Workplane API with the same function names:

Items	Free Function API	CadQuery Workplane API
rect	def rect(w: float, h: float) -> Shape:	def rect( self: T, xLen: float, yLen: float, centered: Union[bool, Tuple[bool, bool]] = True, forConstruction: bool = False, ) -> T:
circle	def circle(r: float) -> Shape:	def circle(self: T, radius: float, forConstruction: bool = False) -> T:
ellipse	def ellipse(r1: float, r2: float) -> Shape:	def ellipse( self: T, x_radius: float, y_radius: float, rotation_angle: float = 0.0, forConstruction: bool = False, ) -> T:
box	def box(w: float, l: float, h: float) -> Shape:	def box( self: T, length: float, width: float, height: float, centered: Union[bool, Tuple[bool, bool, bool]] = True, combine: CombineMode = True, clean: bool = True, ) -> T:
cylinder	def cylinder(d: float, h: float) -> Shape:	def cylinder( self: T, height: float, radius: float, direct: Union[Tuple[float, float, float], Vector] = Vector(0, 0, 1), angle: float = 360, centered: Union[bool, Tuple[bool, bool, bool]] = True, combine: CombineMode = True, clean: bool = True, ) -> T:
sphere	def sphere(d: float) -> Shape:	def sphere( self: T, radius: float, direct: VectorLike = (0, 0, 1), angle1: float = -90, angle2: float = 90, angle3: float = 360, centered: Union[bool, Tuple[bool, bool, bool]] = True, combine: CombineMode = True, clean: bool = True, ) -> T:

[adam-urbanczyk]

Fair request, there is also cq.Sketch to match. For clarity: are you referring to parameter order and semantics (e.g. radius vs diameter) or names too?

[huskier]

All of them, I think:

1. the parameters order;
2. the semantics, by radius and diameter, I think radius is preferred.
3. the parameter name, for example, "width" is preferred to "w" for width.

We do not need to think about the parameters' thing when we write code. It is a natural thing for the parameters.

[huskier]

Is it possible to keep the centered parameter for box, cylinder and sphere free functions? This is also related to consistency with the the same name methods in Workplane class.

[adam-urbanczyk]

For now the design is to not have those and keep the api simple. In the future let's see.