chore: minor doc and installation tweaks

Author: amunra

CHANGELOG.rst

@@ -2,6 +2,23 @@
 Changelog
 =========
 
+2.0.1 (2024-03-22)
+------------------
+
+Patch release with minor bug fixes, no API changes and some documentation tweaks.
+
+Bug fixes
+~~~~~~~~~
+* Removed two unnecessary debugging ``print()`` statements that were
+  accidentally left in the code.
+
+Documentation
+~~~~~~~~~~~~~
+* Introduced the ability to optionally install ``pandas`` and ``pyarrow`` via
+  ``python3 -m pip install -U questdb[dataframe]`` and updated the documentation
+  to reflect this.
+
+
 2.0.0 (2024-03-19)
 ------------------
 

README.rst

@@ -22,24 +22,11 @@ The latest version of the library is 2.0.1.
 
 ::
 
-    python3 -m pip install -U questdb
+    python3 -m pip install -U questdb[dataframe]
 
 Please start by `setting up QuestDB <https://questdb.io/docs/quick-start/>`_ . Once set up, you can use this library to insert data.
 
-.. code-block:: python
-
-    from questdb.ingress import Sender, TimestampNanos
-
-    conf = f'http::addr=localhost:9000;'
-    with Sender.from_conf(conf) as sender:
-        sender.row(
-            'sensors',
-            symbols={'id': 'toronto1'},
-            columns={'temperature': 20.0, 'humidity': 0.5},
-            at=TimestampNanos.now())
-        sender.flush()
-
-You can also send Pandas dataframes:
+The most common way to insert data is from a Pandas dataframe.
 
 .. code-block:: python
 
@@ -56,8 +43,25 @@ You can also send Pandas dataframes:
     with Sender.from_conf(conf) as sender:
         sender.dataframe(df, table_name='sensors', at='timestamp')
 
+You can also send individual rows. This only requires a more minimal installation::
+
+    python3 -m pip install -U questdb
+
+.. code-block:: python
+
+    from questdb.ingress import Sender, TimestampNanos
+
+    conf = f'http::addr=localhost:9000;'
+    with Sender.from_conf(conf) as sender:
+        sender.row(
+            'sensors',
+            symbols={'id': 'toronto1'},
+            columns={'temperature': 20.0, 'humidity': 0.5},
+            at=TimestampNanos.now())
+        sender.flush()
+
 
-To connect via TCP, set the
+To connect via the `older TCP protocol <https://py-questdb-client.readthedocs.io/en/latest/sender.html#ilp-tcp-or-ilp-http>`_, set the
 `configuration string <https://py-questdb-client.readthedocs.io/en/latest/conf.html>`_ to:
 
 .. code-block:: python

docs/conf.rst

@@ -67,6 +67,7 @@ Connection
 
   The default is ``0.0.0.0``.
 
+.. _sender_conf_auth:
 
 Authentication
 ==============
@@ -128,7 +129,7 @@ still use TLS by setting up a proxy in front of QuestDB, such as
   * ``pem_file``: Path to a PEM-encoded certificate authority file.
     This is useful for testing with self-signed certificates.
 
-  The default is: ``'webpki_roots'``.
+  The default is: ``'webpki_and_os_roots'``.
 
 * ``tls_roots`` - ``str``: Path to a PEM-encoded certificate authority file.
   When used it defaults the ``tls_ca`` to ``'pem_file'``.
@@ -166,7 +167,7 @@ The following parameters control the :ref:`sender_auto_flush` behavior.
 * ``auto_flush`` - ``'on'`` | ``'off'``: Global switch for the auto-flushing
   behavior.
 
-  *Default: ``'on'``.*
+  Default: ``'on'``.
 
 * ``auto_flush_rows`` - ``int > 0`` | ``'off'``: The number of rows that will
   trigger a flush. Set to ``'off'`` to disable.
@@ -176,12 +177,12 @@ The following parameters control the :ref:`sender_auto_flush` behavior.
 * ``auto_flush_bytes`` - ``int > 0`` | ``'off'``: The number of bytes that will
   trigger a flush. Set to ``'off'`` to disable.
 
-  *Default: ``'off'``.*
+  Default: ``'off'``.
 
 * ``auto_flush_interval`` - ``int > 0`` | ``'off'``: The time in milliseconds
   that will trigger a flush. Set to ``'off'`` to disable.
 
-  *Default: 1000 (millis).*
+  Default: 1000 (millis).
 
 .. _sender_conf_auto_flush_interval:
 
@@ -229,15 +230,15 @@ Buffer
 
 * ``init_buf_size`` - ``int > 0``: Initial buffer capacity.
 
-  *Default: 65536 (64KiB).*
+  Default: 65536 (64KiB).
 
 * ``max_buf_size`` - ``int > 0``: Maximum flushable buffer capacity.
 
-  *Default: 104857600 (100MiB).*
+  Default: 104857600 (100MiB).
 
 * ``max_name_len`` - ``int > 0``: Maximum length of a table or column name.
 
-  *Default: 127.*
+  Default: 127.
 
 .. _sender_conf_request:
 
@@ -251,13 +252,13 @@ The following parameters control the HTTP request behavior.
   backoff starting at 10ms and doubling after each failed attempt up to a
   maximum of 1 second.
 
-  *Default: 10000 (10 seconds).*
+  Default: 10000 (10 seconds).
 
 * ``request_timeout`` - ``int > 0``: The time in milliseconds to wait for a
   response from the server. This is in addition to the calculation derived from
   the ``request_min_throughput`` parameter.
 
-  *Default: 10000 (10 seconds).*
+  Default: 10000 (10 seconds).
 
 * ``request_min_throughput`` - ``int > 0``: Minimum expected throughput in
   bytes per second for HTTP requests. If the throughput is lower than this
@@ -266,7 +267,7 @@ The following parameters control the HTTP request behavior.
   This is useful for large requests.
   You can set this value to ``0`` to disable this logic.
 
-  *Default: 102400 (100 KiB/s).*
+  Default: 102400 (100 KiB/s).
 
 
 The final request timeout calculation is::

docs/installation.rst

@@ -2,36 +2,60 @@
 Installation
 ============
 
+Dependency
+==========
+
 The Python QuestDB client does not have any additional run-time dependencies and
 will run on any version of Python >= 3.8 on most platforms and architectures.
 
+Optional Dependencies
+---------------------
+
+Ingesting dataframes also require the following
+dependencies to be installed:
+
+* ``pandas``
+* ``pyarrow``
+* ``numpy``
+
+These are bundled as the ``dataframe`` extra.
+
+Without this option, the ``questdb`` package has no dependencies other than
+to the Python standard library.
+
+PIP
+---
+
 You can install it (or update it) globally by running::
 
-    python3 -m pip install -U questdb
+    python3 -m pip install -U questdb[dataframe]
 
 
 Or, from within a virtual environment::
 
-    pip install -U questdb
+    pip install -U questdb[dataframe]
 
 
+If you don't need to work with dataframes::
+    
+    python3 -m pip install -U questdb
+
+Poetry
+------
+
 If you're using poetry, you can add ``questdb`` as a dependency::
 
+    poetry add questdb[dataframe]
+
+Similarly, if you don't need to work with dataframes::
+
     poetry add questdb
 
 or to update the dependency::
 
     poetry update questdb
 
 
-Note that ingesting dataframes also require the following
-dependencies to be installed:
-
-* ``pandas``
-* ``pyarrow``
-* ``numpy``
-
-
 Verifying the Installation
 ==========================
 

docs/sender.rst

@@ -642,13 +642,13 @@ Since TCP does not block for a response it is useful for high-throughput
 scenarios in higher latency networks or on older versions of QuestDB which do
 not support ILP/HTTP quite yet.
 
-It should be noted that HTTP performance equivalent to TCP can be achieved by
-:ref:`using multiple sender objects in parallel <sender_http_performance>`.
+It should be noted that you can achieve equivalent or better performance to TCP
+with HTTP by :ref:`using multiple sender objects in parallel <sender_http_performance>`.
 
 Either way, you can easily switch between the two protocols by changing:
 
 * The ``<protocol>`` part of the :ref:`configuration string <sender_conf>`.
 
 * The port number (ILP/TCP default is 9009, ILP/HTTP default is 9000).
 
-* Any authentication parameters such as ``username``, ``token``, et cetera.
+* Any :ref:`authentication parameters <sender_conf_auth>` such as ``username``, ``token``, et cetera.

pyproject.toml

@@ -29,6 +29,7 @@ email = "adam@questdb.io"
 [project.optional-dependencies]
 publish = ["twine", "wheel"]
 ci = ["cibuildwheel"]
+dataframe = ["pandas", "pyarrow", "numpy"]
 
 [project.urls]
 Homepage = "https://questdb.io/"