Documentation about CPython. Make example programs work out of the box. (#23)

* Examples: Make example programs work out of the box

By applying minor adjustments, the example programs are now in a form
that supports integration testing with CrateDB.

* Documentation: Add docs about running the examples on CPython

* Documentation: Update README

* Chore: Update .gitignore

Author: amotl

.gitignore

@@ -3,3 +3,5 @@
 *.swp
 *.bak
 .env
+.idea
+__pycache__

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
 

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/

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.

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.")

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)