Opened 3 years ago

Closed 3 years ago

#24878 closed defect (fixed)

Improve function? docstring

Reported by: rws Owned by:
Priority: major Milestone: sage-8.2
Component: documentation Keywords:
Cc: Merged in:
Authors: Ralf Stephan Reviewers: Sébastien Labbé
Report Upstream: N/A Work issues:
Branch: 9be43fd (Commits) Commit: 9be43fdca23ea8f620a429ff2c2ae17f13f24a8a
Dependencies: Stopgaps:

Description

The function function() from symbolic/function_factory.py allows to create symbolic functions on the command line, and it has an excellent docstring which is not shown with function? because the function is wrapped by function() from calculus/var.pyx. Part of the var function needs to be in Cython for specific reason.

This ticket moves the global function to the one in function_factory.py, leaving the part that needs to be in Cython inside var.pyx, merging docstrings, and so making it all accessible with function?.

Change History (12)

comment:1 Changed 3 years ago by rws

Work on this uncovered that many doctests weren't adapted to the deprecation ticket #17447 but passed nonetheless for some reason.

comment:2 Changed 3 years ago by jdemeyer

Why not simply copy the good docstring to the function function in src/sage/calcular/var.pyx? Seems like the simplest solution...

comment:3 Changed 3 years ago by rws

  • Branch set to u/rws/function__shows_wrong_docstring

comment:4 Changed 3 years ago by rws

  • Authors set to Ralf Stephan
  • Commit set to a54380b1a582e3dfc7e53d42a037ede35ebbcc43
  • Status changed from new to needs_review
  • Summary changed from function? shows wrong docstring to Improve function? docstring

So I merged the docstrings.


New commits:

a54380b24878: improve function? docstring

comment:5 Changed 3 years ago by slabbe

  • Status changed from needs_review to needs_work

The patchbot shows failing tests that seems related to the branch:

sage -t --long src/sage/calculus/var.pyx
**********************************************************************
File "src/sage/calculus/var.pyx", line 219, in sage.calculus.var.function
Failed example:
    g.substitute_function(cr, cos)
Exception raised:
    Traceback (most recent call last):
      File "/home/patchbot/sage-patchbot/local/lib/python2.7/site-packages/sage/doctest/forker.py", line 551, in _run
        self.compile_and_execute(example, compiler, test.globs)
      File "/home/patchbot/sage-patchbot/local/lib/python2.7/site-packages/sage/doctest/forker.py", line 961, in compile_and_execute
        exec(compiled, globs)
      File "<doctest sage.calculus.var.function[4]>", line 1, in <module>
        g.substitute_function(cr, cos)
    NameError: name 'g' is not defined
**********************************************************************
File "src/sage/calculus/var.pyx", line 222, in sage.calculus.var.function
Failed example:
    g.substitute_function(cr, (sin(x) + cos(x)).function(x))
Exception raised:
    Traceback (most recent call last):
      File "/home/patchbot/sage-patchbot/local/lib/python2.7/site-packages/sage/doctest/forker.py", line 551, in _run
        self.compile_and_execute(example, compiler, test.globs)
      File "/home/patchbot/sage-patchbot/local/lib/python2.7/site-packages/sage/doctest/forker.py", line 961, in compile_and_execute
        exec(compiled, globs)
      File "<doctest sage.calculus.var.function[5]>", line 1, in <module>
        g.substitute_function(cr, (sin(x) + cos(x)).function(x))
    NameError: name 'g' is not defined
**********************************************************************
1 item had failures:
   2 of  65 in sage.calculus.var.function
    [95 tests, 2 failures, 1.47 s]

comment:6 Changed 3 years ago by git

  • Commit changed from a54380b1a582e3dfc7e53d42a037ede35ebbcc43 to 6519e9c2aab38b9667b11d0c52d6f18d3573ec3e

Branch pushed to git repo; I updated commit sha1. New commits:

28d04e8Merge branch 'develop' into t/24878/function__shows_wrong_docstring
6519e9cfix doctests

comment:7 Changed 3 years ago by rws

  • Status changed from needs_work to needs_review

comment:8 Changed 3 years ago by slabbe

I would start the EXAMPLES with this one:

We create a formal function called supersin ::

[...]

and I would put the following block

   In Sage 4.0, basic arithmetic with unevaluated functions is no
   longer supported:

      sage: x = var('x')
      sage: f = function('f')
      sage: 2*f
      Traceback (most recent call last):
      ...
      TypeError: unsupported operand parent(s) for *: 'Integer Ring' and '<class
 'sage.symbolic.function_factory.NewSymbolicFunction'>'

   You now need to evaluate the function in order to do the
   arithmetic:

      sage: 2*f(x)
      2*f(x)

   In Sage 4.0, you need to use "substitute_function()" to replace all
   occurrences of a function with another:

      sage: var('a, b')
      (a, b)
      sage: cr = function('cr')
      sage: f = cr(a)
      sage: g = f.diff(a).integral(b)
      sage: g
      b*diff(cr(a), a)
      sage: g.substitute_function(cr, cos)
      -b*sin(a)

      sage: g.substitute_function(cr, (sin(x) + cos(x)).function(x))
      b*(cos(a) - sin(a))

somewhere more below. Do you agree?

comment:9 Changed 3 years ago by rws

Agreed. Please go ahead.

comment:10 Changed 3 years ago by slabbe

  • Branch changed from u/rws/function__shows_wrong_docstring to u/slabbe/24878
  • Commit changed from 6519e9c2aab38b9667b11d0c52d6f18d3573ec3e to 9be43fdca23ea8f620a429ff2c2ae17f13f24a8a
  • Reviewers set to Sébastien Labbé

Feel free to change the status to positive review if you agree with the commit.


New commits:

ba802f6Merge branch 'u/rws/function__shows_wrong_docstring' of trac.sagemath.org:sage into 24878
9be43fd24878: moving technical doctests below

comment:11 Changed 3 years ago by rws

  • Status changed from needs_review to positive_review

Thanks.

comment:12 Changed 3 years ago by vbraun

  • Branch changed from u/slabbe/24878 to 9be43fdca23ea8f620a429ff2c2ae17f13f24a8a
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.