pyeactivities

Introduction

pyeactivities provides a simple Python wrapper around the API for eActivities, the system used by Imperial College Union for societies to manage themselves. It handles tasks such as retrieving lists of members, lists of products, and sales data from the society’s shop.

Installation

Install the extension with pip:

$ pip install pyeactivities-ftm

Usage

In order to use pyeactivities, you will need an eActivities API key, and the eActivities endpoint URL.

Note

To obtain an API key, log in to eActivities and go to the details page for your society (where you can find a list of members), and click on “API Keys”. On this page you can see the API keys that already exist for your society, as well as generate new ones. We recommend using a new API key for each application so they aren’t shared.

The eActivities endpoint URL can be found in the eActivities API documentation which you can download from the API Key page.

Create a new eActivities object like so, specifying the API key and endpoint URL.

from pyeactivities import EActivities

# Base URL must end in trailing / (e.g. https://<eactivities>/API/)
eactivities = EActivities(api_key, api_base_url)

You can then get a reference to your society by using:

csp = eactivities.get_csps()[0]

Warning

get_csps() can return multiple CSPs. The eActivities API implies that one API key could be used with multiple societies but that doesn’t seem to be to be implemented yet so it’s safe to just get the first one. Therefore, we recommend double checking you have access to the CSP you were expecting.

if csp.code != "999":
  raise Exception("Unexpected CSP for given API key")

Most operations are then performed on this CSP object, for example:

members = csp.get_members()

print("{} has {} members".format(csp.name, len(members)))
for m in members:
  print("  {cid} - {fn} {sn}".format(cid=m.cid, fn=m.first_name, sn=m.surname))

API Reference

This documentation is automatically generated from pyeactivities’ source code.

API Objects

class pyeactivities.EActivities(api_key: str, endpoint_base: str)

This is the entry point into the eActivities API. It is used to retrieve the CSP objects you use to access most of the rest of the API.

get_csps() → List[pyeactivities.eactivities.CSP]

Retrieve the list of CSP objects that the API key has access to

class pyeactivities.CSP(code: str, name: str, web_name: str, acronym: str, client: pyeactivities.http.EActivitiesClient)

Represents a CSP as returned by the CSP endpoint

get_members(force_recheck=False, save_results=True) → List[pyeactivities.eactivities.Member]

Retrieve a list of of the CSP’s members

Parameters:
  • force_recheck – override the CSP’s cache
  • save_results – save the respones to the CSP’s cache
get_committee_members(force_recheck=False, save_results=True) → List[pyeactivities.eactivities.CommitteeMember]

Retrieve a list of the CSP’s committee members

Parameters:
  • force_recheck – override the CSP’s cache
  • save_results – save the respones to the CSP’s cache
get_online_sales(force_recheck=False, save_results=True) → List[pyeactivities.eactivities.OnlineSale]

Retrieve all of the CSP’s online sales

Parameters:
  • force_recheck – override the CSP’s cache
  • save_results – save the respones to the CSP’s cache
get_products(force_recheck=False, save_results=True) → List[pyeactivities.eactivities.Product]

Retrieve all of the CSP’s shop products

Parameters:
  • force_recheck – override the CSP’s cache
  • save_results – save the respones to the CSP’s cache
class pyeactivities.Member(first_name: str, surname: str, cid: str, email: str, login: str, order_no: str, member_type: str)

Represents a member of a CSP as returned by the member report endpoint

class pyeactivities.CommitteeMember(first_name: str, surname: str, cid: str, email: str, login: str, post_name: str, phone_no: str, start_date: str, end_date: str)

Represents a committee member of a CSP as returned by the committee member report endpoint

class pyeactivities.OnlineSale(order_number: str, sale_date_time: str, product_id: int, product_line_id: int, price: float, quantity: int, quantity_collected: int, customer: pyeactivities.eactivities.Customer, vat: pyeactivities.eactivities.VAT)

Represents an online sale with details of the product, price, and customer

class pyeactivities.Customer(first_name: str, surname: str, cid: str, email: str, login: str)

Represents a customer from an online sale

class pyeactivities.VAT(code: str, name: str, rate: float)

Represents the VAT information for a product or sale etc.

class pyeactivities.Product(csp: pyeactivities.eactivities.CSP, id: int, name: str, description: str, type: str, selling_date_start: str, selling_date_end: str, url: str, active: bool, product_lines: List[ProductLine])

Represents a product sold on the online shop

get_sales(force_recheck=False, save_results=True) → List[pyeactivities.eactivities.OnlineSale]

Retrieve a list of sales for the product

Parameters:
  • force_recheck – override the CSP’s cache
  • save_results – save the respones to the CSP’s cache
class pyeactivities.ProductLine(id: int, name: str, quantity: int, unlimited: bool, price: float, collectable: bool, default_option: bool, account: pyeactivities.eactivities.Account, activity: pyeactivities.eactivities.Activity, vat: pyeactivities.eactivities.VAT)

Represents a particular line within a product sold on the CSP’s online shop

class pyeactivities.Account(code: str, name: str, type: str)

Represents an account within a CSP’s finances

class pyeactivities.Activity(code: str, name: str)

Represents an activity within a CSP’s finances

Exceptions

exception pyeactivities.exceptions.APIException

The base class for any exception thrown by pyeactivities relating to the eActivities API

exception pyeactivities.exceptions.APIForbiddenException

This exception is thrown by and API access that results in the eActivities API returning a 403 Forbidden status code. The most likely cause is too many requests with an incorrect API key, or an excessive number of requests.

exception pyeactivities.exceptions.APIUnauthorisedException

This exception is thrown by any API access that results in the eActivites API returning a 401 Unauthorised status code. The most likely cause is normally an incorrect API key.

Internal classes

class pyeactivities.http.EActivitiesClient(api_key, endpoint_base, user_agent='pyeactivities/0.1.2')

This is an internal HTTP client used by pyeactivities to send requests to eActivities, it should not be used by the end user. It handles all the common bits between the API calls such as prepending the endpoint, including the API key, and handling any Unauthorised or Forbidden errors.

The client uses a default user agent of “pyeactivities/<version>” where <version> is the version of the pyeactivities library being used.

License

pyeactivities is licensed under the MIT License

Copyright (c) 2019 Fraser May and Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.