{"id":1855,"library":"pdpyras","title":"PagerDuty Python REST API Sessions (pdpyras)","description":"pdpyras is a lightweight Python client that provides an opinionated wrapper around the Requests HTTP library for interacting with the PagerDuty REST API v2 and Events API v2. It aims to simplify common tasks like authentication, pagination, and error handling. The library currently supports Python 3.6 through 3.13, with version 5.4.1 being the latest release. However, this library has been officially deprecated by PagerDuty in favor of `python-pagerduty` since early 2025, with version 5.4.1 being the final bugfix release that also introduces a deprecation warning upon import.","status":"deprecated","version":"5.4.1","language":"en","source_language":"en","source_url":"https://github.com/PagerDuty/pdpyras","tags":["pagerduty","api","rest","events","requests","deprecated"],"install":[{"cmd":"pip install pdpyras","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core HTTP client library extended by pdpyras.","package":"requests"},{"reason":"Used internally for handling deprecation warnings.","package":"deprecation","optional":true}],"imports":[{"note":"Used for interacting with the PagerDuty REST API v2.","symbol":"APISession","correct":"from pdpyras import APISession"},{"note":"Used for interacting with the PagerDuty Events API v2.","symbol":"EventsAPISession","correct":"from pdpyras import EventsAPISession"},{"note":"A specialized session for the Change Events API (part of Events API v2).","symbol":"ChangeEventsAPISession","correct":"from pdpyras import ChangeEventsAPISession"},{"note":"The base session class, typically used indirectly through its subclasses.","symbol":"PDSession","correct":"from pdpyras import PDSession"}],"quickstart":{"code":"import os\nfrom pdpyras import APISession\n\n# Retrieve PagerDuty API key and 'From' email from environment variables\n# It's highly recommended to use environment variables for sensitive data.\nAPI_KEY = os.environ.get(\"PAGERDUTY_API_KEY\", \"YOUR_PAGERDUTY_API_KEY\")\n# For account-level API keys, a 'From' header (user email) is often required\n# for write operations to certain endpoints. Use a valid PagerDuty user email.\nDEFAULT_FROM_EMAIL = os.environ.get(\"PAGERDUTY_FROM_EMAIL\", \"your_email@example.com\")\n\nif API_KEY == \"YOUR_PAGERDUTY_API_KEY\":\n    print(\"WARNING: PAGERDUTY_API_KEY environment variable not set. Using placeholder.\")\nif DEFAULT_FROM_EMAIL == \"your_email@example.com\":\n    print(\"WARNING: PAGERDUTY_FROM_EMAIL environment variable not set. Using placeholder.\")\n\ntry:\n    # Initialize a PagerDuty REST API v2 session.\n    # For user-level API keys, `default_from` might be inferred or not needed.\n    # For account-level API keys, it is often essential for POST/PUT operations.\n    session = APISession(API_KEY, default_from=DEFAULT_FROM_EMAIL)\n\n    # Example: Fetch and print the first 2 incidents that are currently triggered or acknowledged.\n    print(\"\\nFetching recent incidents (triggered or acknowledged)...\")\n    incidents = session.list_all(\n        'incidents',\n        params={'statuses[]': ['triggered', 'acknowledged'], 'limit': 2}\n    )\n\n    if incidents:\n        for i, incident in enumerate(incidents):\n            print(f\"Incident {i+1}: ID={incident['id']}, Summary='{incident['summary']}', Status={incident['status']}')\")\n    else:\n        print(\"No incidents found or an issue occurred with the API call.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions, especially 5.4.1 and later which include deprecation warnings."},{"fix":"Update import statements and class instantiations according to the 'PDPYRAS Migration Guide'. E.g., `s/APISession/RestApiV2Client/g` and `s/pdpyras/pagerduty/g`.","message":"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`.","severity":"breaking","affected_versions":"Migrating from any `pdpyras` version to `python-pagerduty` (version 1.0.0+)."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions."},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}