Skip to content

Commit d0bc7a3

Browse files
javierjavier
authored
[docs] changing examples to the trades dataset (#92)
* changing examples to the trades dataset * Whitespace to re-run tests * Fix tests by changing regex match * Update version and check if rebuild is inconsistent * Try to resolve failure in linux-old-pandas * Iterate * Fix just for old pandas
1 parent c3969d6 commit d0bc7a3

File tree

12 files changed

+134
-145
lines changed

12 files changed

+134
-145
lines changed

‎README.rst

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -34,14 +34,15 @@ The most common way to insert data is from a Pandas dataframe.
3434
from questdb.ingress import Sender
3535
3636
df = pd.DataFrame({
37-
'id': pd.Categorical(['toronto1', 'paris3']),
38-
'temperature': [20.0, 21.0],
39-
'humidity': [0.5, 0.6],
37+
'symbol': pd.Categorical(['ETH-USD', 'BTC-USD']),
38+
'side': pd.Categorical(['sell', 'sell']),
39+
'price': [2615.54, 39269.98],
40+
'amount': [0.00044, 0.001],
4041
'timestamp': pd.to_datetime(['2021-01-01', '2021-01-02'])})
4142
4243
conf = f'http::addr=localhost:9000;'
4344
with Sender.from_conf(conf) as sender:
44-
sender.dataframe(df, table_name='sensors', at='timestamp')
45+
sender.dataframe(df, table_name='trades', at='timestamp')
4546
4647
You can also send individual rows. This only requires a more minimal installation::
4748

@@ -54,9 +55,9 @@ You can also send individual rows. This only requires a more minimal installatio
5455
conf = f'http::addr=localhost:9000;'
5556
with Sender.from_conf(conf) as sender:
5657
sender.row(
57-
'sensors',
58-
symbols={'id': 'toronto1'},
59-
columns={'temperature': 20.0, 'humidity': 0.5},
58+
'trades',
59+
symbols={'symbol': 'ETH-USD', 'side': 'sell'},
60+
columns={'price': 2615.54, 'amount': 0.00044},
6061
at=TimestampNanos.now())
6162
sender.flush()
6263
@@ -103,4 +104,4 @@ License
103104
=======
104105

105106
The code is released under the `Apache License 2.0
106-
<https://github.com/questdb/py-questdb-client/blob/main/LICENSE.txt>`_.
107+
<https://github.com/questdb/py-questdb-client/blob/main/LICENSE.txt>`_.

‎ci/pip_install_deps.py

Lines changed: 19 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,6 @@
44
import textwrap
55
import platform
66
import argparse
7-
import os
8-
97

108
arg_parser = argparse.ArgumentParser(
119
prog='pip_install_deps.py',
@@ -14,6 +12,7 @@
1412

1513
arg_parser.add_argument('--pandas-version')
1614

15+
1716
class UnsupportedDependency(Exception):
1817
pass
1918

@@ -36,8 +35,8 @@ def pip_install(package, version=None):
3635
return
3736
output = res.stdout.decode('utf-8')
3837
is_unsupported = (
39-
('Could not find a version that satisfies the requirement' in output) or
40-
('The conflict is caused by' in output))
38+
('Could not find a version that satisfies the requirement' in output) or
39+
('The conflict is caused by' in output))
4140
if is_unsupported:
4241
raise UnsupportedDependency(output)
4342
else:
@@ -62,17 +61,25 @@ def ensure_timezone():
6261
pip_install('pytz')
6362

6463

64+
def install_old_pandas_and_numpy(args):
65+
try_pip_install('pandas', args.pandas_version)
66+
try_pip_install('numpy<2')
67+
68+
def install_new_pandas_and_numpy():
69+
try_pip_install('pandas')
70+
try_pip_install('numpy')
71+
6572
def main(args):
6673
ensure_timezone()
6774
pip_install('pip')
6875
pip_install('setuptools')
6976
try_pip_install('fastparquet>=2023.10.1')
7077

7178
if args.pandas_version is not None and args.pandas_version != '':
72-
try_pip_install('pandas', args.pandas_version)
79+
install_old_pandas_and_numpy(args)
7380
else:
74-
try_pip_install('pandas')
75-
try_pip_install('numpy')
81+
install_new_pandas_and_numpy()
82+
7683
if (sys.platform == 'darwin') and (platform.processor() == 'i386'):
7784
# Workaround for https://github.com/apache/arrow/issues/41696
7885
# Remove if/once resolved.
@@ -82,14 +89,14 @@ def main(args):
8289
try_pip_install('pyarrow')
8390

8491
on_linux_is_glibc = (
85-
(not platform.system() == 'Linux') or
86-
(platform.libc_ver()[0] == 'glibc'))
87-
is_64bits = sys.maxsize > 2**32
92+
(not platform.system() == 'Linux') or
93+
(platform.libc_ver()[0] == 'glibc'))
94+
is_64bits = sys.maxsize > 2 ** 32
8895
is_cpython = platform.python_implementation() == 'CPython'
8996
is_windows_py3_12 = (
9097
# https://github.com/dask/fastparquet/issues/892
91-
platform.system() == 'Windows' and
92-
sys.version_info >= (3, 12))
98+
platform.system() == 'Windows' and
99+
sys.version_info >= (3, 12))
93100
if on_linux_is_glibc and is_64bits and is_cpython:
94101
# Ensure that we've managed to install the expected dependencies.
95102
import pandas

‎docs/sender.rst

Lines changed: 60 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -20,24 +20,25 @@ The sender also supports TLS and authentication.
2020
2121
conf = 'http::addr=localhost:9000;'
2222
with Sender.from_conf(conf) as sender:
23-
# One row at a time
23+
# Adding by rows
2424
sender.row(
25-
'weather_sensor',
26-
symbols={'id': 'toronto1'},
27-
columns={'temperature': 23.5, 'humidity': 0.49},
25+
'trades',
26+
symbols={'symbol': 'ETH-USD', 'side': 'sell'},
27+
columns={'price': 2615.54, 'amount': 0.00044},
2828
at=TimestampNanos.now())
29+
# It is highly recommended to auto-flush or to flush in batches,
30+
# rather than for every row
31+
sender.flush()
2932
30-
# Whole dataframes at once - MUCH FASTER
33+
# Whole dataframes at once
3134
df = pd.DataFrame({
32-
'id': ['dubai2', 'memphis7'],
33-
'temperature': [41.2, 33.3],
34-
'humidity': [0.34, 0.55],
35-
'timestamp': [
36-
pd.Timestamp('2021-01-01 12:00:00'),
37-
pd.Timestamp('2021-01-01 12:00:01')
38-
]
39-
})
40-
sensor.dataframe('weather_sensor', df, at='timestamp')
35+
'symbol': pd.Categorical(['ETH-USD', 'BTC-USD']),
36+
'side': pd.Categorical(['sell', 'sell']),
37+
'price': [2615.54, 39269.98],
38+
'amount': [0.00044, 0.001],
39+
'timestamp': pd.to_datetime(['2021-01-01', '2021-01-02'])})
40+
41+
sensor.dataframe('trades', df, at='timestamp')
4142
4243
The ``Sender`` object holds an internal buffer which will be flushed and sent
4344
at when the ``with`` block ends.
@@ -138,13 +139,12 @@ Here is an example of sending a row with a symbol and a string:
138139
conf = 'http::addr=localhost:9000;'
139140
with Sender.from_conf(conf) as sender:
140141
sender.row(
141-
'news',
142+
'trades',
142143
symbols={
143-
'category': 'sport'},
144+
'symbol': 'ETH-USD', 'side': 'sell'},
144145
columns={
145-
'headline': 'The big game',
146-
'url': 'https://dailynews.com/sport/the-big-game',
147-
'views': 1000},
146+
'price': 2615.54,
147+
'amount': 0.00044}
148148
at=datetime.datetime(2021, 1, 1, 12, 0, 0))
149149
150150
Populating Timestamps
@@ -184,9 +184,9 @@ received by the server.
184184
conf = 'http::addr=localhost:9000;'
185185
with Sender.from_conf(conf) as sender:
186186
sender.row(
187-
'weather_sensor',
188-
symbols={'id': 'toronto1'},
189-
columns={'temperature': 23.5, 'humidity': 0.49},
187+
'trades',
188+
symbols={'symbol': 'ETH-USD', 'side': 'sell'},
189+
columns={'price': 2615.54, 'amount': 0.00044},
190190
at=ServerTimestamp) # Legacy feature, not recommended.
191191
192192
.. warning::
@@ -217,15 +217,15 @@ send any pending data immediately.
217217
conf = 'http::addr=localhost:9000;'
218218
with Sender.from_conf(conf) as sender:
219219
sender.row(
220-
'weather_sensor',
221-
symbols={'id': 'toronto1'},
222-
columns={'temperature': 23.5, 'humidity': 0.49},
220+
'trades',
221+
symbols={'symbol': 'ETH-USD', 'side': 'sell'},
222+
columns={'price': 2615.54, 'amount': 0.00044},
223223
at=TimestampNanos.now())
224224
sender.flush()
225225
sender.row(
226-
'weather_sensor',
227-
symbols={'id': 'dubai2'},
228-
columns={'temperature': 41.2, 'humidity': 0.34},
226+
'trades',
227+
symbols={'symbol': 'BTC-USD', 'side': 'sell'},
228+
columns={'price': 39269.98, 'amount': 0.001},
229229
at=TimestampNanos.now())
230230
sender.flush()
231231
@@ -276,7 +276,7 @@ When using the HTTP protocol, the server will send back an error message if
276276
the data is invalid or if there is a problem with the server. This will be
277277
raised as an :class:`IngressError <questdb.ingress.IngressError>` exception.
278278

279-
The HTTP layer will also attempt retries, configurable via the
279+
The HTTP layer will also attempt retries, configurable via the
280280
:ref:`retry_timeout <sender_conf_request>` parameter.`
281281

282282
When using the TCP protocol errors are *not* sent back from the server and
@@ -299,12 +299,14 @@ rows as a single transaction.
299299
with Sender.from_conf(conf) as sender:
300300
with sender.transaction('weather_sensor') as txn:
301301
txn.row(
302-
symbols={'id': 'toronto1'},
303-
columns={'temperature': 23.5, 'humidity': 0.49},
302+
'trades',
303+
symbols={'symbol': 'ETH-USD', 'side': 'sell'},
304+
columns={'price': 2615.54, 'amount': 0.00044},
304305
at=TimestampNanos.now())
305306
txn.row(
306-
symbols={'id': 'dubai2'},
307-
columns={'temperature': 41.2, 'humidity': 0.34},
307+
'trades',
308+
symbols={'symbol': 'BTC-USD', 'side': 'sell'},
309+
columns={'price': 39269.98, 'amount': 0.001},
308310
at=TimestampNanos.now())
309311
310312
If auto-flushing is enabled, any pending data will be flushed before the
@@ -385,14 +387,14 @@ buffers.
385387
386388
buf = Buffer()
387389
buf.row(
388-
'weather_sensor',
389-
symbols={'id': 'toronto1'},
390-
columns={'temperature': 23.5, 'humidity': 0.49},
390+
'trades',
391+
symbols={'symbol': 'ETH-USD', 'side': 'sell'},
392+
columns={'price': 2615.54, 'amount': 0.00044},
391393
at=TimestampNanos.now())
392394
buf.row(
393-
'weather_sensor',
394-
symbols={'id': 'dubai2'},
395-
columns={'temperature': 41.2, 'humidity': 0.34},
395+
'trades',
396+
symbols={'symbol': 'BTC-USD', 'side': 'sell'},
397+
columns={'price': 39269.98, 'amount': 0.001},
396398
at=TimestampNanos.now())
397399
398400
conf = 'http::addr=localhost:9000;'
@@ -415,9 +417,9 @@ databases via the ``.flush(buf, clear=False)`` option.
415417
416418
buf = Buffer()
417419
buf.row(
418-
'weather_sensor',
419-
symbols={'id': 'toronto1'},
420-
columns={'temperature': 23.5, 'humidity': 0.49},
420+
'trades',
421+
symbols={'symbol': 'ETH-USD', 'side': 'sell'},
422+
columns={'price': 2615.54, 'amount': 0.00044},
421423
at=TimestampNanos.now())
422424
423425
conf1 = 'http::addr=db1.host.com:9000;'
@@ -480,27 +482,25 @@ sender objects in parallel.
480482
with Sender.from_conf(conf_string) as sender:
481483
sender.dataframe(
482484
df,
483-
table_name='weather_sensor',
484-
symbols=['id'],
485+
table_name='trades',
486+
symbols=['symbol', 'side'],
485487
at='timestamp')
486488
487489
dfs = [
488-
pd.DataFrame({
489-
'id': ['sensor1', 'sensor2'],
490-
'temperature': [22.5, 24.7],
491-
'humidity': [0.45, 0.47],
492-
'timestamp': [
493-
pd.Timestamp('2017-01-01T12:00:00'),
494-
pd.Timestamp('2017-01-01T12:00:01')
495-
]}),
496-
pd.DataFrame({
497-
'id': ['sensor3', 'sensor4'],
498-
'temperature': [23.1, 25.3],
499-
'humidity': [0.48, 0.50],
500-
'timestamp': [
501-
pd.Timestamp('2017-01-01T12:00:02'),
502-
pd.Timestamp('2017-01-01T12:00:03')
503-
]})
490+
pd.DataFrame({
491+
'symbol': pd.Categorical(['ETH-USD', 'BTC-USD']),
492+
'side': pd.Categorical(['sell', 'sell']),
493+
'price': [2615.54, 39269.98],
494+
'amount': [0.00044, 0.001],
495+
'timestamp': pd.to_datetime(['2021-01-01', '2021-01-02'])}
496+
),
497+
pd.DataFrame({
498+
'symbol': pd.Categorical(['BTC-USD', 'BTC-USD']),
499+
'side': pd.Categorical(['buy', 'sell']),
500+
'price': [39268.76, 39270.02],
501+
'amount': [0.003, 0.010],
502+
'timestamp': pd.to_datetime(['2021-01-03', '2021-01-03'])}
503+
),
504504
]
505505
506506
with ThreadPoolExecutor() as executor:

‎examples/auth.py

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -14,20 +14,17 @@ def example(host: str = 'localhost', port: int = 9009):
1414
with Sender.from_conf(conf) as sender:
1515
# Record with provided designated timestamp (using the 'at' param)
1616
# Notice the designated timestamp is expected in Nanoseconds,
17-
# but timestamps in other columns are expected in Microseconds.
17+
# but timestamps in other columns are expected in Microseconds.
1818
# The API provides convenient functions
1919
sender.row(
2020
'trades',
2121
symbols={
22-
'pair': 'USDGBP',
23-
'type': 'buy'},
22+
'symbol': 'ETH-USD',
23+
'side': 'sell'},
2424
columns={
25-
'traded_price': 0.83,
26-
'limit_price': 0.84,
27-
'qty': 100,
28-
'traded_ts': datetime.datetime(
29-
2022, 8, 6, 7, 35, 23, 189062,
30-
tzinfo=datetime.timezone.utc)},
25+
'price': 2615.54,
26+
'amount': 0.00044,
27+
},
3128
at=TimestampNanos.now())
3229

3330
# You can call `sender.row` multiple times inside the same `with`

‎examples/auth_and_tls.py

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -14,20 +14,17 @@ def example(host: str = 'localhost', port: int = 9009):
1414
with Sender.from_conf(conf) as sender:
1515
# Record with provided designated timestamp (using the 'at' param)
1616
# Notice the designated timestamp is expected in Nanoseconds,
17-
# but timestamps in other columns are expected in Microseconds.
17+
# but timestamps in other columns are expected in Microseconds.
1818
# The API provides convenient functions
1919
sender.row(
2020
'trades',
2121
symbols={
22-
'pair': 'USDGBP',
23-
'type': 'buy'},
22+
'symbol': 'ETH-USD',
23+
'side': 'sell'},
2424
columns={
25-
'traded_price': 0.83,
26-
'limit_price': 0.84,
27-
'qty': 100,
28-
'traded_ts': datetime.datetime(
29-
2022, 8, 6, 7, 35, 23, 189062,
30-
tzinfo=datetime.timezone.utc)},
25+
'price': 2615.54,
26+
'amount': 0.00044,
27+
},
3128
at=TimestampNanos.now())
3229

3330
# You can call `sender.row` multiple times inside the same `with`

‎examples/basic.py

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -9,20 +9,17 @@ def example(host: str = 'localhost', port: int = 9009):
99
with Sender.from_conf(conf) as sender:
1010
# Record with provided designated timestamp (using the 'at' param)
1111
# Notice the designated timestamp is expected in Nanoseconds,
12-
# but timestamps in other columns are expected in Microseconds.
12+
# but timestamps in other columns are expected in Microseconds.
1313
# The API provides convenient functions
1414
sender.row(
1515
'trades',
1616
symbols={
17-
'pair': 'USDGBP',
18-
'type': 'buy'},
17+
'symbol': 'ETH-USD',
18+
'side': 'sell'},
1919
columns={
20-
'traded_price': 0.83,
21-
'limit_price': 0.84,
22-
'qty': 100,
23-
'traded_ts': datetime.datetime(
24-
2022, 8, 6, 7, 35, 23, 189062,
25-
tzinfo=datetime.timezone.utc)},
20+
'price': 2615.54,
21+
'amount': 0.00044,
22+
},
2623
at=TimestampNanos.now())
2724

2825
# You can call `sender.row` multiple times inside the same `with`

0 commit comments

Comments
 (0)