Skip to content

Commit

Permalink
Prepared initial version Sphynx documentation, project cleanup (#18)
Browse files Browse the repository at this point in the history
* refactoring package name
* added initial documentation, examples
* temporary fix status issue influxdata/influxdb#15274
  • Loading branch information
rhajek authored Sep 26, 2019
1 parent ce81899 commit bac56bd
Show file tree
Hide file tree
Showing 23 changed files with 5,612 additions and 82 deletions.
7 changes: 7 additions & 0 deletions .readthedocs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
build:
image: latest
python:
version: 3.6
pip_install: true
extra_requirements:
- docs
117 changes: 81 additions & 36 deletions README.rst
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@

influxdb-client-python
======================

.. marker-index-start
.. image:: https://circleci.com/gh/influxdata/influxdb-client-python.svg?style=svg
:target: https://circleci.com/gh/influxdata/influxdb-client-python
Expand All @@ -12,48 +12,72 @@ influxdb-client-python
:target: https://codecov.io/gh/influxdata/influxdb-client-python
:alt: codecov

.. image:: https://img.shields.io/circleci/project/github/influxdata/influxdb-client-python/master.svg
:target: https://circleci.com/gh/influxdata/influxdb-client-python
:alt: CI status

InfluxDB 2.0 python client library.


* `Requirements <#requirements>`_
* `Getting Started <#getting-started>`_
* `Features <#how-to-use>`_

* `Writing data <#writes>`_
* `How to efficiently import large dataset <#how-to-efficiently-import-large-dataset>`_
* `Efficiency write data from IOT sensor <#efficiency-write-data-from-iot-sensor>`_

* `Advanced Usage <#advanced-usage>`_

* `Gzip support <#gzip-support>`_

* InfluxDB 2.0 API client (generated from swagger)

* Bucket
* Organizations
* Authorizations
* Labels
* Tasks

Requirements
.. image:: https://img.shields.io/codecov/c/github/influxdata/influxdb-client-python.svg
:target: https://codecov.io/gh/influxdata/influxdb-client-python
:alt: Coverage

.. image:: https://img.shields.io/pypi/v/influxdb-client-python.svg
:target: https://pypi.python.org/pypi/influxdb-client-python
:alt: PyPI package

.. image:: https://img.shields.io/pypi/pyversions/influxdb-client-python.svg
:target: https://pypi.python.org/pypi/influxdb-client-python
:alt: Supported Python versions

.. image:: https://readthedocs.org/projects/influxdb-client/badge/?version=latest
:target: https://influxdb-client.readthedocs.io/en/stable/?badge=latest
:alt: Documentation status

InfluxDB 2.0 python client library. The library covers InfluxDB 2.0

InfluxDB 2.0 client features
----------------------------

- Querying data
- using the Flux language
- into csv, raw data, `flux_table <https://github.com/influxdata/influxdb-client-python/blob/master/influxdb_client/client/flux_table.py#L5>`_ structure
- Writing data using
- `Line Protocol <https://docs.influxdata.com/influxdb/v1.6/write_protocols/line_protocol_tutorial>`_
- `Data Point <https://github.com/influxdata/influxdb-client-python/blob/master/influxdb_client/client/write/point.py#L16>`_
- `RxPY`_ Observable
- Not implemented yet
- write user types using decorator
- write Pandas DataFrame
- `InfluxDB 2.0 API <https://github.com/influxdata/influxdb/blob/master/http/swagger.yml>`_ client for management
- the client is generated from `swagger <https://github.com/influxdata/influxdb/blob/master/http/swagger.yml>`_ by using `openapi-generator <https://github.com/OpenAPITools/openapi-generator>`_
- organizations & users management
- buckets management
- tasks management
- authorizations
- health check

Installation
------------
.. marker-install-start
InfluxDB python library uses `RxPY <https://github.com/ReactiveX/RxPY>`_ - The Reactive Extensions for Python (RxPY).

Python 3.6+
**Python 3.6** or later is required.

Installation & Usage
--------------------

pip install
^^^^^^^^^^^

If the python package is hosted on Github, you can install directly from Github
If the python package is hosted on Github, you can install latest version directly from Github

.. code-block:: sh
pip install git+https://github.com/influxdata/influxdb-client-python.git
pip3 install git+https://github.com/influxdata/influxdb-client-python.git
(you may need to run ``pip`` with root permission:

(you may need to run ``pip`` with root permission: ``sudo pip install git+https://github.com/influxdata/influxdb-client-python.git``\ )
.. code-block:: sh
sudo pip3 install git+https://github.com/influxdata/influxdb-client-python.git
Then import the package:

Expand All @@ -78,10 +102,14 @@ Then import the package:
import influxdb_client
.. marker-install-end
Getting Started
---------------

Please follow the `installation procedure <#installation--usage>`_ and then run the following:
Please follow the `installation procedure <#installation>`_ and then run the following:

.. marker-query-start
.. code-block:: python
Expand Down Expand Up @@ -115,19 +143,26 @@ Please follow the `installation procedure <#installation--usage>`_ and then run
for cell in row:
val_count += 1
.. marker-query-end
.. marker-index-end
How to use
----------

Writes
^^^^^^
.. marker-writes-start
The `WriteApi <https://github.com/influxdata/influxdb-client-python/blob/master/influxdb_client/client/write_api.py>`_ supports synchronous, asynchronous and batching writes into InfluxDB 2.0.
The data should be passed as a `InfluxDB Line Protocol <https://docs.influxdata.com/influxdb/v1.6/write_protocols/line_protocol_tutorial/>`_\ , `Data Point <https://github.com/influxdata/influxdb-client-python/blob/master/influxdb_client/client/write/point.py>`_ or Observable stream.

*The default instance of ``WriteApi`` use batching.*

Batching
~~~~~~~~
""""""""

.. marker-batching-start
The batching is configurable by ``write_options``\ :

Expand Down Expand Up @@ -195,6 +230,8 @@ The batching is configurable by ``write_options``\ :
_write_client.__del__()
_client.__del__()
.. marker-batching-end
Asynchronous client
"""""""""""""""""""

Expand Down Expand Up @@ -230,7 +267,7 @@ Data are writes in a synchronous HTTP request.
client.__del__()
How to efficiently import large dataset
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
"""""""""""""""""""""""""""""""""""""""


* sources - `import_data_set.py <https://github.com/influxdata/influxdb-client-python/blob/master/tests/import_data_set.py>`_
Expand Down Expand Up @@ -323,9 +360,12 @@ How to efficiently import large dataset
"""
client.__del__()
Efficiency write data from IOT sensor
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. marker-writes-end
Efficiency write data from IOT sensor
"""""""""""""""""""""""""""""""""""""
.. marker-iot-start
* sources - `iot_sensor.py <https://github.com/influxdata/influxdb-client-python/blob/master/tests/iot_sensor.py>`_

Expand Down Expand Up @@ -408,11 +448,14 @@ Efficiency write data from IOT sensor
input()
.. marker-iot-end
Advanced Usage
--------------

Gzip support
^^^^^^^^^^^^
.. marker-gzip-start
``InfluxDBClient`` does not enable gzip compress for http request by default. If you want to enable gzip to reduce transfer data's size, you can call:

Expand All @@ -421,3 +464,5 @@ Gzip support
from influxdb_client import InfluxDBClient
_db_client = InfluxDBClient(url="http://localhost:9999", token="my-token", org="my-org", enable_gzip=True)
.. marker-gzip-end
20 changes: 20 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = influxdb_client
SOURCEDIR = .
BUILDDIR = _build

# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
3 changes: 3 additions & 0 deletions docs/_static/custom.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
.wy-table-responsive table td {
white-space: normal;
}
Loading

0 comments on commit bac56bd

Please sign in to comment.