Merge branch 'master' into release

README.rst

@@ -56,6 +56,14 @@ Documentation is published on `ReadTheDocs <http://pypexels.readthedocs.io/>`_.
 #######
 Version
 #######
+**PyPexels v1.0.0b3 (beta, v3)**
+
+    Third beta release introduces support for `curated` and `random`.
+
+    Note that using this library you still need to abide to Pexels Guidelines, which
+    are explained on `Pexels API page <https://www.pexels.com/api/>`_
+
+
 **PyPexels v1.0.0b2 (beta, v2)**
 
     Second beta release introduces Python3 support.

docs/source/classes/class_curated.rst

@@ -0,0 +1,252 @@
+##################
+API: Class Curated
+##################
+This class is used to access the **curated** photos on the ``PyPexels`` ``/curated/`` REST API.
+
+It is returned as result from a call to ``PyPexels.curated(page, per_page)``
+
+
+==========
+Properties
+==========
+Properties exposed by the ``Curated`` class.
+
+-----------------------------------------------------
+**Curated.entries**
+-----------------------------------------------------
+    Iterator for the returned objects contained in this ``Curated`` instance.
+    Each entry will be an instance of class ``Photo``.
+
+    ==========  ========================================
+    iterator    each time an instance of class ``Photo``
+    ==========  ========================================
+
+    **Example**
+    ::
+
+        import pypexels
+        py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')
+
+        #
+        #
+        curated_photos_page = py_pexel.curated(per_page=40)
+        for photo in curated_photos_page.entries:
+            print(photo.id, photo.photographer, photo.url)
+            # no need to specify per_page: will take from original object
+            curated_photos_page = curated_photos_page.get_next_page()
+        curated_results = py_pexel.curated(per_page=40)
+        for photo in curated_results.entries:
+            print(photo.id, photo.photographer, photo.url)
+
+-----------------------------------------------------
+**Curated.page**
+-----------------------------------------------------
+    Current curated photos page number.
+
+    ==========  ========================================
+    int         current curated photos page number
+    ==========  ========================================
+
+-----------------------------------------------------
+**Curated.per_page**
+-----------------------------------------------------
+    Current curated photos per_page value.
+
+    ==========  ========================================
+    int         current curated photos per_page value
+    ==========  ========================================
+
+-----------------------------------------------------
+**Curated.has_previous**
+-----------------------------------------------------
+    Returns boolean **True** or **False** depending on whether the current results page
+    has a previous page to navigate to or not.
+
+    ==========  ========================================
+    boolean     presence of previous page results
+    ==========  ========================================
+
+-----------------------------------------------------
+**Curated.has_next**
+-----------------------------------------------------
+    Returns boolean **True** or **False** depending on whether the current results page
+    has a next page to navigate to or not.
+
+    ==========  ========================================
+    boolean     presence of next page results
+    ==========  ========================================
+
+-----------------------------------------------------
+**Curated.body**
+-----------------------------------------------------
+    Returns JSON body of curated photos page.
+
+    ==========  ========================================
+    JSON        JSON converted body of results page
+    ==========  ========================================
+
+-----------------------------------------------------
+**Curated.headers**
+-----------------------------------------------------
+    Returns response headers of curated photos page.
+
+    ==========  ========================================
+    dict        headers of results page
+    ==========  ========================================
+
+-----------------------------------------------------
+**Curated.link_self**
+-----------------------------------------------------
+    Returns URL to current results page
+
+    ==========  ========================================
+    str         URL to current results page
+    ==========  ========================================
+
+-----------------------------------------------------
+**Curated.link_next**
+-----------------------------------------------------
+    Returns URL to next results page
+
+    ==========  ========================================
+    str         URL to next results page
+    ==========  ========================================
+
+-----------------------------------------------------
+**Curated.link_previous**
+-----------------------------------------------------
+    Returns URL to previous results page
+
+    ==========  ========================================
+    str         URL to previous results page
+    ==========  ========================================
+
+-----------------------------------------------------
+**Curated.link_first**
+-----------------------------------------------------
+    Returns URL to first results page
+
+    ==========  ========================================
+    str         URL to first results page
+    ==========  ========================================
+
+
+.. note::  ``curated.total_results`` always returns 0 (zero).
+           ``curated.link_last`` always points to the first page.
+
+
+=======
+Methods
+=======
+Methods exposed by the ``Curated`` class.
+
+-----------------------------------------------------
+**Curated.get_page()**
+-----------------------------------------------------
+    Returns the requested curated photos page with the current `query` and `per_page` parameters.
+    The returned page may not contain `entries` if the page is out of boundaries.
+
+    **Parameters**
+
+    ============  ======  ===========================  ====================================
+    Argument      Type    Optional/Required            Notes
+    ============  ======  ===========================  ====================================
+    **page**      number  required                     Page number to retrieve.
+    ============  ======  ===========================  ====================================
+
+    **Returns**
+
+    ==========  ========================================================================
+    **Object**  Instance of class ``Curated``
+    ==========  ========================================================================
+
+--------
+
+
+-----------------------------------------------------
+**Curated.get_next_page()**
+-----------------------------------------------------
+    Returns next available curated photos page with the current `query`, `page`, and `per_page` parameters.
+    Returns `None` if no page is available.
+
+    **Returns**
+
+    ==========  ========================================================================
+    **Object**  Instance of class ``Curated`` or `None`
+    ==========  ========================================================================
+
+    **Example**
+    ::
+
+        import pypexels
+        py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')
+
+        #
+        #
+        search_results = py_pexel.curated(query='red flowers', per_page=40)
+        while search_results is not None:
+            print 'Current page number %s' % search_results.page
+            search_results = search_results.get_next_page()
+
+--------
+
+
+-----------------------------------------------------
+**Curated.get_previous_page()**
+-----------------------------------------------------
+    Returns previous available curated photos page with the current `query`, `page`, and `per_page` parameters.
+    Returns `None` if no page is available.
+
+    **Returns**
+
+    ==========  ========================================================================
+    **Object**  Instance of class ``Curated`` or `None`
+    ==========  ========================================================================
+
+    **Example**
+    ::
+
+        import pypexels
+        py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')
+
+        #
+        #
+        search_results = py_pexel.curated(query='red flowers', page=3, per_page=40)
+        while search_results is not None:
+            print 'Current page number %s' % search_results.page
+            search_results = search_results.get_previous_page()
+
+--------
+
+
+-----------------------------------------------------
+**Curated.get_first_page()**
+-----------------------------------------------------
+    Returns first curated photos page with the current `query`, `page`, and `per_page` parameters.
+    Returns `None` if no page is available.
+
+    **Returns**
+
+    ==========  ========================================================================
+    **Object**  Instance of class ``Curated`` or `None`
+    ==========  ========================================================================
+
+    **Example**
+    ::
+
+        import pypexels
+        py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')
+
+        #
+        #
+        search_results = py_pexel.curated(query='red flowers', page=3, per_page=40)
+        print 'Current page number %s' % search_results.page
+        # To something with search_results
+
+        # Go back to first page
+        search_results = search_results.get_first_page():
+        print 'Current page number %s' % search_results.page
+
+--------
+
+.. note::  ``curated.get_last_page()`` always returns the first page.

docs/source/classes/class_random_.rst

@@ -0,0 +1,74 @@
+#################
+API: Class Random
+#################
+This class is used to emulate a **random** API using the ``PyPexels`` ``/curated/`` REST API.
+
+It is returned as result from a call to ``PyPexels.random(per_page)``
+
+
+==========
+Properties
+==========
+Properties exposed by the ``Random`` class.
+
+-----------------------------------------------------
+**Random.entries**
+-----------------------------------------------------
+    Returns an iterator for the returned objects contained in this ``Random`` instance.
+    Each entry will be an instance of class ``Photo``.
+
+    ==========  ========================================
+    iterator    each time an instance of class ``Photo``
+    ==========  ========================================
+
+    **Example**
+    ::
+
+        import pypexels
+        py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')
+
+        #
+        #
+        random_results = py_pexel.random(per_page=10)
+        for photo in random_results.entries:
+            print(photo.id, photo.photographer, photo.url)
+
+
+-----------------------------------------------------
+**Random.per_page**
+-----------------------------------------------------
+    Current random results per_page value.
+
+    ==========  ========================================
+    int         current random results per_page value
+    ==========  ========================================
+
+-----------------------------------------------------
+**Random.has_previous**
+-----------------------------------------------------
+    Returns always boolean **False**
+
+    ==========  ========================================
+    boolean     presence of previous page results
+    ==========  ========================================
+
+-----------------------------------------------------
+**Random.has_next**
+-----------------------------------------------------
+    Returns always boolean **True**
+
+    ==========  ========================================
+    boolean     presence of next page results
+    ==========  ========================================
+
+
+
+------------------
+**IMPORTANT NOTE**
+------------------
+Although this class will expose additional methods and properties from the ``PyPexels.Curated`` class, you should only
+rely upon and make use of the methods and properties listed above. Remember, this is a `convenience` class that provides
+some uniformity in behavior while emulating a random image generator. If you need to fully control the content and
+behavior of the classes, then revert to use ``PyPexels.Curated`` class, with ``per_page=1`` and ``page=randint()`` value
+directly.
+

docs/source/conf.py

@@ -64,7 +64,7 @@
 
 # General information about the project.
 project = u'PyPexels'
-copyright = u'2017 Salvatore Ventura'
+copyright = u'2017,2018,2019 Salvatore Ventura'
 author = u'Salvatore Ventura'
 
 # The version info for the project you're documenting, acts as replacement for

docs/source/examples.rst

@@ -49,3 +49,23 @@ each, retrieve each photo in there, and print some of their attributes.
         if not search_results.has_next:
             break
         search_results = search_results.get_next_page()
+
+
+======
+Random
+======
+The code below will return random images. Use the parameter ``per_page`` to specify how many random images the iterator
+will allow.
+
+.. code-block:: python
+
+    from pypexels import PyPexels
+    api_key = 'YOUR_API_KEY'
+
+    # instantiate PyPexels object
+    py_pexel = PyPexels(api_key=api_key)
+
+    random_photos_page = py_pexel.random(per_page=3)
+    for photo in random_photos_page.entries:
+        print(photo.id, photo.photographer, photo.url)
+

docs/source/index.rst

@@ -15,6 +15,7 @@ The source code is available on GitHub at `https://github.com/salvoventura/pypex
     classes/class_pypexels
     classes/class_popular
     classes/class_search
+    classes/class_random
     classes/class_photo
     version
     license

docs/source/version.rst

@@ -1,8 +1,8 @@
 Version
 =======
-**PyPexels v1.0.0b2 (beta, v2)**
+**PyPexels v1.0.0b3 (beta, v3)**
 
-    Second beta release introduces Python3 support.
+    Third beta release introduces support for /curated API, and Random() class.
 
     Note that using this library you still need to abide to Pexels Guidelines, which
     are explained on `Pexels API page <https://www.pexels.com/api/>`_