README.rst
1InfluxDB-Python
2===============
3
4.. image:: https://travis-ci.org/influxdata/influxdb-python.svg?branch=master
5 :target: https://travis-ci.org/influxdata/influxdb-python
6
7.. image:: https://readthedocs.org/projects/influxdb-python/badge/?version=latest&style
8 :target: http://influxdb-python.readthedocs.org/
9 :alt: Documentation Status
10
11.. image:: https://img.shields.io/coveralls/influxdata/influxdb-python.svg
12 :target: https://coveralls.io/r/influxdata/influxdb-python
13 :alt: Coverage
14
15
16
17InfluxDB-Python is a client for interacting with InfluxDB_. Development of this library is maintained by
18
19+-----------+-------------------------------+
20| Github ID | URL |
21+===========+===============================+
22| @aviau | (https://github.com/aviau) |
23+-----------+-------------------------------+
24| @xginn8 | (https://github.com/xginn8) |
25+-----------+-------------------------------+
26| @sebito91 | (https://github.com/sebito91) |
27+-----------+-------------------------------+
28
29.. _readme-about:
30
31InfluxDB is an open-source distributed time series database, find more about InfluxDB_ at https://docs.influxdata.com/influxdb/latest
32
33
34.. _installation:
35
36InfluxDB pre v1.1.0 users
37-------------------------
38
39This module is tested with InfluxDB v1.2.4, our recommended version. Though there have been v1.3 (initial TSI branch) and v1.4 releases these are not
40yet supported.
41
42Those users still on InfluxDB v0.8.x users may still use the legacy client by importing ``from influxdb.influxdb08 import InfluxDBClient``.
43
44Installation
45------------
46
47Install, upgrade and uninstall influxdb-python with these commands::
48
49 $ pip install influxdb
50 $ pip install --upgrade influxdb
51 $ pip uninstall influxdb
52
53On Debian/Ubuntu, you can install it with this command::
54
55 $ sudo apt-get install python-influxdb
56
57Dependencies
58------------
59
60The influxdb-python distribution is supported and tested on Python 2.7, 3.3, 3.4, 3.5, 3.6, PyPy and PyPy3.
61
62**Note:** Python 3.2 is currently untested. See ``.travis.yml``.
63
64Main dependency is:
65
66- Requests: HTTP library for human beings (http://docs.python-requests.org/)
67
68
69Additional dependencies are:
70
71- pandas: for writing from and reading to DataFrames (http://pandas.pydata.org/)
72- Sphinx: Tool to create and manage the documentation (http://sphinx-doc.org/)
73- Nose: to auto-discover tests (http://nose.readthedocs.org/en/latest/)
74- Mock: to mock tests (https://pypi.python.org/pypi/mock)
75
76
77Documentation
78-------------
79
80Documentation is available at https://influxdb-python.readthedocs.io/en/latest/.
81
82You will need Sphinx_ installed to generate the documentation.
83
84The documentation can be generated by running::
85
86 $ tox -e docs
87
88
89Generated documentation can be found in the *docs/build/html/* directory.
90
91
92Examples
93--------
94
95Here's a basic example (for more see the examples directory)::
96
97 $ python
98
99 >>> from influxdb import InfluxDBClient
100
101 >>> json_body = [
102 {
103 "measurement": "cpu_load_short",
104 "tags": {
105 "host": "server01",
106 "region": "us-west"
107 },
108 "time": "2009-11-10T23:00:00Z",
109 "fields": {
110 "value": 0.64
111 }
112 }
113 ]
114
115 >>> client = InfluxDBClient('localhost', 8086, 'root', 'root', 'example')
116
117 >>> client.create_database('example')
118
119 >>> client.write_points(json_body)
120
121 >>> result = client.query('select value from cpu_load_short;')
122
123 >>> print("Result: {0}".format(result))
124
125
126Testing
127-------
128
129Make sure you have tox by running the following::
130
131 $ pip install tox
132
133To test influxdb-python with multiple version of Python, you can use Tox_::
134
135 $ tox
136
137
138Support
139-------
140
141For issues with, questions about, or feedback for InfluxDB_, please look into
142our community page: http://influxdb.com/community/.
143
144We are also lurking on the following:
145
146- #influxdb on irc.freenode.net
147- #influxdb on gophers.slack.com
148
149
150Development
151-----------
152
153All development is done on Github_. Use Issues_ to report
154problems or submit contributions.
155
156.. _Github: https://github.com/influxdb/influxdb-python/
157.. _Issues: https://github.com/influxdb/influxdb-python/issues
158
159Please note that we WILL get to your questions/issues/concerns as quickly as possible. We maintain many
160software repositories and sometimes things may get pushed to the backburner. Please don't take offense,
161we will do our best to reply as soon as possible!
162
163
164Source code
165-----------
166
167The source code is currently available on Github: https://github.com/influxdata/influxdb-python
168
169
170TODO
171----
172
173The TODO/Roadmap can be found in Github bug tracker: https://github.com/influxdata/influxdb-python/issues
174
175
176.. _InfluxDB: https://influxdata.com/time-series-platform/influxdb/
177.. _Sphinx: http://sphinx.pocoo.org/
178.. _Tox: https://tox.readthedocs.org
179
