classification
Title: Tkinter.PanedWindow: docstring fixes, change in paneconfigure and removed some returns
Type: behavior Stage: patch review
Components: Tkinter Versions: Python 3.4
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: serhiy.storchaka Nosy List: gpolo, serhiy.storchaka, terry.reedy
Priority: normal Keywords: patch

Created on 2009-05-31 23:28 by gpolo, last changed 2017-07-10 06:01 by serhiy.storchaka.

Files
File name Uploaded Description Edit
PanedWindow_docstring_and_return_fixes.diff gpolo, 2009-05-31 23:27 review
PanedWindow_docstring_and_return_fixes_2.patch serhiy.storchaka, 2013-11-03 12:53 review
Messages (6)
msg88620 - (view) Author: Guilherme Polo (gpolo) * (Python committer) Date: 2009-05-31 23:27
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.
msg112289 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2010-08-01 08:29
This issue is self explanatory, can it be committed as is?
msg201497 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-10-27 20:49
LGTM, but perhaps renaming tagOrId worth deprecation warning.
msg202021 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-11-03 12:52
Patch updated to tip and added deprecation warning.
msg202064 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-11-03 21:31
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.
msg298026 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-07-10 06:01
> 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.
History
Date User Action Args
2017-07-10 06:01:21serhiy.storchakasetmessages: + msg298026
2014-02-03 15:48:20BreamoreBoysetnosy: - BreamoreBoy
2013-11-03 21:31:09terry.reedysetmessages: + msg202064
2013-11-03 12:53:11serhiy.storchakasetfiles: + PanedWindow_docstring_and_return_fixes_2.patch
2013-11-03 12:52:34serhiy.storchakasetnosy: + terry.reedy

messages: + msg202021
versions: - Python 2.7, Python 3.3
2013-10-31 16:07:54serhiy.storchakasetassignee: serhiy.storchaka
2013-10-27 20:50:14serhiy.storchakasetversions: + Python 3.3, Python 3.4, - Python 3.1, Python 3.2
2013-10-27 20:49:25serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg201497
2010-08-01 08:29:51BreamoreBoysetversions: + Python 3.2
nosy: + BreamoreBoy

messages: + msg112289

type: behavior
stage: patch review
2009-05-31 23:28:00gpolocreate