Install & Compatibility
Where this runs
tested against v5.4.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.362s · 21.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.1s · import 0.340s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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}")
Debug
Known issues
breakingThe `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.fixFor 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.
affects: All versions, especially 5.4.1 and later which include deprecation warnings.
breakingWhen 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`.fixUpdate import statements and class instantiations according to the 'PDPYRAS Migration Guide'. E.g., `s/APISession/RestApiV2Client/g` and `s/pdpyras/pagerduty/g`.
affects: Migrating from any `pdpyras` version to `python-pagerduty` (version 1.0.0+).
gotchaWhen 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.fixInitialize `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.
affects: All versions.
gotchaError 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`.fixFor 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.
affects: All versions.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pdpyras'
The 'pdpyras' library is not installed in the current Python environment or the Python interpreter cannot locate it in its search path.
fixInstall the library using pip: `pip install pdpyras`.
pdpyras.PDClientError: Received 401 Unauthorized response from the API. The key (...xxxx) may be invalid or deactivated.
The PagerDuty API key provided to `pdpyras.APISession` is incorrect, has expired, been revoked, or lacks the necessary permissions for the requested operation.
fixVerify your PagerDuty API key by checking it in the PagerDuty UI (API Access Keys) and ensure it is active and has the appropriate scopes. Regenerate the key if necessary.
pdpyras.PDClientError: GET /some/endpoint: API responded with non-success status (400).
This is a general client-side error indicating a bad request was sent to the PagerDuty API, often due to incorrect parameters, a malformed URL, invalid data in the payload, or exceeding API limits (e.g., pagination limits).
fixCarefully examine the request parameters, URL, and payload for syntax errors, incorrect data types, or values that violate PagerDuty API constraints for the specific endpoint. Consult the PagerDuty API documentation for the endpoint you are calling.
The package "pdpyras" is deprecated and as of 2025-06-20 will no longer receive updates. Please use "pagerduty" instead. Migration guide: https://pagerduty.github.io/python-pagerduty/pdpyras_migration_guide.html
The `pdpyras` library has been officially deprecated by PagerDuty in favor of the `python-pagerduty` library, and version 5.4.1 (the final bugfix release) now explicitly issues this warning upon import.
fixFor new projects, use `pip install pagerduty`. For existing projects, migrate your codebase to use the `python-pagerduty` library by following the provided migration guide to replace `pdpyras` with the new client.
Upgrade
Version history
5.4.1latest on PyPI · released Jun 3, 2025
Audit
Dependencies
requestsrequiredCore HTTP client library extended by pdpyras.
deprecationoptionalUsed internally for handling deprecation warnings.