Re: [Zope3-dev] Re: Windows eggs
Benji York wrote: It'd be nice to have a -C option that disables -c for when your test runner has -c included in the default options (as I intend to do with mine). I've added such an option. The -C switch makes sense, but I'm not entirely happy with the --no-color version of the name, any suggestions? -- Benji York Senior Software Engineer Zope Corporation ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
Benji York wrote: Marius Gedminas wrote: There's a little complication: when you have test layers that don't support tearDown, some of the tests are run in a subprocess, where stdout isn't a terminal (it's a pipe), but all the output will be copied verbatim to the stdout of the parent process (which may or may not be a terminal). The test runner could look at the top level stdout and pass the information to subprocesses. I've implemented this in revision 78022. The option name is --auto-color. -- Benji York Senior Software Engineer Zope Corporation ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Debugging doctests (was Re: [Zope3-dev] Re: Windows eggs)
On Jul 13, 2007, at 5:09 PM, Wichert Akkerman wrote: ... Amen. I find failing doctests to be much harder to debug as well. Are you are of the post-mortem debugging features of the zope.testing test runner? I find this helps a lot when debugging test failures. On Jul 14, 2007, at 1:00 PM, Wichert Akkerman wrote: ... Until you have to step through the test with pdb, at which point it becomes very painful. It's true that you can't step across examples. Of course, you can call pdb.set_trace on an example. If you really need to step through multiple examples, you can combine the examples. So, for example, you could convert: x = f() y = g(x) to: if 1: ... x = f() ... y = g(x) For me, post-mortem debugging or using set_trace is almost always good enough. On those occasions where I really need to step through a series of example, It's straightforward to convert them to a single example. In general I find well-written doctests easier to debug because they have documentation and the documentation makes their intent clearer. Well written doctests will have documentation even when they aren't intended as documentation. Of course, it could be argued that well written classic tests will have comments. I think that doctest facilitates writing good tests, as I have see far more well-written doctests than I've seen well-written classic tests. Jim -- Jim Fulton mailto:[EMAIL PROTECTED]Python Powered! CTO (540) 361-1714 http://www.python.org Zope Corporationhttp://www.zope.com http://www.zope.org ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: Debugging doctests (was Re: [Zope3-dev] Re: Windows eggs)
On Monday 16 July 2007 08:44, Jim Fulton wrote: For me, post-mortem debugging or using set_trace is almost always good enough. On those occasions where I really need to step through a series of example, It's straightforward to convert them to a single example. Me too. Actually I only use set_trace() and I always quickly find what I need. In general I find well-written doctests easier to debug because they have documentation and the documentation makes their intent clearer. I agree. Well written doctests will have documentation even when they aren't intended as documentation. Of course, it could be argued that well written classic tests will have comments. I think that doctest facilitates writing good tests, as I have see far more well-written doctests than I've seen well-written classic tests. Amen. :-) I think we can say this about ourselves too. We (Zope 3 developers) have written much better tests since we started using doctests. Regards, Stephan -- Stephan Richter CBU Physics Chemistry (B.S.) / Tufts Physics (Ph.D. student) Web2k - Web Software Design, Development and Training ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
On Sunday 15 July 2007 11:26, Benji York wrote:
I think I miscommunicated. Let me combine your example and mine to
demonstrate what I was talking about. Say you have an HTML document and
you want to make assertions about a portion of it. You could use XPath
to extract part of the document and then use the smart ellipses to make
assertions about it. Like so:
browser.open(...)
Introspector(browser.contents).xpath('//foo')
foo ...Text here/foo
In the above example, the tester wants to extract the foo element, and
assert that its contents are Text here and that there are no child
elements. They don't want to make any assertions about it's attributes
so they put the ellipses there. Is that example clearer?
Yes, I see. I think this would be somewhat useful, since it would make the
test less brittle to id or cass changes.
Regards,
Stephan
--
Stephan Richter
CBU Physics Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
On Sunday 15 July 2007 12:45, Marius Gedminas wrote: I was talking about regular programmer-facing documentation and couldn't find a good word for it (tutorial? programmer's guide). The thing you read to learn about the package, not the thing you use to look up some details of some function. Right, explanatory text. That's a huge win coming from interfaces, in my opinion. I wish pydoc knew about zope interfaces... Me too. At least APIDOC knows about them. However, with the component architecture I find all of those tools rather limiting, since they do not reveal anything about how components can be put together, like is this used as a utility or what adapters are available? I never do this anymore. If I have a collection of utility functions, I Still put them in a text file, because text files allow me to concentrate on documentation. Perhaps I did not get my point clearly accross. Python modules with doctests are useful for testing the various corner cases that you did not test in the corresponding .txt file. I test all corner cases in the text file. I have learned that as long as you cannot explain something to someone else, you do not understand it yourself well enough. Writing documentation even for the corner cases ensures that I have motivation for the case and I can explain why I think this is the right solution. Note that there are plenty of technical writing techniques to cover special cases. You can use footnotes, chapters, and appendices to talk about them. We are doing nothing new here; we just should not refuse to use well-established writing methods just because we are doing software engineering. If you put the tests for all your corner cases into the documentation, it quickly becomes unreadable. I totally disagree. If it becomes unreadable, your writing skills are lacking. I relate this to Phsyics, which makes what you are saying clearer: If I have to explain to you all the gory details of solving this problem, then the lecture/write-up becomes incomprehensible. In my experience only a bad educator would make such a statement. A good educator takes the time to break down the problem and explain everything about the problem. In our case, educator equals writer. Which brings me to my final point: When I am writing doctests I do not wear my programmer hat, but my educator/writer hat. I think very carefully about the use cases the reader might have in mind, expectations s/he might have when hearing a term, existing knowledge that I expect the reader to bring into the reading, etc. Right, but test_foo.py is never about documentation, it's about isolated unit tests. But what is a unit test without documentation? In my opinion, it is a brittle test. Because documentation formalizes intend, while the test formalizes functionality. In the SchoolTool code (can't remember where) I have seen tests where the documentation deviated from the test code. Would the documentation not be there, the disacrepency would not be shown at all. Writing a one liner is fine, but it will never be as thought out as if you were to write an explanatory text. All this reminds me of another practice that I really dislike. Some people, when fixing a bug, will create a separate section at the end of document, often titled something like Demonstration of Bug XXX. I think this is rather dubious, since people learning the API after the bug has been fixed were never aware of it in the first place and now wonder why the bug case is so special. A bug fixer should find the documentation discussing the subject and insert text adn test in a way that the text keeps flowing. I know this is not easy; sometimes when I cannot find any good place, I create a footnote, which effectively is a non-flowing piece of text, but it is at least located at the right location. Okay, I am done preaching. ;-) Regards, Stephan -- Stephan Richter CBU Physics Chemistry (B.S.) / Tufts Physics (Ph.D. student) Web2k - Web Software Design, Development and Training ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
On Saturday 14 July 2007 18:13, Marius Gedminas wrote: http://svn.zope.org/zope.testing/branches/colorized-output/ I'm very much looking forward to that branch being merged to the trunk. Merged. Yipee! Regards, Stephan -- Stephan Richter CBU Physics Chemistry (B.S.) / Tufts Physics (Ph.D. student) Web2k - Web Software Design, Development and Training ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
On Saturday 14 July 2007 15:30, Benji York wrote: Marius Gedminas wrote: - Functional tests: these are .txt files that use zope.testbrowser and are the hardest to debug. There ought to be a better way to make assertions about HTML output than using ELLIPSIS and then pulling your hair out looking at huge and incomprehensible diffs. Yep, assertions about HTML (or XML) are difficult to do with plain text. One option is to feed browser.contents to your favorite HTML (XML) parser. Right, z3c.etestbrowser does this already. I wish they would have done this with a different object altogether, but they extended the TestBrowser class. But then I do not have enough objectstion to write a new package. Regards, Stephan -- Stephan Richter CBU Physics Chemistry (B.S.) / Tufts Physics (Ph.D. student) Web2k - Web Software Design, Development and Training ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
On Saturday 14 July 2007 04:24, Marius Gedminas wrote:
- API documentation: human readability is the primary concern, doctests
are in there just to make sure the documentation stays up to date.
These are .txt files.
I disagree. API reference should be automatically created. Text files are
there to explain the API to someone who wants to use it. I write text files
like I would write a lab report or a book on the subject.
- Short usage examples: sometimes it's simpler to show an example than
to describe the function in words:
def parse_date(date_string):
Parses an ISO-8601 date.
parse_date('2007-07-14')
datetime.date(2007, 7, 14)
I have not done this, because most interesting functions/methods are not that
simple. Also, I really enjoy not having long documentation strings in the
code anymore. That's a huge win coming from interfaces, in my opinion.
- Unit tests: there are many of those, they're independent (thus a
single .txt for a collection of tests is a Bad Idea), they're short
(so understanding and debugging is easy) and expressive. I put
those into .py files full with functions that look like
def doctest_FooClass_does_this():
Test that FooClass is able to ...
foo = FooClass()
results = foo.do_this()
for fruit, score, comments in results:
... print fruit.ljust(10), '|', score.ljust(5), '|',
comments Orange | 9 | Tastes good, a bit sour
Apple | 8 | Varies
I never do this anymore. If I have a collection of utility functions, I Still
put them in a text file, because text files allow me to concentrate on
documentation. In you example above, for example, I miss a lot of explanatory
text. When I have utility functions that I want to explain independently,
then I simply create one section/chapter per function.
- Functional tests: these are .txt files that use zope.testbrowser and
are the hardest to debug. There ought to be a better way to make
assertions about HTML output than using ELLIPSIS and then pulling
your hair out looking at huge and incomprehensible diffs.
I agree. You should give z3c.etestbrowser a try. It is based on lxml and
supports XPath querying. I switched all my functional testing to etestbrowser
now.
Regards,
Stephan
--
Stephan Richter
CBU Physics Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
Stephan Richter wrote: On Saturday 14 July 2007 15:30, Benji York wrote: Yep, assertions about HTML (or XML) are difficult to do with plain text. One option is to feed browser.contents to your favorite HTML (XML) parser. Right, z3c.etestbrowser does this already. I wish they would have done this with a different object altogether, but they extended the TestBrowser class. But then I do not have enough objectstion to write a new package. Perhaps someone can explain the utility of z3c.etestbrowser. As far as I can see, it just adds an etree attribute to browser instances. That doesn't seem to have much advantage over just calling etree on browser.contents. I'm doing some work with doctest right now, and am considering how to make assertions about HTML/XML better. The programmatic approach like above is one option. Another would be to use a special checker that took into account HTML/XML structure. For example, it could interpret ellipses differently such that foo ...Text here/foo would match foo a=bText here/foo but not foobar/Text here/foo -- Benji York Senior Software Engineer Zope Corporation ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
On Sunday 15 July 2007 10:44, Benji York wrote:
Right, z3c.etestbrowser does this already. I wish they would have done
this with a different object altogether, but they extended the
TestBrowser class. But then I do not have enough objectstion to write a
new package.
Perhaps someone can explain the utility of z3c.etestbrowser. As far as
I can see, it just adds an etree attribute to browser instances. That
doesn't seem to have much advantage over just calling etree on
browser.contents.
Right, right now it does not do much more. But I do not have to think about it
and just use the attribute. I usually end up writing one more utility
function that does an XPath expression selects the first result (which I am
usually interested in) and prints that. I think this would make a great
method on etestbrowser.
I'm doing some work with doctest right now, and am considering how to
make assertions about HTML/XML better. The programmatic approach like
above is one option. Another would be to use a special checker that
took into account HTML/XML structure. For example, it could interpret
ellipses differently such that
foo ...Text here/foo
would match
foo a=bText here/foo
but not
foobar/Text here/foo
I would not like that. I really, really like to use XPath to select an element
in the HTML structure. The method above would still require me to write
print browser.contents
...
foo ...Text here/foo
...
So I really like this much better:
print browser.xpath1('//foo')
foo a=bText here/foo
Of course, I really would prefer this:
print Introspector(browser).xpath1('//foo')
foo a=bText here/foo
This is so that the browser features and content inspection are separated.
Regards,
Stephan
--
Stephan Richter
CBU Physics Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
Stephan Richter wrote:
I would not like that. I really, really like to use XPath to select an element
in the HTML structure. The method above would still require me to write
I think I miscommunicated. Let me combine your example and mine to
demonstrate what I was talking about. Say you have an HTML document and
you want to make assertions about a portion of it. You could use XPath
to extract part of the document and then use the smart ellipses to make
assertions about it. Like so:
browser.open(...)
Introspector(browser.contents).xpath('//foo')
foo ...Text here/foo
In the above example, the tester wants to extract the foo element, and
assert that its contents are Text here and that there are no child
elements. They don't want to make any assertions about it's attributes
so they put the ellipses there. Is that example clearer?
Of course, I really would prefer this:
print Introspector(browser).xpath1('//foo')
foo a=bText here/foo
This is so that the browser features and content inspection are separated.
Yep, I much prefer having this functionality in a separate object as
well; it's not really testbrowser specific.
--
Benji York
Senior Software Engineer
Zope Corporation
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
On Sun, Jul 15, 2007 at 08:34:43AM -0400, Stephan Richter wrote:
On Saturday 14 July 2007 04:24, Marius Gedminas wrote:
- API documentation: human readability is the primary concern, doctests
are in there just to make sure the documentation stays up to date.
These are .txt files.
I disagree.
Perhaps not. ;)
API reference should be automatically created.
Yes, absolutely, with something like pydoc/epydoc/pydoctor.
I was talking about regular programmer-facing documentation and couldn't
find a good word for it (tutorial? programmer's guide). The thing you
read to learn about the package, not the thing you use to look up some
details of some function.
Text files are
there to explain the API to someone who wants to use it. I write text files
like I would write a lab report or a book on the subject.
- Short usage examples: sometimes it's simpler to show an example than
to describe the function in words:
def parse_date(date_string):
Parses an ISO-8601 date.
parse_date('2007-07-14')
datetime.date(2007, 7, 14)
I have not done this, because most interesting functions/methods are not that
simple.
Yes, these are very rarely applicable in my experience. Low-level
universal utility functions, mainly, not application business logic.
Also, I really enjoy not having long documentation strings in the
code anymore.
That's great, I completely agree.
That's a huge win coming from interfaces, in my opinion.
I wish pydoc knew about zope interfaces...
- Unit tests: there are many of those, they're independent (thus a
single .txt for a collection of tests is a Bad Idea), they're short
(so understanding and debugging is easy) and expressive. I put
those into .py files full with functions that look like
def doctest_FooClass_does_this():
Test that FooClass is able to ...
foo = FooClass()
results = foo.do_this()
for fruit, score, comments in results:
... print fruit.ljust(10), '|', score.ljust(5), '|',
comments Orange | 9 | Tastes good, a bit sour
Apple | 8 | Varies
I never do this anymore. If I have a collection of utility functions, I Still
put them in a text file, because text files allow me to concentrate on
documentation.
Perhaps I did not get my point clearly accross. Python modules with
doctests are useful for testing the various corner cases that you did
not test in the corresponding .txt file.
If you put the tests for all your corner cases into the documentation,
it quickly becomes unreadable.
In you example above, for example, I miss a lot of explanatory
text.
I was trying to keep the email short. I usually have a sentence
explaining each set short sequence of doctest assertions that do
something and then inspect the result.
When I have utility functions that I want to explain independently,
then I simply create one section/chapter per function.
Right, but test_foo.py is never about documentation, it's about isolated
unit tests.
Marius Gedminas
--
I noticed that Open Source proponents using MacOS X have developed highly tuned
excuses, similar to those that smokers have about why cigarettes are good for
you.
-- Miguel de Icaza,
http://primates.ximian.com/~miguel/archive/2004/Aug-03.html
signature.asc
Description: Digital signature
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
On Sun, Jul 15, 2007 at 10:44:35AM -0400, Benji York wrote: I'm doing some work with doctest right now, and am considering how to make assertions about HTML/XML better. Fixing https://bugs.launchpad.net/zope3/+bug/126169 would make my life easier. Marius Gedminas -- Microsoft -- because God hates us. signature.asc Description: Digital signature ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
Marius Gedminas wrote: On Sun, Jul 15, 2007 at 10:44:35AM -0400, Benji York wrote: I'm doing some work with doctest right now, and am considering how to make assertions about HTML/XML better. Fixing https://bugs.launchpad.net/zope3/+bug/126169 would make my life easier. I wonder if that behavior is present in the mainline doctest (the one included in the Python standard library). If so, reporting the issue to the Python team would be appropriate. My desire is that zope.testing will stop including a forked doctest. -- Benji York Senior Software Engineer Zope Corporation ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
Marius Gedminas wrote: On Sat, Jul 14, 2007 at 03:30:22PM -0400, Benji York wrote: Digression: syntax highlighting the diffs helps immensely. Check out http://svn.zope.org/zope.testing/branches/colorized-output/ I'm very much looking forward to that branch being merged to the trunk. Merged. Yay! I'm already using it. :) I have a feature suggestion: it would be nice to have a switch to say colorize output, unless stdout isn't a terminal, so piping the output to a pager (or file) doesn't result in polluted output. There's a little complication: when you have test layers that don't support tearDown, some of the tests are run in a subprocess, where stdout isn't a terminal (it's a pipe), but all the output will be copied verbatim to the stdout of the parent process (which may or may not be a terminal). The test runner could look at the top level stdout and pass the information to subprocesses. It's not that hard to remove the -c flag when you're adding |less to the command line. Or you could use |less -R and have colourful and scrollable output. It'd be nice to have a -C option that disables -c for when your test runner has -c included in the default options (as I intend to do with mine). -- Benji York Senior Software Engineer Zope Corporation ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
On Fri, Jul 13, 2007 at 02:03:04PM -0400, Jim Fulton wrote: Of course, I'm a big fan of doctest. Not all tests are documentation though, even if they are written as doctest. I'm happy with what we've done. We're making good incremental progress. I think though that many of our doctests that aspire to be documentation are actually not good documentation. IMO, we need to separate tests into 2 classes: executable documentation and tests. +infinity Absolutely! Trying to reach two unrelated goals (comprehensive tests + human-friendly documentation) with one file is just too hard, if not impossible. The executable documentation needs to be **much more readable than it is now**. FWIW, here's a very good example of executable documentation: https://storm.canonical.com/Tutorial Marius Gedminas -- We have enough youth, how about a fountain of SMART? signature.asc Description: Digital signature ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
On Fri, Jul 13, 2007 at 11:09:30PM +0200, Wichert Akkerman wrote:
Previously Tres Seaver wrote:
Stephan Richter wrote:
I think in the long term it will be most beneficial, if we convert all
tests
to doctests; then a reasonable on-line documentation is not that hard to
provide.
- -1. Good tests don't always make good documentation; I prefer the
isolation of traditional unittests for anything other than main line
use cases, for which doctests are best suited.
Amen. I find failing doctests to be much harder to debug as well. I use
doctests as a method to make sure examples in my documentation are
correct, which is very useful.
Doctests are hard to get right. I've finally settled on classifying my
tests into four categories and using different styles for them:
- API documentation: human readability is the primary concern, doctests
are in there just to make sure the documentation stays up to date.
These are .txt files.
- Short usage examples: sometimes it's simpler to show an example than
to describe the function in words:
def parse_date(date_string):
Parses an ISO-8601 date.
parse_date('2007-07-14')
datetime.date(2007, 7, 14)
This is the only case when I allow doctests in code modules.
Putting long test suites in class/function docstrings clutters the
code and makes it harder to read.
- Unit tests: there are many of those, they're independent (thus a
single .txt for a collection of tests is a Bad Idea), they're short
(so understanding and debugging is easy) and expressive. I put
those into .py files full with functions that look like
def doctest_FooClass_does_this():
Test that FooClass is able to ...
foo = FooClass()
results = foo.do_this()
for fruit, score, comments in results:
... print fruit.ljust(10), '|', score.ljust(5), '|',
comments
Orange | 9 | Tastes good, a bit sour
Apple | 8 | Varies
and have a traditional test_suite() function at the end that returns
a DocTestSuite with the appropriate setUp/tearDown/optionflags.
In effect this is a more or less direct translation of the
traditional unittest tests. I find that rewriting the assertions
into doctest format helps me make the tests more readable. Compare
the above with
class TestFooClass(unittest.TestCase):
def test_does_this(self):
foo = FooClass()
results = foo.do_this()
self.assertEquals(results,
[('Orange', 9, 'Tastes good, a bit sour'),
('Apple', 8, 'Varies')])
and especially compare the output you get when the test fails.
- Functional tests: these are .txt files that use zope.testbrowser and
are the hardest to debug. There ought to be a better way to make
assertions about HTML output than using ELLIPSIS and then pulling
your hair out looking at huge and incomprehensible diffs.
Digression: syntax highlighting the diffs helps immensely.
Check out http://svn.zope.org/zope.testing/branches/colorized-output/
Another digression: this is why I want Zope 3 to run on Python 2.5.
I want to make XPath queries on the HTML, and I hope I'll be
able to do that with cElementTree.
Marius Gedminas
--
Added mysterious, undocumented --scanflags and --fuzzy options.
-- nmap 3.0 announcement
signature.asc
Description: Digital signature
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
On Sat, Jul 14, 2007 at 11:24:36AM +0300, Marius Gedminas wrote: Digression: syntax highlighting the diffs helps immensely. Check out http://svn.zope.org/zope.testing/branches/colorized-output/ A picture is better than five hundred lines of code: http://mg.pov.lt/blog/europython-2007-sprints-2.html Marius Gedminas -- An algorithm must be seen to be believed. -- D.E. Knuth signature.asc Description: Digital signature ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
On Saturday 14 July 2007 04:05, Marius Gedminas wrote: Absolutely! Trying to reach two unrelated goals (comprehensive tests + human-friendly documentation) with one file is just too hard, if not impossible. While it cannot be done in one file, I think it can be done in one style of writing. I have found that modules do not just split up in logical units, but also in usage. I tend to write one text file per module. Thus, naturally, some will read more like usage instructions and others like API documentation. Another good method is to write a simple example first explaining the most common usage and dive into the special cases later on. Of course, this style of writing is common in introductory science/engineering books and is nothing new. For functional tests I use a somewhat different approach, writing one text file per user and task, and name it something like admin-createsite.txt. BTW, I think the Storm tutorial is okay, but not exceptionally good. At the beginning it lacks introduction of what storm is and what its goals are. While a specific example is used in the tutorial all the writing is done generically talking about programming concepts. This is like talking about the gravitational force in physics and use a flying canon ball as an example. Something that attracts me is the choice of small sections/chapters. Regards, Stephan -- Stephan Richter CBU Physics Chemistry (B.S.) / Tufts Physics (Ph.D. student) Web2k - Web Software Design, Development and Training ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
Previously Marius Gedminas wrote: - Unit tests: there are many of those, they're independent (thus a single .txt for a collection of tests is a Bad Idea), they're short (so understanding and debugging is easy) and expressive. I put those into .py files full with functions that look like def doctest_FooClass_does_this(): Test that FooClass is able to ... foo = FooClass() results = foo.do_this() for fruit, score, comments in results: ... print fruit.ljust(10), '|', score.ljust(5), '|', comments Orange | 9 | Tastes good, a bit sour Apple | 8 | Varies and have a traditional test_suite() function at the end that returns a DocTestSuite with the appropriate setUp/tearDown/optionflags. Until you have to step through the test with pdb, at which point it becomes very painful. Wichert. -- Wichert Akkerman [EMAIL PROTECTED]It is simple to make things. http://www.wiggy.net/ It is hard to make things simple. ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
Marius Gedminas wrote: - Functional tests: these are .txt files that use zope.testbrowser and are the hardest to debug. There ought to be a better way to make assertions about HTML output than using ELLIPSIS and then pulling your hair out looking at huge and incomprehensible diffs. Yep, assertions about HTML (or XML) are difficult to do with plain text. One option is to feed browser.contents to your favorite HTML (XML) parser. Digression: syntax highlighting the diffs helps immensely. Check out http://svn.zope.org/zope.testing/branches/colorized-output/ I'm very much looking forward to that branch being merged to the trunk. I have a feature suggestion: it would be nice to have a switch to say colorize output, unless stdout isn't a terminal, so piping the output to a pager (or file) doesn't result in polluted output. -- Benji York Senior Software Engineer Zope Corporation ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
On Sat, Jul 14, 2007 at 03:30:22PM -0400, Benji York wrote: Digression: syntax highlighting the diffs helps immensely. Check out http://svn.zope.org/zope.testing/branches/colorized-output/ I'm very much looking forward to that branch being merged to the trunk. Merged. I have a feature suggestion: it would be nice to have a switch to say colorize output, unless stdout isn't a terminal, so piping the output to a pager (or file) doesn't result in polluted output. There's a little complication: when you have test layers that don't support tearDown, some of the tests are run in a subprocess, where stdout isn't a terminal (it's a pipe), but all the output will be copied verbatim to the stdout of the parent process (which may or may not be a terminal). It's not that hard to remove the -c flag when you're adding |less to the command line. Or you could use |less -R and have colourful and scrollable output. Marius Gedminas -- Nothing ever goes missing that they don't look at me, ever since that time I lost my horse. As if that could be helped. He was white and it was snowing, what did they expect? -- Dolorous Edd in A Storm of Swords by George R. R. Martin signature.asc Description: Digital signature ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
On Jul 13, 2007, at 9:25 AM, Philipp von Weitershausen wrote: Jim Fulton wrote: On Jul 13, 2007, at 6:57 AM, Jim Fulton wrote: * zope.interface * zope.security * zope.app.container * zope.hookable * zope.i18nmessageid Could you or someone else make final source releases of these first? I expect that some of these haven't changed since Zope 3.3. We should not make new releases of eggs if they haven't changed. One of the great things about eggs is that we can stop releasing non-changes. :) In the short term, I'll go ahead and make windows eggs for the packages that have latest source distros. I take that back. It looks like it's going to take more time than I have to figure out what releases to make. There are various versions floating around. Yes, I noticed that too. I think the current situtation is way too confusing. We should decide which the authoritative source for the eggs is, the CheeseShop or http://download.zope.org/distribution. The advantage of the latter is that everybody with checkin rights can release a new egg, whereas on the CheeseShop it takes access rights. Once we reach steady state, I'd like to see everything in the cheese shop. Unfortunately, I hate crapping poorly packaged eggs there. : ( I'm not sure what to do about that given the time availability of current volunteers. It would be great if people who had time and were looking for easy projects would adopt some packages and make sure they are packaged well, especially with good overview information and on-line documentation. I don't have much time for this in the short term, although I'll certainly chip away at it in the long term. Please either: Point me at an existing source release, and I'll be happy to generate corresponding windows eggs. I made windows eggs for the latest version of zope.interface that's in pypi. Great. So we have zope.interface and zope.proxy and there'll be no need for zope.thread. Which leaves us with: http://download.zope.org/distribution/zope.security-3.4.0b2.tar.gz http://download.zope.org/distribution/ zope.app.container-3.5.0a1.tar.gz http://download.zope.org/distribution/zope.hookable-3.4.0a1.tar.gz http://download.zope.org/distribution/ zope.i18nmessageid-3.4.0a1.tar.gz I'll make Python 2.4 windows eggs today and put them there. I realize that those aren't final releases, but they (most probably) haven't changed significantly after these releases were made, which would make it a waste of time if I had to tag and tarball them just for the sake of a different version ID. We really need to get these to final. Most of our packages are stable and unchanging. Once we get them to final, we'll be able to mostly forget about them. Jim -- Jim Fulton mailto:[EMAIL PROTECTED]Python Powered! CTO (540) 361-1714 http://www.python.org Zope Corporationhttp://www.zope.com http://www.zope.org ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
On Friday 13 July 2007 11:23, Jim Fulton wrote: Once we reach steady state, I'd like to see everything in the cheese shop. Unfortunately, I hate crapping poorly packaged eggs there. : ( I'm not sure what to do about that given the time availability of current volunteers. It would be great if people who had time and were looking for easy projects would adopt some packages and make sure they are packaged well, especially with good overview information and on-line documentation. I don't have much time for this in the short term, although I'll certainly chip away at it in the long term. What does a good package contain? I have tried hard to follow the example of the existing packages, but are they good? I think we need to develop some guidelines first, before we can ask people to do the work. Regards, Stephan -- Stephan Richter CBU Physics Chemistry (B.S.) / Tufts Physics (Ph.D. student) Web2k - Web Software Design, Development and Training ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
On Jul 13, 2007, at 11:31 AM, Stephan Richter wrote: On Friday 13 July 2007 11:23, Jim Fulton wrote: Once we reach steady state, I'd like to see everything in the cheese shop. Unfortunately, I hate crapping poorly packaged eggs there. : ( I'm not sure what to do about that given the time availability of current volunteers. It would be great if people who had time and were looking for easy projects would adopt some packages and make sure they are packaged well, especially with good overview information and on-line documentation. I don't have much time for this in the short term, although I'll certainly chip away at it in the long term. What does a good package contain? I have tried hard to follow the example of the existing packages, but are they good? I think we need to develop some guidelines first, before we can ask people to do the work. Fair enough. We're still learning, but IMO, a could release should have: - a good overview, and preferably - on-line documentation Of course, the standard meta data should be filed in to a reasonable degree. Mainly what I'm looking for is a good faith effort. For example, IMO, zope.proxy is inadequate: http://www.python.org/pypi/zope.proxy/3.4.0 I released it anyway because it is a dependency of ZODB, but I wasn't happy. I really want to go bask and provide some basic documentation. We have soo much work to do on packaging. Oh well, we'll get their eventually. Jim -- Jim Fulton mailto:[EMAIL PROTECTED]Python Powered! CTO (540) 361-1714 http://www.python.org Zope Corporationhttp://www.zope.com http://www.zope.org ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
On Friday 13 July 2007 12:14, Jim Fulton wrote: IMO, a could release should have: - a good overview, and preferably - on-line documentation Right, I think this is well-served for packages that have doctests. I think that your example of including the dotest files into the long description is a good thing. However, I have noticed some problems with regard to PyPI: 1. It does not support unicode. I had some problems with characters before, but I cannot remember the details. 2. The PyPI website does not encode the long description, causing text with HTML to not display correctly. I have avoided this problem by escaping the long description myself, but then you loose the REST conversion. (See z3c.form.) Of course, the standard meta data should be filed in to a reasonable degree. Okay, I think most of the packages provide a lot of the info with exception of the Trove classifiers. They are very important for marketing reasons, because the PyPI Package browser (http://cheeseshop.python.org/pypi?%3Aaction=browse) recognizes them and uses them to organize the packages. I think it would be awesome, if it would say: Zope 3 (300 [packages]). OT: Did you notice that 17 out of 20 package updates today where Zope-related? :-) Mainly what I'm looking for is a good faith effort. I think in the long term it will be most beneficial, if we convert all tests to doctests; then a reasonable on-line documentation is not that hard to provide. Regards, Stephan -- Stephan Richter CBU Physics Chemistry (B.S.) / Tufts Physics (Ph.D. student) Web2k - Web Software Design, Development and Training ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
On Jul 13, 2007, at 11:38 AM, Philipp von Weitershausen wrote: I'm not sure what to do about that given the time availability of current volunteers. I would happily upload properly released stuff to the CheeseShop if I had access. Somebody thought I wanted to own pretty much everything -- so I do. If you want access to something, just ask. Seriously, I was hoping someone else would step forward. This is a task that is good for someone without deep knowledge and who wants to contribute. Please either: Point me at an existing source release, and I'll be happy to generate corresponding windows eggs. I made windows eggs for the latest version of zope.interface that's in pypi. Great. So we have zope.interface and zope.proxy and there'll be no need for zope.thread. Which leaves us with: http://download.zope.org/distribution/zope.security-3.4.0b2.tar.gz http://download.zope.org/distribution/ zope.app.container-3.5.0a1.tar.gz http://download.zope.org/distribution/zope.hookable-3.4.0a1.tar.gz http://download.zope.org/distribution/ zope.i18nmessageid-3.4.0a1.tar.gz I'll make Python 2.4 windows eggs today and put them there. Awesome. Thanks! If all I have to d is drive windows, this is very easy for me. I just have to download, untar, and execute a single command per python versions that creates the egg and uploads to PyPI. Jim -- Jim Fulton mailto:[EMAIL PROTECTED]Python Powered! CTO (540) 361-1714 http://www.python.org Zope Corporationhttp://www.zope.com http://www.zope.org ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
On Jul 13, 2007, at 1:14 PM, Stephan Richter wrote: On Friday 13 July 2007 12:14, Jim Fulton wrote: IMO, a could release should have: - a good overview, and preferably - on-line documentation Right, I think this is well-served for packages that have doctests. I think that your example of including the dotest files into the long description is a good thing. I need to get better though on making sure it is truly documentation and not just test. For example, I think it would be better if the online buildout documentation was easier to use. However, I have noticed some problems with regard to PyPI: 1. It does not support unicode. I had some problems with characters before, but I cannot remember the details. 2. The PyPI website does not encode the long description, causing text with HTML to not display correctly. I have avoided this problem by escaping the long description myself, but then you loose the REST conversion. (See z3c.form.) What I've doe with PyPI is a nice hack -- no more. It would be nice if some tool made it easy to maintain project home pages. I might like something better, but I can live with the hack for now. :) Of course, the standard meta data should be filed in to a reasonable degree. Okay, I think most of the packages provide a lot of the info with exception of the Trove classifiers. They are very important for marketing reasons, because the PyPI Package browser (http://cheeseshop.python.org/pypi?% 3Aaction=browse) recognizes them and uses them to organize the packages. I think it would be awesome, if it would say: Zope 3 (300 [packages]). Yup OT: Did you notice that 17 out of 20 package updates today where Zope-related? :-) :) And Zope dependent. :/ Mainly what I'm looking for is a good faith effort. I think in the long term it will be most beneficial, if we convert all tests to doctests; then a reasonable on-line documentation is not that hard to provide. Of course, I'm a big fan of doctest. Not all tests are documentation though, even if they are written as doctest. I'm happy with what we've done. We're making good incremental progress. I think though that many of our doctests that aspire to be documentation are actually not good documentation. IMO, we need to separate tests into 2 classes: executable documentation and tests. The executable documentation needs to be **much more readable than it is now**. I need to start using the footnote feature that Benji and Gary added. I suspect that that would help. Jim -- Jim Fulton mailto:[EMAIL PROTECTED]Python Powered! CTO (540) 361-1714 http://www.python.org Zope Corporationhttp://www.zope.com http://www.zope.org ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
Re: [Zope3-dev] Re: Windows eggs
Previously Tres Seaver wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Stephan Richter wrote: On Friday 13 July 2007 12:14, Jim Fulton wrote: IMO, a could release should have: - a good overview, and preferably - on-line documentation Right, I think this is well-served for packages that have doctests. I think that your example of including the dotest files into the long description is a good thing. However, I have noticed some problems with regard to PyPI: 1. It does not support unicode. I had some problems with characters before, but I cannot remember the details. 2. The PyPI website does not encode the long description, causing text with HTML to not display correctly. I have avoided this problem by escaping the long description myself, but then you loose the REST conversion. (See z3c.form.) Of course, the standard meta data should be filed in to a reasonable degree. Okay, I think most of the packages provide a lot of the info with exception of the Trove classifiers. They are very important for marketing reasons, because the PyPI Package browser (http://cheeseshop.python.org/pypi?%3Aaction=browse) recognizes them and uses them to organize the packages. I think it would be awesome, if it would say: Zope 3 (300 [packages]). OT: Did you notice that 17 out of 20 package updates today where Zope-related? :-) Mainly what I'm looking for is a good faith effort. I think in the long term it will be most beneficial, if we convert all tests to doctests; then a reasonable on-line documentation is not that hard to provide. - -1. Good tests don't always make good documentation; I prefer the isolation of traditional unittests for anything other than main line use cases, for which doctests are best suited. Amen. I find failing doctests to be much harder to debug as well. I use doctests as a method to make sure examples in my documentation are correct, which is very useful. Wichert. -- Wichert Akkerman [EMAIL PROTECTED]It is simple to make things. http://www.wiggy.net/ It is hard to make things simple. ___ Zope3-dev mailing list Zope3-dev@zope.org Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
