Style Guide for Lazr Projects
Lazr projects are a collection of the open-sourced stand-alone components that Canonical releases.
Lazr projects generally follow the guidelines described in the Hacking document.
__version__ number
The __init__.py should have a __version__ string for the package that is used by setup.py for the packages version.
Guidelines for re-exporting
Sometimes a package wants to re-export code in its __init__.py file. For instance, if your package is essentially a module with tests and documentation, it may be quite ugly to have your users import your code with from foo.bar.bar import Bar. You would prefer to have your code canonically available as foo.bar.Bar.
However, the __init__.py should have a __version__, as described above; when the setup.py tries to import it, it may get an import error when it is trying to build. And coders looking at your package will generally not expect to find much code in your init.py file.
Our compromise is the following:
Code that you want to re-export in your __init__.py should be placed in a file with a "_" prefix. For instance, in the "foo.bar.Bar" example, you would create a "foo.bar._bar" module for the Bar class.
The __init__.py code that imports your modules should import them within a try: except block:
This allows the setup.py usage of __version__ to still work.
- Tests should only import from the package: that is, if you re-export, the re-export should be the canonical and tested location for imports.