Players¶

class PlayerNamespace:
    """Top-level namespace for player data.

    Access sub-namespaces for info, teams, agents, match history, and
    consolidated profiles. Use ``vlrdevapi.player(player_id)`` for
    curried access.

    Quick start::

        info = vlrdevapi.player.info(player_id=11225)
        matches = vlrdevapi.player(11225).matches(limit=20)
        agents = vlrdevapi.player(11225).agents(timespan="60d")
        profile = vlrdevapi.player(11225).profile()
    """

    def __init__(
        self,
        client: httpx.Client,
        timeout: int = DEFAULT_TIMEOUT,
        retry_config: RetryConfig = DEFAULT_RETRY_CONFIG,
        rate_limiter: RateLimiter | None = None,
        extra_headers: dict[str, str] | None = None,
        source_tz: ZoneInfo | tzinfo | None = None,
    ):
        self._source_tz = source_tz
        self._info = PlayerInfoNamespace(client, timeout, retry_config, rate_limiter, extra_headers, source_tz=source_tz)
        self._teams = PlayerTeamsNamespace(client, timeout, retry_config, rate_limiter, extra_headers, source_tz=source_tz)
        self._agents = AgentsNamespace(client, timeout, retry_config, rate_limiter, extra_headers, source_tz=source_tz)
        self._matches = MatchesNamespace(client, timeout, retry_config, rate_limiter, extra_headers, source_tz=source_tz)
        self._profile = ProfileNamespace(client, timeout, retry_config, rate_limiter, extra_headers, source_tz=source_tz)

    @property
    def info(self) -> PlayerInfoNamespace:
        """Access basic player info.

        Usage::

            info = vlrdevapi.player.info(player_id=11225)

        Returns:
            PlayerInfoNamespace: A namespace instance. Call with a ``player_id``
            to fetch and return a ``PlayerInfo`` model.

        """
        return self._info

    @property
    def teams(self) -> PlayerTeamsNamespace:
        """Access current and past teams for a player.

        Usage::

            teams = vlrdevapi.player.teams(player_id=11225)

        Returns:
            PlayerTeamsNamespace: A namespace instance. Call with a ``player_id``
            to fetch and return a ``PlayerTeams`` model.

        """
        return self._teams

    @property
    def agents(self) -> AgentsNamespace:
        """Access agent statistics for a player.

        Usage::

            agents = vlrdevapi.player.agents(player_id=11225, timespan="60d")

        Returns:
            AgentsNamespace: A namespace instance. Call with a ``player_id``
            and optional ``timespan`` to return an ``AgentStatsPage`` model.

        """
        return self._agents

    @property
    def matches(self) -> "MatchesNamespace":
        """Access match history for a player.

        Usage::

            matches = vlrdevapi.player.matches(player_id=11225, limit=20)

        Returns:
            MatchesNamespace: A namespace instance. Call with a ``player_id``
            and optional ``limit`` to return a ``PlayerMatches`` model.

        """
        return self._matches

    @property
    def profile(self) -> ProfileNamespace:
        """Access consolidated profile for a player.

        Usage::

            profile = vlrdevapi.player.profile(player_id=11225)

        Returns:
            ProfileNamespace: A namespace instance. Call with a ``player_id``
            to fetch and return a ``PlayerProfile`` model.

        """
        return self._profile

    @sanitize_and_validate
    def __call__(self, player_id: int) -> PlayerMatchNamespace:
        """Create a curried namespace bound to a specific player.

        All subsequent calls on the returned object use ``player_id``
        automatically without needing to pass it each time.

        Args:
            player_id: The unique player identifier on vlr.gg.

        Returns:
            PlayerMatchNamespace: A namespace object with methods ``.info()``,
            ``.teams()``, ``.agents()``, ``.matches()``, and
            ``.profile()`` — all pre-bound to the given ``player_id``.

        Raises:
            ValidationError: If ``player_id`` is not a valid positive integer.

        Examples:
            >>> ns = vlrdevapi.player(11225)
            >>> ns.info().name
            'zekken'
            >>> ns.agents(timespan="60d").agents[0].name
            'Raze'

        """
        return PlayerMatchNamespace(
            player_id=player_id,
            info=self._info,
            teams=self._teams,
            agents=self._agents,
            matches=self._matches,
            profile=self._profile,
        )