Welcome to python-xbox’s documentation!¶

Contents:

Authentication¶

Authentication requires a valid login for an Xbox Live account.

You can either set the MS_LOGIN and MS_PASSWD environment variables in which case authentication will happen automatically when it’s required. If you’d prefer not to do that, call the authenticate() method with your credentials.

import xbox
xbox.client.authenticate('joe@example.org', 'password')

Resources¶

Objects that represent an API resource are locked away in here. Things such as gamer profile, games and clips.

class xbox.GamerProfile(xuid, settings, user_data)¶

Represents an xbox live user.

Variables:	xuid (string) – xuid of user gamertag (string) – gamertag of user gamerscore (string) – gamerscore of user gamerpic (string) – url for gamerpic of user

clips()¶

Gets the latest clips made by this user

Returns:	Iterator of `Clip` instances

classmethod from_gamertag(gamertag)¶

Instantiates an instance of GamerProfile from a gamertag

Parameters:	gamertag – Gamertag to look up
Raises:	`GamertagNotFound`
Returns:	`GamerProfile` instance

classmethod from_xuid(xuid)¶

Instantiates an instance of GamerProfile from an xuid

Parameters:	xuid – Xuid to look up
Raises:	`GamertagNotFound`
Returns:	`GamerProfile` instance

class xbox.Clip(user, clip_data)¶

Represents a single game clip.

Variables:

user – User that made the clip
clip_id (string) – Unique id of the clip
scid (string) – Unique SCID of the clip
duration (string) – Duration, in seconds, of the clip
name (string) – Name of the clip. Can be ''
saved (bool) – Whether the user has saved the clip. Clips that aren’t saved eventually expire
state (string) –
views (string) – Number of views the clip has had
rating (string) – Clip rating
ratings (string) – Number of ratings the clip has received
caption (string) – User-defined clip caption
thumbnails (dict) – Thumbnail URLs for the clip
recorded (datetime) – Date and time clip was made
media_url (string) – Video clip URL

classmethod get(xuid, scid, clip_id)¶

Retrieves a specific game clips

Parameters:	xuid – xuid of an xbox live user scid – scid of a clip clip_id – id of a clip
Returns:	`Clip` instance

classmethod saved_from_user(user[, include_pending=False])¶

Retrieves all ‘saved’ clips for a specific user, returning an iterator.

Parameters:	user – `GamerProfile` instance include_pending (bool) – whether to ignore clips that are not yet uploaded. These clips will have thumbnails and media_url set to `None`
Returns:	Iterator of `Clip` instances

classmethod latest_from_user(user[, include_pending=False])¶

Retrieves a user’s gameclips, excluding any that are pending upload.

Parameters:	user – `GamerProfile` instance include_pending (bool) – whether to ignore clips that are not yet uploaded. These clips will have thumbnails and media_url set to `None`
Returns:	Iterator of `Clip` instances

Exceptions¶

exception xbox.exceptions.XboxException¶: Base exception for all Xbox exceptions to subclass

exception xbox.exceptions.AuthenticationException¶: Raised when logging in fails, likely due to incorrect auth credentials

exception xbox.exceptions.InvalidRequest(message, response)¶

Something is wrong with the request

Variables:	message – Error message returned by server is possible response – requests response object

exception xbox.exceptions.NotFoundException¶: Any exception raised due to a resource being missing will subclass this

exception xbox.exceptions.GamertagNotFound¶

exception xbox.exceptions.ClipNotFound¶

Links:

Installation¶

Install the latest released version using pip

$ pip install xbox

Quickstart¶

>>> import xbox

>>> # authenticate
>>> xbox.client.authenticate(email_address, password)

>>> # get a user
>>> gt = xbox.GamerProfile.from_gamertag('JoeAlcorn')
>>> gt.gamerscore
22056
>>> gt.gamerpic
'http://images-eds.xboxlive.com/image?url=z951ykn43p4FqWbbFvR2Ec.8vbDhj8G2Xe7JngaTToBrrCmIEEXHC9UNrdJ6P7KIFXxmxGDtE9Vkd62rOpb7JcGvME9LzjeruYo3cC50qVYelz5LjucMJtB5xOqvr7WR'

class xbox.Client¶

Base API client object handling authentication and making requests.

A global instance of this is instantiated on import, all you have to do is call the authenticate() method.

Variables:	authenticated (bool) – whether client is authed

authenticate(login=None, password=None)¶

Authenticated this client instance.

login and password default to the environment variables MS_LOGIN and MS_PASSWD respectively.

Parameters:	login – Email address associated with a microsoft account password – Matching password
Raises:	`AuthenticationException`
Returns:	Instance of `Client`