bpo-13553: Document tkinter.Tk args

[csabella]

https://bugs.python.org/issue13553

[terryjreedy]

None of my comments are outdated by applying Serhiy's suggestions. My review just happened to start before the patch arrived, and except for 1, happen to be attached to the same sentences. Serhiy, please also review my comments.

[vstinner]

While we are documenting the Tk class. Would it be worth it to document Tk attributes? master, children and tk.

[csabella]

The current page reads more like a 'getting started' or 'how to', so I wasn't sure how much detail to add. I know there's a separate bug issue where Terry figured out the difference between master and parent, so maybe it would be worthwhile to include that here?

[csabella]

I have made the requested changes; please review again.

[csabella]

@terryjreedy @serhiy-storchaka @vstinner
I've made additional changes to document the attributes and to remove the documentation of readprofile. Thanks!

I don't know the function well enough to approve, as oppose to disapprove.

[ned-deily]

@csabella Sorry this has languished. Currently, there is some extensive tkinter documentation review going on in some other PRs. Perhaps @roseman would be willing to review your proposed changes once the other changes are settled on.

[roseman]

So about baseName and className...

My understanding is that className is the equivalent of wish's "-name" option. So this provides the default title for the root window, the class of the root window (which can be used in bindings and option database), and would be what is returned by "tk appname" (sometimes used for inter-application communication).

It appears that baseName isn't passed into Tcl/Tk at all.

About those profile files that can be read in... does anyone know what they're intended to be used for, if they've ever been documented, and if they're actually used at all? It reads like a per-application 'automatically inject your own code' which seems a bit strange.

[csabella]

I tried out specifying className on a call and it seems to lower case the first letter:

root = tkinter.Tk(className='TEST')

creates a window with the name tEST and root.tk.call('tk', 'appname') returns tEST. Should I document that behavior? Since fileName in the wish documentation is used to find the script, I think it might be lowercased for that reason?

Looking through the documentation, it looks like interp is used for inter-application communication, which is the value stored in Tk.tk.

tk appname ?newName?
    If newName is not specified, this command returns the name of the application (the name
    that may be used in **send** commands to communicate with the application)

However, the send command in tkinter has:

    def send(self, interp, cmd, *args):
        """Send Tcl command CMD to different interpreter INTERP to be executed."""
        return self.tk.call(('send', interp, cmd) + args)

As far as the profile files, there was a security patch in the past.

[roseman]

I'm not sure why the first letter is lowercased - it's Tkinter that's doing it, though for what reason I can't guess. From the Tcl side it's perfectly ok with the first letter of argv0 capitalized. My instinct therefore is not to document it.

Note that the classname for the window will lowercase everything except for uppercasing the first letter, e.g. "Test" with your example. I think the first letter uppercase is used for user class names vs. builtin ones like 'button' etc. I was playing around with different things using this:

r = Tk(className='TEST')
print(r.call('tk','appname'))
print(r.wm_title())
print(r.bindtags())
print(sys.argv[0])

I'd suggest not documenting this conversion either. Anyone who needs to get the exact capitalization of the classname will know how to get it through introspection. I also don't imagine that 'send' would be used much by Tkinter apps (it was a useful thing a long while ago, not so much now).

Any suggestions how to proceed with regard to the readprofile() thing, i.e. what on earth it is for and if it should still be there? @serhiy-storchaka ?

[roseman]

This should be "Specifies the id of the window". This whole piece was used for application embedding (think web browser plugins). Therefore, it would be almost always the case that you'd embed inside a specific subwindow somewhere, not directly in the "main" window of the application (which I'd read as toplevel)

[csabella]

Thank you. I think I had taken this from the wish man page and unintentionally changed the meaning slightly with my edit.

[csabella]

Thank you @roseman for the review! I've pushed some of the changes, but still needed some clarification on the className as far as the uses and the behavior that should be documented.

[roseman]

I think for className, saying it sets the window's class, which can be used when specifying event bindings (see documentation for 'bindtags').

The profile thing I just don't know about..

[vstinner]

I removed the " needs backport to 3.6" label, the 3.6 branch no longer accept bugfixes (only security fixes are accepted): https://devguide.python.org/#status-of-python-branches

[JulienPalard]

@csabella Looks like this PR is almost OK, maybe just missing the mention that className permits to choose the title of the window (last message of Mark). I tried to mark as resolved every actually resolved comments, I'll let you read the rest of them a last time.

[JelleZijlstra]

Looks good, it seems the remaining comments don't need to be blocking.

[JelleZijlstra]

Planning to merge this unless someone has further comments.

[taleinat]

LGTM

[miss-islington]

Thanks @csabella for the PR, and @JelleZijlstra for merging it 🌮🎉.. I'm working now to backport this PR to: 3.9, 3.10, 3.11.
🐍🍒⛏🤖