Metadata-Version: 1.1
Name: decipher
Version: 25.90.2
Summary: Package for easier access to Decipher's Beacon REST API
Home-page: https://www.decipherinc.com/n/
Author: Erwin S. Andreasen
Author-email: beacon-api@decipherinc.com
License: BSD
Description: This packages permits easier access to Decipher's Beacon REST API. 
        
        If you are a Beacon user, you can use the API to read and write your survey data, provision users, create surveys
        and many other tasks.
        
        If you are not a Decipher client, visit https://www.decipherinc.com/n/ to learn more about our services.
        
        Documentation
        -------------
        
        For an introduction to using the API, see this Knowledge Base article: http://kb.decipherinc.com/index.php?View=entry&EntryID=5678
        
        For current API reference documentation, see https://v2.decipherinc.com/s/local/beacon.html.
        
        Quick Examples
        --------------
        
        Install the package::
        
          sudo pip install decipher
          
        You have three  options to authenticate against the API:
        
        Using an **API Key**:  visit the Research Hub, and from the User Links menu (click on your picture in the upper right
        corner), select API Keys. Here you can provision a new API key for yourself or another user created just for API usage.
        
        API keys last until revoked or rekeyed. This is the preferrable method if you are using the API for automation.
        
        If you only expect to use the API from the command line, you do not have to create an API key but can login to the
        system just as if you had logged into the user interface (thus it will expire after anywhere between 15 minutes to 24
        hours depending on your company's security settings). Here's an example session::
        
          $ beacon login
        
          If you are using the Beacon API for automation, you should generate and enter
          an API key. If you only need temporary access, to e.g. upload/download files
          you can enter your username/password below
        
          How do you want to authenticate?
          1. Enter the 64-character API key (valid until deactivated)
          2. Enter your username/password (temporary)
          3. Enter a long code (visible on the API key page)
          q. Quit
          Select 1, 2, 3 or q: x
        
        If you select option 1::
        
            Enter your API key
            See http://kb.decipherinc.com/index.php?View=entry&EntryID=5678
        
            API KEY: **p84443bmg06skt6ceawpq4xa9qxyx8jucuxk0fz5mxuwp1v4**
        
            Enter your host, or press Enter for the default v2.decipherinc.com
            Host:  **yourprivatehost.decipherinc.com**
        
            Testing your new settings...
            Looks good. Settings were saved to the file /home/youruser/.config/decipher
        
        If you select option 2::
        
            Enter your full username (email address)
            Username: ***you@company.com***
        
            Enter your password
            Password: **password, not shown**
        
            Enter your host, or press Enter for the default v2.decipherinc.com
            Host: **yourprivatehost.decipherinc.com**
        
            Testing your new settings...
            Acquired a temporary session key. It will be expire after 1439 minutes of idle time.
            Looks good. Settings were saved to the file /home/youruser/.config/decipher
        
        If you select option 3::
        
            Visit https://v2.decipherinc.com/apps/api/keys (or private server equivalent)
            Select 'generate temporary key' then paste it below
        
            Temporary Key: **NDJiZD.....**
        
            Testing your new settings...
            Looks good. Settings were saved to the file /home/youruser/.config/decipher
        
        
        The "login" action saves your API information in the file ~/.config/beacon.
        
        From the command line you can now run the "beacon" script which lets you quickly run an API call::
        
          beacon -t get users select=id,email,fullname,last_login_from sort=-last_login_when limit=10
        
        The above illustrates:
         * An API call with method GET
         * Targetting the "users" resource, which will be at /api/v1/users
         * Using the "projection" feature to select only 4 fields (id, email, full name and IP of last login)
         * Using the "sorting" feature to order the response by descending time of last login
         * Using the "pagination" feature to limit output to 10 first entries
         * Using the -t option to output the data as a formattet text table, rather than JSON.
        
        If you replace the -t option with -p you will see the Python code needed for that same call:
        
        .. code-block:: python
        
         from decipher.beacon import api
         users = api.get("users", select="id,email,fullname,last_login_from", 
          sort="-last_login_when", limit=10)
         for user in users:
            print "User #{id} <{email}> logged in last from {last_login_from}".format(user)
            
        
        Authentication
        --------------
        
        You need an API key to use the API if you are not using a temporary, time limited login. You can supply this key
        in 3 ways when connecting remotely:
        
        By specifying it in the ~/.config/decipherfile which has this format:
        
        .. code-block:: ini
        
         [main]
         apikey=p84443bmg06skt6ceawpq4xa9qxyx8jucuxk0fz5mxuwp1v4
         host=v2.decipherinc.com
         
        The "main" section is default, but you can select any other by using `beacon -sothersection` or
        setting `api.section = "section"` before calling any API functions.
        
        By setting an environment variable::
        
            export BEACON_API=1234567890abcdef1234567890abcdef
            export BEACON_HOST=v2.decipherinc.com
          
        Be aware that environment variables on most UNIX systems are visible to other programs running on the same machine.
        
        By explicitly initializing the API with login information:
        
        .. code-block:: python
        
            from decipher.beacon import api
            api.login("1234567890abcdef1234567890abcdef", "v2.decipherinc.com") 
          
        
        API Versioning
        --------------
        
        Current API uses version 1. This package will only ever do version 1 calls. To opt-in to a newer version of the API,
        run (prior to doing any calls):
        
        .. code-block:: python
        
         from decipher.beacon import api
         api.version = 2
        
        
        We do not expect to increase the API to version 2 any time soon unless new functionality cannot be added without using
        parameters with default values.
        
        Type hints
        ----------
        
        The data returned from the API is serialized as JSON. However the API also provides a "type hint" for the real object
        type. This is transmitted in the `x-typehint` header which is a JSON dictionary mapping field name to type.
        
        Unless you disable it by using `api.typehint = False`, the API will turn some of the returned objects into "enriched"
        objects, and convert some types. For example, the `rh/apikeys` API returns an object containing a field named created_on which
        is an ISO8601 / RFC3329 string. The typehint header tells the API client that "created_on" is a "datetime" and the API turns
        this serialized datetime into an actual datetime object.
        
        The enriched object contain methods that correspond to what you can do to this type of resource in the API as well
        as easier access to build another API call to the resource for methods not wrapped by this current library version.
        
        Command line options
        --------------------
        
        The command line script has the following options::
        
           beacon [options] <verb> <resource> [arg=value...]
            Verb is one of:
             get    -- list resources
             post   -- create new resource
             put    -- update existing resource
             delete -- delete or retire existing resource
        
             login  -- interactively define an API key and host
             rekey  -- rekey your current secret key and update the config file
        
            Extra arguments are decoded as JSON objects/arrays if they start with { or [ or are null
        
            Options:
             -v verbose (show headers sent & received))
             -t display output as an aligned text table
             -x display output as IBM JSON XML
             -p display Python code required to make the call
             -s <section> use a different section in the /home/youruser/.config/decipher file than 'main'
             -V <version> use a different API version
        
        For example, to create a new API key for user bob@company.com, restricted only to the 8.8.8.8 IP address run::
        
            beacon post rh/apikeys user=bob@company.com 'restrictions={"networks":["8.8.8.8"]}'
        
        NOTE: Because of the way the shell manages quoting, you should surround parameters which are to be sent as objects with
        single quotes.
        
        
Platform: UNKNOWN
Requires: requests
