Week

Week Class Documentation

Represents a week's worth of games for a league schedule.

Attributes:

Name	Type	Description
espn_instance	PYESPN	The ESPN API instance used to retrieve event data.
week_list	list[str]	A list of event URLs or event data references for the week.
week_number	int	The numerical representation of the week (e.g., Week 1, Week 2).
start_date	str	The start date of the week (ISO 8601 format or as provided).
end_date	str	The end date of the week (ISO 8601 format or as provided).
events	list[Event]	A list of Event instances corresponding to each game in the week.

Methods:

Name	Description
__repr__	Returns a string representation of the Week instance showing the week number.
get_events	Retrieves the list of Event instances for this week.
_set_week_data	(Legacy) Populates the events list sequentially by fetching data for each event.
_set_week_datav2	Populates the events list concurrently using threading for faster data fetching.
_fetch_event	str) -> Event: Fetches and returns a single Event instance given a URL.

Source code in pyespn/classes/schedule.py

class Week:
    """
    Represents a week's worth of games for a league schedule.

    Attributes:
        espn_instance (PYESPN): The ESPN API instance used to retrieve event data.
        week_list (list[str]): A list of event URLs or event data references for the week.
        week_number (int): The numerical representation of the week (e.g., Week 1, Week 2).
        start_date (str): The start date of the week (ISO 8601 format or as provided).
        end_date (str): The end date of the week (ISO 8601 format or as provided).
        events (list[Event]): A list of Event instances corresponding to each game in the week.

    Methods:
        __repr__() -> str:
            Returns a string representation of the Week instance showing the week number.

        get_events() -> list[Event]:
            Retrieves the list of Event instances for this week.

        _set_week_data() -> None:
            (Legacy) Populates the events list sequentially by fetching data for each event.

        _set_week_datav2() -> None:
            Populates the events list concurrently using threading for faster data fetching.

        _fetch_event(event_url: str) -> Event:
            Fetches and returns a single Event instance given a URL.
    """

    def __init__(self, espn_instance, week_list: list,
                 week_number: int, start_date, end_date):
        """
        Initializes a Week instance.

        Args:
            espn_instance (PyESPN): The primary ESPN API wrapper instance.
            week_list (list[str]): A list of event reference URLs (or identifiers) for games in the week.
            week_number (int): The numerical representation of the week (e.g., 1 for Week 1).
            start_date (str or datetime): The start date of the week.
            end_date (str or datetime): The end date of the week.
        """
        self._espn_instance = espn_instance
        self.week_list = week_list
        self._events = []
        self.week_number = None
        self.start_date = start_date
        self.end_date = end_date
        self.week_number = week_number

        self._set_week_datav2()

    @property
    def espn_instance(self):
        """
            PYESPN: the espn client instance associated with the class
        """
        return self._espn_instance

    @property
    def events(self):
        """
            list[Event]: a list of Event objects
        """
        return self._events

    def __repr__(self) -> str:
        """
        Returns a string representation of the week instance.

        Returns:
            str: A formatted string with the week.
        """
        return f"<Week | {self.week_number}>"

    def _set_week_data(self) -> None:
        """
        Populates the events list by fetching event data for the given week.
        """
        for event in self.week_list:
            event_content = fetch_espn_data(event)
            self._events.append(Event(event_json=event_content,
                                      espn_instance=self._espn_instance,
                                      load_game_odds=self._espn_instance.league.load_game_odds,
                                      load_play_by_play=self._espn_instance.league.load_game_play_by_play))

    def _set_week_datav2(self) -> None:
        """
        Populates the events list by fetching event data concurrently.

        Returns:
            None
        """
        with concurrent.futures.ThreadPoolExecutor() as executor:
            futures = {executor.submit(self._fetch_event, event): event for event in self.week_list}

            for future in concurrent.futures.as_completed(futures):
                try:
                    self._events.append(future.result())  # Append event when future is done
                except Exception as e:
                    print(f"Error fetching event: {e}")  # Handle failed API calls gracefully

    def _fetch_event(self, event_url):
        """
        Fetches event data from the given URL.

        Args:
            event_url (str): The event URL.

        Returns:
            Event: An Event instance.
        """
        event_content = fetch_espn_data(event_url)
        return Event(event_json=event_content,
                     espn_instance=self._espn_instance,
                     load_game_odds=self._espn_instance.league.load_game_odds,
                     load_play_by_play=self._espn_instance.league.load_game_play_by_play)

    def get_events(self) -> list["Event"]:
        """
        Retrieves the list of Event instances for this week.

        Returns:
            list[Event]: A list of Event instances for the week.
        """
        return self._events

espn_instance property

PYESPN: the espn client instance associated with the class

events property

list[Event]: a list of Event objects

__init__(espn_instance, week_list, week_number, start_date, end_date)

Initializes a Week instance.

Parameters:

Name	Type	Description	Default
espn_instance	PyESPN	The primary ESPN API wrapper instance.	required
week_list	list[str]	A list of event reference URLs (or identifiers) for games in the week.	required
week_number	int	The numerical representation of the week (e.g., 1 for Week 1).	required
start_date	str or datetime	The start date of the week.	required
end_date	str or datetime	The end date of the week.	required

Source code in pyespn/classes/schedule.py

def __init__(self, espn_instance, week_list: list,
             week_number: int, start_date, end_date):
    """
    Initializes a Week instance.

    Args:
        espn_instance (PyESPN): The primary ESPN API wrapper instance.
        week_list (list[str]): A list of event reference URLs (or identifiers) for games in the week.
        week_number (int): The numerical representation of the week (e.g., 1 for Week 1).
        start_date (str or datetime): The start date of the week.
        end_date (str or datetime): The end date of the week.
    """
    self._espn_instance = espn_instance
    self.week_list = week_list
    self._events = []
    self.week_number = None
    self.start_date = start_date
    self.end_date = end_date
    self.week_number = week_number

    self._set_week_datav2()

__repr__()

Returns a string representation of the week instance.

Returns:

Name	Type	Description
str	str	A formatted string with the week.

Source code in pyespn/classes/schedule.py

def __repr__(self) -> str:
    """
    Returns a string representation of the week instance.

    Returns:
        str: A formatted string with the week.
    """
    return f"<Week | {self.week_number}>"

get_events()

Retrieves the list of Event instances for this week.

Returns:

Type	Description
list[Event]	list[Event]: A list of Event instances for the week.

Source code in pyespn/classes/schedule.py

def get_events(self) -> list["Event"]:
    """
    Retrieves the list of Event instances for this week.

    Returns:
        list[Event]: A list of Event instances for the week.
    """
    return self._events