commit new documentation build

CHANGELOG.md

@@ -4,7 +4,8 @@ The `2.1.0` release of `petpy` implements several user-defined exceptions to hel
 errors that may occur. Although the `petpy` library attempts to find any invalid passed parameter values and raise the 
 appropriate error before the call to the Petfinder API is made to reduce the number of calls made to the API; however, 
 some errors cannot be caught until after the API call is made. This update introduces these custom, user-defined 
-exceptions for debugging error responses from the Petfinder API. 
+exceptions for debugging error responses from the Petfinder API. For more information on the Petfinder API error 
+definitions, please see the [Petfinder API documentation](https://www.petfinder.com/developers/v2/docs/#errors).
 
 The following is a list of the new user-defined exceptions.
 

docs/build/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 1c0b5de14d3417496c8d3a16acddf901
+config: 66ea139994ced51e5250f75fe157d5e7
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/build/html/_sources/api.rst.txt

@@ -10,10 +10,12 @@ API Reference
 :mod:`Petfinder` -- Petfinder API Wrapper
 -----------------------------------------
 
-.. class:: Petfinder([key], [secret], [host='http://api.petfinder.com/'])
+.. class:: Petfinder([key], [secret])
 
     The Petfinder class provides the wrapper for the Petfinder API. The API methods are listed below
 
+    :param: key: API key received from Petfinder after creating a developer account.
+    :param: secret: Secret key received from Petfinder.
 
 Get Animal Types
 ----------------
@@ -90,4 +92,35 @@ Get Animal Welfare Organization Data
     :param pages: |pages|
     :param return_df: |return_df|
     :rtype: dict or pandas DataFrame. Dictionary object representing the returned JSON object from the Petfinder API.
-            If :code:`return_df=True`, the results are returned as a pandas DataFrame.
+            If :code:`return_df=True`, the results are returned as a pandas DataFrame.
+
+
+API Exceptions
+==============
+
+.. class:: PetfinderError(Exception)
+
+    Base Exception class for Petfinder API Exception definitions.
+
+.. class:: PetfinderInvalidCredentials(PetfinderError)
+
+    Exception for handling invalid API and secret keys passed to the Petfinder class.
+
+.. class:: PetfinderInsufficientAccess(PetfinderError)
+
+    Exception for handling insufficient access errors when working with the Petfinder API. This exception is typically
+    raised when the credentials supplied to the Petfinder API have expired and the connection to the API needs to be
+    re-authenticated.
+
+.. class:: PetfinderResourceNotFound(PetfinderError)
+
+    Exception for handling unknown resource requests.
+
+.. class:: PetfinderUnexpectedError(PetfinderError)
+
+    Exception for handling unexpected errors from the Petfinder API. This error is generally the result of an unknown
+    and unexpected error that occurs on the server-side of the Petfinder API when sending a request.
+
+.. class:: PetfinderInvalidParameters(PetfinderError)
+
+    Exception for handling invalid values passed to Petfinder API method parameters.

docs/build/html/_sources/index.rst.txt

@@ -145,4 +145,9 @@ its usage. The notebooks can also be launched in an `interactive environment <ht
 with `binder <https://mybinder.org/>`_
 
 - `Introduction to petpy <https://github.com/aschleg/petpy/blob/master/docs/notebooks/01-Introduction%20to%20petpy.ipynb>`_
+
+Please note the following notebook is still based on the legacy version of the Petfinder API and thus are not fully
+representative of the functionality and methods of the most recent version of :code:`petpy` and the Petfinder API.
+These are currently being updated to reflect the new version of :code:`petpy`.
+
 - `Download 45,000 Cat Images in 6.5 Minutes with petpy and multiprocessing <https://github.com/aschleg/petpy/blob/master/docs/notebooks/02-Download%2045%2C000%20Adoptable%20Cat%20Images%20with%20petpy%20and%20multiprocessing.ipynb>`_

docs/build/html/_sources/versions.rst.txt

@@ -5,6 +5,41 @@ Version History
 
 Changelog and version changes made with each release.
 
+Version 2.1.0
+-------------
+
+The :code:`2.1.0` release of :code:`petpy` implements several user-defined exceptions to help users debug any
+errors that may occur. Although the :code:`petpy` library attempts to find any invalid passed parameter values and
+raise the appropriate error before the call to the Petfinder API is made to reduce the number of calls made to the
+API; however, some errors cannot be caught until after the API call is made. This update introduces these custom,
+user-defined exceptions for debugging error responses from the Petfinder API. For more information on the Petfinder
+API error definitions, please see the `Petfinder API documentation <https://www.petfinder.com/developers/v2/docs/#errors>`_.
+
+The following is a list of the new user-defined exceptions.
+
+- :code:`PetfinderInvalidCredentials`
+  - Raised when a user enters invalid API key and secret key credentials.
+- :code:`PetfinderInsufficientAccess`
+    - Raised when a `status code 403 <https://httpstatuses.com/403>`_ occurs. This error would typically be
+      raised when the current authentication token to the Petfinder API has expired and requires the connnection
+      to be re-authenticated.
+- :code:`PetfinderResourceNotFound`
+    - Raised when a `status code 404 <https://httpstatuses.com/404>`_ occurs.
+- :code:`PetfinderUnexpectedError`
+    - Raised when a `status code 500 <https://httpstatuses.com/500>`_ occurs.
+- :code:`PetfinderInvalidParameters`
+    - Raised when a `400 status code <https://httpstatuses.com/400>`_ occurs. The exception will include the invalid
+      parameters detected by the Petfinder API and include those parameters as part of the error output as a JSON object.
+      For more information on this error, please see the
+      `Petfinder API error documentation <https://www.petfinder.com/developers/v2/docs/#err-00002>`_.
+    - Please note the `petpy` library will attempt to catch any invalid parameters before the API call is made to avoid
+      extraneous issuage of the API, but if an invalid parameter does get through then this error should help provide
+      the necessary information for users to debug any errors related to their chosen parameters.
+
+The following other changes have been made in the :code:`2.1.0` release.
+
+- The :code:`host` and :code:`auth` attributes of the :code:`Petfinder` class are now private (to the extent that
+  Python allows private attributes, denoted with an underscore in front of the attribute).
 
 Version 2.0.2
 -------------

docs/build/html/_static/documentation_options.js

@@ -1,6 +1,6 @@
 var DOCUMENTATION_OPTIONS = {
     URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
-    VERSION: '2.0.2',
+    VERSION: '2.1.0',
     LANGUAGE: 'None',
     COLLAPSE_INDEX: false,
     FILE_SUFFIX: '.html',

docs/build/html/api.html

@@ -8,7 +8,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
 
-  <title>API Reference &mdash; petpy 2.0.2 documentation</title>
+  <title>API Reference &mdash; petpy 2.1.0 documentation</title>
 
 
 
@@ -93,6 +93,7 @@
 <li class="toctree-l2"><a class="reference internal" href="#get-animal-welfare-organization-data">Get Animal Welfare Organization Data</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="#api-exceptions">API Exceptions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="versions.html">Version History</a></li>
 </ul>
 
@@ -164,8 +165,18 @@
 <h2><code class="xref py py-mod docutils literal notranslate"><span class="pre">Petfinder</span></code> – Petfinder API Wrapper<a class="headerlink" href="#petfinder-petfinder-api-wrapper" title="Permalink to this headline">¶</a></h2>
 <dl class="class">
 <dt id="petpy.api.Petfinder">
-<em class="property">class </em><code class="descclassname">petpy.api.</code><code class="descname">Petfinder</code><span class="sig-paren">(</span><span class="optional">[</span><em>key</em><span class="optional">]</span><span class="optional">[</span>, <em>secret</em><span class="optional">]</span><span class="optional">[</span>, <em>host='http://api.petfinder.com/'</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#petpy.api.Petfinder" title="Permalink to this definition">¶</a></dt>
+<em class="property">class </em><code class="descclassname">petpy.api.</code><code class="descname">Petfinder</code><span class="sig-paren">(</span><span class="optional">[</span><em>key</em><span class="optional">]</span><span class="optional">[</span>, <em>secret</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#petpy.api.Petfinder" title="Permalink to this definition">¶</a></dt>
 <dd><p>The Petfinder class provides the wrapper for the Petfinder API. The API methods are listed below</p>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field-odd field"><th class="field-name">Param:</th><td class="field-body">key: API key received from Petfinder after creating a developer account.</td>
+</tr>
+<tr class="field-even field"><th class="field-name">Param:</th><td class="field-body">secret: Secret key received from Petfinder.</td>
+</tr>
+</tbody>
+</table>
 </dd></dl>
 
 </div>
@@ -293,6 +304,48 @@ <h2>Get Animal Welfare Organization Data<a class="headerlink" href="#get-animal-
 </dd></dl>
 
 </div>
+</div>
+<div class="section" id="api-exceptions">
+<h1>API Exceptions<a class="headerlink" href="#api-exceptions" title="Permalink to this headline">¶</a></h1>
+<dl class="class">
+<dt id="petpy.api.PetfinderError">
+<em class="property">class </em><code class="descclassname">petpy.api.</code><code class="descname">PetfinderError</code><span class="sig-paren">(</span><em>Exception</em><span class="sig-paren">)</span><a class="headerlink" href="#petpy.api.PetfinderError" title="Permalink to this definition">¶</a></dt>
+<dd><p>Base Exception class for Petfinder API Exception definitions.</p>
+</dd></dl>
+
+<dl class="class">
+<dt id="petpy.api.PetfinderInvalidCredentials">
+<em class="property">class </em><code class="descclassname">petpy.api.</code><code class="descname">PetfinderInvalidCredentials</code><span class="sig-paren">(</span><em>PetfinderError</em><span class="sig-paren">)</span><a class="headerlink" href="#petpy.api.PetfinderInvalidCredentials" title="Permalink to this definition">¶</a></dt>
+<dd><p>Exception for handling invalid API and secret keys passed to the Petfinder class.</p>
+</dd></dl>
+
+<dl class="class">
+<dt id="petpy.api.PetfinderInsufficientAccess">
+<em class="property">class </em><code class="descclassname">petpy.api.</code><code class="descname">PetfinderInsufficientAccess</code><span class="sig-paren">(</span><em>PetfinderError</em><span class="sig-paren">)</span><a class="headerlink" href="#petpy.api.PetfinderInsufficientAccess" title="Permalink to this definition">¶</a></dt>
+<dd><p>Exception for handling insufficient access errors when working with the Petfinder API. This exception is typically
+raised when the credentials supplied to the Petfinder API have expired and the connection to the API needs to be
+re-authenticated.</p>
+</dd></dl>
+
+<dl class="class">
+<dt id="petpy.api.PetfinderResourceNotFound">
+<em class="property">class </em><code class="descclassname">petpy.api.</code><code class="descname">PetfinderResourceNotFound</code><span class="sig-paren">(</span><em>PetfinderError</em><span class="sig-paren">)</span><a class="headerlink" href="#petpy.api.PetfinderResourceNotFound" title="Permalink to this definition">¶</a></dt>
+<dd><p>Exception for handling unknown resource requests.</p>
+</dd></dl>
+
+<dl class="class">
+<dt id="petpy.api.PetfinderUnexpectedError">
+<em class="property">class </em><code class="descclassname">petpy.api.</code><code class="descname">PetfinderUnexpectedError</code><span class="sig-paren">(</span><em>PetfinderError</em><span class="sig-paren">)</span><a class="headerlink" href="#petpy.api.PetfinderUnexpectedError" title="Permalink to this definition">¶</a></dt>
+<dd><p>Exception for handling unexpected errors from the Petfinder API. This error is generally the result of an unknown
+and unexpected error that occurs on the server-side of the Petfinder API when sending a request.</p>
+</dd></dl>
+
+<dl class="class">
+<dt id="petpy.api.PetfinderInvalidParameters">
+<em class="property">class </em><code class="descclassname">petpy.api.</code><code class="descname">PetfinderInvalidParameters</code><span class="sig-paren">(</span><em>PetfinderError</em><span class="sig-paren">)</span><a class="headerlink" href="#petpy.api.PetfinderInvalidParameters" title="Permalink to this definition">¶</a></dt>
+<dd><p>Exception for handling invalid values passed to Petfinder API method parameters.</p>
+</dd></dl>
+
 </div>
 
 

docs/build/html/genindex.html

@@ -9,7 +9,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
 
-  <title>Index &mdash; petpy 2.0.2 documentation</title>
+  <title>Index &mdash; petpy 2.1.0 documentation</title>
 
 
 
@@ -85,6 +85,7 @@
 
               <ul>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API Reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="api.html#api-exceptions">API Exceptions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="versions.html">Version History</a></li>
 </ul>
 
@@ -190,6 +191,20 @@ <h2 id="P">P</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="api.html#petpy.api.Petfinder">Petfinder (class in petpy.api)</a>
+</li>
+      <li><a href="api.html#petpy.api.PetfinderError">PetfinderError (class in petpy.api)</a>
+</li>
+      <li><a href="api.html#petpy.api.PetfinderInsufficientAccess">PetfinderInsufficientAccess (class in petpy.api)</a>
+</li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="api.html#petpy.api.PetfinderInvalidCredentials">PetfinderInvalidCredentials (class in petpy.api)</a>
+</li>
+      <li><a href="api.html#petpy.api.PetfinderInvalidParameters">PetfinderInvalidParameters (class in petpy.api)</a>
+</li>
+      <li><a href="api.html#petpy.api.PetfinderResourceNotFound">PetfinderResourceNotFound (class in petpy.api)</a>
+</li>
+      <li><a href="api.html#petpy.api.PetfinderUnexpectedError">PetfinderUnexpectedError (class in petpy.api)</a>
 </li>
   </ul></td>
 </tr></table>

docs/build/html/index.html

@@ -8,7 +8,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
 
-  <title>Petpy - Python Wrapper of the Petfinder API &mdash; petpy 2.0.2 documentation</title>
+  <title>Petpy - Python Wrapper of the Petfinder API &mdash; petpy 2.1.0 documentation</title>
 
 
 
@@ -85,6 +85,7 @@
 
               <ul>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API Reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="api.html#api-exceptions">API Exceptions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="versions.html">Version History</a></li>
 </ul>
 
@@ -262,6 +263,7 @@ <h1>Contents<a class="headerlink" href="#contents" title="Permalink to this head
 <div class="toctree-wrapper compound">
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API Reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="api.html#api-exceptions">API Exceptions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="versions.html">Version History</a></li>
 </ul>
 </div>
@@ -273,6 +275,11 @@ <h1>Tutorials and Examples<a class="headerlink" href="#tutorials-and-examples" t
 with <a class="reference external" href="https://mybinder.org/">binder</a></p>
 <ul class="simple">
 <li><a class="reference external" href="https://github.com/aschleg/petpy/blob/master/docs/notebooks/01-Introduction%20to%20petpy.ipynb">Introduction to petpy</a></li>
+</ul>
+<p>Please note the following notebook is still based on the legacy version of the Petfinder API and thus are not fully
+representative of the functionality and methods of the most recent version of <code class="code docutils literal notranslate"><span class="pre">petpy</span></code> and the Petfinder API.
+These are currently being updated to reflect the new version of <code class="code docutils literal notranslate"><span class="pre">petpy</span></code>.</p>
+<ul class="simple">
 <li><a class="reference external" href="https://github.com/aschleg/petpy/blob/master/docs/notebooks/02-Download%2045%2C000%20Adoptable%20Cat%20Images%20with%20petpy%20and%20multiprocessing.ipynb">Download 45,000 Cat Images in 6.5 Minutes with petpy and multiprocessing</a></li>
 </ul>
 </div>

docs/build/html/objects.inv

@@ -2,4 +2,5 @@
 # Project: petpy
 # Version: 2.0
 # The remainder of this file is compressed using zlib.
-xڕ�AK�0���zm��"�7� =�l3mi�Q����l�����d�{�M&����j;�AI\��C�+ȍ�g}q	�p?���Q�pt�p&�����L���35֏)�YY�4] ��I�C��������t�4Ho��Q�#���^�K�x��Q��1{Ct�A�@���=:������g)[�V���b�4�录����=�}��
�j�\�XӍ����R+�c�w8�xK_K�X/�B?�ܩ���Zq�4i��U�Vw��
+xڕ�AK�0���z��E�E����(�d����L������n[1�f�}�%��!�~!�^Tȵ�
+=�~)�
�`h4ܚ�K(�S�V�¼s�0`�ܐ�?�	m=��d��bև`M6��Ʊ���k-5Z^I�!��{a����"���ɤ+�E< �,x��:/���:�r����Q�=����j�HB9�`U�a�5z��*#�h���1W������TM���e�쉢%T}�޼p.�
����Q��%�K���S#Y>�����?&�	�����MPx��#R-I�S�;,����VO�O��~M+xЁ��s��?c⠿S�N�u�

docs/build/html/parameters.html

@@ -8,7 +8,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
 
-  <title>&lt;no title&gt; &mdash; petpy 2.0.2 documentation</title>
+  <title>&lt;no title&gt; &mdash; petpy 2.1.0 documentation</title>
 
 
 
@@ -84,6 +84,7 @@
 
               <ul>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API Reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="api.html#api-exceptions">API Exceptions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="versions.html">Version History</a></li>
 </ul>
 

docs/build/html/search.html

@@ -8,7 +8,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
 
-  <title>Search &mdash; petpy 2.0.2 documentation</title>
+  <title>Search &mdash; petpy 2.1.0 documentation</title>
 
 
 
@@ -85,6 +85,7 @@
 
               <ul>
 <li class="toctree-l1"><a class="reference internal" href="api.html">API Reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="api.html#api-exceptions">API Exceptions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="versions.html">Version History</a></li>
 </ul>