or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/pypi-pymsgbox

A simple, cross-platform, pure Python module for JavaScript-like message boxes.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pymsgbox@1.0.x

To install, run

npx @tessl/cli install tessl/pypi-pymsgbox@1.0.0

index.mddocs/

PyMsgBox

A simple, cross-platform, pure Python module for JavaScript-like message boxes. PyMsgBox provides four essential dialog functions that create modal message boxes for user interaction, supporting both cross-platform tkinter implementation and native Windows dialogs when available.

Package Information

  • Package Name: PyMsgBox
  • Language: Python
  • Installation: pip install PyMsgBox

Core Imports

import pymsgbox

All functions available via star import:

from pymsgbox import *

Specific function imports:

from pymsgbox import alert, confirm, prompt, password

Basic Usage

import pymsgbox

# Display a simple alert
pymsgbox.alert('Hello World!', 'My Alert')

# Get user confirmation
result = pymsgbox.confirm('Do you want to continue?', 'Confirm Action')
if result == 'OK':
    print('User confirmed')

# Get text input from user
name = pymsgbox.prompt('Enter your name:', 'User Input')
if name:
    print(f'Hello, {name}!')

# Get password input (masked)
password = pymsgbox.password('Enter password:', 'Authentication')
if password:
    print('Password entered')

Capabilities

Alert Dialogs

Displays a simple message box with text and a single button. Returns the text of the button clicked.

def alert(text='', title='', button='OK', root=None, timeout=None, icon=NO_ICON, _tkinter=False):
    """
    Display a simple message box with text and a single button.
    
    Parameters:
    - text (str): Message text to display
    - title (str): Window title
    - button (str): Text for the button (default: 'OK')
    - root: Tkinter root window (optional)
    - timeout (int): Timeout in milliseconds (tkinter only)
    - icon: Icon type for Windows native dialogs (NO_ICON, STOP, QUESTION, WARNING, INFO)
    - _tkinter (bool): Force tkinter implementation on Windows
    
    Returns:
    str: Text of the button clicked
    """

Confirmation Dialogs

Displays a message box with customizable buttons for user confirmation. Returns the text of the button clicked.

def confirm(text='', title='', buttons=('OK', 'Cancel'), root=None, timeout=None, icon=QUESTION, _tkinter=False):
    """
    Display a message box with customizable buttons for confirmation.
    
    Parameters:
    - text (str): Message text to display
    - title (str): Window title  
    - buttons (tuple/list): Button texts (default: ('OK', 'Cancel'))
    - root: Tkinter root window (optional)
    - timeout (int): Timeout in milliseconds (tkinter only)
    - icon: Icon type for Windows native dialogs
    - _tkinter (bool): Force tkinter implementation on Windows
    
    Returns:
    str: Text of the button clicked
    """

Text Input Dialogs

Displays a message box with a text input field and OK/Cancel buttons. Returns the entered text or None if cancelled.

def prompt(text='', title='', default='', root=None, timeout=None):
    """
    Display a message box with text input field.
    
    Parameters:
    - text (str): Message text to display
    - title (str): Window title
    - default (str): Default text in input field
    - root: Tkinter root window (optional)
    - timeout (int): Timeout in milliseconds
    
    Returns:
    str: Text entered by user, or None if cancelled
    """

Password Input Dialogs

Displays a message box with a masked text input field and OK/Cancel buttons. Returns the entered text or None if cancelled.

def password(text='', title='', default='', mask='*', root=None, timeout=None):
    """
    Display a message box with masked text input field.
    
    Parameters:
    - text (str): Message text to display
    - title (str): Window title
    - default (str): Default text in input field
    - mask (str): Character used to mask input (default: '*')
    - root: Tkinter root window (optional)
    - timeout (int): Timeout in milliseconds
    
    Returns:
    str: Text entered by user, or None if cancelled
    """

Constants

Button Text Constants

Standard button text constants for consistent UI:

OK_TEXT = 'OK'
CANCEL_TEXT = 'Cancel'
YES_TEXT = 'Yes'
NO_TEXT = 'No'
RETRY_TEXT = 'Retry'
ABORT_TEXT = 'Abort'
IGNORE_TEXT = 'Ignore'
TRY_AGAIN_TEXT = 'Try Again'  # Note: Windows native code incorrectly references "TRY_TEXT"
CONTINUE_TEXT = 'Continue'

Icon Constants (Windows)

Icon types for Windows native message boxes:

NO_ICON = 0
STOP = 0x10      # Error/stop icon
QUESTION = 0x20  # Question mark icon
WARNING = 0x30   # Warning/exclamation icon
INFO = 0x40      # Information icon

# Additional icon constant aliases (note: some contain intentional typos from original)
MB_ICONHAND = MB_ICONSTOP = MB_ICONERRPR = 0x10  # ICONERRPR has typo in original
MB_ICONQUESTION = 0x20
MB_ICONEXCLAIMATION = 0x30  # ICONEXCLAIMATION has typo in original  
MB_ICONASTERISK = MB_ICONINFOMRAITON = 0x40  # ICONINFOMRAITON has typo in original

Windows MessageBox Constants (Advanced)

Low-level constants used internally for Windows MessageBox API:

# Button type flags
MB_OK = 0x0
MB_OKCANCEL = 0x1
MB_ABORTRETRYIGNORE = 0x2
MB_YESNOCANCEL = 0x3
MB_YESNO = 0x4
MB_RETRYCANCEL = 0x5
MB_CANCELTRYCONTINUE = 0x6

# Default button flags
MB_DEFAULTBUTTON1 = 0x0
MB_DEFAULTBUTTON2 = 0x100
MB_DEFAULTBUTTON3 = 0x200
MB_DEFAULTBUTTON4 = 0x300

# Display flags
MB_SETFOREGROUND = 0x10000
MB_TOPMOST = 0x40000

# Return value constants
IDABORT = 0x3
IDCANCEL = 0x2
IDCONTINUE = 0x11
IDIGNORE = 0x5
IDNO = 0x7
IDOK = 0x1
IDRETRY = 0x4
IDTRYAGAIN = 0x10
IDYES = 0x6

Special Return Values

TIMEOUT_RETURN_VALUE = 'Timeout'  # Returned when dialog times out

Platform Behavior

Cross-Platform (All Systems)

  • Uses tkinter for all dialog types
  • Supports timeout parameter for automatic dismissal
  • Full customization of button text and count
  • Works on Windows, macOS, and Linux

Windows-Specific Enhancements

  • Native Windows MessageBox API used for alert() and confirm() when possible
  • Better OS integration and native look-and-feel
  • Falls back to tkinter when:
    • Timeout is specified
    • Custom button combinations not supported natively
    • _tkinter=True is explicitly set
  • prompt() and password() always use tkinter (no native Windows equivalent)

Error Handling

PyMsgBox handles various error conditions gracefully:

  • Missing tkinter: Functions assert tkinter availability before use
  • Window closure: Returns default button text when window is closed via X button
  • Timeout: Returns TIMEOUT_RETURN_VALUE when dialog times out
  • Invalid parameters: Converts text parameters to strings automatically

Usage Examples

Custom Button Combinations

import pymsgbox

# Yes/No dialog
result = pymsgbox.confirm('Save changes?', 'Save', buttons=('Yes', 'No'))

# Three-button dialog
result = pymsgbox.confirm('How to proceed?', 'Options', 
                         buttons=('Save', 'Discard', 'Cancel'))

# Single custom button
pymsgbox.alert('Task completed successfully!', 'Success', button='Awesome!')

Timeout Dialogs

import pymsgbox

# Auto-dismiss after 5 seconds
result = pymsgbox.alert('This will close automatically', 'Auto Close', timeout=5000)
if result == pymsgbox.TIMEOUT_RETURN_VALUE:
    print('Dialog timed out')

# Timed confirmation
result = pymsgbox.confirm('Quick decision needed!', 'Hurry', timeout=3000)

Input Validation

import pymsgbox

# Get non-empty input
while True:
    name = pymsgbox.prompt('Enter your name (required):', 'Registration')
    if name:  # Not None and not empty
        break
    if name is None:  # User cancelled
        print('Registration cancelled')
        break

# Password with confirmation
password = pymsgbox.password('Enter new password:', 'Set Password')
if password:
    confirm_pwd = pymsgbox.password('Confirm password:', 'Confirm')
    if password == confirm_pwd:
        print('Password set successfully')
    else:
        pymsgbox.alert('Passwords do not match!', 'Error')

Integration with GUI Applications

import tkinter as tk
import pymsgbox

# Create main window
root = tk.Tk()
root.title("My Application")

def show_dialog():
    # Pass root window for proper modal behavior
    result = pymsgbox.confirm('Are you sure?', 'Confirm', root=root)
    if result == 'OK':
        pymsgbox.alert('Action confirmed!', 'Result', root=root)

button = tk.Button(root, text="Show Dialog", command=show_dialog)
button.pack(pady=20)

root.mainloop()