diff --git a/.gitignore b/.gitignore index 38baf4f..fdad6f1 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,4 @@ dist/ pdpyras.egg-info/ docs/.buildinfo tmp/ +.DS_Store diff --git a/CHANGELOG.rst b/CHANGELOG.rst index bd1dd6e..d047faa 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,3 +1,7 @@ +**2019-10-01: version 3.1.2** + +* Fixed regression bug / departure from documentation (#17): the ``payload`` parameter does not merge with but rather completely replaces the default payload + **2019-04-05: version 3.1.1** * Changed behavior of HTTP retry that caused issues with some internal tools: raising ``PDClientError`` in the event of non-transient HTTP error, in the ``request`` method, versus returning the request object and logging it. The previous behavior was: diff --git a/docs/_static/ajax-loader.gif b/docs/_static/ajax-loader.gif deleted file mode 100644 index 61faf8c..0000000 Binary files a/docs/_static/ajax-loader.gif and /dev/null differ diff --git a/docs/_static/basic.css b/docs/_static/basic.css index 104f076..ea6972d 100644 --- a/docs/_static/basic.css +++ b/docs/_static/basic.css @@ -4,7 +4,7 @@ * * Sphinx stylesheet -- basic theme. * - * :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS. + * :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS. * :license: BSD, see LICENSE for details. * */ @@ -231,6 +231,16 @@ a.headerlink { visibility: hidden; } +a.brackets:before, +span.brackets > a:before{ + content: "["; +} + +a.brackets:after, +span.brackets > a:after { + content: "]"; +} + h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, @@ -279,6 +289,12 @@ img.align-center, .figure.align-center, object.align-center { margin-right: auto; } +img.align-default, .figure.align-default { + display: block; + margin-left: auto; + margin-right: auto; +} + .align-left { text-align: left; } @@ -287,6 +303,10 @@ img.align-center, .figure.align-center, object.align-center { text-align: center; } +.align-default { + text-align: center; +} + .align-right { text-align: right; } @@ -358,6 +378,11 @@ table.align-center { margin-right: auto; } +table.align-default { + margin-left: auto; + margin-right: auto; +} + table caption span.caption-number { font-style: italic; } @@ -391,6 +416,16 @@ table.citation td { border-bottom: none; } +th > p:first-child, +td > p:first-child { + margin-top: 0px; +} + +th > p:last-child, +td > p:last-child { + margin-bottom: 0px; +} + /* -- figures --------------------------------------------------------------- */ div.figure { @@ -460,11 +495,58 @@ ol.upperroman { list-style: upper-roman; } +li > p:first-child { + margin-top: 0px; +} + +li > p:last-child { + margin-bottom: 0px; +} + +dl.footnote > dt, +dl.citation > dt { + float: left; +} + +dl.footnote > dd, +dl.citation > dd { + margin-bottom: 0em; +} + +dl.footnote > dd:after, +dl.citation > dd:after { + content: ""; + clear: both; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} + +dl.field-list > dt:after { + content: ":"; +} + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0em; + margin-left: 0em; + margin-bottom: 0em; +} + dl { margin-bottom: 15px; } -dd p { +dd > p:first-child { margin-top: 0px; } @@ -537,6 +619,12 @@ dl.glossary dt { font-style: oblique; } +.classifier:before { + font-style: normal; + margin: 0.5em; + content: ":"; +} + abbr, acronym { border-bottom: dotted 1px; cursor: help; diff --git a/docs/_static/comment-bright.png b/docs/_static/comment-bright.png deleted file mode 100644 index 15e27ed..0000000 Binary files a/docs/_static/comment-bright.png and /dev/null differ diff --git a/docs/_static/comment-close.png b/docs/_static/comment-close.png deleted file mode 100644 index 4d91bcf..0000000 Binary files a/docs/_static/comment-close.png and /dev/null differ diff --git a/docs/_static/comment.png b/docs/_static/comment.png deleted file mode 100644 index dfbc0cb..0000000 Binary files a/docs/_static/comment.png and /dev/null differ diff --git a/docs/_static/doctools.js b/docs/_static/doctools.js index ffadbec..b33f87f 100644 --- a/docs/_static/doctools.js +++ b/docs/_static/doctools.js @@ -4,7 +4,7 @@ * * Sphinx JavaScript utilities for all documentation. * - * :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS. + * :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS. * :license: BSD, see LICENSE for details. * */ @@ -87,14 +87,13 @@ jQuery.fn.highlightText = function(text, className) { node.nextSibling)); node.nodeValue = val.substr(0, pos); if (isInSVG) { - var bbox = span.getBBox(); var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect"); - rect.x.baseVal.value = bbox.x; + var bbox = node.parentElement.getBBox(); + rect.x.baseVal.value = bbox.x; rect.y.baseVal.value = bbox.y; rect.width.baseVal.value = bbox.width; rect.height.baseVal.value = bbox.height; rect.setAttribute('class', className); - var parentOfText = node.parentNode.parentNode; addItems.push({ "parent": node.parentNode, "target": rect}); diff --git a/docs/_static/documentation_options.js b/docs/_static/documentation_options.js index 990819e..17590d2 100644 --- a/docs/_static/documentation_options.js +++ b/docs/_static/documentation_options.js @@ -1,296 +1,10 @@ var DOCUMENTATION_OPTIONS = { URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'), - VERSION: '3.1.1', + VERSION: '3.1.2', LANGUAGE: 'None', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true, SOURCELINK_SUFFIX: '.txt', - NAVIGATION_WITH_KEYS: false, - SEARCH_LANGUAGE_STOP_WORDS: ["a","and","are","as","at","be","but","by","for","if","in","into","is","it","near","no","not","of","on","or","such","that","the","their","then","there","these","they","this","to","was","will","with"] -}; - - - -/* Non-minified version JS is _stemmer.js if file is provided */ -/** - * Porter Stemmer - */ -var Stemmer = function() { - - var step2list = { - ational: 'ate', - tional: 'tion', - enci: 'ence', - anci: 'ance', - izer: 'ize', - bli: 'ble', - alli: 'al', - entli: 'ent', - eli: 'e', - ousli: 'ous', - ization: 'ize', - ation: 'ate', - ator: 'ate', - alism: 'al', - iveness: 'ive', - fulness: 'ful', - ousness: 'ous', - aliti: 'al', - iviti: 'ive', - biliti: 'ble', - logi: 'log' - }; - - var step3list = { - icate: 'ic', - ative: '', - alize: 'al', - iciti: 'ic', - ical: 'ic', - ful: '', - ness: '' - }; - - var c = "[^aeiou]"; // consonant - var v = "[aeiouy]"; // vowel - var C = c + "[^aeiouy]*"; // consonant sequence - var V = v + "[aeiou]*"; // vowel sequence - - var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 - var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 - var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 - var s_v = "^(" + C + ")?" + v; // vowel in stem - - this.stemWord = function (w) { - var stem; - var suffix; - var firstch; - var origword = w; - - if (w.length < 3) - return w; - - var re; - var re2; - var re3; - var re4; - - firstch = w.substr(0,1); - if (firstch == "y") - w = firstch.toUpperCase() + w.substr(1); - - // Step 1a - re = /^(.+?)(ss|i)es$/; - re2 = /^(.+?)([^s])s$/; - - if (re.test(w)) - w = w.replace(re,"$1$2"); - else if (re2.test(w)) - w = w.replace(re2,"$1$2"); - - // Step 1b - re = /^(.+?)eed$/; - re2 = /^(.+?)(ed|ing)$/; - if (re.test(w)) { - var fp = re.exec(w); - re = new RegExp(mgr0); - if (re.test(fp[1])) { - re = /.$/; - w = w.replace(re,""); - } - } - else if (re2.test(w)) { - var fp = re2.exec(w); - stem = fp[1]; - re2 = new RegExp(s_v); - if (re2.test(stem)) { - w = stem; - re2 = /(at|bl|iz)$/; - re3 = new RegExp("([^aeiouylsz])\\1$"); - re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); - if (re2.test(w)) - w = w + "e"; - else if (re3.test(w)) { - re = /.$/; - w = w.replace(re,""); - } - else if (re4.test(w)) - w = w + "e"; - } - } - - // Step 1c - re = /^(.+?)y$/; - if (re.test(w)) { - var fp = re.exec(w); - stem = fp[1]; - re = new RegExp(s_v); - if (re.test(stem)) - w = stem + "i"; - } - - // Step 2 - re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; - if (re.test(w)) { - var fp = re.exec(w); - stem = fp[1]; - suffix = fp[2]; - re = new RegExp(mgr0); - if (re.test(stem)) - w = stem + step2list[suffix]; - } - - // Step 3 - re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; - if (re.test(w)) { - var fp = re.exec(w); - stem = fp[1]; - suffix = fp[2]; - re = new RegExp(mgr0); - if (re.test(stem)) - w = stem + step3list[suffix]; - } - - // Step 4 - re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; - re2 = /^(.+?)(s|t)(ion)$/; - if (re.test(w)) { - var fp = re.exec(w); - stem = fp[1]; - re = new RegExp(mgr1); - if (re.test(stem)) - w = stem; - } - else if (re2.test(w)) { - var fp = re2.exec(w); - stem = fp[1] + fp[2]; - re2 = new RegExp(mgr1); - if (re2.test(stem)) - w = stem; - } - - // Step 5 - re = /^(.+?)e$/; - if (re.test(w)) { - var fp = re.exec(w); - stem = fp[1]; - re = new RegExp(mgr1); - re2 = new RegExp(meq1); - re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); - if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) - w = stem; - } - re = /ll$/; - re2 = new RegExp(mgr1); - if (re.test(w) && re2.test(w)) { - re = /.$/; - w = w.replace(re,""); - } - - // and turn initial Y back to y - if (firstch == "y") - w = firstch.toLowerCase() + w.substr(1); - return w; - } -} - - - - - -var splitChars = (function() { - var result = {}; - var singles = [96, 180, 187, 191, 215, 247, 749, 885, 903, 907, 909, 930, 1014, 1648, - 1748, 1809, 2416, 2473, 2481, 2526, 2601, 2609, 2612, 2615, 2653, 2702, - 2706, 2729, 2737, 2740, 2857, 2865, 2868, 2910, 2928, 2948, 2961, 2971, - 2973, 3085, 3089, 3113, 3124, 3213, 3217, 3241, 3252, 3295, 3341, 3345, - 3369, 3506, 3516, 3633, 3715, 3721, 3736, 3744, 3748, 3750, 3756, 3761, - 3781, 3912, 4239, 4347, 4681, 4695, 4697, 4745, 4785, 4799, 4801, 4823, - 4881, 5760, 5901, 5997, 6313, 7405, 8024, 8026, 8028, 8030, 8117, 8125, - 8133, 8181, 8468, 8485, 8487, 8489, 8494, 8527, 11311, 11359, 11687, 11695, - 11703, 11711, 11719, 11727, 11735, 12448, 12539, 43010, 43014, 43019, 43587, - 43696, 43713, 64286, 64297, 64311, 64317, 64319, 64322, 64325, 65141]; - var i, j, start, end; - for (i = 0; i < singles.length; i++) { - result[singles[i]] = true; - } - var ranges = [[0, 47], [58, 64], [91, 94], [123, 169], [171, 177], [182, 184], [706, 709], - [722, 735], [741, 747], [751, 879], [888, 889], [894, 901], [1154, 1161], - [1318, 1328], [1367, 1368], [1370, 1376], [1416, 1487], [1515, 1519], [1523, 1568], - [1611, 1631], [1642, 1645], [1750, 1764], [1767, 1773], [1789, 1790], [1792, 1807], - [1840, 1868], [1958, 1968], [1970, 1983], [2027, 2035], [2038, 2041], [2043, 2047], - [2070, 2073], [2075, 2083], [2085, 2087], [2089, 2307], [2362, 2364], [2366, 2383], - [2385, 2391], [2402, 2405], [2419, 2424], [2432, 2436], [2445, 2446], [2449, 2450], - [2483, 2485], [2490, 2492], [2494, 2509], [2511, 2523], [2530, 2533], [2546, 2547], - [2554, 2564], [2571, 2574], [2577, 2578], [2618, 2648], [2655, 2661], [2672, 2673], - [2677, 2692], [2746, 2748], [2750, 2767], [2769, 2783], [2786, 2789], [2800, 2820], - [2829, 2830], [2833, 2834], [2874, 2876], [2878, 2907], [2914, 2917], [2930, 2946], - [2955, 2957], [2966, 2968], [2976, 2978], [2981, 2983], [2987, 2989], [3002, 3023], - [3025, 3045], [3059, 3076], [3130, 3132], [3134, 3159], [3162, 3167], [3170, 3173], - [3184, 3191], [3199, 3204], [3258, 3260], [3262, 3293], [3298, 3301], [3312, 3332], - [3386, 3388], [3390, 3423], [3426, 3429], [3446, 3449], [3456, 3460], [3479, 3481], - [3518, 3519], [3527, 3584], [3636, 3647], [3655, 3663], [3674, 3712], [3717, 3718], - [3723, 3724], [3726, 3731], [3752, 3753], [3764, 3772], [3774, 3775], [3783, 3791], - [3802, 3803], [3806, 3839], [3841, 3871], [3892, 3903], [3949, 3975], [3980, 4095], - [4139, 4158], [4170, 4175], [4182, 4185], [4190, 4192], [4194, 4196], [4199, 4205], - [4209, 4212], [4226, 4237], [4250, 4255], [4294, 4303], [4349, 4351], [4686, 4687], - [4702, 4703], [4750, 4751], [4790, 4791], [4806, 4807], [4886, 4887], [4955, 4968], - [4989, 4991], [5008, 5023], [5109, 5120], [5741, 5742], [5787, 5791], [5867, 5869], - [5873, 5887], [5906, 5919], [5938, 5951], [5970, 5983], [6001, 6015], [6068, 6102], - [6104, 6107], [6109, 6111], [6122, 6127], [6138, 6159], [6170, 6175], [6264, 6271], - [6315, 6319], [6390, 6399], [6429, 6469], [6510, 6511], [6517, 6527], [6572, 6592], - [6600, 6607], [6619, 6655], [6679, 6687], [6741, 6783], [6794, 6799], [6810, 6822], - [6824, 6916], [6964, 6980], [6988, 6991], [7002, 7042], [7073, 7085], [7098, 7167], - [7204, 7231], [7242, 7244], [7294, 7400], [7410, 7423], [7616, 7679], [7958, 7959], - [7966, 7967], [8006, 8007], [8014, 8015], [8062, 8063], [8127, 8129], [8141, 8143], - [8148, 8149], [8156, 8159], [8173, 8177], [8189, 8303], [8306, 8307], [8314, 8318], - [8330, 8335], [8341, 8449], [8451, 8454], [8456, 8457], [8470, 8472], [8478, 8483], - [8506, 8507], [8512, 8516], [8522, 8525], [8586, 9311], [9372, 9449], [9472, 10101], - [10132, 11263], [11493, 11498], [11503, 11516], [11518, 11519], [11558, 11567], - [11622, 11630], [11632, 11647], [11671, 11679], [11743, 11822], [11824, 12292], - [12296, 12320], [12330, 12336], [12342, 12343], [12349, 12352], [12439, 12444], - [12544, 12548], [12590, 12592], [12687, 12689], [12694, 12703], [12728, 12783], - [12800, 12831], [12842, 12880], [12896, 12927], [12938, 12976], [12992, 13311], - [19894, 19967], [40908, 40959], [42125, 42191], [42238, 42239], [42509, 42511], - [42540, 42559], [42592, 42593], [42607, 42622], [42648, 42655], [42736, 42774], - [42784, 42785], [42889, 42890], [42893, 43002], [43043, 43055], [43062, 43071], - [43124, 43137], [43188, 43215], [43226, 43249], [43256, 43258], [43260, 43263], - [43302, 43311], [43335, 43359], [43389, 43395], [43443, 43470], [43482, 43519], - [43561, 43583], [43596, 43599], [43610, 43615], [43639, 43641], [43643, 43647], - [43698, 43700], [43703, 43704], [43710, 43711], [43715, 43738], [43742, 43967], - [44003, 44015], [44026, 44031], [55204, 55215], [55239, 55242], [55292, 55295], - [57344, 63743], [64046, 64047], [64110, 64111], [64218, 64255], [64263, 64274], - [64280, 64284], [64434, 64466], [64830, 64847], [64912, 64913], [64968, 65007], - [65020, 65135], [65277, 65295], [65306, 65312], [65339, 65344], [65371, 65381], - [65471, 65473], [65480, 65481], [65488, 65489], [65496, 65497]]; - for (i = 0; i < ranges.length; i++) { - start = ranges[i][0]; - end = ranges[i][1]; - for (j = start; j <= end; j++) { - result[j] = true; - } - } - return result; -})(); - -function splitQuery(query) { - var result = []; - var start = -1; - for (var i = 0; i < query.length; i++) { - if (splitChars[query.charCodeAt(i)]) { - if (start !== -1) { - result.push(query.slice(start, i)); - start = -1; - } - } else if (start === -1) { - start = i; - } - } - if (start !== -1) { - result.push(query.slice(start)); - } - return result; -} - - + NAVIGATION_WITH_KEYS: false +}; \ No newline at end of file diff --git a/docs/_static/down-pressed.png b/docs/_static/down-pressed.png deleted file mode 100644 index 5756c8c..0000000 Binary files a/docs/_static/down-pressed.png and /dev/null differ diff --git a/docs/_static/down.png b/docs/_static/down.png deleted file mode 100644 index 1b3bdad..0000000 Binary files a/docs/_static/down.png and /dev/null differ diff --git a/docs/_static/jquery-3.2.1.js b/docs/_static/jquery-3.4.1.js similarity index 89% rename from docs/_static/jquery-3.2.1.js rename to docs/_static/jquery-3.4.1.js index d2d8ca4..773ad95 100644 --- a/docs/_static/jquery-3.2.1.js +++ b/docs/_static/jquery-3.4.1.js @@ -1,5 +1,5 @@ /*! - * jQuery JavaScript Library v3.2.1 + * jQuery JavaScript Library v3.4.1 * https://jquery.com/ * * Includes Sizzle.js @@ -9,7 +9,7 @@ * Released under the MIT license * https://jquery.org/license * - * Date: 2017-03-20T18:59Z + * Date: 2019-05-01T21:04Z */ ( function( global, factory ) { @@ -71,16 +71,70 @@ var ObjectFunctionString = fnToString.call( Object ); var support = {}; +var isFunction = function isFunction( obj ) { + // Support: Chrome <=57, Firefox <=52 + // In some browsers, typeof returns "function" for HTML
Efficient API access through automatic HTTP connection pooling and +persistence
Tested in / support for Python 2.7 through 3.7
Automatic cooldown/reattempt for rate limiting and transient network problems
Inclusion of required HTTP Request Headers for PagerDuty REST API requests
Bulk data retrieval and iteration over resource index endpoints with +automatic pagination
Individual object retrieval by name
API request profiling
Bonus Events API client
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR ++THE SOFTWARE. +THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE.
There is no need to include the API base URL. Any path relative to the web
root, leading slash or no, is automatically appended to the base URL when
constructing an API request, i.e. one can specify users/PABC123
or
-/users/PABC123
instead of https://api.pagerduty.com/users/PABC123
.
/users/PABC123
instead of https://api.pagerduty.com/users/PABC123
.One can also pass the full URL of an API endpoint and it will still work, i.e.
the self
property of any object can be used, and there is no need to strip
-out the API base URL.
Data is represented as dictionary or list objects, and should have a +structure that mirrors that of the API schema:
+If the data type documented in the schema is
object, then the
-corresponding type in Python will be dict
.
dict
.If the data type documented in the schema is
array, then the
-corresponding type in Python will be list
.
list
.dict
object (or list
, where
-applicable) in the json
keyword argument.dict
(or list
, if applicable), call
+Everything is automatically JSON-encoded and decoded, using it as follows:
+To send a JSON request body, pass a dict
object (or list
, where
+applicable) in the json
keyword argument.
To get the response body as a dict
(or list
, if applicable), call
the json
-method of the response object.
r{VERB}
methods, i.e. rget
, the return value will be
+method of the response object.If using the r{VERB}
methods, i.e. rget
, the return value will be
the dict
/list
object decoded from the wrapped entity and there is
-no need to call response.json()
.
j{VERB}
methods, i.e. jget
, return the object
+no need to call response.json()
.Similarly, the j{VERB}
methods, i.e. jget
, return the object
decoded from the JSON string in the response body (but without attempting
-to unwrap any wrapped entities it may contain).
Validate that the response HTTP status is not an error.
Predict the name of the envelope property which will contain the object.
Validate that the result contains the predicted envelope property.
Access the property that is encapsulated within the response.
PUT /priorities (not yet published, as of 2018-11-28)
Please note: as of yet, merging incidents is not supported by rput
.
For this and other unsupported endpoints, you will need to call put
directly,
@@ -542,16 +544,16 @@
pdpyras.EventsAPISession
. It has most of the same features as
pdpyras.APISession
:
Connection persistence
Automatic cooldown and retry in the event of rate limiting or a transient network error
Setting all required headers
Configurable HTTP retry logic
To transmit alerts and perform actions through the events API, one would use:
pdpyras.EventsAPISession.trigger
pdpyras.EventsAPISession.acknowledge
pdpyras.EventsAPISession.resolve
To instantiate a session object, pass the constructor the routing key:
import pdpyras
@@ -592,44 +594,44 @@ Generic API Clientpdpyras.EventsAPISession
.
-
-class
pdpyras.
PDSession
(api_key, name=None)¶
+class pdpyras.
PDSession
(api_key, name=None)¶
Base class for making HTTP requests to PagerDuty APIs.
Instances of this class are essentially the same as requests.Session
objects, but with a few modifications:
-- The client will reattempt the request with configurable, auto-increasing
-cooldown/retry intervals if encountering a network error or rate limit
-- When making requests, headers specified ad-hoc in calls to HTTP verb
-functions will not replace, but will be merged with, default headers.
-- The request URL, if it doesn’t already start with the REST API base URL,
-will be prepended with the default REST API base URL.
-- It will only perform requests with methods as given in the
+
The client will reattempt the request with configurable, auto-increasing
+cooldown/retry intervals if encountering a network error or rate limit
+When making requests, headers specified ad-hoc in calls to HTTP verb
+functions will not replace, but will be merged with, default headers.
+The request URL, if it doesn’t already start with the REST API base URL,
+will be prepended with the default REST API base URL.
+It will only perform requests with methods as given in the
permitted_methods
list, and will raise PDClientError
for
-any other HTTP methods.
+any other HTTP methods.
-
+
-
-
max_http_attempts
= 10¶
+max_http_attempts
= 10¶
The number of times that the client will retry after error statuses, for any
that are defined greater than zero in retry
.
-
-
max_network_attempts
= 3¶
+max_network_attempts
= 3¶
The number of times that connecting to the API will be attempted before
treating the failure as non-transient; a PDClientError
exception
will be raised if this happens.
@@ -637,33 +639,30 @@ Generic API Client
-
-
parent
= None¶
+parent
= None¶
The super
object (requests.Session)
-
-
postprocess
(response)¶
+postprocess
(response)¶
Perform supplemental actions immediately after receiving a response.
-
-
prepare_headers
(method)¶
+prepare_headers
(method)¶
Append special additional per-request headers.
-
-
-
-
-Parameters: method – The HTTP method, in upper case.
-
-
-
+
+- Parameters
+method – The HTTP method, in upper case.
+
+
-
-
raise_if_http_error
= True¶
+raise_if_http_error
= True¶
Raise an exception upon receiving an error response from the server.
This affects iteration (in the REST API) as well as the generic request
method itself.
@@ -678,47 +677,43 @@ Generic API Client
-
-
request
(method, url, **kwargs)¶
+request
(method, url, **kwargs)¶
Make a generic PagerDuty API request.
-
-
-
-
-Parameters:
-- method (str) – The request method to use. Case-insensitive. May be one of get, put,
-post or delete.
-- url (str) – The path/URL to request. If it does not start with the base URL, the
-base URL will be prepended.
-- **kwargs –
Additional keyword arguments to pass to requests.Session.request
-
+
+- Parameters
+
+method (str) – The request method to use. Case-insensitive. May be one of get, put,
+post or delete.
+url (str) – The path/URL to request. If it does not start with the base URL, the
+base URL will be prepended.
+**kwargs –
Additional keyword arguments to pass to requests.Session.request
+
-
-
-Returns: the HTTP response object
-
-
-Return type:
-
-
-
-
+
+- Returns
+the HTTP response object
+
+- Return type
+-
+
+
-
-
retry
= None¶
+retry
= None¶
A dict defining the retry behavior for each HTTP response status code.
Each key in this dictionary represents a HTTP response code. The behavior is
specified by the value at each key as follows:
--1
to retry infinitely
-0
to return the requests.Response object and exit (which is the
-default behavior)
-n
, where n > 0
, to retry n
times (or up
+-1
to retry infinitely
+0
to return the requests.Response object and exit (which is the
+default behavior)
+n
, where n > 0
, to retry n
times (or up
to max_http_attempts
total for all statuses, whichever is
encountered first), and raise a PDClientError
after that many
attempts. For each successive attempt, the wait time will increase by a
-factor of sleep_timer_base
.
+factor of sleep_timer_base
.
The default behavior is to retry infinitely on a 429, and return the
response in any other case (assuming a HTTP response was received from the
@@ -727,7 +722,7 @@
Generic API Client
-
-
set_api_key
(api_key)¶
+set_api_key
(api_key)¶
Set the API key/token.
Child classes should implement this method to do special things like
setting default headers.
@@ -737,7 +732,7 @@ Generic API Client
-
-
sleep_timer
= 1.5¶
+sleep_timer
= 1.5¶
Default initial cooldown time factor for rate limiting and network errors.
Each time that the request makes a followup request, there will be a delay
in seconds equal to this number times sleep_timer_base
to the power
@@ -746,20 +741,20 @@
Generic API Client
-
-
sleep_timer_base
= 2¶
+sleep_timer_base
= 2¶
After each retry, the time to sleep before reattempting the API connection
and request will increase by a factor of this amount.
-
+
-
+
@@ -772,139 +767,127 @@ REST API Client
-
-class
pdpyras.
APISession
(api_key, name=None, default_from=None)¶
+class pdpyras.
APISession
(api_key, name=None, default_from=None)¶
Reusable PagerDuty REST API session objects for making API requests.
Includes some convenience functions as well, i.e. rget
, find
and iter_all
, to eliminate some repetitive tasks associated with
making API calls.
Inherits from PDSession
.
-
-
-
-
-Parameters:
-- api_key – REST API access token to use for HTTP requests
-- name (str or None) – Optional name identifier for logging. If unspecified or
None
, it
-will be the last four characters of the REST API token.
-- default_from (str or None) – Email address of a valid PagerDuty user to use in API requests by
-default as the
From
header (see: HTTP Request Headers)
+
+- Parameters
+
+api_key – REST API access token to use for HTTP requests
+name (str or None) – Optional name identifier for logging. If unspecified or None
, it
+will be the last four characters of the REST API token.
+default_from (str or None) – Email address of a valid PagerDuty user to use in API requests by
+default as the From
header (see: HTTP Request Headers)
-
-
-Members:
-
-
-
+
+- Members
+
+
-
-
api_call_counts
= None¶
+api_call_counts
= None¶
A dict object recording the number of API calls per endpoint
-
-
api_time
= None¶
+api_time
= None¶
A dict object recording the total time of API calls to each endpoint
-
-
default_page_size
= 100¶
+default_page_size
= 100¶
This will be the default number of results requested in each page when
iterating/querying an index (the limit
parameter). See: pagination.
-
-
dict_all
(path, **kw)¶
+dict_all
(path, **kw)¶
Returns a dictionary of all objects from a given index endpoint.
With the exception of by
, all keyword arguments passed to this
method are also passed to iter_all
; see the documentation on
that method for further details.
-
-
-
-
-Parameters:
-- path – The index endpoint URL to use.
-- by – The attribute of each object to use for the key values of the
+
+- Parameters
+
+path – The index endpoint URL to use.
+by – The attribute of each object to use for the key values of the
dictionary. This is id
by default. Please note, there is no
uniqueness validation, so if you use an attribute that is not
distinct for the data set, this function will omit some data in the
-results.
-- params – Additional URL parameters to include.
-- paginate – If True, use pagination to get through all available results. If
+results.
+params – Additional URL parameters to include.
+paginate – If True, use pagination to get through all available results. If
False, ignore / don’t page through more than the first 100 results.
Useful for special index endpoints that don’t fully support
pagination yet, i.e. “nested” endpoints like
-/users/{id}/contact_methods
and /services/{id}/integrations
+/users/{id}/contact_methods
and /services/{id}/integrations
-
-
-
-
+
+
-
-
find
(resource, query, attribute='name', params=None)¶
+find
(resource, query, attribute='name', params=None)¶
Finds an object of a given resource exactly matching a query.
Will query a given resource index endpoint using the query
parameter supported by most indexes.
Returns a dict if a result is found. The structure will be that of an
entry in the index endpoint schema’s array of results. Otherwise, it
will return None if no result is found or an error is encountered.
-
-
-
-
-Parameters:
-- resource (str) – The name of the resource endpoint to query, i.e.
-
escalation_policies
-- query (str) – The string to query for in the the index.
-- attribute (str) – The property of each result to compare against the query value when
+
+- Parameters
+
+resource (str) – The name of the resource endpoint to query, i.e.
+escalation_policies
+query (str) – The string to query for in the the index.
+attribute (str) – The property of each result to compare against the query value when
searching for an exact match. By default it is name
, but when
-searching for user by email (for example) it can be set to email
-- params (dict or None) – Optional additional parameters to use when querying.
+searching for user by email (for example) it can be set to email
+params (dict or None) – Optional additional parameters to use when querying.
-
-
-Return type: dict
-
-
-
-
+
+- Return type
+dict
+
+
-
-
iter_all
(path, params=None, paginate=True, item_hook=None, total=False)¶
+iter_all
(path, params=None, paginate=True, item_hook=None, total=False)¶
Iterator for the contents of an index endpoint or query.
Automatically paginates and yields the results in each page, until all
matching results have been yielded or a HTTP error response is received.
@@ -912,119 +895,101 @@ REST API Client/users endpoint, each
yielded value will be an entry of the users
array property in the
response; see: List Users
-
-
-
-
-Parameters:
-- path (str) – The index endpoint URL to use.
-- params (dict or None) – Additional URL parameters to include.
-- paginate (bool) – If True, use pagination to get through all available results. If
+
+- Parameters
+
+path (str) – The index endpoint URL to use.
+params (dict or None) – Additional URL parameters to include.
+paginate (bool) – If True, use pagination to get through all available results. If
False, ignore / don’t page through more than the first 100 results.
Useful for special index endpoints that don’t fully support
pagination yet, i.e. “nested” endpoints like (as of this writing):
-/users/{id}/contact_methods
and /services/{id}/integrations
-- item_hook – Callable object that will be invoked for each iteration, i.e. for
+
/users/{id}/contact_methods
and /services/{id}/integrations
+item_hook – Callable object that will be invoked for each iteration, i.e. for
printing progress. It will be called with three parameters: a dict
representing a given result in the iteration, the number of the
-item, and the total number of items in the series.
-- total (bool) – If True, the
total
parameter will be included in API calls, and
+item, and the total number of items in the series.
+total (bool) – If True, the total
parameter will be included in API calls, and
the value for the third parameter to the item hook will be the total
count of records that match the query. Leaving this as False confers
a small performance advantage, as the API in this case does not have
-to compute the total count of results in the query.
+to compute the total count of results in the query.
-
-
-Yields: Results from the index endpoint.
-
-
-Return type: dict
-
-
-
-
+
+- Yields
+Results from the index endpoint.
+
+- Return type
+dict
+
+
-
-
list_all
(path, **kw)¶
+list_all
(path, **kw)¶
Returns a list of all objects from a given index endpoint.
All keyword arguments passed to this function are also passed directly
to iter_all
; see the documentation on that method for details.
-
-
-
-
-Parameters: path – The index endpoint URL to use.
-
-
-
+
+- Parameters
+path – The index endpoint URL to use.
+
+
-
-
postprocess
(response, suffix=None)¶
+postprocess
(response, suffix=None)¶
Records performance information about the API call.
This method is called automatically by request()
for all requests,
and can be extended in child classes.
-
-
-
-
-Parameters:
-- method (str) – Method of the request
-- response (requests.Response) – Response object
-- suffix (str or None) – Optional suffix to append to the key
+
+- Parameters
+
+method (str) – Method of the request
+response (requests.Response) – Response object
+suffix (str or None) – Optional suffix to append to the key
-
-
-
-
+
+
-
-
prepare_headers
(method)¶
+prepare_headers
(method)¶
Append special additional per-request headers.
-
-
-
-
-Parameters: method – The HTTP method, in upper case.
-
-
-
+
+- Parameters
+method – The HTTP method, in upper case.
+
+
-
-
profiler_key
(method, path, suffix=None)¶
+profiler_key
(method, path, suffix=None)¶
Generates a fixed-format key to classify a request, i.e. for profiling.
Returns a string that will have all instances of IDs replaced with
{id}
, and will begin with the method in lower case followed by a
colon, i.e. get:escalation_policies/{id}
-
-
-
-
-Parameters:
-- method (str) – The request method
-- path (str) – The path/URI to classify
-- suffix (str) – Optional suffix to append to the key
+
+- Parameters
+
+method (str) – The request method
+path (str) – The path/URI to classify
+suffix (str) – Optional suffix to append to the key
-
-
-Return type: str
-
-
-
-
+
+- Return type
+str
+
+
-
-
set_api_key
(api_key)¶
+set_api_key
(api_key)¶
Set the API key/token.
Child classes should implement this method to do special things like
setting default headers.
@@ -1032,41 +997,38 @@ REST API Client
+
-
-
subdomain
¶
+property subdomain
¶
Subdomain of the PagerDuty account of the API access token.
-
-
-
-
-Type: str or None
-
-
-
+
+- Type
+str or None
+
+
-
+
-
+
-
+
@@ -1079,115 +1041,98 @@ Events API Clientpdpyras.PDSession
.
-
-class
pdpyras.
EventsAPISession
(api_key, name=None)¶
+class pdpyras.
EventsAPISession
(api_key, name=None)¶
Session class for submitting events to the PagerDuty v2 Events API.
Provides methods for submitting events to the Events API.
Inherits from PDSession
.
-
-
acknowledge
(dedup_key)¶
+acknowledge
(dedup_key)¶
Acknowledge an alert via Events API.
-
-
-
-
-Parameters: dedup_key – The deduplication key of the alert to set to the acknowledged state.
-
-
-
+
+- Parameters
+dedup_key – The deduplication key of the alert to set to the acknowledged state.
+
+
-
-
prepare_headers
(method)¶
+prepare_headers
(method)¶
Add user agent and content type headers for Events API requests.
-
-
resolve
(dedup_key)¶
+resolve
(dedup_key)¶
Resolve an alert via Events API.
-
-
-
-
-Parameters: dedup_key – The deduplication key of the alert to resolve.
-
-
-
+
+- Parameters
+dedup_key – The deduplication key of the alert to resolve.
+
+
-
-
send_event
(action, dedup_key=None, **properties)¶
+send_event
(action, dedup_key=None, **properties)¶
Send an event to the v2 Events API.
See: https://v2.developer.pagerduty.com/docs/send-an-event-events-api-v2
-
-
-
-
-Parameters:
-- action (str) – The action to perform through the Events API: trigger, acknowledge
-or resolve.
-- dedup_key (str) – The deduplication key; used for determining event uniqueness and
-associating actions with existing incidents.
-- **properties – Additional properties to set, i.e. if
action
is trigger
-this would include payload
+
+- Parameters
+
+action (str) – The action to perform through the Events API: trigger, acknowledge
+or resolve.
+dedup_key (str) – The deduplication key; used for determining event uniqueness and
+associating actions with existing incidents.
+**properties – Additional properties to set, i.e. if action
is trigger
+this would include payload
-
-
-Returns: The deduplication key of the incident, if any.
-
-
-
-
+
+- Returns
+The deduplication key of the incident, if any.
+
+
-
-
set_api_key
(api_key)¶
+set_api_key
(api_key)¶
Sets the routing key in the X-Routing-Key
header.
-
-
-
-
-Parameters: api_key (str) – The routing key to use for this session.
-
-
-
+
+- Parameters
+api_key (str) – The routing key to use for this session.
+
+
-
-
trigger
(summary, source, dedup_key=None, severity='critical', payload=None, custom_details=None, images=None, links=None)¶
+trigger
(summary, source, dedup_key=None, severity='critical', payload=None, custom_details=None, images=None, links=None)¶
Trigger an incident
-
-
-
-
-Parameters:
-- summary (str) – Summary / brief description of what is wrong.
-- source (str) – A human-readable name identifying the system that is affected.
-- dedup_key (str) – The deduplication key; used for determining event uniqueness and
-associating actions with existing incidents.
-- severity (str) – Alert severity. Sets the
payload.severity
property.
-- payload (dict) – Set the payload directly. Can be used in conjunction with other
+
+- Parameters
+
+summary (str) – Summary / brief description of what is wrong.
+source (str) – A human-readable name identifying the system that is affected.
+dedup_key (str) – The deduplication key; used for determining event uniqueness and
+associating actions with existing incidents.
+severity (str) – Alert severity. Sets the payload.severity
property.
+payload (dict) – Set the payload directly. Can be used in conjunction with other
parameters that also set payload properties; these properties will
be merged into the default payload, and any properties in this
parameter will take precedence except with regard to
-custom_details
.
-- custom_details (dict) – The
payload.custom_details
property of the payload. Will
-override the property set in the payload
parameter if given.
-- images (list) – Set the
images
property of the event.
-- links (list) – Set the
links
property of the event.
+custom_details
.
+custom_details (dict) – The payload.custom_details
property of the payload. Will
+override the property set in the payload
parameter if given.
+images (list) – Set the images
property of the event.
+links (list) – Set the links
property of the event.
-
-
-Return type: str
-
-
-
-
+
+- Return type
+str
+
+
@@ -1197,11 +1142,11 @@ Events API Client¶
-
-class
pdpyras.
PDClientError
(message, response=None)¶
+class pdpyras.
PDClientError
(message, response=None)¶
General API errors base class.
-
-
response
= None¶
+response
= None¶
The HTTP response object, if a response was successfully received.
In the case of network errors, this property will be None.
@@ -1213,57 +1158,55 @@ Errors
Functions¶
-
-
pdpyras.
auto_json
(method)¶
+pdpyras.
auto_json
(method)¶
Function decorator that makes methods return the full response JSON
-
-
pdpyras.
object_type
(r_name)¶
+pdpyras.
object_type
(r_name)¶
Derives an object type (i.e. user
) from a resource name (i.e. users
)
-
-
-
-
-Parameters: r_name – Resource name, i.e. would be users
for the resource index URL
-https://api.pagerduty.com/users
-
-Returns: The object type name; usually the type
property of an instance
-of the given resource.
-
-Return type: str
-
-
-
+
+- Parameters
+r_name – Resource name, i.e. would be users
for the resource index URL
+https://api.pagerduty.com/users
+
+- Returns
+The object type name; usually the type
property of an instance
+of the given resource.
+
+- Return type
+str
+
+
-
-
pdpyras.
raise_on_error
(r)¶
+pdpyras.
raise_on_error
(r)¶
Raise an exception if a HTTP error response has error status.
-
-
-
-
-Parameters: r (requests.Response) – Response object corresponding to the response received.
-
-Returns: The response object, if its status was success
-
-Return type: requests.Response
-
-
-
+
+- Parameters
+r (requests.Response) – Response object corresponding to the response received.
+
+- Returns
+The response object, if its status was success
+
+- Return type
+-
+
+
-
-
pdpyras.
resource_envelope
(method)¶
+pdpyras.
resource_envelope
(method)¶
Convenience and consistency decorator for HTTP verb functions.
This makes the request methods GET
, POST
and PUT
always return a
dictionary object representing the resource at the envelope property (i.e.
@@ -1283,43 +1226,40 @@
Errors
assuming nothing went wrong in the whole process).
These methods are APISession.rget
, APISession.rpost
and
APISession.rput
.
-
-
-
-
-Parameters: method – Method being decorated. Must take one positional argument
+
+- Parameters
+method – Method being decorated. Must take one positional argument
after self
that is the URL/path to the resource, and must return an
object of class requests.Response, and be named after the HTTP method
-but with “r” prepended.
-
-Returns: A callable object; the reformed method
-
-
-
+but with “r” prepended.
+
+- Returns
+A callable object; the reformed method
+
+
-
-
pdpyras.
resource_name
(obj_type)¶
+pdpyras.
resource_name
(obj_type)¶
Transforms an object type into a resource name
-
-
-
-
-Parameters: obj_type – The object type, i.e. user
or user_reference
-
-Returns: The name of the resource, i.e. the last part of the URL for the
-resource’s index URL
-
-Return type: str
-
-
-
+
+- Parameters
+obj_type – The object type, i.e. user
or user_reference
+
+- Returns
+The name of the resource, i.e. the last part of the URL for the
+resource’s index URL
+
+- Return type
+str
+
+
-
-
pdpyras.
tokenize_url_path
(url, baseurl='https://api.pagerduty.com')¶
+pdpyras.
tokenize_url_path
(url, baseurl='https://api.pagerduty.com')¶
Classifies a URL according to some global patterns in the API.
If the URL is to access a specific individual resource by ID, the node type
will be identified as {id}
, whereas if it is an index, it will be
@@ -1327,48 +1267,44 @@
Errors
For instance, https://api.pagerduty.com/users
would be classified as
("users", "{index}")
, and https://api.pagerduty.com/users/PABC123
would be classified as ("users", "{id}")
-
-
-
-
-Parameters:
-- url (str) – The URL (or path) to be classified; the function should accept either
-- baseurl (str) – API base URL
+
+- Parameters
+
+url (str) – The URL (or path) to be classified; the function should accept either
+baseurl (str) – API base URL
-
-
-Return type: tuple
-
-
-
-
+
+- Return type
+tuple
+
+
-
-
pdpyras.
try_decoding
(r)¶
+pdpyras.
try_decoding
(r)¶
JSON-decode a response body and raise PDClientError
if it fails.
-
-
-
-
-Parameters: r – requests.Response object
-
-
-
+
+- Parameters
+r – requests.Response object
+
+
2019-10-01: version 3.1.2
+Fixed regression bug / departure from documentation (#17): the payload
parameter does not merge with but rather completely replaces the default payload
2019-04-05: version 3.1.1
PDClientError
in the event of non-transient HTTP error, in the request
method, versus returning the request object and logging it. The previous behavior was:PDClientError
in the event of non-transient HTTP error, in the request
method, versus returning the request object and logging it. The previous behavior was:Not the intended design
At odds with the documentated behavior
User-Agent
header to distinguish the API client as such, for the purposes of usage analyticsIntroduction of a custom User-Agent
header to distinguish the API client as such, for the purposes of usage analytics
2019-04-02: version 3.0.2:
Important bug fixes to the custom HTTP retry logic:
KeyError
in APISession.request
Fixed KeyError
in APISession.request
Fixed incorrect behavior (retrying more than the specified amount of times) due to faulty comparison logic
2019-03-14: version 3.0.1:
A light Events API client methods refactor:
EventsAPISession.send_event
methodsend_event
and uses a catch-all keyword argument to set event properties.All keyword arguments specific to sending trigger events have been refactored out of the generic EventsAPISession.send_event
method
Now, instead, send_event
and uses a catch-all keyword argument to set event properties.
The keyword arguments specific to triggering incidents are in the method EventsAPISession.trigger method.
2019-03-12: version 3.0:
Added new Events API session class that still has most of the same functional features as the REST API session class.
2019-01-28: version 2.4.1:
/log_entries
Fixed bug: unpacking wrapped entities does not work with /log_entries
2019-01-10: version 2.4:
r*
/ *_all
methods has been rescinded, and documentation has been updated with how to identify endpoints that these methods can be used with.Whitelisting of endpoints supported by the r*
/ *_all
methods has been rescinded, and documentation has been updated with how to identify endpoints that these methods can be used with.
2019-01-03: version 2.3:
r*
/ *_all
methods on endpoints they don’t supporttype
property in order to support posting to business impact metricsMore helpful error messaging when using r*
/ *_all
methods on endpoints they don’t support
Resource envelope auto-unpacking no longer validates for the presence of a type
property in order to support posting to business impact metrics
2018-12-04: version 2.2:
list_all
and dict_all
turn all results from an index into a list/dict to save a bit of effortMethods list_all
and dict_all
turn all results from an index into a list/dict to save a bit of effort
2018-11-28: version 2.1:
rput
method.iter_all
is now to raise an exception if an error response is received from the API during iteration.Support for performing multi-update actions (i.e. Manage Incidents) via the rput
method.
The default behavior of iter_all
is now to raise an exception if an error response is received from the API during iteration.
Changelog Started 2018-11-28