Exceptions

The ptouch library provides a hierarchy of exception classes for targeted error handling.

Exception Hierarchy

All printer-related exceptions inherit from PrinterConnectionError:

PrinterConnectionError (base)
├── PrinterNotFoundError
├── PrinterPermissionError
├── PrinterNetworkError
├── PrinterTimeoutError
└── PrinterWriteError

Exception Classes

exception PrinterConnectionError

Base exception for all printer connection errors.

Attributes:

  • original_error - The original exception that caused this error (if any)

Usage:

Catch this exception to handle all connection-related errors:

try:
    printer.print(label)
except PrinterConnectionError as e:
    print(f"Connection error: {e}")
    if e.original_error:
        print(f"Original error: {e.original_error}")
exception PrinterNotFoundError

Printer device not found or not accessible.

Common causes:

  • USB printer not connected

  • Wrong USB product ID

  • Device unplugged during operation

Solutions:

  • Check USB connection

  • Verify printer is powered on

  • Check product ID matches your model

exception PrinterPermissionError

Insufficient permissions to access printer (USB only).

Common causes:

  • Linux USB permissions not configured

  • Running without necessary privileges

Solutions:

See Installation for USB permissions setup (udev rules, user groups).

exception PrinterNetworkError

Network-specific connection errors.

Common causes:

  • Network connectivity issues

  • Firewall blocking port 9100

  • Printer disconnected from network

  • Connection lost during print

Solutions:

  • Check network connectivity

  • Verify firewall settings

  • Test with telnet <ip> 9100

  • Check WiFi signal strength

exception PrinterTimeoutError

Connection or operation timeout.

Common causes:

  • Printer powered off

  • Wrong IP address

  • Network latency

  • Printer busy or jammed

Solutions:

  • Verify printer is powered on

  • Check IP address is correct

  • Increase timeout if needed

  • Check printer status (paper, cover, etc.)

exception PrinterWriteError

Failed to write data to printer.

Common causes:

  • USB cable disconnected

  • USB communication error

  • Network connection lost

  • Incomplete data transfer

Solutions:

  • Check USB/network connection

  • Try different USB port or cable

  • Implement retry logic

  • Check for transient errors

Usage Examples

Catch All Connection Errors

from ptouch import PrinterConnectionError

try:
    printer.print(label)
except PrinterConnectionError as e:
    print(f"Failed to print: {e}")

Catch Specific Errors

from ptouch import (
    PrinterTimeoutError,
    PrinterNetworkError,
    PrinterPermissionError,
)

try:
    printer.print(label)
except PrinterPermissionError:
    print("Permission denied - see installation guide for USB setup")
except PrinterTimeoutError:
    print("Printer not responding - check if powered on")
except PrinterNetworkError as e:
    print(f"Network error: {e} - check connectivity")

Access Original Error

All exceptions preserve the original error:

try:
    printer.print(label)
except PrinterConnectionError as e:
    print(f"Error: {e}")
    if e.original_error:
        print(f"Caused by: {type(e.original_error).__name__}")
        print(f"Details: {e.original_error}")

Retry Logic

Implement retry logic for transient failures:

import time
from ptouch import PrinterTimeoutError, PrinterNetworkError

def print_with_retry(printer, label, max_retries=3):
    for attempt in range(max_retries):
        try:
            printer.print(label)
            return True
        except (PrinterTimeoutError, PrinterNetworkError) as e:
            if attempt == max_retries - 1:
                raise
            print(f"Retry {attempt + 1}/{max_retries}: {e}")
            time.sleep(2)
    return False

Best Practices

  1. Always catch PrinterConnectionError - Use specific exceptions for known scenarios, fall back to base exception

  2. Log original errors - The original_error attribute helps debugging

  3. Provide user feedback - Give actionable error messages:

    except PrinterTimeoutError:
    print("Printer not responding:")
    print("  1. Check if printer is powered on")
    print("  2. Verify network connection")
    print("  3. Check IP address is correct")

  4. Implement retries - Network and USB connections can have transient failures

  5. Check permissions early - Test USB permissions before batch jobs:

    from ptouch import ConnectionUSB, PrinterPermissionError

try:
    connection = ConnectionUSB()
    # Test connection
    printer = PTE550W(connection)
except PrinterPermissionError:
    print("USB permissions not configured")
    print("See: https://ptouch.readthedocs.io/en/latest/installation.html")
    sys.exit(1)

See Also