Compass Interface — the unofficial Compass API
The Compass Interface project aims to provide a unified and well-documented API to the Scouts' national membership system, Compass.
Notice
This is not an official API to Compass and as such should be used in a way that doesn't cause a high request load on the Compass system.
Please also remember your personal data handling obligations (under both GDPR and Scouting policies) whilst using this library.
Objectives
The project aims to:
- increase flexibility and simplicity when developing applications that interface with Compass data,
- provide stability and abstract complexities of Compass, and
- enable greater support to our adult volunteers and members.
Where to get it
The source code for the project is hosted on GitHub at the-scouts/compass-interface
Installers for the latest release are availibe on Conda and at the Python Package Index (PyPI).
# conda
conda env create
conda install compass-interface
If installing dependencies with pip
,
use a virtual environment
to isolate your packages.
# or PyPI
# create venv
python -m venv venv
# activate venv - windows
.\venv\Scripts\activate
# activate venv - unix-like (macOS, linux)
source env/bin/activate
# install dependencies
python -m pip install --upgrade pip
python -m pip install compass-interface
Dependencies
- httpx - for intuitive HTTP requests
- lxml - for parsing HTML documents
- pydantic, email-validator, phonenumbers - for data validation and parsing
- compass - Core Compass Interface, with parsing and validation logic
- pandas - for data management and transformation
- numba - to speed things up
- pyarrow - to process and move data fast
- FastAPI - for an intuitive API
- uvicorn - serving on the lightning-fast ASGI server
Licence
Compass Interface is naturally open source and is licensed under the MIT license.
Core Module
This sub-project hosts the extraction functionaility of Compass Interface, and is itself a standalone module for querying Compass.
The main project is found at the-scouts/compass-interface.
Example Usage
import compass.core as ci
from compass.core.logger import enable_debug_logging
# Turn on debug logging for development
enable_debug_logging()
# Login to Compass
api = ci.login("username", "password")
# Get all unique members from your hierarchy
member_set = api.hierarchy.unique_members()
Specifying a role
By default, Compass Interface uses your primary role to access Compass. To
change this, a custom role can be specified when calling ci.login
, as
follows:
import compass.core as ci
from compass.core.logger import enable_debug_logging
# Turn on debug logging for development
enable_debug_logging()
# Login to Compass
api = ci.login("username", "password", role="role_as_on_compass")
The string passed to the role
argument must match the role title on Compass
exactly, as they are compared internally. You can validate that the role has
updated successfully through the log output.
Specifying a role and location
If you have multiple roles with the same title on compass (for example, two
Group Administrator
or Scout Active Support Manager
roles), these can be
differentiated by also specifying a role location, as follows:
import compass.core as ci
from compass.core.logger import enable_debug_logging
# Turn on debug logging for development
enable_debug_logging()
# Login to Compass
api = ci.login("username", "password", role="role_as_on_compass", location="location_as_on_compass")
As with the role title, the location needs to match the text in the Location
column of My Roles
exactly, as we verify the text matches internally.
API Usage
Running the API
To run the API either run uvicorn compass.api.app:app --reload
in the
root directory, or run the app.py
file in the /compass/api/
directory. This
second method also enables interactive debugging.
Alternatively, use Docker
Running the Compass Interface files directly
To run the Compass Interface files directly the top-level script.py file is useful for getting started immediately. Please make sure not to commit credentials to git, as these are assumed public as soon as they are on GitHub.
Docker
To run Compass Interface locally, we provide docker templates in /docker
.
! Note: All commands below are run in the /docker directory.
Local hosting / development
To start docker, run docker compose -f docker-compose.yml up -d
.
To rebuild the Compass Interface backend, run docker buildx build -t scouts/compass-interface-backend --load -f backend.dockerfile .
.
To stop docker, run docker compose down
.
To remove old build files, run docker container prune -f; docker image prune -f
Deployment
To start docker, run
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
.
To stop docker, run docker-compose down
.
Ports
When the containers are running, the FastAPI app is reached at localhost:8888.
If you are running the deployment configuration, you will also find the Traefik reverse proxy at localhost:80 and Traefik's dashboard at localhost:8080.
Support
For support please contact Adam Turner (@AA-Turner). There is a wider
community of interest on the UK Scouts IT Lab
group.
Ideas, Bugs, Features
Please use GitHub issues / Pull Requests to note bugs or feature requests.