Feature Request: Async Support for API Client(s)

[jamestexas]

Howdy! Apologies if this doesn't adhere to community guidelines, I didn't see anything about submitting questions / issues.

I'm a frequent user of this SDK and appreciate the work put into it. I recently faced a challenge while trying to use the PagerDuty API with asynchronous Python. Since the current implementation relies on the requests library, it doesn't support async operations out of the box.

I'm aware that transitioning to async isn't a minor task, especially considering the need to maintain compatibility with existing sync functionalities. However, libraries like httpx could be a potential solution, offering strong compatibility with requests and support for both sync and async operations.

Are there any plans or roadmap items to introduce async support for the API clients? Adding this feature would greatly enhance the utility of the library for async applications.
If this is something the maintainers are considering, I'd be willing to contribute to the development of this feature.

Thanks for your time and consideration!

[Deconstrained]

Greetings!

There are no plans for this yet, but this is interesting and has me thinking of the requirements and scope of such an undertaking. Given the similarities between the underlying client libraries, superficially, a lift-and-replace might not be too many changes.

It would be great to hear more about what the goals and requirements are, i.e. the desired outcomes of such a refactor and how one would/could ultimately use it. What isn't clear to me yet is what asynchronous usage of the new API client would look like, as distinct from how it is used currently. This might help us figure out what additional changes would be needed in each feature of the API client to make them usable in asynchronous applications. For instance, how would APISession.iter_all need to change for asynchronous use?

It wouldn't be a dealbreaker to me if it results in the client needing an overhaul or deep class hierarchy refactor for backwards compatibility. I've been mulling over the idea of negotiating with PyPI to rename the module to pagerduty. The incumbent module's last release was over ten years ago and it only supports the "Service API" which is the legacy name of Events API v1, so I think there's a strong case for it. Part of this big change would be renaming the client classes to be more descriptive, i.e. RestApiV2Client. Dovetailing this with adding support for asynchronous usage would probably give us more flexibility with regard to how we can strategize changes to classes, as we would at that point already be deprecating classes and instructing implementers to swap them out for the new client.

Super late edit: because I keep losing the link to the request and I thought this was as good a place to put it as any:
pypi/support#3589
(The request to transfer ownership of the pagerduty library on PyPI)

[jamestexas]

Glad to hear there’s interest in exploring async! My experience transitioning a project to httpx, despite minor differences like its default redirect behavior, was quite smooth.

Requirements in my opinion could probably be the various rest (get / put / post etc) methods having async variants and potentially the find / iter_all methods.

My primary use case for async would be with the /incidents endpoint. Here, an async client could significantly streamline the process of retrieving, acknowledging, and processing incidents (such as adding alerts and log_entries) especially as each await during API calls would enable more efficient context switching.

Specifically, using an async generator for iter_all would allow processing incidents concurrently, enhancing responsiveness. I observed this first hand when toying with a TUI for personal use with sync requests. Note that usage patterns would change; for example, we’d use [i async for i in iter_all()] instead of list(await iter_all()) I’ve personally observed other repos prefix an a to method names to denote the async variants.

Any method making network calls would need to be async to prevent blocking. HTTPX also features connection pooling, which could be beneficial here. I’m open to assisting with this transition, especially with APISession and related areas.

[Deconstrained]

I've been working on a lift-and-shift to httpx as a side project but have run into quite a few difficulties/incompatibilities with the new interface. I might try to tackle this again after we move to the new project name.

[Deconstrained]

(New issue in new project: PagerDuty/python-pagerduty#33)