Project example¶
TBD - simple example
Project layout¶
XXX explains here the bascis
Dos and Don’ts¶
XXX intro
Dos:
- name the directory something related to your project. For example, if your project is named Twisted, name the top-level directory for its source files Twisted. When you do releases, you should include a version number suffix: Twisted-2.5.
- create a directory
Twisted/bin
and put your executables there, if you have any. Don’t give them a.py
extension, even if they are Python source files. Don’t put any code in them except an import of and call to a main function defined somewhere else in your projects. - 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
. If you need multiple source files, create a package instead (Twisted/twisted/
, with an emptyTwisted/twisted/__init__.py
) and place your source files in it. For example,Twisted/twisted/internet.py
. - put your unit tests in a sub-package of your package (note - this means that
the single Python source file option above was a trick - you always need at
least one other file for your unit tests). For example,
Twisted/twisted/test
. Of course, make it a package withTwisted/twisted/test/__init__.py
. Place tests in files likeTwisted/twisted/test/test_internet.py
. - add
Twisted/README
andTwisted/setup.py
to explain and install your software, respectively, if you’re feeling nice.
Don’ts:
- put your source in a directory called
src
orlib
. This makes it hard to run without installing. - put your tests outside of your Python package. This makes it hard to run the tests against an installed version.
- create a package that only has a
__init__.py
and then put all your code into__init__.py
. Just make a module instead of a package, it’s simpler. - try to come up with magical hacks to make Python able to import your module or package without having the user add the directory containing it to their import path (either via PYTHONPATH or some other mechanism). You will not correctly handle all cases and users will get angry at you when your software doesn’t work in their environment.