Packaging python programs with a command line script

Question

I've trying to get my pet Python project into a releasable state and I'm stumped when it comes to packaging it.

Mark Pilgrim recommend this directory structure in Dive Into Python

httplib2/                 
|  
+--README.txt             
|  
+--setup.py               
|  
+--httplib2/              
    |  
    +--__init__.py  
    |  
    +--iri2uri.py

What I can't figure out is, if I have a runner script ie an executable command line program, say foo and the name of my project is foo, what should I name the internal package directory?

To give a concrete example, if I have

README.md
LICENSE
somefile1.py
somefile2.py
foo

What is that best way to package this?

For instance

+--README.md
|
+--LICENSE
|
+--foo
|
+--foo/
    |
    +--somefile1.py
    |
    +--somefile2.py

Doesn't work because of the duplicate name.

Evan Plaice · Accepted Answer · 2012-04-14 04:09:03Z

3

You're doing it wrong...

Here's what the structure 'should' look like

foo 1.0/
| +--README.txt
| +--setup.py
| +--foo/__init__.py
| +--foo/iri2uri.py
| +--foo/httplib2/__init__.py
| +--foo/httplib2/bar.py

Think of the outer, enclosing folder as the package. This should include installation and documentation files LICENSE, README, MANIFEST, setup.py. The folders within the package (in this case, just '/foo') are the modules.

To access all of the functions above you'd use the following import statements:

import foo                # represented by foo/__init__.py
import foo.iri2uri        # represented by foo/iri2uri.py
import foo.httplib2       # represented by foo/httplib2/__init__.py
import foo.httplib2.bar   # represented by foo/httplib/bar.py

Technically, you can choose to include sub-modules as either a file or a folder. Folders are only necessary of there are sub-modules of the sub-module.

For instance:

foo 1.0/
| +--/foo/iri2uri.py
| +--/foo/iri2uri/__init__.py

Will be both be interpreted the same way.

For example:

import foo.iri2uri

It's a little tricky at first but everybody who has ever built a package for installation has encountered this speed bump.

Update: I think this better answers your question

For executables you create a separate package

No installer is necessary because this code won't be imported by other applications.

examples/
| +--/foo.py

They should be run as stand-alone programs and import the necessary modules from the library (foo) that you installed.

edited Apr 14, 2012 at 4:09

answered Apr 14, 2012 at 2:22

Evan Plaice

14.2k6 gold badges78 silver badges95 bronze badges

Sign up to request clarification or add additional context in comments.

4 Comments

Evan Plaice Over a year ago

Woah! your question changed drastically while I was writing my answer. The gist is, the outer folder name doesn't matter; it's just the name of the package. The inner folder is important because that's the name of the module you're installing.

James McMahon Over a year ago

Sorry if that was confusing, Piligrim's example is distinct from my layout.

James McMahon Over a year ago

I just updated the question again, hopefully that clears things up.

Evan Plaice Over a year ago

There, that should be it. If you're familiar with Linux, you'll understand the use of the /lib and /bin directories. /lib is where code that is expected to be imported into other applications should live. /bin is where stand-alone applications live. If you want to install a stand-alone app, you'll need another package to handle installing it to the correct location.

Collectives™ on Stack Overflow

Packaging python programs with a command line script

1 Answer 1

4 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

4 Comments

Your Answer

Sign up or log in

Post as a guest

Related