Connection

class O365.connection.Connection(credentials, *, scopes=None, proxy_server=None, proxy_port=8080, proxy_username=None, proxy_password=None, requests_delay=200, raise_http_errors=True, request_retries=3, token_backend=None, tenant_id='common', auth_flow_type='authorization', timeout=None, json_encoder=None, verify_ssl=True, **kwargs)

Bases: object

Handles all communication (requests) between the app and the server

__init__(credentials, *, scopes=None, proxy_server=None, proxy_port=8080, proxy_username=None, proxy_password=None, requests_delay=200, raise_http_errors=True, request_retries=3, token_backend=None, tenant_id='common', auth_flow_type='authorization', timeout=None, json_encoder=None, verify_ssl=True, **kwargs)

Creates an API connection object

Parameters

• credentials (tuple) –

  a tuple of (client_id, client_secret)

  Generate client_id and client_secret in https://apps.dev.microsoft.com

• scopes (list[str]) – list of scopes to request access to

• proxy_server (str) – the proxy server

• proxy_port (int) – the proxy port, defaults to 8080

• proxy_username (str) – the proxy username

• proxy_password (str) – the proxy password

• requests_delay (int) – number of milliseconds to wait between api calls. The Api will respond with 429 Too many requests if more than 17 requests are made per second. Defaults to 200 milliseconds just in case more than 1 connection is making requests across multiple processes.

• raise_http_errors (bool) – If True Http 4xx and 5xx status codes will raise as exceptions

• request_retries (int) – number of retries done when the server responds with 5xx error codes.

• token_backend (BaseTokenBackend) – the token backend used to get and store tokens

• tenant_id (str) – use this specific tenant id, defaults to common

• auth_flow_type (str) – the auth method flow style used: Options: - ‘authorization’: 2 step web style grant flow using an authentication url - ‘public’: 2 step web style grant flow using an authentication url for public apps where client secret cannot be secured - ‘credentials’: also called client credentials grant flow using only the cliend id and secret

• or tuple timeout (float) – How long to wait for the server to send data before giving up, as a float, or a tuple (connect timeout, read timeout)

• json_encoder (JSONEncoder) – The JSONEnocder to use during the JSON serialization on the request.

• verify_ssl (bool) – set the verify flag on the requests library

• kwargs (dict) – any extra params passed to Connection

Raises

ValueError – if credentials is not tuple of (client_id, client_secret)

property auth_flow_type

delete(url, **kwargs)

Shorthand for self.request(url, ‘delete’)

Parameters

• url (str) – url to send delete oauth request to

• kwargs – extra params to send to request api

Returns

Response of the request

Return type

requests.Response

get(url, params=None, **kwargs)

Shorthand for self.oauth_request(url, ‘get’)

Parameters

• url (str) – url to send get oauth request to

• params (dict) – request parameter to get the service data

• kwargs – extra params to send to request api

Returns

Response of the request

Return type

requests.Response

get_authorization_url(requested_scopes=None, redirect_uri=None, **kwargs)

Initializes the oauth authorization flow, getting the authorization url that the user must approve.

Parameters

• requested_scopes (list[str]) – list of scopes to request access for

• redirect_uri (str) – redirect url configured in registered app

• kwargs – allow to pass unused params in conjunction with Connection

Returns

authorization url

Return type

str

get_naive_session()

Creates and returns a naive session

get_session(*, state=None, redirect_uri=None, load_token=False, scopes=None)

Create a requests Session object

Parameters

• state (str) – session-state identifier to rebuild OAuth session (CSRF protection)

• redirect_uri (str) – callback URL specified in previous requests

• scopes (list(str)) – list of scopes we require access to

• load_token (bool) – load and ensure token is present

Returns

A ready to use requests session, or a rebuilt in-flow session

Return type

OAuth2Session

naive_request(url, method, **kwargs)

Makes a request to url using an without oauth authorization session, but through a normal session

Parameters

• url (str) – url to send request to

• method (str) – type of request (get/put/post/patch/delete)

• kwargs – extra params to send to the request api

Returns

Response of the request

Return type

requests.Response

oauth_request(url, method, **kwargs)

Makes a request to url using an oauth session

Parameters

• url (str) – url to send request to

• method (str) – type of request (get/put/post/patch/delete)

• kwargs – extra params to send to the request api

Returns

Response of the request

Return type

requests.Response

patch(url, data=None, **kwargs)

Shorthand for self.oauth_request(url, ‘patch’)

Parameters

• url (str) – url to send patch oauth request to

• data (dict) – patch data to update the service

• kwargs – extra params to send to request api

Returns

Response of the request

Return type

requests.Response

post(url, data=None, **kwargs)

Shorthand for self.oauth_request(url, ‘post’)

Parameters

• url (str) – url to send post oauth request to

• data (dict) – post data to update the service

• kwargs – extra params to send to request api

Returns

Response of the request

Return type

requests.Response

put(url, data=None, **kwargs)

Shorthand for self.oauth_request(url, ‘put’)

Parameters

• url (str) – url to send put oauth request to

• data (dict) – put data to update the service

• kwargs – extra params to send to request api

Returns

Response of the request

Return type

requests.Response

refresh_token()

Refresh the OAuth authorization token. This will be called automatically when the access token

expires, however, you can manually call this method to request a new refresh token.

Return bool

Success / Failure

request_token(authorization_url, *, state=None, redirect_uri=None, requested_scopes=None, store_token=True, **kwargs)

Authenticates for the specified url and gets the token, save the token for future based if requested

Parameters

• or None authorization_url (str) – url given by the authorization flow

• state (str) – session-state identifier for web-flows

• redirect_uri (str) – callback url for web-flows

• requested_scopes (lst) – a list of scopes to be requested. Only used when auth_flow_type is ‘credentials’

• store_token (bool) – whether or not to store the token, so you don’t have to keep opening the auth link and authenticating every time

• kwargs – allow to pass unused params in conjunction with Connection

Returns

Success/Failure

Return type

bool

set_proxy(proxy_server, proxy_port, proxy_username, proxy_password)

Sets a proxy on the Session

Parameters

• proxy_server (str) – the proxy server

• proxy_port (int) – the proxy port, defaults to 8080

• proxy_username (str) – the proxy username

• proxy_password (str) – the proxy password

class O365.connection.MSBusinessCentral365Protocol(api_version='v1.0', default_resource=None, environment=None, **kwargs)

Bases: O365.connection.Protocol

A Microsoft Business Central Protocol Implementation https://docs.microsoft.com/en-us/dynamics-nav/api-reference/v1.0/endpoints-apis-for-dynamics

__init__(api_version='v1.0', default_resource=None, environment=None, **kwargs)

Create a new Microsoft Graph protocol object

_protocol_url = ‘https://api.businesscentral.dynamics.com/’

_oauth_scope_prefix = ‘https://api.businesscentral.dynamics.com/’

Parameters

• api_version (str) – api version to use

• default_resource (str) – the default resource to use when there is nothing explicitly specified during the requests

class O365.connection.MSGraphProtocol(api_version='v1.0', default_resource=None, **kwargs)

Bases: O365.connection.Protocol

A Microsoft Graph Protocol Implementation https://docs.microsoft.com/en-us/outlook/rest/compare-graph-outlook

__init__(api_version='v1.0', default_resource=None, **kwargs)

Create a new Microsoft Graph protocol object

_protocol_url = ‘https://graph.microsoft.com/’

_oauth_scope_prefix = ‘https://graph.microsoft.com/’

Parameters

• api_version (str) – api version to use

• default_resource (str) – the default resource to use when there is nothing explicitly specified during the requests

class O365.connection.MSOffice365Protocol(api_version='v2.0', default_resource=None, **kwargs)

Bases: O365.connection.Protocol

A Microsoft Office 365 Protocol Implementation https://docs.microsoft.com/en-us/outlook/rest/compare-graph-outlook

__init__(api_version='v2.0', default_resource=None, **kwargs)

Create a new Office 365 protocol object

_protocol_url = ‘https://outlook.office.com/api/’

_oauth_scope_prefix = ‘https://outlook.office.com/’

Parameters

• api_version (str) – api version to use

• default_resource (str) – the default resource to use when there is nothing explicitly specified during the requests

class O365.connection.Protocol(*, protocol_url=None, api_version=None, default_resource=None, casing_function=None, protocol_scope_prefix=None, timezone=None, **kwargs)

Bases: object

Base class for all protocols

__init__(*, protocol_url=None, api_version=None, default_resource=None, casing_function=None, protocol_scope_prefix=None, timezone=None, **kwargs)

Create a new protocol object

Parameters

• protocol_url (str) – the base url used to communicate with the server

• api_version (str) – the api version

• default_resource (str) – the default resource to use when there is nothing explicitly specified during the requests

• casing_function (function) – the casing transform function to be used on api keywords (camelcase / pascalcase)

• protocol_scope_prefix (str) – prefix url for scopes

• or str timezone (pytz.UTC) – preferred timezone, defaults to the system timezone

Raises

ValueError – if protocol_url or api_version are not supplied

convert_case(key)

Returns a key converted with this protocol casing method

Converts case to send/read from the cloud

When using Microsoft Graph API, the keywords of the API use lowerCamelCase Casing

When using Office 365 API, the keywords of the API use PascalCase Casing

Default case in this API is lowerCamelCase

Parameters

key (str) – a dictionary key to convert

Returns

key after case conversion

Return type

str

get_scopes_for(user_provided_scopes)

Returns a list of scopes needed for each of the scope_helpers provided, by adding the prefix to them if required

Parameters

user_provided_scopes (list or tuple or str) – a list of scopes or scope helpers

Returns

scopes with url prefix added

Return type

list

Raises

ValueError – if unexpected datatype of scopes are passed

get_service_keyword(keyword)

Returns the data set to the key in the internal data-key dict

Parameters

keyword (str) – key to get value for

Returns

value of the keyword

prefix_scope(scope)

Inserts the protocol scope prefix if required

static to_api_case(key)

Converts key to snake_case

Parameters

key (str) – key to convert into snake_case

Returns

key after case conversion

Return type

str

O365.connection.oauth_authentication_flow(client_id, client_secret, scopes=None, protocol=None, **kwargs)

A helper method to perform the OAuth2 authentication flow. Authenticate and get the oauth token

Parameters

• client_id (str) – the client_id

• client_secret (str) – the client_secret

• scopes (list[str]) – a list of protocol user scopes to be converted by the protocol or raw scopes

• protocol (Protocol) – the protocol to be used. Defaults to MSGraphProtocol

• kwargs – other configuration to be passed to the Connection instance, connection.get_authorization_url or connection.request_token

Returns

Success or Failure

Return type

bool