pyglossary

PyGlossary

The primary purpose is to be able to use our offline glossaries in any Open Source dictionary we like on any OS/device.

There are countless formats, and my time is limited, so I implement formats that seem more useful for myself, or for Open Source community. Also diversity of languages is taken into account. Pull requests are welcome.

Screenshots

Linux - Gtk3-based interface

Windows - Tkinter-based interface

Linux - command-line interface

Android Termux - interactive command-line interface

Web interface

Supported formats

Legend:

• Directory
• Text file
• Package/archive file
• ️ SQLite file
• Binary file
• ✅ Supported
• ❌ Will not be supported

Note: SQLite-based formats are not detected by extension (.db); So you need to select the format (with UI or --read-format flag). Also don't confuse SQLite-based formats with SQLite mode.

Requirements

PyGlossary requires Python 3.12 or higher, and works in practically all mainstream operating systems, including GNU/Linux, Windows, Mac OS, FreeBSD and other common Unix-based operating systems.

As shown in screenshots, there are multiple User Interface types (multiple ways to use the program).

• Gtk3-based interface, uses PyGI+Gtk3. Best option for most Linux users. See doc/gtk3.md for how to install it on Linux and Mac OS X.

• Gtk4-based interface, uses PyGI+Gtk4. See doc/gtk4.md.

• Qt6-based interface, good native-looking interface for all operating systems. Requires either PySide6 or PyQt6. Uses a wizard-based UI flow for simplicity of use.

• wxPython-based interface, wizard-style GUI using wxPython. Install with pip install pyglossary[wx] (or install wxPython separately).

• Tkinter-based interface, meant to be used in the lack of more modern UI. Specially on Windows where Tkinter library is installed with Python itself. You can install Tkinter on Linux or Mac OS X.

• Command-line interface, works in all operating systems without any specific requirements, just type ./main.py --help or pyglossary --help

  • Interactive command-line interface
    • Requires: pip install prompt_toolkit
    • Perfect for mobile devices (like Termux on Android) where no GUI is available
    • Automatically selected if output file argument is not passed and one of these:
      • On Linux and $DISPLAY environment variable is empty or not set
        • For example when you are using a remote Linux machine over SSH
      • On Mac and no tkinter module is found
    • Manually select with --cmd or --ui=cmd
      • Minimally: ./main.py --cmd
      • You can still pass input file, or any flag/option
    • If both input and output files are passed, non-interactive cmd ui will be default.
      • Pass --interactive to change it.
    • If you are writing a script, you can pass --no-interactive to force disable interactive ui
      • Then you have to pass both input and output file arguments
    • Don't forget to use Up/Down or Tab keys in prompts!
      • Up/Down key shows you recent values you have used
      • Tab key shows available values/options
    • You can press Control+C (on Linux/Windows) at any prompt to exit

UI (User Interface) selection

When you run PyGlossary without any command-line arguments or options/flags, PyGlossary will try to run the first available interface:

• It tries to find PyGI+Gtk3 and open Gtk3-based interface.
• It tries to find PyGI+Gtk4 and open Gtk4-based interface.
• It tries to find PySide6 or PyQt6 and open Qt 6 interface.
• It tries to find wxPython and open wxPython-based interface.
• It tries to find Tkinter and open the classic Tkinter interface.
• It tries to open the Tk wizard interface (also Tkinter-based).
• If it's run in command line (with stdin connected to a terminal) it tries to find prompt_toolkit and run interactive command-line interface.
• It runs a HTTP server and opens the web interface in your browser.

The order depends on operating system. On GNU/Linux the default order is Gtk3, Gtk4, Qt 6, wxPython, Tkinter (classic), Tk wizard, then web. On Mac OS and Windows, Qt 6, wxPython, and the Tk wizard are tried before classic Tkinter and Gtk.

You can explicitly select user interface type using --ui

• ./main.py --ui=gtk3
• ./main.py --ui=gtk4
• ./main.py --ui=gtk which currently selects gtk3
• ./main.py --ui=qt6 or ./main.py --ui=qt: Qt 6 wizard-based interface
• ./main.py --ui=wx or ./main.py --wx: wxPython wizard-based interface
• ./main.py --ui=tk
• ./main.py --ui=tk_wizard: new wizard-based Tkinter interface
  • Shortcut: ./main.py --tkw
• ./main.py --ui=web
• ./main.py --ui=cmd with no extra arguments opens interactive command-line interface

Installation on Windows

You can either download the latest setup.exe from Releases and install it via a wizard, or install it using Python and pip:

• Download and install latest Python
• Open Start -> type Command -> right-click on Command Prompt -> Run as administrator
• To ensure you have pip, run: python -m ensurepip --upgrade
• To install, run: pip install --upgrade pyglossary
• Now you should be able to run pyglossary command
• If command was not found, make sure Python environment variables are set up:

Installation on Mac OS (14 & 15)

If you download the DMG file from Releases and install it, Mac may refuse to run it, showing the app is damaged and cannot be opened error. In that case, move the unpacked bundle to /Applications, and run this from the Terminal:

/usr/bin/xattr -d com.apple.quarantine /Applications/PyGlossaryWX.app

Or

/usr/bin/xattr -d com.apple.quarantine /Applications/PyGlossaryTK.app

Now you should be able to open the app by right-clicking on /Applications/PyGlossary.app in Finder, selecting Open and confirming running an app unsigned by Apple (only needs to be done once).

Feature-specific requirements

• Using Sort by Locale feature requires PyICU

• Using --remove-html-all flag requires:

  pip install lxml beautifulsoup4

Some formats have additional requirements. If you have trouble with any format, please check the link given for that format to see its documentations.

The Qt 6 wizard GUI (--ui=qt, --ui=qt6, --qt, or --qt6) needs PySide6 or PyQt6: pip install pyglossary[qt6] (or install PySide6 separately). On macOS, that extra also installs pyobjc-framework-Cocoa so the Dock and app switcher can show PyGlossary’s icon (standalone python/CLI runs do not ship an .app bundle icon otherwise).

The wxPython wizard GUI (--ui=wx or --wx) needs wxPython: pip install pyglossary[wx] (or install wxPython separately). On macOS, that extra also installs pyobjc-framework-Cocoa for the same Dock icon behaviour as the Qt extra.

Using Termux on Android? See doc/termux.md

Configuration

See doc/config.rst.

Direct and indirect modes

Indirect mode means that input glossary is completely read and loaded into RAM, then converted into output format. This was the only method available in old versions (before 3.0.0).

Direct mode means entries are one-at-a-time read, processed and written into output glossary.

Direct mode was added to limit memory usage for large glossaries; But it may reduce the conversion time for most cases as well.

Converting glossaries into these formats requires sorting entries:

• StarDict
• EPUB-2
• Mobipocket E-Book
• Yomichan
• DictionaryForMIDs

That's why direct mode will not work for these formats, and PyGlossary has to switch to indirect mode (or it previously had to, see SQLite mode).

For other formats, direct mode will be default. You may override this by --indirect flag.

SQLite mode

As mentioned above, converting glossaries to some specific formats will need them to l