radicale-ics-sync 0.1.0__tar.gz

radicale_ics_sync-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Lehmkuhl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

radicale_ics_sync-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: radicale-ics-sync
+Version: 0.1.0
+Summary: Radicale plugin: subscribe to ICS feeds with filtering and local edit support
+Author-email: Jonathan Lehmkuhl <jonathanlehmkuhl@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Jonathan Lehmkuhl
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/jlmkuhl/radicale-ics-sync
+Project-URL: Repository, https://github.com/jlmkuhl/radicale-ics-sync
+Project-URL: Issues, https://github.com/jlmkuhl/radicale-ics-sync/issues
+Keywords: radicale,caldav,icalendar,ics,calendar,plugin,sync
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Scheduling
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: radicale>=3.0
+Requires-Dist: vobject>=0.9.6
+Dynamic: license-file
+
+# radicale-ics-sync
+
+Ever wanted to subscribe to an ICS feed (like a university timetable or a shared calendar) in [Radicale](https://radicale.org), but still be able to edit events locally? That's what this plugin is for.
+
+It syncs external ICS feeds into your Radicale calendars, keeps your local changes intact, and lets you filter out events you don't care about.
+
+## Installation
+
+```bash
+pip install radicale-ics-sync
+```
+
+Then configure Radicale to use the plugin (see [Configuration](#configuration)).
+
+## Configuration
+
+### Radicale config
+
+In your Radicale `config` file, set the storage type to `radicale_ics_sync.storage`:
+
+```ini
+[storage]
+type = radicale_ics_sync.storage
+filesystem_folder = /data/collections
+# ics_config is optional; if omitted, defaults to /config/ics_sync.json
+ics_config = /config/ics_sync.json
+```
+
+### Sync jobs (`ics_sync.json`)
+
+Create a file `/config/ics_sync.json` that defines which feeds to sync and where.
+
+```json
+[
+  {
+    "feed": "https://example.com/calendar.ics",
+    "collection": "username/calendar-name",
+    "sync_interval": 3600,
+    "include_patterns": [],
+    "exclude_patterns": []
+  }
+]
+```
+You can provide multiple pairs of feed + collection.
+Each sync job supports these fields:
+
+| Field | Required | Default | Description |
+|---|---|---|---|
+| `feed` | ✅ | — | URL of the ICS feed |
+| `collection` | ✅ | — | Radicale collection path |
+| `sync_interval` | | `3600` | How often to poll the feed, in seconds |
+| `include_patterns` | | `[]` | Can be strings or arbitrary regex patterns |
+| `exclude_patterns` | | `[]` | Can be strings or arbitrary regex patterns |
+
+> **Note:** The collection must already exist in Radicale before the plugin can sync to it. Create it through the Radicale web interface or your CalDAV client first.
+
+### Filtering
+
+Patterns are matched case-insensitively against the event's `SUMMARY` (title) field.
+
+```json
+{
+  "feed": "https://university.example.com/timetable.ics",
+  "collection": "alice/uni",
+  "exclude_patterns": ["Tutorial", "Exercise"]
+}
+```
+
+- If `include_patterns` is set: only events matching at least one pattern are synced
+- If `exclude_patterns` is set: events matching any pattern are removed
+
+## Docker setup
+
+Here is a minimal `docker-compose.yml`:
+
+```yaml
+services:
+  radicale:
+    build: .
+    container_name: radicale
+    restart: always
+    ports:
+      - "5232:5232"
+    volumes:
+      - ./config:/config/config:ro  # Radicale config file (not a directory)
+      - ./users:/config/users:ro
+      - ./ics_sync.json:/config/ics_sync.json:ro
+      - ./data:/data
+    read_only: true
+    tmpfs:
+      - /tmp
+```
+
+And a `Dockerfile` to install the plugin:
+
+```dockerfile
+FROM tomsquest/docker-radicale
+RUN /venv/bin/pip install radicale-ics-sync --no-cache-dir
+```
+
+## Non-Docker setup
+ 
+Install Radicale and the plugin:
+ 
+```bash
+pip install radicale radicale-ics-sync
+```
+ 
+Create your Radicale config (e.g. `~/.config/radicale/config`) and specify the path of your ics_sync.json:
+ 
+```ini
+[storage]
+type = radicale_ics_sync.storage
+filesystem_folder = ~/.local/share/radicale/collections
+ics_config = ~/.config/radicale/ics_sync.json
+```
+ 
+Then create `~/.config/radicale/ics_sync.json` and start Radicale:
+ 
+```bash
+radicale
+```
+
+## State
+
+The plugin stores its sync state in `ics_sync_hashes.json`, written next to your Radicale data. It tracks the last known content hash per event so unchanged events aren't rewritten. Safe to delete if you want a full re-sync on next startup.
+
+## Behavior
+
+The plugin polls ICS feeds at a regular interval. Events are filtered by include/exclude patterns before being written to Radicale. Events that disappear from the upstream feed or are filtered out are deleted from the Radicale collection. Local edits to upstream events are preserved, until the upstream event itself changes, in which case the upstream version wins. Local events are not touched.
+
+## Limitations & Roadmap
+
+- **Filtering is `SUMMARY`-only** — other fields (`LOCATION`, `DESCRIPTION`) aren't supported yet, but are planned.
+- **Upstream changes fully overwrite local edits** — field-level merge (e.g. keeping your local title while accepting upstream time changes) is planned.
+
+## Contributing
+
+Issues and pull requests are welcome.
+
+## License
+
+MIT

radicale_ics_sync-0.1.0/README.md

@@ -0,0 +1,143 @@
+# radicale-ics-sync
+
+Ever wanted to subscribe to an ICS feed (like a university timetable or a shared calendar) in [Radicale](https://radicale.org), but still be able to edit events locally? That's what this plugin is for.
+
+It syncs external ICS feeds into your Radicale calendars, keeps your local changes intact, and lets you filter out events you don't care about.
+
+## Installation
+
+```bash
+pip install radicale-ics-sync
+```
+
+Then configure Radicale to use the plugin (see [Configuration](#configuration)).
+
+## Configuration
+
+### Radicale config
+
+In your Radicale `config` file, set the storage type to `radicale_ics_sync.storage`:
+
+```ini
+[storage]
+type = radicale_ics_sync.storage
+filesystem_folder = /data/collections
+# ics_config is optional; if omitted, defaults to /config/ics_sync.json
+ics_config = /config/ics_sync.json
+```
+
+### Sync jobs (`ics_sync.json`)
+
+Create a file `/config/ics_sync.json` that defines which feeds to sync and where.
+
+```json
+[
+  {
+    "feed": "https://example.com/calendar.ics",
+    "collection": "username/calendar-name",
+    "sync_interval": 3600,
+    "include_patterns": [],
+    "exclude_patterns": []
+  }
+]
+```
+You can provide multiple pairs of feed + collection.
+Each sync job supports these fields:
+
+| Field | Required | Default | Description |
+|---|---|---|---|
+| `feed` | ✅ | — | URL of the ICS feed |
+| `collection` | ✅ | — | Radicale collection path |
+| `sync_interval` | | `3600` | How often to poll the feed, in seconds |
+| `include_patterns` | | `[]` | Can be strings or arbitrary regex patterns |
+| `exclude_patterns` | | `[]` | Can be strings or arbitrary regex patterns |
+
+> **Note:** The collection must already exist in Radicale before the plugin can sync to it. Create it through the Radicale web interface or your CalDAV client first.
+
+### Filtering
+
+Patterns are matched case-insensitively against the event's `SUMMARY` (title) field.
+
+```json
+{
+  "feed": "https://university.example.com/timetable.ics",
+  "collection": "alice/uni",
+  "exclude_patterns": ["Tutorial", "Exercise"]
+}
+```
+
+- If `include_patterns` is set: only events matching at least one pattern are synced
+- If `exclude_patterns` is set: events matching any pattern are removed
+
+## Docker setup
+
+Here is a minimal `docker-compose.yml`:
+
+```yaml
+services:
+  radicale:
+    build: .
+    container_name: radicale
+    restart: always
+    ports:
+      - "5232:5232"
+    volumes:
+      - ./config:/config/config:ro  # Radicale config file (not a directory)
+      - ./users:/config/users:ro
+      - ./ics_sync.json:/config/ics_sync.json:ro
+      - ./data:/data
+    read_only: true
+    tmpfs:
+      - /tmp
+```
+
+And a `Dockerfile` to install the plugin:
+
+```dockerfile
+FROM tomsquest/docker-radicale
+RUN /venv/bin/pip install radicale-ics-sync --no-cache-dir
+```
+
+## Non-Docker setup
+ 
+Install Radicale and the plugin:
+ 
+```bash
+pip install radicale radicale-ics-sync
+```
+ 
+Create your Radicale config (e.g. `~/.config/radicale/config`) and specify the path of your ics_sync.json:
+ 
+```ini
+[storage]
+type = radicale_ics_sync.storage
+filesystem_folder = ~/.local/share/radicale/collections
+ics_config = ~/.config/radicale/ics_sync.json
+```
+ 
+Then create `~/.config/radicale/ics_sync.json` and start Radicale:
+ 
+```bash
+radicale
+```
+
+## State
+
+The plugin stores its sync state in `ics_sync_hashes.json`, written next to your Radicale data. It tracks the last known content hash per event so unchanged events aren't rewritten. Safe to delete if you want a full re-sync on next startup.
+
+## Behavior
+
+The plugin polls ICS feeds at a regular interval. Events are filtered by include/exclude patterns before being written to Radicale. Events that disappear from the upstream feed or are filtered out are deleted from the Radicale collection. Local edits to upstream events are preserved, until the upstream event itself changes, in which case the upstream version wins. Local events are not touched.
+
+## Limitations & Roadmap
+
+- **Filtering is `SUMMARY`-only** — other fields (`LOCATION`, `DESCRIPTION`) aren't supported yet, but are planned.
+- **Upstream changes fully overwrite local edits** — field-level merge (e.g. keeping your local title while accepting upstream time changes) is planned.
+
+## Contributing
+
+Issues and pull requests are welcome.
+
+## License
+
+MIT

radicale_ics_sync-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=42"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "radicale-ics-sync"
+version = "0.1.0"
+description = "Radicale plugin: subscribe to ICS feeds with filtering and local edit support"
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.9"
+authors = [
+    { name = "Jonathan Lehmkuhl", email = "jonathanlehmkuhl@gmail.com" }
+]
+keywords = ["radicale", "caldav", "icalendar", "ics", "calendar", "plugin", "sync"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Scheduling",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = [
+    "radicale>=3.0",
+    "vobject>=0.9.6",
+]
+
+[project.urls]
+Homepage = "https://github.com/jlmkuhl/radicale-ics-sync"
+Repository = "https://github.com/jlmkuhl/radicale-ics-sync"
+Issues = "https://github.com/jlmkuhl/radicale-ics-sync/issues"

radicale_ics_sync-0.1.0/radicale_ics_sync/__init__.py

@@ -0,0 +1,3 @@
+"""radicale-ics-sync: Subscribe to ICS feeds with filtering and local edit support."""
+
+__version__ = "0.1.0"

radicale_ics_sync-0.1.0/radicale_ics_sync/storage.py

@@ -0,0 +1,318 @@
+"""
+Radicale ICS Sync - Storage Plugin
+
+Wraps Radicale's multifilesystem storage and syncs upstream ICS feeds
+into Radicale collections with event filtering.
+Upstream changes are detected via event content hashes.
+Newer upstream changes overwrite local changes.
+
+Configuration is read from the path set by ics_config in [storage]
+(default: /config/ics_sync.json).
+"""
+
+import json
+import os
+import re
+from typing import Dict, List
+
+import radicale.item as radicale_item
+from radicale.log import logger
+from radicale.storage import BaseStorage, ComponentNotFoundError
+from radicale.storage.multifilesystem import Storage as MultiFileSystemStorage
+
+from .upstream import SyncJob
+
+_DEFAULT_INTERVAL = 3600
+_DEFAULT_CONFIG_PATH = "/config/ics_sync.json"
+_BATCH_SIZE = 20
+
+PLUGIN_CONFIG_SCHEMA = {
+    "storage": {
+        "ics_config": {
+            "value": _DEFAULT_CONFIG_PATH,
+            "help": "path to the ics_sync.json configuration file",
+            "type": str,
+        },
+    }
+}
+
+
+def _load_hashes(path: str) -> Dict[str, Dict[str, Dict[str, str]]]:
+    """Load persisted upstream hashes from disk.
+
+    Returns {collection_path: {feed_url: {uid: hash}}}.
+    """
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+            total = sum(
+                len(uids)
+                for feed_dicts in data.values()
+                for uids in feed_dicts.values()
+            )
+            logger.info(
+                "radicale-ics-sync: loaded %d upstream hashes across %d collections from %s",
+                total,
+                len(data),
+                path,
+            )
+            return data
+    except FileNotFoundError:
+        logger.info("radicale-ics-sync: no hash db found at %s, starting fresh", path)
+        return {}
+    except Exception as e:
+        logger.warning(
+            "radicale-ics-sync: failed to load hash db: %s, starting fresh", e
+        )
+        return {}
+
+
+def _save_hashes(hashes: Dict[str, Dict[str, Dict[str, str]]], path: str) -> None:
+    """Persist upstream hashes to disk."""
+    try:
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(hashes, f, indent=2)
+    except Exception as e:
+        logger.warning("radicale-ics-sync: failed to save hash db: %s", e)
+
+
+def _load_sync_config(config_path: str) -> List[dict]:
+    """Load the configuration file."""
+    try:
+        with open(config_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+            if not isinstance(data, list):
+                logger.error("radicale-ics-sync: %s must be a JSON array", config_path)
+                return []
+            logger.info(
+                "radicale-ics-sync: loaded %d sync job(s) from %s",
+                len(data),
+                config_path,
+            )
+            return data
+    except FileNotFoundError:
+        logger.info(
+            "radicale-ics-sync: no config found at %s, running in passthrough mode",
+            config_path,
+        )
+        return []
+    except Exception as e:
+        logger.error("radicale-ics-sync: failed to load config %s: %s", config_path, e)
+        return []
+
+
+def _compile_patterns(patterns: List[str]) -> List[re.Pattern]:
+    """Compile a list of regex pattern strings, case-insensitive.
+
+    Invalid patterns are skipped with a warning.
+    """
+    compiled = []
+    for pattern in patterns:
+        try:
+            compiled.append(re.compile(pattern, re.IGNORECASE))
+        except re.error as e:
+            logger.warning("radicale-ics-sync: invalid pattern %r: %s", pattern, e)
+    return compiled
+
+
+class Storage(BaseStorage):
+    """ICS Sync storage plugin.
+
+    Delegates all standard CalDAV operations to Radicale's built-in
+    multifilesystem storage, while adding upstream ICS feed syncing on top.
+    """
+
+    def __init__(self, configuration):
+        super().__init__(configuration.copy(PLUGIN_CONFIG_SCHEMA))
+        self._delegate = MultiFileSystemStorage(configuration)
+        self._sync_jobs: List[SyncJob] = []
+        filesystem_folder = configuration.get("storage", "filesystem_folder")
+        self._hash_db_path = os.path.join(
+            os.path.dirname(os.path.normpath(filesystem_folder)),
+            "ics_sync_hashes.json",
+        )
+        self._upstream_hashes: Dict[str, Dict[str, Dict[str, str]]] = _load_hashes(
+            self._hash_db_path
+        )
+        self._setup_sync_jobs(self.configuration)
+        logger.info("radicale-ics-sync: storage plugin loaded")
+
+    def _setup_sync_jobs(self, configuration) -> None:
+        """Read sync jobs from the config file and start a thread for each."""
+        config_path = configuration.get("storage", "ics_config")
+        sync_jobs = _load_sync_config(config_path)
+        if not sync_jobs:
+            return
+
+        for job in sync_jobs:
+            feed_url = job.get("feed")
+            collection_path = job.get("collection")
+
+            if not feed_url:
+                logger.error("radicale-ics-sync: sync job missing 'feed': %s", job)
+                continue
+            if not collection_path:
+                logger.error(
+                    "radicale-ics-sync: sync job missing 'collection': %s", job
+                )
+                continue
+
+            interval = job.get("sync_interval", _DEFAULT_INTERVAL)
+            include_patterns = _compile_patterns(job.get("include_patterns", []))
+            exclude_patterns = _compile_patterns(job.get("exclude_patterns", []))
+
+            if include_patterns:
+                logger.info(
+                    "radicale-ics-sync: [%s] include patterns: %s",
+                    collection_path,
+                    [p.pattern for p in include_patterns],
+                )
+            if exclude_patterns:
+                logger.info(
+                    "radicale-ics-sync: [%s] exclude patterns: %s",
+                    collection_path,
+                    [p.pattern for p in exclude_patterns],
+                )
+
+            sync_job = SyncJob(
+                url=feed_url,
+                interval_seconds=interval,
+                on_update=lambda events, hashes, p=collection_path, u=feed_url: (
+                    self._sync_events(p, u, events, hashes)
+                ),
+                include_patterns=include_patterns,
+                exclude_patterns=exclude_patterns,
+            )
+            sync_job.start()
+            self._sync_jobs.append(sync_job)
+            logger.info(
+                "radicale-ics-sync: registered sync job: %s → %s (every %ds)",
+                feed_url,
+                collection_path,
+                interval,
+            )
+
+    def _sync_events(
+        self,
+        collection_path: str,
+        feed_url: str,
+        events: Dict[str, str],
+        hashes: Dict[str, str],
+    ) -> None:
+        """Sync upstream events to Radicale for a specific feed + collection.
+
+        Deletes and writes are processed in batches of _BATCH_SIZE so that the
+        write lock is released between batches, allowing Radicale to serve
+        CalDAV requests in the gaps.
+        """
+        path = "/" + collection_path.strip("/")
+
+        # Phase 1: verify the collection exists and compute both work lists.
+        with self._delegate.acquire_lock("w"):
+            collections = list(self._delegate.discover(path, depth="0"))
+            if not collections:
+                logger.warning(
+                    "radicale-ics-sync: collection %r not found, "
+                    "skipping sync (create it in the Radicale web UI first)",
+                    collection_path,
+                )
+                return
+
+            collection_feeds = self._upstream_hashes.setdefault(collection_path, {})
+            feed_hashes = collection_feeds.setdefault(feed_url, {})
+
+            to_delete = list(set(feed_hashes.keys()) - set(events.keys()))
+            to_write = [
+                (uid, ics_text)
+                for uid, ics_text in events.items()
+                if feed_hashes.get(uid) != hashes[uid]
+            ]
+            skipped = len(events) - len(to_write)
+
+        # Phase 2: delete stale events in batches.
+        deleted = 0
+        for i in range(0, len(to_delete), _BATCH_SIZE):
+            batch = to_delete[i : i + _BATCH_SIZE]
+            with self._delegate.acquire_lock("w"):
+                collections = list(self._delegate.discover(path, depth="0"))
+                if not collections:
+                    logger.warning(
+                        "radicale-ics-sync: collection %r disappeared during sync, "
+                        "aborting",
+                        collection_path,
+                    )
+                    return
+                collection = collections[0]
+
+                for uid in batch:
+                    href = uid + ".ics"
+                    try:
+                        collection.delete(href)
+                        del feed_hashes[uid]
+                        deleted += 1
+                        logger.debug("radicale-ics-sync: deleted event %r", uid)
+                    except ComponentNotFoundError:
+                        del feed_hashes[uid]
+                        logger.debug(
+                            "radicale-ics-sync: event %r already gone, skipping", uid
+                        )
+                    except Exception as e:
+                        logger.warning(
+                            "radicale-ics-sync: failed to delete event %r: %s", uid, e
+                        )
+
+                _save_hashes(self._upstream_hashes, self._hash_db_path)
+
+        # Phase 3: write new/changed events in batches.
+        written = 0
+        for i in range(0, len(to_write), _BATCH_SIZE):
+            batch = to_write[i : i + _BATCH_SIZE]
+            with self._delegate.acquire_lock("w"):
+                collections = list(self._delegate.discover(path, depth="0"))
+                if not collections:
+                    logger.warning(
+                        "radicale-ics-sync: collection %r disappeared during sync, "
+                        "aborting",
+                        collection_path,
+                    )
+                    return
+                collection = collections[0]
+
+                for uid, ics_text in batch:
+                    href = uid + ".ics"
+                    try:
+                        item = radicale_item.Item(collection=collection, text=ics_text)
+                        collection.upload(href, item)
+                        feed_hashes[uid] = hashes[uid]
+                        written += 1
+                    except Exception as e:
+                        logger.warning(
+                            "radicale-ics-sync: failed to write event %r: %s", uid, e
+                        )
+
+                _save_hashes(self._upstream_hashes, self._hash_db_path)
+
+        logger.info(
+            "radicale-ics-sync: [%s] wrote %d, deleted %d, skipped %d unchanged",
+            collection_path,
+            written,
+            deleted,
+            skipped,
+        )
+
+    def discover(self, path, depth="0", child_context_manager=None, user_groups=None):
+        return self._delegate.discover(
+            path, depth, child_context_manager, user_groups or set()
+        )
+
+    def move(self, item, to_collection, to_href):
+        return self._delegate.move(item, to_collection, to_href)
+
+    def create_collection(self, href, items=None, props=None):
+        return self._delegate.create_collection(href, items, props)
+
+    def acquire_lock(self, mode, user="", *args, **kwargs):
+        return self._delegate.acquire_lock(mode, user, *args, **kwargs)
+
+    def verify(self):
+        return self._delegate.verify()

radicale_ics_sync-0.1.0/radicale_ics_sync/upstream.py

@@ -0,0 +1,195 @@
+"""
+Upstream ICS feed syncing and filtering.
+
+Fetches remote ICS feeds, filters events by patterns,
+and detects changes via per-event content hashes.
+Polling runs in a background thread at a configurable interval.
+"""
+
+import copy
+import hashlib
+import json
+import re
+import threading
+from typing import Callable, Dict, List, Optional, Tuple
+from urllib.error import URLError
+from urllib.request import Request, urlopen
+
+import vobject
+from radicale.log import logger
+from radicale_ics_sync import __version__
+
+# Fields that determine if an event has meaningfully changed.
+_RELEVANT_FIELDS = ("SUMMARY", "DTSTART", "DTEND", "LOCATION", "DESCRIPTION")
+
+
+def _fetch_raw(url: str) -> Optional[str]:
+    """Fetch raw text from a URL. Returns None on failure."""
+    try:
+        req = Request(url, headers={"User-Agent": f"radicale-ics-sync/{__version__}"})
+        with urlopen(req, timeout=30) as response:
+            charset = response.headers.get_content_charset("utf-8")
+            return response.read().decode(charset)
+    except URLError as e:
+        logger.warning("radicale-ics-sync: failed to fetch %r: %s", url, e)
+        return None
+    except Exception as e:
+        logger.warning("radicale-ics-sync: unexpected error fetching %r: %s", url, e)
+        return None
+
+
+def _event_content_hash(component: vobject.base.Component) -> str:
+    """Compute a stable hash of an event's meaningful fields."""
+    fields = {}
+    for field in _RELEVANT_FIELDS:
+        field_list = component.contents.get(field.lower(), [])
+        fields[field] = str(field_list[0].value) if field_list else ""
+    stable = json.dumps(fields, sort_keys=True)
+    return hashlib.sha256(stable.encode()).hexdigest()
+
+
+def _matches_any(summary: str, patterns: List[re.Pattern]) -> bool:
+    """Return True if summary matches any of the compiled patterns."""
+    return any(p.search(summary) for p in patterns)
+
+
+def _filter_events(
+    components: List[vobject.base.Component],
+    include_patterns: List[re.Pattern],
+    exclude_patterns: List[re.Pattern],
+) -> List[vobject.base.Component]:
+    """Filter VEVENT components by include and exclude patterns on SUMMARY."""
+    result = []
+    for component in components:
+        try:
+            summary = component.summary.value
+        except AttributeError:
+            summary = ""
+
+        if include_patterns and not _matches_any(summary, include_patterns):
+            continue
+        if exclude_patterns and _matches_any(summary, exclude_patterns):
+            continue
+        result.append(component)
+    return result
+
+
+def _parse_events(
+    ics_text: str,
+    include_patterns: Optional[List[re.Pattern]] = None,
+    exclude_patterns: Optional[List[re.Pattern]] = None,
+) -> Optional[Tuple[Dict[str, str], Dict[str, str]]]:
+    """Parse the content of an ICS file into per-event ICS text and per-event content hashes.
+    Applies filtering before hashing.
+
+    Returns None on parse failure.
+    Returns {uid: ics_text}, {uid: content_hash} on success.
+    """
+    events: Dict[str, str] = {}
+    hashes: Dict[str, str] = {}
+    try:
+        calendar = vobject.readOne(ics_text)
+    except Exception as e:
+        logger.error("radicale-ics-sync: failed to parse ICS: %s", e)
+        return None
+
+    all_components = list(calendar.components())
+    timezones = [c for c in all_components if c.name == "VTIMEZONE"]
+    components = [c for c in all_components if c.name == "VEVENT"]
+
+    # Apply filtering
+    filtered = _filter_events(
+        components,
+        include_patterns or [],
+        exclude_patterns or [],
+    )
+
+    if include_patterns or exclude_patterns:
+        logger.info(
+            "radicale-ics-sync: %d/%d events passed filter",
+            len(filtered),
+            len(components),
+        )
+
+    for component in filtered:
+        try:
+            uid = component.uid.value
+        except AttributeError:
+            uid = hashlib.sha256(component.serialize().encode()).hexdigest()
+            component.add("uid").value = uid
+
+        wrapper = vobject.iCalendar()
+        for tz in timezones:
+            wrapper.add(copy.deepcopy(tz))
+        wrapper.add(component)
+        events[uid] = wrapper.serialize()
+        hashes[uid] = _event_content_hash(component)
+
+    return events, hashes
+
+
+def _feed_content_hash(hashes: Dict[str, str]) -> str:
+    """Compute a stable hash of the entire feed from per-event hashes."""
+    stable = json.dumps(hashes, sort_keys=True)
+    return hashlib.sha256(stable.encode()).hexdigest()
+
+
+class SyncJob:
+    """Manages periodic polling of a single upstream ICS feed URL."""
+
+    def __init__(
+        self,
+        url: str,
+        interval_seconds: int,
+        on_update: Callable[[Dict[str, str], Dict[str, str]], None],
+        include_patterns: Optional[List[re.Pattern]] = None,
+        exclude_patterns: Optional[List[re.Pattern]] = None,
+    ) -> None:
+        self._url = url
+        self._interval = interval_seconds
+        self._on_update = on_update
+        self._include_patterns = include_patterns or []
+        self._exclude_patterns = exclude_patterns or []
+        self._last_feed_hash: Optional[str] = None
+        self._thread: Optional[threading.Thread] = None
+        self._stop_event = threading.Event()
+
+    def fetch_once(self) -> None:
+        """Fetch the feed once and call on_update if content changed."""
+        logger.info("radicale-ics-sync: fetching upstream feed %r", self._url)
+        raw = _fetch_raw(self._url)
+        if raw is None:
+            return
+
+        result = _parse_events(raw, self._include_patterns, self._exclude_patterns)
+        if result is None:
+            return
+        events, hashes = result
+
+        feed_hash = _feed_content_hash(hashes)
+        if feed_hash == self._last_feed_hash:
+            logger.info("radicale-ics-sync: feed unchanged, skipping")
+            return
+
+        logger.info("radicale-ics-sync: feed updated, %d events", len(events))
+        self._last_feed_hash = feed_hash
+        self._on_update(events, hashes)
+
+    def start(self) -> None:
+        """Start background polling thread."""
+        self._thread = threading.Thread(
+            target=self._poll_loop, daemon=True, name="ics-sync-poller"
+        )
+        self._thread.start()
+        logger.info(
+            "radicale-ics-sync: polling %r every %ds", self._url, self._interval
+        )
+
+    def stop(self) -> None:
+        """Stop background polling thread."""
+        self._stop_event.set()
+
+    def _poll_loop(self) -> None:
+        self.fetch_once()
+        while not self._stop_event.wait(timeout=self._interval):
+            self.fetch_once()

radicale_ics_sync-0.1.0/radicale_ics_sync.egg-info/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: radicale-ics-sync
+Version: 0.1.0
+Summary: Radicale plugin: subscribe to ICS feeds with filtering and local edit support
+Author-email: Jonathan Lehmkuhl <jonathanlehmkuhl@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Jonathan Lehmkuhl
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/jlmkuhl/radicale-ics-sync
+Project-URL: Repository, https://github.com/jlmkuhl/radicale-ics-sync
+Project-URL: Issues, https://github.com/jlmkuhl/radicale-ics-sync/issues
+Keywords: radicale,caldav,icalendar,ics,calendar,plugin,sync
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Scheduling
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: radicale>=3.0
+Requires-Dist: vobject>=0.9.6
+Dynamic: license-file
+
+# radicale-ics-sync
+
+Ever wanted to subscribe to an ICS feed (like a university timetable or a shared calendar) in [Radicale](https://radicale.org), but still be able to edit events locally? That's what this plugin is for.
+
+It syncs external ICS feeds into your Radicale calendars, keeps your local changes intact, and lets you filter out events you don't care about.
+
+## Installation
+
+```bash
+pip install radicale-ics-sync
+```
+
+Then configure Radicale to use the plugin (see [Configuration](#configuration)).
+
+## Configuration
+
+### Radicale config
+
+In your Radicale `config` file, set the storage type to `radicale_ics_sync.storage`:
+
+```ini
+[storage]
+type = radicale_ics_sync.storage
+filesystem_folder = /data/collections
+# ics_config is optional; if omitted, defaults to /config/ics_sync.json
+ics_config = /config/ics_sync.json
+```
+
+### Sync jobs (`ics_sync.json`)
+
+Create a file `/config/ics_sync.json` that defines which feeds to sync and where.
+
+```json
+[
+  {
+    "feed": "https://example.com/calendar.ics",
+    "collection": "username/calendar-name",
+    "sync_interval": 3600,
+    "include_patterns": [],
+    "exclude_patterns": []
+  }
+]
+```
+You can provide multiple pairs of feed + collection.
+Each sync job supports these fields:
+
+| Field | Required | Default | Description |
+|---|---|---|---|
+| `feed` | ✅ | — | URL of the ICS feed |
+| `collection` | ✅ | — | Radicale collection path |
+| `sync_interval` | | `3600` | How often to poll the feed, in seconds |
+| `include_patterns` | | `[]` | Can be strings or arbitrary regex patterns |
+| `exclude_patterns` | | `[]` | Can be strings or arbitrary regex patterns |
+
+> **Note:** The collection must already exist in Radicale before the plugin can sync to it. Create it through the Radicale web interface or your CalDAV client first.
+
+### Filtering
+
+Patterns are matched case-insensitively against the event's `SUMMARY` (title) field.
+
+```json
+{
+  "feed": "https://university.example.com/timetable.ics",
+  "collection": "alice/uni",
+  "exclude_patterns": ["Tutorial", "Exercise"]
+}
+```
+
+- If `include_patterns` is set: only events matching at least one pattern are synced
+- If `exclude_patterns` is set: events matching any pattern are removed
+
+## Docker setup
+
+Here is a minimal `docker-compose.yml`:
+
+```yaml
+services:
+  radicale:
+    build: .
+    container_name: radicale
+    restart: always
+    ports:
+      - "5232:5232"
+    volumes:
+      - ./config:/config/config:ro  # Radicale config file (not a directory)
+      - ./users:/config/users:ro
+      - ./ics_sync.json:/config/ics_sync.json:ro
+      - ./data:/data
+    read_only: true
+    tmpfs:
+      - /tmp
+```
+
+And a `Dockerfile` to install the plugin:
+
+```dockerfile
+FROM tomsquest/docker-radicale
+RUN /venv/bin/pip install radicale-ics-sync --no-cache-dir
+```
+
+## Non-Docker setup
+ 
+Install Radicale and the plugin:
+ 
+```bash
+pip install radicale radicale-ics-sync
+```
+ 
+Create your Radicale config (e.g. `~/.config/radicale/config`) and specify the path of your ics_sync.json:
+ 
+```ini
+[storage]
+type = radicale_ics_sync.storage
+filesystem_folder = ~/.local/share/radicale/collections
+ics_config = ~/.config/radicale/ics_sync.json
+```
+ 
+Then create `~/.config/radicale/ics_sync.json` and start Radicale:
+ 
+```bash
+radicale
+```
+
+## State
+
+The plugin stores its sync state in `ics_sync_hashes.json`, written next to your Radicale data. It tracks the last known content hash per event so unchanged events aren't rewritten. Safe to delete if you want a full re-sync on next startup.
+
+## Behavior
+
+The plugin polls ICS feeds at a regular interval. Events are filtered by include/exclude patterns before being written to Radicale. Events that disappear from the upstream feed or are filtered out are deleted from the Radicale collection. Local edits to upstream events are preserved, until the upstream event itself changes, in which case the upstream version wins. Local events are not touched.
+
+## Limitations & Roadmap
+
+- **Filtering is `SUMMARY`-only** — other fields (`LOCATION`, `DESCRIPTION`) aren't supported yet, but are planned.
+- **Upstream changes fully overwrite local edits** — field-level merge (e.g. keeping your local title while accepting upstream time changes) is planned.
+
+## Contributing
+
+Issues and pull requests are welcome.
+
+## License
+
+MIT

radicale_ics_sync-0.1.0/radicale_ics_sync.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+radicale_ics_sync/__init__.py
+radicale_ics_sync/storage.py
+radicale_ics_sync/upstream.py
+radicale_ics_sync.egg-info/PKG-INFO
+radicale_ics_sync.egg-info/SOURCES.txt
+radicale_ics_sync.egg-info/dependency_links.txt
+radicale_ics_sync.egg-info/requires.txt
+radicale_ics_sync.egg-info/top_level.txt

radicale_ics_sync-0.1.0/radicale_ics_sync.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

radicale_ics_sync-0.1.0/radicale_ics_sync.egg-info/requires.txt

@@ -0,0 +1,2 @@
+radicale>=3.0
+vobject>=0.9.6

radicale_ics_sync-0.1.0/radicale_ics_sync.egg-info/top_level.txt

@@ -0,0 +1 @@
+radicale_ics_sync

radicale_ics_sync-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+