domaintools-api 0.1.2

DomainTools' Official Python API

|domaintools|
=============

|PyPI version| |Build Status| |Coverage Status| |License| |Join the chat
at https://gitter.im/DomainTools/python\_api|

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
.. |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/
.. |Join the chat at https://gitter.im/DomainTools/python\_api| image:: https://badges.gitter.im/Join%20Chat.svg
:target: https://gitter.im/DomainTools/python_api?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge