Skip to content

Commit d9ff11c

Browse files
Remove Tkl/tk caveats from quirks (#434)
## Summary I'm open to keeping something here, but it should just be a non-issue for users in the future?
1 parent f91adf9 commit d9ff11c

File tree

1 file changed

+0
-82
lines changed

1 file changed

+0
-82
lines changed

docs/quirks.rst

Lines changed: 0 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -80,88 +80,6 @@ at build time! So actually using this bundled terminfo database will
8080
require custom code setting ``TERMINFO_DIRS`` before
8181
ncurses/libedit/readline are loaded.
8282

83-
.. _quirk_tcl:
84-
85-
Tcl/tk Support Files
86-
====================
87-
88-
Python functionality using tcl/tk (such as the ``tkinter`` or ``turtle``
89-
modules) requires loading ``.tcl`` support files from the filesystem.
90-
If these support files cannot be found, you'll get an error like
91-
``_tkinter.TclError: Can't find a usable init.tcl in the following
92-
directories:``.
93-
94-
Distributions produced from this project contain tcl/tk support files.
95-
The paths to these files in the extracted distribution are advertised
96-
in the ``PYTHON.json`` file.
97-
98-
When tcl is initialized by Python, Python and tcl attempt to locate the
99-
``.tcl`` support files. If the ``tcl<X.Y>/init.tcl`` file cannot be found,
100-
an error occurs.
101-
102-
But the mechanism for finding the ``.tcl`` files varies by platform.
103-
104-
On all platforms, if the ``TCL_LIBRARY`` environment variable is set,
105-
it will be used to locate the ``.tcl`` support files. This environment
106-
variable is processed by tcl itself and is documented at
107-
https://wiki.tcl-lang.org/page/TCL_LIBRARY.
108-
109-
On Windows, CPython will attempt to locate the ``.tcl`` support files in
110-
well-defined directories. The C code performs the equivalent of the
111-
following:
112-
113-
.. code-block:: python
114-
115-
import os
116-
import sys
117-
118-
def get_tcl_path():
119-
# e.g. sys.prefix/tcl/tcl8.6
120-
p = os.path.join(sys.prefix, "tcl", "tcl<X.Y>")
121-
if os.path.exists(p):
122-
return p
123-
124-
return None
125-
126-
If Python's code can find the support files in the well-defined location,
127-
it calls into the tcl C API and defines the ``tcl_library`` variable to the
128-
found path.
129-
130-
The most robust way to ensure Python/tcl can find the ``.tcl`` support files
131-
is to define ``TCL_LIBRARY`` to the path to the ``.tcl`` files present in
132-
the extracted Python distribution. It is possible to define this environment
133-
variable from within Python. But it must be done before running any Python
134-
code in the ``tkinter`` module. The following example should work on Linux
135-
and macOS distributions:
136-
137-
.. code-block:: python
138-
139-
import os
140-
import sys
141-
142-
os.environ["TCL_LIBRARY"] = os.path.join(os.path.dirname(sys.executable), "..", "lib", "tcl8.6")
143-
144-
import turtle
145-
146-
If you don't set ``TCL_LIBRARY`` on Linux and macOS, the default search
147-
mechanics implemented by Tcl are used. These may pick up ``.tcl`` files from
148-
a location outside the Python distribution. This may *just work*. This may
149-
fail fast. Or it could result in undefined behavior. For best results,
150-
forcefully point Tcl at the ``.tcl`` files from the Python distribution
151-
produced by this project.
152-
153-
On Windows, explicitly setting ``TCL_LIBRARY`` is not required as the
154-
default install layout of this project's Python distributions allows CPython's
155-
filesystem probing code to find the ``.tcl`` files. As long as the
156-
files from ``python/install/tcl`` are present (in a ``tcl`` directory
157-
under the directory where the ``python.exe`` is), things should *just work*.
158-
159-
For reference, PyOxidizer's approach to this problem is to copy all the
160-
``.tcl`` files from the Python distribution into an install location. At
161-
run time, the ``TCL_LIBRARY`` environment variable is set from within
162-
the process before the Python interpreter is initialized. This ensures the
163-
``.tcl`` files from the Python distribution are used.
164-
16583
.. _quirk_macos_no_tix:
16684

16785
No tix on macOS

0 commit comments

Comments
 (0)