Opened 13 years ago

Closed 12 years ago

#4405 closed defect (fixed)

[with patch, positive review] double/single quotation marks in docstring

Reported by: mvngu Owned by: mhansen
Priority: minor Milestone: sage-3.3
Component: user interface Keywords: docstring, triple ''', triple """
Cc: kcrisman Merged in:
Authors: Reviewers:
Report Upstream: Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Status badges

Description

At this sage-support thread, kcrisman reported the following problem with single quotation marks in docstring:

I came across some very strange behavior recently regarding docstrings
in functions.  In the notebook in 3.2.alpha0 and 3.0.6, putting an
apostrophe in the docstring causes various bugs.  It doesn't have to
be in any particular spot, as far as I can tell; in fact, it took a
long time to pinpoint this as the source of the problem!

More precisely, it seems to cause the preparser to turn off or
something, because it disallows the following (in the function
definition):
f(x)=x^3
because of the f(x), and
f=x^3
because of the ^ used instead of ** (the error message for the first
is very mysterious at times, but the second one is always clear when
you try to use the function).

I can post a link to a worksheet if it's really necessary, but
hopefully this will be enough for someone to help.  I checked Sage and
Python docs about documentation strings, but couldn't find anything
about it being bad to have apostrophes; in fact, some Sage docstrings
have them (e.g. for declaring variables).  I didn't try this in the
command line, so it is possible it's only a notebook issue.

Some basic experimentation reveals that it's likely to be caused by the use of single quotation marks in docstring from within the console and notebook. However, the reported error as described by kcrisman seems to go away when double quotation marks are used instead of single quotation marks:

OK, here's my experimentation from within the console sage-3.1.4, x86
machine, Debian 5.0 Lenny (testing):

Yep, I received a similar error as you described:

sage: def foo():
....:     '''
....:     What's up with this? x^3
....:     '''
....:     f(x) = x^3
------------------------------------------------------------
  File "<ipython console>", line 5
SyntaxError: can't assign to function call (<ipython console>, line 5)

John's suggestion about replacing the ''' with r''' results in the same error:

sage: def foo():
....:     r'''
....:     What's up with this? x^3
....:     '''
....:     f(x) = x^3
------------------------------------------------------------
  File "<ipython console>", line 5
SyntaxError: can't assign to function call (<ipython console>, line 5)

As Simon has said, the error seems to go away when I used triple "
(double quotation mark, not single quotation mark), which I normally
do anyway whenever I write docstring. But using triple ''' with or
without the leading r, and with or without the question mark, resulted
in a siimilar error:

sage: def foo():
....:     '''
....:     What's up with this? x^3
....:     '''
....:     f(x) = x^3
------------------------------------------------------------
  File "<ipython console>", line 5
SyntaxError: can't assign to function call (<ipython console>, line 5)

sage: def foo():
....:     r'''
....:     What's up here x^3
....:     '''
....:     f(x) = x^3
------------------------------------------------------------
  File "<ipython console>", line 5
SyntaxError: can't assign to function call (<ipython console>, line 5)

Attachments (1)

trac_4405.patch (4.8 KB) - added by mhansen 12 years ago.

Download all attachments as: .zip

Change History (7)

comment:1 Changed 13 years ago by kcrisman

  • Cc kcrisman added

comment:2 Changed 13 years ago by justin

The following seems to show that Sage parsing is bypassed, in some way, when using single-quote marks for docstrings.

sage: def foo(x):
   ....:     """
   ....:     it's a comment.
   ....:     """
   ....:     return x^2
   ....: 
sage: foo(3)
9
sage: def foo(x):
   ....:     '''
   ....:     It's a comment.
   ....:     '''
   ....:     return x^2
   ....: 
sage: foo(3)
1

In the first case, "^" is exponentiation; in the second, XOR.

Changed 12 years ago by mhansen

comment:3 Changed 12 years ago by mhansen

  • Owner changed from tba to mhansen
  • Status changed from new to assigned
  • Summary changed from double/single quotation marks in docstring to [with patch, needs review] double/single quotation marks in docstring

comment:4 Changed 12 years ago by mhansen

Note that this depends on #3752.

comment:5 Changed 12 years ago by malb

  • Summary changed from [with patch, needs review] double/single quotation marks in docstring to [with patch, positive review] double/single quotation marks in docstring

patch looks good, doctests pass.

comment:6 Changed 12 years ago by mabshoff

  • Milestone changed from sage-3.4.1 to sage-3.3
  • Resolution set to fixed
  • Status changed from assigned to closed

Merged in Sage 3.3.alpha2.

Cheers,

Michael

Note: See TracTickets for help on using tickets.