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-...
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.