= Style Guide for Lazr Projects =

[[https://launchpad.net/lazr|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 [[Hacking|Launchpad Hacking]] documents.

New projects should also always follow, and start from, the [[https://launchpad.net/lazr.yourpkg|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 [[http://sphinx.pocoo.org/rest.html|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 [[http://sphinx.pocoo.org/extensions.html#builtin-sphinx-extensions|Sphinx extensions]] or [[http://sphinx.pocoo.org/markup/inline.html#cross-referencing-documents|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:

 {{{#!python
    try:
        from foo.bar._bar import Bar
    except ImportError:
        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.