faceit 0.1.0__py3-none-any.whl

faceit/__init__.py

@@ -0,0 +1,35 @@
+from .__version__ import __version__
+from ._faceit import AsyncFaceit, Faceit
+from ._resources import (
+    AsyncPageIterator,
+    CollectReturnFormat,
+    SyncPageIterator,
+    check_pagination_support,
+)
+from .constants import (
+    ELO_THRESHOLDS,
+    EventCategory,
+    ExpandOption,
+    GameID,
+    HighTierLevel,
+    SkillLevel,
+)
+from .http import AsyncClient, SyncClient
+
+__all__ = (
+    "ELO_THRESHOLDS",
+    "AsyncClient",
+    "AsyncFaceit",
+    "AsyncPageIterator",
+    "CollectReturnFormat",
+    "EventCategory",
+    "ExpandOption",
+    "Faceit",
+    "GameID",
+    "HighTierLevel",
+    "SkillLevel",
+    "SyncClient",
+    "SyncPageIterator",
+    "__version__",
+    "check_pagination_support",
+)

faceit/__version__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version(__package__ or __name__)
+except PackageNotFoundError:
+    __version__ = "dev"

faceit/_faceit.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import typing as t
+from abc import ABC
+from warnings import warn
+
+from ._repr import representation
+from ._resources import AsyncResources, SyncResources
+from ._typing import ClientT, ResourceT, Self, ValidUUID
+from .constants import BASE_WIKI_URL
+from .http import AsyncClient, SyncClient
+
+if t.TYPE_CHECKING:
+    from types import TracebackType
+
+
+@representation("client", "resources")
+class BaseFaceit(t.Generic[ClientT, ResourceT], ABC):
+    __slots__ = "_client", "_resources"
+
+    _client_cls: t.Type[ClientT]
+    _resources_cls: t.Type[ResourceT]
+
+    @t.overload
+    def __init__(
+        self,
+        api_key: ValidUUID,
+        **client_options: t.Any,
+    ) -> None: ...
+
+    @t.overload
+    def __init__(
+        self,
+        *,
+        client: ClientT,
+    ) -> None: ...
+
+    def __init__(
+        self,
+        api_key: t.Optional[ValidUUID] = None,
+        *,
+        client: t.Optional[ClientT] = None,
+        **client_options: t.Any,
+    ) -> None:
+        if api_key is None and client is None:
+            raise ValueError("Either 'api_key' or 'client' must be provided")
+        if api_key is not None and client is not None:
+            raise ValueError("Provide either 'api_key' or 'client', not both")
+
+        if client is not None:
+            if client_options:
+                warn(
+                    "'client_options' are ignored when an existing client "
+                    "instance is provided. Configure your client before "
+                    "passing it to this constructor.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+            self._client = client
+        else:
+            self._client = self.__class__._client_cls(
+                api_key, **client_options
+            )
+
+        self._resources = self.__class__._resources_cls(self._client)
+
+    @property
+    def client(self) -> ClientT:
+        return self._client
+
+    @property
+    def resources(self) -> ResourceT:
+        return self._resources
+
+    def __str__(self) -> str:
+        return (
+            f"FACEIT API interface "
+            f"(resources and client, docs: {BASE_WIKI_URL})"
+        )
+
+
+@t.final
+class Faceit(BaseFaceit[SyncClient, SyncResources]):
+    __slots__ = ()
+
+    _client_cls = SyncClient
+    _resources_cls = SyncResources
+
+    def __enter__(self) -> Self:
+        self.client.__enter__()
+        return self
+
+    def __exit__(
+        self,
+        typ: t.Optional[t.Type[BaseException]],
+        exc: t.Optional[BaseException],
+        tb: t.Optional[TracebackType],
+    ) -> None:
+        self.client.__exit__(typ, exc, tb)
+
+
+@t.final
+class AsyncFaceit(BaseFaceit[AsyncClient, AsyncResources]):
+    __slots__ = ()
+
+    _client_cls = AsyncClient
+    _resources_cls = AsyncResources
+
+    MAX_CONCURRENT_REQUESTS: t.ClassVar[int] = (
+        AsyncClient.MAX_CONCURRENT_REQUESTS
+    )
+
+    async def __aenter__(self) -> Self:
+        await self.client.__aenter__()
+        return self
+
+    async def __aexit__(
+        self,
+        typ: t.Optional[t.Type[BaseException]],
+        exc: t.Optional[BaseException],
+        tb: t.Optional[TracebackType],
+    ) -> None:
+        await self.client.__aexit__(typ, exc, tb)

faceit/_repr.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import typing as t
+
+if t.TYPE_CHECKING:
+    from ._typing import TypeAlias
+
+_ReprMethod: TypeAlias = t.Callable[[], str]
+_ClassT = t.TypeVar("_ClassT", bound=t.Type)
+
+_UNINITIALIZED_MARKER: t.Final = "uninitialized"
+
+
+def _format_fields(
+    obj: t.Any, fields: t.Tuple[str, ...], joiner: str = " ", /
+) -> str:
+    return (
+        joiner.join(f"{field}={getattr(obj, field)!r}" for field in fields)
+        if all(hasattr(obj, field) for field in fields)
+        else repr(_UNINITIALIZED_MARKER)
+    )
+
+
+def _apply_representation(
+    cls: _ClassT, fields: t.Tuple[str, ...], use_str: bool, /
+) -> _ClassT:
+    has_str = getattr(cls, "__str__", None) is not object.__str__
+
+    if use_str and not has_str:
+        raise TypeError(f"Class {cls.__name__} must define __str__ method")
+
+    def repr_(self: _ClassT) -> str:
+        str_args = (
+            f"'{self}'" if use_str else _format_fields(self, fields, ", ")
+        )
+        return f"{cls.__name__}({str_args})"
+
+    def str_(self: _ClassT) -> str:
+        return _format_fields(self, fields)
+
+    cls.__repr__ = t.cast(_ReprMethod, repr_)
+    if not has_str:
+        cls.__str__ = t.cast(_ReprMethod, str_)
+
+    return cls
+
+
+def representation(
+    *fields: str, use_str: bool = False
+) -> t.Callable[[_ClassT], _ClassT]:
+    def decorator(cls: _ClassT) -> _ClassT:
+        return _apply_representation(cls, fields, use_str)
+
+    return decorator

faceit/_resources/__init__.py

@@ -0,0 +1,105 @@
+import typing as t
+from abc import ABC
+from dataclasses import dataclass
+from functools import cached_property
+
+from faceit._typing import ClientT, Model, Raw
+from faceit.http import AsyncClient, SyncClient
+
+from ._base import BaseResource
+from ._championships import (
+    AsyncChampionships,
+    BaseChampionships,
+    SyncChampionships,
+)
+from ._matches import AsyncMatches, BaseMatches, SyncMatches
+from ._pagination import (
+    AsyncPageIterator,
+    BasePageIterator,
+    CollectReturnFormat,
+    SyncPageIterator,
+    TimestampPaginationConfig,
+    check_pagination_support,
+)
+from ._players import AsyncPlayers, BasePlayers, SyncPlayers
+
+__all__ = (
+    "AsyncChampionships",
+    "AsyncMatches",
+    "AsyncPageIterator",
+    "AsyncPlayers",
+    "AsyncResources",
+    "BaseChampionships",
+    "BaseMatches",
+    "BasePageIterator",
+    "BasePlayers",
+    "BaseResource",
+    "BaseResources",
+    "CollectReturnFormat",
+    "SyncChampionships",
+    "SyncMatches",
+    "SyncPageIterator",
+    "SyncPlayers",
+    "SyncResources",
+    "TimestampPaginationConfig",
+    "check_pagination_support",
+)
+
+
+@dataclass(eq=False, frozen=True)
+class BaseResources(t.Generic[ClientT], ABC):
+    _client: ClientT
+
+
+@t.final
+class SyncResources(BaseResources[SyncClient]):
+    @cached_property
+    def raw_championships(self) -> SyncChampionships[Raw]:
+        return SyncChampionships(self._client, raw=True)
+
+    @cached_property
+    def championships(self) -> SyncChampionships[Model]:
+        return SyncChampionships(self._client, raw=False)
+
+    @cached_property
+    def raw_matches(self) -> SyncMatches[Raw]:
+        return SyncMatches(self._client, raw=True)
+
+    @cached_property
+    def matches(self) -> SyncMatches[Model]:
+        return SyncMatches(self._client, raw=False)
+
+    @cached_property
+    def raw_players(self) -> SyncPlayers[Raw]:
+        return SyncPlayers(self._client, raw=True)
+
+    @cached_property
+    def players(self) -> SyncPlayers[Model]:
+        return SyncPlayers(self._client, raw=False)
+
+
+@t.final
+class AsyncResources(BaseResources[AsyncClient]):
+    @cached_property
+    def raw_championships(self) -> AsyncChampionships[Raw]:
+        return AsyncChampionships(self._client, raw=True)
+
+    @cached_property
+    def championships(self) -> AsyncChampionships[Model]:
+        return AsyncChampionships(self._client, raw=False)
+
+    @cached_property
+    def raw_matches(self) -> AsyncMatches[Raw]:
+        return AsyncMatches(self._client, raw=True)
+
+    @cached_property
+    def matches(self) -> AsyncMatches[Model]:
+        return AsyncMatches(self._client, raw=False)
+
+    @cached_property
+    def raw_players(self) -> AsyncPlayers[Raw]:
+        return AsyncPlayers(self._client, raw=True)
+
+    @cached_property
+    def players(self) -> AsyncPlayers[Model]:
+        return AsyncPlayers(self._client, raw=False)

faceit/_resources/_base.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import logging
+import typing as t
+from abc import ABC
+from dataclasses import dataclass
+from warnings import warn
+
+from pydantic import ValidationError
+from strenum import StrEnum
+
+from faceit._typing import (
+    ClientT,
+    ModelT,
+    NotRequired,
+    RawAPIPageResponse,
+    RawAPIResponse,
+)
+from faceit.http import Endpoint
+from faceit.models import ItemPage
+
+from ._pagination import (
+    AsyncPageIterator,
+    SyncPageIterator,
+    TimestampPaginationConfig,
+)
+
+if t.TYPE_CHECKING:
+    _ResponseT = t.TypeVar("_ResponseT", bound=RawAPIResponse)
+
+_logger = logging.getLogger(__name__)
+
+_KT = t.TypeVar("_KT")
+
+# Temporary placeholder type for unimplemented models.
+# Serves as a stub during development and should be replaced with
+# concrete models as implementation progresses.
+ModelPlaceholder: None = None
+
+
+@t.final
+class RequestPayload(t.TypedDict):
+    endpoint: Endpoint
+    params: t.Dict[str, t.Any]
+
+
+@t.final
+class MappedValidatorConfig(t.TypedDict, t.Generic[_KT, ModelT]):
+    validator_map: t.Dict[_KT, t.Type[ModelT]]
+    is_paged: bool
+    key_name: NotRequired[str]
+
+
+@t.final
+class FaceitResourcePath(StrEnum):
+    CHAMPIONSHIPS = "championships"
+    MATCHES = "matches"
+    PLAYERS = "players"
+
+
+@dataclass(eq=False, frozen=True)
+class BaseResource(t.Generic[ClientT], ABC):
+    __slots__ = "_client", "raw"
+
+    _client: ClientT
+    raw: bool
+
+    _sync_page_iterator: t.ClassVar = SyncPageIterator
+    _async_page_iterator: t.ClassVar = AsyncPageIterator
+    _timestamp_cfg: t.ClassVar = TimestampPaginationConfig
+
+    PATH: t.ClassVar[Endpoint]
+
+    _PARAM_NAME_MAP: t.ClassVar = {
+        "start": "from",
+        "category": "type",
+    }
+
+    def __init_subclass__(
+        cls,
+        *,
+        resource_path: t.Optional[FaceitResourcePath] = None,
+        **kwargs: t.Any,
+    ) -> None:
+        super().__init_subclass__(**kwargs)
+        if hasattr(cls, "PATH"):
+            return
+        if resource_path is None:
+            raise TypeError(
+                f"Class {cls.__name__} requires 'path' parameter or a "
+                f"parent with 'PATH' defined."
+            )
+        cls.PATH = Endpoint(resource_path)
+
+    # NOTE: These overloads are necessary as this function directly returns in resource
+    # methods, where typing must be strict for public API. Current implementation
+    # is sufficient, though alternative typing approaches could be considered.
+
+    # TODO: Replace named arguments with a single `config: MappedValidatorConfig`
+    # parameter, but this is currently not possible due to Python 3.8 compatibility
+    # issues with Generic type subscriptions. Once Python 3.8 support is dropped,
+    # this should be refactored.
+
+    @t.overload
+    def _process_response_with_mapped_validator(
+        self,
+        response: RawAPIPageResponse,
+        key: _KT,
+        /,
+        *,
+        validator_map: t.Dict[_KT, t.Type[ModelT]],
+        is_paged: t.Literal[False],
+        key_name: str = ...,
+    ) -> t.Union[ModelT, RawAPIPageResponse]: ...
+
+    @t.overload
+    def _process_response_with_mapped_validator(
+        self,
+        response: RawAPIPageResponse,
+        key: _KT,
+        /,
+        *,
+        validator_map: t.Dict[_KT, t.Type[ModelT]],
+        is_paged: t.Literal[True],
+        key_name: str = ...,
+    ) -> t.Union[ItemPage[ModelT], RawAPIPageResponse]: ...
+
+    def _process_response_with_mapped_validator(
+        self,
+        response: RawAPIPageResponse,
+        key: _KT,
+        /,
+        *,
+        validator_map: t.Dict[_KT, t.Type[ModelT]],
+        is_paged: bool,
+        key_name: str = "key",
+    ) -> t.Union[ModelT, ItemPage[ModelT], RawAPIPageResponse]:
+        _logger.debug(
+            "Processing response with mapped validator for key: %s", key
+        )
+
+        validator = validator_map.get(key)
+        if validator is None:
+            warn(
+                f"No model defined for {key_name} '{key}'. "
+                f"Consider using the raw response.",
+                UserWarning,
+                stacklevel=3,
+            )
+            return response
+
+        # Suppressing type checking warning because we're using a
+        # dynamic runtime subscript `ItemPage` is being subscripted
+        # with a variable (`validator`) which mypy cannot statically verify
+        return self._validate_response(
+            response,
+            t.cast(t.Type[ModelT], ItemPage[validator])  # type: ignore[valid-type]
+            if is_paged
+            else validator,
+        )
+
+    def _validate_response(
+        self,
+        response: _ResponseT,
+        validator: t.Optional[t.Type[ModelT]],
+        /,
+    ) -> t.Union[_ResponseT, ModelT]:
+        if validator is not None and not self.raw:
+            try:
+                return validator.model_validate(response)
+            except ValidationError:
+                _logger.exception(
+                    "Response validation failed for %s model",
+                    validator.__name__,
+                )
+        return response
+
+    @classmethod
+    def _build_params(cls, **params: t.Any) -> t.Dict[str, t.Any]:
+        return {
+            cls._PARAM_NAME_MAP.get(key, key): value
+            for key, value in params.items()
+            if value is not None
+        }