Connecting to an endpoint

A service object represents a single endpoint which has at least one EntitySet. It is the cornerstone of this library. If you have multiple endpoints to connect to, create multiple instances of ODataService. All Entity objects are each bound to exactly one Service and cannot be used across multiple services.

Optionally, the Service object can connect to the endpoint and request its metadata document. This document will then be used to build Entity objects corresponding to each EntitySet provided by the endpoint. This operation requires a working network connection to the endpoint. Creating an instance with reflect_entities=False will not cause any network activity.

Authentication

auth and session keyword arguments to ODataService are passed as-is to Requests calls, so most of the same guides can be used.

HTTP Basic authentication:

>>> from requests.auth import HTTPBasicAuth
>>> my_auth = HTTPBasicAuth('username', 'password')
>>> Service = ODataService('url', auth=my_auth)

NTLM Auth (for services like Microsoft Dynamics 2016):

>>> import requests
>>> from requests_ntlm import HttpNtlmAuth
>>> my_session = requests.Session()
>>> my_session.auth = HttpNtlmAuth('domain\username', 'password')
>>> my_session.get('basic url')  # should return 200 OK
>>> Service = ODataService('url', session=my_session)

API

class odata.service.ODataService(url, base=None, reflect_entities=False, session=None, auth=None)
Parameters:
  • url – Endpoint address. Must be an address that can be appended with $metadata
  • base – Custom base class to use for entities
  • reflect_entities – Create a request to the service for its metadata, and create entity classes automatically
  • session – Custom Requests session to use for communication with the endpoint
  • auth – Custom Requests auth object to use for credentials
Raises:

ODataConnectionError – Fetching metadata failed. Server returned an HTTP error code
Action = None

A baseclass for this service’s Actions

Base = None

Entity base class. Either a custom one given in init or a generated one. Can be used to define entities

Function = None

A baseclass for this service’s Functions

actions = None

A dictionary containing all the automatically created unbound Action callables. Empty if the service is created with reflect_entities=False

create_context(auth=None, session=None)

Create new context to use for session-like usage

Parameters:
  • auth – Custom Requests auth object to use for credentials
  • session – Custom Requests session to use for communication with the endpoint
Returns:

Context instance
Return type:

Context
delete(entity)

Creates a DELETE call to the service, deleting the entity

Raises:ODataConnectionError – Delete not allowed or a serverside error. Server returned an HTTP error code
describe(entity)

Print a debug screen of an entity instance

Parameters:entity – Entity instance to describe
entities = None

A dictionary containing all the automatically created Entity classes. Empty if the service is created with reflect_entities=False

functions = None

A dictionary containing all the automatically created unbound Function callables. Empty if the service is created with reflect_entities=False

is_entity_saved(entity)

Returns boolean indicating entity’s status

query(entitycls)

Start a new query for given entity class

Parameters:entitycls – Entity to query
Returns:Query object
save(entity, force_refresh=True)

Creates a POST or PATCH call to the service. If the entity already has a primary key, an update is called. Otherwise the entity is inserted as new. Updating an entity will only send the changed values

Parameters:
  • entity – Model instance to insert or update
  • force_refresh – Read full entity data again from service after PATCH call
Raises:

ODataConnectionError – Invalid data or serverside error. Server returned an HTTP error code
types = None

A dictionary containing all types (EntityType, EnumType) created during reflection. Empty if the service is created with reflect_entities=False