Merge pull request #124 from PagerDuty/v5.2.0-updated-retry-logic

v5.1.2 Updates

.circleci/config.yml

@@ -1,9 +1,5 @@
 version: 2.1
 
-pip: &pip
-  name: Install Pip
-  command: |
-    sudo apt update && sudo apt install python-pip python-virtualenv
 venv: &venv
   name: Setup Virtualenv
   command: |
@@ -31,11 +27,9 @@ jobs:
 
   py3_6:
     docker:
-      - image: circleci/python:3.6-buster
+      - image: cimg/python:3.6
     steps:
       - checkout
-      - run:
-          <<: *pip
       - run:
           <<: *venv
       - run:
@@ -47,11 +41,9 @@ jobs:
 
   py3_7:
     docker:
-      - image: circleci/python:3.7-buster
+      - image: cimg/python:3.7
     steps:
       - checkout
-      - run:
-          <<: *pip
       - run:
           <<: *venv
       - run:
@@ -63,11 +55,9 @@ jobs:
 
   py3_8:
     docker:
-      - image: circleci/python:3.8-buster
+      - image: cimg/python:3.8
     steps:
       - checkout
-      - run:
-          <<: *pip
       - run:
           <<: *venv
       - run:
@@ -79,11 +69,9 @@ jobs:
 
   py3_9:
     docker:
-      - image: circleci/python:3.9-buster
+      - image: cimg/python:3.9
     steps:
       - checkout
-      - run:
-          <<: *pip
       - run:
           <<: *venv
       - run:
@@ -95,11 +83,23 @@ jobs:
 
   py3_10:
     docker:
-      - image: circleci/python:3.10-buster
+      - image: cimg/python:3.10
     steps:
       - checkout
       - run:
-          <<: *pip
+          <<: *venv
+      - run:
+          <<: *getenv
+      - run:
+          <<: *depinst
+      - run:
+          <<: *test
+
+  py3_11:
+    docker:
+      - image: cimg/python:3.11
+    steps:
+      - checkout
       - run:
           <<: *venv
       - run:
@@ -118,4 +118,5 @@ workflows:
       - py3_8
       - py3_9
       - py3_10
+      - py3_11
 

CHANGELOG.rst

@@ -1,3 +1,9 @@
+**2023-09-12: Version 5.1.2:**
+
+* Address issue `#115 <https://github.com/PagerDuty/pdpyras/issues/115>`_ by adding default values to :attr:`pdpyras.PDSession.retry` for Events and Change Events API client classes
+* Upgrade CI images
+* Add support for Python 3.11
+
 **2023-07-18: Version 5.1.1:**
 
 * Fix bug: using ``iter_all`` on an endpoint that supports cursor-based pagination should correctly call out to ``iter_cursor`` (it was making the call but with a removed keyword argument)

README.rst

@@ -22,7 +22,7 @@ manipulated through APIs are left to the user or implementer to make.
 Features
 --------
 - Uses Requests' automatic HTTP connection pooling and persistence
-- Tested in / support for Python 3.6 through 3.10
+- Tested in / support for Python 3.6 through 3.11
 - Abstraction layer for authentication, pagination, filtering and wrapped
   entities
 - Configurable cooldown/reattempt logic for handling rate limiting and

docs/_static/documentation_options.js

@@ -1,6 +1,6 @@
 var DOCUMENTATION_OPTIONS = {
     URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
-    VERSION: '5.1.1',
+    VERSION: '5.1.2',
     LANGUAGE: 'en',
     COLLAPSE_INDEX: false,
     BUILDER: 'html',

docs/changelog.html

@@ -6,7 +6,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
 
-    <title>Changelog &#8212; PagerDuty Python REST API Sessions 5.1.1 documentation</title>
+    <title>Changelog &#8212; PagerDuty Python REST API Sessions 5.1.2 documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
     <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
@@ -37,6 +37,12 @@
 
   <section id="changelog">
 <h1>Changelog<a class="headerlink" href="#changelog" title="Permalink to this heading">¶</a></h1>
+<p><strong>2023-09-12: Version 5.1.2:</strong></p>
+<ul class="simple">
+<li><p>Address issue <a class="reference external" href="https://github.com/PagerDuty/pdpyras/issues/115">#115</a> by adding default values to <a class="reference internal" href="module_reference.html#pdpyras.PDSession.retry" title="pdpyras.PDSession.retry"><code class="xref py py-attr docutils literal notranslate"><span class="pre">pdpyras.PDSession.retry</span></code></a> for Events and Change Events API client classes</p></li>
+<li><p>Upgrade CI images</p></li>
+<li><p>Add support for Python 3.11</p></li>
+</ul>
 <p><strong>2023-07-18: Version 5.1.1:</strong></p>
 <ul class="simple">
 <li><p>Fix bug: using <code class="docutils literal notranslate"><span class="pre">iter_all</span></code> on an endpoint that supports cursor-based pagination should correctly call out to <code class="docutils literal notranslate"><span class="pre">iter_cursor</span></code> (it was making the call but with a removed keyword argument)</p></li>

docs/contributing.html

@@ -6,7 +6,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
 
-    <title>Contribution Guide &#8212; PagerDuty Python REST API Sessions 5.1.1 documentation</title>
+    <title>Contribution Guide &#8212; PagerDuty Python REST API Sessions 5.1.2 documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
     <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>

docs/genindex.html

@@ -5,7 +5,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Index &#8212; PagerDuty Python REST API Sessions 5.1.1 documentation</title>
+    <title>Index &#8212; PagerDuty Python REST API Sessions 5.1.2 documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
     <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>

docs/index.html

@@ -6,7 +6,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
 
-    <title>PDPYRAS: PagerDuty Python REST API Sessions &#8212; PagerDuty Python REST API Sessions 5.1.1 documentation</title>
+    <title>PDPYRAS: PagerDuty Python REST API Sessions &#8212; PagerDuty Python REST API Sessions 5.1.2 documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
     <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>

docs/module_reference.html

@@ -6,7 +6,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
 
-    <title>Module Reference &#8212; PagerDuty Python REST API Sessions 5.1.1 documentation</title>
+    <title>Module Reference &#8212; PagerDuty Python REST API Sessions 5.1.2 documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
     <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>

docs/py-modindex.html

@@ -5,7 +5,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Python Module Index &#8212; PagerDuty Python REST API Sessions 5.1.1 documentation</title>
+    <title>Python Module Index &#8212; PagerDuty Python REST API Sessions 5.1.2 documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
     <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>

docs/search.html

@@ -5,7 +5,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Search &#8212; PagerDuty Python REST API Sessions 5.1.1 documentation</title>
+    <title>Search &#8212; PagerDuty Python REST API Sessions 5.1.2 documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
 

docs/user_guide.html

@@ -6,7 +6,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
 
-    <title>User Guide &#8212; PagerDuty Python REST API Sessions 5.1.1 documentation</title>
+    <title>User Guide &#8212; PagerDuty Python REST API Sessions 5.1.2 documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
     <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
@@ -180,21 +180,28 @@ <h3>REST API v2<a class="headerlink" href="#rest-api-v2" title="Permalink to thi
 <span class="n">updated_user</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">persist</span><span class="p">(</span><span class="s1">&#39;users&#39;</span><span class="p">,</span> <span class="s1">&#39;email&#39;</span><span class="p">,</span> <span class="n">user_data</span><span class="p">,</span> <span class="n">update</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
 </pre></div>
 </div>
-<p><strong>Using multi-valued set filters:</strong> set the value in the <code class="docutils literal notranslate"><span class="pre">params</span></code> dictionary at
-the appropriate key to a list, and include <code class="docutils literal notranslate"><span class="pre">[]</span></code> at the end of the paramter
-name:</p>
-<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Query all open incidents assigned to a user:</span>
+<p><strong>Using multi-valued set filters:</strong> set the value in the <code class="docutils literal notranslate"><span class="pre">params</span></code> dictionary
+at the appropriate key to a list. Square brackets will then be automatically
+appended to the names of list-type-value parameters as necessary. Ordinarily
+(and in pdpyras versions prior to 4.4.0) one must include <code class="docutils literal notranslate"><span class="pre">[]</span></code> at the end of
+the paramter name to denote a set type filter. For example:</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Query all open incidents assigned to a user</span>
 <span class="n">incidents</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">list_all</span><span class="p">(</span>
     <span class="s1">&#39;incidents&#39;</span><span class="p">,</span>
-    <span class="n">params</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;user_ids[]&#39;</span><span class="p">:[</span><span class="s1">&#39;PHIJ789&#39;</span><span class="p">],</span><span class="s1">&#39;statuses[]&#39;</span><span class="p">:[</span><span class="s1">&#39;triggered&#39;</span><span class="p">,</span> <span class="s1">&#39;acknowledged&#39;</span><span class="p">]}</span>
+    <span class="n">params</span><span class="o">=</span><span class="p">{</span>
+      <span class="s1">&#39;user_ids[]&#39;</span><span class="p">:[</span><span class="s1">&#39;PHIJ789&#39;</span><span class="p">],</span> <span class="c1"># (Necessary in &lt; 4.4.0, compatible with &gt;= 4.4.0)</span>
+      <span class="s1">&#39;statuses&#39;</span><span class="p">:[</span><span class="s1">&#39;triggered&#39;</span><span class="p">,</span> <span class="s1">&#39;acknowledged&#39;</span><span class="p">]</span> <span class="c1"># (&gt;= 4.4.0)</span>
+    <span class="p">}</span>
 <span class="p">)</span>
+<span class="c1"># API calls will look like the following:</span>
+<span class="c1"># GET /incidents?user_ids%5B%5D=PHIJ789&amp;statuses%5B%5D=triggered&amp;statuses%5B%5D=acknowledged&amp;offset=0&amp;limit=100</span>
 </pre></div>
 </div>
 <p><strong>Performing multi-update:</strong> for endpoints that support it only, i.e. <code class="docutils literal notranslate"><span class="pre">PUT</span> <span class="pre">/incidents</span></code>:</p>
 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Acknowledge all triggered incidents assigned to a user:</span>
 <span class="n">incidents</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">list_all</span><span class="p">(</span>
     <span class="s1">&#39;incidents&#39;</span><span class="p">,</span>
-    <span class="n">params</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;user_ids[]&#39;</span><span class="p">:[</span><span class="s1">&#39;PHIJ789&#39;</span><span class="p">],</span><span class="s1">&#39;statuses[]&#39;</span><span class="p">:[</span><span class="s1">&#39;triggered&#39;</span><span class="p">]}</span>
+    <span class="n">params</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;user_ids&#39;</span><span class="p">:[</span><span class="s1">&#39;PHIJ789&#39;</span><span class="p">],</span><span class="s1">&#39;statuses&#39;</span><span class="p">:[</span><span class="s1">&#39;triggered&#39;</span><span class="p">]}</span>
 <span class="p">)</span>
 <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">incidents</span><span class="p">:</span>
     <span class="n">i</span><span class="p">[</span><span class="s1">&#39;status&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;acknowledged&#39;</span>
@@ -282,6 +289,7 @@ <h2>Query Parameters<a class="headerlink" href="#query-parameters" title="Permal
 <span class="p">})</span>
 <span class="c1"># GET https://api.pagerduty.com/services?query=foo&amp;include%5B%5D=escalation_policies&amp;include%5B%5D=teams&amp;limit=50&amp;offset=0</span>
 <span class="c1"># GET https://api.pagerduty.com/services?query=foo&amp;include%5B%5D=escalation_policies&amp;include%5B%5D=teams&amp;limit=50&amp;offset=50</span>
+<span class="c1"># &gt;&gt;&gt; foo_services</span>
 <span class="c1"># [{&quot;type&quot;: &quot;service&quot; ...}, ... ]</span>
 </pre></div>
 </div>
@@ -445,7 +453,7 @@ <h3>Special Cases<a class="headerlink" href="#special-cases" title="Permalink to
 <span class="c1"># &gt;&gt;&gt; created_overrides</span>
 <span class="c1"># [</span>
 <span class="c1">#     {&#39;status&#39;: 201, &#39;override&#39;: {...}},</span>
-<span class="c1">#     {&#39;status&#39;: 400, errors: [&#39;Override must end after its start&#39;], &#39;override&#39;: {...}}</span>
+<span class="c1">#     {&#39;status&#39;: 400, &#39;errors&#39;: [&#39;Override must end after its start&#39;], &#39;override&#39;: {...}}</span>
 <span class="c1"># ]</span>
 </pre></div>
 </div>

pdpyras.py

@@ -18,7 +18,7 @@
 from urllib3.exceptions import HTTPError, PoolError
 from requests.exceptions import RequestException
 
-__version__ = '5.1.1'
+__version__ = '5.1.2'
 
 #######################
 ### CLIENT DEFAULTS ###
@@ -1246,6 +1246,13 @@ class EventsAPISession(PDSession):
 
     url = "https://events.pagerduty.com"
 
+    def __init__(self, api_key: str, debug=False):
+        super(EventsAPISession, self).__init__(api_key, debug)
+        # See: https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTgw-events-api-v2-overview#response-codes--retry-logic
+        self.retry[500] = 2 # internal server error, 3 requests total
+        self.retry[502] = 4 # bad gateway, 5 requests total
+        self.retry[503] = 6 # service unavailable, 7 requests total
+
     @property
     def auth_header(self):
         return {}
@@ -1411,6 +1418,13 @@ class ChangeEventsAPISession(PDSession):
 
     url = "https://events.pagerduty.com"
 
+    def __init__(self, api_key: str, debug=False):
+        super(ChangeEventsAPISession, self).__init__(api_key, debug)
+        # See: https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTgw-events-api-v2-overview#response-codes--retry-logic
+        self.retry[500] = 2 # internal server error, 3 requests total
+        self.retry[502] = 4 # bad gateway, 5 requests total
+        self.retry[503] = 6 # service unavailable, 7 requests total
+
     @property
     def auth_header(self):
         return {}

setup.py

@@ -1,6 +1,6 @@
 from setuptools import setup, find_packages
 
-__version__ = '5.1.1'
+__version__ = '5.1.2'
 
 if __name__ == '__main__':
     setup(

sphinx/source/user_guide.rst

@@ -171,17 +171,25 @@ matching a string using the ``query`` parameter on an index endpoint:
     user_data = {'email': 'user123@example.com', 'name': 'User McUserson'}
     updated_user = session.persist('users', 'email', user_data, update=True)
 
-**Using multi-valued set filters:** set the value in the ``params`` dictionary at
-the appropriate key to a list, and include ``[]`` at the end of the paramter
-name:
+**Using multi-valued set filters:** set the value in the ``params`` dictionary
+at the appropriate key to a list. Square brackets will then be automatically
+appended to the names of list-type-value parameters as necessary. Ordinarily
+(and in pdpyras versions prior to 4.4.0) one must include ``[]`` at the end of
+the paramter name to denote a set type filter. For example:
 
 .. code-block:: python
 
-    # Query all open incidents assigned to a user:
+    # Query all open incidents assigned to a user
     incidents = session.list_all(
         'incidents',
-        params={'user_ids[]':['PHIJ789'],'statuses[]':['triggered', 'acknowledged']}
+        params={
+          'user_ids[]':['PHIJ789'], # (Necessary in < 4.4.0, compatible with >= 4.4.0)
+          'statuses':['triggered', 'acknowledged'] # (>= 4.4.0)
+        }
     )
+    # API calls will look like the following:
+    # GET /incidents?user_ids%5B%5D=PHIJ789&statuses%5B%5D=triggered&statuses%5B%5D=acknowledged&offset=0&limit=100
+
 
 **Performing multi-update:** for endpoints that support it only, i.e. ``PUT /incidents``:
 
@@ -190,7 +198,7 @@ name:
     # Acknowledge all triggered incidents assigned to a user:
     incidents = session.list_all(
         'incidents',
-        params={'user_ids[]':['PHIJ789'],'statuses[]':['triggered']}
+        params={'user_ids':['PHIJ789'],'statuses':['triggered']}
     )
     for i in incidents:
         i['status'] = 'acknowledged'
@@ -290,6 +298,7 @@ then ``[]`` will be automatically appended to the parameter name.
     })
     # GET https://api.pagerduty.com/services?query=foo&include%5B%5D=escalation_policies&include%5B%5D=teams&limit=50&offset=0
     # GET https://api.pagerduty.com/services?query=foo&include%5B%5D=escalation_policies&include%5B%5D=teams&limit=50&offset=50
+    # >>> foo_services
     # [{"type": "service" ...}, ... ]
 
 
@@ -469,7 +478,7 @@ entity is wrapped as appropriate. For instance:
     # >>> created_overrides
     # [
     #     {'status': 201, 'override': {...}},
-    #     {'status': 400, errors: ['Override must end after its start'], 'override': {...}}
+    #     {'status': 400, 'errors': ['Override must end after its start'], 'override': {...}}
     # ]
 
 Pagination