open_fda_drug_label.api
=======================

.. py:module:: open_fda_drug_label.api


Classes
-------

.. autoapisummary::

   open_fda_drug_label.api.Drug_Label_Client


Module Contents
---------------

.. py:class:: Drug_Label_Client(api_key: str)

   OVERVIEW:
       The Label Client is an API client class that allows an individual to
       engage directly with the openFDA Drug/Label API after loading in
       their API key. Users can use generic_search and search_request in
       tandem to expedite search-term specific API calls, or use
       manual_request for non-Drug/label search-specific queries of the
       broader openFDA API environment.

   ATTRIBUTES
       api_key (str): OpenFDA API key loaded in by user
       base_url (str): Base URL for OpenFDA endpoint (shortcut functions)
       session (requests.Session()): Universal HTTP sesh for API requests

   USAGE EXAMPLE:
       >>> # User function loads in API key as api_key
       >>> client = Drug_Label_Client(api_key)
       >>> advil_items = generic_search("brand_name", "Advil")
       >>> advil_json = search_request(advil_items, limit=1)
       >>> print(advil_json) # prints raw complete json for shortcut query


   .. py:attribute:: api_key


   .. py:attribute:: base_url
      :value: 'https://api.fda.gov/drug/label.json'



   .. py:attribute:: session


   .. py:method:: search_request(search_items, limit: int = 1)

      OVERVIEW:
          Executes a search based on an inputted list of search_items
          which contains a list of searches built by generic_search.
          Returns a raw json with the number of searches equal to limit.

      :param search_items: list of fields generated by generic_search
      :type search_items: list
      :param limit: defines the number of total drugs contained in json
      :type limit: int

      RETURN VALUE:
          returns response.json(), raw json format of openFDA HTTPS request

      USAGE EXAMPLE:
          >>> client = Drug_Label_Client(api_key)
          >>> client.search_request([generic_search("brand_name","Advil")])
          >>> # above gives json format of first item search for "Advil"



   .. py:method:: generic_search(parameter, name, exact=False)

      OVERVIEW:
          Generates a generic_search string for input into the search_request
          function. Takes in a parameter (of any drug) and a particular name
          for the parameter to search for. For example, searching by parameter
          "brand_name" and name "Advil" yields all drugs with "Advil" in the
          "brand_name" field. Exact allows for exact string matching in the
          search field, and defaults to false.

          Multiple generic_search functions can be combined using +AND+ and
          this is the reason for including all generic_search items in a list
          when inputting into search_request.

      :param parameter: field search function is being performed on
      :type parameter: str
      :param name: string to match parameter search function to
      :type name: str
      :param exact: designates whether exact match is required
      :type exact: Bool

      RETURN VALUE:
          search_item (str): string formatted for link insertion

      USAGE EXAMPLE:
          >>> client = Drug_Label_Client(api_key)
          >>> client.generic_search("brand_name","Advil")
          >>> # above returns list of drugs w/ "brand_name" containing "Advil"



   .. py:method:: manual_request(url)

      OVERVIEW:
          Executes a manual data pull request using a user-provided url.

      :param url: string of user-inputted url.
      :type url: str

      RETURN VALUE:
          response.json() => json response if valid url is enterred.

      USAGE EXAMPLE:
          >>> client = Drug_Label_Client(api_key)
          >>> url = # [user inputted string]
          >>> client.manual_request(url)