I've just rediscovered how annoying it is to have to cobble together ISO8601 timestamps for when I just want to select an hour in the past or somesuch thing.

There thus needs to be an easier way to generate since and until parameters to reduce repeated work making function calls to datetime.datetime and datetime.timedelta and datetime.datetime.strftime (etc)

This is a very common beginner error when dealing with the REST API.

Filtering parameters of array type, known as "set filters", must end with [].

It would be really nice to bake this into the client.

Hi,

I'm having some issues using the EventsAPISession object. I've properly instantiated this object with a routing key obtained from the Events API v2 integration attached to my desired service. When calling the 'trigger' method, I get a deduplicate key and even took it a step further by implementing a class that returns the full response object (see below). I can see that my calls are being returned as successful according to the response code of 202 and the response body containing {'message': 'Event processed', 'status': 'success'}.

When I visit the GUI to ensure my incident fired under the desired service, there is no instance of this incident under the service or any other service for that matter. I cannot find any breaking API changes that would be causing this, so unsure how to proceed.

from pdpyras import EventsAPISession, raise_on_error, try_decoding

class EventsAPISessionWrapper(EventsAPISession):
    def send_event(self, action, dedup_key=None, **properties):
        actions = ('trigger', 'acknowledge', 'resolve')
        if action not in actions:
            raise ValueError("Event action must be one of: "+', '.join(actions))

        event = {'event_action':action}

        event.update(properties)
        if isinstance(dedup_key, str):
            event['dedup_key'] = dedup_key
        elif not action == 'trigger':
            raise ValueError("The dedup_key property is required for"
                "event_action=%s events, and it must be a string."%action)
        response = self.post('/v2/enqueue', json=event)
        raise_on_error(response)
        response_body = try_decoding(response)
        if not 'dedup_key' in response_body:
            raise PDClientError("Malformed response body; does not contain "
                "deduplication key.", response=response)
        return response

hello ,

how can I get the /audit/records?
look at https://developer.pagerduty.com/api-reference/reference/REST/openapiv3.json/paths/~1audit~1records/get

thanks
sorin

I'm thinking that instead of the current verbose mess, we could make it loosely follow the same structure as the general API documentation while briefly introducing all the cool ways that the implementation of that stuff is handled by the client.

https://developer.pagerduty.com/docs/ZG9jOjQ2NDA2-introduction

Adding a user to a team with client.rput(f'teams/{team}/users/{user}') raises PDHTTPError from JSONDecodeError encountered trying to decode response text. The raw response from put is a 204 with no content.

Removing a user from a team with client.rdelete(f'teams/{team}/users/{user}') does not raise the same error even though the raw response is also a 204 with no content.

Reproduce with the following:

from pdpyras import APISession, PDClientError

# Action is missing an extra layer of bracket 
# valid format is:
# 'actions': [['route', '<INSERT_SERVICE_ID>']]
payload = {'condition': ['and', ['contains', ['path', 'payload', 'source'], 'website'], ['contains', ['path', 'payload', 'source'], 'api']], 'actions': ['route', '<INSERT_SERVICE_ID>']}

try: 
    session = APISession(api_token)
    provision_event_rules = session.post("/event_rules", json=payload )
    print(provision_event_rules.status_code) # prints 400
    # prints: {'rules': [{'actions': ['expected array, received Elixir.Api.Schemas.MixedList']}]}
    print(provision_event_rules.json()) 
except PDClientError as e:
   print(e.response)
   print(e.response.url)
   print(e.response.text)

Never returns the 400 response

Hello!

I've been tinkering with the EventsAPISession and notice that if you set a payload it will completely ignore the summary, source and severity instead of merging it with the payload as the docstring says.

Here's the override:
https://github.com/PagerDuty/pdpyras/blob/master/pdpyras.py#L641

I wouldn't mind setting either kwargs OR payload, but right now to make a valid event with any of the fields not supported by the kwargs (component, group and class) if have to do it like this because summary and source are not optional:

session = pdpyras.EventsAPISession(routing_key)

dedup_key = session.trigger(
    summary='ignored',
    source='ignored',
    payload={
        'summary': 'actual summary',
        'source': 'actual source',
        'severity': 'critical',
        'component': 'a component',
        'group': 'a group',
        'class': 'a class',
    },
    custom_details={
        'this': 'works'
    },
)

So maybe:

• Payload could merge as said in the docstring
• Payload could be extra_payload_args
• Payload could be removed to add **kwargs (or add class, component, and group as params)

Just a suggestion,
Thank you

Hello,

I'm trying to query the PD Analytics API but I get a permission error: API responded with non-success status (403)

Based on the documentation, it seems that we have to pass the X-EARLY-ACCESS header in order to use it.

Is there a way to do this using this client?

Thanks

The example incident creation code fails with a 400 "You must specify a user's email address in the "From" header to perform this"

Traceback:

Traceback (most recent call last):
  File "/Users/jpb/Dropbox/s/pdcrier/bin/examplecode", line 20, in <module>
    pd_incident = session.rpost("incidents", json=payload)
  File "/Users/jpb/Library/Caches/pypoetry/virtualenvs/pdcrier-4jRKjqUa-py3.9/lib/python3.9/site-packages/pdpyras.py", line 145, in call
    r = raise_on_error(method(self, path, **pass_kw))
  File "/Users/jpb/Library/Caches/pypoetry/virtualenvs/pdcrier-4jRKjqUa-py3.9/lib/python3.9/site-packages/pdpyras.py", line 78, in raise_on_error
    raise PDHTTPError("%s %s: API responded with non-success status "
pdpyras.PDHTTPError: POST /incidents: API responded with non-success status (400): {"error":{"message":"You must specify a user's email address in the \"From\" header to perform this

See branch: https://github.com/PagerDuty/pdpyras/tree/hotfix-check-api-key-user-or-account-level

This just needs a bit of review and potential neatening up.

When I have code like the following:

from pdpyras import APISession

api_token = '<redacted>'
session = APISession(api_token)

for incident in session.iter_all('incidents', params={'service_ids[]': ['<redacted>'], 'since': '2020-08-01T00:00:00Z'}):
    print("{id}\t{created_at}\t{html_url}\t{description}\t{resolve_reason}".format(**incident))

I only get around 25 incidents. If I change the since date, I get a different 25-ish incidents, so it seems like the pagination isn't working. (Also, I know from the PD website that there are definitely much more than 25 incidents for this query).

Any ideas?

Thanks.

In the section Using HTTP client library features there's no mention of how APISession itself is a child class of requests.Session.

This could be an opportunity to both point this out and document an asked-about use case as an example of what that means.

(as asked in #47)

Hi,

When posting to /schedules/{id}/overrides, logic defined here (https://github.com/PagerDuty/pdpyras/blob/main/pdpyras.py#L130):

if is_index and http_method=='get' or multi_put:
            # Plural resource name, for index action (GET /<resource>), or for
            # multi-update (PUT /<resource>). In both cases, the response
            # (former) or request (latter) body is {<resource>:[<objects>]}
            envelope_name = resource
        else:
            # Individual resource create/read/update
            # Body = {<singular-resource-type>: {<object>}}
            envelope_name = envelope_name_single

leads to the latter case in which we are updating an individual resource which is not the case. Specifically:

• is_index is true because url has 3 parts
• http_method is POST, so we fail in the else part

As a consequence, when performing session.rpost('/schedules/{id}/overrides', json=overrides), overrides provided are being encapsulated as a "override" property of an object.

Workaround is to pass overrides as:
overrides = {
overrides= [ ... ],
override = ''
}
Then, as override property is present, the whole object is being sent.

I'm really liking pdpyras for working with the PagerDuty API, however it would be really nice if could support the Events API too. As low level handling rate limits and errors for sending events from custom applications would be really helpful.

Usage would be something like:

from pdpyras import EventSession

integration_key = 'your-token-here'
session = EventSession(integration_key)

event = {}

session.enqueue(event)

The log_entries endpoint is similar to escalation_policies in terms of how it is pluralized / de-pluralized and so iter_all wouldn't work with it.

There is an assumption in resource_envelope used for rget/rpost/rput and list_all functions that the name of the resource provided in the url path is the same as the name of the resource that comes back in the API response:
https://github.com/PagerDuty/pdpyras/blob/main/pdpyras.py#L127
https://github.com/PagerDuty/pdpyras/blob/main/pdpyras.py#L1138

However this doesn't always seem to be the case. For the event orchestrations APIs, the url path is /event_orchestrations and the response contains "orchestrations" or "orchestration_path" for the router/unrouted/service APIs
https://developer.pagerduty.com/api-reference/7ba0fe7bdb26a-list-event-orchestrations

so the result of list_all is a KeyError at pdpyras.py:1187
KeyError: 'event_orchestrations'

It's not yet possible to set a page size for different endpoints/iteration calls apart from setting the default_page_size property.

Looks we can't use same key with different values in dict and pass to params.
But on server side it supports To query multiple statuses, pass statuses[] more than once,
https://developer.pagerduty.com/api-reference/9d0b4b12e36f9-list-incidents.

        params = {
            'statuses[]': 'acknowledged',
            'statuses[]': 'triggered',
            'statuses[]': 'resolved',
        }
        for incident in session.iter_all('incidents', params):
            yield incident

Our enterprise network require to use a proxy to access https://api.pagerduty.com. I can't find a way to set the proxy for EventAPISession. Can someone here provide some helps our point me to the correct instructions/docs?

Committing doc rebuilds manually is getting really old. It's also contributing to bloat of the repo.

Acceptance criteria: there is an automated build and publish of docs (i.e. with CircleCI or GitHub Actions) so that changes to the restructured text / docstrings don't need doc rebuild commits and we can remove/git-ignore the built docs.

PyPI pdpyras package requires Python versions >=3.5:
https://pypi.org/project/pdpyras/

Yet README suggests support is up to v3.8:

Tested in / support for Python 2.7 through 3.8
(source: https://github.com/PagerDuty/pdpyras/tree/v4.4.0#features)

This needs clarification, please.

When I trigger an event like below the dedup key does not appear anywhere on the resulting incident. Is this a bug or am I doing something wrong? My understanding is it would show up there and be usable for querying for the incident post creation.

session = EventsAPISession(token)
# all parameters are variables omitted here 
response = session.trigger(
        summary, source, dedup_key, severity,
        payload, custom_details, images, links)

We are using below function to resolve the incident

def resolve_incident(self, incident_ids):
    for incident_id in incident_ids:
        incident = self.session.rget("incidents/" + incident_id)
        try:
            if incident['status'] != 'resolved':
                self.session.rput(
                    "incidents",
                    json=[{'id': incident_id, 'type': 'incident_reference', 'status': 'resolved'}]
                )
            else:
                print "Incident: " + incident_id + " is already resolved!"
        except PDClientError:
            print "Could not resolve incident: " + incident_id
            traceback.print_exc()
            raise RuntimeError("Could not resolve incident: " + incident_id)
    return True

suddenly its started throwing below error :
PDClientError: PUT /incidents: API responded with non-success status (400)

 As per my finding there is some issue with rput
Is anything changes in the pagerduty API ? or in pdpyras ?

The rput, rpost, and rget methods aren't guaranteed to work for the experimental / undocumented endpoints, but were intended for the "mainstream" endpoints that follow the self-similar pattern wherein the envelope property name follows from the resource name.

This has caused some user error and confusion when using it for experimental endpoints that contain exceptions to this pattern.

Hi There,

First off, this is a great project and I'm really enjoying using it. I've written a few things so far and they work well.

However, I'm in a spot where I'm trying to assemble a full user list of specific elements (e.g. query all users and their emails, roles, teams, tags) and well, the TAGS api is completely separate and while of course I can write against just a regular client, it would be great if that was another component of pdpyras so I can easily pull it all together.

Thanks!

I am trying to create an event, and then create another event with the same dedup. I expect that there will be 2 alerts in the same incident, however there is only 1 (new summary), which means that the alert is overwritten.

This is my code:

from pdpyras import EventsAPISession


class PagerDutyApi:
    def __init__(self, integration_key: str) -> None:
        self._session = EventsAPISession(integration_key)

        # Returns the dedup key
        dedup = self._session.trigger(summary='test summary', source='val1', severity='info')
        self._session.trigger(summary='new summary', source='val1', severity='info', dedup_key=dedup)


PagerDutyApi('Dummy-Integration-Key')

See:

https://v2.developer.pagerduty.com/docs/oauth-2-functionality-client-secret

This may require a child class of APISession, unless the client_secret is formatted in such a way that it is always distinguishable from REST API tokens.

If performing updates or deletions through the API to objects that are part of the set being iterated over, then the iteration will skip over records when the following happens:

1. The set in itself changes due to updates/deletions to the objects in the set which render them not applicable to the filter being used for iteration (and if deletion occurs then no filter will match them)
2. The offset in pagination will reflect paging through the set as it was prior to the updates
3. Therefore, objects that would be in the next page instead end up on the previous page after the update, because the offset changes by more than the objects shift due to previous objects getting removed from the set

Ideas for addressing this:

• Warning messages when performing deletion or update to a resource when iteration is currently in progress for that same resource (prompting the developer to use list_all and pre-fetch records instead of iter_all
• Preferred update_all or delete_all pagination methods that have some clever way of checking for deletion/insertion and adjust the offset accordingly - or just pre-fetch set members' resource URLs before proceeding - and fulfill the bulk-update / bulk-delete need.

I just noticed this error when trying to use your library to retrieve my organization's log entries

>>> data_list = session.list_all('log_entries')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/gtang/.pyenv/versions/etl_env/lib/python3.6/site-packages/pdpyras.py", line 1074, in list_all
    return list(self.iter_all(path, **kw))
  File "/Users/gtang/.pyenv/versions/etl_env/lib/python3.6/site-packages/pdpyras.py", line 999, in iter_all
    r.status_code, path), response=r)
pdpyras.PDClientError: Encountered HTTP error status (400) response while iterating through index endpoint log_entries.

Not sure if the error is coming from PagerDuty's API or your wrapper but I figure I post this issue here

The following line in pdpyras.py:

Is then redefined as:

This causes pylint to throw the following error about unsupported-assignment-operation, but only when the module is installed via pip.

test.py:11:4: E1137: 'session.retry' does not support item assignment (unsupported-assignment-operation)

The following test file reports the above error when 4.0 is installed via pip, but not when the file is in a checkout of pypdras.

"""Test Pdpyras file for pylint error."""


from pdpyras import APISession


def main(api_key=None):
    """Main function"""
    session = APISession(api_key=api_key)

    session.retry[404] = 5
    session.max_http_attempts = 4
    session.sleep_timer = 1
    session.sleep_timer_base = 2

    response = session.get('/users/PNOEXST')

    return response

if __name__ == '__main__':
    print(main(api_key=None))

Confirmed changing the None to {} fixes the issue. So I'll raise a PR.

A nice-to-have.

The cooldown time increases by a constant factor after each attempt. If there are many concurrent API requests, they will all retry at exactly the same time.

E.G.

import random
...
                sleep_timer *= self.sleep_timer_base*(1+random.random())

It's really bad practice to hard-code API keys. Our code examples should reflect that.

We could just do this to begin with:

api_key = os.env.get('PD_API_KEY')

EventsAPISession uses the X-Routing-Key header to specify the routing key and does not set the routing_key parameter in the REST Payload.

API specification requires that the routing_key parameter is a required parameter.

https://developer.pagerduty.com/docs/events-api-v2/trigger-events/

For example,

Causes the following deprecation warning.

DeprecationWarning: invalid escape sequence \*

Here's a reproduction.

import warnings
warnings.simplefilter("always")
x = "\*\*kwargs"
# <stdin>:1: DeprecationWarning: invalid escape sequence \*

Definitely not a pressing issue, but it pollutes my build logs. I'd suggest adding another slash (e.g., \\*). Sphinx appears to render \\* and \* the same way. For example, here's how they both render on a sample site.

There's no way to handle this new type of pagination currently except with a custom implementation.

Moreover, iter_all was written during a time when nearly all API index endpoints followed the same pattern: of alternating IDs and resource names in the path. The only endpoint that currently supports cursor pagination is the newer audit trail API that breaks from this pattern.

There will need to be some kind of generalization of iteration that can encompass this new scenario (which breaks away from the pattern that was once ubiquitous) and does what's needed to support cursor-based pagination.

The Pdpyras 5.0.0 released an hour ago misses deprecation module in install_requires.

The deprecation module is imported here:

https://github.com/PagerDuty/pdpyras/blob/main/pdpyras.py#L17

This has been detected by Airflow's canary builds (pdpyras is used by pagerduty provider of Airflow).

On python 3.10
https://github.com/PagerDuty/pdpyras/blob/main/pdpyras.py#LL787C1-L790C26
Throws an TypeError: not enough arguments for format string error, because no variable is available to be inserted. Suggest rewriting like

        return (
            f"{endpoint}: Success (status {r.status_code}) but an expectation still " \
            f"failed{context_msg}"
        )

This happens when using the paged request for oncall. e.g.

    user_params = {
        "time_zone": TZ_NAME,
        "since": ts["start"].isoformat(),
        "until": ts["end"].isoformat(),
    }

    oncalls = session.iter_all(
        "oncalls", params=user_params, page_size=MAX_ITEMS)
    final_report_rows = {}
    for o in oncalls:

Line 1157 raises an uncaught key error when a 500 is returned, as the request_id is not in the header. https://github.com/PagerDuty/pdpyras/blob/master/pdpyras.py#L1157

The request_id is already available, so this can simply read:

if int(status) == 500:
            self.log.error("PagerDuty API server error (%d)! "
                "For additional diagnostics, contact PagerDuty support "
                "and reference x_request_id=%s / date=%s",
                status, request_id, request_date)

I have a branch ready to go, but i don't have push access to this repo.

Receive TypeError when doing the following

>>> rp = list(session.iter_all("response_plays"))
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "D:\Users\[user]\AppData\Local\Programs\Python\Python39\lib\site-packages\pdpyras.py", line 1058, in iter_all
    offset += data['limit']
TypeError: unsupported operand type(s) for +=: 'int' and 'NoneType' ```

Same error occurs with list_all and dict_all. Able to receive list via rget method only

👋 Hey there @Deconstrained 😄. I'm observing a behavior where the changes from here: bab0368#diff-60f61ab7a8d1910d86d9fda2261620314edcae5894d5aaa236b821c7256badd7R3 seem to be manifesting as the following issue upon installation of release 4.5.1.

I assume that anyone else that doesn't explicitly specify requests as a requirement of their own would see the same since this occurs before pdpyras can install its own requests requirement.

Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "/tmp/pip-install-h5zdz16c/pdpyras/setup.py", line 3, in <module>
        from pdpyras import __version__
      File "/tmp/pip-install-h5zdz16c/pdpyras/pdpyras.py", line 13, in <module>
        import requests
    ModuleNotFoundError: No module named 'requests'

It looks like this was able to sneak by CI checks due to the one-off requirements.txt install happening here:

The X-Request-Id response header should always contain a UUID that PagerDuty Support can use to track down the full trace of a HTTP request through the public API, so that the reason for a 5XX can be more quickly investigated.

This API client should really be logging this response header, at the very least for server error responses.

Using:
session.list_all('schedules')

I get:

...
HTTP or network error: ReadTimeout: HTTPSConnectionPool(host='api.pagerduty.com', port=443): Read timed out. (read timeout=5); retrying in 12 seconds.

Until it errors for exceeding the maximum number of attempts to connect to the API.

This only happens when making the request on a PagerDuty account with thousands of schedules. The same request works fine with an account with only hundreds of schedules. Also, the same style request works fine for other endpoints (objects).

The same call using requests.get() with paging works fine. I couldn't replicate the issue after copying headers and so on.

Thank you.

To give developers the option of using functions that return JSON in all cases, there should be a set of functions that don't bother unpacking the object from the envelope, but that at least return the JSON and raise an exception if there's a HTTP error. This will make it easier to work with unconventional / early-access / experimental endpoints.

iter_all('incidents', params={'service_ids': [service_id]})

fails with 400 with the error

'{"error":{"message":"Invalid Input Provided","code":2001,"errors":["Service ids must be a Array."]}}'

API V2 and pdpyras 4.3.0

#86 was about the team membership API not working with rput. While this is expected, the docs state:

They can still be used with the basic get, post, put and delete methods, as well as the j* methods

This would however not be the case for the team membership API, which responds with status 204 / no content (empty body). That would result in a JSONDecodeError if one used jput.

Alternately, #88 will also resolve this issue.

• Nice-to-have / Syntactic sugar
• Doesn't need to have explicitly defined schemas; can start with type/resource and ID and then "inherit" from API responses
• If possible: detect changes, know what the minimum required mandatory fields are for updates (i.e. ID and type) and then PUT only the changes + required fields.
• Ideally can access properties as property names, i.e. model.field_name

Would need figure out how this could help us internally, i.e. how easy it would be to eliminate code duplication.

If the body is empty, it seems appropriate to return None from try_decoding rather than raise JSONDecodeError.

This will resolve #87 by allowing j* methods to be used on endpoints that may respond with 204 / no content to request methods other than DELETE, i.e. the add-user-to-team endpoint.

I would like to use the API to change and escalation_rules target from a schedule_reference to a user_reference.

I am getting all the Escalation Policies like so

services = list(session.iter_all('escalation_policies', params={'query': 'myquery'}))

How could I go through them and update the escalation_rules target?