Tiny TaskBot

Tiny TaskBot is a lightweight Python scheduler for timer-based and file-change tasks. It provides a simple way to automate recurring jobs, react to filesystem events, run commands, and send notifications. It's designed to be easy to configure and run with minimal setup.

Features

• Timer tasks: Schedule jobs to run daily at a specified time (e.g., 09:00).
• File-change tasks: Trigger actions by monitoring folders for modifications.
• Flexible Actions: Send cross-platform desktop notifications or execute any shell command.
• Dry-run Mode: Validate your configuration by printing what tasks would run without executing them.
• File Logging: Optionally redirect all output to a log file with timestamps.

Installation

Tiny TaskBot is available on the Python Package Index (PyPI). The recommended way to install it is using pip:

pip install tiny-taskbot

Build from source

If you prefer to install from the source code for development or contribution, follow these steps.

1. Clone the repository from GitLab:

git clone https://gitlab.com/dmxsoftware/tiny-taskbot.git
cd tiny-taskbot

2. It's highly recommended to use a virtual environment:

# For Linux/macOS
python3 -m venv venv
source venv/bin/activate

# For Windows
python -m venv venv
venv\\Scripts\\activate

3. Install the required dependencies:

pip install -r requirements.txt

4. Copy the example configuration file to get started:

cp example_tasks.json tasks.json

Usage

Getting started with Tiny TaskBot involves two simple steps:

1. Edit the tasks.json file to define your custom tasks. See the Task Configuration section for a detailed guide.

2. Run the bot from your terminal:

python bot.py

Command-line Arguments

You can modify the bot's behavior with optional arguments.

Dry-run mode: Preview tasks without executing them. (What is dry-run mode?)

python bot.py --dry-run

Enable logging: Write all output to a file.

python bot.py --log scheduler.log

You can also combine arguments:

python bot.py --dry-run --log dry_run.log

Task Configuration (tasks.json)

All tasks are defined in a tasks.json file, which is a JSON array of task objects. Each object represents a single task for the scheduler to manage.

Task Object Structure

Each task object must contain three main keys:

The trigger Object

This object determines the condition for the task to execute.

The action Object

This object determines what happens when the trigger condition is met.

Full Example

Below is an example tasks.json file demonstrating different task types.

[
  {
    "name": "Morning Reminder",
    "trigger": {
      "type": "timer",
      "time": "09:00"
    },
    "action": {
      "type": "notify",
      "message": "Good morning! Time to start your day."
    }
  },
  {
    "name": "Run Backup Script",
    "trigger": {
      "type": "timer",
      "time": "23:00"
    },
    "action": {
      "type": "run_command",
      "command": "python3 backup.py"
    }
  },
  {
    "name": "Watch Documents Folder",
    "trigger": {
      "type": "file_change",
      "path": "/home/user/Documents"
    },
    "action": {
      "type": "notify",
      "message": "Documents folder has changed!"
    }
  }
]

Dry-run mode explained

The dry-run mode is a safeguard that allows you to check your configuration without any consequences. It will parse your tasks.json file and print a summary of the tasks it has loaded, but it will not start the scheduler or execute any actions.

Input:

python bot.py --dry-run

Example output:

1. Morning Reminder - Timer at 09:00 -> Notify: Good morning! Time to start your day.
2. Run Backup Script - Timer at 23:00 -> Run command: python3 backup.py
3. Watch Documents Folder - Watch folder /home/user/Documents -> Notify: Documents folder has changed!

Logging

You can log all scheduler output to a file using the --log option. This is useful for debugging or keeping a historical record of task activity.

python bot.py --log my_log.log

You can also specify an absolute or relative path for the log file:

python bot.py --log /home/user/logs/my_log.log

• Logs all timer triggers and file-change events.
• Preserves timestamps and details of actions taken.

Tip: You can name the log file anything. For example: log_12-05-2025.txt.

Dependencies

Tiny TaskBot relies on a few excellent open-source libraries:

• Python 3.7+
• Rich - for beautiful console output.
• Watchdog - for file system monitoring.
• Schedule - for human-friendly timer scheduling.
• Plyer - for cross-platform notifications.

Useful tips

• Ensure timer tasks use the 24-hour format (HH:MM) to avoid ambiguity.
• File-change tasks require a valid path. Use absolute paths (e.g., /home/user/Documents or C:\Users\User\Documents) to prevent errors.

Support

If you find any bugs, have feature requests, or need help, please open an issue on the official GitLab repository.

License

Tiny TaskBot is licensed under the BSD license. Please see the LICENSE file in the repository for full details.