Skip to content

A Pythonic library that attains FRC-related information from sources like The Blue Alliance and more.

License

Notifications You must be signed in to change notification settings

team4099/FalconAlliance

Repository files navigation

FalconAlliance

A Pythonic wrapper around TBA and other FRC data sources at your convenience. You can find the documentation here.


Installation

To install falcon-alliance, run the following in your console:

(.venv) $ pip install falcon-alliance

If the following doesn't work, and you get an error regarding pip not being a command, try one of the following below:

(.venv) $ python -m pip install falcon-alliance
(.venv) $ python3 -m pip install falcon-alliance
(.venv) $ python3.<your_version> -m pip install falcon-alliance

Setup

Once you have falcon-alliance installed, a basic skeleton of FalconAlliance code is

import falcon_alliance

with falcon_alliance.ApiClient(api_key=YOUR_API_KEY) as api_client:
  # Code using the API client here

For more information about the building block of FalconAlliance code, check out this section of our documentation.

Do note that passing in the API key is not required if the API key is already stored in your .env file under the name TBA_API_KEY or API_KEY.

As for the code within the context manager (the with statement), below is an example of retrieving a list of all the teams that played in 2022 via FalconAlliance:

import falcon_alliance

with falcon_alliance.ApiClient(api_key=YOUR_API_KEY) as api_client:
  all_teams = api_client.teams(year=2022)

For more examples with the building block, check out the Common Tasks section and the Examples section.

Structure

The structure of FalconAlliance code follows a hierarchy, with ApiClient being at the top, containing agnostic methods like getting a list of all teams from a certain year, a list of all events from a certain year, etc.

In the middle of the hierarchy are schemas with methods in them, containing endpoints depending on a certain team/event/district. Team, Event, and District, which wrap around endpoints that depend on a certain key (team key/event key/district key). An example of a method for each of the following classes are:

  • Team.events, which wraps around the /team/{team_key}/events endpoint.
  • Event.teams, which wraps around the /event/{event_key}/teams endpoint.
  • District.rankings, which wraps around the /district/{district_key}/rankings endpoint.

At the bottom of the hierarchy are schemas which primarily act as data-classes, and are there as a means of communicating data in a readable format rather than having functionality. The classes at the bottom of the hierarchy are: Award, EventTeamStatus, Match, Media, and Robot.

Plotting

FalconAlliance has a plotting feature that makes on-the-fly visualizations for you based on your data. You can learn more about the plotting feature here.

Examples

import falcon_alliance

states_to_teams = {}

with falcon_alliance.ApiClient(api_key=YOUR_API_KEY) as api_client:
   all_teams = api_client.teams(year=2022)

   for team in all_teams:
       states_to_teams[team.state_prov] = states_to_teams.get(team.state_prov, 0) + 1
import falcon_alliance

with falcon_alliance.ApiClient(api_key=YOUR_API_KEY) as api_client:
    team4099 = falcon_alliance.Team(4099)

    # Suggested way
    match_with_max_score = team4099.max(2022, metric=falcon_alliance.Metrics.MATCH_SCORE)
    maximum_score = match_with_max_score.alliance_of(team4099).score

    # Alternative way
    match_scores = []

    for match in team4099.matches(year=2022):
        match_scores.append(match.alliance_of(team4099).score)

    maximum_match_score = max(match_scores)
import falcon_alliance

with falcon_alliance.ApiClient(api_key=YOUR_API_KEY) as api_client:
    team4099 = falcon_alliance.Team(4099)

    # Suggested way
    match_with_max_score = team4099.max(2022, metric=falcon_alliance.Metrics.MATCH_SCORE)
    maximum_score = match_with_max_score.alliance_of(team4099).score

    # Alternative way
    match_scores = []

    for match in team4099.matches(year=2022):
        match_scores.append(match.alliance_of(team4099).score)

    maximum_match_score = max(match_scores)

More examples are listed on the documentation here.

About

A Pythonic library that attains FRC-related information from sources like The Blue Alliance and more.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages