[Distutils] People want CPAN :-)

[Kevin Teague]

On Nov 12, 2009, at 12:42 PM, John Kleint wrote:
>
> I have the start of such a document, derived from my own recent
> experience pulling together all the information needed to release a
> new Python project.  It's aimed at people new to packaging and
> possibly open source in general, so it's broader than just packaging.
> It includes things like basic file layout, unit testing, Pylint,
> getting started with Sphinx, a sample (distutils) setup.py, and how to
> register with PyPI.  I try to pull together all the info a novice
> would need to have a reasonable shot at sharing their code.  It's by
> no means all-encompassing (e.g. no mention of native extensions), but
> perhaps someone would be willing to write a complimentary advanced
> packaging howto.  You can find it at:
>
> http://infinitemonkeycorps.net/docs/pph/
>
> Let me know what you think.
>

It's a good start, but a few critques on the packaging section:

  * Avoid importing your package before you've installed it.

   Importing a package works fine for packages which have no  
dependencies, but once your package depends upon other packages you  
can't use this technique. It's better to teach people how to write  
setup.py scripts which don't import the package so that their  
setup.py's can be consistent once they do write packages with  
dependencies. There are lots of cases where the assumptions of the  
configuration of a developer's environment where dependencies are  
installed that won't work for other people trying to install such a  
package, which leads to setup.py files which don't work.

   One example for handling the long_description field can be done  
with (there are lots of variants on this, and you can just call open()  
for a single text file:

def read(*rnames):
     return open(os.path.join(os.path.dirname(__file__),  
*rnames)).read()

long_description=read(
     read('README.txt')
     + '\n' +
     'Detailed Documentation\n'
     '**********************\n'
     + '\n' +
     'src/some-other-file.txt',
)


  * download_url field is not necessary.

    Libraries are often installed automatically by tools (buildout,  
pip, easy_install). This work best if the downloads are in a  
consistent structure (e.g. on PyPI). If releases are made to PyPI,  
then you don't need a download_url to get to another place where the  
file can be downloaded. The field is also prone to mistakes, since  
easy_install will follow the download URL and screen-scrape that page  
looking for a download link. Which can lead to older or wrong versions  
of the package being downloaded. Basically it just causes room for  
errors, and is just one extra step that you need to do to create a  
package, so why do it?

  * package_dir location.

     This is a very minor point, but I find putting the source in a  
directory named after the module or package which isn't the module or  
package confusing. A common alternative is to use 'src' as the name  
for the source directory. Then that location can be consistent from  
package to package.

  * provides (and requires) are scheduled for deprecation

    These fields don't make any sense. If you are listing the imports  
that your package needs, you need to list the name of the distribution  
which provides those packages, not the names of the imports that your  
code is using. setuptools (or now distribute) lets you use an  
'install_requires' field, and this fields is also likely to be in  
Distutils in the next Python release.


  * Use a tool to help automate releases

    Creating each release requires a lot of manual changes here and  
there (bump the version, update the changelog, run sdist, upload to  
pypi). In the spirit of "release early, release often", I like to use  
a tool to automate releases, and also helps establish a few more  
common conventions between Python projects. I'm using zest.releaser  
for this ATM (shameless plug, since I'm also a contributor to the  
project):

    http://pypi.python.org/pypi/zest.releaser




-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/distutils-sig/attachments/20091112/bc683f31/attachment.htm>