Re: [sage-devel] Poll for issue G5 a specific guideline for writing docstrings

> OUTPUT: a tuple ``(a,b)`` with > > - ``a`` a foo > > - ``b`` a bar > How about this? We can avoid making up variables. (1) OUTPUT: tuple of - foo; friend of bar - bar; friend of foo or simply (2) OUTPUT: - foo; friend of bar - bar; friend of foo - -- You

[sage-devel] About oneliners in TOC vs. docstring

This might also be of interest. I have written for example a docstring "Return True if the lattice is sectionally complemented, and False otherwise. A lattice is sectionally complemented if all intervals from the bottom element interpreted as sublattices are complemented lattices."

Re: [sage-devel] Re: Poll for issue G2 a specific guideline for writing docstrings

On Wed, 17 May 2017, Andrey Novoseltsev wrote: X I think ``self`` should be allowed in a longer description and allowing it there but not in a one-liner is a bit confusing. So I'd rather not say anything about it and let people use their preferences. I am strongly against X. If we have no

[sage-devel] Re: Poll for issue G5 a specific guideline for writing docstrings

On Wednesday, 17 May 2017 15:05:55 UTC-6, Eric Gourgoulhon wrote: > > +1 (a list can have a single item anyway) > > +1 I actually like how OUTPUT block is formatted in the same way as INPUT in HTML when a hyphen is used. On a related note, I do not like allowing :param: etc directives since

[sage-devel] Re: Poll for issue G4 a specific guideline for writing docstrings

+1 -- 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.

Re: [sage-devel] Poll for issue G3 a specific guideline for writing docstrings

-1 I prefer (3) or (4) or "Check" instead of "Test" and have no problems with mixing them. -- 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] Re: Poll for issue G2 a specific guideline for writing docstrings

X I think ``self`` should be allowed in a longer description and allowing it there but not in a one-liner is a bit confusing. So I'd rather not say anything about it and let people use their preferences. -- You received this message because you are subscribed to the Google Groups

[sage-devel] Re: Poll for issue G1 a specific guideline for writing docstrings

-1 -- 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.

Re: [sage-devel] Re: Normaliz and parallel doctest

Well, we could do something in each doctest, but this is cumbersome and ugly IMO. I was thinking of something more in the doctesting framework. Best, Travis On Wednesday, May 17, 2017 at 6:38:51 PM UTC-5, Matthias Koeppe wrote: > > I suppose one could try to set this using os.putenv in the

Re: [sage-devel] Re: Normaliz and parallel doctest

I suppose one could try to set this using os.putenv in the doctests. On Tue, May 16, 2017 at 2:41 PM, Travis Scrimshaw wrote: > Hey Matthias, >Yes, that fixes the problem. Thank you. > > The next question is do we want to (temporarily) set this to, say, 1 when > running

[sage-devel] splitting BRiAl

Hi all, Sorry for the cross posting but I believe it is relevant to sage-devel as a statement of intent. As you may remember BRiAl is a slightly stripped down version of polybori that has been autotooled. I say stripped down because BRiAl do not built the pypolybori python dynamic library that

Re: [sage-devel] Re: what happened to ipython?

I just want to mention that if you would like the old (IPython <= 4.x) readline interface, it is now available separately as rlipython . pip install rlipython python -c "import rlipython as r; r.install()" Right now, it only works in IPython 6.0 (Python

[sage-devel] Re: Poll for issue G5 a specific guideline for writing docstrings

+1 (a list can have a single item anyway) -- 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

Re: [sage-devel] Poll for issue G4 a specific guideline for writing docstrings

+1 for Daniel's proposal: G4. An OUTPUT block is recommended unless it is clear from the one-line > explanation. If in doubt include it. > > > -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving

[sage-devel] Re: Poll for issue G3 a specific guideline for writing docstrings

-1 (fully agree with Vincent) -- 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] Re: Poll for issue G2 a specific guideline for writing docstrings

+1, although I agree with Travis that ``self`` is technically precise and unambiguous (but for users not familiar with Python, who would read the inline documentation obtained via the question mark, ``self`` can be disturbing) What is the policy of other Python projects regarding this? --

[sage-devel] Re: Poll for issue G1 a specific guideline for writing docstrings

-1 (typesetting adds readability) -- 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

Re: [sage-devel] Poll for issue G4 a specific guideline for writing docstrings

+1 Le 17/05/2017 à 17:02, Jeroen Demeyer a écrit : +1 In practice, this is already how things are done anyway. -- 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

[sage-devel] Re: Poll for issue G1 a specific guideline for writing docstrings

I'd try to avoid the entire construct; Its the linguistic equivalent of if condition: return True else: return False Just say "Test condition" in the docstring. On Wednesday, May 17, 2017 at 4:07:29 PM UTC+2, Kwankyu Lee wrote: > > We do a poll for adopting an official guideline for

Re: [sage-devel] Poll for issue G5 a specific guideline for writing docstrings

+1 to OUTPUT: lattice when possible. On Wednesday, May 17, 2017 at 8:05:21 AM UTC-7, Jeroen Demeyer wrote: > > What about > > OUTPUT: lattice > > Unlike an INPUT, an OUTPUT is not a list of things. So why format it as > a list? A list could be useful for example in > > OUTPUT: a tuple

[sage-devel] Re: Poll for issue G1 a specific guideline for writing docstrings

On Wednesday, May 17, 2017 at 7:07:29 AM UTC-7, Kwankyu Lee wrote: > > We do a poll for adopting an official guideline for docstrings (see > https://trac.sagemath.org/ticket/23017) > > G1. Write > > Return True if something is true. > > but do not write > > Return ``True`` if

Re: [sage-devel] About certificate-parameter

On 17/05/2017 17:43, Jori Mäntysalo wrote: On Wed, 17 May 2017, Vincent Delecroix wrote: An example is given by "is_cyclotomic" that returns either a boolean or an integer sage: x = polygen(ZZ) sage: p = x^2 + x + 1 sage: p.is_cyclotomic() True sage: p.is_cyclotomic(certificate=True) 3 I

Re: [sage-devel] Poll for issue G2 a specific guideline for writing docstrings

I am (still) a strong -1 on this. ``self`` is a perfectly well-defined concept in Python and is often more concise and readable. It also works better with subclasses that have different names, e.g., lattice vs poset. Granted, this is not a very strong point because one should know a lattice is

[sage-devel] About certificate-parameter

On Wed, 17 May 2017, Vincent Delecroix wrote: An example is given by "is_cyclotomic" that returns either a boolean or an integer sage: x = polygen(ZZ) sage: p = x^2 + x + 1 sage: p.is_cyclotomic() True sage: p.is_cyclotomic(certificate=True) 3 I suggest that certificate=True always returns

Re: [sage-devel] Poll for issue G2 a specific guideline for writing docstrings

On 2017-05-17 17:17, Jeroen Demeyer wrote: > On 2017-05-17 17:10, Daniel Krenn wrote: >> I find this perfectly fine. I personally would write "Return whether >> this lattice is contained in the other lattice", but I do not find any >> need to include ``self`` in the one-line description. > >

Re: [sage-devel] Poll for issue G2 a specific guideline for writing docstrings

On 2017-05-17 17:10, Daniel Krenn wrote: I find this perfectly fine. I personally would write "Return whether this lattice is contained in the other lattice", but I do not find any need to include ``self`` in the one-line description. Well, in general, sentences containing too many words like

Re: [sage-devel] Re: Unifying "test::" and "tests::"

On 2017-05-17 14:13, Kwankyu Lee wrote: > I agree; in the formatteed text, there should not be quotes, > > > In terminal and jupyter, ``True`` is rendered "True". I think this is > ugly. It should be rendered True > > > but it should also not be formatted as plain text. > > > Why

Re: [sage-devel] Poll for issue G5 a specific guideline for writing docstrings

On 2017-05-17 17:09, Vincent Delecroix wrote: I like the above, however there can be more complicated output (depending on the output). An example is given by "is_cyclotomic" that returns either a boolean or an integer Of course a list makes sense in this case. I didn't say to forbid a list,

Re: [sage-devel] Poll for issue G5 a specific guideline for writing docstrings

On 17/05/2017 17:05, Jeroen Demeyer wrote: What about OUTPUT: lattice Unlike an INPUT, an OUTPUT is not a list of things. So why format it as a list? A list could be useful for example in OUTPUT: a tuple ``(a,b)`` with - ``a`` a foo - ``b`` a bar I like the above, however there can be

Re: [sage-devel] Poll for issue G2 a specific guideline for writing docstrings

On 2017-05-17 17:00, Jeroen Demeyer wrote: > def is_sublattice(self, other): > """ > Return ``True`` if this lattice is contained > in the other lattice. > """ > > In this case, it would be better to refer to ``self`` and ``other``. I find this perfectly fine. I personally would

Re: [sage-devel] Poll for issue G5 a specific guideline for writing docstrings

What about OUTPUT: lattice Unlike an INPUT, an OUTPUT is not a list of things. So why format it as a list? A list could be useful for example in OUTPUT: a tuple ``(a,b)`` with - ``a`` a foo - ``b`` a bar -- You received this message because you are subscribed to the Google Groups

Re: [sage-devel] Re: Unifying "test::" and "tests::"

On 2017-05-17 13:40, Kwankyu Lee wrote: > I am simply asking why we aren't writing a docstring as > > "Return True if " > > instead of > > "Return ``True`` if ..." > > just like > > "Return an integer ..." > > instead of > > "Return an ``Integer``" Because ``True`` is an object of

Re: [sage-devel] Poll for issue G4 a specific guideline for writing docstrings

+1 In practice, this is already how things are done anyway. -- 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

Re: [sage-devel] Poll for issue G2 a specific guideline for writing docstrings

+1 but make it clear that this is only a guideline and then "``self``" might still be better in some cases. For example, imagine def is_sublattice(self, other): """ Return ``True`` if this lattice is contained in the other lattice. """ In this case, it would be better to refer

Re: [sage-devel] Poll for issue G1 a specific guideline for writing docstrings

On 2017-05-17 16:07, Kwankyu Lee wrote: > We do a poll for adopting an official guideline for docstrings > (see https://trac.sagemath.org/ticket/23017) > > G1. Write > > | > Return True if something is true. > | > > but do not write > > | > Return ``True`` if something is true. > |

Re: [sage-devel] Poll for issue G2 a specific guideline for writing docstrings

On 2017-05-17 16:11, Kwankyu Lee wrote: > We do a poll for adopting an official guideline for docstrings > (see https://trac.sagemath.org/ticket/23017 > ) > > G2. Write > > | > if the lattice is reflexive ... > | > > but don't write > > | > if

Re: [sage-devel] Poll for issue G3 a specific guideline for writing docstrings

On 2017-05-17 16:16, Kwankyu Lee wrote: > | > Return whether the lattice is reflexive. > | +1 for the above option. (i.e. -1 in the sense of this poll) -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop

Re: [sage-devel] Poll for issue G4 a specific guideline for writing docstrings

On 2017-05-17 16:24, Kwankyu Lee wrote: > We do a poll for adopting an official guideline for docstrings > (see https://trac.sagemath.org/ticket/23017 > ) > > G4. OUTPUT block is optional > > The developer manual says OUTPUT block is not

Re: [sage-devel] Poll for issue G5 a specific guideline for writing docstrings

On 2017-05-17 16:30, Kwankyu Lee wrote: > We do a poll for adopting an official guideline for docstrings > (see https://trac.sagemath.org/ticket/23017 > ) > > G5. Write > > | > OUTPUT: > > - lattice > | > > > but do not write > > | > OUTPUT: >

[sage-devel] Poll for issue G5 a specific guideline for writing docstrings

We do a poll for adopting an official guideline for docstrings (see https://trac.sagemath.org/ticket/23017) G5. Write OUTPUT: - lattice but do not write OUTPUT: lattice The development manual says a hyphen is optional. But for consistency, we need to settle down on

Re: [sage-devel] Poll for issue G4 a specific guideline for writing docstrings

On 17/05/2017 16:24, Kwankyu Lee wrote: We do a poll for adopting an official guideline for docstrings (see https://trac.sagemath.org/ticket/23017) G4. OUTPUT block is optional The developer manual says OUTPUT block is not optional. But I think the first statement of the

Re: [sage-devel] Poll for issue G3 a specific guideline for writing docstrings

On 17/05/2017 16:16, Kwankyu Lee wrote: We do a poll for adopting an official guideline for docstrings (see https://trac.sagemath.org/ticket/23017) G3. Write (1) Return True if the lattice is reflexive. but do not write (2) Return True if the lattice is reflexive and False otherwise.

[sage-devel] Poll for issue G4 a specific guideline for writing docstrings

We do a poll for adopting an official guideline for docstrings (see https://trac.sagemath.org/ticket/23017) G4. OUTPUT block is optional The developer manual says OUTPUT block is not optional. But I think the first statement of the docstring "Return an object ..." already

[sage-devel] Poll for issue G3 a specific guideline for writing docstrings

We do a poll for adopting an official guideline for docstrings (see https://trac.sagemath.org/ticket/23017) G3. Write (1) Return True if the lattice is reflexive. but do not write (2) Return True if the lattice is reflexive and False otherwise. nor (3) Return whether the lattice is

[sage-devel] Poll for issue G2 a specific guideline for writing docstrings

We do a poll for adopting an official guideline for docstrings (see https://trac.sagemath.org/ticket/23017) G2. Write if the lattice is reflexive ... but don't write if ``self`` is reflexive ... If you agree, flag +1; if you disagree and want it reversed, flag -1; if you

[sage-devel] Poll for issue G1 a specific guideline for writing docstrings

We do a poll for adopting an official guideline for docstrings (see https://trac.sagemath.org/ticket/23017) G1. Write Return True if something is true. but do not write Return ``True`` if something is true. The same applies to `False` and `None` If you agree, flag +1; if

Re: [sage-devel] Several choises for docstring

Now we have a ticket for this https://trac.sagemath.org/ticket/23017 Please add your issues to the ticket, following its explicit style :-) -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On 17/05/2017 14:00, Jeroen Demeyer wrote: On 2017-05-17 12:19, Vincent Delecroix wrote: Let me tell that my wish to have another test framework is mostly organizational. First of all, the code in the docstrings are intended to be read by users. I think that we would benefit from a clearer

Re: [sage-devel] Re: Unifying "test::" and "tests::"

On Wednesday, May 17, 2017 at 8:13:30 AM UTC-4, Kwankyu Lee wrote: > > I agree; in the formatteed text, there should not be quotes, > > > In terminal and jupyter, ``True`` is rendered "True". I think this is > ugly. It should be rendered True > > Hmm, that is weird. The reason for ``True``

Re: [sage-devel] Several choises for docstring

On Wed, 17 May 2017, Kwankyu Lee wrote: I am simply asking why we aren't writing a docstring as "Return True if " instead of "Return ``True`` if ...". This would be OK for me. Should it even be "Return true if ..."? But now I will write a long story about short docstrings. Let's suppose

[sage-devel] Re: I need advice on my paper and Sage code on "Classifying bent functions by their Cayley graphs"

On Wednesday, May 17, 2017 at 1:12:15 PM UTC+1, Paul Leopardi wrote: > > Thanks for the suggestion. I have taken a look at the web site. It looks > to be more concerned with the replication of research that has already been > published, rather than the publication of new research >

[sage-devel] Re: I need advice on my paper and Sage code on "Classifying bent functions by their Cayley graphs"

Hi Travis, Thanks for your advice. For now, I will keep the code where it is on GitHub and SageMathCloud, and concentrate on adding documentation, examples and doctests for all the functions and methods. After that, I will revisit the problem of incorporating all r some of it into Sage proper.

[sage-devel] Re: Sage policy question: require docstrings and doctests?

Jeroen Demeyer wrote: > For functions which are meant to be called directly by end users, > doctests are essential because they should show examples of how the > function should actually be used. However, for internal functions or > things like __init__, it is often not easy to write meaningful >

Re: [sage-devel] I need advice on my paper and Sage code on "Classifying bent functions by their Cayley graphs"

Thanks for your suggestions. For now, I have put my first draft up on arXiv as https://arxiv.org/abs/1705.04507 and will update this whenever I produce major revisions, while keeping the minor revisions in LaTeX on Github

[sage-devel] Re: Sage policy question: require docstrings and doctests?

Jeroen Demeyer wrote: >>- random seeds are always the same > > That can easily be fixed by explicitly changing the random seed in the > doctest (probably some helper context should be provided for this) Or, in the case of complicated tests done by a dedicated function, by using

Re: [sage-devel] Re: Unifying "test::" and "tests::"

> > I agree; in the formatteed text, there should not be quotes, In terminal and jupyter, ``True`` is rendered "True". I think this is ugly. It should be rendered True > but it should also not be formatted as plain text. Why not? Why do we treat them differently from other Sage objects?

[sage-devel] Re: I need advice on my paper and Sage code on "Classifying bent functions by their Cayley graphs"

Thanks for the suggestion. I have taken a look at the web site. It looks to be more concerned with the replication of research that has already been published, rather than the publication of new research

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On 05/17/2017 04:07 AM, Jeroen Demeyer wrote: > > Totally +1 > > Too bad that too many people take the coverage script too literal. > > For functions which are meant to be called directly by end users, > doctests are essential because they should show examples of how the > function should

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On Wed, 17 May 2017, Jeroen Demeyer wrote: Here are several reasons: - random seeds are always the same That can easily be fixed by explicitly changing the random seed in the doctest (probably some helper context should be provided for this) Currently sage -t --randorder will give

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On 2017-05-17 12:19, Vincent Delecroix wrote: Here are several reasons: - random seeds are always the same That can easily be fixed by explicitly changing the random seed in the doctest (probably some helper context should be provided for this) - impossible to have complicated test

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On 2017-05-17 12:19, Vincent Delecroix wrote: 1) Each code path (including errors) must be tested". You can easily translate this requirement as "require 100% *line* coverage" instead of *function* coverage which is what is current sage-coverage script tests. 2) Introduce an

Re: [sage-devel] Re: Unifying "test::" and "tests::"

I am simply asking why we aren't writing a docstring as "Return True if " instead of "Return ``True`` if ..." just like "Return an integer ..." instead of "Return an ``Integer``" -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To

Re: [sage-devel] Re: Unifying "test::" and "tests::"

On 2017-05-17 10:51, Kwankyu Lee wrote: > I am for writing double-quotes ``True``, ``False``, ``None``, as > this is > the "offical" representation of these objects and therefore is printed > as output. Thus a typewriter-font is appropriate. > > > In what sense, is it official?

Re: [sage-devel] Re: Unifying "test::" and "tests::"

On Wednesday, May 17, 2017 at 11:56:28 AM UTC+2, Jori Mäntysalo wrote: > > On Wed, 17 May 2017, Kwankyu Lee wrote: > > >> I am for writing double-quotes ``True``, ``False``, ``None`` > > > > Two reasons why I am against it: > > Some example functions with different formats of docstrings?

Re: [sage-devel] Sage policy question: require docstrings and doctests?

I do definitely support the idea of doctests for illustrative purposes. However, as already mentioned, relying on them for the whole testing framework is bad IMHO. Here are several reasons: - random seeds are always the same - impossible to have complicated test code - impossible to tune

Re: [sage-devel] Re: Unifying "test::" and "tests::"

On Wed, 17 May 2017, Kwankyu Lee wrote: I am for writing double-quotes ``True``, ``False``, ``None`` Two reasons why I am against it: Some example functions with different formats of docstrings? Would be easier to compare then. * * * I have made quite many is_* -functions. I suggest

Re: [sage-devel] Sage policy question: require docstrings and doctests?

> > For functions which are meant to be called directly by end users, > doctests are essential because they should show examples of how the > function should actually be used. For the case that a function is meant to be internal but can be accessed by an end user via say tab completion

Re: [sage-devel] Re: Unifying "test::" and "tests::"

> > I am for writing double-quotes ``True``, ``False``, ``None``, as this is > the "offical" representation of these objects and therefore is printed > as output. Thus a typewriter-font is appropriate. > In what sense, is it official? In Python or in Sage? Two reasons why I am against it:

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On 2017-05-15 18:39, Erik Bray wrote: It's possible using something like coverage.py will just work, but I haven't tried it yet. For Cython, see http://cython.readthedocs.io/en/latest/src/tutorial/profiling_tutorial.html#enabling-coverage-analysis -- You received this message because you

Re: [sage-devel] Sage policy question: require docstrings and doctests?

On 2017-05-15 15:56, Erik Bray wrote: The point is that no matter how well motivated a coding guideline is it's just that--a guideline (maybe even a very important one!). But one never bend over backwards to write non-idiomatic, convoluted, or not well-motivated code just to satisfy a

Re: [sage-devel] Re: Unifying "test::" and "tests::"

On 2017-05-16 18:44, Kwankyu Lee wrote: > In general, my opinion is that the guideline for style in the developer > manual should be specific in details such that the whole documentation > is in consistent style. One example is to double-quote or not to > double-quote True, False, and None. I am

Re: [sage-devel] Re: Unifying "test::" and "tests::"

On 2017-05-16 21:02, Jori Mäntysalo wrote: > On Tue, 16 May 2017, Kwankyu Lee wrote: > And about that: what should be the place of SEEALSO-block? Or in > general, order of blocks? I usually put it after the EXAMPLES-block but before a TESTS-block Daniel -- You received this message because you