Teams¶

class TeamNamespace:
    """Top-level namespace for team data.

    Access sub-namespaces for info, roster, stats, matches, transactions,
    and placements. Use ``vlrdevapi.team(team_id)`` for curried access.

    Quick start::

        info = vlrdevapi.team.info(team_id=4568)
        stats = vlrdevapi.team(4568).stats(last_days=90)
        roster = vlrdevapi.team(4568).roster()
    """

    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 = TeamInfoNamespace(client, timeout, retry_config, rate_limiter, extra_headers, source_tz=source_tz)
        self._roster = TeamRosterNamespace(client, timeout, retry_config, rate_limiter, extra_headers, source_tz=source_tz)
        self._completed_matches = TeamCompletedMatchesNamespace(
            client, timeout, retry_config, rate_limiter, extra_headers, source_tz=source_tz,
        )
        self._upcoming_matches = TeamUpcomingMatchesNamespace(
            client, timeout, retry_config, rate_limiter, extra_headers, source_tz=source_tz,
        )
        self._transactions = TeamTransactionsNamespace(client, timeout, retry_config, rate_limiter, extra_headers, source_tz=source_tz)
        self._stats = TeamStatsNamespace(client, timeout, retry_config, rate_limiter, extra_headers, source_tz=source_tz)
        self._placements = TeamPlacementsNamespace(client, timeout, retry_config, rate_limiter, extra_headers, source_tz=source_tz)

    @property
    def info(self) -> TeamInfoNamespace:
        """Access team info: name, tag, country, logos, social links.

        Usage::

            info = vlrdevapi.team.info(team_id=4568)

        Returns:
            A ``TeamInfoNamespace`` instance. Call with a ``team_id``
            to fetch and return a ``TeamInfo`` model.

        """
        return self._info

    @property
    def roster(self) -> TeamRosterNamespace:
        """Access team roster: active players and staff.

        Usage::

            roster = vlrdevapi.team.roster(team_id=4568)

        Returns:
            A ``TeamRosterNamespace`` instance. Call with a ``team_id``
            to fetch and return a ``TeamRoster`` model.

        """
        return self._roster

    @property
    def completed_matches(self) -> TeamCompletedMatchesNamespace:
        """Access completed match history for a team.

        Usage::

            matches = vlrdevapi.team.completed_matches(team_id=4568)

        Returns:
            A ``TeamCompletedMatchesNamespace`` instance. Call with a
            ``team_id`` to fetch and return a ``TeamCompletedMatches`` model.

        """
        return self._completed_matches

    @property
    def upcoming_matches(self) -> TeamUpcomingMatchesNamespace:
        """Access upcoming matches for a team.

        Usage::

            matches = vlrdevapi.team.upcoming_matches(team_id=4568)

        Returns:
            A ``TeamUpcomingMatchesNamespace`` instance. Call with a
            ``team_id`` to fetch and return a ``TeamUpcomingMatches`` model.

        """
        return self._upcoming_matches

    @property
    def transactions(self) -> TeamTransactionsNamespace:
        """Access roster transactions (joins / leaves) for a team.

        Usage::

            txns = vlrdevapi.team.transactions(team_id=4568)

        Returns:
            A ``TeamTransactionsNamespace`` instance. Call with a
            ``team_id`` to fetch and return a ``TeamTransactions`` model.

        """
        return self._transactions

    @property
    def stats(self) -> TeamStatsNamespace:
        """Access map / agent statistics for a team.

        Usage::

            stats = vlrdevapi.team.stats(team_id=4568, last_days=90)

        Returns:
            A ``TeamStatsNamespace`` instance. Call with a ``team_id``
            and optional filters to return a ``TeamStats`` model.

        """
        return self._stats

    @property
    def placements(self) -> TeamPlacementsNamespace:
        """Access event placement history for a team.

        Usage::

            placements = vlrdevapi.team.placements(team_id=4568)

        Returns:
            A ``TeamPlacementsNamespace`` instance. Call with a
            ``team_id`` to fetch and return a ``TeamPlacements`` model.

        """
        return self._placements

    @sanitize_and_validate
    def __call__(self, team_id: int) -> TeamMatchNamespace:
        """Create a curried namespace bound to a specific team.

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

        Args:
            team_id: The unique team identifier on vlr.gg.

        Returns:
            TeamMatchNamespace: A namespace object with methods ``.info()``,
            ``.roster()``, ``.stats()``, ``.completed_matches()``,
            ``.upcoming_matches()``, ``.transactions()``, and
            ``.placements()`` — all pre-bound to the given ``team_id``.

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

        Examples:
            >>> ns = vlrdevapi.team(4568)
            >>> ns.info().name
            'Sentinels'
            >>> ns.stats(last_days=90).maps[0].win_rate
            66.7

        """
        return TeamMatchNamespace(
            team_id=team_id,
            info=self._info, roster=self._roster,
            completed_matches=self._completed_matches,
            upcoming_matches=self._upcoming_matches,
            transactions=self._transactions,
            stats=self._stats, placements=self._placements,
        )