date:20180513

[issue33479] Document tkinter and threads

2018-05-13 Thread Ivan Pozdeev

Ivan Pozdeev added the comment:

I was composing a letter to python-dev with all I know of how tkinter works
with regard to threads and Tcl, and the fixing plans so that we're all on the
same page if you wish to participate.

I'm no longer sure if it belongs in the mailing list so see it in the
attachment.

The plan I have for fixing the documentation is there towards the end.
It includes what you suggested but is more detailed. I'll recite it below:

---

* Document the current behaviour by rewriting
https://docs.python.org/3/library/tkinter.html .

Since I've recently learned Tkinter, I can say which critical information is
missing and which existing one proved useless.

Principles:

* include fundamental information critical to understand the module's
behaviour
* concentrate on reference documentation for the module because it's more
important to have than a user guide (
https://meta.serverfault.com/questions/8934/what-to-do-with-questions-when-the-answer-is-in-a-man-page#comment22241_8938
)
* split off/drop anything unrelated to the above two

Resulting scheme:

0. Intro: +supported Tcl/Tk versions and the two flavors; the fact that
Tkinter adds its own logic, and the Tkinter doc concentrates on that logic and
refers to Tcl/Tk docs for details that are taken from there without changes.

* Move external links section to be bottom.

1. Architecture. "Unlike most other GUI toolkits, Tcl/Tk consists of a few
separate modules with a clear distinction between them, and this is
non-transparect to the user:..." Base on
https://docs.python.org/3/library/tkinter.html#how-tk-and-tkinter-are-related ,
but focus on what implements what rather than what _calls_ what; drop Xlib
entry (transparent implementation detail, not required for understanding).

2. Threading model. The above-described general idea and user-visible
limitations what can be called where and when. (the letter has details that
this refers to, too long to recite)

3. References for `tkinter`, `tkinter.Tk()`, `_tkinter.Tkapp` (public
interface only -- `call()` at least). Mention which functions cannot be called
from other threads. Do not mention the two issue33257 bugs.

* Move widget reference to another page.
* Drop Python-Tcl mappings unless the reference sections need them as
supplemental reference.
* Drop tutorial: too primitive to be useful. Move tutorials to another page
like https://docs.python.org/3/library/logging.html does.
* Drop https://docs.python.org/3/library/tk.html -- proved hard to find.
Make https://docs.python.org/3/library/tkinter.html the head page instead.

* Discuss which of the described behaviour is as intended and which is a bug.
Proceed with fixing.

--
assignee: -> docs@python
components: +Documentation
nosy: +Ivan.Pozdeev, docs@python
Added file: https://bugs.python.org/file47586/[Python-Dev] Tkinter threading
model description and fix plan.eml

___
Python tracker

___
___
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

56 matches

Mail list logo