Getting started with evergreen.py

Design Philosophy

This project is meant to be a thin client around the Evergreen REST API. As such, you can refer to the REST API for more detailed documentation.

Missing Fields

One of the goals of this project is to provide native python objects for working with the API rather than working with raw JSON. This allows features like autocomplete in modern editors. However, new fields can be introduced to the data and updates to this project tend to lagging. Evergreen object does have a json attribute that can be used to access any properties not already included.

project = evg_api.project_by_id("my-project")

assert project.display_name == project.json["display_name"]

New Functionality

Development of this project has mostly happened in a JIT (Just In Time) fashion. The Evergreen API is constantly being added to, but a lot of the new functionality has not been used in any python scripts. Thus parts of the client may be missing or incomplete. If there is additional functionality you would like added, feel free to put up a PR.

Getting an API object

The first step in using the API is to get an API object to work with. This can be done with the get_api method.

from evergreen import EvergreenApi

evg_api = EvergreenApi.get_api()

Many Evergreen endpoints require authentication. When creating an EvergreenApi object, you can pass credentials to use for authentication. There are a number of way to do this.

Pass credentials directly

You can pass in credentials directly with an EvgAuth object:

from evergreen import EvergreenApi, EvgAuth

evg_api = EvergreenApi.get_api(auth=EvgAuth(username="my_user", api_key="api_key"))

Pass credentials via a configuration file

You can also pass credentials with a configuration file. The configuration file should use the same format and location used the by the evergreen command line tool.

from evergreen import EvergreenApi

evg_api = EvergreenApi.get_api(use_config_file=True)

You can also specify a location for the config file:

from evergreen import EvergreenApi

evg_api = EvergreenApi.get_api(config_file="/path/to/config")

Special API Types

We have occassionally seen intermittent failures from the Evergreen API. These go away on retry. As a result, a RetryingEvergreenApi is provided that we retry requests that failed with an HTTP Error. This will retry an API call three times before failing.

It can be created just like an normal EvergreenApi:

from evergreen import RetryingEvergreenApi

evg_api = RetryingEvergreenApi.get_api()

After creating a RetryingEvergreenApi is can be treated just like a normal EvergreenApi object.

Session

If you are making several calls to the API is a short amount of time, you may wish to create a shared session for all the calls rather than a new session for each call. This can be done with the with_session context manager.

from evergreen import EvergreenApi

evg_api = EvergreenApi.get_api(use_config_file=True)
with evg_api.with_session() as evg_session:
    evg_session.all_projects()
    evg_session.versions_by_project()