Project structuring and file implementation in Python

I am having a bit of troubles getting a grasp on how to structure my Python projects. I have read jcalderone: Filesystem structure of a Python project and been looking at the source code of CouchApp, but I'm still feeling very puzzled.

I understand how the files should be structured, but I don't understand why. I would love if somebody could hook me up with a detailed walk-through of this, or could explain it to me. Simply how to set up a basic python project, and how the files would interact with each other.

I think this is definitely something people coming from other languages like C, C++, Erlang ... or people who have never be开发者_C百科en programming before, could benefit from.

name the directory something related to your project. When you do releases, you should include a version number suffix: Twisted-2.5.

Not sure why this is unclear. It seems obvious. It all has to be in one directory.

Why do things have to be in one directory? Because everyone says so, that's why.

create a directory Twisted/bin and put your executables there.

This is the way Linux works. Executables are in a bin directory. It makes it easy to put this specific directory in your PATH environment variable.

If your project is expressable as a single Python source file, then put it into the directory and name it something related to your project. For example, Twisted/twisted.py.

Right. You have /Twisted, /Twisted/bin and /Twisted/twisted.py with your actual, running code in it. Where else would you put it?

There's no "why" to this. Where else could you possibly put it?

If you need multiple source files, create a package instead (Twisted/twisted/, with an empty Twisted/twisted/init.py) and place your source files in it. For example, Twisted/twisted/internet.py.

This is just the way Python packages work. They're directories with __init__.py files. The tutorial is pretty clear on this.

put your unit tests in a sub-package of your package Twisted/twisted/test/.

Where else would you put your tests? Seriously. There's no "why?" to this. There's no sensible alternative.

add Twisted/README and Twisted/setup.py to explain and install your software, respectively

Right. Where else would you put them? Again. There's no "why?" They go in the top directory because -- well -- that's what a directory is for. It contains files.

I am not expert in python but reading this lines from first link makes sense if you think that

• There might be computers/programs involved whit project
• There might be other people involved whit project

If you have consistent names and file structures both humans and computers might understand your complex program much better.

This involves topics like: testing, building, deploying, re-usability, searching, structure, consistency...

Standard makes connectivity.

Let's try to answer to each rule:

1) You should have a root dir with a good name. If you make a tarball of your package, it's not considered good behavior to have files on the root. I feel really angry when I unpack something and the current folder ends up cluttered with junk.

2) You should separate your executables from modules. They are different beasts. And if you plan to use distutils, it will make your life easier.

3) If you have a single module, the reasons above don't appy. So you can simplify your tree.

4) Unit tests should be closely tighted to it's package. But they are not the package, so it's the perfect case for a subpackage.