Re: [sage-devel] Re: hiding doctest in documentation
On Thu, Jul 31, 2014 at 02:23:02PM -0700, Travis Scrimshaw wrote:
>... Just do ``sorted(d.items(), key=str)`` for doctests where the
>order could change (which usually is for dicts of size larger
>than 3).
An variant which I like is to use ``pprint``
sage: d = { 'b':1, 'a':3, 'c':5 }
sage: from pprint import pprint
sage: pprint(d)
{'a': 3, 'b': 1, 'c': 5}
Cheers,
Nicolas
--
Nicolas M. Thiéry "Isil"
http://Nicolas.Thiery.name/
--
You received this message because you are subscribed to the Google Groups
"sage-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to sage-devel+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.
Re: [sage-devel] Re: hiding doctest in documentation
On Jul 31, 2014 7:34 PM, "Volker Braun" wrote: > > I disagree with the whole idea that doctests should be deliberately fragile and break randomly on the buildbot to teach unwary developers a lesson. I very strongly agree with you. I was going to write but you said it better. > Either sort by keys, or disallow dictionary output altogether AND print a useful diagnostic in doctests. > > This whole discussion is similar to the recent ticket #16644 where unwary users get an incorrect and misleading error message from the category framework. Pushing newbies off a cliff like that does not result in interest for how the __getattr__ black magic works, it just steers people away from Sage. > > Coming back to the dictionary sort order. it is a CPython implementation detail that some keys are always sorted (e.g. small positive integers). In fact, this is used in a lot of doctests. > > > > On Thursday, July 31, 2014 5:23:03 PM UTC-4, Travis Scrimshaw wrote: >> >>I disagree with sorting the output of dicts. I ended up finding a very subtle bug dealing with dictionary output that I would have had a much harder time figuring out with the automatic sorting. Just do ``sorted(d.items(), key=str)`` for doctests where the order could change (which usually is for dicts of size larger than 3). >> >> Best, >> Travis >> >> >> On Thursday, July 31, 2014 9:14:30 AM UTC-7, Volker Braun wrote: >>> >>> This is now http://trac.sagemath.org/ticket/16746 >>> >>> On Thursday, July 31, 2014 11:23:14 AM UTC-4, Volker Braun wrote: The doctesting uses its own displayhook, though I thought it would also sort dicts (since it obviously helps with making doctests reproducable). IMHO we should add it... > > -- > You received this message because you are subscribed to the Google Groups "sage-devel" group. > To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. > To post to this group, send email to sage-devel@googlegroups.com. > Visit this group at http://groups.google.com/group/sage-devel. > For more options, visit https://groups.google.com/d/optout. -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at http://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
Re: [sage-devel] Re: hiding doctest in documentation
I disagree with the whole idea that doctests should be deliberately fragile and break randomly on the buildbot to teach unwary developers a lesson. Either sort by keys, or disallow dictionary output altogether AND print a useful diagnostic in doctests. This whole discussion is similar to the recent ticket #16644 where unwary users get an incorrect and misleading error message from the category framework. Pushing newbies off a cliff like that does not result in interest for how the __getattr__ black magic works, it just steers people away from Sage. Coming back to the dictionary sort order. it is a CPython implementation detail that some keys are always sorted (e.g. small positive integers). In fact, this is used in a lot of doctests. On Thursday, July 31, 2014 5:23:03 PM UTC-4, Travis Scrimshaw wrote: > >I disagree with sorting the output of dicts. I ended up finding a very > subtle bug dealing with dictionary output that I would have had a much > harder time figuring out with the automatic sorting. Just do > ``sorted(d.items(), key=str)`` for doctests where the order could change > (which usually is for dicts of size larger than 3). > > Best, > Travis > > > On Thursday, July 31, 2014 9:14:30 AM UTC-7, Volker Braun wrote: >> >> This is now http://trac.sagemath.org/ticket/16746 >> >> On Thursday, July 31, 2014 11:23:14 AM UTC-4, Volker Braun wrote: >>> >>> The doctesting uses its own displayhook, though I thought it would also >>> sort dicts (since it obviously helps with making doctests reproducable). >>> IMHO we should add it... >>> >> -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at http://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
Re: [sage-devel] Re: hiding doctest in documentation
On Thursday, July 31, 2014 2:23:03 PM UTC-7, Travis Scrimshaw wrote: > >I disagree with sorting the output of dicts. I ended up finding a very > subtle bug dealing with dictionary output that I would have had a much > harder time figuring out with the automatic sorting. Just do > ``sorted(d.items(), key=str)`` for doctests where the order could change > (which usually is for dicts of size larger than 3). > In any case we should ensure that doctesting and the command line behave similarly, so in all cases we should probably doctest through IPytthon's displayhook. It's just silly if one cannot paste (deterministic) output from the command line into a doctest and get a valid doctest. With that in mind, your point would have to be addressed by changing IPython's displayhook to not sort dictionaries. I think there's an argument to be made for that. If printing on the command line appears deterministic, a user might easily be led to believe that order is really there and, for instance, think that for a in D: if D[a]=="value": break else: raise ValueError will find the a with "value" as suggested by the print order (which in IPython can be wildly different from the iteration order of a dictionary). >From that point of view, IPython's sorting is a bit of a misfeature. However, when looking at a dict casually and inspecting whether a certain key occurs in the printout, having the output sorted (if possible) can be pretty convenient too. So I'm ambivalent towards retaining/turning off IPython's sorting prettyprinter. Given that it would be quite a bit of work to alter IPython's prettyprinter, I think that leads to accepting sorted pretty-printed dicts for now. -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at http://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
Re: [sage-devel] Re: hiding doctest in documentation
I disagree with sorting the output of dicts. I ended up finding a very subtle bug dealing with dictionary output that I would have had a much harder time figuring out with the automatic sorting. Just do ``sorted(d.items(), key=str)`` for doctests where the order could change (which usually is for dicts of size larger than 3). Best, Travis On Thursday, July 31, 2014 9:14:30 AM UTC-7, Volker Braun wrote: > > This is now http://trac.sagemath.org/ticket/16746 > > On Thursday, July 31, 2014 11:23:14 AM UTC-4, Volker Braun wrote: >> >> The doctesting uses its own displayhook, though I thought it would also >> sort dicts (since it obviously helps with making doctests reproducable). >> IMHO we should add it... >> > -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at http://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
Re: [sage-devel] Re: hiding doctest in documentation
This is now http://trac.sagemath.org/ticket/16746 On Thursday, July 31, 2014 11:23:14 AM UTC-4, Volker Braun wrote: > > The doctesting uses its own displayhook, though I thought it would also > sort dicts (since it obviously helps with making doctests reproducable). > IMHO we should add it... > -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at http://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
Re: [sage-devel] Re: hiding doctest in documentation
On Thursday, July 31, 2014 11:28:59 AM UTC-4, Nils Bruin wrote: > > not everything in python *can* be sorted. > Everything can be sorted, but not necessarily in a stable way ;-) -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at http://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
Re: [sage-devel] Re: hiding doctest in documentation
On Thursday, July 31, 2014 7:43:27 AM UTC-7, Daniel Krenn wrote:
>
> Am 2014-07-31 um 15:55 schrieb Volker Braun:
> > On Thursday, July 31, 2014 9:16:50 AM UTC-4, Daniel Krenn wrote:
> >
> > Does this mean it is guaranteed that in doctests dicts are always
> shown
> > with their keys sorted?
> >
> >
> > AFAIK: Yes, but only the top-level dict (no guarantees for nested
> > datastructures)
>
And it's only a best-effort attempt:
sage: ({200:2,30:4,'ddd':1,complex(1,2):2,complex(1,1):1,'':2,'b':3})
{'b': 3, (1+1j): 1, (1+2j): 2, 200: 2, '': 2, 30: 4, 'ddd': 1}
not everything in python *can* be sorted.
--
You received this message because you are subscribed to the Google Groups
"sage-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to sage-devel+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.
Re: [sage-devel] Re: hiding doctest in documentation
The doctesting uses its own displayhook, though I thought it would also
sort dicts (since it obviously helps with making doctests reproducable).
IMHO we should add it...
On Thursday, July 31, 2014 10:43:27 AM UTC-4, Daniel Krenn wrote:
>
> Am 2014-07-31 um 15:55 schrieb Volker Braun:
> > On Thursday, July 31, 2014 9:16:50 AM UTC-4, Daniel Krenn wrote:
> >
> > Does this mean it is guaranteed that in doctests dicts are always
> shown
> > with their keys sorted?
> >
> >
> > AFAIK: Yes, but only the top-level dict (no guarantees for nested
> > datastructures)
>
> The lines
>
> sage: d = {'a':23, 'b':34, 'au':56, 'bbf':234, 'aaa':234}
> sage: d
> {'a': 23, 'aaa': 234, 'au': 56, 'b': 34, 'bbf': 234}
>
> are the command line output. Doing this in a doctest (called by a simple
> Makefile) gives (among one other failing test):
>
> sage -t test-order.sage
> Running doctests with ID 2014-07-31-16-40-03-3683866f.
> Doctesting 1 file.
> sage -t test-order.sage
> **
> File "test-order.sage", line 8, in test-order
> Failed example:
> d
> Expected:
> {'a': 23, 'aaa': 234, 'au': 56, 'b': 34, 'bbf': 234}
> Got:
> {'a': 23, 'bbf': 234, 'aaa': 234, 'b': 34, 'au': 56}
> **
> 1 item had failures:
>2 of 5 in test-order
> [4 tests, 2 failures, 0.00 s]
> --
> sage -t test-order.sage # 2 doctests failed
> --
> Total time for all tests: 0.0 seconds
> cpu time: 0.0 seconds
> cumulative wall time: 0.0 seconds
> make: *** [doctest] Fehler 1
>
>
> This does not look like it would use the display hook...
>
> Daniel
>
--
You received this message because you are subscribed to the Google Groups
"sage-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to sage-devel+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.
Re: [sage-devel] Re: hiding doctest in documentation
Am 2014-07-31 um 15:55 schrieb Volker Braun:
> On Thursday, July 31, 2014 9:16:50 AM UTC-4, Daniel Krenn wrote:
>
> Does this mean it is guaranteed that in doctests dicts are always shown
> with their keys sorted?
>
>
> AFAIK: Yes, but only the top-level dict (no guarantees for nested
> datastructures)
The lines
sage: d = {'a':23, 'b':34, 'au':56, 'bbf':234, 'aaa':234}
sage: d
{'a': 23, 'aaa': 234, 'au': 56, 'b': 34, 'bbf': 234}
are the command line output. Doing this in a doctest (called by a simple
Makefile) gives (among one other failing test):
sage -t test-order.sage
Running doctests with ID 2014-07-31-16-40-03-3683866f.
Doctesting 1 file.
sage -t test-order.sage
**
File "test-order.sage", line 8, in test-order
Failed example:
d
Expected:
{'a': 23, 'aaa': 234, 'au': 56, 'b': 34, 'bbf': 234}
Got:
{'a': 23, 'bbf': 234, 'aaa': 234, 'b': 34, 'au': 56}
**
1 item had failures:
2 of 5 in test-order
[4 tests, 2 failures, 0.00 s]
--
sage -t test-order.sage # 2 doctests failed
--
Total time for all tests: 0.0 seconds
cpu time: 0.0 seconds
cumulative wall time: 0.0 seconds
make: *** [doctest] Fehler 1
This does not look like it would use the display hook...
Daniel
--
You received this message because you are subscribed to the Google Groups
"sage-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to sage-devel+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.
Re: [sage-devel] Re: hiding doctest in documentation
On Thursday, July 31, 2014 9:16:50 AM UTC-4, Daniel Krenn wrote: > > Does this mean it is guaranteed that in doctests dicts are always shown > with their keys sorted? AFAIK: Yes, but only the top-level dict (no guarantees for nested datastructures) -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at http://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
Re: [sage-devel] Re: hiding doctest in documentation
Am 2014-07-28 um 17:47 schrieb Volker Braun:
> On Monday, July 28, 2014 11:42:05 AM UTC-4, William wrote:
> Specifically for dictionaries we also have the displayhook sorting by key:
>
> sage: d = {'a':23, 'b':34, 'au':56, 'bbf':234, 'aaa':234}
> sage: str(d)# dict uses internal order
> "{'a': 23, 'bbf': 234, 'aaa': 234, 'b': 34, 'au': 56}"
> sage: d # displayhook sorts alphabetically
> {'a': 23, 'aaa': 234, 'au': 56, 'b': 34, 'bbf': 234}
Does this mean it is guaranteed that in doctests dicts are always shown
with their keys sorted?
Daniel
--
You received this message because you are subscribed to the Google Groups
"sage-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to sage-devel+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.
Re: [sage-devel] Re: hiding doctest in documentation
> > That's annoying. The entire point of the tests section (which I > introduced in the first place) was to not appear in the ref manual, > interactive docs, etc. I guess I never got around to implementing that or > somebody changed it. > Well, it does not hurt much after all.. Users see the "Example" field that appears first and should be sufficient for what they want to know, and then there is this "tests" field from time to time It's not necessarily worse than having a routine that automatically removes stuff from the docstring. Plus "TESTS" is not always the last field, sometimes the "references" field comes next, or some todo, and it would be hard to move the tests around without removing those blocks too. Nathann -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at http://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
Re: [sage-devel] Re: hiding doctest in documentation
On Jul 28, 2014 8:47 AM, "Volker Braun" wrote:
>
> On Monday, July 28, 2014 11:42:05 AM UTC-4, William wrote:
>>
>> That said, there is a ready-made solution [1] for exactly the original
>> question,
>
>
> The TESTS: section does appear in the reference manual, fyi. Its just a
way to separate it off from EXAMPLES:
>
That's annoying. The entire point of the tests section (which I introduced
in the first place) was to not appear in the ref manual, interactive docs,
etc. I guess I never got around to implementing that or somebody changed
it.
> Specifically for dictionaries we also have the displayhook sorting by key:
>
> sage: d = {'a':23, 'b':34, 'au':56, 'bbf':234, 'aaa':234}
> sage: str(d)# dict uses internal order
> "{'a': 23, 'bbf': 234, 'aaa': 234, 'b': 34, 'au': 56}"
> sage: d # displayhook sorts alphabetically
> {'a': 23, 'aaa': 234, 'au': 56, 'b': 34, 'bbf': 234}
>
> --
> You received this message because you are subscribed to the Google Groups
"sage-devel" group.
> To unsubscribe from this group and stop receiving emails from it, send an
email to sage-devel+unsubscr...@googlegroups.com.
> To post to this group, send email to sage-devel@googlegroups.com.
> Visit this group at http://groups.google.com/group/sage-devel.
> For more options, visit https://groups.google.com/d/optout.
--
You received this message because you are subscribed to the Google Groups
"sage-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to sage-devel+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.
Re: [sage-devel] Re: hiding doctest in documentation
On Monday, July 28, 2014 11:42:05 AM UTC-4, William wrote:
>
> That said, there is a ready-made solution [1] for exactly the original
> question,
>
The TESTS: section does appear in the reference manual, fyi. Its just a way
to separate it off from EXAMPLES:
Specifically for dictionaries we also have the displayhook sorting by key:
sage: d = {'a':23, 'b':34, 'au':56, 'bbf':234, 'aaa':234}
sage: str(d)# dict uses internal order
"{'a': 23, 'bbf': 234, 'aaa': 234, 'b': 34, 'au': 56}"
sage: d # displayhook sorts alphabetically
{'a': 23, 'aaa': 234, 'au': 56, 'b': 34, 'bbf': 234}
--
You received this message because you are subscribed to the Google Groups
"sage-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to sage-devel+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.
Re: [sage-devel] Re: hiding doctest in documentation
On Mon, Jul 28, 2014 at 8:24 AM, Simon King wrote:
> Hi Daniel,
>
> On 2014-07-28, Daniel Krenn wrote:
>> Background: The output of a doctest is a dictionary; therefore there is
>> some uncertainty about the ordering of the entires. To have the
>> dict-output, but get tested as well, I want to do the following:
>>
>> sage: dict = {'a': 'b', 'x': 'y'} # random
>> {'a': 'b', 'x': 'y'}
>> sage: sorted(dict.iteritems()) # hide doctest
>> [('a', 'b'), ('x', 'y')]
>
> I'd suggest to remove the random test and keep the non-random test in
> the doc. I see no reason for hiding it.
>
> Another possibility to deal with randomness of string representation:
> Explicitly assign the expected result to a variable in the doctest, and
> test for equality (here I assume that you have a function/method
> returning a dictionary. Hence, for testing method "bar" of instance
> "Foo", you could do
>
> sage: D = {'a': 'b', 'x': 'y'}
> sage: D == Foo.bar(pi)
> True
>
> But testing against sorted(dict.iteritems()) is perfectly fine in the
> docs (of course it needs to be the case that the sorting of the
> dictionary keys is non-random).
I agree with Simon -- make the test non-random.
That said, there is a ready-made solution [1] for exactly the original
question, which I'm surprised that neither Volker nor Simon mentioned
[1]:
"A TESTS block (optional), formatted just like EXAMPLES, for
additional tests which should be part of the regression suite but are
not illustrative enough to merit placement in EXAMPLES."
Basically, you put
TESTS::
sage: 2+2
4
in your code, and it gets doctested, but doesn't appear in the reference manual.
[1]
http://www.sagemath.org/doc/developer/coding_basics.html#documentation-strings
--
You received this message because you are subscribed to the Google Groups
"sage-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to sage-devel+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at http://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.
