[Distutils] local development scenarios

[Todd Greenwood-Geer]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Phillip -

This is great feedback. I wrote this tutorial for myself because, in the
course of writing a more involved application, I realized that I did not
really understand how to use the egg/setuptools functionality. So, the
example is definitely contrived.

So, if I may summarize your guidelines:

1. Add complexity as needed
~ a) keep source in the root dir unless there is a need to differentiate
~ disparate types of files, such as source/docs/tests/etc
~ b) use the svn copy of ez_setup.py rather than checking this in to the
repository

2. Clear use of names
~ a) use different names for packages and modules
~ b) again, nest only as necessary

And, above all else, never admit to having a java background ;o).

Thanks again. I'll re-factor as suggested and throw this at you one more
time.

- -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.
|
|
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)

iD8DBQFDmRzIz6uXX4lQc/URAsaWAKCXNcWjf7o59m2MgM2B8Nmx1CfLewCgpqOW
wA2wfi08C4RPW151NngP7BU=
=N5e6
-----END PGP SIGNATURE-----