Is there a doctest mailing list? I couldn't find it. I'm try to use doctest to verify my docs (imagine that!) but I'm having trouble with the one that uses pickle (imagine that!). Any advice on how to make it work? Here's the excerpt: =============================================================================== Pickling -------- Enumerations can be pickled and unpickled:: >>> from enum import Enum >>> class Fruit(Enum): ... tomato = 1 ... banana = 2 ... cherry = 3 ... >>> from pickle import dumps, loads >>> Fruit.tomato is loads(dumps(Fruit.tomato)) True The usual restrictions for pickling apply: picklable enums must be defined in the top level of a module, since unpickling requires them to be importable from that module. =============================================================================== Oh, and I just realized this is probably why the flufl.enum docs import from a preexisting module instead of creating a new class on the spot. Still, it would be nice if this could work. Any ideas? -- ~Ethan~
On 6/7/13, Ethan Furman <ethan@stoneleaf.us> wrote:
Is there a doctest mailing list? I couldn't find it.
JFTR, Testing-in-Python (TiP) ML should be the right target for general purpose questions about testing, considering docs even for unittest and doctest http://lists.idyll.org/listinfo/testing-in-python [...]
Any advice on how to make it work?
Here's the excerpt:
=============================================================================== Pickling --------
Enumerations can be pickled and unpickled::
>>> from enum import Enum >>> class Fruit(Enum): ... tomato = 1 ... banana = 2 ... cherry = 3 ... >>> from pickle import dumps, loads >>> Fruit.tomato is loads(dumps(Fruit.tomato)) True
... but it seems I'm still getting in tests an instance of Fruit after invoking loads (do you ?) [...] -- Regards, Olemis. Apache™ Bloodhound contributor http://issues.apache.org/bloodhound Blog ES: http://simelo-es.blogspot.com/ Blog EN: http://simelo-en.blogspot.com/ Featured article:
On 06/07/2013 09:54 AM, Olemis Lang wrote:
On 6/7/13, Ethan Furman <ethan@stoneleaf.us> wrote:
Is there a doctest mailing list? I couldn't find it.
JFTR, Testing-in-Python (TiP) ML should be the right target for general purpose questions about testing, considering docs even for unittest and doctest http://lists.idyll.org/listinfo/testing-in-python
Cool, thanks.
[...]
Any advice on how to make it work?
Here's the excerpt:
=============================================================================== Pickling --------
Enumerations can be pickled and unpickled::
>>> from enum import Enum >>> class Fruit(Enum): ... tomato = 1 ... banana = 2 ... cherry = 3 ... >>> from pickle import dumps, loads >>> Fruit.tomato is loads(dumps(Fruit.tomato)) True
... but it seems I'm still getting in tests an instance of Fruit after invoking loads (do you ?)
I'm not sure what you mean by "an instance of Fruit" -- you should be getting an instance of Fruit; specifically the tomato instance. -- ~Ethan~
On Fri, Jun 7, 2013 at 10:50 AM, Mark Janssen <dreamingforward@gmail.com> wrote:
>>> from pickle import dumps, loads >>> Fruit.tomato is loads(dumps(Fruit.tomato)) True
Why are you using is here instead of ==? You're making a circular loop using "is"
I should add that when you're serializing with pickle and then reloading, the objects should be seen as "essentially equivalent". This means that they are either byte-by-byte equivalent (not sure actually if Python actually guarantees this), or every element would still compare equal and that is what matters. -- MarkJ Tacoma, Washington
On 06/07/2013 10:54 AM, Mark Janssen wrote:
On Fri, Jun 7, 2013 at 10:50 AM, Mark Janssen <dreamingforward@gmail.com> wrote:
>>> from pickle import dumps, loads >>> Fruit.tomato is loads(dumps(Fruit.tomato)) True
Why are you using is here instead of ==? You're making a circular loop using "is"
I should add that when you're serializing with pickle and then reloading, the objects should be seen as "essentially equivalent". This means that they are either byte-by-byte equivalent (not sure actually if Python actually guarantees this), or every element would still compare equal and that is what matters.
In most cases, sure. But one of the invariants of Enums is that there is only ever one of each member specifically so that `is` tests work. -- ~Ethan~
On Fri, 07 Jun 2013 10:54:57 -0700, Mark Janssen <dreamingforward@gmail.com> wrote:
On Fri, Jun 7, 2013 at 10:50 AM, Mark Janssen <dreamingforward@gmail.com> wrote:
>>> from pickle import dumps, loads >>> Fruit.tomato is loads(dumps(Fruit.tomato)) True
Why are you using is here instead of ==? You're making a circular loop using "is"
I should add that when you're serializing with pickle and then reloading, the objects should be seen as "essentially equivalent". This means that they are either byte-by-byte equivalent (not sure actually if Python actually guarantees this), or every element would still compare equal and that is what matters.
Enums are supposed to be singletons, though, so the 'is' test is exactly the point of this test. --David
On Fri, Jun 7, 2013 at 1:54 PM, Mark Janssen <dreamingforward@gmail.com> wrote:
On Fri, Jun 7, 2013 at 10:50 AM, Mark Janssen <dreamingforward@gmail.com> wrote:
>>> from pickle import dumps, loads >>> Fruit.tomato is loads(dumps(Fruit.tomato)) True
Why are you using is here instead of ==? You're making a circular loop using "is"
I should add that when you're serializing with pickle and then reloading, the objects should be seen as "essentially equivalent". This means that they are either byte-by-byte equivalent (not sure actually if Python actually guarantees this), or every element would still compare equal and that is what matters.
For global objects such as functions and classes -- and singletons such as None, Ellipsis, True, and False -- pickling and unpickling is actually supposed to retain the "is" relationship as well. I don't know if enums *actually* preserve this invariant, but my default expectation of the One Obvious Way would be that enums, being uniquely-named objects that know their name and container, should be considered global objects in the same fashion as classes and functions, *and* that as singletons, they'd also be treated in the same way as None, Ellipsis, etc. That is, there are two independent precedents for objects like that preserving "is" upon pickling and unpickling. (As another precedent, my own SymbolType library (available on PyPI) preserves the "is"-ness of its named symbol objects upon pickling and unpickling.)
On Jun 07, 2013, at 02:30 PM, PJ Eby wrote:
I don't know if enums *actually* preserve this invariant, but my default expectation of the One Obvious Way would be that enums, being uniquely-named objects that know their name and container, should be considered global objects in the same fashion as classes and functions, *and* that as singletons, they'd also be treated in the same way as None, Ellipsis, etc. That is, there are two independent precedents for objects like that preserving "is" upon pickling and unpickling.
This is certainly how I thought of them in flufl.enum, and indeed the `is` test in my own test suite proves that it works. -Barry
On 06/07/2013 10:50 AM, Mark Janssen wrote:
>>> from pickle import dumps, loads >>> Fruit.tomato is loads(dumps(Fruit.tomato)) True
Why are you using is here instead of ==?
I'm using `is` because I'm verifying that the instance returned by `pickle.loads` is the exact same object as the instance fed into `pickle.dumps`. Enum members should be singletons.
You're making a circular loop using "is"
Huh? -- ~Ethan~
Why are you using is here instead of ==?
I'm using `is` because I'm verifying that the instance returned by `pickle.loads` is the exact same object as the instance fed into `pickle.dumps`. Enum members should be singletons.
I see now. That makes sense, but I don't think you'll be able to do that. "Supposed to be singletons" while at the same time you are holding two instances on the interpreter line. How are you going to manage that? -- MarkJ Tacoma, Washington
Ethan Furman writes:
Enumerations can be pickled and unpickled::
>>> from enum import Enum >>> class Fruit(Enum): ... tomato = 1 ... banana = 2 ... cherry = 3 ... >>> from pickle import dumps, loads >>> Fruit.tomato is loads(dumps(Fruit.tomato)) True [...] Still, it would be nice if this could work.
Well, you could cheat and reverse the test. ;-) I assume the problem is that loads proceeds to recreate the Fruit enum, rather than checking if there already is one? Maybe the metaclass can check somehow? At the very least, if this can't work in this implementation, unpickling should be an error.
On 08/06/13 15:18, Stephen J. Turnbull wrote:
Ethan Furman writes:
Enumerations can be pickled and unpickled::
>>> from enum import Enum >>> class Fruit(Enum): ... tomato = 1 ... banana = 2 ... cherry = 3 ... >>> from pickle import dumps, loads >>> Fruit.tomato is loads(dumps(Fruit.tomato)) True [...] Still, it would be nice if this could work.
Well, you could cheat and reverse the test. ;-)
I assume the problem is that loads proceeds to recreate the Fruit enum, rather than checking if there already is one?
I don't believe so. I understand that the problem is that pickle cannot find the Fruit enum in the __main__ module. Untested, but adding this before the call to dumps might work: import __main__ __main__.Fruit = Fruit although that's the sort of thing that makes me think it's time to turn this into a unittest rather than a doctest. -- Steven
On 06/07/2013 11:45 PM, Steven D'Aprano wrote:
On 08/06/13 15:18, Stephen J. Turnbull wrote:
Ethan Furman writes:
Enumerations can be pickled and unpickled::
>>> from enum import Enum >>> class Fruit(Enum): ... tomato = 1 ... banana = 2 ... cherry = 3 ... >>> from pickle import dumps, loads >>> Fruit.tomato is loads(dumps(Fruit.tomato)) True [...] Still, it would be nice if this could work.
Well, you could cheat and reverse the test. ;-)
I assume the problem is that loads proceeds to recreate the Fruit enum, rather than checking if there already is one?
I don't believe so. I understand that the problem is that pickle cannot find the Fruit enum in the __main__ module.
Untested, but adding this before the call to dumps might work:
import __main__ __main__.Fruit = Fruit
although that's the sort of thing that makes me think it's time to turn this into a unittest rather than a doctest.
Indeed, and it is already in several different ways. But it would be nice to have a pickle example in the docs that worked with doctest. I ended up doing what Barry did: >>> from test.test_enum import Fruit >>> from pickle import dumps, loads >>> Fruit.tomato is loads(dumps(Fruit.tomato)) True -- ~Ethan~
08.06.13 10:03, Ethan Furman написав(ла):
Indeed, and it is already in several different ways. But it would be nice to have a pickle example in the docs that worked with doctest.
I ended up doing what Barry did:
>>> from test.test_enum import Fruit >>> from pickle import dumps, loads >>> Fruit.tomato is loads(dumps(Fruit.tomato)) True
I think that the documentation is there for people. If you need tests, add them separately, but the documentation should be clear and understandable. In this case it is better to exclude a code example from doctests or add auxiliary code (i.e. as Steven suggested) to pass the doctest.
On 06/08/2013 01:07 AM, Serhiy Storchaka wrote:
08.06.13 10:03, Ethan Furman написав(ла):
Indeed, and it is already in several different ways. But it would be nice to have a pickle example in the docs that worked with doctest.
I ended up doing what Barry did:
>>> from test.test_enum import Fruit >>> from pickle import dumps, loads >>> Fruit.tomato is loads(dumps(Fruit.tomato)) True
I think that the documentation is there for people.
I agree.
If you need tests, add them separately,
I have.
but the documentation should be clear and understandable.
And the example code should be testable.
In this case it is better to exclude a code example from doctests or add auxiliary code (i.e. as Steven suggested) to pass the doctest.
Are you saying there is something wrong about what I have in place now? I would think that one line showing something you might actually do (importing an Enum from another module) is better than two lines showing esoteric workarounds (importing __main__ and setting an attribute on it). Apologies if I sound gruff -- it's way past my bedtime. In fact, I'll think I'll go sleep now. :) -- ~Ethan~
08.06.13 11:47, Ethan Furman написав(ла):
In this case it is better to exclude a code example from doctests or add auxiliary code (i.e. as Steven suggested) to pass the doctest.
Are you saying there is something wrong about what I have in place now? I would think that one line showing something you might actually do (importing an Enum from another module) is better than two lines showing esoteric workarounds (importing __main__ and setting an attribute on it).
test.test_enum is not here. The reader should look into the external test module (which may not be supplied along with the module and documentation) to understand the example. Or rely on assumptions. Is it possible to add "invisible" code which doesn't displayed in the resulting documentation, but taken into account by doctest?
On 06/08/2013 03:09 AM, Serhiy Storchaka wrote:
08.06.13 11:47, Ethan Furman написав(ла):
In this case it is better to exclude a code example from doctests or add auxiliary code (i.e. as Steven suggested) to pass the doctest.
Are you saying there is something wrong about what I have in place now? I would think that one line showing something you might actually do (importing an Enum from another module) is better than two lines showing esoteric workarounds (importing __main__ and setting an attribute on it).
test.test_enum is not here. The reader should look into the external test module (which may not be supplied along with the module and documentation) to understand the example. Or rely on assumptions.
Fair point. But I suppose that if the end-user is running a doc test, it is not too much to require that the other tests be installed as well. Plus, we definitely have the other tests. :)
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. -- ~Ethan~
On 6/8/13, Ethan Furman <ethan@stoneleaf.us> wrote:
On 06/08/2013 03:09 AM, Serhiy Storchaka wrote:
08.06.13 11:47, Ethan Furman написав(ла): [...]
Fair point. But I suppose that if the end-user is running a doc test, it is not too much to require that the other tests be installed as well. Plus, we definitely have the other tests. :)
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.
<ot> No ... if using doctest . To get such things done you'll need something like dutest [1]_ [2]_ , but that's not an option for testing docs in stdlib . </ot> .. [1] dutest @ PyPI (https://pypi.python.org/pypi/dutest) .. [2] Purpose of Doctests [Was: Best practices for Enum] (http://goo.gl/F7Afy) -- Regards, Olemis. Apache™ Bloodhound contributor http://issues.apache.org/bloodhound Blog ES: http://simelo-es.blogspot.com/ Blog EN: http://simelo-en.blogspot.com/ Featured article:
On 8 June 2013 17:41, Ethan Furman <ethan@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. [1]: http://sphinx-doc.org/ext/doctest.html -- Łukasz Rekucki
On Sat, 08 Jun 2013 19:54:18 +0200, =?UTF-8?Q?=C5=81ukasz_Rekucki?= <lrekucki@gmail.com> wrote:
On 8 June 2013 17:41, Ethan Furman <ethan@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. --David
On 9 June 2013 04:17, R. David Murray <rdmurray@bitdance.com> wrote:
On Sat, 08 Jun 2013 19:54:18 +0200, =?UTF-8?Q?=C5=81ukasz_Rekucki?= <lrekucki@gmail.com> wrote:
On 8 June 2013 17:41, Ethan Furman <ethan@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@gmail.com | Brisbane, Australia
On 06/08/2013 09:21 PM, Nick Coghlan wrote:
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.
Good point. I'll keep that in mind. -- ~Ethan~
participants (11)
-
Barry Warsaw -
Ethan Furman -
Mark Janssen -
Nick Coghlan -
Olemis Lang -
PJ Eby -
R. David Murray -
Serhiy Storchaka -
Stephen J. Turnbull -
Steven D'Aprano -
Łukasz Rekucki