📅 calendar-sync

calendar-sync is a flexible utility to sync one or more ICS feeds (iCalendar) into a CalDAV-compatible calendar — ideal for mailbox.org, Nextcloud, Synology, and more.

It supports features such as:

• ✅ Deterministic UID generation for clean deduplication
• 📅 Emoji mapping for more readable calendar events
• 🔁 Full support for recurring events (e.g., yearly holidays) and custom extra events
• 🧼 Optional cleanup of previously imported events
• 📍 Location-based filtering (e.g., for regional holidays in Austria)
• 🐳 Docker deployment for simple automation
• 💡 Dry-run mode to preview changes without writing
• 🕓 Timezone-aware handling for accurate scheduling

This is perfect for importing:

• 🗑️ Municipal waste collection schedules (e.g., Müll App)
• 🇦🇹 Austrian public holidays
• 🏎️ Formula 1 calendar with free practice, qualifying, and GP events

Unlike subscription-based ICS calendars, this tool writes events directly into your calendar, giving you full control over notifications, offline visibility, and data retention.

Use it on your Synology NAS, a server, or as a cron-triggered Docker container — and never miss a bin collection or Grand Prix again.

calendar-sync.mp4

---

---

🍺 Please support me: Although all my software is free, it is always appreciated if you can support my efforts on Github with a contribution via Paypal - this allows me to write cool projects like this in my personal time and hopefully help you or your business.

---

✨ Features

• 🔁 Sync multiple ICS feeds to any CalDAV calendar
• 🧠 Deterministic UID generation & deduplication
• 🔁 Automatic expansion of YEARLY recurring events
• 📍 Location-based filtering for region-specific holidays
• 🧹 Optional cleanup of old imported events
• 📅 Supports emoji mapping for event names
• 🛑 Dry run mode to test before writing
• 🐳 Docker support for simple deployment

---

🚀 Usage

Manual

python src/calendar_sync.py --import
python src/calendar_sync.py --import --dry-run
python src/calendar_sync.py --cleanup

With Docker Compose

First, build the container:

docker-compose build

Then run the sync:

docker-compose run --rm calendar-sync --import
docker-compose run --rm calendar-sync --import --dry-run
docker-compose run --rm calendar-sync --cleanup

---

🧰 Manual Installation

git clone https://github.com/magicdude4eva/calendar-sync.git
cd calendar-sync
python3.13 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

---

⚙️ config.json

{
  "caldav_url": "https://dav-sso.mailbox.org/caldav/...",
  "username": "your@email.com",
  "password": "your-app-password",
  "timezone": "Europe/Vienna",
  "uid_prefix": "ICS-",
  "future_event_limit_days": 365,
  "ics_feeds": [
    {
      "url": "https://example.com/my.ics",
      "emoji_mapping": {
        "Papier": "♻️",
        "default": "📦"
      }
    }
  ]
}

---

🛠️ How It Works

• Fetches events from each configured ICS feed
• Normalizes dates and checks if the UID exists
• Skips, adds, or replaces events as needed
• Uses emoji mappings to prefix event names
• All-day events are handled properly (no time zone shift)
• Recurring RRULE:FREQ=YEARLY events are expanded into individual years
• Events can be filtered by LOCATION using import_locations

🗺️ For import_locations, configure it per feed. For example:

{
  "url": "https://www.feiertage-oesterreich.at/kalender-download/ics/feiertage-oesterreich.ics",
  "import_locations": "K,St,V",
  "emoji_mapping": {
    "§": "🇦🇹",
    "default": "🗓️"
  }
}

To discover valid locations, run the sync once and check the logs. Example:

INFO: ⏭️ Skipping 'St. Florian' (2025-05-04) due to unmatched location: OÖ

🗓️ Support for Yearly Recurring Events (RRULE:FREQ=YEARLY)

The script now automatically expands ICS events with RRULE:FREQ=YEARLY rules into individual event instances for each year, up to the configured future limit (future_event_limit_days).
This ensures recurring events like public holidays or anniversaries are correctly synced across multiple years.

Behavior:

• Detects yearly recurring events by scanning raw RRULE data.
• Expands the base event for each year (e.g. from 2025 to 2026).
• Skips events in the past or beyond the future limit.
• Deduplicates intelligently using UID hashing per year.

➕ Support for Custom Extra Events

In addition to ICS feeds, you can define your own custom events using the extra_events entry in config.json.

This allows you to add things like:

• 🌷 Mother's Day (2nd Sunday of May)
• 👨‍👧‍👦 Father's Day (2nd Sunday of June)
• 🔥 Summer Solstice (21st June)
• 🎃 Halloween (31st October)
• 🕯️ Advent Sundays
• 🧾 Tax Deadlines
• ☀️ Daylight Saving Time changes

Supported Formats:

Format	Description	Example
N.Weekday.Month	Nth weekday of a month	2.Sunday.5 → 2nd Sunday in May
-N.Weekday.Month	Nth weekday from end of month	-1.Sunday.3 → last Sunday in March
DD.MM.fixed	Fixed date	31.10.fixed → 31st October

Sample:

    "extra_events": [
      "☀️ Sommerzeit beginnt:-1.Sunday.3",
      "🌷 Muttertag:2.Sunday.5",
      "👨‍👧‍👦 Vatertag:2.Sunday.6",
      "🔥 Sonnwendfeier:21.6.fixed",
      "🧾 Steuererklärung:30.6.fixed",
      "🌒 Sommerzeit endet:-1.Sunday.10",
      "🎃 Halloween:31.10.fixed",
      "🕯️ 1. Advent:-4.Sunday.12",
      "🕯️ 2. Advent:-3.Sunday.12",
      "🕯️ 3. Advent:-2.Sunday.12",
      "🕯️ 4. Advent:-1.Sunday.12",
      "👹 Krampusnacht:5.12.fixed",
      "🎅 Nikolaus:6.12.fixed"    
      ],

---

🧪 Dry Run

Add --dry-run to see what would happen without making changes:

docker-compose run --rm calendar-sync --import --dry-run

---

🗂️ Project Structure

calendar-sync/
├── src/
│   ├── calendar_sync.py      # Entry script
│   └── utils.py              # Core sync logic
├── config.json               # Configuration
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── README.md

---

📷 mailbox.org Setup Guide

1. 🔐 Create Application Password

Go to Settings → Security → Application Passwords
Select Calendar and Addressbook Client (CalDAV/CardDAV)

---

2. 📅 Create a New Calendar

Go to the Calendar section → click + Add new calendar

---

3. 🔗 Get the CalDAV URL

Right-click your new calendar → Properties → Copy the URL

Paste it into config.json under "caldav_url"

---

📄 License

This project is licensed under the MIT License.

---

❤️ Contributing

PRs welcome! File issues or ideas via GitHub.

Donations are always welcome

🍺 Please support me: Although all my software is free, it is always appreciated if you can support my efforts on Github with a contribution via Paypal - this allows me to write cool projects like this in my personal time and hopefully help you or your business.

(CRO)    0xBAdB43af444055c4031B79a76F74895469BA0CD7 (Cronos)
(USDC)   0xBAdB43af444055c4031B79a76F74895469BA0CD7
(ETH)    0xfc316ba7d8dc325250f1adfafafc320ad75d87c0
(BTC)    1Mhq9SY6DzPhs7PNDx7idXFDWsGtyn7GWM
(BNB)    0xfc316ba7d8dc325250f1adfafafc320ad75d87c0
Crypto.com PayString: magicdude$paystring.crypto.com    

Go to Curve.com to add your Crypto.com card to ApplePay and signup to Crypto.com for a staking and free Crypto debit card.

Use Binance Exchange to trade #altcoins. I also accept old-school PayPal.