Evergreen.py

A client library for the Evergreen API written in python. Currently supports the V2 version of the API. For more details, see https://github.com/evergreen-ci/evergreen/wiki/REST-V2-Usage.

PyPI - Python Version PyPI Coverage Status

Table of contents

  1. Description
  2. Getting Help
  3. Dependencies
  4. Installation
  5. Usage
  6. Documentation
  7. Contributor's Guide

Description

This is a Python client library for interacting with Evergreen and Evergreen objects. It currently only supports the V2 version of Evergreen's api. It can be used either by Python code in a separate application or on the command line to get data about Evergreen objects quickly and easily.

Getting Help

What's the right channel to ask my question?

If you have a question about evergreen.py, please mention @dag-on-call in slack channel #evergreen-users, or email us at devprod-si-team@mongodb.com.

How can I request a change/report a bug in evergreen.py?

Create a DEVPROD ticket.

What should I include in my ticket or #evergreen-users question?

Since #evergreen-users questions are interrupts, please include as much information as possible. This can help avoid long information-gathering threads.

Please include the following:

  • Motivation for Request
    • provide us the motivation for this change.
  • Context
    • provide some background contexts for this issue.
  • Description
    • provide some descriptions on how this issue happened.

Dependencies

  • Python 3.9-3.13

Installation

$ pip install evergreen.py

Usage

This client can be used either in code or directly via the command line.

In code:

>> from evergreen.api import EvgAuth, EvergreenApi
>> api = EvergreenApi.get_api(EvgAuth('your.username', '***'))
>> project = api.project_by_id('mongodb-mongo-master')
>> project.display_name
'MongoDB (master)'

Cli:

$ evg-api --json list-hosts
{
    "host_id": "host num 0",
    "host_url": "host.num.com",
    "distro": {
        "distro_id": "ubuntu1804-build",
        "provider": "static",
        "image_id": ""
    },
    "provisioned": true,
    "started_by": "mci",
    "host_type": "",
    "user": "mci-exec",
    "status": "running",
    "running_task": {
        "task_id": null,
        "name": null,
        "dispatch_time": null,
        "version_id": null,
        "build_id": null
    },
    "user_host": false
}

The patch_from_diff API requires the Evergreen CLI to be installed. Add the following to the host's DOCKERFILE:

RUN wget https://evergreen.mongodb.com/clients/linux_amd64/evergreen
RUN chmod +x evergreen
ENV PATH="/project:$PATH"

You will need to provide an .evergreen.yml file with credentials to use the CLI. Assuming you are using the web-app chart this can be done by mounting kubernetes secrets in your pod.

Store the secret in the cluster:

kubectl create secret generic <secret_name> --from-file .evergreen.yml --namespace <namespace>

In environments/deployment.yml configure the file to be mounted and linked to the correct location:

volumeSecrets:
  - name: <secret_name>
    path: /etc/secrets
lifecycle:
  postStart:
    type: exec
    command:
      - /bin/sh
      - -c
      - ln -sf /etc/secrets/.evergreen.yml

Documentation

You can find the documentation here.

Contributor's Guide

Setting up a local development environment

Requirements

  • Poetry 1.1 or later

You will need Evergreen credentials on your local machine to use this library or the attached CLI. You can set up your credentials by following the link here.

Linting/formatting

This project uses black and isort for linting/formatting.

poetry run black src tests
poetry run isort src tests

Running tests

poetry run pytest

There are a few tests that are slow running. These tests are not run by default, but can be included by setting the env variable RUN_SLOW_TESTS to any value.

$ RUN_SLOW_TEST=1 poetry run pytest

To get code coverage information:

$ poetry run pytest --cov=src --cov-report=html

Changes to doc site building

Docs are built with sphinx by their recommended GitHub Action. This action is configured to use a requirements.txt from the docs subdirectory so it doesn't know anything about Poetry and Poetry doesn't know anything about Sphinx deps. But this environment also needs to know about the runtime dependencies of the evergreen package in order to auto-document the Python modules from docstrings.

This is an outline of the process you'd use to update the docs requirements.txt

poetry run python3 -m venv docs-env
. docs-env/bin/activate
pip install -r docs/requirements.txt
# if you need to change any docs-only dependencies (like sphinx or extensions/themes), upgrade them now with pip install

If you have upgraded any material runtime dependencies of the evergreen package with poetry, follow this section as well

deactivate
poetry export -f requirements.txt --output docs/runtime_requirements.txt
. docs-env/bin/activate
pip install -r docs/runtime_requirements.txt
rm docs/runtime_requirements.txt

Check that the doc site still builds

pushd docs
sphinx-build -W source build
# poke around the build output directory
popd

Finally to re-pin the docs dependencies

pip freeze > docs/requirements.txt
git add docs/requirements.txt

Automatically running checks on commit

This project has pre-commit configured. Pre-commit will run configured checks at git commit time. To enable pre-commit on your local repository run:

$ poetry run pre-commit install

Versioning

Before deploying a new version, please update the CHANGELOG.md file with a description of what is being changed.

Deployment to PyPi are done automatically on merges to master. In order to avoid overwriting a previous deploy, the version should be updated on all changes. The semver versioning scheme should be used for determining the version number.

The version is found in the pyproject.toml file.

Code Review

This project uses the GitHub merge queue. Click "Merge when ready" as soon as you'd like.

Deployment

Deployment to PyPi is automatically triggered on merges to master.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for dbradf from gravatar.com dbradf Avatar for mongodb-dev-prod from gravatar.com mongodb-dev-prod

Credits

Author: DevProd Services & Integrations Team

License

Apache Software License (Apache-2.0)

Requires

Python <3.14, >=3.9

Classifiers

Report project as malware

Download files

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

Source Distribution

evergreen_py-3.19.2.tar.gz (51.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

evergreen_py-3.19.2-py3-none-any.whl (62.6 kB view details)

Uploaded Python 3

File details

Details for the file evergreen_py-3.19.2.tar.gz.

File metadata

  • Download URL: evergreen_py-3.19.2.tar.gz
  • Upload date:
  • Size: 51.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.1.4 CPython/3.12.3 Linux/6.8.0-1008-aws

File hashes

Hashes for evergreen_py-3.19.2.tar.gz
Algorithm Hash digest
SHA256 b5e070fa7ebd18b3a8134851a306c46fc500b18804563f5fb07f10cd910808a6
MD5 43004628844fd8d361af60a44443559b
BLAKE2b-256 812ceefb341ff95709dd6e4f9f3a7916236a81397843ca2768768b1c4484b49f

See more details on using hashes here.

File details

Details for the file evergreen_py-3.19.2-py3-none-any.whl.

File metadata

  • Download URL: evergreen_py-3.19.2-py3-none-any.whl
  • Upload date:
  • Size: 62.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.1.4 CPython/3.12.3 Linux/6.8.0-1008-aws

File hashes

Hashes for evergreen_py-3.19.2-py3-none-any.whl
Algorithm Hash digest
SHA256 c48c947510df5f6350e4038b8ce45559a6ae45d03522960542525947418ef22e
MD5 6700687dd30abc501d27732984b782cf
BLAKE2b-256 a7a227eb0891c28fc1232a79bdd1f286615d02de86c5d85687557ea492af9933

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

3.19.2 This release

2 files

3.19.1

2 files

3.19.0

2 files

3.18.0

2 files

3.17.0

2 files

3.16.0

2 files

3.15.0

2 files

3.14.1

2 files

3.14.0

2 files

3.13.2

2 files

3.13.1

2 files

3.13.0

2 files

3.12.0

2 files

3.11.5

2 files

3.11.4

2 files

3.11.3

2 files

3.11.2

2 files

3.11.1

2 files

3.11.0

2 files

3.10.7

2 files

3.10.6

2 files

3.10.5

2 files

3.10.4

2 files

3.10.3

2 files

3.10.2

2 files

3.10.1

2 files

3.10.0

2 files

3.9.1

2 files

3.9.0

2 files

3.8.0

2 files

3.7.0

2 files

3.6.29

2 files

3.6.28

2 files

3.6.27

2 files

3.6.26

2 files

3.6.25

2 files

3.6.24

2 files

3.6.23

2 files

3.6.22

2 files

3.6.21

2 files

3.6.20

2 files

3.6.19

2 files

3.6.18

2 files

3.6.17

2 files

3.6.16

2 files

3.6.15

2 files

3.6.14

2 files

3.6.13

2 files

3.6.12

2 files

3.6.11

2 files

3.6.10

2 files

3.6.9

2 files

3.6.8

2 files

3.6.7

2 files

3.6.6

2 files

3.6.5

2 files

3.6.4

2 files

3.6.3

2 files

3.6.2

2 files

3.6.1

2 files

3.6.0

2 files

3.5.9

2 files

3.5.8

2 files

3.5.7

2 files

3.5.6

2 files

3.5.5

2 files

3.5.4

2 files

3.5.3

2 files

3.5.2

2 files

3.5.1

2 files

3.5.0

2 files

3.4.6

2 files

3.4.5

2 files

3.4.4

2 files

3.4.3

2 files

3.4.2

2 files

3.4.1

2 files

3.4.0

2 files

3.3.9

2 files

3.3.8

2 files

3.3.7

2 files

3.3.6

2 files

3.3.5

2 files

3.3.4

2 files

3.3.3

2 files

3.3.2

2 files

3.3.1

2 files

3.3.0

2 files

3.2.9

2 files

3.2.8

2 files

3.2.7

2 files

3.2.6

2 files

3.2.5

2 files

3.2.4

2 files

3.2.3

2 files

3.2.2

2 files

3.2.1

2 files

3.2.0

2 files

3.1.1

2 files

3.1.0

2 files

3.0.9

2 files

3.0.8

2 files

3.0.7

2 files

3.0.6

2 files

3.0.5

2 files

3.0.4

2 files

3.0.3

2 files

3.0.2

2 files

3.0.1

2 files

3.0.0

2 files

2.2.4

2 files

2.2.3

2 files

2.2.2

2 files

2.2.1

2 files

2.2.0

2 files

2.1.0

2 files

2.0.6

2 files

2.0.5

2 files

2.0.4

2 files

2.0.3

2 files

2.0.2

2 files

2.0.1

2 files

2.0.0

2 files

1.4.9

2 files

1.4.8

2 files

1.4.7

2 files

1.4.6

2 files

1.4.5

2 files

1.4.4

2 files

1.4.3

2 files

1.4.2

2 files

1.4.1

2 files

1.4.0

2 files

1.3.1

2 files

1.3.0

2 files

1.2.1

2 files

1.2.0

2 files

1.1.1

2 files

1.1.0

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

0.6.16

2 files

0.6.15

2 files

0.6.14

2 files

0.6.13

2 files

0.6.12

2 files

0.6.11

2 files

0.6.10

2 files

0.6.9

2 files

0.6.8

2 files

0.6.7

2 files

0.6.6

2 files

0.6.5

2 files

0.6.4

2 files

0.6.3

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.0

2 files

0.4.1

2 files

0.4.0

2 files

0.3.9

2 files

0.3.8

2 files

0.3.7

2 files

0.3.6

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.16

2 files

0.1.15

2 files

0.1.14

2 files

0.1.13

2 files

0.1.12

2 files

0.1.11

2 files

0.1.10

2 files

0.1.9

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page