Metadata-Version: 1.1
Name: domaintools-api
Version: 0.3.1
Summary: DomainTools' Official Python API
Home-page: https://github.com/domaintools/python_api
Author: DomainTools
Author-email: timothy@domaintools.com
License: MIT
Description: |domaintools|
        =============
        
        |PyPI version| |Build Status| |Coverage Status| |License|
        
        DomainTools' Official Python API
        
        .. figure:: https://github.com/DomainTools/python_api/raw/master/artwork/example.gif
           :alt: domaintools Example
        
           domaintools Example
        
        Installing the DomainTools' API
        ===============================
        
        To install the API run
        
        .. code:: bash
        
            pip install domaintools_api --upgrade
        
        Ideally, within a virtual environment.
        
        Using the API
        =============
        
        To start out create an instance of the API - passing in your credentials
        
        .. code:: python
        
        
            from domaintools import API
        
        
            api = API(USER_NAME, KEY)
        
        Every API endpoint is then exposed as a method on the API object, with
        any parameters that should be passed into that endpoint being passed in
        as method arguments:
        
        .. code:: python
        
            api.domain_search('google', exclude='photos')
        
        You can get an overview of every endpoint that you can interact with
        using the builtin help function:
        
        .. code:: python
        
            help(api)
        
        If applicable, native Python looping can be used directly to loop
        through any results:
        
        .. code:: python
        
            for result in api.domain_search('google', exclude='photos'):
                print(result['sld'])
        
        You can also use a context manager to ensure processing on the results
        only occurs if the request is successfully made:
        
        .. code:: python
        
            with api.domain_search('google', exclude='photos') as results:
                print(results)
        
        For API calls where a single item is expected to be returned, you can
        directly interact with the result:
        
        .. code:: python
        
            profile = api.domain_profile('google.com')
            title = profile['website_data']['title']
        
        For any API call where a single type of data is expected you can
        directly cast to the desired type:
        
        .. code:: python
        
            float(api.reputation('google.com')) == 0.0
            int(api.reputation('google.com')) == 0
        
        The entire structure returned from DomainTools can be retrieved by doing
        ``.data()`` while just the actionable response information can be
        retrieved by doing ``.response()``:
        
        .. code:: python
        
            api.domain_search('google').data() == {'response': { ... }}
            api.domain_search('google').response() == { ... }
        
        You can directly get the html, xml, or json version of the response by
        calling ``.(html|xml|json)()``:
        
        .. code:: python
        
            html = str(api.domain_search('google').json())
            xml = str(api.domain_search('google').xml())
            html = str(api.domain_search('google').html())
        
        If any API call is unsuccesfull, one of the exceptions defined in
        ``domaintools.exceptions`` will be raised:
        
        .. code:: python
        
            api.domain_profile('notvalid').data()
        
        
            ---------------------------------------------------------------------------
            BadRequestException                       Traceback (most recent call last)
            <ipython-input-3-f9e22e2cf09d> in <module>()
            ----> 1 api.domain_profile('google').data()
        
            /home/tcrosley/projects/external/python_api/venv/lib/python3.5/site-packages/domaintools-0.0.1-py3.5.egg/domaintools/base_results.py in data(self)
                 25                 self.api._request_session = Session()
                 26             results = self.api._request_session.get(self.url, params=self.kwargs)
            ---> 27             self.status = results.status_code
                 28             if self.kwargs.get('format', 'json') == 'json':
                 29                 self._data = results.json()
        
            /home/tcrosley/projects/external/python_api/venv/lib/python3.5/site-packages/domaintools-0.0.1-py3.5.egg/domaintools/base_results.py in status(self, code)
                 44
                 45         elif code == 400:
            ---> 46             raise BadRequestException()
                 47         elif code == 403:
                 48             raise NotAuthorizedException()
        
            BadRequestException:
        
        the exception will contain the status code and the reason for the
        exception:
        
        .. code:: python
        
            try:
                api.domain_profile('notvalid').data()
            except Exception as e:
                assert e.code == 400
                assert 'We could not understand your request' in e.reason['error']['message']
        
        You can get the status code of a response outside of exception handling
        by doing ``.status``:
        
        .. code:: python
        
        
            api.domain_profile('google.com').status == 200
        
        Using the API Asynchronously
        ============================
        
        .. figure:: https://github.com/DomainTools/python_api/raw/master/artwork/example_async.gif
           :alt: domaintools Async Example
        
           domaintools Async Example
        
        If you are running on Python 3.5+ the DomainTools' API automatically
        supports async usage:
        
        .. code:: python
        
        
            search_results = await api.domain_search('google')
        
        There is built-in support for async context managers:
        
        .. code:: python
        
            async with api.domain_search('google') as search_results:
                # do things
        
        And direct async for loops:
        
        .. code:: python
        
            async for result in api.domain_search('google'):
                print(result)
        
        All async operations can safely be intermixed with non async ones - with
        optimal performance achieved if the async call is done first:
        
        .. code:: python
        
            profile = api.domain_profile('google.com')
            await profile
            title = profile['website_data']['title']
        
        Interacting with the API via the command line client
        ====================================================
        
        .. figure:: https://github.com/DomainTools/python_api/raw/master/artwork/example_cli.gif
           :alt: domaintools CLI Example
        
           domaintools CLI Example
        
        Immediately after installing ``domaintools_api`` with pip, a
        ``domaintools`` command line client will become available to you:
        
        .. code:: bash
        
            domaintools --help
        
        To use - simply pass in the api\_call you would like to make along with
        the parameters that it takes and your credentials:
        
        .. code:: bash
        
            domaintools domain_search google --max_length 10 -u $TEST_USER -k $TEST_KEY
        
        Optionally, you can specify the desired format (html, xml, json, or
        list) of the results:
        
        .. code:: bash
        
            domaintools domain_search google --max_length 10 -u $TEST_USER -k $TEST_KEY -f html
        
        To avoid having to type in your API key repeatedly, you can specify them
        in ``~/.dtapi`` separated by a new line:
        
        .. code:: bash
        
            API_USER
            API_KEY
        
        .. |domaintools| image:: https://github.com/DomainTools/python_api/raw/master/artwork/logo.png
        .. |PyPI version| image:: https://badge.fury.io/py/domaintools_api.svg
           :target: http://badge.fury.io/py/domaintools_api
        .. |Build Status| image:: https://travis-ci.org/DomainTools/python_api.svg?branch=master
           :target: https://travis-ci.org/DomainTools/python_api
        .. |Coverage Status| image:: https://coveralls.io/repos/github/DomainTools/python_api/badge.svg?branch=master
           :target: https://coveralls.io/github/DomainTools/python_api?branch=master
        .. |License| image:: https://img.shields.io/github/license/mashape/apistatus.svg
           :target: https://pypi.python.org/pypi/domaintools_api/
        
Keywords: Python,Python3
Platform: UNKNOWN
Classifier: Development Status :: 6 - Mature
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires: requests
Requires: aiohttp
