diff --git a/.gitignore b/.gitignore index ea6e784..5998a24 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,5 @@ *.swp *.bak .env +.idea +__pycache__ diff --git a/README.md b/README.md index 6ac9a2d..6ac776f 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ import cratedb ### Connecting to CrateDB -Connect to a CrateDB cluster in the cloud by providing hostname, user name and password: +Connect to a CrateDB Cloud cluster using SSL, by providing hostname, username, and password: ```python crate = cratedb.CrateDB( @@ -58,7 +58,9 @@ crate = cratedb.CrateDB( The driver uses SSL by default. -If you're running CrateDB locally (with Docker for example), connect like this: +If you're running CrateDB on your workstation (with Docker for example, +by using `docker run --rm -it --publish=4200:4200 crate`), connect like +this: ```python crate = cratedb.CrateDB( @@ -389,7 +391,7 @@ The driver can throw the following types of exception: Here's an example showing how to catch a network error: ```python -crate = cratedb.CrateDB("nonexist", use_ssl = False) +crate = cratedb.CrateDB("nonexist", use_ssl=False) try: response = crate.execute( @@ -440,6 +442,7 @@ Constants for each value of `code` are provided. For example `4043` is `CRATEDB ## Examples The [`examples`](examples/) folder contains example MicroPython scripts, some of which are for specific microcontroller boards, including the popular Raspberry Pi Pico W. +Hardware-independent example programs also work well on CPython, see [Running on CPython](./docs/cpython.md). ## Testing diff --git a/docs/cpython.md b/docs/cpython.md new file mode 100644 index 0000000..61ee8e6 --- /dev/null +++ b/docs/cpython.md @@ -0,0 +1,38 @@ +# Running on CPython + +The module is designed for [MicroPython], but also works on [CPython]. + +## Setup + +Install Python package and project manager [uv]. +```shell +{apt,brew,pip,zypper} install uv +``` + +Create virtualenv, and install requirements. +```shell +uv venv +uv pip install requests +``` + +## Usage + +Start CrateDB. +```shell +docker run --rm -it --name=cratedb \ + --publish=4200:4200 --publish=5432:5432 \ + --env=CRATE_HEAP_SIZE=2g crate:latest -Cdiscovery.type=single-node +``` + +Invoke example programs. +```shell +source .venv/bin/activate +export PYTHONPATH=$(pwd) +python examples/example_usage.py +python examples/object_examples.py +``` + + +[CPython]: https://en.wikipedia.org/wiki/Cpython +[MicroPython]: https://en.wikipedia.org/wiki/Micropython +[uv]: https://docs.astral.sh/uv/ diff --git a/examples/example_usage.py b/examples/example_usage.py index 834fe33..3d748ae 100644 --- a/examples/example_usage.py +++ b/examples/example_usage.py @@ -6,14 +6,16 @@ import cratedb # CrateDB Docker / local network, no SSL. -# crate = cratedb.CrateDB(host="hostname", use_ssl=False) +crate = cratedb.CrateDB(host="localhost", use_ssl=False) -# CrateDB Cloud. +# CrateDB Cloud, using SSL. +""" crate = cratedb.CrateDB( - host="host", - user="user", + host="testdrive.cratedb.net", + user="username", password="password" ) +""" try: # Create a table. diff --git a/examples/object_examples.py b/examples/object_examples.py index 0316a92..9b9b1ce 100644 --- a/examples/object_examples.py +++ b/examples/object_examples.py @@ -6,14 +6,16 @@ import cratedb # CrateDB Docker / local network, no SSL. -# crate = cratedb.CrateDB(host="hostname", use_ssl=False) +crate = cratedb.CrateDB(host="localhost", use_ssl=False) -# CrateDB Cloud. +# CrateDB Cloud, using SSL. +""" crate = cratedb.CrateDB( - host="host", - user="user", + host="testdrive.cratedb.net", + user="username", password="password" ) +""" try: print("Drop any previous table.") diff --git a/examples/picow_demo.py b/examples/picow_demo.py index fc5ef63..73302e6 100644 --- a/examples/picow_demo.py +++ b/examples/picow_demo.py @@ -9,12 +9,17 @@ import cratedb -# Configure CrateDB driver. +# CrateDB Docker / local network, no SSL. +crate = cratedb.CrateDB(host="localhost", use_ssl=False) + +# CrateDB Cloud, using SSL. +""" crate = cratedb.CrateDB( - host="hostname", - user="username", + host="testdrive.cratedb.net", + user="username", password="password" ) +""" # Set up the WiFi and connect. wlan = network.WLAN(network.STA_IF)