Events¶

class EventNamespace:
    """Top-level namespace for event/tournament data.

    Access sub-namespaces for info, stages, teams, matches, standings,
    and event listings. Use ``vlrdevapi.event(event_id)`` for curried access.

    Quick start::

        info = vlrdevapi.event.info(event_id=123)
        matches = vlrdevapi.event(123).matches(state="upcoming")
        standings = vlrdevapi.event(123).standings(stage="group_a")
        listings = vlrdevapi.event.list(tier="vct", region="emea")
    """

    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 = EventInfoNamespace(client, timeout, retry_config, rate_limiter, extra_headers, source_tz=source_tz)
        self._stages = EventStagesNamespace(client, timeout, retry_config, rate_limiter, extra_headers, source_tz=source_tz)
        self._teams = EventTeamsNamespace(client, timeout, retry_config, rate_limiter, extra_headers, source_tz=source_tz)
        self._matches = EventMatchesNamespace(client, timeout, retry_config, rate_limiter, extra_headers, source_tz=source_tz)
        self._standings = EventStandingsNamespace(client, timeout, retry_config, rate_limiter, extra_headers, source_tz=source_tz)
        self._list = EventListNamespace(client, timeout, retry_config, rate_limiter, extra_headers, source_tz=source_tz)

    @property
    def info(self) -> EventInfoNamespace:
        """Access event info: name, dates, location, prize pool, tier.

        Usage::

            info = vlrdevapi.event.info(event_id=123)

        Returns:
            An ``EventInfoNamespace`` instance. Call with an ``event_id``
            to fetch and return an ``EventInfo`` model.

        """
        return self._info

    @property
    def stages(self) -> EventStagesNamespace:
        """Access stage information for an event.

        Usage::

            stages = vlrdevapi.event.stages(event_id=123)

        Returns:
            An ``EventStagesNamespace`` instance. Call with an ``event_id``
            to fetch and return an ``EventStages`` model.

        """
        return self._stages

    @property
    def teams(self) -> EventTeamsNamespace:
        """Access teams participating in an event.

        Usage::

            teams = vlrdevapi.event.teams(event_id=123, stage="playoffs")

        Returns:
            An ``EventTeamsNamespace`` instance. Call with an ``event_id``
            and optional ``stage`` to return an ``EventTeams`` model.

        """
        return self._teams

    @property
    def matches(self) -> EventMatchesNamespace:
        """Access matches for an event.

        Usage::

            matches = vlrdevapi.event.matches(event_id=123, state="upcoming")

        Returns:
            An ``EventMatchesNamespace`` instance. Call with an ``event_id``
            and optional filters to return an ``EventMatches`` model.

        """
        return self._matches

    @property
    def standings(self) -> EventStandingsNamespace:
        """Access standings for an event.

        Usage::

            standings = vlrdevapi.event.standings(event_id=123, stage="group_a")

        Returns:
            An ``EventStandingsNamespace`` instance. Call with an ``event_id``
            and optional ``stage`` to return an ``EventStandings`` model.

        """
        return self._standings

    @property
    def list(self) -> EventListNamespace:
        """Access event listings with optional filters.

        Usage::

            listings = vlrdevapi.event.list(tier="vct", region="emea")

        Returns:
            An ``EventListNamespace`` instance. Call with optional filters
            (``tier``, ``region``, ``status``) to return an ``EventList`` model.

        """
        return self._list

    @sanitize_and_validate
    def __call__(self, event_id: int) -> EventMatchNamespace:
        """Create a curried namespace bound to a specific event.

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

        Args:
            event_id: The unique event identifier on vlr.gg.

        Returns:
            EventMatchNamespace: A namespace object with methods ``.info()``,
            ``.stages()``, ``.teams()``, ``.matches()``, and
            ``.standings()`` — all pre-bound to the given ``event_id``.

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

        Examples:
            >>> ns = vlrdevapi.event(123)
            >>> ns.info().name
            'VCT Masters Tokyo'
            >>> ns.matches(state="upcoming").matches[0].stage
            'Playoffs'

        """
        return EventMatchNamespace(
            event_id=event_id,
            info=self._info,
            stages=self._stages,
            teams=self._teams,
            matches=self._matches,
            standings=self._standings,
        )