[Distutils] Easy Install / Setup Tools Example

[Todd Greenwood-Geer]

I've taken to heart your suggestions. The result is what I hope is a 
very simple example / tutorial that demonstrates:

  * the file structure of a project destined to be an egg
  * how to use doctests and unit tests with setuptools / eggs
  * how to build and deploy an egg
  * how to register with pypi
  * how to (and not to) generate wrapper scripts
  * how to write documentation using restructured text

Instructions:
$ easy_install SimpleExampleEgg

That's it. You have now installed v 0.2. The tutorial docs
are the egg:

/usr/lib/python2.4/site-packages/SimpleExampleEgg-0.2-py2.4.egg:fruit/docs/readme.html

Could I get a quick review of this? I'm attaching the readme.html.

-Todd

Phillip J. Eby wrote:
> At 08:27 PM 12/8/2005 -0800, Todd Greenwood-Geer wrote:
> small_unittest.py::
> 
>>         import small
>>         import unittest
>>         import doctest
>>
>>         def getTestSuite():
>>                 suite = unittest.TestSuite()
>>                 for mod in small,:
>>                         suite.addTest(doctest.DocTestSuite(mod))
>>                 return suite
>>
>>         runner = unittest.TextTestRunner()
>>         runner.run(getTestSuite())
> 
> If 'small.small_unittest' is the actual name of the module, then doing this:
> 
>    python -c "from unittest import main; main(None)" 
> small.small_unittest.getTestSuite
> 
> will run the test, even if it's inside an egg.  No unzipping is 
> necessary.  If the egg wasn't installed with a .pth file (i.e. 
> --multi-version or to a non-standard location), you'll need to make sure 
> it's on PYTHONPATH, along with its dependencies.
> 
>> Here is what the src tree for the simple example looks like:
>>
>> dir listing::
>>
>>         small/src/small/test/test.txt
>>         small/src/small/small2.py
>>         small/src/small/small.py
>>         small/src/small/small_unittest.pyc
>>         small/src/small/__init__.py
>>         small/src/small/small_unittest.py
>>         small/src/small_unittest.py
> 
> This looks like a duplicate.  I'm also not sure why you have a small2, or 
> why you bother having a separate test subdirectory.  Indeed, for this 
> "small" of an example, a src/ directory is probably overkill.  For clarity, 
> I'd also suggest calling the topmost directory something like SmallExample 
> to help distinguish your project name (SmallExample) from your package name 
> (small).
> 
>>         small/setup_mult.py
> 
> What's this file for?
> 
> 
>>         small/ez_setup.py
> 
> If you're using Subversion, btw, you can use the svn:externals trick so 
> that you don't have to manually maintain this file; see the setuptools 
> manual under:
> 
> http://peak.telecommunity.com/DevCenter/setuptools#using-setuptools-without-bundling-it
> 
> 
> 
>> The thing to note here is how small.small and small.small2 are referenced::
>>
>>         from small import small as s1
>>         from small import small2 as s2
>>
>> For some reason, this gave me plenty of problems.
> 
> It's generally not a good idea to name a module the same as a package, and 
> definitely not the same as a class within the module, or else it gets 
> unclear in code which one you're talking about.  In a language like Java, 
> there's no such ambiguity because syntactically you can't refer to a class 
> where a package should be or vice versa, but in Python there are only 
> objects, so you should not name them all the same thing or you (and/or the 
> interpreter) will be confused.  :)
> 
> Similarly, I suspect that your example has way too many files perhaps 
> because you have a Java background?  It really isn't necessary to split 
> Python projects up into so many small pieces; it just makes more work for 
> you and doesn't get you any benefit until the files get too large to 
> conveniently work with.
> 
> 
>> Complex Case
>> ------------
>>
>> The complex case splits out the test modules into a nested package 
>> hierarchy like this:
> ...
>> Package Hierarchy
>> +++++++++++++++++
>>
>> package hierarchy::
>>
>>         small/src/
>>         small/src/size/
>>         small/src/size/small
>>         small/src/size/large
> 
> Ouch.  I thought the previous example was the complex one.  ;)  Seriously, 
> your simple example is way more complex than it needs to be.  This bigger 
> one makes my head hurt, so I'm not going to try to comment on it further, 
> except to suggest that its top-level directory should be named 
> "small-mult-test" since that's your project name.  Also, I'm guessing you 
> mean your package hiearchy is size, size.small, and size.large.  The 
> small/src stuff isn't part of the package hierarchy, just the directory 
> hierarchy.
> 
> By the way, the only reason to have a 'src' directory under your main 
> project directory is if you have a bunch of stuff that's *not* source code 
> there.  Such as documentation, documentation directories, test directories, 
> examples, etc.  Your projects here have none of those things, only a setup 
> script, so there's no reason to have a 'src' subdirectory; you could just 
> put the 'small' or 'size' package directly under the project directory, and 
> in fact this is the most common layout for published Python packages.  The 
> 'src' or 'lib' subdirectory approach is mainly used by large projects with 
> a lot of other things in their project directory, and by people who got 
> used to that format by working on large projects.  :)
> 
> 
>>         from size.small import small
>>         from size.large import large
> 
> I said I wasn't going to comment further, but this is technically a 
> repetition of my earlier comment: please don't name packages and modules 
> the same thing, you will confuse yourself and everyone else who will never 
> be sure if 'small' means 'size.small' or 'size.small.small' or worse, 
> 'size.small.small.small'.  Eeek!
> 
> 
>>  * url : need to see if that works for downloading dependencies (next 
>> tutorial, not this one)
> 
> Yes, it does, *if* you register your package with PyPI.  The URL given will 
> be scanned for download links when and if easy_install looks for your 
> package on PyPI.
> 
> 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.python.org/pipermail/distutils-sig/attachments/20051214/12eb0df8/readme-0001.html
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: OpenPGP digital signature
Url : http://mail.python.org/pipermail/distutils-sig/attachments/20051214/12eb0df8/signature-0001.pgp