Building the Notification Service Executable
Relevant source files
The following files were used as context for generating this wiki page:The pos-tioadan project includes a standalone Telegram notification service written in Python (notification_service.py). To simplify deployment on Windows machines that may not have a Python environment, a build script is provided to package this service into a single executable file named TelegramNotifications.exe. This executable runs as a background console application, monitoring the POS database for zero-stock products and sending daily sales reports via Telegram.
This document outlines the process of building this executable, its dependencies, and the steps required for deployment and configuration. The primary tool used for this process is PyInstaller.
Sources: build_notification_exe.bat, notification_service.py:5-12, README_Notifications.txt:4-7
Prerequisites
Before building the executable, the development environment must be set up with Python and the necessary dependencies.
Python Installation
A Python 3.7 or later installation is required. The install_dependencies.bat script verifies the Python installation before proceeding.
Sources: install_dependencies.bat:11-19
Dependencies
The notification service relies on two external Python packages which must be installed via pip.
| Package | Version | Purpose |
|---|---|---|
requests | >=2.31.0 | For making HTTP requests to the Telegram API. |
pytz | >=2023.3 | For handling timezones for daily reports. |
These can be installed by running the install_dependencies.bat script, which in turn executes pip install -r requirements.txt.
Sources: requirements.txt:5-6, install_dependencies.bat:22-32, notification_service.py:17-18
Build Process
The executable is created using the build_notification_exe.bat script, which automates the PyInstaller build process.
The following diagram illustrates the steps performed by the build script.
This diagram shows the build flow: cleaning old files, running PyInstaller, and handling success or failure.
Sources: build_notification_exe.bat
1. Cleaning Previous Builds
The script first cleans up any artifacts from previous builds to ensure a fresh start. It removes:
- The
build/directory. - The
dist/TelegramNotifications.exefile. - The
notification_service.specfile.
Sources: build_notification_exe.bat:12-15
2. Building with PyInstaller
The core of the script is the pyinstaller command, which bundles the Python script and its dependencies into a single executable.
pyinstaller --onefile --console --name="TelegramNotifications" ^
--hidden-import=requests ^
--hidden-import=pytz ^
notification_service.py
Sources: build_notification_exe.bat:19-23
The options used are detailed below:
| Option | Description |
|---|---|
--onefile | Packages everything into a single executable file. |
--console | Creates a console-based executable. This is necessary to see service logs and stop it with Ctrl+C. |
--name="TelegramNotifications" | Sets the name of the output executable to TelegramNotifications.exe. |
--hidden-import=requests | Explicitly includes the requests library, which PyInstaller might miss. |
--hidden-import=pytz | Explicitly includes the pytz library. |
notification_service.py | The main Python script to be compiled. |
Sources: build_notification_exe.bat:19-23
3. Build Output
Upon successful completion, the script places the final executable in the dist/ folder. The final output is dist\TelegramNotifications.exe.
Sources: build_notification_exe.bat:34-35
Deployment and Execution
After building, the executable must be deployed to the machine where it will monitor the POS system.
Deployment Files
The following files must be placed in the same directory on the target machine for the service to function correctly.
This diagram shows the executable and the files it depends on or creates during runtime.
Sources: build_notification_exe.bat:41-47, README_Notifications.txt:9-12, 22-25
| File / Directory | Description | Source |
|---|---|---|
TelegramNotifications.exe | The compiled notification service. | build_notification_exe.bat:34 |
config.json | Required. Contains Telegram API credentials and other settings. Must be created from config.example.json. | build_notification_exe.bat:42, notification_service.py:560-566 |
pos_inventory.db | Required. The main POS database that the service monitors. | build_notification_exe.bat:46, notification_service.py:228 |
notification_state.db | Auto-created. An SQLite database used to track sent notifications to prevent duplicates. | build_notification_exe.bat:44, notification_service.py:25 |
logs/ | Auto-created. A directory containing log files (notification_service.log, notification_errors.log) for debugging and monitoring. | build_notification_exe.bat:45, notification_service.py:581 |
Configuration (config.json)
The service is configured via a config.json file. This file must be created by copying config.example.json and filling in the required values.
Key configuration parameters include:
| Section | Key | Description |
|---|---|---|
telegram | bot_token | The API token for the Telegram bot, obtained from @BotFather. |
telegram | chat_id | The ID of the Telegram chat where notifications will be sent. |
polling | zero_stock_interval_seconds | How often (in seconds) to check for zero-stock products. Default: 300. |
daily_report | send_time | The time of day (HH:MM) to send the daily report. Default: "08:00". |
database | pos_db_path | Path to the POS database. Default: "pos_inventory.db". |
database | state_db_path | Path to the state tracking database. Default: "notification_state.db". |
logging | log_level | The logging level for the service (e.g., "INFO", "DEBUG"). Default: "INFO". |
Before running the service, it is recommended to verify the Telegram configuration using test_telegram.py (if a Python environment is available).
Sources: config.example.json, install_dependencies.bat:42-52, test_telegram.py:10-17
Running the Service
To start the service, simply execute TelegramNotifications.exe. A console window will open and display log messages, such as "Starting service...". This window must remain open for the service to continue running. To stop the service, press Ctrl+C in the console window.
This process is equivalent to running python notification_service.py using the run_service.bat script in a development environment.
Sources: run_service.bat, README_Notifications.txt:14-18
The following sequence diagram shows the startup process of the service.
This diagram illustrates how the main executable launches and manages its concurrent monitoring threads.
Sources: notification_service.py:755-772
Conclusion
The build_notification_exe.bat script provides a streamlined method for packaging the notification_service.py script into a self-contained Windows executable. This simplifies deployment by removing the need for a Python installation on the target machine, allowing the POS system owner to easily run the monitoring service. Proper deployment requires the executable to be placed alongside the pos_inventory.db and a correctly configured config.json file.