falcon_alliance.ApiClient

class falcon_alliance.ApiClient(api_key: str | None = None, auth_secret: str = '')

Base class that contains all requests to the TBA API.

Examples

If your API key isn’t defined in your .env as TBA_API_KEY or API_KEY:

>>> with ApiClient(api_key=your_api_key) as api_client:
...     print(api_client.team(4099).key)
frc4099

otherwise if it is:

>>> with ApiClient() as api_client:
...     print(api_client.team(4099).key)
frc4099

All code, regardless of if it uses ApiClient’s methods or not must be in this context manager. For example:

>>> with ApiClient():
...     print(Team(4099).event("2022iri", matches=True, keys=True))
["2022iri_f1m1", "2022iri_f1m2", ...]

close() → None: Closes the ongoing session (aiohttp.ClientSession).

districts(year: int) → List[District]

Retrieves all FRC districts during a year.

Parameters:: year (int) – An integer representing the year to retrieve its FRC districts from.
Returns:: A list of District objects with each object representing an active district of that year.
Return type:: List[falcon_alliance.District]

event(event_key: str, simple: bool = False) → Event

Retrieves and returns a record of teams based on the parameters given.

Parameters:

event_key (str) – A string representing a unique key assigned to an event to set it apart from others.
simple (bool) – A boolean that specifies whether the results for the event should be ‘shortened’ and only contain more relevant information.

Returns:

An Event object representing the data given.

Return type:

falcon_alliance.Event

events(year: range | int, simple: bool = False, keys: bool = False) → List[str | Event]

Retrieves all the events from certain year(s).

Parameters:

year (int, range) – An integer representing which year to return its events for o range object representing all the years events should be returned from.
simple (bool) – A boolean representing whether some of the information regarding an event should be stripped to only contain relevant information about the event.
keys (bool) – A boolean representing whether only the keys of the events should be returned.

Returns:

A list of Event objects representing each event in certain year(s) or a list of strings representing all the keys of the events retrieved.

Return type:

List[Union[falcon_alliance.Event, str]]

match(match_key: str, simple: bool = False, timeseries: bool = False, zebra_motionworks: bool = False) → List[dict] | Match | ZebraMotionworks | None

Retrieves information about a match.

Per TBA, the timeseries data is in development and therefore you should NOT rely on it.

Parameters:

match_key (str) – A string representing a unique key assigned to a match to set it apart from others.
simple (bool) – A boolean that specifies whether the results for each match should be ‘shortened’ and only contain more relevant information.
timeseries (bool) – A boolean that specifies whether match timeseries data should be retrieved from a match.
zebra_motionworks (bool) – A boolean that specifies whether data about where robots went during a match should be retrieved. Using this parameter, there may be no data due to the fact that very few matches use the Zebra MotionWorks technology required to get data on where the robots go during a match.

Returns:

A Match object containing information about the match or a Match.ZebraMotionworks object representing data about where teams’ robots went during the match (may not have any data for all teams or even data altogether and if so will return None) or a list of dictionaries containing timeseries data for a match.

Return type:

Optional[Union[List[dict], falcon_alliance.Match, falcon_alliance.Match.ZebraMotionworks]]

status() → APIStatus

Retrieves information about TBA’s API status.

Returns:: An APIStatus object containing information about TBA’s API status.
Return type:: falcon_alliance.APIStatus

team(team_key: int | str, simple: bool = False) → Team

Retrieves and returns a record of teams based on the parameters given.

Parameters:

team_key (int, str) – A string representing a unique key assigned to a team to set it apart from others (in the form of frcXXXX) where XXXX is the team number or an integer representing the team number of a team.
simple (bool) – A boolean that specifies whether the results for the team should be ‘shortened’ and only contain more relevant information.

Returns:

A Team object representing the data given.

Return type:

falcon_alliance.Team

teams(page_num: int = None, year: range | int = None, simple: bool = False, keys: bool = False) → List[Team | str]

Retrieves and returns a record of teams based on the parameters given.

Parameters:

page_num (int, optional) – An integer that specifies the page number of the list of teams that should be retrieved. Teams are paginated by groups of 500, and if page_num is None, every team will be retrieved.
year (int, range, optional) – An integer that specifies if only the teams that participated during that year should be retrieved. If year is a range object, it will return all teams that participated in the years within the range object. If year isn’t passed in, this method will get all teams that have ever participated in the history of FRC.
simple (bool) – A boolean that specifies whether the results for each team should be ‘shortened’ and only contain more relevant information.
keys (bool) – A boolean that specifies whether only the names of the FRC teams should be retrieved.

Returns:

A list of Team objects for each team in the list or a list of strings each representing a team’s key.

Return type:

List[Union[falcon_alliance.Team, str]]