From 51cd319a2488f37a8f95c0c420a2ef189bf06af3 Mon Sep 17 00:00:00 2001 From: Lukas Date: Sun, 23 Nov 2025 19:45:22 +0100 Subject: [PATCH] Task 1.5: Update Provider Factory documentation for key usage - Added comprehensive module-level docstring explaining provider vs series keys - Enhanced Loaders class docstring with purpose and attributes documentation - Added detailed docstring to GetLoader() method with Args/Returns/Raises sections - Added type hints: Dict[str, Loader] for self.dict and -> None for __init__ - Clarified distinction between provider keys (e.g., 'aniworld.to') and series keys - No functional changes - existing implementation already correct - All 34 provider tests pass - All 16 SeriesApp tests pass - Updated instructions.md to mark Task 1.5 as completed - Follows PEP 8 and PEP 257 standards --- instructions.md | 29 ++++++++++++-- src/core/providers/provider_factory.py | 52 ++++++++++++++++++++++++-- 2 files changed, 75 insertions(+), 6 deletions(-) diff --git a/instructions.md b/instructions.md index 0fd9e7e..9c81cb6 100644 --- a/instructions.md +++ b/instructions.md @@ -379,9 +379,9 @@ conda run -n AniWorld python -m pytest tests/unit/ -k "provider" -v **Success Criteria:** -- [ ] Provider factory works with `key` identifiers -- [ ] No breaking changes to provider interface -- [ ] All provider factory tests pass +- [x] Provider factory works with `key` identifiers +- [x] No breaking changes to provider interface +- [x] All provider factory tests pass **Test Command:** @@ -389,6 +389,29 @@ conda run -n AniWorld python -m pytest tests/unit/ -k "provider" -v conda run -n AniWorld python -m pytest tests/unit/ -k "provider_factory" -v ``` +**Status:** ✅ COMPLETED + +**Implementation Details:** + +- Added comprehensive module-level docstring explaining the distinction between provider keys and series keys +- Enhanced `Loaders` class docstring with detailed documentation of its purpose and attributes +- Added comprehensive docstring to `GetLoader()` method explaining: + - Provider key vs series key distinction + - Parameter usage and return value + - Raises clause documenting KeyError exception + - Note clarifying the two-level key usage (provider key in factory, series key in providers) +- Added type hint `Dict[str, Loader]` to `self.dict` attribute for better type safety +- Added return type hint `-> None` to `__init__` method +- Verified provider factory already correctly uses `key` for provider identification +- Verified provider instances (via Loader interface) use `key` for series identification +- No functional changes required - existing implementation was already correct +- Documentation now clearly distinguishes between: + - Provider keys: Site identifiers like "aniworld.to" (used by factory) + - Series keys: Unique anime identifiers like "attack-on-titan" (used by providers) +- All 34 provider-related tests pass successfully +- All 16 SeriesApp tests pass, confirming no breaking changes in Loaders integration +- Code follows PEP 8 and PEP 257 standards + --- ### Phase 2: Core Application Layer diff --git a/src/core/providers/provider_factory.py b/src/core/providers/provider_factory.py index 89d4a4e..2c4dfa2 100644 --- a/src/core/providers/provider_factory.py +++ b/src/core/providers/provider_factory.py @@ -1,10 +1,56 @@ +"""Provider factory for managing anime content providers. + +This module provides a factory class for accessing different anime content +providers (loaders). The factory uses provider identifiers (keys) to return +the appropriate provider instance. + +Note: The 'key' parameter in this factory refers to the provider identifier +(e.g., 'aniworld.to'), not to be confused with series keys used within +providers to identify specific anime series. +""" + +from typing import Dict + from .aniworld_provider import AniworldLoader from .base_provider import Loader -class Loaders: - def __init__(self): - self.dict = {"aniworld.to": AniworldLoader()} +class Loaders: + """Factory class for managing and retrieving anime content providers. + + This factory maintains a registry of available providers and provides + access to them via provider keys. Each provider implements the Loader + interface for searching and downloading anime content. + + Attributes: + dict: Dictionary mapping provider keys to provider instances. + Provider keys are site identifiers (e.g., 'aniworld.to'). + """ + + def __init__(self) -> None: + """Initialize the provider factory with available providers. + + Currently supports: + - 'aniworld.to': AniworldLoader for aniworld.to content + """ + self.dict: Dict[str, Loader] = {"aniworld.to": AniworldLoader()} def GetLoader(self, key: str) -> Loader: + """Retrieve a provider instance by its provider key. + + Args: + key: Provider identifier (e.g., 'aniworld.to'). + This is the site/provider key, not a series key. + + Returns: + Loader instance for the specified provider. + + Raises: + KeyError: If the provider key is not found in the registry. + + Note: + The 'key' parameter here identifies the provider/site, while + series-specific operations on the returned Loader use series + keys to identify individual anime series. + """ return self.dict[key]