[Python-Dev] doctest and pickle

[Nick Coghlan]

On 9 June 2013 04:17, R. David Murray <rdmurray at bitdance.com> wrote:
> On Sat, 08 Jun 2013 19:54:18 +0200, =?UTF-8?Q?=C5=81ukasz_Rekucki?= <lrekucki at gmail.com> wrote:
>> On 8 June 2013 17:41, Ethan Furman <ethan at stoneleaf.us> wrote:
>> > On 06/08/2013 03:09 AM, Serhiy Storchaka wrote:
>> >>
>> >> Is it possible to add "invisible" code which doesn't displayed in the
>> >> resulting documentation, but taken into account by
>> >> doctest?
>> >
>> >
>> > I have no idea.  This is my first time using doctest.
>> >
>>
>> AFAIK, stdlib uses Sphinx, so you can provide a testsetup block[1]. At
>> least if you're running them via Sphinx.
>
> Running the doctests via Sphinx is still, I believe a Future Objective :).
> I think we are getting close to being able to do that, though.  (Well,
> you already can for Python2; but not, I think, for Python3).
>
> If the test module from which you are importing is short, you could use
> the Sphinx literalinclude directive to include the contents of the file
> in the docs just before you show the 'is' example.  You could also explain
> (briefly) *why* it is necessary to use an imported class for this example,
> which IMO is useful information.

Right - for the singleton behaviour of enums to be honoured by pickle,
the enum definition *must* be reachable through the import system
based on its __name__ and __module__ attributes (PEP 3154 will
eventually change that limitation to __qualname__ and __module__). The
temporary namespaces created to run doctests generally aren't
reachable that way, so the unpickling either fails or creates a new
instance (depending on the details of the situation).

Using the test suite in the enum docstrings initially is fine. In the
future, once we migrate a module like socket to using enum.IntEnum
instead of bare integers, it would be appropriate to change the enum
docs to reference that rather than the test suite.

Cheers,
Nick.

--
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia