[SciPy-dev] change print statements to print functions in docstrings

Ralf Gommers ralf.gommers@googlemail....
Sat Aug 15 12:14:48 CDT 2009


On Sat, Aug 15, 2009 at 12:44 PM, Charles R Harris <
charlesr.harris@gmail.com> wrote:

>
>
> On Sat, Aug 15, 2009 at 10:24 AM, Ralf Gommers <
> ralf.gommers@googlemail.com> wrote:
>
>>
>>
>> On Sat, Aug 15, 2009 at 11:37 AM, Charles R Harris <
>> charlesr.harris@gmail.com> wrote:
>>
>>>
>>>
>>> On Sat, Aug 15, 2009 at 7:59 AM, Emmanuelle Gouillart <
>>> emmanuelle.gouillart@normalesup.org> wrote:
>>>
>>>>        Hi,
>>>>
>>>>        I've started changing the print statements in numpy's doctrings
>>>> to print functions on the doc wiki, to meet the requirements of Python
>>>> 3.0. Any objections or comments?
>>>>
>>>
>>> This can lead to some oddities:
>>>
>>> In [6]: print(1,2,3)
>>> (1, 2, 3)
>>>
>>>
>>> I think it might be better to find out what  2to3 does in these
>>> circumstances first.
>>>
>>
>> From the 2to3 docs:
>> "2to3 can also refactor doctests. To enable this mode, use the -d f**<http://docs.python.org/using/cmdline.html#cmdoption-d>lag.
>> Note that *only* doctests will be refactored. This also doesn’t require
>> the module to be valid Python. For example, doctest like examples in a reST
>> document could also be refactored with this option."
>>
>> Anyway, the change can also be made with a good editor and search-replace.
>> I am all for changing this, my point was simply that the doc wiki is not the
>> best tool to make changes like these (not that I don't love the doc wiki,
>> it's great).
>>
>
> I'm not convinced it is a good idea, even pedagogically. First, all the
> python books I have are for the python-2.x versions, and second it saddles
> the students with having to make a distinction between printing single items
> vs printing multiple items. It's better, I think, to wait until we have a
> python 3.x version of numpy.
>

Okay fair enough. Change or no change, I have no strong opinion, as long as
it is done consistently for all docstrings.

>
> That said, it would be interesting if someone ran some tests using 2to3
> just to see how it works.
>

It seems to work out of the box on many files, but chokes on a few. Maybe it
tries to execute some problematic doctests, I'm not sure. Probably easy to
fix. Here are some examples:

ralf@ralf-desktop:~/python/numpy/numpy/core$ 2to3 -d records.py
RefactoringTool: Skipping implicit fixer: buffer
RefactoringTool: Skipping implicit fixer: idioms
RefactoringTool: Skipping implicit fixer: set_literal
RefactoringTool: Skipping implicit fixer: ws_comma
--- records.py (original)
+++ records.py (refactored)
@@ -473,7 +473,7 @@
     >>> x2=np.array(['a','dd','xyz','12'])
     >>> x3=np.array([1.1,2,3,4])
     >>> r = np.core.records.fromarrays([x1,x2,x3],names='a,b,c')
-    >>> print r[1]
+    >>> print(r[1])
     (2, 'dd', 2.0)
     >>> x1[1]=34
     >>> r.a
@@ -552,15 +552,15 @@

     >>> r=np.core.records.fromrecords([(456,'dbe',1.2),(2,'de',1.3)],
     ... names='col1,col2,col3')
-    >>> print r[0]
+    >>> print(r[0])
     (456, 'dbe', 1.2)
     >>> r.col1
     array([456,   2])
     >>> r.col2
     chararray(['dbe', 'de'],
           dtype='|S3')
-    >>> import cPickle
-    >>> print cPickle.loads(cPickle.dumps(r))
+    >>> import pickle
+    >>> print(cPickle.loads(cPickle.dumps(r)))
     [(456, 'dbe', 1.2) (2, 'de', 1.3)]
     """

@@ -647,7 +647,7 @@
     >>> fd.seek(0)
     >>> r=np.core.records.fromfile(fd, formats='f8,i4,a5', shape=10,
     ... byteorder='<')
-    >>> print r[5]
+    >>> print(r[5])
     (0.5, 10, 'abcde')
     >>> r.shape
     (10,)
RefactoringTool: Files that need to be modified:
RefactoringTool: records.py



ralf@ralf-desktop:~/python/numpy/numpy/core$ 2to3 -d numerictypes.py
RefactoringTool: Skipping implicit fixer: buffer
RefactoringTool: Skipping implicit fixer: idioms
RefactoringTool: Skipping implicit fixer: set_literal
RefactoringTool: Skipping implicit fixer: ws_comma
RefactoringTool: No files need to be modified.




ralf@ralf-desktop:~/python/numpy/numpy/core$ 2to3 -d fromnumeric.py
RefactoringTool: Skipping implicit fixer: buffer
RefactoringTool: Skipping implicit fixer: idioms
RefactoringTool: Skipping implicit fixer: set_literal
RefactoringTool: Skipping implicit fixer: ws_comma
--- fromnumeric.py (original)
+++ fromnumeric.py (refactored)
@@ -941,15 +941,15 @@
     to ``reshape(-1)``:

     >>> x = np.array([[1, 2, 3], [4, 5, 6]])
-    >>> print x.reshape(-1)
+    >>> print(x.reshape(-1))
     [1  2  3  4  5  6]

-    >>> print np.ravel(x)
+    >>> print(np.ravel(x))
     [1  2  3  4  5  6]

     When flattening using Fortran-order, however, we see

-    >>> print np.ravel(x, order='F')
+    >>> print(np.ravel(x, order='F'))
     [1 4 2 5 3 6]

     """
RefactoringTool: Files that need to be modified:
RefactoringTool: fromnumeric.py




ralf@ralf-desktop:~/python/numpy/numpy/core$ 2to3 -d numeric.py
RefactoringTool: Skipping implicit fixer: buffer
RefactoringTool: Skipping implicit fixer: idioms
RefactoringTool: Skipping implicit fixer: set_literal
RefactoringTool: Skipping implicit fixer: ws_comma
Traceback (most recent call last):
  File "/usr/bin/2to3", line 6, in <module>
    sys.exit(main("lib2to3.fixes"))
  File "/usr/lib/python2.6/lib2to3/main.py", line 129, in main
    rt.refactor(args, options.write, options.doctests_only)
  File "/usr/lib/python2.6/lib2to3/refactor.py", line 196, in refactor
    self.refactor_file(dir_or_file, write, doctests_only)
  File "/usr/lib/python2.6/lib2to3/refactor.py", line 229, in refactor_file
    output = self.refactor_docstring(input, filename)
  File "/usr/lib/python2.6/lib2to3/refactor.py", line 406, in
refactor_docstring
    indent, filename))
  File "/usr/lib/python2.6/lib2to3/refactor.py", line 426, in
refactor_doctest
    if self.log.isEnabledFor(logging.DEBUG):
AttributeError: 'StdoutRefactoringTool' object has no attribute 'log'



Cheers,
Ralf



>
> Chuck
>
>
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev@scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20090815/bcb46aae/attachment.html 


More information about the Scipy-dev mailing list