.tag mutates but other methods don't?

[cacsar]

I'm just starting to use to CadQuery moving over from a small amount of OpenSCAD, and I've run into an oddity that I can't seem to find an answer to in the documentation, although I have not yet read the code.

In essence the Fluent API does not appear to mutate the objects and so splitting it across lines requires assignment to a variable. This makes sense and is discussed in the concepts section.

However, this does not appear to be the case for tag as seen in the Assemblies tutorial on lines like these.

I ran into this while trying to add features to check that I was tagging the correct faces (ie using sphere or hole instead of tag). Since the door example works as is and not with the lines commented out, I assume that tag is mutating global state and this is the reason for the difference?

If so, would it be reasonable to update the example to something like the below and add a note to tag or in concepts saying it can work without assignment and it's special?

def make_connector():

    rv = (
        cq.Workplane()
        .box(20, 20, 20)
        .faces("<X")
        .workplane()
        .cboreHole(6, 15, 18)
        .faces("<Z")
        .workplane(centerOption="CenterOfMass")
        .cboreHole(6, 15, 18)
    )

    # tag mating faces
    rv = rv.faces(">X").tag("X").end()
    rv = rv.faces(">Z").tag("Z").end()

    return rv

A snippet from my code

def makeSupport():
    support = (
        cq.Workplane("XY")
        .box(supportWidth, supportLength, woodThickness)
        .edges("|Y")
        .fillet(0.125 * mmPerInch)
        )
    
    support.faces("<Y").sphere(5) # Does nothing
    #support = support.faces("<Y").sphere(5) # Adds a half sphere
    support.faces("<Y").tag("bottom")
    return support

show_object(makeSupport())

[lorenzncode]

However, this does not appear to be the case for tag

Correct. The Workplane modeling context is updated. Example:

In [1]: import cadquery as cq

In [2]: r = cq.Workplane().box(1, 1, 1)

In [3]: r.ctx.tags
Out[3]: {}

In [4]: r.faces(">Z").tag("f1")
Out[4]: <cadquery.cq.Workplane at 0x7f77038777d0>

In [5]: r.ctx.tags
Out[5]: {'f1': <cadquery.cq.Workplane at 0x7f77038777d0>}

See also https://cadquery.readthedocs.io/en/latest/workplane.html#an-introspective-example

In this example it says We can tag the Workplane that contains this basic box now:

part = part.tag("base")

saying it can work without assignment and it's special?

I think that makes sense. The example does go on to say it is unusual:

the tag() method has returned the same object at 0xaa90. This is unusual for a Workplane method.

Perhaps it can also mention tagging without assignment:

part.tag("base")

[adam-urbanczyk]

Note that few other methods mutate as well, e.g. rect().