frc1418 / tbapy Goto Github PK

View Code? Open in Web Editor NEW

48.0 6.0 16.0 85 KB

:chart_with_upwards_trend: Python wrapper for The Blue Alliance API.

License: MIT License

Python 100.00%

the-blue-alliance frc tba-api

tbapy's Introduction

tbapy

1418 TBA Libraries // Python // Go // Ruby

Python library for interfacing with The Blue Alliance API (v3).

Setup

First, install the module:

pip3 install tbapy

Then, to use these functions, you must import the tbapy module:

import tbapy

Before using the library, you must instantiate its class, for example:

tba = tbapy.TBA('key')

The Blue Alliance's API requires that all applications identify themselves with an auth key when retrieving data. To obtain an auth key, visit TBA's Account page.

Retrieval Functions

You may specify simple=True to get only vital data on some models or lists of models, or you may specify keys=True to get a list of the keys for a list rather than full data on each model. It is recommended to use these options if you do not need full data.

Some requests support year and other optional parameters, which are recommended to use to narrow down your results.

tba.status() - Get TBA's status.
tba.teams([page], [year], [simple/keys]) - Get a list of of valid teams, where page * 500 is the starting team number. If no page is provided, all teams will be fetched.
tba.team(team, [simple]) - Get a team's data. team can be an integer team number of a string-form 'frc####' identifier.
tba.team_events(team, [year], [simple/keys]) - Get a list of events a team has been to.
tba.team_awards(team, [event/year]) - Get a list of the team's awards.
tba.team_matches(team, [event/year], [simple/keys]) - Get a list of a team's matches at an event.
tba.team_years(team) - Get a list of years the team was active in FRC.
tba.team_media(team, [year], [tag]) - Get team media. Specify a year to get media from or a tag or both.
tba.team_robots(team) - Get data about a team's robots.
tba.team_districts(team) - Get the districts that a team has been part of over the years.
tba.team_profiles(team) - Get data on a team's media profiles.
tba.team_status(team, event) - Get a team's status at an event.
tba.events([year], [simple/keys]) - Get a list of all events.
tba.event(event, [simple]) - Get data about an event.
tba.event_rankings(event) - Gets a list of team rankings at a given event.
tba.event_alliances(event) - Get sophisticated data on alliances at a given event.
tba.event_district_points(event) - Get sophisticated data on district points at a given event.
tba.event_insights(event) - Get insight data on a given event.
tba.event_oprs(event) - Get sophisticated data on alliances at a given event.
tba.event_predictions(event) - Get predicted scores for a given event.
tba.event_teams(event, [simple/keys]) - Get a list of teams at an event.
tba.event_awards(event) - Get the awards from an event.
tba.event_matches(event, [simple/keys]) - Get a match list of an event.
tba.match([key], [year], [event], [type], [number], [round], [simple]) - Get data about a match. You may either pass the match's key directly, or pass year, event, type, match (the match number), and round if applicable (playoffs only). The event year may be specified as part of the event key or specified in the year parameter.
tba.districts(year) - Get a list of all districts that exist(ed) in a given year.
tba.district_events(district, [simple/keys]) - Get list of events in a district.
tba.district_rankings(district) - Get the rankings in a district.
tba.district_teams(district, [simple/keys]) - Get a list of the teams in a district.

See example.py for several usage examples.

Documentation for The Blue Alliance's API can be found here.

Write Functions

Writing to The Blue Alliance requires an additional set of tokens that can be obtained here.

Since each set of tokens is unique to an event you will have the instantiate the TBA class like so:

tba = tbapy.TBA('key', 'ID', 'secret', 'event_key')

or update an existing TBA object like so:

tba.update_trusted('ID', 'secret', 'event_key')

All of the write functions require data models that can be found here at the Write API documentation

tba.update_event_info(info) - Update the Event's info with the given dictionary.
tba.update_event_alliances(alliances) - Update the alliances. Input is a list of lists, 8 lists with the team names in frc#### format are expected.
tba.update_event_awards(awards) - Update the awards for an event with a list of dictionaries. Each dictionary must have a name_str key and optionally a team_key key in frc### format and/or an awardee key for an individual award.
tba.update_event_matches(rankings) - Update the matches of an event with a dictionary. Additional info can be found in the Write API Documentation on The Blue Alliance.
tba.delete_event_matches([matches]) - Delete all matches or the matches in the given list.
tba.update_event_rankings(rankings) - Update rankings of an event with a dictionary containing a breakdowns key and rankings key. Rankings key must have a list of dictionaries as the value.
tba.update_event_team_list(team_list) - Replace the event's team list with the list given.
tba.add_match_videos(match_videos) - Add YouTube videos to matches with a dictionary of partial match keys to YouTube video ids.
tba.add_event_videos(event_videos) - Add videos to the event's media tab on The Blue Alliance with a list of YouTube video ids.

Authors

This software was created and is maintained by Erik Boesen with Team 1418. Additional contributions made by Ian Weiss with Team 4131.

License

This software is protected under the MIT License.

tbapy's People

Contributors

Stargazers

Watchers

Forkers

tomorth samuelcouch nikhilnarayana 1124816 andrewlester mgfernanda cadandcookies fizzlebert jkim jjkoletar team5918-pumatrons richardmazur1 pchild ibanknatoprad belaw888 lessthantrue

tbapy's Issues

Pulling red or blue alliance data.

Hello. I'd like to use this API to pull data for either red alliance or blue alliance in a certain match?
I don't see where that's done anywhere in the documentation. If it's possible,could you point to a example?
Thanks.

Better error handling

When an error occurs, it's fairly difficult to figure out what went wrong (see #26).

The get/post methods should check the returned JSON for an 'errors' key, and if present raise an exception. The JSON returns something like this when an error is present:

{'Errors': [{'team_id': '294 is not a valid team id'}]}

Call to team_matches throws error

Here is the stacktrace that is printed when trying to call team_matches:

File "<stdin>", line 1, in <module>
File "C:\Python36\lib\site-packages\tbapy\main.py", line 139, in team_matches
  return [Match(raw) for raw in self.__get('team/%s/event/%s/matches%s' % (self.team_key(team), event, '/simple' if simple else''))]
File "C:\Python36\lib\site-packages\tbapy\main.py", line 139, in <listcomp>
  return [Match(raw) for raw in self.__get('team/%s/event/%s/matches%s' % (self.team_key(team), event, '/simple' if simple else''))]
File "C:\Python36\lib\site-packages\tbapy\models.py", line 3, in __init__
  self.update(json)
ValueError: dictionary update sequence element #0 has length 1; 2 is required

I am running this on a Windows 10 laptop, too.

Support If-Modified-Since headers in the APIs

The TBA API docs recommend using the If-Modified-Since header to save time in your application and reduce load on their servers. Are there currently any plans to implement this as part of tbapy?

Add support for event matches simple

The event_matches method supports getting just the keys for matches, but not the simple format as described on the TBA website.

Help - {'Error': 'Invalid endpoint'}

Hello, I'm trying to use this library, and I'm running into an issue. I'm wondering if I can come here for help.
It seems like I get {'Error': 'Invalid endpoint'} back anytime I pass an event as a parameter.

Here's what my code looks like.

tba = tbapy.TBA('key')

current_year = tba.status()["current_season"]
team_number = "frc4091"

team_events = tba.team_events(team=team_number, year=current_year)
for event in team_events:
    print("Week %s: %s" % (event["week"], event["name"]))  # prints Week 2: Orlando Regional
    print(tba.event_rankings(event=event))  # prints Rankings({'Error': 'Invalid endpoint'})
    print(tba.team_status(team=team_number, event=event))  # prints Status({'Error': 'Invalid endpoint'})

If someone could explain what's happening I'd appreciate it.

JSON subscription in example throws

Missing parentheses. When you add them in, there are further problems; it looks like a string is returned... weird.

Consider renaming `team_social_media()` to `team_profiles()`

I feel it would be a great deal cleaner, and also inclusive of all profiles. GitHub and debatably YouTube don't fall under the category of social in my opinion.

Support write APIs

event_predictions broken

The event_predictions function is broken. Running it returns an error of no object named Predictions.

In models.py, you have

Prediction = _model_class('Prediction')

this needs to be

Predictions = _model_class('Predictions')

Support Match Timeseries API

Reuse connections to TBA

Some new requests not implemented

I based the update to TBA API v3 off what seems to have been an incomplete version of that API. There are a couple requests which TBA has since implemented which this library doesn't support. I see the following missing features:

simple parameter for teams() (with and without year)
simple parameter for event_teams()
simple parameter for district_teams()
simple parameter for district_events()
simple parameter for team_events() (with and without year)
simple parameter for team_matches() (with and without year and event)
tag parameter for media requests
Team event status requests (endpoint /team/{team_key}/event/{event_key}/status)

District Teams Invalid Endpoint

The endpoint for district_teams should be district/{district_key}/teams not district/{district_key}/{year}/teams like it is now.

Didn't submit a PR since I wasn't sure if you'd prefer keeping parameters the same or changing them.

If you keep the current parameters and have "chs" as a valid district key for example, it might be good to specify that; I tried pretty much every permutation of values from this file before realizing why I was getting errors.

JSON of object should be generated dynamically

Currently, each class has a .json property holding a raw JSON dictionary version of all the object's data. This works alright, except that if you convert an object to JSON through json.dumps() or a similar method, all the object's data is duplicated inside the json property. For example:

json.dumps(tba.team(1418, simple=True))

yields the following JSON:

{
    "city": "Falls Church",
    "country": "USA",
    "key": "frc1418",
    "name": "(...)",
    "nickname": "Vae Victis",
    "state_prov": "Virginia",
    "team_number": 1418,
    "json": {
        "city": "Falls Church",
        "country": "USA",
        "key": "frc1418",
        "name": "(...)",
        "nickname": "Vae Victis",
        "state_prov": "Virginia",
        "team_number": 1418
    }
}

This is undesirable for obvious reasons. In addition, there's no sense in holding the JSON in memory when it will almost never be needed (and doesn't get updated if the user changes a property of the object).

A better solution would be to implement a method .json() of the base model, similar to how I did it in schoolopy, an API library similar to this one: https://github.com/ErikBoesen/schoolopy/blob/master/schoolopy/models.py#L11

Parameters are poorly ordered

Sometimes, keys & simple come after parameters like year, sometimes they come before. We should pick one and stick with it.

Use f"" strings

They might REALLY help in some places. Although note that this would break on <python37