Docs: Import/Export references a function with a deprecation warning

[DeflateAwning]

In the Import/Export docs page, the very first example uses a deprecated function, as warned by Python linters.

The example in question:

with BuildPart() as box_builder:
    Box(1, 1, 1)
box_builder.part.export_step("box.step")

The warning:

The method "export_stl" in class "Shape" is deprecated
  Use the `export_stl` function instead
Pylance

I'm not sure if the issue is that the example shows the wrong method, or if the deprecation warning shouldn't be there, but it seems there's an issue.

[jdegenstein]

Thanks for pointing it out -- the docs need to be updated.

[DeflateAwning]

What is the correct way? I could probably submit a quick PR for this :)

[jdegenstein]

@DeflateAwning here is the correct syntax:

with BuildPart() as box_builder:
    Box(1, 1, 1)
export_step(box_builder.part, "box.step")

A PR is not necessary as I already added it to my draft docfix PR here #667

[DeflateAwning]

Out of curiosity, why is this better? This seems less easy to find, and at the very least, doesn't seem like it needs to have a deprecation associated with the old way

[jdegenstein]

It is deprecated because we are planning to remove it, just trying to give some warning before we do that. The imports have always been functions, so making the exports functions as well offers better consistency. I am sure there are other benefits too.

If you are new to build123d, I highly recommend you go through the examples here which covers some common use cases -- including this one. https://build123d.readthedocs.io/en/latest/introductory_examples.html

[DeflateAwning]

In most other similar DSL-like systems (e.g., Polars, Pandas, etc.), the imports are viewed as a constructor-like entry point, and thus are not tied to an object. However, exports are an operation on an object (exporting that object), and thus are a method of that object.

I've done that introductory example. Quite good overall.

I just think this is a very strange choice, and that the reasoning isn't quite there.