Whine's CrossFileDialog

whines_crossfiledialog

A Python wrapper for opening files and folders with the native file dialog.

Makes it easy to prompt the user with a native filepicker on all supported platforms.

Currently supports:

• GTK (via PyGObject, Zenity)
• KDE (via KDialog)
• Qt5/6 (via pyqt5/pyqt6)
• Windows 2000 and newer (via PyWin32)

Note

If you know how to add the file picker for MacOS, please consider doing so and make a pull request for it. Thank you!

Guys, I really don't know why, but why does QT and Kdialog have the same UI in my computer? Can someone who knows open an issue and explain it to me? Thank you!

Edit: The explanation has been provided in this issue comment.

Installing

pip install whines_crossfiledialog

Basic API usage

from whines_crossfiledialog import file_dialog

CrossFileDialog = file_dialog(["zenity"])

filename = CrossFileDialog.open_file()
multiple_filenames = CrossFileDialog.open_multiple()
save_filename = CrossFileDialog.save_file()
foldername = CrossFileDialog.choose_folder()

Documentation

file_dialog(picker_preference: Optional[list[str]] = None) -> BaseFileDialog

From a list of (optional) file picker preferences, return the first available implementation.

Args:

• picker_preference (Optional[list[str]], optional): Order of precedence for picking the file picker implementations. Defaults to None.

Raises:

• NoImplementationFoundException: Raise when no implementation is found from the list of preferences
• NoImplementationFoundException: Raise when no implementation is found for the current platform

Returns: BaseFileDialog: File picker class.

---

CrossFileDialog.open_file(title, start_dir, filter) -> str

Open a file selection dialog for selecting a file.

Args:

• title (str, optional): The title of the file selection dialog. Default is 'Choose a file'
• start_dir (str, optional): The starting directory for the dialog.
• filter (str | list[str | list[str] | dict[str, str]] | dict[str, str | list[str]], optional): The filter for file types to display. For an example, head to documentation the of whines_crossfiledialog.utils.filter_processor.

Returns: Optional[str]: The selected file's path.

Example: result = open_file(title="Select a file", start_dir="/path/to/starting/directory", filter="*.txt")

---

CrossFileDialog.open_multiple(title, start_dir, filter) -> list[str]

Open a file selection dialog for selecting multiple files.

Parameters:

• title (str, optional) — The title of the file selection dialog. Default is 'Choose one or more files'
• start_dir (str, optional) — The starting directory for the dialog.
• filter (str, list, dict, optional) — The filter for file types to display. It can be either:
  • a single wildcard (e.g.: "*.py", all files are displayed ending .py)
  • a list of wildcards (e.g.: ["*.py" "*.md"], all files are displayed ending either .py or .md)
  • a list of list optional one or more wildcards (e.g.: [["*.py", "*.md"], ["*.txt"]], user can switch between (.py, .md) and (.txt))
  • a dictionary mapping descriptions to wildcards (e.g.: {"PDF-Files": "*.pdf", "Python Project": ["\*.py", "*.md"]})

Returns:

• list[str]: A list of selected file paths.

---

CrossFileDialog.save_file(title, start_dir) -> str

Open a save file dialog.

Parameters:

• title (str, optional) — The title of the file selection dialog. Default is 'Enter the name of the file to save to'
• start_dir (str, optional) — The starting directory for the dialog.

Returns:

• str: The selected file's path for saving.

---

CrossFileDialog.save_file(title, start_dir) -> str

Open a folder selection dialog.

Parameters:

• title (str, optional) — The title of the file selection dialog. Default is 'Choose a folder'
• start_dir (str, optional) — The starting directory for the dialog.

Returns:

• str: The selected folder's path.

Getting Started

Follow this tutorial to install development prerequsites and get started.

Linting

In any platform, run the following command:

just lint

or:

python -m no_implicit_optional whines_crossfiledialog
python -m black -q school
python -m ruff check whines_crossfiledialog --fix

Attribution

Thank you so much to Maikel Wever and 3ricsonn for allowing their Github repository to be relicensed to LGPL 3.0 so that I can use this library in my own proprietary projects.

My deepest gratitude also goes to Benjamin Auquite for letting me use snippets of their code from a pull request they made to the Toga repository, and to Russell Keith-Magee (the owner of said repository) and Malcolm Smith for the advice regarding using BSD 3-Clause licensed code to an LGPL licensed codebase.

Thank you so much!

License

This software is licensed under the GNU LGPL 3.0.

Copyright (c) 2020-2025 Maikel Wever
Copyright (c) 2024-2025 whinee

Portions of this codebase, specifically whines_crossfiledialog/file_pickers/win32.py, are derived from Toga, which is licensed under the BSD 3-Clause License.

Copyright (c) 2014 Russell Keith-Magee.

See LICENSE.md for full details.