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