doctest and exposing internals.

[Neil Cerutti]

I'm using doctest for the first time, and boy is it cool.

But I'm nervous about exposing library internals in the
docstring.

def glk_cancel_char_event(win):
""" Cancel a pending request for character input.

win must be a valid Glk window.

>>> glk_cancel_char_event([])

Glk library error: cancel_char_event: invalid id

Here's an example of correct usuage.
False

For convenience, it's OK to call this function when a
character input request is not pending, in which case it has
no effect.
(0, 0)

"""

if win != glk_window.main:
_strict_warning("cancel_char_event: invalid id")
return
glk_window.main.char_request = False

The example of correct usage it what's wrong with the docstring.

There's no interface for checking if an event is queued in Glk,
so I resorted to exposing the internal state main.char_request in
the doc string. What are the alternatives?

In addition, the last test in the docstring is only there to
ensure that other tests can open a window themselves (this
version of the library only allows one window to be open at a
time).

 

[Gabriel Genellina]

The example of correct usage it what's wrong with the docstring.

There's no interface for checking if an event is queued in Glk,
so I resorted to exposing the internal state main.char_request in
the doc string. What are the alternatives?

- what you have done
- modify the interfase to allow that kind of checking
- use a standard unit test


--
Gabriel Genellina
Softlab SRL

__________________________________________________
Correo Yahoo!
Espacio para todos tus mensajes, antivirus y antispam ¡gratis!
¡Abrí tu cuenta ya! - http://correo.yahoo.com.ar

 

[Neil Cerutti]

- what you have done

I haven't fully absorbed soapbox section of the doctest manual;
it cautions against doing what I'm doing, i.e., trying to put
complete test coverage in my docstrings.

- modify the interfase to allow that kind of checking

Fortunately, I don't control the specification. ;-)

- use a standard unit test

I'm making some progress in removing the boilerplate from the
doctests by supplying globs to the testmod function.

Thanks for your suggestion.