[docs] changing examples to the trades dataset

README.rst

@@ -34,14 +34,15 @@ The most common way to insert data is from a Pandas dataframe.
     from questdb.ingress import Sender
 
     df = pd.DataFrame({
-        'id': pd.Categorical(['toronto1', 'paris3']),
-        'temperature': [20.0, 21.0],
-        'humidity': [0.5, 0.6],
+        'symbol': pd.Categorical(['ETH-USD', 'BTC-USD']),
+        'side': pd.Categorical(['sell', 'sell']),
+        'price': [2615.54, 39269.98],
+        'amount': [0.00044, 0.001],
         'timestamp': pd.to_datetime(['2021-01-01', '2021-01-02'])})
 
     conf = f'http::addr=localhost:9000;'
     with Sender.from_conf(conf) as sender:
-        sender.dataframe(df, table_name='sensors', at='timestamp')
+        sender.dataframe(df, table_name='trades', at='timestamp')
 
 You can also send individual rows. This only requires a more minimal installation::
 
@@ -54,9 +55,9 @@ You can also send individual rows. This only requires a more minimal installatio
     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},
+            'trades',
+            symbols={'symbol': 'ETH-USD', 'side': 'sell'},
+            columns={'price': 2615.54, 'amount': 0.00044},
             at=TimestampNanos.now())
         sender.flush()
 
@@ -103,4 +104,4 @@ License
 =======
 
 The code is released under the `Apache License 2.0
-<https://github.com/questdb/py-questdb-client/blob/main/LICENSE.txt>`_.
+<https://github.com/questdb/py-questdb-client/blob/main/LICENSE.txt>`_. 

ci/pip_install_deps.py

@@ -4,8 +4,6 @@
 import textwrap
 import platform
 import argparse
-import os
-
 
 arg_parser = argparse.ArgumentParser(
     prog='pip_install_deps.py',
@@ -14,6 +12,7 @@
 
 arg_parser.add_argument('--pandas-version')
 
+
 class UnsupportedDependency(Exception):
     pass
 
@@ -36,8 +35,8 @@ def pip_install(package, version=None):
         return
     output = res.stdout.decode('utf-8')
     is_unsupported = (
-        ('Could not find a version that satisfies the requirement' in output) or
-        ('The conflict is caused by' in output))
+            ('Could not find a version that satisfies the requirement' in output) or
+            ('The conflict is caused by' in output))
     if is_unsupported:
         raise UnsupportedDependency(output)
     else:
@@ -62,17 +61,25 @@ def ensure_timezone():
         pip_install('pytz')
 
 
+def install_old_pandas_and_numpy(args):
+    try_pip_install('pandas', args.pandas_version)
+    try_pip_install('numpy<2')
+
+def install_new_pandas_and_numpy():
+    try_pip_install('pandas')
+    try_pip_install('numpy')
+
 def main(args):
     ensure_timezone()
     pip_install('pip')
     pip_install('setuptools')
     try_pip_install('fastparquet>=2023.10.1')
 
     if args.pandas_version is not None and args.pandas_version != '':
-        try_pip_install('pandas', args.pandas_version)
+        install_old_pandas_and_numpy(args)
     else:
-        try_pip_install('pandas')
-    try_pip_install('numpy')
+        install_new_pandas_and_numpy()
+
     if (sys.platform == 'darwin') and (platform.processor() == 'i386'):
         # Workaround for https://github.com/apache/arrow/issues/41696
         # Remove if/once resolved.
@@ -82,14 +89,14 @@ def main(args):
         try_pip_install('pyarrow')
 
     on_linux_is_glibc = (
-        (not platform.system() == 'Linux') or
-        (platform.libc_ver()[0] == 'glibc'))
-    is_64bits = sys.maxsize > 2**32
+            (not platform.system() == 'Linux') or
+            (platform.libc_ver()[0] == 'glibc'))
+    is_64bits = sys.maxsize > 2 ** 32
     is_cpython = platform.python_implementation() == 'CPython'
     is_windows_py3_12 = (
         # https://github.com/dask/fastparquet/issues/892
-        platform.system() == 'Windows' and
-        sys.version_info >= (3, 12))
+            platform.system() == 'Windows' and
+            sys.version_info >= (3, 12))
     if on_linux_is_glibc and is_64bits and is_cpython:
         # Ensure that we've managed to install the expected dependencies.
         import pandas

docs/sender.rst

@@ -20,24 +20,25 @@ The sender also supports TLS and authentication.
 
     conf = 'http::addr=localhost:9000;'
     with Sender.from_conf(conf) as sender:
-        # One row at a time
+        # Adding by rows
         sender.row(
-            'weather_sensor',
-            symbols={'id': 'toronto1'},
-            columns={'temperature': 23.5, 'humidity': 0.49},
+            'trades',
+            symbols={'symbol': 'ETH-USD', 'side': 'sell'},
+            columns={'price': 2615.54, 'amount': 0.00044},
             at=TimestampNanos.now())
+        # It is highly recommended to auto-flush or to flush in batches,
+        # rather than for every row
+        sender.flush()
 
-        # Whole dataframes at once - MUCH FASTER
+        # Whole dataframes at once
         df = pd.DataFrame({
-            'id': ['dubai2', 'memphis7'],
-            'temperature': [41.2, 33.3],
-            'humidity': [0.34, 0.55],
-            'timestamp': [
-                pd.Timestamp('2021-01-01 12:00:00'),
-                pd.Timestamp('2021-01-01 12:00:01')
-            ]
-        })
-        sensor.dataframe('weather_sensor', df, at='timestamp')
+            'symbol': pd.Categorical(['ETH-USD', 'BTC-USD']),
+            'side': pd.Categorical(['sell', 'sell']),
+            'price': [2615.54, 39269.98],
+            'amount': [0.00044, 0.001],
+            'timestamp': pd.to_datetime(['2021-01-01', '2021-01-02'])})
+
+        sensor.dataframe('trades', df, at='timestamp')
 
 The ``Sender`` object holds an internal buffer which will be flushed and sent
 at when the ``with`` block ends.
@@ -138,13 +139,12 @@ Here is an example of sending a row with a symbol and a string:
     conf = 'http::addr=localhost:9000;'
     with Sender.from_conf(conf) as sender:
         sender.row(
-            'news',
+            'trades',
             symbols={
-                'category': 'sport'},
+                'symbol': 'ETH-USD', 'side': 'sell'},
             columns={
-                'headline': 'The big game',
-                'url': 'https://dailynews.com/sport/the-big-game',
-                'views': 1000},
+                'price': 2615.54,
+                'amount': 0.00044}
             at=datetime.datetime(2021, 1, 1, 12, 0, 0))
 
 Populating Timestamps
@@ -184,9 +184,9 @@ received by the server.
     conf = 'http::addr=localhost:9000;'
     with Sender.from_conf(conf) as sender:
         sender.row(
-            'weather_sensor',
-            symbols={'id': 'toronto1'},
-            columns={'temperature': 23.5, 'humidity': 0.49},
+            'trades',
+            symbols={'symbol': 'ETH-USD', 'side': 'sell'},
+            columns={'price': 2615.54, 'amount': 0.00044},
             at=ServerTimestamp)  # Legacy feature, not recommended.
 
 .. warning::
@@ -217,15 +217,15 @@ send any pending data immediately.
     conf = 'http::addr=localhost:9000;'
     with Sender.from_conf(conf) as sender:
         sender.row(
-            'weather_sensor',
-            symbols={'id': 'toronto1'},
-            columns={'temperature': 23.5, 'humidity': 0.49},
+            'trades',
+            symbols={'symbol': 'ETH-USD', 'side': 'sell'},
+            columns={'price': 2615.54, 'amount': 0.00044},
             at=TimestampNanos.now())
         sender.flush()
         sender.row(
-            'weather_sensor',
-            symbols={'id': 'dubai2'},
-            columns={'temperature': 41.2, 'humidity': 0.34},
+            'trades',
+            symbols={'symbol': 'BTC-USD', 'side': 'sell'},
+            columns={'price': 39269.98, 'amount': 0.001},
             at=TimestampNanos.now())
         sender.flush()
 
@@ -276,7 +276,7 @@ When using the HTTP protocol, the server will send back an error message if
 the data is invalid or if there is a problem with the server. This will be
 raised as an :class:`IngressError <questdb.ingress.IngressError>` exception.
 
-The HTTP layer will also attempt retries, configurable via the 
+The HTTP layer will also attempt retries, configurable via the
 :ref:`retry_timeout <sender_conf_request>` parameter.`
 
 When using the TCP protocol errors are *not* sent back from the server and
@@ -299,12 +299,14 @@ rows as a single transaction.
     with Sender.from_conf(conf) as sender:
         with sender.transaction('weather_sensor') as txn:
             txn.row(
-                symbols={'id': 'toronto1'},
-                columns={'temperature': 23.5, 'humidity': 0.49},
+                'trades',
+                symbols={'symbol': 'ETH-USD', 'side': 'sell'},
+                columns={'price': 2615.54, 'amount': 0.00044},
                 at=TimestampNanos.now())
             txn.row(
-                symbols={'id': 'dubai2'},
-                columns={'temperature': 41.2, 'humidity': 0.34},
+                'trades',
+                symbols={'symbol': 'BTC-USD', 'side': 'sell'},
+                columns={'price': 39269.98, 'amount': 0.001},
                 at=TimestampNanos.now())
 
 If auto-flushing is enabled, any pending data will be flushed before the
@@ -385,14 +387,14 @@ buffers.
 
     buf = Buffer()
     buf.row(
-        'weather_sensor',
-        symbols={'id': 'toronto1'},
-        columns={'temperature': 23.5, 'humidity': 0.49},
+        'trades',
+        symbols={'symbol': 'ETH-USD', 'side': 'sell'},
+        columns={'price': 2615.54, 'amount': 0.00044},
         at=TimestampNanos.now())
     buf.row(
-        'weather_sensor',
-        symbols={'id': 'dubai2'},
-        columns={'temperature': 41.2, 'humidity': 0.34},
+        'trades',
+        symbols={'symbol': 'BTC-USD', 'side': 'sell'},
+        columns={'price': 39269.98, 'amount': 0.001},
         at=TimestampNanos.now())
 
     conf = 'http::addr=localhost:9000;'
@@ -415,9 +417,9 @@ databases via the ``.flush(buf, clear=False)`` option.
 
     buf = Buffer()
     buf.row(
-        'weather_sensor',
-        symbols={'id': 'toronto1'},
-        columns={'temperature': 23.5, 'humidity': 0.49},
+        'trades',
+        symbols={'symbol': 'ETH-USD', 'side': 'sell'},
+        columns={'price': 2615.54, 'amount': 0.00044},
         at=TimestampNanos.now())
 
     conf1 = 'http::addr=db1.host.com:9000;'
@@ -480,27 +482,25 @@ sender objects in parallel.
         with Sender.from_conf(conf_string) as sender:
             sender.dataframe(
                 df,
-                table_name='weather_sensor',
-                symbols=['id'],
+                table_name='trades',
+                symbols=['symbol', 'side'],
                 at='timestamp')
 
     dfs = [
-        pd.DataFrame({
-            'id': ['sensor1', 'sensor2'],
-            'temperature': [22.5, 24.7],
-            'humidity': [0.45, 0.47],
-            'timestamp': [
-                pd.Timestamp('2017-01-01T12:00:00'),
-                pd.Timestamp('2017-01-01T12:00:01')
-            ]}),
-        pd.DataFrame({
-            'id': ['sensor3', 'sensor4'],
-            'temperature': [23.1, 25.3],
-            'humidity': [0.48, 0.50],
-            'timestamp': [
-                pd.Timestamp('2017-01-01T12:00:02'),
-                pd.Timestamp('2017-01-01T12:00:03')
-            ]})
+            pd.DataFrame({
+            'symbol': pd.Categorical(['ETH-USD', 'BTC-USD']),
+            'side': pd.Categorical(['sell', 'sell']),
+            'price': [2615.54, 39269.98],
+            'amount': [0.00044, 0.001],
+            'timestamp': pd.to_datetime(['2021-01-01', '2021-01-02'])}
+            ),
+            pd.DataFrame({
+            'symbol': pd.Categorical(['BTC-USD', 'BTC-USD']),
+            'side': pd.Categorical(['buy', 'sell']),
+            'price': [39268.76, 39270.02],
+            'amount': [0.003, 0.010],
+            'timestamp': pd.to_datetime(['2021-01-03', '2021-01-03'])}
+            ),
     ]
 
     with ThreadPoolExecutor() as executor:

examples/auth.py

@@ -14,20 +14,17 @@ def example(host: str = 'localhost', port: int = 9009):
         with Sender.from_conf(conf) as sender:
             # Record with provided designated timestamp (using the 'at' param)
             # Notice the designated timestamp is expected in Nanoseconds,
-            # but timestamps in other columns are expected in Microseconds. 
+            # but timestamps in other columns are expected in Microseconds.
             # The API provides convenient functions
             sender.row(
                 'trades',
                 symbols={
-                    'pair': 'USDGBP',
-                    'type': 'buy'},
+                    'symbol': 'ETH-USD',
+                    'side': 'sell'},
                 columns={
-                    'traded_price': 0.83,
-                    'limit_price': 0.84,
-                    'qty': 100,
-                    'traded_ts': datetime.datetime(
-                        2022, 8, 6, 7, 35, 23, 189062,
-                        tzinfo=datetime.timezone.utc)},
+                    'price': 2615.54,
+                    'amount': 0.00044,
+                   },
                 at=TimestampNanos.now())
 
             # You can call `sender.row` multiple times inside the same `with`

examples/auth_and_tls.py

@@ -14,20 +14,17 @@ def example(host: str = 'localhost', port: int = 9009):
         with Sender.from_conf(conf) as sender:
             # Record with provided designated timestamp (using the 'at' param)
             # Notice the designated timestamp is expected in Nanoseconds,
-            # but timestamps in other columns are expected in Microseconds. 
+            # but timestamps in other columns are expected in Microseconds.
             # The API provides convenient functions
             sender.row(
                 'trades',
                 symbols={
-                    'pair': 'USDGBP',
-                    'type': 'buy'},
+                    'symbol': 'ETH-USD',
+                    'side': 'sell'},
                 columns={
-                    'traded_price': 0.83,
-                    'limit_price': 0.84,
-                    'qty': 100,
-                    'traded_ts': datetime.datetime(
-                        2022, 8, 6, 7, 35, 23, 189062,
-                        tzinfo=datetime.timezone.utc)},
+                    'price': 2615.54,
+                    'amount': 0.00044,
+                   },
                 at=TimestampNanos.now())
 
             # You can call `sender.row` multiple times inside the same `with`

examples/basic.py

@@ -9,20 +9,17 @@ def example(host: str = 'localhost', port: int = 9009):
         with Sender.from_conf(conf) as sender:
             # Record with provided designated timestamp (using the 'at' param)
             # Notice the designated timestamp is expected in Nanoseconds,
-            # but timestamps in other columns are expected in Microseconds. 
+            # but timestamps in other columns are expected in Microseconds.
             # The API provides convenient functions
             sender.row(
                 'trades',
                 symbols={
-                    'pair': 'USDGBP',
-                    'type': 'buy'},
+                    'symbol': 'ETH-USD',
+                    'side': 'sell'},
                 columns={
-                    'traded_price': 0.83,
-                    'limit_price': 0.84,
-                    'qty': 100,
-                    'traded_ts': datetime.datetime(
-                        2022, 8, 6, 7, 35, 23, 189062,
-                        tzinfo=datetime.timezone.utc)},
+                    'price': 2615.54,
+                    'amount': 0.00044,
+                   },
                 at=TimestampNanos.now())
 
             # You can call `sender.row` multiple times inside the same `with`