python client

Connecting to ATK server

The Python client must 'connect' to an ATK server before it can be used. Here is the 'connect' process described by the method's documentation:

>>> print ta.connect.__doc__

    Connect to the trustedanalytics ATK server.

    This method calls the server, downloads its API information and dynamically
    generates and adds the appropriate Python code to the Python package for
    this python session.  Calling this method is required before invoking any
    server activity.

    After the client has connected to the server, the server config cannot be
    changed.  The user must restart Python in order to change connection info.

    Subsequent calls to this method invoke no action.

    There is no "connection" object or notion of being continuously "connected".
    The call to connect is just a one-time process to download the API and
    prepare the client.  If the server goes down and comes back up, this client
    will not recognize any difference from a connection point of view, and will
    still be operating with the API information originally downloaded.

    Parameters
    ==========
    credentials_file: str (optional)
        file name of a credentials file.   If supplied, it will override the
        settings authentication settings in the client's server configuration.
        The credentials file is normally obtained through the env.

Basic connecting

To use the default settings provided by the env and/or conf:

import trustedanalytics as ta
ta.connect()

To connect to a specific server:

import trustedanalytics as ta
ta.server.uri = 'myhost-name:port'
ta.connect()

Connections requiring OAuth (i.e. ATK in DP2)

To connect to a DP2 instance of ATK, the python client must have an OAuth access token (see oauth tokens). The user must have a credentials file which holds an OAuth access token and a refresh token.

The user can create a credentials file using ATK client running in an interactive python REPL. Call create_credentials_file('filename_of_your_choice') and interactively provide answers to its prompt.

$ python2.7

>>> import trustedanalytics as ta
>>> ta.server.uri = 'my-atk-host-name'
>>> ta.create_credentials_file('~/.atk/demo.creds')
URI of ATK or OAuth server: my-atk-instance.my-dp2-apps-domain.com
user name: dscientist9
Password: **********

Credentials created at '/home/dscientist9/.atk/demo.creds'

The credentials file can be specified when calling connect or set as an env variable $ATK_CREDS.

>>> ta.connect('~/.atk/demo.creds')
Connected.  This client instance connected to server http://my-atk-instance.my-dp2-apps-domain.com/v1
as user dscientist9 at 2015-06-19 10:27:21.583704.

The credentials file path must be relative to how python was launched. Full paths are recommended. Multiple credentials files can be created. They should be protected with appropriate OS privileges.

Using ENV variables

The URI of the ATK server can be specified by the env variable $ATK_URI. The python client will initialize its config setting to this value. It may still be overridden as shown above in the session or script.

$ export ATK_URI=my-atk-instance.my-dp2-apps-domain.com

The credentials file can be specified by $ATK_CREDS.

$ export ATK_CREDS=~/.atk/demo.creds

With these two variables set, the simple connect sequence works.

import trustedanalytics as ta
ta.connect()

Troubleshooting

Client's Server Settings

To see the client's configuration to find the server, just repr the ta.server

>>> ta.server
{
  "headers": {
    "Accept": "application/json,text/plain", 
    "Authorization": "eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiIyOTllYmMxZC0zNDgyLTRhOWEtODM2ZC03ZDM1ZmIzZWZiNmYiLCJzdWIiOiJiZTYzMWQ1OS1iYWM4LTRiOWQtOTFhNy05NzMyMTBhMWRhMTkiLCJzY29wZSI6WyJjbG91ZF9jb250cm9sbGVyX3NlcnZpY2VfcGVybWlzc2lvbnMucmVhZCIsImNsb3VkX2NvbnRyb2xsZXIud3JpdGUiLCJvcGVuaWQiLCJjbG91ZF9jb250cm9sbGVyLnJlYWQiXSwiY2xpZW50X2lkIjoiYXRrLWNsaWVudCIsImNpZCI6ImF0ay1jbGllbnQiLCJhenAiOiJhdGstY2xpZW50IiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6ImJlNjMxZDU5LWJhYzgtNGI5ZC05MWE3LTk3MzIxMGExZGExOSIsInVzZXJfbmFtZSI6ImFuamFsaS5zb29kQGludGVsLmNvbSIsImVtYWlsIjoiYW5qYWxpLnNvb2RAaW50ZWwuY29tIiwiaWF0IjoxNDM0NzUyODU4LCJleHAiOjE0MzQ3OTYwNTgsImlzcyI6Imh0dHBzOi8vdWFhLmRlbW8tZ290YXBhYXMuY29tL29hdXRoL3Rva2VuIiwiYXVkIjpbImF0ay1jbGllbnQiLCJjbG91ZF9jb250cm9sbGVyX3NlcnZpY2VfcGVybWlzc2lvbnMiLCJjbG91ZF9jb250cm9sbGVyIiwib3BlbmlkIl19.PAwF2OtC0Wd97-gmZ4OXQ36xpyaeCCUC2ErGgCk619m7s6uCGcqydrWveTtgehEjIkZxZ5jfaFI53_bU0cHLseKlxMi1llggk6xC0rWnaUePF47pw-u6eGm2z-rPIqP9i4_2TdTxDKCe9_qziNTQzKOlrn2_yN6KSgtytGEKxkE", 
    "Content-type": "application/json"
  }, 
  "scheme": "http", 
  "oauth_uri": "uaa.my-dp2-domain.comdemo-gotapaas.com", 
  "user": "dscientist9"
}

The settings may be individually modified off the ta.server object, before calling connect.

HTTP Logging

To see http traffic, call ta.loggers.set_http(). It can be helpful to turn on the logging before calling connect or create_connect_file.

import trustedanalytics as ta
ta.loggers.set_http()
ta.create_connect_file('supercreds')