blizzardapi3 3.0.0__py3-none-any.whl

blizzardapi3/__init__.py

@@ -0,0 +1,13 @@
+"""BlizzardAPI v3 - Modern Python wrapper for the Blizzard API."""
+
+__version__ = "3.0.0"
+
+from .blizzard_api import BlizzardAPI
+from .types import Locale, Region
+
+__all__ = [
+    "__version__",
+    "BlizzardAPI",
+    "Region",
+    "Locale",
+]

blizzardapi3/api/__init__.py

@@ -0,0 +1,5 @@
+"""Game-specific API facades."""
+
+from .wow import WowAPI
+
+__all__ = ["WowAPI"]

blizzardapi3/api/wow.py

@@ -0,0 +1,76 @@
+"""World of Warcraft API facade."""
+
+from ..core import BaseClient, EndpointRegistry, MethodFactory, RequestExecutor
+
+
+class WowGameDataAPI:
+    """WoW Game Data API with dynamically generated methods."""
+
+    def __init__(self, client: BaseClient, executor: RequestExecutor, registry: EndpointRegistry):
+        """Initialize WoW Game Data API.
+
+        Args:
+            client: Base client for session management
+            executor: Request executor
+            registry: Endpoint registry
+        """
+        self.client = client
+        self.executor = executor
+        self.registry = registry
+
+        # Generate and attach all methods
+        factory = MethodFactory(executor, registry)
+        methods = factory.generate_all_methods("wow", "game_data")
+
+        for method_name, (sync_method, async_method) in methods.items():
+            # Bind methods to this instance
+            setattr(self, method_name, sync_method.__get__(self, type(self)))
+            setattr(self, f"{method_name}_async", async_method.__get__(self, type(self)))
+
+
+class WowProfileAPI:
+    """WoW Profile API with dynamically generated methods."""
+
+    def __init__(self, client: BaseClient, executor: RequestExecutor, registry: EndpointRegistry):
+        """Initialize WoW Profile API.
+
+        Args:
+            client: Base client for session management
+            executor: Request executor
+            registry: Endpoint registry
+        """
+        self.client = client
+        self.executor = executor
+        self.registry = registry
+
+        # Generate and attach all methods
+        factory = MethodFactory(executor, registry)
+        methods = factory.generate_all_methods("wow", "profile")
+
+        for method_name, (sync_method, async_method) in methods.items():
+            # Bind methods to this instance
+            setattr(self, method_name, sync_method.__get__(self, type(self)))
+            setattr(self, f"{method_name}_async", async_method.__get__(self, type(self)))
+
+
+class WowAPI:
+    """World of Warcraft API facade.
+
+    Provides access to:
+    - game_data: WoW Game Data API (achievements, items, etc.)
+    - profile: WoW Profile API (characters, guilds, etc.)
+    """
+
+    def __init__(self, client: BaseClient, registry: EndpointRegistry):
+        """Initialize WoW API.
+
+        Args:
+            client: Base client for session management
+            registry: Endpoint registry
+        """
+        self.client = client
+        executor = RequestExecutor(client.token_manager)
+
+        # Initialize sub-APIs
+        self.game_data = WowGameDataAPI(client, executor, registry)
+        self.profile = WowProfileAPI(client, executor, registry)

blizzardapi3/blizzard_api.py

@@ -0,0 +1,53 @@
+"""Main BlizzardAPI client."""
+
+from .api import WowAPI
+from .core import BaseClient, EndpointRegistry
+from .types import Locale, Region
+
+
+class BlizzardAPI(BaseClient):
+    """Main Blizzard API client.
+
+    Provides access to all Blizzard game APIs with proper session management,
+    authentication, and error handling.
+
+    Example:
+        Synchronous usage:
+            with BlizzardAPI(client_id, client_secret) as api:
+                data = api.wow.game_data.get_achievement(
+                    region="us",
+                    locale="en_US",
+                    achievement_id=6
+                )
+
+        Asynchronous usage:
+            async with BlizzardAPI(client_id, client_secret) as api:
+                data = await api.wow.game_data.get_achievement_async(
+                    region="us",
+                    locale="en_US",
+                    achievement_id=6
+                )
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        region: Region | str = Region.US,
+        locale: Locale | str | None = None,
+    ):
+        """Initialize Blizzard API client.
+
+        Args:
+            client_id: Blizzard API client ID
+            client_secret: Blizzard API client secret
+            region: Default region (defaults to US)
+            locale: Default locale (defaults to region's default)
+        """
+        super().__init__(client_id, client_secret, region, locale)
+
+        # Initialize endpoint registry
+        self.registry = EndpointRegistry()
+
+        # Initialize game APIs
+        self.wow = WowAPI(self, self.registry)

blizzardapi3/core/__init__.py

@@ -0,0 +1,17 @@
+"""Core framework components."""
+
+from .auth import TokenManager
+from .client import BaseClient
+from .context import RequestContext
+from .executor import RequestExecutor
+from .factory import MethodFactory
+from .registry import EndpointRegistry
+
+__all__ = [
+    "BaseClient",
+    "TokenManager",
+    "RequestContext",
+    "RequestExecutor",
+    "MethodFactory",
+    "EndpointRegistry",
+]

blizzardapi3/core/auth.py

@@ -0,0 +1,177 @@
+"""OAuth token management."""
+
+import time
+
+import aiohttp
+import requests
+
+from ..exceptions import TokenError
+
+
+class TokenManager:
+    """Manages OAuth token lifecycle with automatic refresh.
+
+    Attributes:
+        TOKEN_BUFFER_SECONDS: Refresh tokens 5 minutes before expiry
+    """
+
+    TOKEN_BUFFER_SECONDS = 300  # 5 minutes
+
+    def __init__(self, client_id: str, client_secret: str):
+        """Initialize token manager.
+
+        Args:
+            client_id: Blizzard API client ID
+            client_secret: Blizzard API client secret
+        """
+        self.client_id = client_id
+        self.client_secret = client_secret
+
+        self._token: str | None = None
+        self._token_type: str | None = None
+        self._expires_at: float | None = None
+
+    def is_token_valid(self) -> bool:
+        """Check if current token is valid.
+
+        Returns:
+            True if token exists and hasn't expired (with buffer)
+        """
+        if not self._token or not self._expires_at:
+            return False
+        return time.time() < (self._expires_at - self.TOKEN_BUFFER_SECONDS)
+
+    def get_token(self, region: str, session: requests.Session) -> str:
+        """Get valid access token (synchronous).
+
+        Args:
+            region: API region for OAuth endpoint
+            session: requests Session to use
+
+        Returns:
+            Valid access token
+
+        Raises:
+            TokenError: If token fetch fails
+        """
+        if self.is_token_valid():
+            return self._token
+
+        return self._fetch_token(region, session)
+
+    async def get_token_async(self, region: str, session: aiohttp.ClientSession) -> str:
+        """Get valid access token (asynchronous).
+
+        Args:
+            region: API region for OAuth endpoint
+            session: aiohttp ClientSession to use
+
+        Returns:
+            Valid access token
+
+        Raises:
+            TokenError: If token fetch fails
+        """
+        if self.is_token_valid():
+            return self._token
+
+        return await self._fetch_token_async(region, session)
+
+    def _fetch_token(self, region: str, session: requests.Session) -> str:
+        """Fetch new access token (synchronous).
+
+        Args:
+            region: API region for OAuth endpoint
+            session: requests Session to use
+
+        Returns:
+            New access token
+
+        Raises:
+            TokenError: If token request fails
+        """
+        url = self._get_oauth_url(region)
+
+        try:
+            response = session.post(
+                url, auth=(self.client_id, self.client_secret), data={"grant_type": "client_credentials"}, timeout=10
+            )
+
+            if response.status_code != 200:
+                raise TokenError(
+                    f"Failed to obtain token: {response.status_code}",
+                    status_code=response.status_code,
+                    request_url=url,
+                    response_data=response.json() if response.text else None,
+                )
+
+            data = response.json()
+            self._token = data["access_token"]
+            self._token_type = data["token_type"]
+            self._expires_at = time.time() + data["expires_in"]
+
+            return self._token
+
+        except requests.RequestException as e:
+            raise TokenError(f"Token request failed: {str(e)}", request_url=url)
+
+    async def _fetch_token_async(self, region: str, session: aiohttp.ClientSession) -> str:
+        """Fetch new access token (asynchronous).
+
+        Args:
+            region: API region for OAuth endpoint
+            session: aiohttp ClientSession to use
+
+        Returns:
+            New access token
+
+        Raises:
+            TokenError: If token request fails
+        """
+        url = self._get_oauth_url(region)
+
+        try:
+            async with session.post(
+                url,
+                auth=aiohttp.BasicAuth(self.client_id, self.client_secret),
+                data={"grant_type": "client_credentials"},
+                timeout=aiohttp.ClientTimeout(total=10),
+            ) as response:
+
+                if response.status != 200:
+                    response_data = await response.json() if response.content_type == "application/json" else None
+                    raise TokenError(
+                        f"Failed to obtain token: {response.status}",
+                        status_code=response.status,
+                        request_url=url,
+                        response_data=response_data,
+                    )
+
+                data = await response.json()
+                self._token = data["access_token"]
+                self._token_type = data["token_type"]
+                self._expires_at = time.time() + data["expires_in"]
+
+                return self._token
+
+        except aiohttp.ClientError as e:
+            raise TokenError(f"Token request failed: {str(e)}", request_url=url)
+
+    def invalidate(self) -> None:
+        """Invalidate current token, forcing a refresh on next request."""
+        self._token = None
+        self._expires_at = None
+
+    @staticmethod
+    def _get_oauth_url(region: str) -> str:
+        """Get OAuth URL for region.
+
+        Args:
+            region: API region
+
+        Returns:
+            OAuth token endpoint URL
+        """
+        if region == "cn":
+            return "https://oauth.battlenet.com.cn/token"
+        return f"https://{region}.battle.net/oauth/token"

blizzardapi3/core/client.py

@@ -0,0 +1,144 @@
+"""Base API client with session management."""
+
+import aiohttp
+import requests
+
+from ..types import Locale, Region, get_default_locale
+from .auth import TokenManager
+
+
+class BaseClient:
+    """Base API client with proper session management.
+
+    Manages HTTP sessions for both sync and async requests,
+    with automatic cleanup via context managers.
+
+    Example:
+        Synchronous usage:
+            with BaseClient(client_id, client_secret) as client:
+                # Use client
+                pass
+
+        Asynchronous usage:
+            async with BaseClient(client_id, client_secret) as client:
+                # Use client
+                pass
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        region: Region | str = Region.US,
+        locale: Locale | str | None = None,
+    ):
+        """Initialize API client.
+
+        Args:
+            client_id: Blizzard API client ID
+            client_secret: Blizzard API client secret
+            region: Default region (defaults to US)
+            locale: Default locale (defaults to region's default locale)
+        """
+        self.client_id = client_id
+        self.client_secret = client_secret
+
+        # Convert region to enum if string
+        if isinstance(region, str):
+            self.default_region = Region(region)
+        else:
+            self.default_region = region
+
+        # Set default locale
+        if locale is None:
+            self.default_locale = get_default_locale(self.default_region)
+        elif isinstance(locale, str):
+            self.default_locale = Locale(locale)
+        else:
+            self.default_locale = locale
+
+        # Session management
+        self._sync_session: requests.Session | None = None
+        self._async_session: aiohttp.ClientSession | None = None
+
+        # Token manager (shared between sync and async)
+        self.token_manager = TokenManager(client_id, client_secret)
+
+    @property
+    def sync_session(self) -> requests.Session:
+        """Get or create synchronous session.
+
+        Returns:
+            Active requests.Session instance
+        """
+        if self._sync_session is None:
+            self._sync_session = requests.Session()
+        return self._sync_session
+
+    @property
+    def async_session(self) -> aiohttp.ClientSession:
+        """Get or create asynchronous session.
+
+        Returns:
+            Active aiohttp.ClientSession instance
+        """
+        if self._async_session is None or self._async_session.closed:
+            self._async_session = aiohttp.ClientSession()
+        return self._async_session
+
+    def close(self) -> None:
+        """Close synchronous session."""
+        if self._sync_session is not None:
+            self._sync_session.close()
+            self._sync_session = None
+
+    async def aclose(self) -> None:
+        """Close asynchronous session."""
+        if self._async_session is not None and not self._async_session.closed:
+            await self._async_session.close()
+            self._async_session = None
+
+    # Context manager support (sync)
+
+    def __enter__(self):
+        """Enter synchronous context manager.
+
+        Returns:
+            Self for context manager usage
+        """
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Exit synchronous context manager.
+
+        Closes sync session automatically.
+        """
+        self.close()
+
+    # Async context manager support
+
+    async def __aenter__(self):
+        """Enter asynchronous context manager.
+
+        Returns:
+            Self for async context manager usage
+        """
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Exit asynchronous context manager.
+
+        Closes async session automatically.
+        """
+        await self.aclose()
+
+    def __del__(self):
+        """Cleanup on deletion.
+
+        Attempts to close sessions if they're still open.
+        """
+        try:
+            if self._sync_session is not None:
+                self._sync_session.close()
+        except Exception:
+            pass

blizzardapi3/core/context.py

@@ -0,0 +1,23 @@
+"""Request context for API calls."""
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class RequestContext:
+    """Context information for an API request.
+
+    Attributes:
+        region: API region (e.g., "us", "eu")
+        path: API endpoint path
+        query_params: Query string parameters
+        access_token: User-provided OAuth access token (optional)
+        auth_type: Type of authentication ("client_credentials" or "oauth")
+    """
+
+    region: str
+    path: str
+    query_params: dict[str, Any]
+    access_token: str | None = None
+    auth_type: str = "client_credentials"