Organizing a Python project

[Gabriel Genellina]

En Wed, 21 May 2008 07:44:50 -0300, Casey McGinty <casey.mcginty at gmail.com> escribió:

Just my own opinion on these things:

> 1. Script code should be as basic as possible, ideally a module import line
> and function or method call. This is so you don't have to worry about script
> errors and/or increase startup time because a *.pyc file can not be store in
> /usr/bin.

Scripts are not compiled by default, only imported modules (anyway you could compile scripts by hand). Keeping the main script short might reduce the startup time, yes.

> 2. In the top of your package directory it is typical to have a module name
> '_package.py'. This is ideally where the main command line entry point for
> the package code should be placed.

Why the underscore? And I usually don't put executable scripts inside a package - I consider them just libraries, to be imported by other parts of the application.
It's easier to test too when your tests *and* the application code are external to the package itself.

> 3. In the _package.py file you should add a "class Package" that holds most
> or all of the application startup/execution code not designated to other
> modules. Then run the application with the call to "Package()", as in
>
>     if __name__ == '__main__':
>        Package()

In Python that doesn't *have* to be a class, and in fact, most of the time I use a function instead. Something like this:

def main(argv):
     # do things

if __name__ == '__main__':
     import sys
     sys.exit(int(main(sys.argv) or 0))

> Some other questions I have are:
> A. What should go in the package __init__.py file? For example, a doc
> describing the program usage seems helpful, but maybe it should have info
> about your modules only? Assuming the __init__.py code gets executed when
> you import the module, you could place part or all of the application code
> here as well. I'm guessing this is not a good idea, but not really
> convinced.

Yes, the __init__.py is executed when you import the package. And no, I don't think it's a good idea to put all the application code there. As I said above, I consider packages *libraries*, the application code should *import* and use them, but not reside *inside* a package.
And there is the "import lock" issue too - I'm unsure of this but I think a lock is held until the import operation finishes, and that would happen only after __init__.py is fully executed.

> B. How should you import your _package.py module into your /usr/bin script.
> Is there a way to use an '__all__' to simplify this? Again this goes back to
> question A, should there be any code added to __init__.py?

I don't get the question... you import it as any other module (but I would not use a _package.py file anyway)

> C. If you have a _package.py file as the application entry, is it worth it
> to place most of the application code in a class, described in part 3?

As I said, I'd use a function, at least at the top level. Of course it can create many other objects.

> D. When I import a package._package module, I get a lot of junk in my
> namespace. I thought an '__all__' define in the module would prevent this,
> but it does not seem to work.

`import package._package` should only add "package" to the current namespace. If you're using `from package import *` - well, just don't do that :)
Otherwise I don't understand what you mean.

-- 
Gabriel Genellina