Skip to main content

A python 3 client for the Cachet API

Project description

pypi travis Documentation Status

cachet-client

A python 3.5+ API client for the open source status page system Cachet.

The goal of this package is to create a user friendly interface to the Cachet API.

  • Resources are returned as objects clearly separating read only properties from the ones we can change. The raw json response is always available in an attrs property
  • Active use of type hints throughout the entire codebase making code completion a breeze
  • Proper pagination under the hood. Method listing resources will return generators. You can configure the start page and page size that fits the situation. Each new page leads to a new http request.
  • Client is using a single session regardless of resource type making more complex work a lot faster (connection reuse)
  • A very extensive set of tests/unit tests.
  • Easy to extend and test
  • Documentation

Please don't hesitate opening an issue about anything related to this package.

Install

pip install cachet-client

Example

import cachetclient
from cachetclient.v1 import enums

client = cachetclient.Client(
    endpoint='https://status.test/api/v1',
    api_token='secrettoken',
)

Check if api is responding

if client.ping():
    print("Cachet is up and running!")

Create and delete a subscriber

sub = client.subscribers.create(email='user@example.test', verify=True)
sub.delete()

List all subscribers paginated (generator). Each new page is fetched from the server under the hood.

for sub in client.subscribers.list(page=1, per_page=100):
    print(sub.id, sub.email)

Create a component issue

issue = client.incidents.create(
    name="Something blew up!",
    message="We are looking into it",
    status=enums.INCIDENT_INVESTIGATING,
    # Optional for component issues
    component_id=mycomponent.id,
    component_status=enums.COMPONENT_STATUS_MAJOR_OUTAGE,
)

.. and most other features supported by the Cachet API

Local Development

Local setup:

python -m virtualenv .venv
. .venv/bin/activate
pip install -e .

Tests

This project has a fairly extensive test setup.

  • Unit tests are located in tests/ including a fake implementation of the Cachet API.
  • A simpler test script under extras/live_run.py that needs a running test instance of Cachet.

Running unit tests

pip install -r tests/requirements.txt
tox

# Optionally
tox -e pep8  # for pep8 run only
tox -e py36  # tests only


# Running tests with pytest also works, but this works poorly in combination with environment variables for the live test script (tox separates environments)
pytest tests/

Testing with real Cachet service

Do not run this script against a system in production. This is only for a test service. Cachet can easily be set up locally with docker: https://github.com/CachetHQ/Docker

Optionally we can run cachet from source: https://github.com/CachetHQ/Docker

A local setup is also located in the root or the repo (docker-compose.yaml).

You need to set the following environment variables.

CACHET_ENDPOINT
CACHET_API_TOKEN

Running tests:

python extras/live_run.py
...
=================================================
Numer of tests    : 10
Succesful         : 8
Failure           : 2
Percentage passed : 80.0%
=================================================

Building Docs

pip install -r docs/requirements.txt
python setup.py build_sphinx

Contributing

Do not hesitate opening issues or submit completed or partial pull requests. Contributors of all experience levels are welcome.


This project is sponsored by zetta.io

zetta.io

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

cachet_client-3.1.0-py3-none-any.whl (24.2 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page