Tkinter.PanedWindow: docstring fixes, change in paneconfigure and removed some returns

[gpolo]

BPO	6159
Nosy	@terryjreedy, @serhiy-storchaka
Files	PanedWindow_docstring_and_return_fixes.diff PanedWindow_docstring_and_return_fixes_2.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/serhiy-storchaka'
closed_at = None
created_at = <Date 2009-05-31.23:28:00.082>
labels = ['type-bug', 'expert-tkinter']
title = 'Tkinter.PanedWindow: docstring fixes, change in paneconfigure and removed some returns'
updated_at = <Date 2017-07-10.06:01:21.392>
user = 'https://bugs.python.org/gpolo'

bugs.python.org fields:

activity = <Date 2017-07-10.06:01:21.392>
actor = 'serhiy.storchaka'
assignee = 'serhiy.storchaka'
closed = False
closed_date = None
closer = None
components = ['Tkinter']
creation = <Date 2009-05-31.23:28:00.082>
creator = 'gpolo'
dependencies = []
files = ['14133', '32476']
hgrepos = []
issue_num = 6159
keywords = ['patch']
message_count = 6.0
messages = ['88620', '112289', '201497', '202021', '202064', '298026']
nosy_count = 3.0
nosy_names = ['terry.reedy', 'gpolo', 'serhiy.storchaka']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue6159'
versions = ['Python 3.4']

[gpolo]

The attached patch removes the return statements from proxy_forget and
proxy_place since these methods aren't supposed to return anything.

It also fixes the docstring for the identify and paneconfigure methods.
While fixing the docstring in paneconfigure I considered as important to
rename "tagOrId" to "window", so the documentation and the method
signature get in agreement and also makes sense.

[BreamoreBoy]

This issue is self explanatory, can it be committed as is?

[serhiy-storchaka]

LGTM, but perhaps renaming tagOrId worth deprecation warning.

[serhiy-storchaka]

Patch updated to tip and added deprecation warning.

[terryjreedy]

Shipman and Lundh References:
http://infohost.nmt.edu/tcc/help/pubs/tkinter/web/panedwindow.html
http://effbot.org/tkinterbook/panedwindow.htm#Tkinter.PanedWindow-class

Let us separate the different issues with the PanedWindow code and docstrings.

0. .proxy is specified as 'Internal function'. The 3 .proxy_xyz methods are not but I believe they should be. (Without further examination) they make no sense to me otherwise. Lundh includes these 3 (but not .proxy); Shipman omits all 4. If they were to be marked 'internal', the return could be changed without worry, but it is low priority in any case. If anything, this should be a separate tracker issue.

1. The revision of the .identify docstring agrees with Shipman. However, while the revision describes how the Python wrapper should behave, I am dubious that tk.call itself returns either a list or a tuple, rather than a string such as '{0 sash}' unless verifed with a test. If there is none in test_widgets, I will try using sash_coord to get inputs that hit a sash and handle.

2. The 'proper' name for the required .paneconfigure parameter is 'child', which is the name used for all other functions and in both Shipman and Lundh. As long as we are revising, I much prefer the current standard docstrings, which is to use the imperative 'return' rather than 'returns' or 'is returned'.

3. After and before options are after and before a child *widget*, not window.

I may do a revised patch (or two) later.

[serhiy-storchaka]

However, while the revision describes how the Python wrapper should behave, I am dubious that tk.call itself returns either a list or a tuple, rather than a string such as '{0 sash}' unless verifed with a test.

This depends on the value of wantobjects. If it is 0, PanedWindow.identify() returns a string such as '{0 sash}'. Otherwise it currently returns a pair of an integer and a string. But this depends on Tk implementation details. In future versions it could return a second item as a Tcl_Obj instead of a string. This can be changed even in a Tk bugfix release.