From 46ea9db457a0579f93cce6ba6d4d898637086ed6 Mon Sep 17 00:00:00 2001
From: Adam Cimarosti <cimarosti@gmail.com>
Date: Fri, 22 Mar 2024 10:44:33 +0000
Subject: [PATCH 1/4] chore: minor doc and installation tweaks
---
CHANGELOG.rst | 17 +++++++++++++++++
README.rst | 36 +++++++++++++++++++----------------
docs/conf.rst | 21 +++++++++++----------
docs/installation.rst | 44 +++++++++++++++++++++++++++++++++----------
docs/sender.rst | 6 +++---
pyproject.toml | 1 +
6 files changed, 86 insertions(+), 39 deletions(-)
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index fa660888..e5fca2f6 100644
--- a/CHANGELOG.rst
+++ b/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)
------------------
diff --git a/README.rst b/README.rst
index 6be717f4..4b40ca06 100644
--- a/README.rst
+++ b/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
diff --git a/docs/conf.rst b/docs/conf.rst
index 15ff6ff9..f4e802d7 100644
--- a/docs/conf.rst
+++ b/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::
diff --git a/docs/installation.rst b/docs/installation.rst
index f9c3c9e0..a0ef6376 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -2,21 +2,53 @@
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::
@@ -24,14 +56,6 @@ 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
==========================
diff --git a/docs/sender.rst b/docs/sender.rst
index 1a39beab..48b9b59f 100644
--- a/docs/sender.rst
+++ b/docs/sender.rst
@@ -642,8 +642,8 @@ 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:
@@ -651,4 +651,4 @@ Either way, you can easily switch between the two protocols by changing:
* 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.
diff --git a/pyproject.toml b/pyproject.toml
index 96d5a367..7201f189 100644
--- a/pyproject.toml
+++ b/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/"
From f0b56b7ff21204f6889ece861181c06715de53d5 Mon Sep 17 00:00:00 2001
From: Adam Cimarosti <cimarosti@gmail.com>
Date: Fri, 22 Mar 2024 12:56:06 +0000
Subject: [PATCH 2/4] minor doc tweaks
---
README.rst | 2 +-
docs/sender.rst | 8 ++++++++
2 files changed, 9 insertions(+), 1 deletion(-)
diff --git a/README.rst b/README.rst
index 4b40ca06..b2ed8bfd 100644
--- a/README.rst
+++ b/README.rst
@@ -18,7 +18,7 @@ and full-connection encryption with
Quickstart
==========
-The latest version of the library is 2.0.1.
+The latest version of the library is 2.0.1 (`changelog <https://py-questdb-client.readthedocs.io/en/latest/changelog.html>`_).
::
diff --git a/docs/sender.rst b/docs/sender.rst
index 48b9b59f..7231232c 100644
--- a/docs/sender.rst
+++ b/docs/sender.rst
@@ -587,6 +587,9 @@ You can also specify the configuration parameters programmatically:
...
+See the :ref:`sender_conf` section for a full list of configuration parameters:
+each configuration parameter can be passed as named arguments to the constructor.
+
Python type mappings:
* Parameters that require strings take a ``str``.
@@ -600,6 +603,11 @@ Python type mappings:
* Paths can also be specified as a ``pathlib.Path``.
+.. note::
+
+ The constructor arguments have changed between 1.x and 2.x.
+ If you are upgrading, take a look at the :ref:`changelog <changelog>`.
+
Customising ``.from_conf()`` and ``.from_env()``
------------------------------------------------
From 06942f9e6bc3b1554c71a977026d9f74e87aa86a Mon Sep 17 00:00:00 2001
From: Adam Cimarosti <cimarosti@gmail.com>
Date: Fri, 22 Mar 2024 13:09:47 +0000
Subject: [PATCH 3/4] fixed a broken doc link ref
---
CHANGELOG.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index e5fca2f6..4d48e6b2 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -1,3 +1,4 @@
+.. _changelog:
Changelog
=========
From d048f7d7b5ad7384d30e866d3840b2b3510271b5 Mon Sep 17 00:00:00 2001
From: Adam Cimarosti <cimarosti@gmail.com>
Date: Fri, 22 Mar 2024 13:37:33 +0000
Subject: [PATCH 4/4] fixing theming
---
docs/conf.py | 16 ++++++++++++++--
1 file changed, 14 insertions(+), 2 deletions(-)
diff --git a/docs/conf.py b/docs/conf.py
index 90dca507..7a2c2ee7 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -36,14 +36,26 @@
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if not on_rtd: # only set the theme if we're building docs locally
- html_theme = 'sphinx_rtd_theme'
+ html_theme = 'alabaster'
html_use_smartypants = True
html_last_updated_fmt = '%b %d, %Y'
html_split_index = False
html_sidebars = {
- '**': ['searchbox.html', 'globaltoc.html', 'sourcelink.html'],
+ '**': [
+ 'about.html',
+ 'searchbox.html',
+ 'globaltoc.html',
+ 'sourcelink.html'
+ ],
}
+html_theme_options = {
+ 'description': 'Python client for QuestDB',
+ 'github_button': True,
+ 'github_user': 'questdb',
+ 'github_repo': 'py-questdb-client',
+}
+
html_short_title = '%s-%s' % (project, version)
napoleon_use_ivar = True