lazr-developers team mailing list archive

[Barry Warsaw <barry@xxxxxxxxxxxxx>]

On Mar 14, 2009, at 01:30 AM, Gary Poster wrote:

>Hi Barry.  Thank you for the review!  
>
>I agree that for the case that you describe, a tests directory would be appropriate.  
>
>However, of the several examples that I've done so far, we only have one such lazr.* package that fits this description (that is, one with tests other than doc tests).
>
>Moreover, for this one that has additional non-doctest tests, the addition is so small that I'd prefer to combine them.  
>
>Even if you disagree with me on whether those two files could be combined, the rest of the packages I've done initially all had a directory with a single file in it: the one that ran the doctest(s).  I find a directory holding a single file worse than pointless--a needless hindrance.
>
>I guess we simply disagree that ./tests.py is particularly more jarring than ./tests.

Of course, it's not difficult for a package derived from lazr.yourpkg to move
things around and do different things, but lazr.yourpkg is a better template
if it lays out the most useful directory structure.  There's another
consideration for making a tests directory: are the existing test files too
big?  I'm thinking about lazr.config's doctest and that might be something
that we'd want to split up into smaller documentation files.

I suppose the other thing that bugs me about this is that tests.py is
intermingled with the 'real' modules of the library.  By sequestering the
tests in a separate subdirectory, it's a stronger clue (to me) that these are
not part of the package proper.  Okay, yes, tests are part of the package, but
they are a separate thing too, and the directory structure should reflect that.

>If I ignore that one point of disagreement, then it simply comes down to this: the *exception* so far has been the kind of package that you describe, in which we have more than one test file.  For the rule, I've had to modify the lazr.yourpkg results repeatedly.  I wanted to change the template to match what I've encountered.
>
>I must admit that I have thought while working on this that we might want a "large" and "small" variant.  Almost all of the lazr packages I've done so far have had a single doctest, for which a package README.txt and a package tests.py is quite sufficient and appropriate, without (to my mind) needless delving into further directories only to discover that they have a one-to-one relationship with their contents.
>
>So, in this hypothetical magic wonderland, a ``./prepare.py --small``, with only a README.txt and a tests.py (no docs or tests directories) would most definitely be the default, in my mind.  A ``./prepare.py --large`` (with a README.txt, a docs directory, and a tests directory) would be a nice-to-have exception, in my experience.

It might be indeed be nice to have --large and --small variants.  I'm also not
so sure about loading up README.txt with documentation.  I think README.txt
should be fairly generic, and possibly exactly the same across all lazr
packages.  That's where I get to the question of where documentation /should/
go and from there, to the docs/ directory.

>
>So in sum, I push back to your push back :-).  At least once. ;-)  If you can agree that unnecessarily nested folders is at least a reasonable equivalent nastiness to your dislike of tests.py in the main package, then my proposed resolution possibilities would be the following:
>
>OPTION 1: We commit this as is.  I argue it matches the common case better.  We can build the hypothetical magic wonderland when we discover we need it (releases of larger projects are frequent).
>
>OPTION 2: I maintain a fork.  If I continue making releases as I have been, it will come in handy (it would have been handy last week).
>
>OPTION 3: We work on the hypothetical magic wonderland now.

So, we definitely don't want to fork, and I'm not much in favor of doing
hypothetical work.  I'll push back a little more and we'll try to resolve
Zeno's Paradox of Package Design. :)

>So, the questions for you are whether you can agree on the reasonable equivalent of nastiness (tests.py in a package is a reasonable dislike; a tests folder with only a single meaningful file is at least a reasonable equivalent dislike); and if so, which of the options you prefer (or propose another).

(Obviously ;) I tip the balance against the former nastiness because I like
the idea that consistency, and a higher level of granularity, would call for
the tests subdirectory.  It doesn't bother me that much that a test directory
has only one file in it (aside from the __init__.py, so I guess that makes two
at a minimum :).

halfway-closer-ly y'rs,
Barry
-- 
https://code.launchpad.net/~gary/lazr.yourpkg/trunk/+merge/4477
Your team LAZR Developers is subscribed to branch lp:lazr.yourpkg.