PagerDuty Python REST API Sessions (pdpyras)

Warnings

• breaking The `pdpyras` library is officially deprecated by PagerDuty. For all new projects, use the `python-pagerduty` library instead, which is its successor. Existing projects should also consider migrating.
  Fix: For new projects, `pip install pagerduty` and use `from pagerduty.api import RestApiV2Client` (or other new client classes). For existing projects, refer to the 'PDPYRAS Migration Guide' in the `python-pagerduty` documentation for class and method name changes.
• breaking When migrating from `pdpyras` to `python-pagerduty`, many class and exception names have changed. For example, `APISession` becomes `RestApiV2Client`, `EventsAPISession` becomes `EventsApiV2Client`, and `PDClientError` becomes `Error`.
  Fix: Update import statements and class instantiations according to the 'PDPYRAS Migration Guide'. E.g., `s/APISession/RestApiV2Client/g` and `s/pdpyras/pagerduty/g`.
• gotcha When using an account-level API key (created by an administrator) for REST API v2 endpoints that take actions on incidents (e.g., creating notes, resolving), you must supply the `default_from` keyword argument to the `APISession` constructor with a valid PagerDuty user's email address. Failing to do so will result in an `HTTP 400` response.
  Fix: Initialize `APISession` with `session = APISession(api_key, default_from='user@example.com')`. If using a user's API key, this is often not necessary as the user is derived from the key itself.
• gotcha Error handling differentiates between low-level `requests`-like methods (`get`, `post`) which return `requests.Response` objects even on HTTP errors, and higher-level methods (`list_all`, `iter_all`) which raise `pdpyras.PDClientError` (or its subclasses) on non-success HTTP statuses after exhausting retries. A `401 Unauthorized` error will immediately raise `PDClientError`.
  Fix: For low-level methods, check `response.raise_for_status()` or `response.status_code`. For high-level methods, wrap calls in `try...except pdpyras.PDClientError`. Inspect `PDClientError.response` for the underlying `requests.Response` object.

Install

• pip install pdpyras Install latest version

Imports

• APISession

  from pdpyras import APISession

  Used for interacting with the PagerDuty REST API v2.
• EventsAPISession

  from pdpyras import EventsAPISession

  Used for interacting with the PagerDuty Events API v2.
• ChangeEventsAPISession

  from pdpyras import ChangeEventsAPISession

  A specialized session for the Change Events API (part of Events API v2).
• PDSession

  from pdpyras import PDSession

  The base session class, typically used indirectly through its subclasses.

Quickstart

This quickstart demonstrates how to initialize an `APISession` and fetch PagerDuty incidents. It emphasizes using environment variables for API keys and `default_from` email for security and proper API usage, especially with account-level keys. Replace placeholders with your actual PagerDuty API key and a valid PagerDuty user email.

import os
from pdpyras import APISession

# Retrieve PagerDuty API key and 'From' email from environment variables
# It's highly recommended to use environment variables for sensitive data.
API_KEY = os.environ.get("PAGERDUTY_API_KEY", "YOUR_PAGERDUTY_API_KEY")
# For account-level API keys, a 'From' header (user email) is often required
# for write operations to certain endpoints. Use a valid PagerDuty user email.
DEFAULT_FROM_EMAIL = os.environ.get("PAGERDUTY_FROM_EMAIL", "your_email@example.com")

if API_KEY == "YOUR_PAGERDUTY_API_KEY":
    print("WARNING: PAGERDUTY_API_KEY environment variable not set. Using placeholder.")
if DEFAULT_FROM_EMAIL == "your_email@example.com":
    print("WARNING: PAGERDUTY_FROM_EMAIL environment variable not set. Using placeholder.")

try:
    # Initialize a PagerDuty REST API v2 session.
    # For user-level API keys, `default_from` might be inferred or not needed.
    # For account-level API keys, it is often essential for POST/PUT operations.
    session = APISession(API_KEY, default_from=DEFAULT_FROM_EMAIL)

    # Example: Fetch and print the first 2 incidents that are currently triggered or acknowledged.
    print("\nFetching recent incidents (triggered or acknowledged)...")
    incidents = session.list_all(
        'incidents',
        params={'statuses[]': ['triggered', 'acknowledged'], 'limit': 2}
    )

    if incidents:
        for i, incident in enumerate(incidents):
            print(f"Incident {i+1}: ID={incident['id']}, Summary='{incident['summary']}', Status={incident['status']}')")
    else:
        print("No incidents found or an issue occurred with the API call.")

except Exception as e:
    print(f"An error occurred: {e}")