Tweeting python packaging tips.

I've begun 'tweeting' python packaging tips. I'm hoping to go up to 100 useful python packaging tips. If you're a twit too, please feel free to join in on the conversations.

---

update: I wrote a little script to download all the python packaging related tweets from twitter. For some reason twitter is only giving me 32 of them... but I've written about 40 so far. Going to run through these at the london python dojo tonight in a mini talk.

---

setup.py build_ext --inplace to compile your extensions inside the source directory. Good for developing inplace

distribute 'setup.py develop' Installed pkg points to dev copy, quicker changes during dev. develop -u to remove

For pyrex/cython/swig packages, include the generated C code so people do not need to install cython/pyrex/swig.

For debugging info set DISTUTILS_DEBUG. os.environ['DISTUTILS_DEBUG'] = "on" OR export DISTUTILS_DEBUG=on

Don't put code in package/__init__.py file. Makes debugging/editing harder as there are lots of __init__.py files

Name the folder your package lives in after the package name, not src or lib. eg ./mypackage/

Make quick and dirty .deb .rpm packaging of any python package with checkinstall

Create man pages(unix docs) for scripts and command line programs you make available. See rst2man and help2man.

Install scripts (cmd line programs) with pkg http://docs.python.org/distutils/setupscript.html#installing-scripts

Including a short summary of changes at end of 'description' metadata lets people quickly see changes on pypi.

put a #hashtag in your description metadata, and your package will turn up on twitter under that.

Read other peoples python packages to see what they do well. Especially packages you use.

Distutils2 is the future of packaging. It's not ready yet though. http://pypi.python.org/pypi/Distutils2

setup.cfg is an (optional) setup config file. http://docs.python.org/distutils/configfile.html

Test on multiple python versions before release. Each py version is different (2.6,3,pypy,ironpython,jython).

Tests are good. See what you are not testing with the coverage package. http://nedbatchelder.com/code/coverage/

Check your package quality with Cheesecake. 'pip install Cheesecake' 'cheesecake_index -v -n yourpackage'.

Give credit, ♥, and props to your contributors in a thanks.txt file.

pep 386 specifies version scheme for Distutils - use it. http://www.python.org/dev/peps/pep-0386/

1 eg. #django package is not at http://pypi.python.org/pypi/django . It is at http://pypi.python.org/pypi/Django

Packages are caseSensitive. Refer to it the same way it's installed, otherwise confusion installing & finding.

Check your package name is available on pypi, and that it follows the pep8 naming convention. All lowercase, etc.

No changes metadata field. Put in long_description field and CHANGES.txt so people know what's new or changed.

MANIFEST.in controls files to include/exclude (.bak .swp) http://docs.python.org/distutils/sourcedist.html

bdist_mpkg is the package required to make Mac OSX installers.

1 In your setup.py from distutils.command.build import build;build.sub_commands.append(('test', None))

Running tests after build helps catch errors in distro packaged versions, and turns all users into testers.

Great guide http://diveintopython3.org/packaging.html Slightly dated (2009) since py packaging moves fast.

pep 345, latest spec for adding metadata to Python distributions. http://www.python.org/dev/peps/pep-0345/

readme.txt - Use .txt extension. Be reStructuredText. Use windows carriage returns/newlines because notepad sux.

The debian/ dir should only be in the Debian packaging repository. The debian maintainer takes care of it.

_module.so _module.dll _module.dynlib - compiled extensions should be named with a leading underscore.