Getting Started
===============

`TheNounProjectAPI <https://github.com/tomaarsen/TheNounProjectAPI>`_ is a Python wrapper allowing convenient access to the `Noun Project <https://thenounproject.com>`_ API.
It supports all endpoints and types of responses.

.. _api-keys-label:

API keys
^^^^^^^^

Before any requests can be made, the api key and secret need to be set.
These keys can be generated once you have made a Noun Project account. 
See `this topic <https://api.thenounproject.com/getting_started.html#creating-an-api-key>`_ on the official Noun Project documentation for more information.

Once you have generated these keys, they need to be set in the api wrapper. This can be done in a few ways. 
For each of these ways, assume that this section of code is present at the top:

.. code-block :: python
    :linenos:

    from TheNounProjectAPI import API
    key = "<sample api key>"
    secret = "<sample secret key>"

You can pass the keys to the constructor when creating the object:

.. code-block :: python
    :lineno-start: 4

    api = API(key=key, secret=secret)

You can also set the attributes directly:

.. code-block :: python
    :lineno-start: 4

    api = API()
    api.api_key = key
    api.secret_key = secret

Or call the api key and secret key setters:

.. code-block :: python
    :lineno-start: 4

    api = API()
    api.set_api_key(key)
    api.set_secret_key(secret)

Making requests
^^^^^^^^^^^^^^^

Once an API object has been set up, it can be used to make requests. Some of the most useful methods used for these requests are listed here.

========================================================== =======================
Methods                                                    Example output
========================================================== =======================
:py:meth:`~TheNounProjectAPI.api.API.get_collection`       :ref:`collection-label`
:py:meth:`~TheNounProjectAPI.api.API.get_collection_icons` :ref:`icons-label`
:py:meth:`~TheNounProjectAPI.api.API.get_collections`      :ref:`collections-label`
:py:meth:`~TheNounProjectAPI.api.API.get_icon`             :ref:`icon-label`
:py:meth:`~TheNounProjectAPI.api.API.get_icons_by_term`    :ref:`icons-label`
:py:meth:`~TheNounProjectAPI.api.API.get_recent_icons`     :ref:`icons-label`
:py:meth:`~TheNounProjectAPI.api.API.get_usage`            :ref:`usage-label`
:py:meth:`~TheNounProjectAPI.api.API.get_user_collection`  :ref:`collection-label`
:py:meth:`~TheNounProjectAPI.api.API.get_user_collections` :ref:`collections-label`
:py:meth:`~TheNounProjectAPI.api.API.get_user_uploads`     :ref:`icons-label`
:py:meth:`~TheNounProjectAPI.api.API.report_usage`         :ref:`enterprise-label`
========================================================== =======================

See :py:class:`~TheNounProjectAPI.api.API` for the other methods not listed here.

See `the official Noun Project documentation <https://api.thenounproject.com/documentation.html>`_ for more information regarding what information may be fetched.

Output handling
^^^^^^^^^^^^^^^

Let's take a look at some examples of how to parse the outputs from the aforementioned methods.

.. _icons-code-label:

:ref:`Icons<icons-label>`
""""""""""""""""""""""""""""""""""""""""""

.. code-block:: python
    :lineno-start: 7

    # See Sample outputs -> Icons for more information about this: 
    icons = api.get_icons_by_term("goat", public_domain_only=True, limit=2)
    
    # >>>icons
    # [<IconModel: Term: Goat Feeding, Slug: goat-feeding, Id: 24014>, 
    # <IconModel: Term: Herbivore teeth, Slug: herbivore-teeth, Id: 675870>]

    for icon in icons:
        print("Icon's term:", icon.term)
        print("This icon's tags:", ", ".join(tag.slug for tag in icon.tags))
        print("Uploader's username:", icon.uploader.username)

.. _icon-code-label:

:ref:`Icon<icon-label>`
"""""""""""""""""""""""

.. code-block:: python
    :lineno-start: 7

    # See Sample outputs -> Icon for more information about this: 
    icon = api.get_icon("goat")
    
    # >>>icon
    # <IconModel: Term: Goat, Slug: goat, Id: 8786>

    print("Icon's term:", icon.term)
    print("This icon's tags:", ", ".join(tag.slug for tag in icon.tags))
    print("Uploader's username:", icon.uploader.username)

.. _collections-code-label:

:ref:`Collections<collections-label>`
"""""""""""""""""""""""""""""""""""""

.. code-block:: python
    :lineno-start: 7

    # See Sample outputs -> Collections for more information about this: 
    collections = api.get_collections(limit=3)
    
    # >>>collections
    # [<CollectionModel: Name: Electric, Slug: electric, Id: 88081>, 
    #  <CollectionModel: Name: Banking, Slug: banking, Id: 88080>, 
    #  <CollectionModel: Name: Academy, Slug: academy, Id: 88079>]

    for collection in collections:
        print("Collection's name:", collection.name)
        print("Collection's tags:", ", ".join(tag for tag in collection.tags))
        print("Author's username:", collection.author.username)

.. _collection-code-label:

:ref:`Collection<collection-label>`
"""""""""""""""""""""""""""""""""""

.. code-block:: python
    :lineno-start: 7

    # See Sample outputs -> Collection for more information about this: 
    collection = api.get_collection("goat")
    
    # >>>collection
    # <CollectionModel: Name: Goat, Slug: goat, Id: 6861>

    print("Collection's name:", collection.name)
    print("Collection's tags:", ", ".join(tag for tag in collection.tags))
    print("Author's username:", collection.author.username)

.. _usage-code-label:

:ref:`Usage<usage-label>`
"""""""""""""""""""""""""

.. code-block:: python
    :lineno-start: 7

    # See Sample outputs -> Usage for more information about this: 
    usage = api.get_usage()

    # >>>usage
    # <UsageModel: Hourly: 12, Daily: 12, Monthly: 226>

    print("Monthly limit:", usage.limits.monthly)
    print("Today's usage:", usage.usage.daily)

Exception handling
^^^^^^^^^^^^^^^^^^

This wrapper may raise any exception listed in :py:mod:`~TheNounProjectAPI.exceptions`. 
Here's some clarification regarding some of these exceptions:

+--------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| Exception                                                          | How to handle                                                                                                                                        |
+--------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| :py:class:`~TheNounProjectAPI.exceptions.APIKeyNotSet`             | One or both of the keys have not been set correctly. See :ref:`api-keys-label` for how to resolve this exception.                                    |
+--------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | :py:class:`~TheNounProjectAPI.exceptions.IncorrectType`          | One or more of the parameters passed to the method is not correct.                                                                                   |
| | :py:class:`~TheNounProjectAPI.exceptions.NonPositive`            | See the exception class and program output for more information on how to resolve the exception.                                                     |
| | :py:class:`~TheNounProjectAPI.exceptions.IllegalSlug`            |                                                                                                                                                      |
| | :py:class:`~TheNounProjectAPI.exceptions.IllegalTerm`            |                                                                                                                                                      |
+--------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| :py:class:`~TheNounProjectAPI.exceptions.ServerException`          | The Noun Project API is likely experiencing issues. There is not much you can do about this, except for waiting.                                     |
+--------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | :py:class:`~TheNounProjectAPI.exceptions.BadRequest`             | A page that does not exist has been requested. This can happen for example when asking for an icon, collection or user that does not exist.          |
| | :py:class:`~TheNounProjectAPI.exceptions.NotFound`               |                                                                                                                                                      |
+--------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| :py:class:`~TheNounProjectAPI.exceptions.Unauthorized`             | The authentication is incorrect, most likely due to the api key and/or secret being incorrect.                                                       |
+--------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| :py:class:`~TheNounProjectAPI.exceptions.RateLimited`              | You may have been rate limited. You may have sent too many requests, or you've been timed out.                                                       |
+--------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| :py:class:`~TheNounProjectAPI.exceptions.UnknownStatusCode`        | Any status code without a custom exception has been returned from the API. Please look up the status code in the error message for more information. |
+--------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+