diff --git a/CHANGELOG.md b/CHANGELOG.md index bf02f4f..e2e99d4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ and the project uses [Semantic Versioning](https://semver.org/). ## [Unreleased] +## [0.3.1] - 2026-11-06 + ### Added - Commands to install tkinter on the common Linux distributions, and tkinter and Tktable where @@ -17,6 +19,11 @@ and the project uses [Semantic Versioning](https://semver.org/). ### Changed +- The installation docs list one row per distribution, show the tkinter commands only once (in + "Check tkinter first"), have the Linux and macOS pages install only Tktable, and move + Troubleshooting to its own page. +- The installation docs say that Magicsplat's latest releases have Tktable 2.12.1, from + bohagan1/TkTable, like the prebuilt one. - `python -m tktable` calls Tktable "Tktable (Tcl/Tk extension)", so it's not confused with pytktable, and links to the installation docs when tkinter doesn't work, instead of suggesting a Debian/Ubuntu command on every OS. @@ -131,7 +138,8 @@ First release on PyPI. These changes were made with the help of - `tktable/__init__.py` imports `ArrayVar` and `Table` lazily, so the diagnostic works without tkinter (explained in the module docstring). -[Unreleased]: https://github.com/nbro/tktable/compare/0.3.0...HEAD +[Unreleased]: https://github.com/nbro/tktable/compare/0.3.1...HEAD +[0.3.1]: https://github.com/nbro/tktable/compare/0.3.0...0.3.1 [0.3.0]: https://github.com/nbro/tktable/compare/0.2.0...0.3.0 [0.2.0]: https://github.com/nbro/tktable/compare/0.1.0...0.2.0 [0.1.0]: https://github.com/nbro/tktable/releases/tag/0.1.0 diff --git a/docs/installation/index.md b/docs/installation/index.md index b672081..b525fe4 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -12,7 +12,31 @@ python -c "import tkinter; print(tkinter.TkVersion)" ``` It should print the version of Tcl/Tk your Python uses, e.g. `8.6` or `9.0`. If it fails instead, -fix tkinter first (see [Troubleshooting](#troubleshooting)), then install pytktable. +install or fix tkinter first, then install pytktable. The python.org installers for Windows and +macOS include tkinter. On Linux, install your distribution's tkinter package: + +| Distribution | Command | +|---|---| +| Debian | `sudo apt install python3-tk` | +| Ubuntu | `sudo apt install python3-tk` | +| Linux Mint | `sudo apt install python3-tk` | +| Kali Linux | `sudo apt install python3-tk` | +| Fedora | `sudo dnf install python3-tkinter` | +| RHEL 10 | `sudo dnf install python3-tkinter` | +| CentOS Stream 10 | `sudo dnf install python3-tkinter` | +| RHEL 9 | `sudo dnf install python3.12 python3.12-tkinter` | +| Rocky Linux 9 | `sudo dnf install python3.12 python3.12-tkinter` | +| AlmaLinux 9 | `sudo dnf install python3.12 python3.12-tkinter` | +| openSUSE | `sudo zypper install python3-tk` | +| Alpine | `sudo apk add python3-tkinter` | +| Arch Linux | `sudo pacman -S tk` | +| Manjaro | `sudo pacman -S tk` | +| Gentoo | Python built with the `tk` USE flag | + +On RHEL 9 and its rebuilds, `python3` is Python 3.9, older than pytktable requires, so use +`python3.12`. Most of these are tested with the prebuilt Tktable (see +[Testing](https://github.com/nbro/pytktable-binaries/blob/main/docs/testing.md)). If tkinter +still doesn't work, see {doc}`troubleshooting`. (prebuilt-tktable)= ## With prebuilt Tktable (recommended) @@ -22,8 +46,8 @@ pip install "pytktable[binary]" ``` Keep the quotes: some shells, e.g. zsh (the default on macOS), would otherwise treat the brackets -as a file pattern. This also installs [pytktable-binaries](https://github.com/nbro/pytktable-binaries), which contains -[Tktable](https://wiki.tcl-lang.org/page/Tktable), the Tcl/Tk extension that provides the table +as a file pattern. This also installs +[pytktable-binaries](https://github.com/nbro/pytktable-binaries), which contains [Tktable](https://wiki.tcl-lang.org/page/Tktable), the Tcl/Tk extension that provides the table widget, compiled for Tcl/Tk 8.6 and 9.0 for: | OS | Architectures | @@ -33,27 +57,12 @@ widget, compiled for Tcl/Tk 8.6 and 9.0 for: | macOS 11 and later | Intel, Apple silicon | | Windows | x64, x86, ARM | -See [pytktable-binaries](https://github.com/nbro/pytktable-binaries) for where +See [Platforms](https://github.com/nbro/pytktable-binaries/blob/main/docs/platforms.md) for where they are tested. pytktable finds it automatically, so you don't need to install Tktable or set `TKTABLE_LIBRARY`. -You only need tkinter, which the python.org installers for Windows and macOS include. On Linux, -install your distribution's tkinter package: - -| Distribution | Command | -|---|---| -| Debian, Ubuntu, Linux Mint, Kali Linux | `sudo apt install python3-tk` | -| Fedora, RHEL 10, CentOS Stream 10 | `sudo dnf install python3-tkinter` | -| RHEL 9, Rocky Linux 9, AlmaLinux 9 | `sudo dnf install python3.12 python3.12-tkinter` | -| openSUSE | `sudo zypper install python3-tk` | -| Alpine | `sudo apk add python3-tkinter` | -| Arch Linux, Manjaro | `sudo pacman -S tk` | -| Gentoo | Python built with the `tk` USE flag | - -On RHEL 9 and its rebuilds, `python3` is Python 3.9, older than pytktable requires, so use -`python3.12`. Most of these are tested with the prebuilt Tktable (see -[Testing](https://github.com/nbro/pytktable-binaries/blob/main/docs/testing.md)). Tktable also -needs the X11 library (`libX11`), which every desktop Linux has. +You only need tkinter ({ref}`see above `). Tktable also needs the X11 library +(`libX11`), which every desktop Linux has. (without-prebuilt-tktable)= ## Without prebuilt Tktable @@ -84,7 +93,9 @@ How to install them depends on your OS: Tktable from different sources isn't always the same version, so it can behave slightly differently: e.g. the default colors of the title rows of the prebuilt Tktable (2.12) and of -Magicsplat's (2.11) differ. +Tktable 2.11, from [apnadkarni/tktable](https://github.com/apnadkarni/tktable), which older +Magicsplat releases had, differ. Magicsplat's latest releases (1.18.0 and 2.0.7) have Tktable +2.12.1, from [bohagan1/TkTable](https://github.com/bohagan1/TkTable), like the prebuilt one. ## Check the installation @@ -103,44 +114,6 @@ If Tktable is installed in a directory Tcl does not search, set the environment `TKTABLE_LIBRARY` to the directory containing Tktable's `pkgIndex.tcl`. That directory is named after Tktable's version, e.g. `Tktable2.10` for Tktable 2.10. See your OS page for how to set it. -(troubleshooting)= -## Troubleshooting - -`_tkinter.TclError: can't find package Tktable` or `invalid command name "table"` -: Tcl cannot find Tktable. Install pytktable with [prebuilt Tktable](#prebuilt-tktable), or - [install Tktable](#without-prebuilt-tktable) and, if needed, set - [`TKTABLE_LIBRARY`](#tktable-library). - {py:class}`~tktable.table.Table` raises {py:class}`~tktable.table.CannotUseError` in this case. - -`ModuleNotFoundError: No module named 'tkinter'` -: tkinter is not installed for your Python. On Linux, install your distribution's tkinter - package ([see above](#prebuilt-tktable)). - -`ImportError: ... Library not loaded: .../libtk8.6.dylib` on macOS -: Your Python was compiled (e.g. by pyenv) against Homebrew's Tcl/Tk 8.6, which Homebrew has since - replaced with Tcl/Tk 9 in the `tcl-tk` formula. Python 3.14 and newer work with Tcl/Tk 9, so - reinstalling them is enough. Python 3.11 to 3.13 need Tcl/Tk 8.6, from Homebrew's `tcl-tk@8`; - with pyenv, e.g. for Python 3.11.9: - - ```sh - brew install tcl-tk@8 - ``` - - ```sh - pyenv uninstall -f 3.11.9 - ``` - - ```sh - PKG_CONFIG_PATH="$(brew --prefix tcl-tk@8)/lib/pkgconfig" pyenv install 3.11.9 - ``` - - Then [check tkinter](#check-tkinter) again, and recreate your virtual environments. The - python.org installers for macOS don't have this problem: they come with their own Tcl/Tk. - -Tktable is found but fails to load -: It was probably built for a different Tcl/Tk version than the one your Python uses (e.g. Tcl 8.6 - vs 9.0). `python -m tktable` shows both. - ```{toctree} :hidden: @@ -148,4 +121,5 @@ linux macos windows other-systems +troubleshooting ``` diff --git a/docs/installation/linux.md b/docs/installation/linux.md index 2b6f8a4..f70fbe1 100644 --- a/docs/installation/linux.md +++ b/docs/installation/linux.md @@ -3,21 +3,24 @@ These instructions are for installing Tktable yourself, with `pip install pytktable`. With `pip install "pytktable[binary]"`, you don't need them: see {ref}`prebuilt-tktable`. -## Install tkinter and Tktable +## Install Tktable -Where the distribution has a Tktable package, install it with tkinter: +First, install tkinter ({ref}`see the commands `). Then, where the distribution has +a Tktable package: | Distribution | Command | Tktable version | |---|---|---| -| Debian, Ubuntu, Linux Mint, Kali Linux | `sudo apt install python3-tk tk-table` | 2.10.8 ([Kali](https://pkg.kali.org/pkg/tk-table)) | -| Gentoo | `sudo emerge dev-tcltk/tktable`, with Python built with the `tk` USE flag | [2.12.1](https://packages.gentoo.org/packages/dev-tcltk/tktable) | +| Debian | `sudo apt install tk-table` | | +| Ubuntu | `sudo apt install tk-table` | | +| Linux Mint | `sudo apt install tk-table` | | +| Kali Linux | `sudo apt install tk-table` | [2.10.8](https://pkg.kali.org/pkg/tk-table) | +| Gentoo | `sudo emerge dev-tcltk/tktable` | [2.12.1](https://packages.gentoo.org/packages/dev-tcltk/tktable) | | Slackware | the [`tktable` SlackBuild](https://slackbuilds.org/repository/15.0/development/tktable/), built from source | 2.10.8 | Fedora, RHEL and its rebuilds (CentOS, Rocky Linux, AlmaLinux), openSUSE, Alpine and Arch Linux -have no Tktable package that we know of: there, install only tkinter -({ref}`see the commands `) and use the prebuilt Tktable, or -[conda](other-systems.md#conda). `perl-Tk-TableMatrix` (Fedora, Arch Linux, Manjaro) is a -different table widget, for Perl/Tk, not Tktable. +have no Tktable package that we know of: there, use the prebuilt Tktable +({ref}`prebuilt-tktable`) or [conda](other-systems.md#conda). `perl-Tk-TableMatrix` (Fedora, +Arch Linux, Manjaro) is a different table widget, for Perl/Tk, not Tktable. ## Check the installation diff --git a/docs/installation/macos.md b/docs/installation/macos.md index b7c5f27..de1b36c 100644 --- a/docs/installation/macos.md +++ b/docs/installation/macos.md @@ -3,10 +3,11 @@ These instructions are for installing Tktable yourself, with `pip install pytktable`. With `pip install "pytktable[binary]"`, you don't need them: see {ref}`prebuilt-tktable`. -## Install tkinter and Tktable +## Install Tktable -The python.org installers for macOS include tkinter. With [MacPorts](https://www.macports.org/), -install [Tktable](https://ports.macports.org/port/tktable/) (version 2.11): +First, make sure that your Python has a working tkinter ({ref}`check-tkinter`). Then, with +[MacPorts](https://www.macports.org/), install +[Tktable](https://ports.macports.org/port/tktable/) (version 2.11): ```sh sudo port install tktable @@ -14,8 +15,7 @@ sudo port install tktable [conda](other-systems.md#conda) also has Tktable. -If tkinter doesn't work with a Python built by pyenv or Homebrew, see -[Troubleshooting](index.md#troubleshooting). +If tkinter doesn't work with a Python built by pyenv or Homebrew, see {doc}`troubleshooting`. ## Check the installation diff --git a/docs/installation/other-systems.md b/docs/installation/other-systems.md index f341526..e4e21ec 100644 --- a/docs/installation/other-systems.md +++ b/docs/installation/other-systems.md @@ -15,8 +15,9 @@ the same package manager. (conda)= ## conda -On Linux, macOS and Windows, [conda-forge](https://github.com/conda-forge/tktable-feedstock) has -Tktable, for the Tcl/Tk of a conda environment: +On Linux, macOS and Windows, [conda-forge](https://anaconda.org/conda-forge/tktable/files) has +Tktable 2.10, for the Tcl/Tk of a conda environment, also for some CPUs without prebuilt Tktable +(`ppc64le`, `riscv64`): ```sh conda install -c conda-forge tktable diff --git a/docs/installation/troubleshooting.md b/docs/installation/troubleshooting.md new file mode 100644 index 0000000..eb6dda8 --- /dev/null +++ b/docs/installation/troubleshooting.md @@ -0,0 +1,37 @@ +(troubleshooting)= +# Troubleshooting + +`_tkinter.TclError: can't find package Tktable` or `invalid command name "table"` +: Tcl cannot find Tktable. Install pytktable with {ref}`prebuilt Tktable `, or + {ref}`install Tktable ` and, if needed, set + {ref}`TKTABLE_LIBRARY `. + {py:class}`~tktable.table.Table` raises {py:class}`~tktable.table.CannotUseError` in this case. + +`ModuleNotFoundError: No module named 'tkinter'` +: tkinter is not installed for your Python. On Linux, install your distribution's tkinter + package ({ref}`see the commands `). + +`ImportError: ... Library not loaded: .../libtk8.6.dylib` on macOS +: Your Python was compiled (e.g. by pyenv) against Homebrew's Tcl/Tk 8.6, which Homebrew has since + replaced with Tcl/Tk 9 in the `tcl-tk` formula. Python 3.14 and newer work with Tcl/Tk 9, so + reinstalling them is enough. Python 3.11 to 3.13 need Tcl/Tk 8.6, from Homebrew's `tcl-tk@8`; + with pyenv, e.g. for Python 3.11.9: + + ```sh + brew install tcl-tk@8 + ``` + + ```sh + pyenv uninstall -f 3.11.9 + ``` + + ```sh + PKG_CONFIG_PATH="$(brew --prefix tcl-tk@8)/lib/pkgconfig" pyenv install 3.11.9 + ``` + + Then {ref}`check tkinter ` again, and recreate your virtual environments. The + python.org installers for macOS don't have this problem: they come with their own Tcl/Tk. + +Tktable is found but fails to load +: It was probably built for a different Tcl/Tk version than the one your Python uses (e.g. Tcl 8.6 + vs 9.0). `python -m tktable` shows both. diff --git a/pyproject.toml b/pyproject.toml index c29c751..81becbb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ [project] name = "pytktable" -version = "0.3.0" +version = "0.3.1" description = "A spreadsheet-like table widget for tkinter, wrapping the Tcl/Tk Tktable extension." readme = "README.md" requires-python = ">=3.11"