Phase 8: Documentation and deprecation warnings for identifier standardization

- Enhanced infrastructure.md with identifier convention table, format requirements, migration notes
- Updated docs/README.md with series identifier convention section
- Updated docs/api_reference.md with key-based API examples and notes
- Added deprecation warnings to SerieList.get_by_folder()
- Added deprecation warnings to anime.py folder fallback lookup
- Added deprecation warnings to validate_series_key_or_folder()
- All warnings include v3.0.0 removal timeline
- All 1006 tests pass

src/core/entities/SerieList.py

@@ -2,6 +2,7 @@
 
 import logging
 import os
+import warnings
 from json import JSONDecodeError
 from typing import Dict, Iterable, List, Optional
 
@@ -144,6 +145,11 @@ class SerieList:
         """
         Get a series by its folder name.
         
+        .. deprecated:: 2.0.0
+            Use :meth:`get_by_key` instead. Folder-based lookups will be
+            removed in version 3.0.0. The `folder` field is metadata only
+            and should not be used for identification.
+        
         This method is provided for backward compatibility only.
         Prefer using get_by_key() for new code.
         
@@ -153,6 +159,12 @@ class SerieList:
         Returns:
             The Serie instance if found, None otherwise
         """
+        warnings.warn(
+            "get_by_folder() is deprecated and will be removed in v3.0.0. "
+            "Use get_by_key() instead. The 'folder' field is metadata only.",
+            DeprecationWarning,
+            stacklevel=2
+        )
         for serie in self.keyDict.values():
             if serie.folder == folder:
                 return serie

src/server/api/anime.py

@@ -1,3 +1,5 @@
+import logging
+import warnings
 from typing import Any, List, Optional
 
 from fastapi import APIRouter, Depends, HTTPException, status
@@ -11,6 +13,8 @@ from src.server.utils.dependencies import (
     require_auth,
 )
 
+logger = logging.getLogger(__name__)
+
 router = APIRouter(prefix="/api/anime", tags=["anime"])
 
 
@@ -715,6 +719,21 @@ async def get_anime(
             for serie in series:
                 if getattr(serie, "folder", None) == anime_id:
                     found = serie
+                    # Log deprecation warning for folder-based lookup
+                    key = getattr(serie, "key", "unknown")
+                    logger.warning(
+                        "Folder-based lookup for '%s' is deprecated. "
+                        "Use series key '%s' instead. Folder-based lookups "
+                        "will be removed in v3.0.0.",
+                        anime_id,
+                        key
+                    )
+                    warnings.warn(
+                        f"Folder-based lookup for '{anime_id}' is deprecated. "
+                        f"Use series key '{key}' instead.",
+                        DeprecationWarning,
+                        stacklevel=2
+                    )
                     break
 
         if not found:

src/server/utils/validators.py

@@ -6,6 +6,7 @@ utilities for ensuring data integrity across the application.
 """
 
 import re
+import warnings
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
@@ -496,6 +497,10 @@ def validate_series_key_or_folder(
     """
     Validate an identifier that could be either a series key or folder.
 
+    .. deprecated:: 2.0.0
+        Folder-based identification is deprecated. Use series `key` only.
+        This function will require key format only in v3.0.0.
+
     This function provides backward compatibility during the transition
     from folder-based to key-based identification.
 
@@ -532,6 +537,15 @@ def validate_series_key_or_folder(
             "Keys must be lowercase with hyphens (e.g., 'attack-on-titan')."
         )
 
+    # Emit deprecation warning for folder-based identification
+    warnings.warn(
+        f"Folder-based identification for '{identifier}' is deprecated. "
+        "Use series key (lowercase with hyphens) instead. "
+        "Folder-based identification will be removed in v3.0.0.",
+        DeprecationWarning,
+        stacklevel=2
+    )
+
     # Validate as folder (more permissive)
     if len(identifier) > 1000:
         raise ValueError("Identifier too long (max 1000 characters)")