Add configurable minimum photo threshold

Author: wolfgangbures

README.md

@@ -14,6 +14,7 @@ This code was generatde by GPT5.1-Codex.
 ✅ **Microsoft Graph API** - Secure authentication using Azure AD  
 ✅ **Real-time Updates** - Background refresh with coordinator pattern  
 ✅ **Recent Folder History** - Configurable limit keeps the last N folders out of rotation  
+✅ **Folder Quality Filter** - Enforce a minimum number of photos before a folder enters the rotation  
 ✅ **Rich Sensors** - Multiple sensors with photo URLs as attributes  
 ✅ **Services** - Manual refresh and folder selection services  
 ✅ **Configuration UI** - Easy setup through Home Assistant UI  
@@ -76,6 +77,7 @@ Restart Home Assistant to load the new integration.
    - **Library Name**: Document library name (default: `Documents`)
    - **Base Folder Path**: Path to photo folders (e.g., `/Photos`)
   - **Recent Folder History Size**: Number of previously selected folders to avoid when refreshing (default: `30`, set to `0` to disable)
+    - **Minimum Photos Per Folder**: Only include folders that contain at least this many photos (default: `5`)
 
 ## How It Works
 

custom_components/sharepoint_photos/__init__.py

@@ -17,9 +17,11 @@
 from .const import (
     CONF_BASE_FOLDER_PATH,
     CONF_FOLDER_HISTORY_SIZE,
+    CONF_MIN_PHOTO_COUNT,
     CONF_LIBRARY_NAME,
     DEFAULT_BASE_FOLDER_PATH,
     DEFAULT_FOLDER_HISTORY_SIZE,
+    DEFAULT_MIN_PHOTO_COUNT,
     DEFAULT_LIBRARY_NAME,
     DOMAIN,
 )
@@ -170,6 +172,10 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         CONF_FOLDER_HISTORY_SIZE,
         entry.data.get(CONF_FOLDER_HISTORY_SIZE, DEFAULT_FOLDER_HISTORY_SIZE),
     )
+    min_photos_per_folder = entry.options.get(
+        CONF_MIN_PHOTO_COUNT,
+        entry.data.get(CONF_MIN_PHOTO_COUNT, DEFAULT_MIN_PHOTO_COUNT),
+    )
 
     client = SharePointPhotosApiClient(
         hass=hass,
@@ -180,6 +186,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         library_name=library_name,
         base_folder_path=base_folder_path,
         recent_history_size=recent_history_size,
+        min_photos_per_folder=min_photos_per_folder,
     )
 
     coordinator = SharePointPhotosDataUpdateCoordinator(hass, client=client, entry_id=entry.entry_id)

custom_components/sharepoint_photos/api.py

@@ -18,6 +18,7 @@
     CONF_CLIENT_SECRET,
     CONF_TENANT_ID,
     DEFAULT_FOLDER_HISTORY_SIZE,
+    DEFAULT_MIN_PHOTO_COUNT,
     GRAPH_API_BASE,
     IMAGE_EXTENSIONS,
     SCOPE,
@@ -39,6 +40,7 @@ def __init__(
         library_name: str = "Documents",
         base_folder_path: str = "/Photos",
         recent_history_size: int = DEFAULT_FOLDER_HISTORY_SIZE,
+        min_photos_per_folder: int = DEFAULT_MIN_PHOTO_COUNT,
     ) -> None:
         """Initialize the SharePoint client."""
         self.hass = hass
@@ -49,6 +51,7 @@ def __init__(
         self.library_name = library_name
         self.base_folder_path = base_folder_path
         self._recent_history_size = max(0, recent_history_size or 0)
+        self._min_photos_per_folder = max(1, min_photos_per_folder or DEFAULT_MIN_PHOTO_COUNT)
         self._recent_folder_paths = (
             deque(maxlen=self._recent_history_size) if self._recent_history_size > 0 else None
         )
@@ -401,8 +404,8 @@ async def _scan_folders_recursive(self, drive_id: str, folder_path: str, folders
 
             status, data = await self._make_authenticated_request(url)
             if status == 200:
-                # Check if current folder has photos
-                has_photos = False
+                # Count how many photos exist in this folder
+                photo_count = 0
                 subfolders = []
 
                 items = data.get("value", [])
@@ -416,16 +419,28 @@ async def _scan_folders_recursive(self, drive_id: str, folder_path: str, folders
                         # It's a file, check if it's an image
                         file_name = item.get("name", "").lower()
                         if any(file_name.endswith(ext) for ext in IMAGE_EXTENSIONS):
-                            has_photos = True
+                            photo_count += 1
 
-                # If current folder has photos, add it to the list
-                if has_photos:
+                # If current folder meets the minimum threshold, add it to the list
+                if photo_count >= self._min_photos_per_folder:
                     folders.append({
                         "name": self._build_display_folder_name(folder_path),
                         "path": folder_path,
                         "full_path": folder_path,
+                        "photo_count": photo_count,
                     })
-                    _LOGGER.debug("Added photo folder: %s", folder_path)
+                    _LOGGER.debug(
+                        "Added photo folder: %s (%d photos)",
+                        folder_path,
+                        photo_count,
+                    )
+                else:
+                    _LOGGER.debug(
+                        "Skipping folder %s: only %d photos (minimum %d)",
+                        folder_path,
+                        photo_count,
+                        self._min_photos_per_folder,
+                    )
 
                 # Recursively scan subfolders
                 _LOGGER.debug("Scanning %d subfolders in %s", len(subfolders), folder_path)
@@ -517,12 +532,23 @@ async def get_random_photo_folder(self) -> Optional[Dict[str, Any]]:
         """Get a random photo folder with its images - this always selects a NEW folder."""
         folders = await self.get_photo_folders()
         if not folders:
+            _LOGGER.warning(
+                "No folders meet the minimum photo requirement (%d)",
+                self._min_photos_per_folder,
+            )
             return None
 
         # Select a random folder while avoiding recently used ones when possible
         candidate_folders = self._filter_recent_folders(folders)
+        if not candidate_folders:
+            _LOGGER.warning("No folders available after recent-history filtering")
+            return None
         selected_folder = random.choice(candidate_folders)
-        _LOGGER.info("Selected random folder: %s", selected_folder["path"])
+        _LOGGER.info(
+            "Selected random folder: %s (%d photos)",
+            selected_folder["path"],
+            selected_folder.get("photo_count", -1),
+        )
 
         # Get photos from the selected folder
         photos = await self.get_folder_photos(selected_folder["path"])

custom_components/sharepoint_photos/config_flow.py

@@ -15,11 +15,13 @@
     CONF_CLIENT_ID,
     CONF_CLIENT_SECRET,
     CONF_FOLDER_HISTORY_SIZE,
+    CONF_MIN_PHOTO_COUNT,
     CONF_LIBRARY_NAME,
     CONF_SITE_URL,
     CONF_TENANT_ID,
     DEFAULT_BASE_FOLDER_PATH,
     DEFAULT_FOLDER_HISTORY_SIZE,
+    DEFAULT_MIN_PHOTO_COUNT,
     DEFAULT_LIBRARY_NAME,
     DOMAIN,
     ERROR_AUTH_FAILED,
@@ -58,6 +60,7 @@ async def async_step_user(
                 library_name=user_input.get(CONF_LIBRARY_NAME, DEFAULT_LIBRARY_NAME),
                 base_folder_path=user_input.get(CONF_BASE_FOLDER_PATH, DEFAULT_BASE_FOLDER_PATH),
                 recent_history_size=user_input.get(CONF_FOLDER_HISTORY_SIZE, DEFAULT_FOLDER_HISTORY_SIZE),
+                min_photos_per_folder=user_input.get(CONF_MIN_PHOTO_COUNT, DEFAULT_MIN_PHOTO_COUNT),
             )
 
             try:
@@ -94,6 +97,10 @@ async def async_step_user(
                     CONF_FOLDER_HISTORY_SIZE,
                     default=DEFAULT_FOLDER_HISTORY_SIZE
                 ): vol.All(vol.Coerce(int), vol.Range(min=0, max=200)),
+                vol.Optional(
+                    CONF_MIN_PHOTO_COUNT,
+                    default=DEFAULT_MIN_PHOTO_COUNT
+                ): vol.All(vol.Coerce(int), vol.Range(min=1, max=500)),
             }),
             errors=errors,
         )
@@ -145,5 +152,12 @@ async def async_step_init(
                         self.config_entry.data.get(CONF_FOLDER_HISTORY_SIZE, DEFAULT_FOLDER_HISTORY_SIZE)
                     ),
                 ): vol.All(vol.Coerce(int), vol.Range(min=0, max=200)),
+                vol.Optional(
+                    CONF_MIN_PHOTO_COUNT,
+                    default=self.config_entry.options.get(
+                        CONF_MIN_PHOTO_COUNT,
+                        self.config_entry.data.get(CONF_MIN_PHOTO_COUNT, DEFAULT_MIN_PHOTO_COUNT)
+                    ),
+                ): vol.All(vol.Coerce(int), vol.Range(min=1, max=500)),
             }),
         )

custom_components/sharepoint_photos/const.py

@@ -12,12 +12,14 @@
 CONF_BASE_FOLDER_PATH = "base_folder_path"
 CONF_REFRESH_INTERVAL = "refresh_interval"
 CONF_FOLDER_HISTORY_SIZE = "folder_history_size"
+CONF_MIN_PHOTO_COUNT = "min_photo_count"
 
 # Default values
 DEFAULT_LIBRARY_NAME = "Freigegebene Dokumente"  # German SharePoint default
 DEFAULT_BASE_FOLDER_PATH = "/General/Fotos"
 DEFAULT_REFRESH_INTERVAL = 6  # hours
 DEFAULT_FOLDER_HISTORY_SIZE = 30
+DEFAULT_MIN_PHOTO_COUNT = 5
 
 # Microsoft Graph API
 GRAPH_API_BASE = "https://graph.microsoft.com/v1.0"

custom_components/sharepoint_photos/strings.json

@@ -11,7 +11,8 @@
           "site_url": "SharePoint Site URL",
           "library_name": "Document Library Name",
           "base_folder_path": "Base Folder Path",
-          "folder_history_size": "Recent Folder History Size"
+          "folder_history_size": "Recent Folder History Size",
+          "min_photo_count": "Minimum Photos Per Folder"
         },
         "data_description": {
           "tenant_id": "Your Azure Active Directory tenant ID (GUID)",
@@ -20,7 +21,8 @@
           "site_url": "Full URL to your SharePoint site (e.g., https://yourdomain.sharepoint.com/sites/photos)",
           "library_name": "Name of the document library containing your photos. Common values: 'Documents' (English), 'Freigegebene Dokumente' (German), 'Shared Documents'",
           "base_folder_path": "Path to the folder containing your photo folders (e.g., /Photos, /General/Fotos)",
-          "folder_history_size": "Number of recently used folders to exclude when picking a new random folder (set to 0 to disable)"
+          "folder_history_size": "Number of recently used folders to exclude when picking a new random folder (set to 0 to disable)",
+          "min_photo_count": "Only include folders that contain at least this many photos (default 5)"
         }
       }
     },
@@ -45,7 +47,8 @@
         "data": {
           "library_name": "Document Library Name",
           "base_folder_path": "Base Folder Path",
-          "folder_history_size": "Recent Folder History Size"
+          "folder_history_size": "Recent Folder History Size",
+          "min_photo_count": "Minimum Photos Per Folder"
         }
       }
     }

custom_components/sharepoint_photos/translations/en.json

@@ -11,7 +11,8 @@
           "site_url": "SharePoint Site URL",
           "library_name": "Document Library Name",
           "base_folder_path": "Base Folder Path",
-          "folder_history_size": "Recent Folder History Size"
+          "folder_history_size": "Recent Folder History Size",
+          "min_photo_count": "Minimum Photos Per Folder"
         },
         "data_description": {
           "tenant_id": "Your Azure Active Directory tenant ID (GUID)",
@@ -20,7 +21,8 @@
           "site_url": "Full URL to your SharePoint site (e.g., https://yourdomain.sharepoint.com/sites/photos)",
           "library_name": "Name of the document library containing your photos. Common values: 'Documents' (English), 'Freigegebene Dokumente' (German), 'Shared Documents'",
           "base_folder_path": "Path to the folder containing your photo folders (e.g., /Photos, /General/Fotos)",
-          "folder_history_size": "Number of recently used folders to exclude when picking a new random folder (set to 0 to disable)"
+          "folder_history_size": "Number of recently used folders to exclude when picking a new random folder (set to 0 to disable)",
+          "min_photo_count": "Only include folders that contain at least this many photos (default 5)"
         }
       }
     },
@@ -45,7 +47,8 @@
         "data": {
           "library_name": "Document Library Name",
           "base_folder_path": "Base Folder Path",
-          "folder_history_size": "Recent Folder History Size"
+          "folder_history_size": "Recent Folder History Size",
+          "min_photo_count": "Minimum Photos Per Folder"
         }
       }
     }