Logging and Error Handling

Relevant source files

The following files were used as context for generating this wiki page:

• error_logs/importing_errors_2025-11-01_14-52-12.txt
• pos_app.py
• notification_service.py
• config.example.json
• README_Notifications.txt
• test_telegram.py
• build_exe.bat

The project employs distinct logging and error handling strategies tailored to its two main components: the POSApplication GUI and the NotificationService background process. The GUI application focuses on immediate user feedback through dialog boxes for operational errors, with a specific file-based logging mechanism for batch operations like XLSX imports. The background service utilizes a more robust, formal logging framework with configurable levels, rotating file handlers, and separate outputs for general and error-level messages.

This document outlines the architecture and implementation of these systems.

Notification Service Logging

The NotificationService implements a comprehensive logging system using Python's standard logging module. It is designed for unattended operation, capturing detailed information for debugging and monitoring.

Sources: notification_service.py:448-504, config.example.json:18-24

Architecture

The logging system is configured in the _setup_logging method of the NotificationService class. It establishes a main logger (NotificationService) and attaches multiple handlers to direct log messages to different destinations based on their severity level.

The diagram below illustrates the flow of log messages from the service to their final destinations.

Configuration

Logging behavior is controlled by the logging section in config.json. This allows administrators to adjust verbosity and file management without modifying the source code.

Parameter	Description	Default Value
log_level	The minimum level of logs to be processed by the main logger (e.g., "INFO", "DEBUG").	"INFO"
log_file	Path to the main rotating log file.	"logs/notification_service.log"
error_log_file	Path to the dedicated error log file.	"logs/notification_errors.log"
max_bytes	Maximum size in bytes before a log file is rotated.	10485760 (10 MB)
backup_count	Number of old log files to keep.	5

Sources: config.example.json:18-24

Error Handling within the Service

The service includes specific error handling mechanisms for critical operations.

Telegram API Retry Logic

When sending a message via the Telegram API, the send_message function implements a retry mechanism with exponential backoff to handle transient network errors.

The sequence diagram below shows the retry process.

Database Connectivity

The POSDatabaseReader and StateTracker classes wrap all database operations in try...except sqlite3.Error blocks to catch and log any issues, preventing the service from crashing due to database problems like file locks or corruption.

Sources: notification_service.py:92-95, notification_service.py:240-243

POS Application Error Handling

The pos_app.py GUI application handles errors differently, prioritizing immediate feedback to the user.

User-Facing Error Dialogs

Most operational errors are caught using try...except blocks and presented to the user via tkinter.messagebox dialogs. This approach is used for:

• Product not found (scan_product).
• Insufficient stock (add_product_to_cart).
• Invalid user input in forms (edit_product_full, create_new_product_dialog).
• Database integrity errors (e.g., duplicate barcode).
• Failures during checkout (checkout).

# Example from checkout function
except Exception as e:
    messagebox.showerror("Error",
                       f"Error al procesar la venta:\n{str(e)}\n\n"
                       f"Por favor, verifique el inventario y contacte al administrador.")

Sources: pos_app.py:1691-1695

File System Fallback Mechanism

The application demonstrates robust error handling when initializing output paths. The _init_output_paths function attempts to create a recibos directory on the user's Desktop. If this fails (e.g., due to permissions), it falls back to a local receipts directory, and then to a temporary directory as a last resort. This ensures the application can always save receipts.

This flow prevents the application from failing at startup if the preferred directory is not writable.

XLSX Import Error Logging

A specialized file-based logging mechanism is implemented for the "Importar XLSX" feature. This is the only part of the GUI application that generates a persistent log file for errors.

Sources: pos_app.py:1820-1925

Process Flow

If more than 10 errors occur during an XLSX file import, the system generates a detailed .txt log file inside the error_logs directory. This prevents overwhelming the user with numerous dialog boxes for large files with many issues.

The diagram below outlines this logic.

Log File Format

The generated error log is a plain text file with a clear, human-readable format. It includes a summary and a detailed list of errors with corresponding row numbers from the source XLSX file.

Example Log File: error_logs/importing_errors_2025-11-01_14-52-12.txt

============================================================
XLSX Import Error Log
============================================================
Date: 2025-11-01 14:52:12
File: C:/Users/Admin/Downloads/LP- PAME SUSPENSION TRACKONE.xlsx

Summary:
- Products imported: 1099
- Products updated: 0
- Errors encountered: 12

============================================================
Detailed Errors:
============================================================
Fila 606: Valores numéricos inválidos
Fila 614: Valores numéricos inválidos
...

Sources: error_logs/importing_errors_2025-11-01_14-52-12.txt, pos_app.py:1886-1906

The creation of the error_logs/ directory is also mentioned as part of the build process documentation.
Sources: build_exe.bat:34

Summary of Mechanisms

The project utilizes a combination of logging and error handling techniques appropriate for different contexts.

Mechanism	Component	Scope	Output
logging Module	notification_service.py	Entire service	Console, logs/notification_service.log, logs/notification_errors.log
tkinter.messagebox	pos_app.py	User-facing operations	GUI dialog boxes
Custom .txt Log	pos_app.py	XLSX Import	error_logs/importing_errors_*.txt
try...except	Both	General error trapping	Varies (log entry, user message, etc.)
Fallback Logic	pos_app.py	File system access	Internal state change, console warning

Sources: notification_service.py, pos_app.py

This dual strategy ensures that the background service has robust, persistent logs for diagnostics, while the interactive GUI application provides immediate, user-friendly feedback and only resorts to file-based logging for complex, high-volume error scenarios.