[Distutils] local development scenarios

[Phillip J. Eby]

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.