pypd

pypd is a Python client library for PagerDuty’s v2 REST API, built by PagerDuty and released on PyPI in 2016. It wraps the API’s incidents, alerts, escalation policies, schedules, on-calls, users, and events endpoints in dict-like Entity classes, offering find/find_one/create/delete class methods and instance actions like resolve, acknowledge, and reassign for incidents.

The project has been officially deprecated by PagerDuty in favor of PDPyras, its successor library, and the last commit landed in mid-2020. It remains useful as a lightweight reference implementation of a REST-to-object mapping pattern for teams maintaining legacy integrations or studying the PagerDuty v2 API surface.

What You Get

• Entity classes for Incident, Alert, EscalationPolicy, Event/EventV2, Integration, LogEntry, MaintenanceWindow, Note, Notification, OnCall, Schedule, Service, Team, User, Vendor, and AddOn
• Class-level find, find_one, create, and delete methods plus instance helpers (resolve, acknowledge, reassign, merge, create_note) for incident workflows
• Automatic pagination via _fetch_all with an optional maximum cap, and exclude-filter support on find() results
• Environment- or code-level HTTP proxy configuration built on top of requests

Common Use Cases

• Resolving, acknowledging, or reassigning incidents from a script or cron job using a service API key
• Sending custom monitoring alerts into PagerDuty via the Events API v2 (EventV2.create)
• Pulling on-call schedules and escalation policies for internal reporting or audits

Under The Hood

Architecture - pypd centers on a single Entity base class (pypd/models/entity.py) that all seventeen resource models (Incident, Alert, Schedule, User, etc.) subclass; Entity mixes in ClientMixin (pypd/mixins.py) which resolves an api_key/base_url/proxies triple from either an explicit constructor argument or the module-level globals set on pypd.api_key, then performs the actual requests call and raises typed errors (BadRequest, UnknownError, InvalidResponse) based on status code. Querying flows through find() -> _fetch_all() -> repeated _fetch_page() calls that track offset/limit/total from the API response to auto-paginate, while fetch()/get() retrieve a single record by ID and create()/delete()/put() cover mutation. Model-specific behavior (e.g. Incident.resolve(), .acknowledge(), .reassign(), .merge()) is layered on top as thin wrappers that build the PUT payload and required from-email header.

Tech Stack - The library targets Python 2.7 and 3.5 (per tox.ini) and depends on just two runtime packages: requests for HTTP and six for py2/3 compatibility shims, declared without version pins in requirements.txt/setup.py. Packaging is classic setuptools-based (setup.py reading pypd/version.py) with no pyproject.toml, wheel metadata, or async support - a snapshot of pre-2018 Python packaging conventions.

Code Quality - test/unit/ (roughly 1,300 lines across clientmixin.py and per-model files) exercises the client with unittest, mock, and requests_mock, run via tox across the two supported interpreters; coverage is decent for HTTP-mocked request/response paths but there are no type hints anywhere in the codebase (predates Python typing conventions) and error handling in mixins.py’s _handle_response uses a bare except: when parsing JSON responses. Docstrings are present on most public methods and the Entity base class has an unusually thorough class-level docstring explaining its conventions.

API Design - The dict-like entity[‘property’]/entity.get(‘property’, default) accessor pattern plus classmethod-style find/find_one/create/delete gives a consistent, low-boilerplate surface once pypd.api_key is set globally; incident actions read naturally (incident.resolve(from_email=…)). The trade-off is implicit global mutable state (pypd.api_key, pypd.base_url, pypd.proxies module attributes) instead of an explicit client object, which is thread-unsafe and a dated pattern next to modern SDKs that instantiate a client instance per session.