opendota-sdk 0.1.0a1__tar.gz

opendota_sdk-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juan Manuel Bermudez Cabrera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opendota_sdk-0.1.0a1/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: opendota-sdk
+Version: 0.1.0a1
+Summary: SDK for the OpenDota API, providing enhanced capabilities for Dota 2 data.
+Author: Juan Manuel Bermudez Cabrera
+Author-email: Juan Manuel Bermudez Cabrera <juanmorestep@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: niquests>=3.9,<4.0
+Requires-Dist: tenacity>=9.0,<10.0
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/jbnone/opendota-sdk
+Project-URL: Issues, https://github.com/jbnone/opendota-sdk/issues
+Project-URL: Repository, https://github.com/jbnone/opendota-sdk
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<h1>Open Dota SDK</h1>
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![prek](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/j178/prek/master/docs/assets/badge-v0.json)](https://github.com/j178/prek)
+
+</div>
+
+Build better Dota 2 tools with the OpenDota SDK, providing enhanced access to [OpenDota API](https://docs.opendota.com/) data.

opendota_sdk-0.1.0a1/README.md

@@ -0,0 +1,13 @@
+<div align="center">
+
+<h1>Open Dota SDK</h1>
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![prek](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/j178/prek/master/docs/assets/badge-v0.json)](https://github.com/j178/prek)
+
+</div>
+
+Build better Dota 2 tools with the OpenDota SDK, providing enhanced access to [OpenDota API](https://docs.opendota.com/) data.

opendota_sdk-0.1.0a1/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "opendota-sdk"
+version = "0.1.0-alpha.1"
+description = "SDK for the OpenDota API, providing enhanced capabilities for Dota 2 data."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [
+    { name = "Juan Manuel Bermudez Cabrera", email = "juanmorestep@gmail.com" }
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+dependencies = [
+  "niquests>=3.9,<4.0",
+  "tenacity>=9.0,<10.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/jbnone/opendota-sdk"
+Issues = "https://github.com/jbnone/opendota-sdk/issues"
+Repository = "https://github.com/jbnone/opendota-sdk"
+
+
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest==9.0.3",
+    "pytest-asyncio==1.3.0",
+    "ruff==0.15.11",
+    "ty==0.0.31",
+]

opendota_sdk-0.1.0a1/src/opendota_sdk/__init__.py

@@ -0,0 +1,25 @@
+"""OpenDota SDK - A modern, type-safe Python SDK for the OpenDota API."""
+
+from opendota_sdk._config import OpenDotaClientConfig, config_from_env, default_config
+from opendota_sdk._errors import (
+    HTTPStatusError,
+    OpenDotaError,
+    RateLimitError,
+    ResponseDecodeError,
+    TransportError,
+)
+from opendota_sdk.client import OpenDotaAsyncClient, OpenDotaClient
+
+__version__ = "0.1.0"
+__all__ = [
+    "OpenDotaClient",
+    "OpenDotaAsyncClient",
+    "OpenDotaClientConfig",
+    "OpenDotaError",
+    "HTTPStatusError",
+    "RateLimitError",
+    "TransportError",
+    "ResponseDecodeError",
+    "default_config",
+    "config_from_env",
+]

opendota_sdk-0.1.0a1/src/opendota_sdk/_config.py

@@ -0,0 +1,81 @@
+"""Configuration for OpenDota SDK transport and client behavior."""
+
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class OpenDotaClientConfig:
+    """Configuration for OpenDota API client.
+
+    Attributes:
+        api_key: Optional API key for authentication. If not provided, checks
+            OPENDOTA_API_KEY environment variable.
+        base_url: Base URL for the OpenDota API.
+        timeout: Request timeout in seconds.
+        max_retries: Maximum number of retries for failed requests.
+        backoff_factor: Exponential backoff factor for retries.
+        retry_on_status: HTTP status codes that trigger automatic retries.
+        extra_headers: Extra headers to include in all requests.
+        verify_ssl: Whether to verify SSL certificates.
+        trust_env: Whether to trust environment settings for HTTP proxies, etc.
+    """
+
+    api_key: str | None = None
+    base_url: str = "https://api.opendota.com/api"
+    timeout: float = 10.0
+    max_retries: int = 3
+    backoff_factor: float = 0.5
+    retry_on_status: list[int] = field(
+        default_factory=lambda: [429, 500, 502, 503, 504]
+    )
+    extra_headers: dict[str, str] = field(default_factory=dict)
+    verify_ssl: bool = True
+    trust_env: bool = True
+
+    def merge_other(self, other: "OpenDotaClientConfig") -> "OpenDotaClientConfig":
+        """Merge another config into this one, with the other config taking precedence."""
+        return OpenDotaClientConfig(
+            api_key=other.api_key or self.api_key,
+            base_url=other.base_url or self.base_url,
+            timeout=other.timeout or self.timeout,
+            max_retries=other.max_retries or self.max_retries,
+            backoff_factor=other.backoff_factor or self.backoff_factor,
+            retry_on_status=other.retry_on_status or self.retry_on_status,
+            extra_headers={**self.extra_headers, **other.extra_headers},
+            verify_ssl=other.verify_ssl
+            if other.verify_ssl is not None
+            else self.verify_ssl,
+            trust_env=other.trust_env
+            if other.trust_env is not None
+            else self.trust_env,
+        )
+
+
+def default_config() -> OpenDotaClientConfig:
+    """Create a default OpenDota client configuration.
+
+    Returns:
+        An OpenDotaClientConfig with sensible defaults for the OpenDota API.
+    """
+    return OpenDotaClientConfig()
+
+
+def config_from_env() -> OpenDotaClientConfig:
+    """Create configuration from environment variables.
+
+    Reads:
+        OPENDOTA_API_KEY: API key for authentication.
+        OPENDOTA_BASE_URL: Base URL for the API (default: https://api.opendota.com/api).
+        OPENDOTA_TIMEOUT: Request timeout in seconds (default: 10.0).
+        OPENDOTA_MAX_RETRIES: Maximum number of retries (default: 3).
+
+    Returns:
+        An OpenDotaClientConfig populated from environment variables.
+    """
+    return OpenDotaClientConfig(
+        api_key=os.getenv("OPENDOTA_API_KEY"),
+        base_url=os.getenv("OPENDOTA_BASE_URL", "https://api.opendota.com/api"),
+        timeout=float(os.getenv("OPENDOTA_TIMEOUT", "10.0")),
+        max_retries=int(os.getenv("OPENDOTA_MAX_RETRIES", "3")),
+    )

opendota_sdk-0.1.0a1/src/opendota_sdk/_errors.py

@@ -0,0 +1,89 @@
+"""OpenDota SDK exception hierarchy and error types."""
+
+from typing import Any
+
+
+class OpenDotaError(Exception):
+    """Base exception for all OpenDota SDK errors."""
+
+    pass
+
+
+class TransportError(OpenDotaError):
+    """Raised when a transport-level error occurs (connection, timeout, etc.)."""
+
+    pass
+
+
+class HTTPStatusError(OpenDotaError):
+    """Raised when an HTTP response indicates an error status code.
+
+    Attributes:
+        status_code: The HTTP status code returned by the server.
+        method: The HTTP method used in the request.
+        url: The URL that was requested.
+        response_text: The response body as text.
+        headers: The response headers.
+    """
+
+    def __init__(
+        self,
+        status_code: int | None,
+        method: str,
+        url: str | None,
+        response_text: str | None = None,
+        headers: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize HTTPStatusError.
+
+        Args:
+            status_code: The HTTP status code returned by the server.
+            method: The HTTP method used in the request.
+            url: The URL that was requested.
+            response_text: The response body as text (optional).
+            headers: The response headers (optional).
+        """
+        self.status_code = status_code
+        self.method = method
+        self.url = url
+        self.response_text = response_text
+        self.headers = headers or {}
+        message = f"{method} {url}: {status_code}"
+        if response_text:
+            truncated = (
+                response_text[:100] + "..."
+                if len(response_text) > 100
+                else response_text
+            )
+            message += f"\n{truncated}"
+        super().__init__(message)
+
+
+class RateLimitError(OpenDotaError):
+    """Raised when the API rate limit is exceeded (HTTP 429).
+
+    Attributes:
+        retry_after: The number of seconds to wait before retrying, if provided.
+        message: A descriptive error message.
+    """
+
+    def __init__(self, retry_after: int | None = None, message: str = "") -> None:
+        """Initialize RateLimitError.
+
+        Args:
+            retry_after: The number of seconds to wait before retrying (optional).
+            message: A descriptive error message (optional).
+        """
+        self.retry_after = retry_after
+        if not message:
+            if retry_after:
+                message = f"Rate limited. Retry after {retry_after} seconds."
+            else:
+                message = "Rate limited."
+        super().__init__(message)
+
+
+class ResponseDecodeError(OpenDotaError):
+    """Raised when response body cannot be decoded (e.g., invalid JSON)."""
+
+    pass

opendota_sdk-0.1.0a1/src/opendota_sdk/client.py

@@ -0,0 +1,284 @@
+"""Public client interface for the OpenDota API."""
+
+import logging
+from typing import Any
+
+from opendota_sdk._config import OpenDotaClientConfig, config_from_env, default_config
+from opendota_sdk.http._auth import AuthHandler
+from opendota_sdk.http._retry import RetryPolicy
+from opendota_sdk.http._transport import AsyncHTTPTransport, SyncHTTPTransport
+from opendota_sdk.responses import HeroesResponse
+
+logger = logging.getLogger(__name__)
+
+
+class ClientLogicMixin:
+    """Mixin for client logic that can be shared between sync and async clients."""
+
+    def make_heroes_response(
+        self,
+        *,
+        heroes_api: list[dict[str, Any]],
+        heroes_constants: dict[str, dict[str, Any]],
+    ) -> HeroesResponse:
+        """Updates hero data from the constants  with the data from /heroes and return a HeroesResponse."""
+        heroes: list[dict[str, Any]] = []
+        for hero in heroes_api:
+            hero_id = str(hero["id"])
+            if hero_id in heroes_constants:
+                merged_hero = {**heroes_constants[hero_id], **hero}
+                heroes.append(merged_hero)
+            else:
+                logger.warning(
+                    f"Hero ID {hero_id} from /heroes not found in /constants/heroes, using API data only"
+                )
+                heroes.append(hero)
+
+        return HeroesResponse(heroes)
+
+
+class OpenDotaClient(ClientLogicMixin):
+    """Synchronous client for the OpenDota API.
+
+    Provides high-level, ergonomic access to OpenDota API endpoints with
+    automatic retry handling, rate-limit management, and API key authentication.
+
+    Example:
+        ```python
+        from opendota_sdk import OpenDotaClient
+
+        # Zero-config usage
+        client = OpenDotaClient()
+        heroes = client.get_heroes()
+
+        # With API key
+        client = OpenDotaClient(api_key="my-key")
+        heroes = client.get_heroes()
+
+        # Context manager for resource management
+        with OpenDotaClient() as client:
+            heroes = client.get_heroes()
+        ```
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        timeout: float = 10.0,
+        max_retries: int = 3,
+        base_url: str | None = None,
+        config: OpenDotaClientConfig | None = None,
+    ) -> None:
+        """Initialize the OpenDota client.
+
+        Args:
+            api_key: Optional API key for authentication. If not provided, checks
+                OPENDOTA_API_KEY environment variable.
+            timeout: Request timeout in seconds (default: 10.0).
+            max_retries: Maximum number of retries for failed requests (default: 3).
+            base_url: Optional base URL for the API (default: https://api.opendota.com/api).
+            config: Optional OpenDotaClientConfig for advanced customization.
+                If provided, overrides all other arguments.
+        """
+        config_from_args = OpenDotaClientConfig(
+            api_key=api_key,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        if base_url:
+            config_from_args.base_url = base_url
+
+        if config is None:
+            defaults = default_config()
+            self._config = defaults.merge_other(config_from_env()).merge_other(
+                config_from_args
+            )
+        else:
+            self._config = config
+
+        self._auth_handler = AuthHandler(api_key=self._config.api_key)
+        self._retry_policy = RetryPolicy(
+            max_retries=self._config.max_retries,
+            backoff_factor=self._config.backoff_factor,
+            retry_on_status=self._config.retry_on_status,
+        )
+        self._transport = SyncHTTPTransport(
+            config=self._config,
+            auth_handler=self._auth_handler,
+            retry_policy=self._retry_policy,
+        )
+
+    def _get(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: Any | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Make an internal HTTP request and return decoded JSON.
+
+        Args:
+            method: HTTP method (GET, POST, etc.).
+            path: API path (e.g., "/heroStats").
+            params: Query parameters.
+            json_body: JSON request body.
+            **kwargs: Additional arguments passed to transport.
+
+        Returns:
+            The decoded JSON response body.
+        """
+        return self._transport.request_json(
+            method="GET",
+            path=path,
+            params=params,
+            json_body=json_body,
+            **kwargs,
+        )
+
+    def get_heroes(self) -> HeroesResponse:
+        """Retrieve info about all Dota 2 heroes.
+
+        Returns:
+            A HeroesResponse containing a list of hero data.
+
+        Raises:
+            OpenDotaError: For any API-related errors, including HTTP errors, rate limits, and decoding issues.
+        """
+        heroes_api: list[dict[str, Any]] = self._get("/heroes")
+        heroes_constants: dict[str, dict[str, Any]] = self._get("/constants/heroes")
+        return self.make_heroes_response(
+            heroes_api=heroes_api, heroes_constants=heroes_constants
+        )
+
+    def close(self) -> None:
+        """Close the client and release resources."""
+        self._transport.close()
+
+    def __enter__(self) -> "OpenDotaClient":
+        """Enter context manager."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Exit context manager and close the client."""
+        self.close()
+
+
+class OpenDotaAsyncClient(ClientLogicMixin):
+    """Asynchronous client for the OpenDota API.
+
+    Provides high-level, ergonomic access to OpenDota API endpoints with
+    automatic retry handling, rate-limit management, and API key authentication.
+    All operations are async and must be awaited.
+
+    Example:
+        ```python
+        import asyncio
+        from opendota_sdk import OpenDotaAsyncClient
+
+        async def main():
+            # Zero-config usage
+            async with OpenDotaAsyncClient() as client:
+                heroes = await client.get_heroes()
+                print(f"Loaded {len(heroes)} heroes")
+
+        asyncio.run(main())
+        ```
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        timeout: float = 10.0,
+        max_retries: int = 3,
+        base_url: str | None = None,
+        config: OpenDotaClientConfig | None = None,
+    ) -> None:
+        """Initialize the async OpenDota client.
+
+        Args:
+            api_key: Optional API key for authentication. If not provided, checks
+                OPENDOTA_API_KEY environment variable.
+            timeout: Request timeout in seconds (default: 10.0).
+            max_retries: Maximum number of retries for failed requests (default: 3).
+            base_url: Optional base URL for the API (default: https://api.opendota.com/api).
+            config: Optional OpenDotaClientConfig for advanced customization.
+                If provided, overrides all other arguments.
+        """
+        if config is None:
+            config = OpenDotaClientConfig(
+                api_key=api_key,
+                timeout=timeout,
+                max_retries=max_retries,
+                base_url=base_url or "https://api.opendota.com/api",
+            )
+
+        self._config = config
+        self._auth_handler = AuthHandler(api_key=config.api_key)
+        self._retry_policy = RetryPolicy(
+            max_retries=config.max_retries,
+            backoff_factor=config.backoff_factor,
+            retry_on_status=config.retry_on_status,
+        )
+        self._transport = AsyncHTTPTransport(
+            config=config,
+            auth_handler=self._auth_handler,
+            retry_policy=self._retry_policy,
+        )
+
+    async def _get(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: Any | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Make an internal HTTP request and return decoded JSON.
+
+        Args:
+            method: HTTP method (GET, POST, etc.).
+            path: API path (e.g., "/heroStats").
+            params: Query parameters.
+            json_body: JSON request body.
+            **kwargs: Additional arguments passed to transport.
+
+        Returns:
+            The decoded JSON response body.
+        """
+        return await self._transport.request_json(
+            method="GET",
+            path=path,
+            params=params,
+            json_body=json_body,
+            **kwargs,
+        )
+
+    async def get_heroes(self) -> HeroesResponse:
+        """Retrieve info about all Dota 2 heroes.
+
+        Returns:
+            A HeroesResponse containing a list of hero data.
+
+        Raises:
+            OpenDotaError: For any API-related errors, including HTTP errors, rate limits, and decoding issues.
+        """
+        heroes_api: list[dict[str, Any]] = await self._get("/heroes")
+        heroes_constants: dict[str, dict[str, Any]] = await self._get(
+            "/constants/heroes"
+        )
+        return self.make_heroes_response(
+            heroes_api=heroes_api, heroes_constants=heroes_constants
+        )
+
+    async def close(self) -> None:
+        """Close the client and release resources."""
+        await self._transport.close()
+
+    async def __aenter__(self) -> "OpenDotaAsyncClient":
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Async context manager exit and close the client."""
+        await self.close()

opendota_sdk-0.1.0a1/src/opendota_sdk/enums.py

@@ -0,0 +1,24 @@
+from enum import StrEnum
+
+
+class HeroRole(StrEnum):
+    CARRY = "Carry"
+    SUPPORT = "Support"
+    NUKER = "Nuker"
+    DISABLER = "Disabler"
+    JUNGLER = "Jungler"
+    DURABLE = "Durable"
+    ESCAPE = "Escape"
+    Pusher = "Pusher"
+
+
+class HeroAttackType(StrEnum):
+    MELEE = "Melee"
+    RANGED = "Ranged"
+
+
+class HeroPrimaryAttr(StrEnum):
+    STR = "str"
+    AGI = "agi"
+    INT = "int"
+    ALL = "all"

opendota_sdk-0.1.0a1/src/opendota_sdk/http/__init__.py

@@ -0,0 +1 @@
+"""Internal HTTP transport layer for OpenDota SDK."""

opendota_sdk-0.1.0a1/src/opendota_sdk/http/_auth.py

@@ -0,0 +1,52 @@
+"""Authentication handler for API key injection."""
+
+import os
+from typing import Any
+
+
+class AuthHandler:
+    """Handles API key authentication by injecting credentials into requests.
+
+    Supports injection via HTTP headers (default) or query parameters.
+
+    Attributes:
+        api_key: The API key for authentication.
+        header_name: The header name for API key injection (e.g., "X-API-Key").
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        header_name: str = "X-API-Key",
+    ) -> None:
+        """Initialize the authentication handler.
+
+        Args:
+            api_key: Optional API key. If not provided, reads from OPENDOTA_API_KEY
+                environment variable.
+            header_name: The HTTP header name for API key injection.
+        """
+        self.api_key = api_key or os.getenv("OPENDOTA_API_KEY")
+        self.header_name = header_name
+
+    def apply_to_headers(self, headers: dict[str, Any]) -> dict[str, Any]:
+        """Inject API key into request headers.
+
+        Args:
+            headers: The headers dictionary to modify.
+
+        Returns:
+            The modified headers dictionary with API key injected (if available).
+        """
+        if self.api_key:
+            headers = dict(headers)
+            headers[self.header_name] = self.api_key
+        return headers
+
+    def has_auth(self) -> bool:
+        """Check if an API key is configured.
+
+        Returns:
+            True if an API key is set, False otherwise.
+        """
+        return bool(self.api_key)

opendota_sdk-0.1.0a1/src/opendota_sdk/http/_retry.py

@@ -0,0 +1,72 @@
+"""Retry policy and decorator builder for HTTP requests."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from tenacity import (
+    Retrying,
+    retry_if_exception_type,
+    retry_if_result,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+
+@dataclass
+class RetryPolicy:
+    """Policy for retrying failed HTTP requests.
+
+    Attributes:
+        max_retries: Maximum number of attempts (total, including initial).
+        backoff_factor: Multiplier for exponential backoff wait time.
+        retry_on_status: HTTP status codes that should trigger a retry.
+        retry_on_timeout: Whether to retry on timeout exceptions.
+    """
+
+    max_retries: int = 3
+    backoff_factor: float = 0.5
+    retry_on_status: list[int] = field(
+        default_factory=lambda: [429, 500, 502, 503, 504]
+    )
+    retry_on_timeout: bool = True
+
+
+def build_retry_decorator(policy: RetryPolicy) -> Retrying:
+    """Build a tenacity Retrying object from a retry policy.
+
+    The returned object can be used as a decorator or context manager to retry
+    a callable with exponential backoff. Retries are triggered when:
+    - The response status code is in retry_on_status
+    - A timeout exception occurs (if retry_on_timeout is True)
+
+    Args:
+        policy: The retry policy configuration.
+
+    Returns:
+        A tenacity.Retrying object configured according to the policy.
+    """
+
+    def should_retry(result: Any) -> bool:
+        """Check if response should be retried based on status code."""
+        if hasattr(result, "status_code"):
+            return result.status_code in policy.retry_on_status
+        return False
+
+    retry_decorator = Retrying(
+        stop=stop_after_attempt(policy.max_retries),
+        wait=wait_exponential(multiplier=policy.backoff_factor, min=1, max=60),
+        retry=retry_if_result(should_retry),
+        reraise=True,
+    )
+
+    if policy.retry_on_timeout:
+        retry_decorator = Retrying(
+            stop=stop_after_attempt(policy.max_retries),
+            wait=wait_exponential(multiplier=policy.backoff_factor, min=1, max=60),
+            retry=(
+                retry_if_result(should_retry) | retry_if_exception_type(TimeoutError)
+            ),
+            reraise=True,
+        )
+
+    return retry_decorator

opendota_sdk-0.1.0a1/src/opendota_sdk/http/_transport.py

@@ -0,0 +1,479 @@
+"""HTTP transport layer for OpenDota API requests."""
+
+import json
+from typing import Any
+from urllib.parse import urljoin
+
+import niquests
+
+from opendota_sdk._config import OpenDotaClientConfig
+from opendota_sdk._errors import (
+    HTTPStatusError,
+    RateLimitError,
+    ResponseDecodeError,
+    TransportError,
+)
+
+from ._auth import AuthHandler
+from ._retry import RetryPolicy, build_retry_decorator
+
+
+_DEFAULT_HEADERS = {"Accept": "application/json"}
+
+
+class HTTPTransportBase:
+    """Base class for HTTP transports.
+
+    Defines the interface and common functionality for both sync and async transports.
+    """
+
+    def __init__(
+        self,
+        config: OpenDotaClientConfig,
+        auth_handler: AuthHandler,
+        retry_policy: RetryPolicy,
+    ) -> None:
+        """Initialize the transport.
+
+        Args:
+            config: The client configuration.
+            auth_handler: Authentication handler for API key injection.
+            retry_policy: Policy for retrying failed requests.
+        """
+        self.config = config
+        self.auth_handler = auth_handler
+        self.retry_policy = retry_policy
+        self._retry_decorator = build_retry_decorator(retry_policy)
+
+    def build_url(self, path: str) -> str:
+        """Build full URL from base URL and path.
+
+        Args:
+            path: The API path (e.g., "/heroStats").
+
+        Returns:
+            The full URL.
+        """
+        base_url = self.config.base_url
+        if base_url:
+            # Ensure base URL ends with a slash for proper urljoin behavior
+            sanitized_base_url = base_url if base_url.endswith("/") else base_url + "/"
+        else:
+            sanitized_base_url = ""
+
+        return urljoin(sanitized_base_url, path.lstrip("/"))
+
+    def build_headers(
+        self, request_headers: dict[str, str] | None = None
+    ) -> dict[str, str]:
+        """Build request headers by merging defaults, config, and extra headers.
+
+        Args:
+            extra_headers: Additional headers to include in the request.
+
+        Returns:
+            The merged headers dictionary.
+        """
+        merged_headers = _DEFAULT_HEADERS.copy()
+        merged_headers.update(self.config.extra_headers or {})
+        if request_headers:
+            merged_headers.update(request_headers)
+
+        return self.auth_handler.apply_to_headers(merged_headers)
+
+    def handle_response(
+        self, response: niquests.Response, method: str
+    ) -> niquests.Response:
+        """Validate response status and raise errors if needed.
+
+        Args:
+            response: The HTTP response.
+            method: The HTTP method used.
+
+        Returns:
+            The response if valid.
+
+        Raises:
+            RateLimitError: If rate limited (429).
+            HTTPStatusError: For other error status codes.
+        """
+        if response.status_code == 429:
+            retry_after = None
+            if "Retry-After" in response.headers:
+                try:
+                    retry_after = int(response.headers["Retry-After"])
+                except (ValueError, TypeError):
+                    pass
+            raise RateLimitError(
+                retry_after=retry_after,
+                message=f"Rate limited on {method} {response.url}",
+            )
+
+        if not response.ok:
+            raise HTTPStatusError(
+                status_code=response.status_code,
+                method=method,
+                url=response.url,
+                response_text=response.text,
+                headers=dict(response.headers),
+            )
+
+        return response
+
+
+class SyncHTTPTransport(HTTPTransportBase):
+    """Synchronous HTTP transport using niquests.
+
+    Handles request execution, retries, rate limiting, and API key authentication
+    for synchronous operations.
+    """
+
+    def __init__(
+        self,
+        config: OpenDotaClientConfig,
+        auth_handler: AuthHandler,
+        retry_policy: RetryPolicy,
+    ) -> None:
+        """Initialize the sync transport.
+
+        Args:
+            config: The client configuration.
+            auth_handler: Authentication handler for API key injection.
+            retry_policy: Policy for retrying failed requests.
+        """
+        super().__init__(config, auth_handler, retry_policy)
+        self._session = niquests.Session()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_body: Any | None = None,
+        data: Any | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
+    ) -> niquests.Response:
+        """Make an HTTP request.
+
+        Args:
+            method: HTTP method.
+            path: API path.
+            params: Query parameters.
+            json_body: JSON body for POST/PUT.
+            data: Form data.
+            headers: Additional headers.
+            timeout: Request timeout in seconds.
+
+        Returns:
+            The HTTP response.
+
+        Raises:
+            HTTPStatusError: For error status codes.
+            TransportError: For connection/timeout errors.
+            RateLimitError: For rate limit errors.
+        """
+
+        def _do_request() -> niquests.Response:
+            try:
+                response = self._session.request(
+                    method=method,
+                    url=self.build_url(path),
+                    params=params or None,
+                    json=json_body,
+                    data=data,
+                    headers=self.build_headers(headers),
+                    timeout=timeout or self.config.timeout,
+                    verify=self.config.verify_ssl,
+                )
+                return self.handle_response(response, method)
+            except (
+                niquests.RequestException,
+                niquests.ConnectionError,
+                niquests.Timeout,
+            ) as exc:
+                raise TransportError(f"Request failed: {exc}") from exc
+            except RateLimitError:
+                raise
+            except HTTPStatusError:
+                raise
+
+        try:
+            return self._retry_decorator(_do_request)
+        except Exception as exc:
+            if isinstance(exc, (RateLimitError, HTTPStatusError, TransportError)):
+                raise
+            raise TransportError(f"Unexpected error: {exc}") from exc
+
+    def request_json(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_body: Any | None = None,
+        data: Any | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
+    ) -> Any:
+        """Make a request and return decoded JSON.
+
+        Args:
+            method: HTTP method.
+            path: API path.
+            params: Query parameters.
+            json_body: JSON body.
+            data: Form data.
+            headers: Additional headers.
+            timeout: Request timeout.
+
+        Returns:
+            The decoded JSON response body.
+
+        Raises:
+            HTTPStatusError: For error status codes.
+            TransportError: For connection errors.
+            ResponseDecodeError: If JSON decoding fails.
+        """
+        response = self.request(
+            method=method,
+            path=path,
+            params=params,
+            json_body=json_body,
+            data=data,
+            headers=headers,
+            timeout=timeout,
+        )
+        try:
+            return response.json()
+        except json.JSONDecodeError as exc:
+            raise ResponseDecodeError(
+                f"Failed to decode JSON from {response.url}: {exc}"
+            ) from exc
+
+    def request_bytes(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_body: Any | None = None,
+        data: Any | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
+    ) -> bytes:
+        """Make a request and return raw bytes.
+
+        Args:
+            method: HTTP method.
+            path: API path.
+            params: Query parameters.
+            json_body: JSON body.
+            data: Form data.
+            headers: Additional headers.
+            timeout: Request timeout.
+
+        Returns:
+            The raw response body as bytes.
+        """
+        response = self.request(
+            method=method,
+            path=path,
+            params=params,
+            json_body=json_body,
+            data=data,
+            headers=headers,
+            timeout=timeout,
+        )
+        return response.content or b""
+
+    def close(self) -> None:
+        """Close the session and clean up resources."""
+        self._session.close()
+
+    def __enter__(self) -> "SyncHTTPTransport":
+        """Enter context manager."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Exit context manager and close the session."""
+        self.close()
+
+
+class AsyncHTTPTransport(HTTPTransportBase):
+    """Asynchronous HTTP transport using niquests.
+
+    Handles request execution, retries, rate limiting, and API key authentication
+    for asynchronous operations.
+
+    This is an internal transport implementation. It is not part of the public API
+    and should not be used directly by end users.
+    """
+
+    def __init__(
+        self,
+        config: OpenDotaClientConfig,
+        auth_handler: AuthHandler,
+        retry_policy: RetryPolicy,
+    ) -> None:
+        """Initialize the async transport.
+
+        Args:
+            config: The client configuration.
+            auth_handler: Authentication handler for API key injection.
+            retry_policy: Policy for retrying failed requests.
+        """
+        super().__init__(config, auth_handler, retry_policy)
+        self._session = niquests.AsyncSession()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_body: Any | None = None,
+        data: Any | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
+    ) -> niquests.Response:
+        """Make an HTTP request.
+
+        Args:
+            method: HTTP method.
+            path: API path.
+            params: Query parameters.
+            json_body: JSON body for POST/PUT.
+            data: Form data.
+            headers: Additional headers.
+            timeout: Request timeout in seconds.
+
+        Returns:
+            The HTTP response.
+
+        Raises:
+            HTTPStatusError: For error status codes.
+            TransportError: For connection/timeout errors.
+            RateLimitError: For rate limit errors.
+        """
+
+        async def _do_request() -> niquests.Response:
+            try:
+                response = await self._session.request(
+                    method=method,
+                    url=self.build_url(path),
+                    params=params or None,
+                    json=json_body,
+                    data=data,
+                    headers=self.build_headers(headers),
+                    timeout=timeout or self.config.timeout,
+                    verify=self.config.verify_ssl,
+                )
+                return self.handle_response(response, method)
+            except (
+                niquests.RequestException,
+                niquests.ConnectionError,
+                niquests.Timeout,
+            ) as exc:
+                raise TransportError(f"Request failed: {exc}") from exc
+            except RateLimitError:
+                raise
+            except HTTPStatusError:
+                raise
+
+        try:
+            return await self._retry_decorator(_do_request)
+        except Exception as exc:
+            if isinstance(exc, (RateLimitError, HTTPStatusError, TransportError)):
+                raise
+            raise TransportError(f"Unexpected error: {exc}") from exc
+
+    async def request_json(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_body: Any | None = None,
+        data: Any | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
+    ) -> Any:
+        """Make a request and return decoded JSON.
+
+        Args:
+            method: HTTP method.
+            path: API path.
+            params: Query parameters.
+            json_body: JSON body.
+            data: Form data.
+            headers: Additional headers.
+            timeout: Request timeout.
+
+        Returns:
+            The decoded JSON response body.
+
+        Raises:
+            HTTPStatusError: For error status codes.
+            TransportError: For connection errors.
+            ResponseDecodeError: If JSON decoding fails.
+        """
+        response = await self.request(
+            method=method,
+            path=path,
+            params=params,
+            json_body=json_body,
+            data=data,
+            headers=headers,
+            timeout=timeout,
+        )
+        try:
+            return response.json()
+        except json.JSONDecodeError as exc:
+            raise ResponseDecodeError(
+                f"Failed to decode JSON from {response.url}: {exc}"
+            ) from exc
+
+    async def request_bytes(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_body: Any | None = None,
+        data: Any | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
+    ) -> bytes:
+        """Make a request and return raw bytes.
+
+        Args:
+            method: HTTP method.
+            path: API path.
+            params: Query parameters.
+            json_body: JSON body.
+            data: Form data.
+            headers: Additional headers.
+            timeout: Request timeout.
+
+        Returns:
+            The raw response body as bytes.
+        """
+        response = await self.request(
+            method=method,
+            path=path,
+            params=params,
+            json_body=json_body,
+            data=data,
+            headers=headers,
+            timeout=timeout,
+        )
+        return response.content or b""
+
+    async def close(self) -> None:
+        """Close the session and clean up resources."""
+        if self._session is not None:
+            await self._session.close()
+
+    async def __aenter__(self) -> "AsyncHTTPTransport":
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Async context manager exit and close the session."""
+        await self.close()

opendota_sdk-0.1.0a1/src/opendota_sdk/models.py

@@ -0,0 +1,42 @@
+from opendota_sdk.enums import HeroPrimaryAttr, HeroAttackType, HeroRole
+from dataclasses import dataclass
+
+
+@dataclass
+class Hero:
+    # Values coming from the API
+    id: int
+    name: str
+    localized_name: str
+    primary_attr: HeroPrimaryAttr
+    attack_type: HeroAttackType
+    roles: list[HeroRole]
+    legs: int
+
+    # Values coming from dotaconstants
+    img: str
+    icon: str
+    base_health: int
+    base_health_regen: float
+    base_mana: int
+    base_mana_regen: float
+    base_armor: float
+    base_mr: int
+    base_attack_min: int
+    base_attack_max: int
+    base_attack_time: int
+    base_str: int
+    base_agi: int
+    base_int: int
+    str_gain: float
+    agi_gain: float
+    int_gain: float
+    attack_point: float
+    attack_range: int
+    projectile_speed: int
+    attack_rate: float
+    move_speed: int
+    turn_rate: float | None
+    cm_enabled: bool
+    day_vision: int
+    night_vision: int

opendota_sdk-0.1.0a1/src/opendota_sdk/responses.py

@@ -0,0 +1,13 @@
+from opendota_sdk.models import Hero
+from typing import Any
+
+
+class HeroesResponse:
+    def __init__(self, data: list[dict[str, Any]]) -> None:
+        self._data = data
+
+    def as_typed(self) -> list[Hero]:
+        return [Hero(**hero) for hero in self._data]
+
+    def as_raw(self) -> list[dict[str, Any]]:
+        return self._data