docs: Added examples to docs.

Author: amunra

README.rst

@@ -8,40 +8,63 @@ This client library implements QuestDB's variant of the
 `InfluxDB Line Protocol <https://questdb.io/docs/reference/api/ilp/overview/>`_
 (ILP) over TCP.
 
+ILP provides the fastest way to insert data into QuestDB.
 
-Status of the library
-=====================
+This implementation supports `authentication
+<https://questdb.io/docs/reference/api/ilp/authenticate/>`_ and full-connection
+encryption with TLS.
 
-Work in progress: do not use yet.
-
-There will be an announcement on our `slack <http://slack.questdb.io>`_ once
-it's ready for use.
-
-
-Installation
-=============
+Quickstart
+==========
 
 The latest version of the library is 0.0.3.
 
 ::
 
     python3 -m pip install questdb
 
+.. code-block:: python
+
+    from questdb.ingress import Sender
+
+    with qi.Sender('localhost', 9009) as sender:
+        sender.row(
+            'sensors',
+            symbols={'id': 'toronto1'},
+            columns={'temperature': 20.0, 'humidity': 0.5})
+        sender.flush()
+
 
 Docs
 ====
 
-    https://py-questdb-client.readthedocs.io/
+https://py-questdb-client.readthedocs.io/
 
 
 Code
 ====
 
-    https://github.com/questdb/py-questdb-client
+https://github.com/questdb/py-questdb-client
 
 
 Package on PyPI
 ===============
 
-    https://pypi.org/project/questdb/
+https://pypi.org/project/questdb/
+
+
+Community
+=========
+
+If you need help, have additional questions or want to provide feedback, you
+may find us on `Slack <https://slack.questdb.io>`_.
+
+You can also `sign up to our mailing list <https://questdb.io/community/>`_
+to get notified of new releases.
+
+
+License
+=======
 
+The code is released under the `Apache License 2.0
+<https://github.com/questdb/py-questdb-client/blob/main/LICENSE.txt>`_.

docs/conf.py

@@ -12,7 +12,7 @@
     'sphinx.ext.ifconfig',
     'sphinx.ext.napoleon',
     'sphinx.ext.todo',
-    'sphinx.ext.viewcode',
+    'sphinx.ext.viewcode'
 ]
 source_suffix = '.rst'
 master_doc = 'index'

docs/examples.rst

@@ -0,0 +1,48 @@
+========
+Examples
+========
+
+Basics
+======
+
+The following example connects to the database and sends two rows (lines).
+
+The connection is unauthenticated and the data is sent at the end of the
+``with`` block.
+
+Here the :class:`questdb.ingress.Sender` is constructed with just ``host`` and
+``port``.
+
+.. literalinclude:: ../examples/basic.py
+   :language: python
+
+
+Authentication and TLS
+======================
+
+Continuing from the previous example, the connection is authenticated
+and also uses TLS.
+
+Here the :class:`questdb.ingress.Sender` is also constructed with the ``auth``
+and ``tls`` arguments.
+
+.. literalinclude:: ../examples/auth_and_tls.py
+   :language: python
+
+
+Explicit Buffers
+================
+
+For more advanced use cases where the same messages need to be sent to multiple
+questdb instances or you want to decouple serialization and sending (as may be
+in a multi-threaded application) construct :class:``questdb.ingress.Buffer``
+objects explicitly, then pass them to the :func:``questdb.ingress.Sender.flush``
+method.
+
+Note that this bypasses ``auto-flush`` logic
+(see :class:`questdb.ingress.Sender`) and you are fully responsible for ensuring
+all data is sent.
+
+.. literalinclude:: ../examples/buffer.py
+   :language: python
+

docs/index.rst

@@ -12,8 +12,9 @@ Contents
    :maxdepth: 2
 
    installation
-   usage
+   examples
    api
+   troubleshooting
    contributing
    changelog
 

docs/troubleshooting.rst

@@ -0,0 +1,59 @@
+===============
+Troubleshooting
+===============
+
+Common issues
+=============
+
+You may be experiencing one of the issues below.
+
+Production-optimized QuestDB configuration
+------------------------------------------
+
+If you can't initially see your data through a ``select`` SQL query straight
+away, this is normal: by default the database will only commit data it receives
+though the line protocol periodically to maximize throughput.
+
+For dev/testing you may want to tune the following database configuration
+parameters as so::
+
+    # server.conf
+    cairo.max.uncommitted.rows=1
+    line.tcp.maintenance.job.interval=100
+
+
+The default QuestDB configuration is more applicable for a production
+environment.
+
+For these and more configuration parameters refer to `database configuration
+<https://questdb.io/docs/reference/configuration/>`_ documentation.
+
+
+Infrequent Flushing
+-------------------
+
+You may not see data appear in a timely manner because you're not calling
+:func:`questdb.ingress.Sender.flush` often enough.
+
+The :class:`questdb.ingress.Sender` class only  provides auto-flushing based on
+a buffer size and *not on a timer*.
+
+
+Inspecting and debugging errors
+===============================
+
+Both the :class:`questdb.ingress.Sender` and :class:`questdb.ingress.Buffer`
+types support ``__len__`` and ``__str__`` methods to inspect the buffer that is
+about to be flushed.
+
+Note that the ILP protocol does not send errors back to the client.
+
+On error, the QuestDB server will disconnect and any error messages will be
+present in the `server logs
+<https://questdb.io/docs/concept/root-directory-structure#log-directory>`_.
+
+
+Asking for help
+===============
+
+The best way to get help is through `Slack <https://slack.questdb.io>`_.

docs/usage.rst

@@ -0,0 +1,24 @@
+from questdb.ingress import Sender
+
+
+def example():
+    # See: https://questdb.io/docs/reference/api/ilp/authenticate
+    auth = (
+        "testUser1",                                    # kid
+        "5UjEMuA0Pj5pjK8a-fa24dyIf-Es5mYny3oE_Wmus48",  # d
+        "fLKYEaoEb9lrn3nkwLDA-M_xnuFOdSt9y0Z7_vWSHLU",  # x
+        "Dt5tbS1dEDMSYfym3fgMv0B99szno-dFc1rYF9t0aac")  # y
+    with Sender('localhost', 9009, auth=auth, tls=True) as sender:
+        sender.row(
+            'line_sender_example',
+            symbols={'id': 'OMEGA'},
+            columns={'price': 111222233333, 'qty': 3.5})
+        sender.row(
+            'line_sender_example',
+            symbols={'id': 'ZHETA'},
+            columns={'price': 111222233330, 'qty': 2.5})
+        sender.flush()
+
+
+if __name__ == '__main__':
+    example()

examples/auth_and_tls.py

@@ -0,0 +1,18 @@
+from questdb.ingress import Sender
+
+
+def example():
+    with Sender('localhost', 9009) as sender:
+        sender.row(
+            'line_sender_example',
+            symbols={'id': 'OMEGA'},
+            columns={'price': 111222233333, 'qty': 3.5})
+        sender.row(
+            'line_sender_example',
+            symbols={'id': 'ZHETA'},
+            columns={'price': 111222233330, 'qty': 2.5})
+        sender.flush()
+
+
+if __name__ == '__main__':
+    example()

examples/basic.py

@@ -1,19 +1,21 @@
-from questdb.ingress import Sender, Buffer, TimestampNanos
+from questdb.ingress import Sender, TimestampNanos
 
-if __name__ == '__main__':
+
+def example():
     with Sender('localhost', 9009) as sender:
         buffer = sender.new_buffer()
         buffer.row(
             'line_sender_buffer_example',
             symbols={'id': 'Hola'},
-            columns={'price': '111222233333i', 'qty': 3.5},
-            at=TimestampNanos(111222233333)
-        )
+            columns={'price': 111222233333, 'qty': 3.5},
+            at=TimestampNanos(111222233333))
         buffer.row(
             'line_sender_example',
             symbols={'id': 'Adios'},
-            columns={'price': '111222233343i', 'qty': 2.5},
-            at=TimestampNanos(111222233343)
-        )
-        # last line is not flushed
+            columns={'price': 111222233343, 'qty': 2.5},
+            at=TimestampNanos(111222233343))
         sender.flush(buffer)
+
+
+if __name__ == '__main__':
+    example()