CadQuery documentation page on assemblies seem to be the last of their conceptual overviews page. After that was a large list of examples, which illustrated many concepts not explicitly covered by earlier overview pages. I expect this page will be a great reference if I continue using CadQuery. To make the most of it, though, I should run through it once now so I have concepts in the back of my head even if I don't fully understand all the subtleties yet. It also turned out to be an opportunity to see how CadQuery behaves when things don't go perfectly.

This opportunity came from my decision not to copy/paste each example into CQ-editor. I typed the commands in line by line, pressing F5 after each line to see results of the most recent action. This helps my memory retention and understanding of CadQuery commands. This also means I would occasionally make mistakes as I go.

I'm worried about the fact CadQuery documentation didn't have a section on how CadQuery handles errors. I'm not talking about raising and catching exceptions kind of error-handling, I'm referring to how it reports errors in user input. FreeCAD set a low bar to clear, as it too often reports only a "Recompute failed!" and left the user up a creek. The good news is that CadQuery seems to offer more feedback, the bad news is the feedback can be quite opaque. Here are two examples:

TypeError: object of type 'float' has no len()

I was mystified when this error came up because I didn't call len() on anything, but I did type in a pair of coordinates as floating point numbers so I knew at least which line of code to look at. It didn't take long before I found I had mistakenly typed a period instead of a comma on the second coordinate.

r = r.pushPoints([(0, 0.75),(0.-0.75)])

Great, but the error message was not terribly unhelpful. I'm worried I'll pull my hair out at future equally unhelpful errors, we'll just have to see. But I'm optimistic based on my experiment to deliberately make the same error on the first coordinate instead of the second:

r = r.pushPoints([(0. 0.75),(0,-0.75)])

For this line, CadQuery gave me this error:

SyntaxError: invalid syntax. Perhaps you forgot a comma?

This is wonderful! I don't know why behavior differed between first and second coordinates. (Maybe the negative sign has something to do with it?) But I am very encouraged by the fact CadQuery at least tried to be helpful.

ValueError: No pending wires present

Thanks to CadQuery's initial overview page, I know what "wires" are in this context. (2D entities with a length but no surface area or volume.) And since I typed in each command on its own separate line, I was able to use CQ-editor's ability to step through line-by-line to understand this was an error from a call to extrude(). I looked over my commands before calling extrude(), which drew a 2D profile line by line. I eventually found a typo in one of the coordinates, which mean its endpoint didn't line up with another and left a gap in my 2D profile.

The bad news is this is worse than FreeCAD error message, which at least told me the profile was not closed. The good news is that I can mitigate such errors by using different 2D sketch commands. For example lineTo() will always draw from the previous point to ensure there are no gaps, and close() will draw a line from the previous point to the first point and ensure shape is closed. I hope that will spare me future headaches.

In the meantime, exploring examples introduced me to some novel and potentially powerful tools like "extrude until".