Sage: Ticket #17447: Clarify and complete documentation of function()
https://trac.sagemath.org/ticket/17447
<p>
The documentation of function() is incomplete and confusing.
For example, none of the methods described in <a href="http://www.sagemath.org/doc/reference/calculus/sage/symbolic/function_factory.html">http://www.sagemath.org/doc/reference/calculus/sage/symbolic/function_factory.html</a> show up when I type:
</p>
<pre class="wiki">function?
</pre><p>
The distinction between
</p>
<pre class="wiki">f = function('f')
</pre><p>
and
</p>
<pre class="wiki">f = function('f', x)
</pre><p>
is also not documented. See also <a class="new ticket" href="https://trac.sagemath.org/ticket/17445" title="enhancement: Document derivative operator and notations (new)">#17445</a> for sources of confusion. Need to explain what happens in the second case above (<code>f = function('f',x)</code>). A symbolic function <code>f</code> is first created and then overwritten by the expression <code>f</code>?
See the following example, where f is first an expression, then becomes redefined to a function in the background, but does not contain any information about its variables.
</p>
<pre class="wiki">sage: f = function('f', x); print type(f)
<type 'sage.symbolic.expression.Expression'>
sage: fx = function('f',x); print type(f)
<class 'sage.symbolic.function_factory.NewSymbolicFunction'>
sage: f.variables()
()
sage: fx.variables()
(x,)
</pre><p>
See <a class="ext-link" href="http://ask.sagemath.org/question/9932/how-to-substitute-a-function-within-derivatives/?answer=14752#post-id-14752"><span class="icon"></span>http://ask.sagemath.org/question/9932/how-to-substitute-a-function-within-derivatives/?answer=14752#post-id-14752</a> for a possible start at how to explain this, at least for those writing this.
</p>
en-usSagehttps://trac.sagemath.org/chrome/site/logo_sagemath_trac.png
https://trac.sagemath.org/ticket/17447
Trac 1.1.6kcrismanFri, 05 Dec 2014 14:09:19 GMTdescription changed
https://trac.sagemath.org/ticket/17447#comment:1
https://trac.sagemath.org/ticket/17447#comment:1
<ul>
<li><strong>description</strong>
modified (<a href="/ticket/17447?action=diff&version=1">diff</a>)
</li>
</ul>
TicketkcrismanFri, 05 Dec 2014 14:10:38 GMTdescription changed
https://trac.sagemath.org/ticket/17447#comment:2
https://trac.sagemath.org/ticket/17447#comment:2
<ul>
<li><strong>description</strong>
modified (<a href="/ticket/17447?action=diff&version=2">diff</a>)
</li>
</ul>
TicketnbruinFri, 05 Dec 2014 19:28:04 GMT
https://trac.sagemath.org/ticket/17447#comment:3
https://trac.sagemath.org/ticket/17447#comment:3
<p>
For the question about creation and overwriting:
</p>
<p>
The toplevel <code>function</code> has the sideeffect of inserting a binding in the global scope, just as the toplevel <code>var</code> does.
</p>
<pre class="wiki">sage: var('U')
U
sage: U
U
sage: function('f')
f
sage: f
f
</pre><p>
The library versions of these routines don't do that:
</p>
<pre class="wiki">sage: SR.var('V')
V
sage: V
NameError: name 'V' is not defined
sage: sage.symbolic.function_factory.function('g')
g
sage: g
NameError: name 'g' is not defined
</pre><p>
The intended use of the toplevel <code>function</code> is <em>not</em> to be assigned but to be called as a statement, just as <code>var</code>. There is plenty of documentation in sage that was written by people unaware of this fact (or possibly they think they're being helpful by providing code that doesn't return an error when used with the library versions of these functions)
</p>
<p>
As a result <code>x=var('x')</code> and <code>fx=function('f',x)</code> are quite ubiquitous in the docs. The former is fairly inocuous but the second, as you experience, has a rather nasty side effect. We're violating python's convention here: routines with side effects should return None.
</p>
<p>
I think this is the point where people usually give up fixing this mess (I have). Hopefully you will now follow through.
</p>
<p>
Note that we can probably not do more than document the issues, which is not going to fix much, because people won't read the doc, but then at least you can point them somewhere when they complain.
</p>
<p>
I suspect that Zimmerman's calculus book uses this stuff quite extensively, so deprecating/changing the current behaviour will likely lead to pushback from him, and probably rightly so.
</p>
<p>
(this is the kind of issue that earns sage the reputation of "implement now, design later")
</p>
TicketrwsThu, 25 Dec 2014 09:33:25 GMTcomponent changed
https://trac.sagemath.org/ticket/17447#comment:4
https://trac.sagemath.org/ticket/17447#comment:4
<ul>
<li><strong>component</strong>
changed from <em>symbolics</em> to <em>documentation</em>
</li>
</ul>
TicketschymansTue, 06 Jan 2015 22:26:07 GMT
https://trac.sagemath.org/ticket/17447#comment:5
https://trac.sagemath.org/ticket/17447#comment:5
<p>
Awesome, thank you, Nils. These things always confused me, so I'm relieved to hear that they should be avoided! Even the documentation of var is full of such examples:
</p>
<pre class="wiki">sage: x = var('x', domain=RR); x; x.conjugate()
x
x
sage: y = var('y', domain='real'); y.conjugate()
y
sage: y = var('y', domain='positive'); y.abs()
y
Custom latex expression can be assigned to variable:
sage: x = var('sui', latex_name="s_{u,i}"); x._latex_()
's_{u,i}'
</pre><p>
Should we change these examples, too?
</p>
TicketnbruinThu, 08 Jan 2015 22:53:09 GMTbranch set
https://trac.sagemath.org/ticket/17447#comment:6
https://trac.sagemath.org/ticket/17447#comment:6
<ul>
<li><strong>branch</strong>
set to <em>u/nbruin/clarify_and_complete_documentation_of_function__</em>
</li>
</ul>
<p>
Don't base any other work on this branch just yet, since it's likely to be rebased. I have deprecated the use of <code>function('f',x)</code> in favour of using <code>function('f')(x)</code>. It's hardly longer to type and much less ambiguous. Otherwise, it seems that the documentation here is actually pretty accurate, apart from being terse. As soon as the objects returned by <code>function('f')</code> are consistent, I think users will be forced to learn the (now clear) semantics pretty quickly.
</p>
<p>
The object returned by <code>function(f)</code> doesn't allow symbolic operations on it, so people will quickly find they need to evaluate it in order to get a symbolic expression.
</p>
<p>
I haven't changed all doctests to take into account the deprecation, but I've done some files to show the impact of the change (seems relatively minor).
</p>
TicketnbruinThu, 08 Jan 2015 23:01:32 GMTstatus changed; commit set
https://trac.sagemath.org/ticket/17447#comment:7
https://trac.sagemath.org/ticket/17447#comment:7
<ul>
<li><strong>status</strong>
changed from <em>new</em> to <em>needs_review</em>
</li>
<li><strong>commit</strong>
set to <em>fa3ebd6645eb2cae45c2218628eaa1d984f16506</em>
</li>
</ul>
<p>
Not really ready for *review* but is ready for input. And is mainly ready for someone else to rewrite documentation properly. People CC'd on this ticket look like good candidates to do so.
</p>
<hr />
<p>
New commits:
</p>
<table class="wiki">
<tr><td><a class="ext-link" href="http://git.sagemath.org/sage.git/commit/?id=b41248b13e18744ab9902adde9b7740832bb1724"><span class="icon"></span>b41248b</a></td><td><code>trac 17447: Deprecation of function('f',x) in favour of function('f')(x)</code>
</td></tr><tr><td><a class="ext-link" href="http://git.sagemath.org/sage.git/commit/?id=fa3ebd6645eb2cae45c2218628eaa1d984f16506"><span class="icon"></span>fa3ebd6</a></td><td><code>trac 17447: Doctest changes to reflect deprecation of function('f',x)</code>
</td></tr></table>
<hr />
<p>
note that the doctest that apparently got removed in b41248b in reality gets moved to var.pyx because it tests the toplevel <code>function</code>, not the library <code>function</code>
</p>
TicketschymansSun, 11 Jan 2015 22:13:06 GMT
https://trac.sagemath.org/ticket/17447#comment:8
https://trac.sagemath.org/ticket/17447#comment:8
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/17447#comment:7" title="Comment 7">nbruin</a>:
</p>
<blockquote class="citation">
<p>
Not really ready for *review* but is ready for input. And is mainly ready for someone else to rewrite documentation properly. People CC'd on this ticket look like good candidates to do so.
</p>
<hr />
<p>
New commits:
</p>
<table class="wiki">
<tr><td><a class="ext-link" href="http://git.sagemath.org/sage.git/commit/?id=b41248b13e18744ab9902adde9b7740832bb1724"><span class="icon"></span>b41248b</a></td><td><code>trac 17447: Deprecation of function('f',x) in favour of function('f')(x)</code>
</td></tr><tr><td><a class="ext-link" href="http://git.sagemath.org/sage.git/commit/?id=fa3ebd6645eb2cae45c2218628eaa1d984f16506"><span class="icon"></span>fa3ebd6</a></td><td><code>trac 17447: Doctest changes to reflect deprecation of function('f',x)</code>
</td></tr></table>
<hr />
<p>
note that the doctest that apparently got removed in b41248b in reality gets moved to var.pyx because it tests the toplevel <code>function</code>, not the library <code>function</code>
</p>
</blockquote>
<p>
This makes it a lot clearer to me now. Just a minor thing:
In one of the examples, I would replace
</p>
<pre class="wiki">sage: cr = function('cr')
sage: f = cr(a)
</pre><p>
by
</p>
<pre class="wiki">sage: function('cr')
sage: f = cr(a)
</pre><p>
which in my understanding does the same but is shorter and makes clear that <code>function('cr')</code> does already create a symbolic function called <code>cr</code>. Otherwise, one may be surprised to create two functions by typing e.g. <code>cr1 = function('cr')</code>.
</p>
TicketnbruinMon, 12 Jan 2015 00:12:42 GMT
https://trac.sagemath.org/ticket/17447#comment:9
https://trac.sagemath.org/ticket/17447#comment:9
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/17447#comment:8" title="Comment 8">schymans</a>:
</p>
<blockquote class="citation">
<p>
This makes it a lot clearer to me now. Just a minor thing:
In one of the examples, I would replace
</p>
<pre class="wiki">sage: cr = function('cr')
sage: f = cr(a)
</pre></blockquote>
<p>
At least one occurrence of that is in the doctest of <code>sage.symbolic.function_factory.function</code>, which (now) goes out of its way to import <em>that</em> function, which does <em>not</em> have the side-effect of mutating the global scope, as documented. So the assignment is actually necessary.
</p>
<p>
Another independent point: the top-level <code>function</code> does refer to <code>sage.symbolic.function_factory.function</code>, but perhaps should do so more explicitly, if possible with a hyperlink. The examples on the latter are a little more elaborate, so someone who wants to read up on <code>function</code> (and would probably find the top-level documentation first via <code>sage: function?</code>). I don't know how to make hyperlinks to other documentation in sage's docstrings.
</p>
TicketncohenTue, 13 Jan 2015 08:18:40 GMTstatus changed
https://trac.sagemath.org/ticket/17447#comment:10
https://trac.sagemath.org/ticket/17447#comment:10
<ul>
<li><strong>status</strong>
changed from <em>needs_review</em> to <em>needs_work</em>
</li>
</ul>
<p>
There are broken doctests in the 'doc' folder
</p>
<pre class="wiki">sage -t --long prep/Quickstarts/Differential-Equations.rst # 1 doctest failed
sage -t --long tutorial/tour_algebra.rst # 1 doctest failed
sage -t --long constructions/calculus.rst # 1 doctest failed
</pre><p>
Nathann
</p>
TicketnbruinTue, 13 Jan 2015 16:23:33 GMT
https://trac.sagemath.org/ticket/17447#comment:11
https://trac.sagemath.org/ticket/17447#comment:11
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/17447#comment:10" title="Comment 10">ncohen</a>:
</p>
<blockquote class="citation">
<p>
There are broken doctests in the 'doc' folder
</p>
</blockquote>
<p>
Yes, and that is not the only place. First we need to see if there is any good reason why <code>function('f',x)</code> is preferable over <code>function('f')(x)</code>, of if we can get away with deprecating this confusing construction. And then someone should take a look at the doc to see if it needs further improvement. You're on a doc revamping binge, so this might just be the task for you!
</p>
TicketncohenTue, 13 Jan 2015 16:26:46 GMT
https://trac.sagemath.org/ticket/17447#comment:12
https://trac.sagemath.org/ticket/17447#comment:12
<blockquote class="citation">
<p>
You're on a doc revamping binge, so this might just be the task for you!
</p>
</blockquote>
<p>
I am afraid that you will have to find somebody else. I never used Sage's symbolics.
</p>
<p>
Nathann
</p>
TickettmonteilFri, 30 Jan 2015 16:45:44 GMTcc changed
https://trac.sagemath.org/ticket/17447#comment:13
https://trac.sagemath.org/ticket/17447#comment:13
<ul>
<li><strong>cc</strong>
<em>tmonteil</em> added
</li>
</ul>
TicketrwsSun, 01 Feb 2015 16:41:08 GMTbranch changed
https://trac.sagemath.org/ticket/17447#comment:14
https://trac.sagemath.org/ticket/17447#comment:14
<ul>
<li><strong>branch</strong>
changed from <em>u/nbruin/clarify_and_complete_documentation_of_function__</em> to <em>public/17447</em>
</li>
</ul>
TicketrwsSun, 01 Feb 2015 16:54:44 GMTcommit changed
https://trac.sagemath.org/ticket/17447#comment:15
https://trac.sagemath.org/ticket/17447#comment:15
<ul>
<li><strong>commit</strong>
changed from <em>fa3ebd6645eb2cae45c2218628eaa1d984f16506</em> to <em>e6a35343e5f712b88a5a9a80abd4e9302879c187</em>
</li>
</ul>
<p>
That fixes the three above marked doctests.
</p>
<hr />
<p>
New commits:
</p>
<table class="wiki">
<tr><td><a class="ext-link" href="http://git.sagemath.org/sage.git/commit/?id=e3ef9195793c87d54b088823e06438e647cc6d89"><span class="icon"></span>e3ef919</a></td><td><code>Merge branch 'develop' into t/17447/clarify_and_complete_documentation_of_function__</code>
</td></tr><tr><td><a class="ext-link" href="http://git.sagemath.org/sage.git/commit/?id=e6a35343e5f712b88a5a9a80abd4e9302879c187"><span class="icon"></span>e6a3534</a></td><td><code>17447: reviewer's patch: fix rst doctests</code>
</td></tr></table>
TicketgitMon, 02 Feb 2015 08:28:20 GMTcommit changed
https://trac.sagemath.org/ticket/17447#comment:16
https://trac.sagemath.org/ticket/17447#comment:16
<ul>
<li><strong>commit</strong>
changed from <em>e6a35343e5f712b88a5a9a80abd4e9302879c187</em> to <em>4585e74063e81a8c332a500d016e837069edf8eb</em>
</li>
</ul>
<p>
Branch pushed to git repo; I updated commit sha1. New commits:
</p>
<table class="wiki">
<tr><td><a class="ext-link" href="http://git.sagemath.org/sage.git/commit/?id=4585e74063e81a8c332a500d016e837069edf8eb"><span class="icon"></span>4585e74</a></td><td><code>17447: fix rest of doctests</code>
</td></tr></table>
TicketrwsMon, 02 Feb 2015 08:33:30 GMTreviewer set
https://trac.sagemath.org/ticket/17447#comment:17
https://trac.sagemath.org/ticket/17447#comment:17
<ul>
<li><strong>reviewer</strong>
set to <em>Ralf Stephan</em>
</li>
</ul>
<p>
These are the remaining doctest fixes coming from <code>make ptestlong</code>. I have reviewed and found fine the commits up to mine, so following reviewers can skip that.
</p>
<blockquote class="citation">
<p>
And then someone should take a look at the doc to see if it needs further improvement.
</p>
</blockquote>
TicketkcrismanTue, 03 Feb 2015 01:33:35 GMTcc changed
https://trac.sagemath.org/ticket/17447#comment:18
https://trac.sagemath.org/ticket/17447#comment:18
<ul>
<li><strong>cc</strong>
<em>zimmerma</em> added
</li>
</ul>
<blockquote class="citation">
<p>
I suspect that Zimmerman's calculus book uses this stuff quite extensively, so deprecating/changing the current behaviour will likely lead to pushback from him, and probably rightly so.
</p>
</blockquote>
<p>
Cc:ing him for that reason. Though we have already had a few other discussions on Trac about the need to update our tests while not maintaining exact compatibility. Since they don't (yet) raise errors, but apparently only the deprecation warning, should we maybe update the tests (in that part only) to have the deprecation warning returned? Note that I don't believe the deprecation warning is even doctested, which is a no-no :)
</p>
<p>
Also, does the current branch actually "clarify and complete documentation of function"? It looks like it mostly fixes doctests.
</p>
<p>
Another change not doctested is
</p>
<pre class="wiki"> if is_SymbolicVariable(dvar):
- raise ValueError("You have to declare dependent variable as a function, eg. y=function('y',x)")
+ raise ValueError("You have to declare dependent variable as a function evaluated at the independent variable, eg. y=function('y')(x)")
</pre><p>
which I think happens twice.
</p>
<p>
I'm <em>still</em> not sure I even understand some of the subtle differences. Are there occasions where the old behavior was "right" in the sense that one wanted that returned, and have we shown how to get that object? What about the ask.sagemath question?
</p>
<p>
All that to say that nonetheless it will be great to have a unified interface on this, if that is really the right thing to do, which from the comments it apparently is.
</p>
TicketnbruinTue, 03 Feb 2015 02:09:13 GMT
https://trac.sagemath.org/ticket/17447#comment:19
https://trac.sagemath.org/ticket/17447#comment:19
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/17447#comment:18" title="Comment 18">kcrisman</a>:
</p>
<blockquote class="citation">
<p>
Also, does the current branch actually "clarify and complete documentation of function"? It looks like it mostly fixes doctests.
</p>
</blockquote>
<p>
I think there are two things that are/were confusing:
</p>
<ul><li><code>function('f',x)</code> returns something that is not, according to our definition, a function (e.g., it cannot be evaluated ("called") in a non-ambiguous way and hence triggers a deprecation warning)).
</li><li>The top-level <code>function</code> makes a binding in the global namespace and returns a value. The two were different.
</li></ul><p>
With the proposed patch, <code>function('f',x)</code> is deprecated, so number 1 gets eliminated and number 2 is less confusing because, while it still injects something in the namespace, the value it returns is always the same as what it injects.
</p>
<p>
When I read the documentation of <code>sage.symbolic.function_factory.function</code>, I actually thought it described what happens fairly correctly, and it has good examples. Hence I did not feel the need to add to it. The top-level <code>function</code> documentation is rather sparse, so that could use expansion. However, we do not want to repeat ourselves, so perhaps it should just contain a clear pointer (hyperlink?) to the documentation of <code>sage.symbolic.function_factory.function</code>. I don't know how to do that, so please go ahead and improve that bit. You are excellently qualified to produce extensive and understandable documentation for the target audience of these functions.
</p>
<blockquote class="citation">
<p>
Another change not doctested is
</p>
<pre class="wiki"> if is_SymbolicVariable(dvar):
- raise ValueError("You have to declare dependent variable as a function, eg. y=function('y',x)")
+ raise ValueError("You have to declare dependent variable as a function evaluated at the independent variable, eg. y=function('y')(x)")
</pre><p>
which I think happens twice.
</p>
</blockquote>
<p>
These messages weren't doctested before either. If you feel the projects benefits from such administrations, go ahead.
</p>
<blockquote class="citation">
<p>
I'm <em>still</em> not sure I even understand some of the subtle differences. Are there occasions where the old behavior was "right" in the sense that one wanted that returned, and have we shown how to get that object?
</p>
</blockquote>
<p>
In my opinion: no. In all cases, <code>function('f')(x)</code> is much clearer and not much longer than <code>function('f',x)</code>. There are *many* tickets and questions about people getting tripped up by the fact that a function called function doesn't return a function.
</p>
<blockquote class="citation">
<p>
What about the ask.sagemath question?
</p>
</blockquote>
<p>
In my opinion, that's another thing to document. However, the confusion about function not returning a function definitely contributed to the confusion about how to use substitute_function.
</p>
TicketkcrismanTue, 03 Feb 2015 02:24:53 GMT
https://trac.sagemath.org/ticket/17447#comment:20
https://trac.sagemath.org/ticket/17447#comment:20
<blockquote class="citation">
<p>
The top-level function documentation is rather sparse, so that could use expansion.
</p>
</blockquote>
<p>
Yes, this is what I meant. Hyperlink is tricky - not per se, but in command line and even sagenb it's not as useful. So I figure at least a little more in the top-level and then the hyperlink (assuming that file is in fact already in the documentation!).
</p>
<blockquote class="citation">
<p>
You are excellently qualified to produce extensive and understandable documentation for the target audience of these functions.
</p>
</blockquote>
<p>
That is very kind, I will see; this one is lower on my priority list but definitely important.
</p>
<blockquote class="citation">
<p>
If you feel the projects benefits from such administrations, go ahead.
</p>
</blockquote>
<p>
Well, I've found it does. I guess I will ask you to review it if I do that :-)
</p>
<blockquote class="citation">
<p>
In my opinion, that's another thing to document. However, the confusion about function not returning a function definitely contributed to the confusion about how to use substitute_function.
</p>
</blockquote>
<p>
Yes.
</p>
TicketzimmermaTue, 03 Feb 2015 07:52:41 GMT
https://trac.sagemath.org/ticket/17447#comment:21
https://trac.sagemath.org/ticket/17447#comment:21
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/17447#comment:18" title="Comment 18">kcrisman</a>:
</p>
<blockquote class="citation">
<blockquote class="citation">
<p>
I suspect that Zimmerman's calculus book uses this stuff quite extensively, so deprecating/changing the current behaviour will likely lead to pushback from him, and probably rightly so.
</p>
</blockquote>
<p>
Cc:ing him for that reason.
</p>
</blockquote>
<p>
thanks, however I gave up trying to maintain compatibility with the book, since there
are already many examples from the book that we put as doctests in Sage, and which were changed afterwards...
</p>
TicketkcrismanMon, 09 Mar 2015 23:17:13 GMT
https://trac.sagemath.org/ticket/17447#comment:22
https://trac.sagemath.org/ticket/17447#comment:22
<p>
Here is another example of something confusing.
</p>
<p>
<a class="ext-link" href="http://ask.sagemath.org/question/26114/why-is-basic-arithmetic-disallowed-on-symbolic-functions/"><span class="icon"></span>http://ask.sagemath.org/question/26114/why-is-basic-arithmetic-disallowed-on-symbolic-functions/</a>
</p>
TicketnbruinTue, 10 Mar 2015 01:13:15 GMT
https://trac.sagemath.org/ticket/17447#comment:23
https://trac.sagemath.org/ticket/17447#comment:23
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/17447#comment:22" title="Comment 22">kcrisman</a>:
</p>
<blockquote class="citation">
<p>
Here is another example of something confusing.
</p>
<p>
<a class="ext-link" href="http://ask.sagemath.org/question/26114/why-is-basic-arithmetic-disallowed-on-symbolic-functions/"><span class="icon"></span>http://ask.sagemath.org/question/26114/why-is-basic-arithmetic-disallowed-on-symbolic-functions/</a>
</p>
</blockquote>
<p>
I think that's another issue. The problem there is that global namespace <code>var</code> and <code>function</code> return a value <em>as well as</em> insert something into the namespace. That's counter to python custom (routines that mutate state normally return <code>None</code>. Compare <code>L.sort()</code> and <code>sorted(L)</code>. There are exceptions: <code>L.pop()</code>).
</p>
<p>
Initially it seems pedantic to enforce such rules in a computer algebra system as well, but the many problems it causes suggests it's not. Can we have <code>declare_var('x,y')</code> and <code>declare_function('f')</code> for the mutating stuff and just have <code>var('x')</code> and <code>function('f')</code> for the normal stuff? That ship has probably sailed already.
</p>
TicketschymansWed, 11 Mar 2015 07:45:19 GMT
https://trac.sagemath.org/ticket/17447#comment:24
https://trac.sagemath.org/ticket/17447#comment:24
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/17447#comment:23" title="Comment 23">nbruin</a>:
</p>
<blockquote class="citation">
<p>
Can we have <code>declare_var('x,y')</code> and <code>declare_function('f')</code> for the mutating stuff and just have <code>var('x')</code> and <code>function('f')</code> for the normal stuff? That ship has probably sailed already.
</p>
</blockquote>
<p>
That would be awesome! Much more consistent AND flexible. +1 from me.
</p>
TicketrwsSat, 14 Mar 2015 15:49:42 GMT
https://trac.sagemath.org/ticket/17447#comment:25
https://trac.sagemath.org/ticket/17447#comment:25
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/17447#comment:23" title="Comment 23">nbruin</a>:
</p>
<blockquote class="citation">
<p>
I think that's another issue. The problem there is that global namespace <code>var</code> and <code>function</code> return a value <em>as well as</em> insert something into the namespace. That's counter to python custom (routines that mutate state normally return <code>None</code>. Compare <code>L.sort()</code> and <code>sorted(L)</code>. There are exceptions: <code>L.pop()</code>).
</p>
<p>
Initially it seems pedantic to enforce such rules in a computer algebra system as well, but the many problems it causes suggests it's not. Can we have <code>declare_var('x,y')</code> and <code>declare_function('f')</code> for the mutating stuff and just have <code>var('x')</code> and <code>function('f')</code> for the normal stuff? That ship has probably sailed already.
</p>
</blockquote>
<p>
See <a class="new ticket" href="https://trac.sagemath.org/ticket/17958" title="defect: implement declare_var, deprecate (None)var (new)">#17958</a> for <code>declare_var</code> and no, this is still a good idea.
</p>
TicketmmezzarobbaSun, 15 Mar 2015 10:08:29 GMT
https://trac.sagemath.org/ticket/17447#comment:26
https://trac.sagemath.org/ticket/17447#comment:26
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/17447#comment:3" title="Comment 3">nbruin</a>:
</p>
<blockquote class="citation">
<p>
I suspect that Zimmerman's calculus book uses this stuff quite extensively, so deprecating/changing the current behaviour will likely lead to pushback from him, and probably rightly so.
</p>
</blockquote>
<p>
I'm not sure about <code>function()</code> and have little time to check now, but regarding <code>var()</code>, I think we tried to always use <code>x = SR.var('x')</code>.
</p>
<p>
And IMO, the version of <code>var</code> that injects a variable in the global namespace should simply be deprecated, or possibly moved to <code>sage.ext.inteactive_constructors_c</code> if someone really care about it.
</p>
TicketrwsSun, 12 Apr 2015 15:15:31 GMTstatus, milestone changed
https://trac.sagemath.org/ticket/17447#comment:27
https://trac.sagemath.org/ticket/17447#comment:27
<ul>
<li><strong>status</strong>
changed from <em>needs_work</em> to <em>needs_review</em>
</li>
<li><strong>milestone</strong>
changed from <em>sage-6.5</em> to <em>sage-6.6</em>
</li>
</ul>
<p>
So, <a class="ticket" href="https://trac.sagemath.org/ticket/17447#comment:17" title="Comment 17">comment:17</a> gave part of a review. Can someone please complete it?
</p>
TicketrwsThu, 11 Jun 2015 07:36:35 GMTstatus changed
https://trac.sagemath.org/ticket/17447#comment:28
https://trac.sagemath.org/ticket/17447#comment:28
<ul>
<li><strong>status</strong>
changed from <em>needs_review</em> to <em>needs_work</em>
</li>
</ul>
<pre class="wiki">sage -t --long src/sage/symbolic/expression.pyx # 1 doctest failed
sage -t --long src/sage/tests/french_book/calculus_doctest.py # 1 doctest failed
sage -t --long src/doc/pt/tutorial/tour_algebra.rst # 1 doctest failed
sage -t --long src/sage/combinat/integer_vector.py # 1 doctest failed
</pre>
TicketgitMon, 09 Nov 2015 23:57:23 GMTcommit changed
https://trac.sagemath.org/ticket/17447#comment:29
https://trac.sagemath.org/ticket/17447#comment:29
<ul>
<li><strong>commit</strong>
changed from <em>4585e74063e81a8c332a500d016e837069edf8eb</em> to <em>bdc154391e7ce6ceca1226f341ab62579bc3f4ee</em>
</li>
</ul>
<p>
Branch pushed to git repo; I updated commit sha1. New commits:
</p>
<table class="wiki">
<tr><td><a class="ext-link" href="http://git.sagemath.org/sage.git/commit/?id=7956412cef63579521e6f8673a096c9952609a38"><span class="icon"></span>7956412</a></td><td><code>Merge branch 'public/17447' of git://trac.sagemath.org/sage into public/17447</code>
</td></tr><tr><td><a class="ext-link" href="http://git.sagemath.org/sage.git/commit/?id=bdc154391e7ce6ceca1226f341ab62579bc3f4ee"><span class="icon"></span>bdc1543</a></td><td><code>trac 17447: further doctest adjustments</code>
</td></tr></table>
TicketgitTue, 10 Nov 2015 01:17:15 GMTcommit changed
https://trac.sagemath.org/ticket/17447#comment:30
https://trac.sagemath.org/ticket/17447#comment:30
<ul>
<li><strong>commit</strong>
changed from <em>bdc154391e7ce6ceca1226f341ab62579bc3f4ee</em> to <em>7c029f3c98032a985c2ca0329dfe940271e9b86b</em>
</li>
</ul>
<p>
Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:
</p>
<table class="wiki">
<tr><td><a class="ext-link" href="http://git.sagemath.org/sage.git/commit/?id=7c029f3c98032a985c2ca0329dfe940271e9b86b"><span class="icon"></span>7c029f3</a></td><td><code>trac 17447: further doctest adjustments</code>
</td></tr></table>
TicketnbruinTue, 10 Nov 2015 01:18:57 GMTstatus changed
https://trac.sagemath.org/ticket/17447#comment:31
https://trac.sagemath.org/ticket/17447#comment:31
<ul>
<li><strong>status</strong>
changed from <em>needs_work</em> to <em>needs_review</em>
</li>
</ul>
TicketnbruinTue, 10 Nov 2015 18:35:02 GMTstatus, reviewer, milestone, author changed
https://trac.sagemath.org/ticket/17447#comment:32
https://trac.sagemath.org/ticket/17447#comment:32
<ul>
<li><strong>status</strong>
changed from <em>needs_review</em> to <em>positive_review</em>
</li>
<li><strong>reviewer</strong>
changed from <em>Ralf Stephan</em> to <em>Ralf Stephan, Nils Bruin</em>
</li>
<li><strong>milestone</strong>
changed from <em>sage-6.6</em> to <em>sage-6.10</em>
</li>
<li><strong>author</strong>
changed from <em>schymans</em> to <em>Nils Bruin, Ralf Stephan</em>
</li>
</ul>
<p>
OK, comments <a class="closed ticket" href="https://trac.sagemath.org/ticket/17" title="defect: Inconsistent files generated when loading .sage files. (closed: fixed)">#17</a> and <a class="closed ticket" href="https://trac.sagemath.org/ticket/27" title="enhancement: Move the function dual_eigenvector in sage/hecke/module.py to (closed: invalid)">#27</a> provide a positive review of the first bit. I give a largely positive review to Ralf's doctest adjustments. There was one overcorrection in <code>french_book/calculus_doctest.py</code> that I corrected. The other changes were just parallel corrections to different translations of one document that have been introduced since the last time this ticket was updated.
</p>
<p>
patchbot is happy and I think all code is positively reviewed now. Ready for merge!
</p>
TicketvbraunWed, 11 Nov 2015 19:40:44 GMTstatus, branch changed; resolution set
https://trac.sagemath.org/ticket/17447#comment:33
https://trac.sagemath.org/ticket/17447#comment:33
<ul>
<li><strong>status</strong>
changed from <em>positive_review</em> to <em>closed</em>
</li>
<li><strong>resolution</strong>
set to <em>fixed</em>
</li>
<li><strong>branch</strong>
changed from <em>public/17447</em> to <em>7c029f3c98032a985c2ca0329dfe940271e9b86b</em>
</li>
</ul>
Ticket