search

lcm-proj / lcm

Lightweight Communications and Marshalling
GNU Lesser General Public License v2.1
1.01k stars 393 forks source link

Refactor exports to follow Python conventions #543

Closed nosracd closed 1 week ago

nosracd commented 1 week ago

Currently the __init__.py generated by lcm-gen exports symbols using the from .file import Foo pattern. Python has defined a set of conventions for exporting symbols:

https://typing.readthedocs.io/en/latest/spec/distributing.html#import-conventions

but the current approach does not follow any of the conventions defined by Python. While the current exports should generally still work it means that some tools won't be able to detect the symbols without implicitly exporting them. For example, running mypy with --no-implicit-reexport would cause errors like error: Module "foo" does not explicitly export attribute "Foo" [attr-defined].

This PR refactors the Python output to export symbols using one of the "redundant symbol alias" conventions defined by Python, or from .file import Foo as Foo. My biggest concern with this change is it will be confusing to people who aren't familiar with the Python export conventions, since at first glance it looks like unnecessary aliasing. I considered generating a comment in the __init__.py to explain the pattern, but I'm unsure if that would be helpful or just junk up the output.

nosracd commented 1 week ago

Perhaps adding a blurb to our documentation and a link to Python's import conventions would help here. Though I'm not sure where to put it. Possibly in the Python tutorial. There's a "Java application notes" so maybe we need a "Python application notes".

That's a good idea. 47b2fb9be3db8b748c50bcf96cd7d2208fe72664 implements that.