HaloPy

travis coveralls

HaloPy is an abstraction layer for the Halo 5 REST API, and as such, it requires an API key from https://developer.haloapi.com/

Installation

pip install halopy or install from source

git clone https://github.com/maxpowa/halopy.git
cd halopy
pip install .

Documentation

Licensed under the Eiffel Forum License 2

class halopy.HaloPy(api_key, title='h5', cache=300, cache_backend='sqlite', rate=(10, 10), **backend_options)[source]

Bases: object

Primary abstraction class for HaloPy

Parameters:
  • api_key (str) – Halo API key.
  • title (Optional[str]) – Game title, presumably for forward compatibility.
  • cache (Optional[int]) – Seconds to cache API results, 0 indicates no cache.
  • cache_backend (Optional[obj]) – requests-cache supported backend. If unspecified, HaloPy will automatically generate a cache.sqlite file in the current working directory.
  • rate (Optional[tuple]) – Maximum rate limit in form (req, sec)
  • **backend_options – Options to pass to the requests-cache backend
api_key

str – Halo API key.

cache

int – Seconds to cache API results, 0 indicates no cache.

can_request()[source]

Check if we should be within our rate limits.

This is called before actually executing any request internally, so you aren’t required to check this yourself.

Returns:True if we are within the limit, False otherwise.
Return type:bool
get_arena_match_by_id(match_id)[source]

Get arena match details by match id.

See https://developer.haloapi.com/docs/services/560af163e2f7f710cc79e517/operations/5612e539e2f7f7334c177fb3 for more information on this endpoint.

Parameters:match_id (uid) – Match unique identifier
Returns:An object representing an arena match’s details
Return type:HaloPyResult
get_campaign_match_by_id(match_id)[source]

Get campaign match details by match id.

See https://developer.haloapi.com/docs/services/560af163e2f7f710cc79e517/operations/5612e539e2f7f7334c177fb4 for more information on this endpoint.

Parameters:match_id (uid) – Match unique identifier
Returns:An object representing a campaign match details
Return type:HaloPyResult
get_campaign_missions()[source]

Get a listing of campaign missions supported in the title.

See https://developer.haloapi.com/docs/services/560af0dae2f7f710cc79e516/operations/562d68f1e2f7f72764ff1f53 for more information on this endpoint.

Returns:List of campaign mission details
Return type:list[HaloPyResult]
get_commendations()[source]

Get a listing of commendations supported in the title.

See https://developer.haloapi.com/docs/services/560af0dae2f7f710cc79e516/operations/562d68f1e2f7f72764ff1f4e for more information on this endpoint.

Returns:List of commendation details
Return type:list[HaloPyResult]
get_csr_designations()[source]

Get a listing of CSR designations supported in the title.

See https://developer.haloapi.com/docs/services/560af0dae2f7f710cc79e516/operations/562d68f1e2f7f72764ff1f50 for more information on this endpoint.

Returns:List of CSR designation details
Return type:list[HaloPyResult]
get_custom_match_by_id(match_id)[source]

Get custom match details by match id.

See https://developer.haloapi.com/docs/services/560af163e2f7f710cc79e517/operations/5612e539e2f7f7334c177fb5 for more information on this endpoint.

Parameters:match_id (uid) – Match unique identifier
Returns:An object representing a custom match details
Return type:HaloPyResult
get_enemies()[source]

Get a listing of enemies supported in the title.

See https://developer.haloapi.com/docs/services/560af0dae2f7f710cc79e516/operations/562d68f1e2f7f72764ff1f49 for more information on this endpoint.

Returns:List of enemy details
Return type:list[HaloPyResult]
get_flexible_stats()[source]

Get a listing of flexible statistics supported in the title.

See https://developer.haloapi.com/docs/services/560af0dae2f7f710cc79e516/operations/562d68f1e2f7f72764ff1f43 for more information on this endpoint.

Returns:List of flexible statistic details
Return type:list[HaloPyResult]
get_game_base_variants()[source]

Get a listing of all game base variants supported in the title.

See https://developer.haloapi.com/docs/services/560af0dae2f7f710cc79e516/operations/562d68f1e2f7f72764ff1f45 for more information on this endpoint.

Returns:List of game base variant details
Return type:list[HaloPyResult]
get_game_variant_by_id(var_id)[source]

Get details for specified game variant id.

See https://developer.haloapi.com/docs/services/560af0dae2f7f710cc79e516/operations/562d68f1e2f7f72764ff1f46 for more information on this endpoint.

Parameters:var_id (uid) – Game variant unique identifier
Returns:Game variant details
Return type:HaloPyResult
get_impulses()[source]

Get list of supported impulses for the title. Impulses are essentially invisible medals, players receive them for performing virtually any action in the game.

See https://developer.haloapi.com/docs/services/560af0dae2f7f710cc79e516/operations/562d68f1e2f7f72764ff1f4f for more information on this endpoint.

Returns:List of impulse details
Return type:list[HaloPyResult]
get_map_variant_by_id(map_id)[source]

Get details for specified map variant id

See https://developer.haloapi.com/docs/services/560af0dae2f7f710cc79e516/operations/562d68f1e2f7f72764ff1f4c for more information on this endpoint.

Parameters:map_id (uid) – Unique identifier for the map
Returns:Map variant details
Return type:HaloPyResult
get_maps()[source]

Get list of supported maps in the title.

See https://developer.haloapi.com/docs/services/560af0dae2f7f710cc79e516/operations/562d68f1e2f7f72764ff1f44 for more information on this endpoint.

Returns:List of map details
Return type:list[HaloPyResult]
get_medals()[source]

Get list of supported medals in the title.

See https://developer.haloapi.com/docs/services/560af0dae2f7f710cc79e516/operations/562d68f1e2f7f72764ff1f47 for more information on this endpoint.

Returns:List of medal details
Return type:list[HaloPyResult]
get_player_emblem(player_gt, size=None)[source]

Get the emblem image for the given player gamertag.

See https://developer.haloapi.com/docs/services/56393773e2f7f718548921d7/operations/56393774e2f7f70ad8d46e9c for more information on this endpoint.

Parameters:
  • player_gt (str) – Player gamertag
  • size (Optional[int]) – Size of emblem image, must be one of the following values: 95, 128, 190, 256, 512. Default is 256.
Returns:

Response object containing the player’s emblem
Return type:

Response
get_player_matches(player_gt, modes=None, start=None, count=None)[source]

Get matches played by the given player

See https://developer.haloapi.com/docs/services/560af163e2f7f710cc79e517/operations/560af163e2f7f703f8349976 for more information on this endpoint.

Parameters:
  • player_gt (str) – Player gamertag
  • modes (Optional[str]) – Game mode(s) to show, if unspecified, all game modes will be included in the result set. You may specify multiple game modes by comma-delimiting the values.
  • start (Optional[int]) – Start index for batched results
  • count (Optional[int]) – Count of results to return. Minimum value is 1, maximum is 25. 25 is assumed if unspecified.
Returns:

A batched results object:: {

“Start”: int, “Count”: int, “ResultCount”: int, “Results” list

}
Return type:

HaloPyResult
get_player_service_record(player_gt, game_mode='campaign')[source]

Get service record for the given player

Parameters:
  • player_gt (str) – Player gamertag to get the service record for
  • game_mode (str) – Must be arena, warzone, custom, or campaign. Defaults to campaign.
Returns:

Player service record object
Return type:

HaloPyResult
get_player_spartan_image(player_gt, size=None, crop=None)[source]

Get the given player’s spartan image.

See https://developer.haloapi.com/docs/services/56393773e2f7f718548921d7/operations/56393774e2f7f70ad8d46e9b for more information on this endpoint.

Parameters:
  • player_gt (str) – Player gamertag
  • size (Optional[int]) – Size of spartan image, must be one of the following values: 95, 128, 190, 256, 512. Default is 256.
  • crop (Optional[str]) – Either full or portrait. If not specified, full is used.
Returns:

Response object containing the player’s spartan image
Return type:

Response
get_players_service_record(player_gts, game_mode='campaign')[source]

Get service records for the given list of player gamertags and the given mode

Parameters:
  • player_gts (List[str]) – List of player gamertags
  • game_mode (str) – Must be arena, warzone, custom, or campaign. Defaults to campaign.
Returns:

List of player service record objects
Return type:

list[HaloPyResult]
get_playlists()[source]

Get list of playlists available in the title.

See https://developer.haloapi.com/docs/services/560af0dae2f7f710cc79e516/operations/562d68f1e2f7f72764ff1f4b for more information on this endpoint.

Returns:List of playlist details
Return type:list[HaloPyResult]
get_requisition_by_id(req_id)[source]

Get details for a specific “REQ”

See https://developer.haloapi.com/docs/services/560af0dae2f7f710cc79e516/operations/562d68f1e2f7f72764ff1f51 for more information on this endpoint.

Parameters:req_id (uid) – Unique identifier string
Returns:“REQ” details
Return type:HaloPyResult
get_requisition_pack_by_id(req_pack_id)[source]

Get details for a specific “REQ” pack

See https://developer.haloapi.com/docs/services/560af0dae2f7f710cc79e516/operations/562d68f1e2f7f72764ff1f52 for more information on this endpoint.

Parameters:req_pack_id (uid) – Unique identifier string
Returns:“REQ” pack details
Return type:HaloPyResult
get_skulls()[source]

Get list of skulls supported in the title.

See https://developer.haloapi.com/docs/services/560af0dae2f7f710cc79e516/operations/562d68f1e2f7f72764ff1f54 for more information on this endpoint.

Returns:List of skull details
Return type:list[HaloPyResult]
get_spartan_ranks()[source]

Get list of spartan ranks supported in the title.

See https://developer.haloapi.com/docs/services/560af0dae2f7f710cc79e516/operations/562d68f1e2f7f72764ff1f4d for more information on this endpoint.

Returns:List of spartan rank details
Return type:list[HaloPyResult]
get_team_colors()[source]

Get list of supported team colors in the title.

See https://developer.haloapi.com/docs/services/560af0dae2f7f710cc79e516/operations/562d68f1e2f7f72764ff1f55 for more information on this endpoint.

Returns:List of team color details
Return type:list[HaloPyResult]
get_vehicles()[source]

Get list of supported vehicles in the title.

See https://developer.haloapi.com/docs/services/560af0dae2f7f710cc79e516/operations/562d68f1e2f7f72764ff1f4a for more information on this endpoint.

Returns:List of vehicle details
Return type:list[HaloPyResult]
get_warzone_match_by_id(match_id)[source]

Get warzone match details by match id.

See https://developer.haloapi.com/docs/services/560af163e2f7f710cc79e517/operations/5612e539e2f7f7334c177fb6 for more information on this endpoint.

Parameters:match_id (uid) – Match unique identifier
Returns:An object representing a warzone match details
Return type:HaloPyResult
get_weapons()[source]

Get list of supported weapons in the title.

See https://developer.haloapi.com/docs/services/560af0dae2f7f710cc79e516/operations/562d68f1e2f7f72764ff1f48 for more information on this endpoint.

Returns:List of weapon details
Return type:list[HaloPyResult]
meta_request(endpoint, params={}, headers={})[source]

Helper method for metadata requests

Prepends the endpoint with metadata/{title}/metadata/ where {title} is the game title.

Parameters:
  • endpoint (str) – The endpoint to send the request to
  • params (Optional[dict]) – Dictionary of key, value URL params
  • headers (Optional[dict]) – Dictionary of key, value request headers
Returns:

json-encoded content of a response, if any
profile_request(endpoint, params={}, headers={})[source]

Helper method for profile requests

Prepends the endpoint with profile/{title}/profiles/ where {title} is the game title.

Parameters:
  • endpoint (str) – The endpoint to send the request to
  • params (Optional[dict]) – Dictionary of key, value URL params
  • headers (Optional[dict]) – Dictionary of key, value request headers
Returns:

Requests Response object.
Return type:

Response
rate

tuple – Maximum rate limit in form (req, sec)

request(endpoint, params={}, headers={})[source]

Sends request to the Halo API servers.

API key header will automatically be attached if it’t not already specified. Endpoint will be prefixed with https://www.haloapi.com/ before the request is executed.

Retrieved values will be cached via cache method specified when initializing HaloPy. If the value is from the cache, we the request will not count towards our rate limit bucket.

Parameters:
  • endpoint (str) – The endpoint to send the request to
  • params (Optional[dict]) – Dictionary of key, value URL params
  • headers (Optional[dict]) – Dictionary of key, value request headers
Returns:

Requests Response object.
Return type:

Response
Raises:

HaloPyError – If we are over our rate limit, or if an HTTP error occurs.
stats_request(endpoint, params={}, headers={})[source]

Helper method for metadata requests

Prepends the endpoint with stats/{title}/ where {title} is the game title.

Parameters:
  • endpoint (str) – The endpoint to send the request to
  • params (Optional[dict]) – Dictionary of key, value URL params
  • headers (Optional[dict]) – Dictionary of key, value request headers
Returns:

json-encoded content of a response, if any
exception halopy.HaloPyError[source]

Bases: Exception

Standard HaloPy exception class

class halopy.HaloPyResult(wrap)[source]

Bases: object

Wrapper object for results from the Halo API

Parameters:wrap (dict) – Dictionary to wrap

Indices and tables