{"id":15019156,"url":"https://github.com/team4099/falconalliance","last_synced_at":"2025-10-24T05:31:09.260Z","repository":{"id":57814429,"uuid":"527367403","full_name":"team4099/FalconAlliance","owner":"team4099","description":"A Pythonic library that attains FRC-related information from sources like The Blue Alliance and more.","archived":false,"fork":false,"pushed_at":"2023-03-11T03:14:05.000Z","size":421,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-30T23:51:12.174Z","etag":null,"topics":["first-frc","first-robotics-competition","frc","tba","tba-api","thebluealliance"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/team4099.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-08-22T01:04:55.000Z","updated_at":"2024-07-03T04:54:43.000Z","dependencies_parsed_at":"2023-01-22T17:15:10.704Z","dependency_job_id":null,"html_url":"https://github.com/team4099/FalconAlliance","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/team4099%2FFalconAlliance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/team4099%2FFalconAlliance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/team4099%2FFalconAlliance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/team4099%2FFalconAlliance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/team4099","download_url":"https://codeload.github.com/team4099/FalconAlliance/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237918710,"owners_count":19387305,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["first-frc","first-robotics-competition","frc","tba","tba-api","thebluealliance"],"created_at":"2024-09-24T19:53:05.179Z","updated_at":"2025-10-24T05:31:08.764Z","avatar_url":"https://github.com/team4099.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FalconAlliance\n### A Pythonic wrapper around TBA and other FRC data sources at your convenience. You can find the documentation [here](https://falcon-alliance.readthedocs.io/en/latest).\n\n\u003chr\u003e\n\n## Installation\n\nTo install `falcon-alliance`, run the following in your console:\n```console\n(.venv) $ pip install falcon-alliance\n```\n\nIf the following doesn't work, and you get an error regarding pip not being a command, try one of the following below:\n```console\n(.venv) $ python -m pip install falcon-alliance\n```\n```console\n(.venv) $ python3 -m pip install falcon-alliance\n```\n```console\n(.venv) $ python3.\u003cyour_version\u003e -m pip install falcon-alliance\n```\n\n## Setup\n\nOnce you have `falcon-alliance` installed, a basic skeleton of FalconAlliance code is \n```py\nimport falcon_alliance\n\nwith falcon_alliance.ApiClient(api_key=YOUR_API_KEY) as api_client:\n  # Code using the API client here\n```\n\u003csup\u003e For more information about the building block of FalconAlliance code, check out [this section](https://falcon-alliance.readthedocs.io/en/latest/getting_started/quick_start.html#building-block-of-falconalliance-code) of our documentation. \u003c/sup\u003e\n\nDo 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`. \n\nAs 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:\n```py\nimport falcon_alliance\n\nwith falcon_alliance.ApiClient(api_key=YOUR_API_KEY) as api_client:\n  all_teams = api_client.teams(year=2022)\n```\n\u003csup\u003e For more examples with the building block, check out the [Common Tasks](https://falcon-alliance.readthedocs.io/en/latest/getting_started/quick_start.html#common-tasks) section and the [Examples](https://falcon-alliance.readthedocs.io/en/latest/getting_started/examples.html) section.\n\n## Structure\nThe 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. \n\nIn 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:\n  - `Team.events`, which wraps around the `/team/{team_key}/events` endpoint.\n  - `Event.teams`, which wraps around the `/event/{event_key}/teams` endpoint.\n  - `District.rankings`, which wraps around the `/district/{district_key}/rankings` endpoint.\n\nAt 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`.\n\n## Plotting\nFalconAlliance 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](https://github.com/team4099/FalconAlliance/blob/main/PLOTTING.md).**\n\n## Examples\n### [Creating a Dictionary Containing how many Teams each State has](https://falcon-alliance.readthedocs.io/en/latest/getting_started/examples.html#creating-a-dictionary-containing-how-many-teams-each-state-has)\n```py\nimport falcon_alliance\n\nstates_to_teams = {}\n\nwith falcon_alliance.ApiClient(api_key=YOUR_API_KEY) as api_client:\n   all_teams = api_client.teams(year=2022)\n\n   for team in all_teams:\n       states_to_teams[team.state_prov] = states_to_teams.get(team.state_prov, 0) + 1\n```\n### [Getting the Average Rookie Year of Teams in a District](https://falcon-alliance.readthedocs.io/en/latest/getting_started/examples.html#getting-the-average-rookie-year-of-teams-in-a-district)\n```py\nimport falcon_alliance\n\nwith falcon_alliance.ApiClient(api_key=YOUR_API_KEY) as api_client:\n    team4099 = falcon_alliance.Team(4099)\n\n    # Suggested way\n    match_with_max_score = team4099.max(2022, metric=falcon_alliance.Metrics.MATCH_SCORE)\n    maximum_score = match_with_max_score.alliance_of(team4099).score\n\n    # Alternative way\n    match_scores = []\n\n    for match in team4099.matches(year=2022):\n        match_scores.append(match.alliance_of(team4099).score)\n\n    maximum_match_score = max(match_scores)\n```\n### [Finding the Maximum Score from all the Matches a Team Played During a Year](https://falcon-alliance.readthedocs.io/en/latest/getting_started/examples.html#finding-the-maximum-score-from-all-the-matches-a-team-played-during-a-year)\n```py\nimport falcon_alliance\n\nwith falcon_alliance.ApiClient(api_key=YOUR_API_KEY) as api_client:\n    team4099 = falcon_alliance.Team(4099)\n\n    # Suggested way\n    match_with_max_score = team4099.max(2022, metric=falcon_alliance.Metrics.MATCH_SCORE)\n    maximum_score = match_with_max_score.alliance_of(team4099).score\n\n    # Alternative way\n    match_scores = []\n\n    for match in team4099.matches(year=2022):\n        match_scores.append(match.alliance_of(team4099).score)\n\n    maximum_match_score = max(match_scores)\n```\n\n**More examples are listed on the documentation [here](https://falcon-alliance.readthedocs.io/en/latest/getting_started/examples.html#examples).**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteam4099%2Ffalconalliance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fteam4099%2Ffalconalliance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteam4099%2Ffalconalliance/lists"}