Keep unrelated Plex changes out of #949 fix

Author: dannyvfilms

docs/agents/plex_integration.md

@@ -11,8 +11,9 @@ The system prioritizes **TMDB IDs** as the canonical source of truth. All Plex e
 1.  **Explicit TMDB ID**: Extracted directly from Plex GUIDs (e.g., `tmdb://123`).
 2.  **IMDB/TVDB Lookup**: If only IMDB (`tt123`) or TVDB (`789`) IDs are present, the system queries the TMDB `find` API to resolve the corresponding `tmdb_id`.
 3.  **Title Search Fallback**:
-    -   If no external IDs are found (or they return 404s), the system performs a search against TMDB using the media title.
-    -   **TV Shows**: Uses `grandparentTitle` (series title) or `title`. Match attempts to filter by year if available.
+    -   For TV history entries, Plex item metadata and then show metadata from `grandparentRatingKey`/`grandparentKey` are checked before title search.
+    -   If no deterministic IDs are found (or they return 404s), the system performs a search against TMDB using the media title.
+    -   **TV Shows**: Uses `grandparentTitle` (series title) or `title` only after the Plex show-level lookup. Match attempts to filter by year if available.
     -   **Movies**: Uses `title` and `year`.
 
 **GUID extraction & conflicts:**
@@ -42,7 +43,7 @@ Plex history import uses Plex's history endpoint as the canonical event stream.
 -   Sorted newest-first (`sort=viewedAt:desc`) and paged with `X-Plex-Container-Start`/`X-Plex-Container-Size`. `PLEX_HISTORY_PAGE_SIZE` controls page size; `PLEX_HISTORY_MAX_ITEMS` (0 = no cap) limits how far back we fetch. There is no time windowing, so re-importing overlapping ranges is expected.
 
 **Fields we rely on:**
--   IDs: `Guid`/`guid` entries with TMDB/IMDB/TVDB identifiers are required for deterministic resolution. Order is: resolve IDs from the history row (including title search when allowed); if missing, fetch `GET {server_uri}/library/metadata/{ratingKey}` to pull GUIDs (no title search in this step); if still missing, the movie/TV recorders may still fall back to title search when a title is available, otherwise the entry is skipped.
+-   IDs: `Guid`/`guid` entries with TMDB/IMDB/TVDB identifiers are required for deterministic resolution. For TV history, resolve IDs from the history row, fetch `GET {server_uri}/library/metadata/{ratingKey}` when needed, then inspect the Plex show at `grandparentRatingKey`/`grandparentKey` before allowing title search. Movies retain their existing title fallback when a title is available; otherwise the entry is skipped.
 -   Titles: `title` or `grandparentTitle` is required for title-search fallback; Plex-only GUIDs without a title are skipped.
 -   Timing: `viewedAt` or `lastViewedAt` (epoch seconds) is the authoritative `watched_at`. If missing, we fall back to import time; `viewCount`/`viewOffset` are ignored. Rows missing `viewedAt`/`lastViewedAt` are nondeterministic and can dedupe poorly across runs.
 -   TV structure: `parentIndex` (season) and `index` (episode) must be numeric. Missing numbers can cause the entry to be skipped or treated as a movie in show libraries.

src/integrations/imports/plex.py

@@ -130,7 +130,6 @@ def __init__(self, user, account, mode, library, fast_mode=True):
 
     def import_data(self):
         """Import history for the selected library."""
-        self._ensure_username_matches()
         self._ensure_account_id()
         self._init_allowed_usernames()
         self._init_allowed_account_ids()
@@ -232,23 +231,6 @@ def import_data(self):
         deduped_warnings = "\n".join(dict.fromkeys(self.warnings))
         return result_counts, deduped_warnings
 
-    def _ensure_username_matches(self):
-        """Persist the Plex username into the user's webhook allow list."""
-        username = (self.account.plex_username or "").strip()
-        if not username:
-            return
-
-        existing = [
-            u.strip() for u in (self.user.plex_usernames or "").split(",") if u.strip()
-        ]
-
-        if username.lower() in [u.lower() for u in existing]:
-            return
-
-        updated = [*existing, username]
-        self.user.plex_usernames = ", ".join(updated)
-        self.user.save(update_fields=["plex_usernames"])
-
     def _ensure_account_id(self):
         """Fetch and persist the Plex account id if missing."""
         if self._account_id:

src/integrations/tests/test_plex_import_logic.py

@@ -1456,6 +1456,99 @@ def test_import_that_creates_nothing_does_not_reload_the_calendar(
         mock_schedule_stats.assert_called_once_with(self.user.id)
 
 
+class TestPlexUsernameImportBehavior(TestCase):
+    """Plex imports must not rewrite the user's configured username filters."""
+
+    def setUp(self):
+        User = get_user_model()
+        self.user = User.objects.create_user(username="plex-import-user")
+        self.account = PlexAccount.objects.create(
+            user=self.user,
+            plex_token="token",
+            plex_username="server-user",
+            plex_account_id="9999",
+        )
+        self.user.plex_usernames = "user1, user2"
+        self.user.save(update_fields=["plex_usernames"])
+
+    def test_successful_import_preserves_explicit_username_list(self):
+        """A completed import must not add the connected server account."""
+        with (
+            patch("integrations.imports.plex.plex_api.list_users", return_value=[]),
+            patch(
+                "integrations.imports.plex.plex_api.list_sections",
+                return_value=[
+                    {
+                        "id": "1",
+                        "machine_identifier": "machine",
+                        "title": "Movies",
+                        "type": "movie",
+                        "uri": "http://plex",
+                    }
+                ],
+            ),
+            patch(
+                "integrations.imports.plex.plex_api.list_resources",
+                return_value=[
+                    {
+                        "machine_identifier": "machine",
+                        "connections": [{"uri": "http://plex"}],
+                    }
+                ],
+            ),
+            patch(
+                "integrations.imports.plex.plex_api.fetch_history",
+                return_value=([], 0),
+            ),
+            patch(
+                "integrations.imports.plex.plex_api.fetch_section_all_items",
+                return_value=([], 0),
+            ),
+        ):
+            plex.importer("all", self.user, "new")
+
+        self.user.refresh_from_db()
+        self.assertEqual(self.user.plex_usernames, "user1, user2")
+
+    def test_failed_import_preserves_explicit_username_list(self):
+        """An early Plex failure must not add the connected server account."""
+        from integrations.plex import PlexAuthError
+
+        with (
+            patch("integrations.imports.plex.plex_api.list_users", return_value=[]),
+            patch(
+                "integrations.imports.plex.plex_api.list_resources",
+                side_effect=PlexAuthError("token expired"),
+            ),
+        ):
+            with self.assertRaises(helpers.MediaImportError):
+                plex.importer("all", self.user, "new")
+
+        self.user.refresh_from_db()
+        self.assertEqual(self.user.plex_usernames, "user1, user2")
+
+    def test_empty_username_list_uses_connected_account_without_persisting(self):
+        """An empty list still filters to the connected account without saving it."""
+        self.user.plex_usernames = ""
+        self.user.save(update_fields=["plex_usernames"])
+        importer = PlexHistoryImporter(
+            user=self.user,
+            account=self.account,
+            mode="new",
+            library="all",
+        )
+
+        with patch("integrations.imports.plex.plex_api.list_users", return_value=[]):
+            importer._init_allowed_usernames()
+            importer._init_allowed_account_ids()
+
+        self.assertEqual(importer._allowed_usernames, ["server-user"])
+        self.assertEqual(importer._allowed_account_ids, {"9999"})
+        self.assertTrue(importer._is_allowed_history_user({"accountID": "9999"}))
+        self.user.refresh_from_db()
+        self.assertEqual(self.user.plex_usernames, "")
+
+
 class TestPlexMultiServerImport(TestCase):
     """Tests for multi-server / shared-library import resilience."""