Tony J Ibbs (Tibs)
Thu, 22 Mar 2001 11:04:06 -0000
Edward Welbourne wrote:
> A test case should be written to actually run
> for real; a python block should just be illustrating use of
> the code and
> might, indeed, be deliberately broken, e.g. as an accompaniment to the
> explanation of why something is done the slightly odd way it
> is, so that
> maintainers will realise what would go horribly wrong if hey made the
> obvious `improvement'.
You really should read the doctest documentation (see the chapter in the
2.1 docs for the best intro) - it *will* test broken examples as well
> Equally, plenty of the tools I write are intended to be used
> from within
> the implementations of other tools; having a test system `run' the
> illustrations I'd want to supply is pointless - e.g.::
> class selfRepresenting:
> def _emit(self, *bits):
> """Representation support method.
> for example:
> def __repr__(self):
> return self._emit(`self.state`,
> 'name=' + `self.name`)
> return (_fullname(self.__class__) + '(' +
> string.joinfields(bits, ', ') + ')')
> in which the illustration only gives the __repr__ method of a class
> implicitly inheriting from selfRepresenting.
But as you've presented it, that wouldn't naturally be presented as an
interatice session at all - one wouldn't write it as::
>>> def __repr__(self):
and so on
but rather as::
and so on
That's *why* the chosen "start of Python paragraph" thing is '>>>' -
because it *is* what it looks like.
Anwyay, we probably aren't disagreeing - the "job" of the '>>>'
paragraph is well delimited (and was introduced as an idea last time
round the Doc-SIG loop, of course), and it is not the same as the job of
the '::' paragraph.
Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)