remindme_caldav/README.md

# remindme_caldav
## A Calendar Alerting Daemon

## Purpose
This script is a simple calendar alerting daemon written in Python. It monitors
.ics files for changes and sends alerts based on the events' start times,
recurrence rules, and alert triggers defined within these files. The main
purpose of this script is to provide reminders or notifications about upcoming
events.

## How it Works
The script works by parsing .ics files using the `icalendar` library, which
converts them into a Python dictionary format for easier manipulation. It then
processes each event and calculates when the next alert should be triggered
based on the event's start time, recurrence rules, and alert triggers. If an
alert is due to trigger, it sends a notification via email or XMPP (an instant
messaging protocol).

The script also monitors for changes in the directory containing .ics files
using the `watchdog` library. When a file is modified, created, or deleted, it
updates its internal list of events accordingly.

## How to Use It
This script should be used with a calendar syncing service such as vdirsyncer.
vdirsyncer can be scheduled using cron to sync regularly from the CalDav
server.

To use this script, you need Python 3 installed on your system. You can install
the required libraries by running:

```bash
pip install -r requirements.txt
```

You also need a .toml configuration file with the following structure:
```toml
[app]
calendar_dir = "/path/to/your/ics/files"
email_address = "your-email@example.com"
smtp_server = "smtp.example.com"
smtp_port = 587
smtp_username = "your-username"
smtp_password = "your-password"
...
```
The config file is passed to the script with the `--config` argument.

You can then run the script with:
```bash
python3 remindme_caldav.py --config /path/to/your/config.toml
```

## Installation
A Makefile and systemd service file is also included for Debian/Ubuntu based
systems. Make sure to modify the config file in the source directory before
installation. Also, please ensure that the calendar_dir exists and syncing
from a CalDav server before running the script.

This Makefile does the following:
  - install: Installs Python 3.11, creates a virtual environment in
    /opt/remindme_caldav/.venv, installs dependencies from requirements.txt
    into this virtual environment, copies the script to /opt/remindme_caldav/,
    copies the config file to /etc/remindme_caldav and sets up the systemd
    service file. It also sets up the logging dir in /opt/remindme_caldav/logs.

  - uninstall: Stops and disables the systemd service, removes the installation
    directory (/opt/remindme_caldav/), and deletes the systemd service file.

## Logging
The script uses Python's built-in logging module to handle logging. The
setup_logging(log_location) function sets up basic configuration for the
logger, including the log file location and format. 

Log levels are used to categorize logs based on their severity: DEBUG, INFO,
WARNING, ERROR, CRITICAL. By default, the log level is set to INFO. This can
be modified by passing a --loglevel argument when running the script.

The setup_log_location(logdir) function sets up the locations for three types
of logs: log, status, and alert_history. 

 - Log Location: This is where script logs are stored. These logs contain
   information about the general operation of the script, such as when it
   starts or stops, what files it's processing, errors etc. The logdir argument
   specifies the directory where these log files will be created. 

 - Status Location: This file contains information about the current state of
   each event being monitored by the script. It includes details such as the
   current time, the name of the event, its recurrence dates, and when the
   next alert will be triggered. The purpose of this file is to provide a
   real-time status update on what's happening in the script.

 - Alert History Location: This file logs all alerts that have been sent out
   by the script. It includes details such as the timestamp when the alert was
   triggered, and the definition time of the alert. The purpose of this file
   is to keep a record of all alerts that have been sent.