Metadata-Version: 2.1
Name: ddpclient
Version: 2.0.3
Summary: A client library for DDP API
Home-page: https://github.com/insiight/ddpclient
Author: David Lin
Author-email: david.lin@effectivemeasure.com
License: MIT
Description: DDP API python client
        ---------------------
        
        This is a python client library for the OAuth2 DDP API. Currently the following services are supported:
        
        * UserListService
        * UserListClientService
        
        
        Installation
        ------------
        
        ::
        
            pip install ddpclient
        
        
        Test
        ----
        
        ::
        
            python setup.py test
        
        Deploy
        ----
        Update the version and dependencies in `setup.py` and then:
        
        ::
        
            python setup.py sdist upload
        
        
        Requirement
        -----------
        
        1. OAuth client ID and OAuth client secret
        
           DDP API uses OAuth 2.0 for authorization, to authorize the DDP API,
           you must first create a Client ID and a Client Secret. Visit the
           `Developer Console`_ to create a project and a OAuth client with
           credentials.
        
           You will use the client ID and secret to authorize DDP API.
        
        2. AdWards Client `Customer ID`_
        
           A unique three-part number that’s assigned to each AdWords account,
           listed at the top of every page in your account.
        
           You can set it as an environment variable `DDP_CLIENT_CUSTOMER_ID`. Or you can pass the ID into the `Client` class constructor (details below).
        
        Commands
        --------
        
        When installed, the DDP API client provide two command for authorizing
        your application access to a DDP account.
        
        These commands are provided to help quickly getting access to the DDP API to run the examples.
        It stores crendentials in a file named ``.ddp_credentials``.
        If you are using Flask or Django, consider using the ``oauth2client.contrib.flask_util`` and ``oauth2client.contrib.django_util``
        
        Generate Authorize URL
        ^^^^^^^^^^^^^^^^^^^^^^
        
        The ``ddp_authorize_url`` command expect the OAuth client id and client
        secret as parameter and generate a URL for getting a AuthCode
        
        ::
        
            $ ddp_authorize_url
            usage: ddp_authorize_url [client_id client_secret]
        
        Authorizing
        ^^^^^^^^^^^
        
        The ``ddp_authorize`` command expect the OAuth client id, secrete and
        the AuthCode obtained by using the ``ddp_authorize_url`` URL
        
        ::
        
            $ ddp_authorize
            usage: ddp_authorize [client_id client_secret auth_code]
        
        Once this is done, a file ``.ddp_credentials`` is created and store the
        resulting redentials. The credentials from this file will be used from
        then on.
        
        Usage
        -----
        
        Get UserList example:
        ^^^^^^^^^^^^^^^^^^^^^
        
        ::
        
            from ddpclient import UserListSelector, Client, Auth
        
            credentials = Auth().get_credentials()
            api_client = Client(credentials)
            selector = UserListSelector(). \
                select_fields('Id', 'Size'). \
                filter_by('Status', 'CLOSED'). \
                order_by('Id', True). \
                at_page(1, 3)
            response = api_client.get(selector)
        
            print response
        
            # (UserListPage){
            #    totalNumEntries = 108
            #    Page.Type = "UserListPage"
            #    entries[] =
            #       (BasicUserList){
            #          id = 978704062
            #          isReadOnly = False
            #          name = "Name one"
            #          size = 0
            #          sizeRange = "LESS_THAN_FIVE_HUNDRED"
            #          listType = "REMARKETING"
            #          UserList.Type = "BasicUserList"
            #       },
            #       (BasicUserList){
            #          id = 178703382
            #          isReadOnly = False
            #          name = "Name two"
            #          size = 0
            #          sizeRange = "LESS_THAN_FIVE_HUNDRED"
            #          listType = "REMARKETING"
            #          UserList.Type = "BasicUserList"
            #       },
            #       (BasicUserList){
            #          id = 138700763
            #          isReadOnly = False
            #          name = "Name three"
            #          size = 0
            #          sizeRange = "LESS_THAN_FIVE_HUNDRED"
            #          listType = "REMARKETING"
            #          UserList.Type = "BasicUserList"
            #       },
            #  }
        
        
        Add UserList example:
        ^^^^^^^^^^^^^^^^^^^^^
        
        ::
        
            from ddpclient import UserListSelector, Client, Auth
        
            credentials = Auth().get_credentials()
            api_client = Client(credentials)
        
            new_user_list = api_client.create_empty_user_list()
            new_user_list.name = 'TEST'
            new_user_list.description = 'TEST Description'
            new_user_list.status = 'CLOSED'
            new_user_list.integrationCode = '123'
            new_user_list.accountUserListStatus = 'INACTIVE'
        
            response = api_client.add(new_user_list)
        
            print response
        
        
            # (UserListReturnValue){
            #    ListReturnValue.Type = "UserListReturnValue"
            #    value[] =
            #       (BasicUserList){
            #          id = 12345678
            #          isReadOnly = False
            #          name = "TEST"
            #          description = "TEST Description"
            #          status = "CLOSED"
            #          integrationCode = "123"
            #          accessReason = "OWNED"
            #          accountUserListStatus = "INACTIVE"
            #          membershipLifeSpan = 30
            #          listType = "REMARKETING"
            #          isEligibleForSearch = True
            #          isEligibleForDisplay = True
            #          UserList.Type = "BasicUserList"
            #       },
            #  }
        
        
        Update UserList example:
        ^^^^^^^^^^^^^^^^^^^^^^^^
        
        ::
        
            from ddpclient import UserListSelector, Client, Auth
        
            credentials = Auth().get_credentials()
            api_client = Client(credentials)
        
            new_user_list = api_client.create_empty_user_list()
            new_user_list.id = 12345678
            new_user_list.description = 'TEST Description'
        
            response = api_client.set(new_user_list)
        
            print response
        
            # (UserListReturnValue){
            #    ListReturnValue.Type = "UserListReturnValue"
            #    value[] =
            #       (BasicUserList){
            #          id = 12345678
            #          isReadOnly = False
            #          name = "TEST Updated Name"
            #          description = "TEST Description"
            #          status = "CLOSED"
            #          integrationCode = "123"
            #          accessReason = "OWNED"
            #          accountUserListStatus = "INACTIVE"
            #          membershipLifeSpan = 30
            #          listType = "REMARKETING"
            #          isEligibleForSearch = True
            #          isEligibleForDisplay = True
            #          UserList.Type = "BasicUserList"
            #       },
            #  }
        
        
        Remove UserList example:
        ^^^^^^^^^^^^^^^^^^^^^^^^
        
        ::
        
            from ddpclient import UserListSelector, Client, Auth
        
            credentials = Auth().get_credentials()
            api_client = Client(credentials)
        
            new_user_list = api_client.create_empty_user_list()
            new_user_list.id = 395803975
        
            response = api_client.remove(new_user_list)
        
            print response
        
            # suds.WebFault: Server raised fault: '[OperatorError.OPERATOR_NOT_SUPPORTED @ operations[0]]'
            # Note: UserListService does not support deleting user list, this code servers as example of 'remove' operations
        
        
        
        Classes
        -------
        
        ``Auth``
        ^^^^^^^^
        
        ``Auth`` class can be used to generate URL (``authorize_url``) for user giving authorization:
        
        ::
        
            Auth().authorize_url(client_id, client_secret)
        
        
        
        ``Auth`` also accept a auth code and obtain credentials after user having visited the above URL and granted the authorization to you application.
        The credentials object returned will be saved into a ``storage`` object.
        
        ::
        
            Auth().authorize(client_id, client_secret, auth_code)
        
        
        When the ``authorize`` method is done, by default ``Auth`` save the credentials object ( ``oauth2client.client.OAuth2Credentials``)
        into a file (``.ddp_credentials``) using ``oauth2client.file.Storage``. Once saved, this credential can be retrieved by:
        
        ::
        
            credentials = Auth().get_credentials()
        
        
        Saving credentials into a file for later retrieval is very simple but does not work for environments like Heroku.
        You might want to save the credentials object into a database so that the credentials can survive between deployments.
        The ``Auth`` constructor can accept a custom storage object with ``put`` and ``get`` methods defined.
        Using custom storage object can save/retrieve credentials object into/from a database, for example.
        
        ::
        
            storage = MyDBStorage()
            auth = Auth(storage)
        
            auth.authorize(client_id, client_secret, auth_code)
            credentials = auth.get_credentials()
        
        
        ``Client``
        ^^^^^^^^^^
        
        ``Client`` manages SOAP services. It requires an ``oauth2client.client.OAuth2Credentials`` object ( most likely retrieved by ``Auth``)
        to its constructor. ``Client`` then use the crendentials details to make SOAP API calls to available services (``UserListService`` and ``UserListClientService``)
        
        A client customer id is also required to set the SOAP header in every request. You can provide it via an environment variable ``DDP_CLIENT_CUSTOMER_ID`` or pass it
        explicitly to the constructor.
        
        
        ::
        
            credentials = Auth().get_credentials()
            client_customer_id = '123-123-1234'
            api_service = Client(credentials, client_customer_id).user_list_service_soap_client
        
        
        ``UserListSelector`` and ``UserListClientSelector``
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        These two selector classes are provided to specified entities to retrieve. They share the same interface. Example
        
        
        ::
        
            from ddpclient import UserListClientSelector, Client, Auth
            import datetime
        
            selector = UserListClientSelector(). \
                select_fields('ClientCustomerName', 'UserListId'). \
                filter_by('Status', 'ACTIVE'). \
                order_by('UserListId'). \
                order_by('ClientCustomerName', desc=True). \
                from_date_range(datetime.date(2016, 1, 1), datetime.date(2016, 1, 7)). \
                at_page(1, 3)
        
        .. _Developer Console: http://
        .. _Customer ID: https://support.google.com/adwords/answer/29198?hl=en-AU
        
Keywords: DDP API client
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.6
Provides-Extra: test
Provides-Extra: dev
