README.rst
1==============
2NS1 Python SDK
3==============
4
5> This project is in [active development](https://github.com/ns1/community/blob/master/project_status/ACTIVE_DEVELOPMENT.md).
6
7:Info: A Python SDK for accessing NS1, the Data Driven DNS platform.
8
9.. image:: https://travis-ci.org/ns1/ns1-python.svg?branch=master
10 :target: https://travis-ci.org/ns1/ns1-python
11
12.. image:: https://readthedocs.org/projects/ns1-python/badge/?version=latest
13 :target: https://ns1-python.readthedocs.io/en/latest/
14
15About
16=====
17
18This package provides a python SDK for accessing the NS1 DNS platform
19and includes both a simple NS1 REST API wrapper as well as a higher level
20interface for managing zones, records, data feeds, and more.
21It supports synchronous and asynchronous transports.
22
23Both python 2.7 and 3.3+ are supported. Automated tests are currently run
24against 2.7 and 3.6.
25
26Installation
27============
28
29 $ pip install ns1-python
30
31Dependencies
32============
33
34None, but supports different transport backends. Currently supported:
35
36 * `requests <http://docs.python-requests.org/en/latest/>`_ (synchronous, the default if available)
37 * urllib (synchronous, the default if requests isn't available)
38 * `twisted <https://twistedmatrix.com/>`_ (asynchronous, requires 2.7 or 3.5+)
39
40Other transports are easy to add, see `transport <https://github.com/ns1/ns1-python/tree/master/ns1/rest/transport>`_
41
42Examples
43========
44
45See the `examples directory <https://github.com/ns1/ns1-python/tree/master/examples>`_
46
47Documentation
48=============
49
50If you don't yet have an NS1 account, `signup here (free) <https://ns1.com/signup/>`_
51
52You'll need an API Key. To create one, login to `the portal <https://my.nsone.net/>`_ and
53click on the Account button in the top right. Select Settings & Users, then add a new
54API Key at the bottom.
55
56* `Documentation at ReadTheDocs <https://ns1-python.readthedocs.org/en/latest/>`_
57* `NS1 REST API Documentation <https://ns1.com/api/>`_
58
59Tests
60=====
61
62Unit tests use `pytest` (`pip install pytest`). 2.7 also requires `mock` to be
63installed (`pip install mock`).
64
65Tests should, of course, run and pass under python 2 and 3. We use tox to
66automate test runs and virtualenv setup, see `tox.ini` for config.
67
68Contributions
69=============
70Pull Requests and issues are welcome. See the [NS1 Contribution Guidelines](https://github.com/ns1/community) for more information.
71
72Our CI process will lint and check for formatting issues with `flake8` and
73`black`.
74It is suggested to run these checks prior to submitting a pull request and fix
75any issues:
76```
77pip install flake8 black
78flake8 . --count --show-source --statistics --extend-ignore=E501
79black . --check -l 79 --diff
80```
81
