incorrect "in ?" output in 'divide' example at "Defining Clean-up Actions" in tutorial

[omiday]

BPO	28315
Nosy	@terryjreedy, @ultimatecoder, @Mariatta, @omiday, @csabella
PRs	bpo-28315: Fixing wrong documentation #1372 [3.6] bpo-28315: Improve code examples in docs (GH-1372) #1445 [3.5] bpo-28315: Improve code examples in docs (GH-1372) #1446 [2.7] bpo-28315: Improve code examples in docs (GH-1372) #1447
Files	issue28315.patch all_rst_patch_default.diff: rst patch for default branch v_2_7_conflict_files.diff: rst patch for 2.7 branch for rejected files from default patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/Mariatta'
closed_at = <Date 2017-05-04.01:56:16.511>
created_at = <Date 2016-09-30.00:17:24.442>
labels = ['type-bug', '3.7', 'docs']
title = 'incorrect "in ?" output in \'divide\' example at "Defining Clean-up Actions" in tutorial'
updated_at = <Date 2017-05-04.01:56:16.510>
user = 'https://github.com/omiday'

bugs.python.org fields:

activity = <Date 2017-05-04.01:56:16.510>
actor = 'Mariatta'
assignee = 'Mariatta'
closed = True
closed_date = <Date 2017-05-04.01:56:16.511>
closer = 'Mariatta'
components = ['Documentation']
creation = <Date 2016-09-30.00:17:24.442>
creator = 'viorel'
dependencies = []
files = ['44885', '44970', '44971']
hgrepos = []
issue_num = 28315
keywords = ['patch']
message_count = 19.0
messages = ['277731', '277733', '277734', '277770', '278021', '278022', '278093', '278120', '278253', '292333', '292672', '292714', '292925', '292937', '292938', '292951', '292952', '292953', '292954']
nosy_count = 6.0
nosy_names = ['terry.reedy', 'docs@python', 'jaysinh.shukla', 'Mariatta', 'viorel', 'cheryl.sabella']
pr_nums = ['1372', '1445', '1446', '1447']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue28315'
versions = ['Python 2.7', 'Python 3.5', 'Python 3.6', 'Python 3.7']

[omiday]

At https://docs.python.org/3.5/tutorial/errors.html#defining-clean-up-actions
when I'm running the "divide('2', '1')" example I get:

File "<stdin>", line 1, in <module>

instead of the documentation output of:

File "<stdin>", line 1, in ?

The same message is included with the 2.7 tutorial.

To wit:

   $ python3
   Python 3.5.2 (default, Sep 14 2016, 11:28:32)
   [GCC 6.2.1 20160901 (Red Hat 6.2.1-1)] on linux
   Type "help", "copyright", "credits" or "license" for more information.
   >>> def divide(x, y):
   ...     try:
   ...             result = x / y
   ...     except ZeroDivisionError:
   ...             print('division by zero!')
   ...     else:
   ...             print('result is', result)
   ...     finally:
   ...             print('executing finally clause')
   ...
   >>> divide(2, 1)
   result is 2.0
   executing finally clause
   >>> divide(2, 0)
   division by zero!
   executing finally clause
   >>> divide('2', '1')
   executing finally clause
   Traceback (most recent call last):
   File "<stdin>", line 1, in <module>
   File "<stdin>", line 3, in divide
   TypeError: unsupported operand type(s) for /: 'str' and 'str'


   $ python2
   Python 2.7.12 (default, Sep  2 2016, 15:40:50)
   [GCC 6.2.1 20160901 (Red Hat 6.2.1-1)] on linux2
   Type "help", "copyright", "credits" or "license" for more information.
   >>> def divide(x, y):
   ...     result = x / y
   KeyboardInterrupt
   >>> def divide(x, y):
   ...     try:
   ...             result = x / y
   ...     except ZeroDivisionError:
   ...             print('division by zero!')
   ...     else:
   ...             print('result is', result)
   ...     finally:
   ...             print('executing finally clause')
   ...
   >>> divide(2, 1)
   ('result is', 2)
   executing finally clause
   >>> divide(2, 0)
   division by zero!
   executing finally clause
   >>> divide('2', '1')
   executing finally clause
   Traceback (most recent call last):
   File "<stdin>", line 1, in <module>
   File "<stdin>", line 3, in divide
   TypeError: unsupported operand type(s) for /: 'str' and 'str'
  

Nice tutorial by the way ;) Thanks!

[Mariatta]

Thanks for the report. I agree, it should be <module> instead of ?

I'll work on a patch for this :)

[Mariatta]

Updated the documentation to use <module> instead of ?

I also went through other examples in the page and fixed those too.

[terryjreedy]

Pushed to all 4 versions in ce57a74b5223, 1bead1f0260f, c729a62d4ec5, and 89cc2a6b64aa, but I gave issue # as 28815 instead of 28315. Thanks for the clean patch for 3.5. It mostly worked for 2.7, which also had an additional item not in 3.5.

The only other file in /Doc with 'in ?' is Doc/includes/test.py, which is mostly a doctest docstring. The test obviously have not been run for years and the directory puzzles me, so I left it alone.

[ultimatecoder]

According to this email, conversation with Terry, https://mail.python.org/mailman/private/core-mentorship/2016-October/003662.html adding patch for [Doc/library/ctypes.rst](https://github.com/python/cpython/blob/main/Doc/library/ctypes.rst)

[ultimatecoder]

@Treyy: I have uploaded patches according to your comment at Core mentorship here (https://mail.python.org/mailman/private/core-mentorship/2016-October/003662.html)

`Since I applied the patch, I can say in in this particular case,
re-open, preferably with one or more patches. I intended to include all
changes needed, at least for .rst files, and grepped with IDLE's
re-based grep, but missed most of what you listed. I probably started
in the wrong directory.

But exclude

1. the .rej files, which are not tracked, and which you should delete.
2. the old 'What's New' files, where 'in ?' is likely correct.
3. the includes/text/py files, for reasons given in the issue.
4. the other .py files, like test_generators.py, at least initially,
   until it is determined why they are not failing if incorrect.

Left are *.rst. At least some of the code should be run to verify that
the proposed changes are correct. I would not mind a separate patch for
ctypes.rst, which has half the hits.

If you only reopen and do not do a patch, please copy these comments
into the issue.`

Please change the status of issue to open from close. Thanks!

[terryjreedy]

Jaysinh, unless a patch for 3.5 does not cleanly apply to 3.6, or the patch must be different in 3.6*, no 3.6 patch is needed. Ditto for 3.7/default. Mariatta's patch merged forward without problem. *In this case, 'must be different' would be because there are different code examples.

The same is true for 2.7 if the 3.x patch applies cleanly there (though this is less common there). Mariatta's patch also applied to 2.7, though as I reported, I found one more change for 2.7.

So when you revise in response to comments, one of each patch is enough unless you know more are needed, in which case say so. If there are problems forward-merging the other_rst patch, please report first before preparing a 3.6 patch. If there were a problem with just one of the files, I would prpbably want a 3.6 patch just for the one file.

I discovered a deeper problem. In spite of the doctest annotations, the doctests is not run on the ctypes doc and at least one of the tracebacks is wrong.

>>> windll.kernel32.GetModuleHandleA()      # doctest: +WINDOWS	  Traceback (most recent call last):	
  File "<stdin>", line 1, in ?	
    ValueError: Procedure probably called with not enough arguments (4 bytes missing)
>>> windll.kernel32.GetModuleHandleA(0, 0)  # doctest: +WINDOWS
Traceback (most recent call last):
  File "<stdin>", line 1, in ?	   ValueError: Procedure probably called with too many arguments (4 bytes in excess)

whereas, on Win10, 3.5
>>> from ctypes import *
>>> windll.kernel32.GetModuleHandleA()
0
>>> windll.kernel32.GetModuleHandleA(0, 0)
480968704

However, when I ran make doctest, these did not show up, but they were not run. I will worry about this as a separate issue.

>>> windll.kernel32.GetModuleHandleA()
477822976
>>> windll.kernel32.GetModuleHandleA(0, 0)
477822976