Re: [sage-devel] Second round poll for H1 a specific guideline for writing docstrings

[Jori Mäntysalo]

On Thu, 18 May 2017, Kwankyu Lee wrote:

So this time if I fail to get approval from most of you, the guideline 
will be simply discarded.  


I am strongly against discarding the guideline(s). If we have no common 
view, I suggest that we make a poll (LimeSurvey or similar) and tell it 
sage-support.


And if that fails too, we will give an official dollar coin to William. He 
will then toss a coin to make an arbitrary decision.


(By guideline I do not mean a rule.)

--
Jori Mäntysalo

Re: [sage-devel] Docstring standards: new Sphinx directives? New Sphinx directions?

[Jori Mäntysalo]

On Thu, 18 May 2017, John H Palmieri wrote:


    .. INPUT::

We would need to add "INPUT", "OUTPUT", etc. as Sphinx directives. Then we 
would have control over the format for the
output.


Sounds good, BUT what about substructures? Can we have, for example, NOTE 
inside INPUT? In some more complicated situations, mostly constructors, we 
also could have examples inside input blocks.


--
Jori Mäntysalo

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

[Travis Scrimshaw]

As I mentioned about, I suspect what is happening is each process runs its 
own copy of normaliz, which in turn, uses all CPU cores with its parallel 
computations. This would cause either a lot of thrashing or waiting for 
locks to free up. Thus, we don't run into this when running Sage directly 
because we are only using one Sage process, and I believe there is only one 
file which really has normaliz do some non-trivial work. I would guess you 
could reproduce this locally by starting up a few Sage processes and having 
them run computations simultaneously. At least, I'd be more surprised if 
you didn't get a (large) time difference between testing the 
combinat/rigged_configurations folder in series and in parallel. Are you 
saying you do not get that?

So I'm not sure I would qualify this as a bug on the part of normaliz. I 
would say it is a misuse on our part because of Sage's parallel doctesting 
framework of forking a new process (at least, I believe that is what it 
does, someone please correct me if I'm wrong). So the proper fix in my mind 
is to tell normaliz that when we are running our parallel doctests that it 
should not do computations in parallel.

Best,
Travis


On Thursday, May 18, 2017 at 6:04:34 PM UTC-5, Matthias Koeppe wrote:
>
> I think it is really an upstream problem with normaliz. We could try 
> to work around it in our normaliz interface (not just the doctest) 
> because it may also affect computation time in general on some 
> hardware. (I never ran into trouble with it on my machine.) 
>
> On Wed, May 17, 2017 at 5:24 PM, Travis Scrimshaw  > wrote: 
> > 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 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 the doctests? If so, then how/where? 
> >> > 
> >> > Best, 
> >> > Travis 
> >> > 
> >> > 
> >> > 
> >> > On Tuesday, May 16, 2017 at 12:29:51 PM UTC-5, Matthias Koeppe wrote: 
> >> >> 
> >> >> Hi Travis, 
> >> >> please try if setting OMP_NUM_THREADS=4 or smaller fixes this 
> problem. 
> >> >> This is something that I have to do in the CI scripts for Normaliz 
> also 
> >> >> (
> https://github.com/Normaliz/Normaliz/blob/master/.travis-build.sh#L7) 
> >> >> Best, 
> >> >> Matthias 
> >> >> 
> >> >> On Saturday, May 13, 2017 at 12:45:46 PM UTC-7, Travis Scrimshaw 
> wrote: 
> >> >>> 
> >> >>> For the combinat/rigged_configurations, I recently changed the 
> >> >>> iteration 
> >> >>> method to use lattice point counting using normaliz (if installed). 
> >> >>> However, 
> >> >>> when running the doctests in parallel with normaliz installed, this 
> >> >>> causes a 
> >> >>> significant slowdown: 
> >> >>> 
> >> >>> travis@apricot:~/sage-build$ ./sage -tp 2 
> >> >>> src/sage/combinat/rigged_configurations/* 
> >> >>> too many failed tests, not using stored timings 
> >> >>> Running doctests with ID 2017-05-13-14-41-00-970329a3. 
> >> >>> Git branch: public/crystals/speedup_rigged_configurations-TBA 
> >> >>> Using 
> >> >>> 
> >> >>> 
> --optional=coxeter3,database_gap,gambit,libbraiding,libhomfly,meataxe,mpir,normaliz,ore_algebra,pynormaliz,python2,sage,sirocco
>  
>
> >> >>> Sorting sources by runtime so that slower doctests are run 
> first 
> >> >>> Doctesting 24 files using 2 threads. 
> >> >>> sage -t src/sage/combinat/rigged_configurations/kr_tableaux.py 
> >> >>> [238 tests, 9.41 s] 
> >> >>> sage -t src/sage/combinat/rigged_configurations/bij_type_B.py 
> >> >>> [41 tests, 5.29 s] 
> >> >>> sage -t 
> >> >>> 
> >> >>> 
> src/sage/combinat/rigged_configurations/rigged_configuration_element.py 
> >> >>> [268 tests, 17.18 s] 
> >> >>> sage -t 
> >> >>> 
> >> >>> 
> src/sage/combinat/rigged_configurations/tensor_product_kr_tableaux_element.py 
>
> >> >>> [75 tests, 5.61 s] 
> >> >>> sage -t 
> >> >>> src/sage/combinat/rigged_configurations/rigged_configurations.py 
> >> >>> [214 tests, 15.21 s] 
> >> >>> sage -t src/sage/combinat/rigged_configurations/rc_infinity.py 
> >> >>> [105 tests, 2.07 s] 
> >> >>> sage -t 
> >> >>> 
> src/sage/combinat/rigged_configurations/tensor_product_kr_tableaux.py 
> >> >>> [91 tests, 4.31 s] 
> >> >>> sage -t src/sage/combinat/rigged_configurations/bij_infinity.py 
> >> >>> [44 tests, 1.87 s] 
> >> >>> sage -t src/sage/combinat/rigged_configurations/rc_crystal.py 
> >> >>> [83 tests, 1.13 s] 
> >> >>> sage -t src/sage/combinat/rigged_configurations/bij_type_E67.py 
> >> >>> [68 tests, 2.95 s] 
> >> >>> 

[sage-devel] Re: Second round poll for H2 a specific guideline for writing docstrings

[Travis Scrimshaw]

Strong -1 (still)

On Thursday, May 18, 2017 at 5:46:35 PM UTC-5, Kwankyu Lee wrote:
>
> As some of you worry, I do not attempt to put some strict rules into the 
> developer manual so that forbid your own style in writing docstrings. These 
> are intended just as guidelines; these will guide him or her when a 
> developer is in doubt in styling the docstrings. On the other hand, if you 
> have a strong reason to write in a different style, these guidelines should 
> not forbid you.
>

-- 
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Secondl round poll for H6 a specific guideline for writing docstrings

[Travis Scrimshaw]

+1 (this is also my preferred format)

On Thursday, May 18, 2017 at 5:28:54 PM UTC-5, Kwankyu Lee wrote:
>
> Hi,
>
> I prepared H6 from your comments on the style of INPUT block. It was hard 
> to make a compromise from your differing opinions and reach a proposal for 
> the better. So this time* if I fail to get approval from most of you, the 
> guideline will be simply discarded.*  
> **
> H6. Write
>
> INPUT: 
>
> - ``n`` -- integer (default: 1); the number of repetition
>
> 
> If you agree, flag +1; if you don't, flag -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.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Second round poll for H4 a specific guideline for writing docstrings

[Travis Scrimshaw]

+1 (it is also currently used in practice).

On Thursday, May 18, 2017 at 5:24:12 PM UTC-5, Kwankyu Lee wrote:
>
> Hi,
>
> I prepared H4 revised from G4 based on your ideas and wishes. It was hard 
> to make a compromise from your differing opinions and reach a proposal for 
> the better. So this time* if I fail to get approval from most of you, the 
> guideline will be simply discarded.*  
> **
> H4. OUTPUT block is optional but recommended unless it is clear from the 
> one-line 
> explanation.
> 
> If you agree, flag +1; if you don't, flag -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.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Second round poll for H1 a specific guideline for writing docstrings

[Travis Scrimshaw]

+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.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Google Summer of Code 2017 matroids project

[Zachary Gershkoff]

Hello,

This year I will be working on the matroid and graph theory packages for 
Google Summer of Code. My project will focus on expanding the list of 
matroid classes available in sage, with methods to do convenient or more 
efficient computations specific to the class. In particular, I'll make a 
graphic matroid class, where instances will keep an associated graph in 
memory. I also will try to improve the existing functionality for plotting 
rank-3 matroids geometrically.

My GSoC blog is at https://picturesofmatroids.wordpress.com/ . I've already 
started working on tickets such as https://trac.sagemath.org/ticket/23027 
(needs review) and https://trac.sagemath.org/ticket/22559 (positive review) 
so I should be ready to go once coding starts May 30th.

--Zach

-- 
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

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

[Matthias Koeppe]

I think it is really an upstream problem with normaliz. We could try
to work around it in our normaliz interface (not just the doctest)
because it may also affect computation time in general on some
hardware. (I never ran into trouble with it on my machine.)

On Wed, May 17, 2017 at 5:24 PM, Travis Scrimshaw  wrote:
> 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 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 the doctests? If so, then how/where?
>> >
>> > Best,
>> > Travis
>> >
>> >
>> >
>> > On Tuesday, May 16, 2017 at 12:29:51 PM UTC-5, Matthias Koeppe wrote:
>> >>
>> >> Hi Travis,
>> >> please try if setting OMP_NUM_THREADS=4 or smaller fixes this problem.
>> >> This is something that I have to do in the CI scripts for Normaliz also
>> >> (https://github.com/Normaliz/Normaliz/blob/master/.travis-build.sh#L7)
>> >> Best,
>> >> Matthias
>> >>
>> >> On Saturday, May 13, 2017 at 12:45:46 PM UTC-7, Travis Scrimshaw wrote:
>> >>>
>> >>> For the combinat/rigged_configurations, I recently changed the
>> >>> iteration
>> >>> method to use lattice point counting using normaliz (if installed).
>> >>> However,
>> >>> when running the doctests in parallel with normaliz installed, this
>> >>> causes a
>> >>> significant slowdown:
>> >>>
>> >>> travis@apricot:~/sage-build$ ./sage -tp 2
>> >>> src/sage/combinat/rigged_configurations/*
>> >>> too many failed tests, not using stored timings
>> >>> Running doctests with ID 2017-05-13-14-41-00-970329a3.
>> >>> Git branch: public/crystals/speedup_rigged_configurations-TBA
>> >>> Using
>> >>>
>> >>> --optional=coxeter3,database_gap,gambit,libbraiding,libhomfly,meataxe,mpir,normaliz,ore_algebra,pynormaliz,python2,sage,sirocco
>> >>> Sorting sources by runtime so that slower doctests are run first
>> >>> Doctesting 24 files using 2 threads.
>> >>> sage -t src/sage/combinat/rigged_configurations/kr_tableaux.py
>> >>> [238 tests, 9.41 s]
>> >>> sage -t src/sage/combinat/rigged_configurations/bij_type_B.py
>> >>> [41 tests, 5.29 s]
>> >>> sage -t
>> >>>
>> >>> src/sage/combinat/rigged_configurations/rigged_configuration_element.py
>> >>> [268 tests, 17.18 s]
>> >>> sage -t
>> >>>
>> >>> src/sage/combinat/rigged_configurations/tensor_product_kr_tableaux_element.py
>> >>> [75 tests, 5.61 s]
>> >>> sage -t
>> >>> src/sage/combinat/rigged_configurations/rigged_configurations.py
>> >>> [214 tests, 15.21 s]
>> >>> sage -t src/sage/combinat/rigged_configurations/rc_infinity.py
>> >>> [105 tests, 2.07 s]
>> >>> sage -t
>> >>> src/sage/combinat/rigged_configurations/tensor_product_kr_tableaux.py
>> >>> [91 tests, 4.31 s]
>> >>> sage -t src/sage/combinat/rigged_configurations/bij_infinity.py
>> >>> [44 tests, 1.87 s]
>> >>> sage -t src/sage/combinat/rigged_configurations/rc_crystal.py
>> >>> [83 tests, 1.13 s]
>> >>> sage -t src/sage/combinat/rigged_configurations/bij_type_E67.py
>> >>> [68 tests, 2.95 s]
>> >>> sage -t src/sage/combinat/rigged_configurations/bij_abstract_class.py
>> >>> [66 tests, 0.77 s]
>> >>> sage -t src/sage/combinat/rigged_configurations/kleber_tree.py
>> >>> [218 tests, 37.54 s]
>> >>> sage -t src/sage/combinat/rigged_configurations/bij_type_D.py
>> >>> [79 tests, 0.77 s]
>> >>> sage -t src/sage/combinat/rigged_configurations/bij_type_D_twisted.py
>> >>> [29 tests, 0.57 s]
>> >>> sage -t src/sage/combinat/rigged_configurations/bij_type_C.py
>> >>> [28 tests, 0.54 s]
>> >>> sage -t src/sage/combinat/rigged_configurations/bij_type_A2_dual.py
>> >>> [19 tests, 0.48 s]
>> >>> sage -t src/sage/combinat/rigged_configurations/bij_type_A2_odd.py
>> >>> [19 tests, 0.49 s]
>> >>> sage -t src/sage/combinat/rigged_configurations/bij_type_D_tri.py
>> >>> [19 tests, 0.48 s]
>> >>> sage -t src/sage/combinat/rigged_configurations/bij_type_A2_even.py
>> >>> [19 tests, 0.48 s]
>> >>> sage -t src/sage/combinat/rigged_configurations/bijection.py
>> >>> [6 tests, 0.35 s]
>> >>> sage -t src/sage/combinat/rigged_configurations/rigged_partition.py
>> >>> [58 tests, 0.46 s]
>> >>> sage -t src/sage/combinat/rigged_configurations/__init__.py
>> >>> [0 tests, 0.00 s]
>> >>> sage -t src/sage/combinat/rigged_configurations/all.py
>> >>> [0 tests, 0.00 s]
>> >>> sage -t src/sage/combinat/rigged_configurations/bij_type_A.py
>> >>> [19 tests, 0.36 s]
>> >>> --
>> >>> All tests passed!
>> >>> 

[sage-devel] Re: Second round poll for H2 a specific guideline for writing docstrings

[Kwankyu Lee]

As some of you worry, I do not attempt to put some strict rules into the 
developer manual so that forbid your own style in writing docstrings. These 
are intended just as guidelines; these will guide him or her when a 
developer is in doubt in styling the docstrings. On the other hand, if you 
have a strong reason to write in a different style, these guidelines should 
not forbid you.

-- 
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Docstring standards: new Sphinx directives? New Sphinx directions?

[John H Palmieri]

Regarding the current polling for docstring guidelines and standards, 
perhaps it would be better to write docstrings in a form like

def f(...):
"""
one line description, as we currently have

.. INPUT::

input block, maybe an itemized list

.. OUTPUT::

output block

.. ALGORITHM::

etc.

..  SEEALSO::

etc.
"""

We would need to add "INPUT", "OUTPUT", etc. as Sphinx directives. Then we 
would have control over the format for the output. 

Or we could use the existing Sphinx syntax of 

:param x: the number of edges
:type x: integer
:return: the number of vertices
:rtype: integer
:raises ValueError: if x is negative

and then perhaps modify how Sphinx produces output from those.

Or see http://www.sphinx-doc.org/en/stable/ext/napoleon.html for another 
option. Maybe we should look into this one more.

-- 
John

-- 
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Secondl round poll for H6 a specific guideline for writing docstrings

[Kwankyu Lee]

Hi,

I prepared H6 from your comments on the style of INPUT block. It was hard 
to make a compromise from your differing opinions and reach a proposal for 
the better. So this time* if I fail to get approval from most of you, the 
guideline will be simply discarded.*  
**
H6. Write

INPUT: 

- ``n`` -- integer (default: 1); the number of repetition


If you agree, flag +1; if you don't, flag -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.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Second round poll for H5 a specific guideline for writing docstrings

[Kwankyu Lee]

Hi,

I prepared H5 revised from G5 based on your ideas and wishes. It was hard 
to make a compromise from your differing opinions and reach a proposal for 
the better. So this time* if I fail to get approval from most of you, the 
guideline will be simply discarded.*  
**
H5. Write

OUTPUT: 

- tuple of lattices

Note the leading hyphen and no period at the end. If the output consists of 
several items, add each starting with a hyphen.

If you agree, flag +1; if you don't, flag -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.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Second round poll for H4 a specific guideline for writing docstrings

[Kwankyu Lee]

Hi,

I prepared H4 revised from G4 based on your ideas and wishes. It was hard 
to make a compromise from your differing opinions and reach a proposal for 
the better. So this time* if I fail to get approval from most of you, the 
guideline will be simply discarded.*  
**
H4. OUTPUT block is optional but recommended unless it is clear from the 
one-line 
explanation.

If you agree, flag +1; if you don't, flag -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.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Second round poll for H1 a specific guideline for writing docstrings

[John H Palmieri]

+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.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Second round poll for H3 a specific guideline for writing docstrings

[Kwankyu Lee]

Hi,

I prepared H3 revised from G3 based on your ideas and wishes. It was hard 
to make a compromise from your differing opinions and reach a proposal for 
the better. So this time* if I fail to get approval from most of you, the 
guideline will be simply discarded.*  
**
H3. Write

Return whether the lattice is reflexive.

but do not write

Return ``True`` if the lattice is reflexive and ``False`` otherwise.


If you agree, flag +1; if you don't, flag -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.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Second round poll for H2 a specific guideline for writing docstrings

[Kwankyu Lee]

Hi,

I prepared H2 revised from G2 based on your ideas and wishes. It was hard 
to make a compromise from your differing opinions and reach a proposal for 
the better. So this time* if I fail to get approval from most of you, the 
guideline will be simply discarded.*  
**
H2. Write

if the lattice is reflexive 

but do not write

if ``self`` is reflexive

If you agree, flag +1; if you don't, flag -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.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Second round poll for H1 a specific guideline for writing docstrings

[Kwankyu Lee]

Hi,

I prepared H1 revised from G1 based on your ideas and wishes. It was hard 
to make a compromise from your differing opinions and reach a proposal for 
the better. So this time* if I fail to get approval from most of you, the 
guideline will be simply discarded.*  
**
H1. Write 

``True``, ``False``, ``None``

but do not write 

True, False, None

If you agree, flag +1; if you don't, flag -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.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

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

[Vincent Klein]

+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.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

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

[Vincent Klein]

+1

Le mercredi 17 mai 2017 16:24:47 UTC+2, Kwankyu Lee a écrit :
>
> 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 describes 
> what is output. Hence usually the OUTPUT block is redundant and is needed 
> only when more explanation about the returned object is necessary.
>
> If you agree, flag +1; if you disagree, flag -1; if you want to leave it 
> as it is, flag X.
>

-- 
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

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

[Jeroen Demeyer]

On 2017-05-18 14:36, Erik Bray wrote:

I don't think you could write something that is intelligent enough to
distinguish the literals ``True``, ``False``, or ``None`` with the
word itself (which would be capitalized if beginning a sentence--not
common, but not impossible either).


Reasonable example: "None of the input vertices should be adjacent."

--
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

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

[Erik Bray]

On Thu, May 18, 2017 at 9:19 AM, Kwankyu Lee  wrote:
>> -1
>>
>> See the first few lines of [1] where an equivalent of our ``True`` is
>> used (and therefore written in typewriter font)
>
>
> (This is perhaps my last resistance; please bear with me :-)
>
> A technical question: is it possible to set our Sphinx so that we write in a
> docstring
>
> Return True if something is False.
>
> but the True and False are rendered in tt font (or even as links as you
> suggested). Then we could avoid cluttering files with lots of double quotes
> for True, False, and None, and use them mostly for arguments.

I don't think you could write something that is intelligent enough to
distinguish the literals ``True``, ``False``, or ``None`` with the
word itself (which would be capitalized if beginning a sentence--not
common, but not impossible either).

-- 
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

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

[Erik Bray]

On Wed, May 17, 2017 at 1:53 PM, Jeroen Demeyer  wrote:
> 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 alternative way of testing Sage code in the flavour of
>> unit tests
>
>
> We have had this discussion before... which problem would that solve?
>
> Doctesting is just a tool. You can run the same tests as doctest or as
> py.test test: a test is just some code which is run. There is nothing
> magical about "unit testing" that it cannot be done using doctests.
>
> Before we add a new testing framework, I would like to see at least one
> compelling advantage of it.

I agree in part with both of you.  I think some kinds of code is
difficult to test without significant test harnessing that is hard to
set up in the doctest format.  This especially tends to be the case
with tests of code that touch external resources, such as networks or
databases, that you might prefer to mock for the purposes of unit
testing.  Fortunately I haven't personally run into too many examples
like that in Sage, but I'm sure they exist.  Doctests can also make
testing some numerical results tricky, but Sage's doctest checker has
already implemented the usual workarounds for that (parsing floats,
etc.)

As to whether or not private functions / methods should have their own
tests, I'm split.  I think the "EXAMPLES" section is genuinely useful,
even for code that only programmers will see.  But I have also seen
examples like Jeroen has mentioned of literally copy/pasting entire
test sequences just to satisfy this, which is completely pointless and
not useful for example purposes either.  I can't find a specific
example right now but it will be things like:

def public_function():
"""

"""

with some_context_manager_that_was_probably_added_later():
_private_implementation_of_public_function()

def _private_implementation_of_public_function():
"""

"""

and that's just silly.

Personally, when I'm writing unit tests, I will *rarely* write unit
tests specifically for private functions/methods if that code is
covered by the tests for public functions.  Although I'm not a TDD
evangelist, tests for the public functions tend to be a more valuable
use of one's time, because they ensure that the public interface works
as intended, and public interfaces are less subject to change.
Whereas private functions are usually implementation details that are
highly subject to change, and there are diminishing returns in writing
specific tests for them when they are covered by the public function
tests.

That said, there are cases where if a private function is complicated
enough on its own, or is used in a complicated way by functions that
are complicated on their own, sometimes it's worth having tests for
it.  One has to use their judgement, along with *line* profiling to
see if the most important bits are being covered.

If you're really concerned about keeping a number looking good, most
linting and profiling tools have a way to exclude lines (in Python
this is usually a comment like "# noqa") for those rare exceptions to
whatever rules you're otherwise trying to stick to.

-- 
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

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

[Marc Mezzarobba]

Kwankyu Lee wrote:
> G2. Write
> 
> if the lattice is reflexive ...
> 
> but don't write
> 
> if ``self`` is reflexive ...

X

-- 
Marc

-- 
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

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

[Marc Mezzarobba]

Kwankyu Lee wrote:
> G5. Write
> 
> OUTPUT:
> 
> - lattice
> 
> 
> but do not write
> 
> OUTPUT:
> 
> lattice

X

-- 
Marc

-- 
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

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

[Marc Mezzarobba]

Kwankyu Lee wrote:
> 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 reflexive.
> 
> nor (4)
> 
> Test if the lattice is reflexive.

X

-- 
Marc

-- 
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

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

[Marc Mezzarobba]

Kwankyu Lee wrote:
> G4. OUTPUT block is optional

+1

-- 
Marc

-- 
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

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

[Marc Mezzarobba]

Kwankyu Lee wrote:
> 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`

X

-- 
Marc

-- 
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

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

[Jori Mäntysalo]

On Thu, 18 May 2017, Vincent Delecroix wrote:


Yep, seems to be nicer. But maybe we should first see if we want to have
"test if..." -structure in function docstrings.


How is this different from the poll G3 where everybody seems to agree - -


I think that the poll is still open.

--
Jori Mäntysalo

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

[Kwankyu Lee]

On Thursday, May 18, 2017 at 10:59:35 AM UTC+2, vdelecroix wrote:
>
> On 18/05/2017 10:33, Jori Mäntysalo wrote: 
> > On Thu, 18 May 2017, Kwankyu Lee wrote: 
> > 
> >>   is_sectionally_complemented() | Return True if every interval 
> >>   from the bottom is complemented. 
> >> 
> >> I would write: 
> >> 
> >> is_sectionally_complemented() | Test if every interval from the bottom 
> is 
> >> complemented. 
> > 
> > Yep, seems to be nicer. But maybe we should first see if we want to have 
> > "test if..." -structure in function docstrings. 
>
> How is this different from the poll G3 where everybody seems to agree 
> that we should use 
>Return whether every interval from the bottom is complemented 
>
> ?! 
>

My suggestion was to his "index", which I thought a somewhat informal list 
of functions and descriptions about them. This is not my opinion about G3, 
and I respect the result of the poll G3.
 
 

-- 
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] splitting BRiAl

[Francois Bissey]

> On 18/05/2017, at 21:37, Jeroen Demeyer  wrote:
> 
> On 2017-05-18 11:25, Francois Bissey wrote:
>> Puzzled me for a while too. It doesn’t.
> 
> So you are saying that BRiAl consists of two *independent* parts which don't 
> interact at all? That by itself would increase the reasons for splitting. 
> Does Sage actually require both parts?
> 

OK I should elaborate. Polybori used to build a dynamic python library
(by that I mean something installed as 
local/lib/python2.7/polybori/dynamic/PyPolyBoRi.so).
And the python interface to polybori/brial first try to import sage.
If sage is present, sage’s interface to libbrial is used. If sage is not
present it will try load the aforementioned dynamic python library.

So at present they do interact, but exclusively through sage.

That dynamic python library hasn’t ever been build in any version
of brial.

It is quite possible to work to restore it or remove all the calling bits.
If restoring, it could completely be done python side with libbrial as a
dependency. 

-- 
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] splitting BRiAl

[Jeroen Demeyer]

On 2017-05-18 11:25, Francois Bissey wrote:

Puzzled me for a while too. It doesn’t.


So you are saying that BRiAl consists of two *independent* parts which 
don't interact at all? That by itself would increase the reasons for 
splitting. Does Sage actually require both parts?


--
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] splitting BRiAl

[Francois Bissey]

On 18/05/2017, at 21:24, Jeroen Demeyer  wrote:
> 
> On 2017-05-18 01:09, François Bissey wrote:
>> And I have a pure
>> python pybrial that install with a minimal setup.py.
> 
> If it's pure Python, then how does it access the libBRiAl library?
> 

Puzzled me for a while too. It doesn’t.

-- 
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] splitting BRiAl

[Jeroen Demeyer]

On 2017-05-18 01:09, François Bissey wrote:

And I have a pure
python pybrial that install with a minimal setup.py.


If it's pure Python, then how does it access the libBRiAl library?


--
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

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

[Vincent Delecroix]

On 18/05/2017 10:33, Jori Mäntysalo wrote:

On Thu, 18 May 2017, Kwankyu Lee wrote:


  is_sectionally_complemented() | Return True if every interval
  from the bottom is complemented.

I would write:

is_sectionally_complemented() | Test if every interval from the bottom is
complemented.


Yep, seems to be nicer. But maybe we should first see if we want to have
"test if..." -structure in function docstrings.


How is this different from the poll G3 where everybody seems to agree 
that we should use


  Return whether every interval from the bottom is complemented

?!

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@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

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

[Jori Mäntysalo]

On Thu, 18 May 2017, Kwankyu Lee wrote:


  is_sectionally_complemented() | Return True if every interval
  from the bottom is complemented.

I would write:

is_sectionally_complemented() | Test if every interval from the bottom is
complemented. 


Yep, seems to be nicer. But maybe we should first see if we want to have 
"test if..." -structure in function docstrings.


--
Jori Mäntysalo

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

[Kwankyu Lee]

>
>
> However, in the index I use 
>
> is_sectionally_complemented() | Return True if every interval from the 
> bottom is complemented. 
>

I would write:

is_sectionally_complemented() | Test if every interval from the bottom is 
complemented. 

-- 
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

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

[Kwankyu Lee]

>
> -1 
>
> See the first few lines of [1] where an equivalent of our ``True`` is 
> used (and therefore written in typewriter font)
>

(This is perhaps my last resistance; please bear with me :-) 

A technical question: is it possible to set our Sphinx so that we write in 
a docstring

Return True if something is False.

but the True and False are rendered in tt font (or even as links as you 
suggested). Then we could avoid cluttering files with lots of double quotes 
for True, False, and None, and use them mostly for arguments.
 

-- 
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 https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.