cofecms package

Submodules

cofecms.api module

class cofecms.api.CofeCMS(api_id, api_key, diocese_id=None)

Bases: object

BASE_URL = 'https://cmsapi.cofeportal.org'

DATE_FORMAT = '%Y-%m-%d %H:%M'

DEFAULT_LIMIT = 100

diocese_id

do_request(endpoint_url, request_params)

Performs a request to the given endpoint_url with the supplied request params.

Parameters:

• endpoint_url – The absolute URL for the endpoint to use. For example: https://cmsapi.cofeportal.org/v2/contacts
• request_params – A dict containing the GET params for this request. Will be URL encoded for you.

Returns:

An unmolested requests.Result object.

Raises:

Will raise the appropriate HTTP exception for any non-200 HTTP response.

encode_search_params(search_params)

Generate a JSON representation of the supplied dict suitable for use in the ‘search_params’ parameter.

Parameters:search_params – A dict of search params. The API docs contain more information: https://cmsapi.cofeportal.org/json-data-string. Returns:A JSON string of the provided search_params.

format_date(python_datetime)

Format the given Python datetime to the format used by the API.

Parameters:python_datetime – The datetime to format Returns:A string representation of the date which can be used by the API.

generate_endpoint_url(endpoint)

Generate an absolute URL for a given endpoint.

Uses the BASE_URL constant.

Parameters:endpoint – The endpoint to use, as defined in the specs. For example: ‘/v2/contacts’. Returns:The absolute URL for the given endpoint.

generate_request_params(diocese_id, search_params, **basic_params)

Generate a dict containing the GET request parameters for a request.

The required ‘api_id’, ‘data’ and ‘sig’ params are always added.

API docs: https://cmsapi.cofeportal.org/request-parameters

Parameters:

• diocese_id – Optionally supply the diocese_id.
• search_params – A dict of search params. The API docs have more information on this: https://cmsapi.cofeportal.org/json-data-string.
• **basic_params – Any extra params for the API call, for example to set a limit on.

Returns:

A dict containing the final requst params, including the calculated signing ‘sig’.

generate_signature(json_search_params, **basic_params)

Generate a signature used for signing each request.

The process is described here: https://cmsapi.cofeportal.org/signing-requests

Parameters:

• json_search_params – The JSON encoded search_params.
• **basic_params – Any extra params for the request.

Returns:

A string containing the hexadecimal signature for the request.

get(endpoint_url, diocese_id=None, search_params=None, **basic_params)

Perform a generic request against the API and retrieves the results.

Note: This is a fairly raw way of requesting data from the API and will not hold your hand for dealing with paged results. See ‘paged_get’ for a better way of doing raw queries with paged results.

Parameters:

• endpoint_url – The absolute URL for the endpoint to use. For example: https://cmsapi.cofeportal.org/v2/contacts
• diocese_id – Optionally supply the diocese_id.
• search_params – A dict containing search params. The API docs contain more information on this: https://cmsapi.cofeportal.org/json-data-string.
• **basic_params – Pass general request parameters as needed by the endpoint. ‘api_id’, ‘data’ and ‘sig’ params are automatically added for you. The API docs give more information on what params can be used: https://cmsapi.cofeportal.org/request-parameters

Returns:

A CofeCMSResult with the results and details of the query.

get_contact(contact_id, diocese_id=None)

Retrieve data on a single contact.

API docs: https://cmsapi.cofeportal.org/get-contacts-id

Parameters:

• contact_id – The ID of the requested contact
• diocese_id – Optionally supply the diocese_id.

Returns:

A CofeCMSResult with the results of the query.

get_contact_fields(diocese_id=None)

Retrieves all possible fields for contacts.

API docs: https://cmsapi.cofeportal.org/get-contact-fields

Parameters:diocese_id – Optionally supply the diocese_id. Returns:A CofeCMSResult with the results of the query.

get_contacts(diocese_id=None, search_params=None, end_date=None, fields=None, limit=None, offset=None, start_date=None)

Retrieve a collection of contact records.

API docs: https://cmsapi.cofeportal.org/get-contacts

Parameters:

• diocese_id – Optionally supply the diocese_id.
• search_params – Optionally provide a dict of search params. See the API docs for more information.
• end_date – Optional datetime to only return records that were updated on or before this date.
• fields – Optional list of fields to be included in the response. See output of get_contact_fields() for a list of valid fields.
• limit – The maximum number of records to return at once. Maximum of 1000.
• offset – The number of records to skip. Used for getting paged results. Defaults to 0.
• start_date – Optional datetime to only return records that were updated on or after this date.

Returns:

A CofeCMSResult with the results of the query.

get_deleted_contacts(diocese_id=None, search_params=None, end_date=None, fields=None, limit=None, offset=None, start_date=None)

Retrieve a collection of deleted contact records.

API docs: https://cmsapi.cofeportal.org/get-contacts-deleted

Parameters:

• diocese_id – Optionally supply the diocese_id.
• search_params – Optionally provide a dict of search params. See the API docs for more information.
• end_date – Optional datetime to only return records that were updated on or before this date.
• fields – Optional list of fields to be included in the response. See output of get_contact_fields() for a list of valid fields.
• limit – The maximum number of records to return at once. Maximum of 1000.
• offset – The number of records to skip. Used for getting paged results. Defaults to 0.
• start_date – Optional datetime to only return records that were updated on or after this date.

Returns:

A CofeCMSResult with the results of the query.

get_deleted_places(diocese_id=None, search_params=None, end_date=None, fields=None, limit=None, offset=None, start_date=None)

Retrieve a collection of deleted place records.

API docs: https://cmsapi.cofeportal.org/get-places-deleted

Parameters:

• diocese_id – Optionally supply the diocese_id.
• search_params – Optionally provide a dict of search params. See the API docs for more information.
• end_date – Optional datetime to only return records that were updated on or before this date.
• fields – Optional list of fields to be included in the response. See output of get_contact_fields() for a list of valid fields.
• limit – The maximum number of records to return at once. Maximum of 1000.
• offset – The number of records to skip. Used for getting paged results. Defaults to 0.
• start_date – Optional datetime to only return records that were updated on or after this date.

Returns:

A CofeCMSResult with the results of the query.

get_deleted_posts(diocese_id=None, search_params=None, end_date=None, fields=None, limit=None, offset=None, start_date=None)

Retrieve a collection of deleted records containing post, place, contact and role fields.

API docs: https://cmsapi.cofeportal.org/get-posts-deleted

Parameters:

• diocese_id – Optionally supply the diocese_id.
• search_params – Optionally provide a dict of search params. See the API docs for more information.
• end_date – Optional datetime to only return records that were updated on or before this date.
• fields – Optional list of fields to be included in the response. See output of get_contact_fields() for a list of valid fields.
• limit – The maximum number of records to return at once. Maximum of 1000.
• offset – The number of records to skip. Used for getting paged results. Defaults to 0.
• start_date – Optional datetime to only return records that were updated on or after this date.

Returns:

A CofeCMSResult with the results of the query.

get_place(place_id, diocese_id=None)

Retrieve a single place record.

API docs: https://cmsapi.cofeportal.org/get-places-id

Parameters:

• place_id – The ID of the requested place
• diocese_id – Optionally supply the diocese_id.

Returns:

A CofeCMSResult with the results of the query.

get_place_fields(diocese_id=None)

Retrieves all possible fields for places.

API docs: https://cmsapi.cofeportal.org/get-place-fields

Parameters:diocese_id – Optionally supply the diocese_id. Returns:A CofeCMSResult with the results of the query.

get_places(diocese_id=None, search_params=None, end_date=None, fields=None, limit=None, offset=None, start_date=None)

Retrieve a collection of place records.

API docs: https://cmsapi.cofeportal.org/get-places

Parameters:

• diocese_id – Optionally supply the diocese_id.
• search_params – Optionally provide a dict of search params. See the API docs for more information.
• end_date – Optional datetime to only return records that were updated on or before this date.
• fields – Optional list of fields to be included in the response. See output of get_contact_fields() for a list of valid fields.
• limit – The maximum number of records to return at once. Maximum of 1000.
• offset – The number of records to skip. Used for getting paged results. Defaults to 0.
• start_date – Optional datetime to only return records that were updated on or after this date.

Returns:

A CofeCMSResult with the results of the query.

get_post(post_id, diocese_id=None)

Retrieve a single records containing post, place, contact and role fields.

API docs: https://cmsapi.cofeportal.org/get-posts-id

Parameters:

• post_id – The ID of the requested post
• diocese_id – Optionally supply the diocese_id.

Returns:

A CofeCMSResult with the results of the query.

get_post_fields(diocese_id=None)

Retrieves all possible fields for posts.

API docs: https://cmsapi.cofeportal.org/get-post-fields

Parameters:diocese_id – Optionally supply the diocese_id. Returns:A CofeCMSResult with the results of the query.

get_posts(diocese_id=None, search_params=None, end_date=None, fields=None, limit=None, offset=None, start_date=None)

Retrieve a collection of records containing post, place, contact and role fields.

API docs: https://cmsapi.cofeportal.org/get-posts

Parameters:

• diocese_id – Optionally supply the diocese_id.
• search_params – Optionally provide a dict of search params. See the API docs for more information.
• end_date – Optional datetime to only return records that were updated on or before this date.
• fields – Optional list of fields to be included in the response. See output of get_contact_fields() for a list of valid fields.
• limit – The maximum number of records to return at once. Maximum of 1000.
• offset – The number of records to skip. Used for getting paged results. Defaults to 0.
• start_date – Optional datetime to only return records that were updated on or after this date.

Returns:

A CofeCMSResult with the results of the query.

get_roles(diocese_id=None)

Retrieves all defined role names and their ID.

API docs: https://cmsapi.cofeportal.org/get-roles

Parameters:diocese_id – Optionally supply the diocese_id. Returns:A CofeCMSResult with the results of the query.

paged_get(endpoint_url, diocese_id=None, search_params=None, **basic_params)

Similar to ‘get’, however it also populates the result object with the necessary information to make requests for more pages of data easier.

Parameters:

• endpoint_url – The absolute URL for the endpoint to use. For example: https://cmsapi.cofeportal.org/v2/contacts
• diocese_id – Optionally supply the diocese_id.
• search_params – A dict containing search params. The API docs contain more information on this: https://cmsapi.cofeportal.org/json-data-string.
• **basic_params – Pass general request parameters as needed by the endpoint. ‘api_id’, ‘data’ and ‘sig’ params are automatically added for you. The API docs give more information on what params can be used: https://cmsapi.cofeportal.org/request-parameters

Returns:

A CofeCMSResult with the results and details of the query.

The CofeCMSResult will be populated with the used offset, limit used in the request, and will also add the total_count attribute from the ‘X-Total-Count’ header.

class cofecms.api.CofeCMSResult(*args, **kwargs)

Bases: list

all()

Retrieve the data for all pages of results from the inital query.

Warning: Can be quite slow to run as a request will be made for each page. Suggest reducing the number of pages by increasing the “limit” when performing the initial query.

Returns:A list of result data (which are usually dicts).

get_data_for_page(page_num)

Retrieve the data for a specific page in the initial query.

Parameters:page_num – The number of the page to get. Zero indexed. Returns:A CofeCMSResult object, populated with data for the requested page.

pages_generator()

A generator to iterate through all the pages in the initial query.

Warning: Can be quite slow to run as a request will be made for each page. Suggest reducing the number of pages by increasing the “limit” when performing the initial query.

total_pages

Calculate how many pages of results are in the entire result set.

The COFE CMS API tends to not give an accurate “total_count” of results. So this should be seen as calculating the maximum number of pages.

Returns:An int of of the number of pages.

class cofecms.api.ContactData(contact_data, max_access_level=0)

Bases: object

A wrapper to provide easy access to Worthers contact data, whilst taking into account privacy settings.

Module contents