Merge pull request #21 from PagerDuty/contribution-guide-fixes

Contribution guide fixes

CHANGELOG.rst

@@ -1,3 +1,4 @@
-**2024-12-20: (placeholder)**
+**2025-01-03: Migrate from PDPYRAS - Version v0.9.0**
 
-* This is the start of the Changelog so that the makefile target works. It will be updated when version 1.0.0 is released.
+* **BREAKING CHANGE:** class names have changed from what they were in ``pdpyras``; see :ref:`pdpyras_migration_guide` for details.
+* The REST API client now supports new status page, event orchestrations, custom incident fields, OAuth delegations and alert grouping settings APIs.

docs/changelog.html

@@ -76,9 +76,10 @@
 
   <section id="changelog">
 <h1>Changelog<a class="headerlink" href="#changelog" title="Permalink to this heading"></a></h1>
-<p><strong>2024-12-20: (placeholder)</strong></p>
+<p><strong>2025-01-03: Migrate from PDPYRAS - Version v0.9.0</strong></p>
 <ul class="simple">
-<li><p>This is the start of the Changelog so that the makefile target works. It will be updated when version 1.0.0 is released.</p></li>
+<li><p><strong>BREAKING CHANGE:</strong> class names have changed from what they were in <code class="docutils literal notranslate"><span class="pre">pdpyras</span></code>; see <span class="xref std std-ref">pdpyras_migration_guide</span> for details.</p></li>
+<li><p>The REST API client now supports new status page, event orchestrations, custom incident fields, OAuth delegations and alert grouping settings APIs.</p></li>
 </ul>
 </section>
 

docs/contributing.html

@@ -52,7 +52,9 @@
 <li class="toctree-l2"><a class="reference internal" href="#maintaining-entity-wrapper-configuration">Maintaining Entity Wrapper Configuration</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="#introduction">Introduction</a></li>
 <li class="toctree-l3"><a class="reference internal" href="#limitations">Limitations</a></li>
-<li class="toctree-l3"><a class="reference internal" href="#adding-support-for-new-endpoints">Adding Support for New Endpoints</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#updating-the-canonical-path-set">Updating the Canonical Path Set</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#evaluating-new-endpoints-for-support">Evaluating New Endpoints For Support</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#adding-support-for-non-conforming-endpoints">Adding Support for Non-Conforming Endpoints</a></li>
 </ul>
 </li>
 <li class="toctree-l2"><a class="reference internal" href="#updating-documentation">Updating Documentation</a></li>
@@ -141,8 +143,8 @@ <h3>Introduction<a class="headerlink" href="#introduction" title="Permalink to t
 antipattern-handling configuration.</p>
 <p>This system requires two global variables that must be manually maintained:</p>
 <ul class="simple">
-<li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">CANONICAL_PATHS</span></code>, the list of canonical paths</p></li>
-<li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">ENTITY_WRAPPER_CONFIG</span></code>, a dictionary of exceptions to entity wrapping and schema conventions</p></li>
+<li><p><a class="reference internal" href="module_reference.html#pagerduty.CANONICAL_PATHS" title="pagerduty.CANONICAL_PATHS"><code class="xref py py-attr docutils literal notranslate"><span class="pre">pagerduty.CANONICAL_PATHS</span></code></a>, the list of canonical paths</p></li>
+<li><p><a class="reference internal" href="module_reference.html#pagerduty.ENTITY_WRAPPER_CONFIG" title="pagerduty.ENTITY_WRAPPER_CONFIG"><code class="xref py py-attr docutils literal notranslate"><span class="pre">pagerduty.ENTITY_WRAPPER_CONFIG</span></code></a>, a dictionary of exceptions to entity wrapping and schema conventions</p></li>
 </ul>
 </section>
 <section id="limitations">
@@ -162,22 +164,60 @@ <h3>Limitations<a class="headerlink" href="#limitations" title="Permalink to thi
 according to documented standards, automatic pagination cannot be supported for
 resource collection endpoints.</p>
 </section>
-<section id="adding-support-for-new-endpoints">
-<h3>Adding Support for New Endpoints<a class="headerlink" href="#adding-support-for-new-endpoints" title="Permalink to this heading"></a></h3>
+<section id="updating-the-canonical-path-set">
+<h3>Updating the Canonical Path Set<a class="headerlink" href="#updating-the-canonical-path-set" title="Permalink to this heading"></a></h3>
 <p>The first step for adding support for new APIs is to have a copy of the API
 Reference source code (this is a private GitHub repository owned by the
 PagerDuty org). The script <code class="docutils literal notranslate"><span class="pre">scripts/get_path_list/get_path_list.py</span></code> can then
 be used to automatically generate definitions of the global variables
-<code class="xref py py-attr docutils literal notranslate"><span class="pre">CANONICAL_PATHS</span></code> and <code class="xref py py-attr docutils literal notranslate"><span class="pre">CURSOR_BASED_PAGINATION_PATHS</span></code> that can be
-copied into the source code to replace the existing definitions. The script
-takes one argument: a path to the file <code class="docutils literal notranslate"><span class="pre">reference/v2/Index.yaml</span></code> within the
-reference source repository.</p>
-<p>The next step is to look at the documentation, for each new endpoint added to
-the canonical path list, to see if it follows classic schema conventions for
-entity wrapping. If any new path does not, adding support for it will also
-require adding entries to <a class="reference internal" href="module_reference.html#pagerduty.ENTITY_WRAPPER_CONFIG" title="pagerduty.ENTITY_WRAPPER_CONFIG"><code class="xref py py-attr docutils literal notranslate"><span class="pre">pagerduty.ENTITY_WRAPPER_CONFIG</span></code></a>.</p>
-<p>Following the same examples as given in the <a class="reference internal" href="user_guide.html#user-guide"><span class="std std-ref">User Guide</span></a>:  the entry in
-<code class="xref py py-attr docutils literal notranslate"><span class="pre">ENTITY_WRAPPER_CONFIG</span></code> to handle the “Create Business Service
+<a class="reference internal" href="module_reference.html#pagerduty.CANONICAL_PATHS" title="pagerduty.CANONICAL_PATHS"><code class="xref py py-attr docutils literal notranslate"><span class="pre">pagerduty.CANONICAL_PATHS</span></code></a> and
+<a class="reference internal" href="module_reference.html#pagerduty.CURSOR_BASED_PAGINATION_PATHS" title="pagerduty.CURSOR_BASED_PAGINATION_PATHS"><code class="xref py py-attr docutils literal notranslate"><span class="pre">pagerduty.CURSOR_BASED_PAGINATION_PATHS</span></code></a> that can be copied into the
+source code to replace the existing definitions. The script takes one argument:
+a path to the file <code class="docutils literal notranslate"><span class="pre">reference/v2/Index.yaml</span></code> within the reference source
+repository.</p>
+</section>
+<section id="evaluating-new-endpoints-for-support">
+<h3>Evaluating New Endpoints For Support<a class="headerlink" href="#evaluating-new-endpoints-for-support" title="Permalink to this heading"></a></h3>
+<p>The next step is to look at the request and response schemas in the API
+reference for each new endpoint added to the canonical path list, to see if it
+follows classic schema conventions for entity wrapping. If any new path does
+not, adding support for it will also require adding entries to
+<a class="reference internal" href="module_reference.html#pagerduty.ENTITY_WRAPPER_CONFIG" title="pagerduty.ENTITY_WRAPPER_CONFIG"><code class="xref py py-attr docutils literal notranslate"><span class="pre">pagerduty.ENTITY_WRAPPER_CONFIG</span></code></a>. “Classic schema conventions” refers to
+the logic codified in <a class="reference internal" href="module_reference.html#pagerduty.infer_entity_wrapper" title="pagerduty.infer_entity_wrapper"><code class="xref py py-attr docutils literal notranslate"><span class="pre">pagerduty.infer_entity_wrapper</span></code></a> and
+<a class="reference internal" href="module_reference.html#pagerduty.unwrap" title="pagerduty.unwrap"><code class="xref py py-attr docutils literal notranslate"><span class="pre">pagerduty.unwrap</span></code></a> (where a “node” is a component of the path component
+of the URL, separated by forward slashes):</p>
+<p><strong>1:</strong> If the last node of the path is an opaque identifier, then the path corresponds
+to an individual PagerDuty resource, and the request and response wrapper names
+are both the singular form of the second-to-last node. Examples: <code class="docutils literal notranslate"><span class="pre">PUT</span>
+<span class="pre">/escalation_policies/{id}</span></code> (wrapper = <code class="docutils literal notranslate"><span class="pre">escalation_policy</span></code>), <code class="docutils literal notranslate"><span class="pre">GET</span>
+<span class="pre">/users/{id}</span></code> (wrapper = <code class="docutils literal notranslate"><span class="pre">user</span></code>).</p>
+<p><strong>2:</strong> If the last node of the path is not an opaque identifier, and the
+request method is POST, then the request and response wrapper names are both
+the singular form of the last node. Examples: <code class="docutils literal notranslate"><span class="pre">POST</span> <span class="pre">/schedules</span></code> (wrapper =
+<code class="docutils literal notranslate"><span class="pre">schedule</span></code>), <code class="docutils literal notranslate"><span class="pre">POST</span> <span class="pre">/incidents</span></code> (wrapper = <code class="docutils literal notranslate"><span class="pre">incident</span></code>)</p>
+<p><strong>3:</strong> Otherwise (the last node of the path is not an opaque identifier and the
+request method is not POST), the request and response wrapper names are both
+the same as the last node of the path. Examples: <code class="docutils literal notranslate"><span class="pre">GET</span> <span class="pre">/services</span></code> (wrapper =
+<code class="docutils literal notranslate"><span class="pre">services</span></code>), <code class="docutils literal notranslate"><span class="pre">PUT</span> <span class="pre">/incidents</span></code> (wrapper = <code class="docutils literal notranslate"><span class="pre">incidents</span></code>)</p>
+<p>If all of the above apply to new endpoints for all request methods, then no new
+entries need to be added to <a class="reference internal" href="module_reference.html#pagerduty.ENTITY_WRAPPER_CONFIG" title="pagerduty.ENTITY_WRAPPER_CONFIG"><code class="xref py py-attr docutils literal notranslate"><span class="pre">pagerduty.ENTITY_WRAPPER_CONFIG</span></code></a> to support
+them; they are supported automatically by virtue of following preexisting
+already-supported API patterns and having corresponding entries in
+<a class="reference internal" href="module_reference.html#pagerduty.CANONICAL_PATHS" title="pagerduty.CANONICAL_PATHS"><code class="xref py py-attr docutils literal notranslate"><span class="pre">pagerduty.CANONICAL_PATHS</span></code></a>.</p>
+</section>
+<section id="adding-support-for-non-conforming-endpoints">
+<h3>Adding Support for Non-Conforming Endpoints<a class="headerlink" href="#adding-support-for-non-conforming-endpoints" title="Permalink to this heading"></a></h3>
+<p>If the new endpoints do not follow classic schema conventions for entity
+wrapping, entries for them must be added to
+<a class="reference internal" href="module_reference.html#pagerduty.ENTITY_WRAPPER_CONFIG" title="pagerduty.ENTITY_WRAPPER_CONFIG"><code class="xref py py-attr docutils literal notranslate"><span class="pre">pagerduty.ENTITY_WRAPPER_CONFIG</span></code></a> in order to support them. As described
+in the documentation of that attribute, each key is a combination of the
+request method (or “*” for the configuration entry to apply to all methods) and
+the canonical path in question, and each value is a string (for the same
+wrapper name in the request and response bodies), <code class="docutils literal notranslate"><span class="pre">None</span></code> if entity wrapping
+is not applicable, and a tuple if the entity wrapping differs between the
+request and response bodies.</p>
+<p>Following the same examples as given in the <a class="reference internal" href="user_guide.html#user-guide"><span class="std std-ref">User Guide</span></a>: the entry in
+<a class="reference internal" href="module_reference.html#pagerduty.ENTITY_WRAPPER_CONFIG" title="pagerduty.ENTITY_WRAPPER_CONFIG"><code class="xref py py-attr docutils literal notranslate"><span class="pre">pagerduty.ENTITY_WRAPPER_CONFIG</span></code></a> to handle the “Create Business Service
 Subscribers” looks like this:</p>
 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="s1">&#39;POST /business_services/</span><span class="si">{id}</span><span class="s1">/subscribers&#39;</span><span class="p">:</span> <span class="p">(</span><span class="s1">&#39;subscribers&#39;</span><span class="p">,</span> <span class="s1">&#39;subscriptions&#39;</span><span class="p">),</span>
 </pre></div>

docs/index.html

@@ -175,7 +175,9 @@ <h2>Table of Contents<a class="headerlink" href="#table-of-contents" title="Perm
 <li class="toctree-l2"><a class="reference internal" href="contributing.html#maintaining-entity-wrapper-configuration">Maintaining Entity Wrapper Configuration</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="contributing.html#introduction">Introduction</a></li>
 <li class="toctree-l3"><a class="reference internal" href="contributing.html#limitations">Limitations</a></li>
-<li class="toctree-l3"><a class="reference internal" href="contributing.html#adding-support-for-new-endpoints">Adding Support for New Endpoints</a></li>
+<li class="toctree-l3"><a class="reference internal" href="contributing.html#updating-the-canonical-path-set">Updating the Canonical Path Set</a></li>
+<li class="toctree-l3"><a class="reference internal" href="contributing.html#evaluating-new-endpoints-for-support">Evaluating New Endpoints For Support</a></li>
+<li class="toctree-l3"><a class="reference internal" href="contributing.html#adding-support-for-non-conforming-endpoints">Adding Support for Non-Conforming Endpoints</a></li>
 </ul>
 </li>
 <li class="toctree-l2"><a class="reference internal" href="contributing.html#updating-documentation">Updating Documentation</a></li>

docs/pdpyras_migration_guide.html

@@ -101,6 +101,11 @@ <h2>Client Classes<a class="headerlink" href="#client-classes" title="Permalink
 <li><p><code class="docutils literal notranslate"><span class="pre">s/APISession/RestApiV2Client/g</span></code></p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">s/PDSession/ApiClient/g</span></code></p></li>
 </ol>
+<p>The Change Events API client has been merged into the Events API v2 client
+because the differences between these two APIs are trivial enough to support
+them both under the same client class, and there is no method or property name
+overlap between the client classes. Their respective APIs are also documented
+under the same API reference.</p>
 </section>
 <section id="exception-classes">
 <h2>Exception Classes<a class="headerlink" href="#exception-classes" title="Permalink to this heading"></a></h2>

pagerduty.py

@@ -352,7 +352,6 @@
     'POST /extensions/{id}/enable': (None, 'extension'),
 
     # Incidents
-    'PUT /incidents': 'incidents', # Multi-update
     'PUT /incidents/{id}/merge': ('source_incidents', 'incident'),
     'POST /incidents/{id}/responder_requests': (None, 'responder_request'),
     'POST /incidents/{id}/snooze': (None, 'incident'),