Skip to main content

A tool for converting dictionary files aka glossaries.

Project description

PyGlossary

PyPI Supported Python versions tests

A tool for converting dictionary files aka glossaries.

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

Format Extension Read Write
Aard 2 (slob) ๐Ÿ”ข .slob โœ… โœ…
AppleDict Binary ๐Ÿ“ .dictionary โœ… โŒ
AppleDict Source ๐Ÿ“ โœ…
Babylon BGL ๐Ÿ”ข .bgl โœ… โŒ
CSV ๐Ÿ“ .csv โœ… โœ…
DICT.org / Dictd server ๐Ÿ“ (๐Ÿ“.index) โœ… โœ…
DICT.org / dictfmt source ๐Ÿ“ (.dtxt) โœ…
dictunformat output file ๐Ÿ“ (.dictunformat) โœ…
DictionaryForMIDs ๐Ÿ“ (๐Ÿ“.mids) โœ… โœ…
DIKT JSON ๐Ÿ“ (.json) โœ…
EPUB-2 E-Book ๐Ÿ“ฆ .epub โŒ โœ…
FreeDict ๐Ÿ“ .tei โœ… โŒ
Gettext Source ๐Ÿ“ .po โœ… โœ…
HTML Directory (by file size) ๐Ÿ“ โŒ โœ…
JSON ๐Ÿ“ .json โœ…
Kobo E-Reader Dictionary ๐Ÿ“ฆ .kobo.zip โŒ โœ…
Kobo E-Reader Dictfile ๐Ÿ“ .df โœ… โœ…
Lingoes Source ๐Ÿ“ .ldf โœ… โœ…
Mobipocket E-Book ๐Ÿ”ข .mobi โŒ โœ…
Octopus MDict ๐Ÿ”ข .mdx โœ… โŒ
QuickDic version 6 ๐Ÿ”ข .quickdic โœ… โœ…
SQL ๐Ÿ“ .sql โŒ โœ…
StarDict ๐Ÿ“ (๐Ÿ“.ifo) โœ… โœ…
StarDict Textual File ๐Ÿ“ (.xml) โœ… โœ…
Tabfile ๐Ÿ“ .txt, .tab โœ… โœ…
Wiktextract ๐Ÿ“ .jsonl โœ… โŒ
XDXF ๐Ÿ“ .xdxf โœ… โŒ
Zim (Kiwix) ๐Ÿ”ข .zim โœ…
ABBYY Lingvo DSL ๐Ÿ‡ท๐Ÿ‡บ ๐Ÿ“ .dsl โœ… โŒ
Almaany.com (Arabic) ๐Ÿ›ข๏ธ .db โœ… โŒ
cc-kedict ๐Ÿ‡ฐ๐Ÿ‡ท ๐Ÿ“ โœ… โŒ
Dict.cc ๐Ÿ‡ฉ๐Ÿ‡ช ๐Ÿ›ข๏ธ .db โœ…
DigitalNK ๐Ÿ‡ฐ๐Ÿ‡ต ๐Ÿ›ข๏ธ .db โœ…
EDICT2 (CEDICT) ๐Ÿ‡จ๐Ÿ‡ณ ๐Ÿ“ (.u8) โœ… โŒ
JMDict ๐Ÿ‡ฏ๐Ÿ‡ต ๐Ÿ“ โœ… โŒ
JMnedict ๐Ÿ‡ฏ๐Ÿ‡ต ๐Ÿ“ โœ… โŒ
WordNet ๐Ÿ‡ฌ๐Ÿ‡ง ๐Ÿ“ โœ… โŒ
@wordset dictionary ๐Ÿ‡ฌ๐Ÿ‡ง ๐Ÿ“ โœ…
Yomichan / Yomitan ๐Ÿ‡ฏ๐Ÿ‡ต ๐Ÿ“ฆ (.zip) โœ…

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.11 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. 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. This is still not as complete as Gtk3 interface.

  • Tkinter-based interface, meant to be used in the lack of Gtk. 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 Tkinter and open Tkinter-based interface.
  • 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. Currently on Mac OS and Windows, Tkinter is checked before 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=tk
  • ./main.py --ui=web
  • ./main.py --ui=cmd

Installation on Windows

  • Download and install Python (3.10 or above)
  • 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:

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.

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:

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 loaded into RAM.

This can be problematic if the glossary is too big to fit into RAM. That's when you should try adding --sqlite flag to your command. Then it uses SQLite3 as intermediate storage for storing, sorting and then fetching entries. This fixes the memory issue, and may even reduce running time of conversion (depending on your home directory storage).

The temporary SQLite file is stored in cache directory then deleted after conversion (unless you pass --no-cleanup flag).

SQLite mode is automatically enabled for writing these formats if auto_sqlite config parameter is true (which is default). This also applies to when you pass --sort flag for any format. You may use --no-sqlite to override this and switch to indirect mode.

Currently you can not disable alternates in SQLite mode (--no-alts is ignored).

Sorting

There are two things than can activate sorting entries:

  • Output format requires sorting (as explained above)
  • You pass --sort flag in command line.

In the case of passing --sort, you can also pass:

  • --sort-key to select sort key aka sorting order (including locale), see doc/sort-key.md

  • --sort-encoding to change the encoding used for sort

    • UTF-8 is the default encoding for all sort keys and all output formats (unless mentioned otherwise)
    • This will only effect the order of entries, and will not corrupt words / definition
    • Non-encodable characters are replaced with ? byte (only for sorting)

Cache directory

Cache directory is used for storing temporary files which are either moved or deleted after conversion. You can pass --no-cleanup flag in order to keep them.

The path for cache directory:

  • Linux or BSD: ~/.cache/pyglossary/
  • Mac: ~/Library/Caches/PyGlossary/
  • Windows: C:\Users\USERNAME\AppData\Local\PyGlossary\Cache\

User plugins

If you want to add your own plugin without adding it to source code directory, or you want to use a plugin that has been removed from repository, you can place it in this directory:

  • Linux or BSD: ~/.pyglossary/plugins/
  • Mac: ~/Library/Preferences/PyGlossary/plugins/
  • Windows: C:\Users\USERNAME\AppData\Roaming\PyGlossary\plugins\

Linux packaging status

Packaging status

Using PyGlossary as a library

See doc/lib-usage.md for how to use PyGlossary as a Python library.

Internals

See doc/internals.md for information about internal glossary structure and entry filters.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyglossary-5.1.0.tar.gz (487.3 kB view details)

Uploaded Source

Built Distribution

pyglossary-5.1.0-py3-none-any.whl (644.2 kB view details)

Uploaded Python 3

File details

Details for the file pyglossary-5.1.0.tar.gz.

File metadata

  • Download URL: pyglossary-5.1.0.tar.gz
  • Upload date:
  • Size: 487.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for pyglossary-5.1.0.tar.gz
Algorithm Hash digest
SHA256 1d4584343e2b5bf6d75d07935a585e2a513dacd8818064c868a42a4eff08cd3c
MD5 97702e82d950934d252573aec78fb7dd
BLAKE2b-256 6e932e11840bb34a638efe3e3ca4f2f4a42e38552e2f30f9214e96d4d62459c6

See more details on using hashes here.

File details

Details for the file pyglossary-5.1.0-py3-none-any.whl.

File metadata

  • Download URL: pyglossary-5.1.0-py3-none-any.whl
  • Upload date:
  • Size: 644.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for pyglossary-5.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 67798ecbf7798a09cfe16b1a900dd950a0212bff3176a578956d1fc070cbdefa
MD5 c636a53555acc74c0727109d5a6b72e5
BLAKE2b-256 f255dc62305092c386096e6ae593aaca32aaf8c5d3018fcc01204b142e4bd7d7

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page