• Immutable Page
• Info
• Attachments
• More Actions: Raw Text Print View Render as Docbook Delete Cache ------------------------ Check Spelling Like Pages Local Site Map ------------------------ Rename Page Delete Page ------------------------ Subscribe User ------------------------ Remove Spam Revert to this revision Package Pages Sync Pages ------------------------ Load Save SlideShow

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 HackingLazrLibraries and Launchpad Hacking documents.

New projects should also always follow, and start from, the lazr.yourpkg template. Use the prepare.py script in the template package to get the package ready for development. For instance, if you want to make a lazr.foo package, you might do this.

bzr branch lp:lazr.yourpkg lazr.foo
cd lazr.foo
./prepare.py foo

See the Hacking document on where to go from there.

Package README.txt, docs, and tests

All documents in the package should use reStructuredText, with Sphinx extensions as needed. Try using bin/docs in your buildout's bin directory, and then looking at parts/docs/lazr.yourpkg/build/README.html.

The package's README.txt should be an introduction to the package.

If it gets too long strongly consider dividing up the document into a briefer introduction in the README.txt using Sphinx extensions or cross-references to link to documents in the docs/ directory.

On the other hand, if your package is very small, the README.txt may be the only documentation you need. In that case, delete the docs directory.

The README.txt and any/all documents in the docs directory are tested automatically by default (see tests/test_docs.py in lazr.yourpkg).

Doctests are encouraged. Additional unit-style tests should be added in the tests directory.

__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:

     1     try:
     2         from foo.bar._bar import Bar
     3     except ImportError:
     4         pass
  

  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.