From 1e6577130a2c4c00a3f9034a56f45340f2a803d2 Mon Sep 17 00:00:00 2001
From: Tim <timwhite88@gmail.com>
Date: Sat, 13 Jul 2024 16:08:32 +0800
Subject: [PATCH] Add docs, add logging

---
 docs/custom-filters.md                   | 41 ++++++++++++++++++++++++
 tubesync/sync/filtering.py               |  1 +
 tubesync/sync/overrides/custom_filter.py | 12 +++++++
 3 files changed, 54 insertions(+)
 create mode 100644 docs/custom-filters.md

diff --git a/docs/custom-filters.md b/docs/custom-filters.md
new file mode 100644
index 0000000..458a02a
--- /dev/null
+++ b/docs/custom-filters.md
@@ -0,0 +1,41 @@
+# TubeSync
+
+## Advanced usage guide - Writing Custom Filters
+
+Tubesync provides ways to filter media based on age, title string, and 
+duration. This is sufficient for most use cases, but there more complicated
+use cases that can't easily be anticipated. Custom filters allow you to 
+write some Python code to easily add your own logic into the filtering.
+
+Any call to an external API, or that requires access the metadata of the
+media item, will be much slower than the checks for title/age/duration. So
+this custom filter is only called if the other checks have already passed.
+You should also be aware that external API calls will significantly slow
+down the check process, and for large channels or databases this could be
+an issue.
+
+### How to use
+1. Copy `tubesync/sync/overrides/custom_filter.py` to your local computer
+2. Make your code changes to the `filter_custom` function in that file. Simply return `True` to skip downloading the item, and `False` to allow it to download
+3. Override `tubesync/sync/overrides/custom_filter.py` in your docker container.
+
+#### Docker run
+Include `-v /some/directory/tubesync-overrides:/app/sync/overrides` in your docker run
+command, pointing to the location of your override file.
+
+#### Docker Compose
+Include a volume line pointing to the location of your override file.
+e.g.
+```yaml
+services:
+  tubesync:
+    image: ghcr.io/meeb/tubesync:latest
+    container_name: tubesync
+    restart: unless-stopped
+    ports:
+      - 4848:4848
+    volumes:
+      - /some/directory/tubesync-config:/config
+      - /some/directory/tubesync-downloads:/downloads
+      - /some/directory/tubesync-overrides:/app/sync/overrides
+```
\ No newline at end of file
diff --git a/tubesync/sync/filtering.py b/tubesync/sync/filtering.py
index 730a5d8..82c1792 100644
--- a/tubesync/sync/filtering.py
+++ b/tubesync/sync/filtering.py
@@ -36,6 +36,7 @@ def filter_media(instance: Media):
 
     # If we aren't already skipping the file, call our custom function that can be overridden
     if not skip and filter_custom(instance):
+        log.info(f"Media: {instance.source} / {instance} has been skipped by Custom Filter")
         skip = True
 
     # Check if skipping
diff --git a/tubesync/sync/overrides/custom_filter.py b/tubesync/sync/overrides/custom_filter.py
index c7c2213..68bdd8f 100644
--- a/tubesync/sync/overrides/custom_filter.py
+++ b/tubesync/sync/overrides/custom_filter.py
@@ -20,8 +20,20 @@
 """
 
 from ..models import Media
+from common.logger import log
 
 
 def filter_custom(instance: Media) -> bool:
     # Return True to skip, or False to allow the media item to be downloaded
+
+    # Put your conditional logic here
+    if False:
+        # It's in your best interest to log when skipping, so you can look at the logs and see why your media isn't
+        # downloading
+        log.info(
+            f"Media: {instance.source} / {instance} has met some custom condition. Marking to be skipped"
+        )
+        return True
+
+    # Return False if we aren't skipping the media
     return False