commit to update docs and some fixes for 2.0.1 release

CHANGELOG.md

@@ -1,11 +1,21 @@
+## Version 2.0.1
+
+- Fixes the `animals()` and `organizations()` method to return all matching search results when the `pages` parameter 
+  is set to `None`.
+- The resulting JSON (dictionary) from the `breeds()` method when the parameter `return_df=False` will now consistently 
+  have `types` as the key. Prior to this change, if the `breeds()` method was called with a single animal type, the 
+  resulting key name in the returned object would be named `type`, whereas if more than one animal type is specified 
+  the key name would be `types`.
+- The `distance` parameter for the `animals()` and `organizations()` parameters will now raise a `ValueError` if it is 
+  less than 0.
+
 # Version 2.0.0
 
 New major release coinciding with the release of [v2.0 of the Petfinder API](https://www.petfinder.com/developers/)! 
 The legacy version of the Petfinder API, v1.0, will be retired in January 2020, therefore, the `petpy` library has 
 been updated almost from the ground up to be compatible as possible with the new version of the Petfinder API! The 
 new version of the Petfinder API is a huge improvement over the legacy version, with many changes and additions to 
-the design of the API itself. As such, several methods from earlier releases of `petpy` that wrapped these endpoints 
-will be deprecated over the next few releases.
+the design of the API itself. 
 
 Below is a summary of all the changes made in the release of `petpy 2.0`. 
 

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: 42900eae3e759e32265cfe559f1bec05
+config: ac03f6a75fb2bca48e096cef5c4abd3a
 tags: 645f666f9bcd5a90fca523b33c5a78b7

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

@@ -53,6 +53,79 @@ Authentication to the Petfinder API occurs when the :code:`Petfinder()` class is
 
 Calls to the API to extract data can now be made!
 
+Finding Animal Types
+--------------------
+
+.. code-block :: python
+
+   # All animal types and their relevant data.
+   all_types = pf.animal_types()
+
+   # Returning data for a single animal type
+   dogs = pf.animal_types('dog')
+
+   # Getting multiple animal types at once
+   cat_dog_rabbit_types = pf.animal_types(['cat', 'dog', 'rabbit'])
+
+Get Breeds of Animal Types
+--------------------------
+
+.. code-block :: python
+
+   cat_breeds = pf.breeds('cat')
+   dog_breeds = pf.breeds('dog')
+
+   # All available breeds or multiple breeds can also be returned.
+   all_breeds = pf.breeds()
+   cat_dog_rabbit = pf.breeds(types=['cat', 'dog', 'rabbit'])
+
+The `breeds` method can also be set to coerce the returned JSON results into a pandas DataFrame by setting
+the parameter `return_df = True`.
+
+.. code-block :: python
+
+   cat_breeds_df = pf.breeds('cat', return_df = True)
+   all_breeds_df = pf.breeds(return_df = True)
+
+Getting animals on Petfinder
+----------------------------
+
+The :code:`animals()` method returns animals based on specified criteria that are listed in the Petfinder database.
+Specific animals can be searched using the :code:`animal_id` parameter, or a search of the database can be performed
+by entering the desired search criteria.
+
+.. code-block :: python
+
+   # Getting first 20 results without any search criteria
+   animals = pf.animals()
+
+   # Extracting data on specific animals with animal_ids
+
+   animal_ids = []
+   for i in animals['animals'][0:3]:
+       animal_ids.append(i['id'])
+
+   animal_data = pf.animals(animal_id=animal_ids)
+
+   # Returning a pandas DataFrame of the first 150 animal results
+   animals = pf.animals(results_per_page=50, pages=3, return_df=True)
+
+
+Getting animal welfare organizations in the Petfinder database
+--------------------------------------------------------------
+
+Similar to the :code:`animals()` method described above, the :code:`organizations()` method returns data on animal
+welfare organizations listed in the Petfinder database based on specific criteria, if any. In addition to a general
+search of animal welfare organizations, specific organizational data can be extracted by supplying the
+:code:`organizations()` method with organization IDs.
+
+.. code-block :: python
+
+   # Return the first 1,000 animal welfare organizations as a pandas DataFrame
+   organizations = pf.organizations(results_per_page=100, pages=10, return_df=True)
+
+   # Get organizations in the state of Washington
+   wa_organizations = pf.organizations(state='WA')
 
 Contents
 ========

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

@@ -5,10 +5,59 @@ Version History
 
 Changelog and version changes made with each release.
 
-Version 2.0.0
+Version 2.0.1
 -------------
 
+- Fixes the :code:`animals()` and :code:`organizations()` method to return all matching search results when the
+  :code:`pages` parameter is set to :code:`None`.
+- The resulting JSON (dictionary) from the :code:`breeds()` method when the parameter :code:`return_df=False` will now
+  consistently have :code:`types` as the key. Prior to this change, if the :code:`breeds()` method was called with a
+  single animal type, the resulting key name in the returned object would be named :code:`type`, whereas if more than
+  one animal type is specified the key name would be :code:`types`.
+- The :code:`distance` parameter for the :code:`animals()` and :code:`organizations()` parameters will now raise a
+  :code:`ValueError` if it is less than 0.
+
+Version 2.0.0
+-------------
 
+New major release coinciding with the release of `v2.0 of the Petfinder API <https://www.petfinder.com/developers/>`_!
+The legacy version of the Petfinder API, v1.0, will be retired in January 2020, therefore, the :code:`petpy` library has
+been updated almost from the ground up to be compatible as possible with the new version of the Petfinder API! The
+new version of the Petfinder API is a huge improvement over the legacy version, with many changes and additions to
+the design of the API itself. As such, several methods from earlier releases of :code:`petpy` that wrapped these
+endpoints will be deprecated over the next few releases.
+
+Below is a summary of all the changes made in the release of :code:`petpy 2.0`.
+
+- :code:`petpy` now supports the latest release of Python 3.7
+- Support for Python 2.7 is discontinued as Python 2.7 will be officially discontinued in January 2020.
+- The following methods have been added to :code:`petpy` to make it compatible with v2.0 of the Petfinder API.
+    - :code:`animal_types()` is used to getting animal types (or type) available from the Petfinder API. The release
+      of v2.0 of the Petfinder API added several endpoints for accessing animal types in the Petfinder database.
+      This method wraps both Petfinder API endpoints for getting animal types. More information on the animal type
+      endpoints in the Petfinder API can be found in its documentation:
+      - `Get Animal Types <https://www.petfinder.com/developers/v2/docs/#get-animal-types>`_
+      - `Get Single Animal Type <https://www.petfinder.com/developers/v2/docs/#get-a-single-animal-type>`_
+    - :code:`breeds()` is the new method for getting available animal breeds from the Petfinder database. The API
+      endpoint documentation is available on the Petfinder API documentation page.
+      - `Get Animal Breeds <https://www.petfinder.com/developers/v2/docs/#get-animal-breeds>`_
+    - :code:`animals()` is the method for extracting animal data available on the Petfinder API and deprecates the
+      :code:`pets()` related methods. The method wraps both the :code:`animals` and :code:`animal/{id}` endpoints of
+      the Petfinder API. The documentation for these endpoints can be found in the Petfinder API documentation:
+      - `Get Animal <https://www.petfinder.com/developers/v2/docs/#get-animal>`_
+      - `Get Animals <https://www.petfinder.com/developers/v2/docs/#get-animals>`_
+    - :code:`organizations()` is now the method for extracting animal welfare organization data available on Petfinder
+      and deprecates previous :code:`shelter()` related methods and endpoints. The :code:`organizations()` method wraps
+      both the Petfinder API :code:`organizations` and :code:`organizations/{id}` endpoints. The Petfinder API
+      documentation for these two endpoints can be found below:
+      - `Get Organizations <https://www.petfinder.com/developers/v2/docs/#get-organizations>`_
+      - `Get Organization <https://www.petfinder.com/developers/v2/docs/#get-organization>`_
+- The following methods have been removed as they are no longer valid endpoints with the release of v2.0 of the
+  PetFinder API.
+  - :code:`pet_get_random()`
+  - :code:`shelter_list_by_breed()`
+  - :code:`shelter_get_pets()`
+- General refactoring and code clean-up.
 
 Version 1.8.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.0',
+    VERSION: '2.0.1',
     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.0 documentation</title>
+  <title>API Reference &mdash; petpy 2.0.1 documentation</title>
 
 
 

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.0 documentation</title>
+  <title>Index &mdash; petpy 2.0.1 documentation</title>
 
 
 

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.0 documentation</title>
+  <title>Petpy - Python Wrapper of the Petfinder API &mdash; petpy 2.0.1 documentation</title>
 
 
 
@@ -191,6 +191,71 @@ <h2>Authenticating with the Petfinder API<a class="headerlink" href="#authentica
 </div>
 <p>Calls to the API to extract data can now be made!</p>
 </div>
+<div class="section" id="finding-animal-types">
+<h2>Finding Animal Types<a class="headerlink" href="#finding-animal-types" title="Permalink to this headline">¶</a></h2>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># All animal types and their relevant data.</span>
+<span class="n">all_types</span> <span class="o">=</span> <span class="n">pf</span><span class="o">.</span><span class="n">animal_types</span><span class="p">()</span>
+
+<span class="c1"># Returning data for a single animal type</span>
+<span class="n">dogs</span> <span class="o">=</span> <span class="n">pf</span><span class="o">.</span><span class="n">animal_types</span><span class="p">(</span><span class="s1">&#39;dog&#39;</span><span class="p">)</span>
+
+<span class="c1"># Getting multiple animal types at once</span>
+<span class="n">cat_dog_rabbit_types</span> <span class="o">=</span> <span class="n">pf</span><span class="o">.</span><span class="n">animal_types</span><span class="p">([</span><span class="s1">&#39;cat&#39;</span><span class="p">,</span> <span class="s1">&#39;dog&#39;</span><span class="p">,</span> <span class="s1">&#39;rabbit&#39;</span><span class="p">])</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="get-breeds-of-animal-types">
+<h2>Get Breeds of Animal Types<a class="headerlink" href="#get-breeds-of-animal-types" title="Permalink to this headline">¶</a></h2>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">cat_breeds</span> <span class="o">=</span> <span class="n">pf</span><span class="o">.</span><span class="n">breeds</span><span class="p">(</span><span class="s1">&#39;cat&#39;</span><span class="p">)</span>
+<span class="n">dog_breeds</span> <span class="o">=</span> <span class="n">pf</span><span class="o">.</span><span class="n">breeds</span><span class="p">(</span><span class="s1">&#39;dog&#39;</span><span class="p">)</span>
+
+<span class="c1"># All available breeds or multiple breeds can also be returned.</span>
+<span class="n">all_breeds</span> <span class="o">=</span> <span class="n">pf</span><span class="o">.</span><span class="n">breeds</span><span class="p">()</span>
+<span class="n">cat_dog_rabbit</span> <span class="o">=</span> <span class="n">pf</span><span class="o">.</span><span class="n">breeds</span><span class="p">(</span><span class="n">types</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;cat&#39;</span><span class="p">,</span> <span class="s1">&#39;dog&#39;</span><span class="p">,</span> <span class="s1">&#39;rabbit&#39;</span><span class="p">])</span>
+</pre></div>
+</div>
+<p>The <cite>breeds</cite> method can also be set to coerce the returned JSON results into a pandas DataFrame by setting
+the parameter <cite>return_df = True</cite>.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">cat_breeds_df</span> <span class="o">=</span> <span class="n">pf</span><span class="o">.</span><span class="n">breeds</span><span class="p">(</span><span class="s1">&#39;cat&#39;</span><span class="p">,</span> <span class="n">return_df</span> <span class="o">=</span> <span class="bp">True</span><span class="p">)</span>
+<span class="n">all_breeds_df</span> <span class="o">=</span> <span class="n">pf</span><span class="o">.</span><span class="n">breeds</span><span class="p">(</span><span class="n">return_df</span> <span class="o">=</span> <span class="bp">True</span><span class="p">)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="getting-animals-on-petfinder">
+<h2>Getting animals on Petfinder<a class="headerlink" href="#getting-animals-on-petfinder" title="Permalink to this headline">¶</a></h2>
+<p>The <code class="code docutils literal notranslate"><span class="pre">animals()</span></code> method returns animals based on specified criteria that are listed in the Petfinder database.
+Specific animals can be searched using the <code class="code docutils literal notranslate"><span class="pre">animal_id</span></code> parameter, or a search of the database can be performed
+by entering the desired search criteria.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Getting first 20 results without any search criteria</span>
+<span class="n">animals</span> <span class="o">=</span> <span class="n">pf</span><span class="o">.</span><span class="n">animals</span><span class="p">()</span>
+
+<span class="c1"># Extracting data on specific animals with animal_ids</span>
+
+<span class="n">animal_ids</span> <span class="o">=</span> <span class="p">[]</span>
+<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">animals</span><span class="p">[</span><span class="s1">&#39;animals&#39;</span><span class="p">][</span><span class="mi">0</span><span class="p">:</span><span class="mi">3</span><span class="p">]:</span>
+    <span class="n">animal_ids</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">i</span><span class="p">[</span><span class="s1">&#39;id&#39;</span><span class="p">])</span>
+
+<span class="n">animal_data</span> <span class="o">=</span> <span class="n">pf</span><span class="o">.</span><span class="n">animals</span><span class="p">(</span><span class="n">animal_id</span><span class="o">=</span><span class="n">animal_ids</span><span class="p">)</span>
+
+<span class="c1"># Returning a pandas DataFrame of the first 150 animal results</span>
+<span class="n">animals</span> <span class="o">=</span> <span class="n">pf</span><span class="o">.</span><span class="n">animals</span><span class="p">(</span><span class="n">results_per_page</span><span class="o">=</span><span class="mi">50</span><span class="p">,</span> <span class="n">pages</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span> <span class="n">return_df</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="getting-animal-welfare-organizations-in-the-petfinder-database">
+<h2>Getting animal welfare organizations in the Petfinder database<a class="headerlink" href="#getting-animal-welfare-organizations-in-the-petfinder-database" title="Permalink to this headline">¶</a></h2>
+<p>Similar to the <code class="code docutils literal notranslate"><span class="pre">animals()</span></code> method described above, the <code class="code docutils literal notranslate"><span class="pre">organizations()</span></code> method returns data on animal
+welfare organizations listed in the Petfinder database based on specific criteria, if any. In addition to a general
+search of animal welfare organizations, specific organizational data can be extracted by supplying the
+<code class="code docutils literal notranslate"><span class="pre">organizations()</span></code> method with organization IDs.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Return the first 1,000 animal welfare organizations as a pandas DataFrame</span>
+<span class="n">organizations</span> <span class="o">=</span> <span class="n">pf</span><span class="o">.</span><span class="n">organizations</span><span class="p">(</span><span class="n">results_per_page</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span> <span class="n">pages</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">return_df</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
+
+<span class="c1"># Get organizations in the state of Washington</span>
+<span class="n">wa_organizations</span> <span class="o">=</span> <span class="n">pf</span><span class="o">.</span><span class="n">organizations</span><span class="p">(</span><span class="n">state</span><span class="o">=</span><span class="s1">&#39;WA&#39;</span><span class="p">)</span>
+</pre></div>
+</div>
+</div>
 </div>
 <div class="section" id="contents">
 <h1>Contents<a class="headerlink" href="#contents" title="Permalink to this headline">¶</a></h1>

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.0 documentation</title>
+  <title>&lt;no title&gt; &mdash; petpy 2.0.1 documentation</title>
 
 
 

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.0 documentation</title>
+  <title>Search &mdash; petpy 2.0.1 documentation</title>