Python Zenity Wrapper

A comprehensive Python wrapper for Zenity dialogs, making it easy to create native desktop dialogs in your applications.

Note: A Bun version of this library is available at bun_zenity.

Installation

Install the Python Package

# Install from PyPI (once published)
pip3 install python-zenity-wrapper

# Or install from source
git clone https://github.com/codecaine-zz/python_zenity_wrapper.git
cd python_zenity_wrapper
pip3 install -e .

Install Zenity (Required)

This package requires Zenity to be installed on your system:

# macOS
brew install zenity

# Ubuntu/Debian
sudo apt-get install zenity

# Fedora
sudo dnf install zenity

Project Structure

python_zenity_wrapper/
├── zenity_wrapper.py       # Main Zenity wrapper module
├── app.py                  # Simple usage example
├── example_multiline.py    # Multiline form example
└── demo.py                 # Comprehensive demo of all features

Quick Start

Basic Usage

from zenity_wrapper import Zenity, InfoOptions

zenity = Zenity()
zenity.info("Hello, World!", InfoOptions(title="Greeting"))

Simple Example (app.py)

Run the simple example:

python3 app.py

Shows basic info, question, and form dialogs.

Multiline Form Example (example_multiline.py)

Run the multiline form example:

python3 example_multiline.py

Demonstrates creating a blog post form with multiline text area.

Comprehensive Demo (demo.py)

Run the full demo:

python3 demo.py

Demonstrates:

• All message dialogs (info, warning, error, question)
• All input dialogs (entry, password, scale, calendar)
• All selection dialogs (list, checklist, radiolist, color picker)
• File selection dialogs
• Progress dialogs
• Advanced forms with all field types
• Security validation

Usage Examples

Message Dialogs

from zenity_wrapper import Zenity, InfoOptions, QuestionOptions

zenity = Zenity()

# Info dialog
zenity.info("Operation completed!", InfoOptions(title="Success"))

# Question dialog
answer = zenity.question("Continue?", QuestionOptions(ok_label="Yes", cancel_label="No"))
if answer:
    print("User said yes")

Form with All Field Types

from zenity_wrapper import Zenity, FormField, FormsOptions

zenity = Zenity()

result = zenity.forms(
    [
        FormField(type='entry', label='Name'),
        FormField(type='password', label='Password'),
        FormField(type='multiline', label='Bio'),
        FormField(type='calendar', label='Birth Date'),
        FormField(type='combo', label='Gender', values=['Male', 'Female', 'Other']),
        FormField(type='list', label='Country', values=['USA', 'Canada', 'UK'])
    ],
    FormsOptions(
        title="Registration",
        text="Fill out the form",
        separator="||",
        width=600,
        height=700
    )
)

if result.button == 'ok' and result.values:
    print("Form submitted:", result.values)

Multiline Form (Bun Zenity Style)

from zenity_wrapper import Zenity, FormField, FormsOptions

zenity = Zenity()

result = zenity.forms(
    [
        FormField(type='entry', label='Title'),
        FormField(type='multiline', label='Description'),
        FormField(type='entry', label='Tags')
    ],
    FormsOptions(
        text="Create a Post",
        separator="||",
        width=600,
        height=800  # More height = more space for multiline field
    )
)

if result.button == 'ok' and result.values:
    title, description, tags = result.values
    print(f"Post: {title}\n{description}\nTags: {tags}")

Progress Dialog

from zenity_wrapper import Zenity, ProgressOptions
import time

zenity = Zenity()

progress = zenity.progress(
    "Processing...",
    ProgressOptions(percentage=0, auto_close=True)
)

for i in range(0, 101, 20):
    zenity.update_progress(progress, i, f"Step {i}%")
    time.sleep(0.5)

progress.stdin.close()
progress.wait()

Available Dialog Types

Message Dialogs

• info() - Information message
• warning() - Warning message
• error() - Error message
• question() - Yes/No question

Input Dialogs

• entry() - Text input
• password() - Password input (hidden text)
• scale() - Slider/number picker
• calendar() - Date picker

Selection Dialogs

• list() - List selection (single/multiple/checklist/radiolist)
• color_selection() - Color picker
• file_selection() - File/directory picker

Progress Dialogs

• progress() - Progress bar with live updates

Advanced Dialogs

• forms() - Multi-field forms
• text() - Text viewer/editor

Form Field Types

All 6 form field types supported:

1. entry - Single-line text input
2. password - Hidden password input
3. multiline - Multi-line text area
4. calendar - Date picker
5. combo - Dropdown selection
6. list - List selection

Security Features

✓ Input sanitization (null byte removal)
✓ Safe subprocess calls (list-based arguments)
✓ No shell=True usage (prevents shell injection)
✓ Environment variable isolation
✓ Proper error handling

API Documentation

Import all classes from zenity_wrapper:

from zenity_wrapper import (
    Zenity,
    # Options classes
    InfoOptions,
    QuestionOptions,
    EntryOptions,
    PasswordOptions,
    ScaleOptions,
    CalendarOptions,
    ListOptions,
    ColorSelectionOptions,
    FileSelectionOptions,
    ProgressOptions,
    FormsOptions,
    TextOptions,
    # Data classes
    FormField,
    FormsResult
)

License

MIT

Contributing

Contributions welcome! All dialogs should be tested with Zenity installed.