Chore: Satisfy linter, add inline comments, improve documentation

cratedb_toolkit/adapter/pymongo/cursor.py

@@ -385,6 +385,6 @@
             if isinstance(index, str):
                 self.__hint = index
             else:
-                self.__hint = helpers._index_document(index)
+                self.__hint = SON(helpers._index_document(index))
 
     return AmendedCursor

cratedb_toolkit/util/database.py

@@ -32,6 +32,7 @@ class DatabaseAdapter:
     def __init__(self, dburi: str, echo: bool = False):
         self.dburi = dburi
         self.engine = sa.create_engine(self.dburi, echo=echo)
+        # TODO: Make that go away.
         self.connection = self.engine.connect()
 
     def quote_relation_name(self, ident: str) -> str:

doc/io/influxdb/loader.md

@@ -39,7 +39,6 @@ Transfer data from InfluxDB bucket/measurement into CrateDB schema/table.
 ```shell
 export CRATEDB_SQLALCHEMY_URL=crate://crate@localhost:4200/testdrive/demo
 ctk load table influxdb2://example:token@localhost:8086/testdrive/demo
-crash --command "SELECT * FROM testdrive.demo;"
 ```
 
 Query data in CrateDB.

pyproject.toml

@@ -194,10 +194,11 @@ testing = [
   "testcontainers<5",
 ]
 [project.urls]
-changelog = "https://github.com/crate-workbench/cratedb-toolkit/blob/main/CHANGES.rst"
-documentation = "https://github.com/crate-workbench/cratedb-toolkit"
-homepage = "https://github.com/crate-workbench/cratedb-toolkit"
-repository = "https://github.com/crate-workbench/cratedb-toolkit"
+Changelog = "https://github.com/crate-workbench/cratedb-toolkit/blob/main/CHANGES.rst"
+Documentation = "https://github.com/crate-workbench/cratedb-toolkit"
+Homepage = "https://github.com/crate-workbench/cratedb-toolkit"
+Issues = "https://github.com/crate-workbench/cratedb-toolkit/issues"
+Repository = "https://github.com/crate-workbench/cratedb-toolkit"
 [project.scripts]
 cratedb-cfr = "cratedb_toolkit.cfr.cli:cli"
 cratedb-retention = "cratedb_toolkit.retention.cli:cli"
@@ -309,7 +310,7 @@ extend-exclude = [
 "tests/*" = ["S101"]  # Allow use of `assert`, and `print`.
 "tests/adapter/test_rockset.py" = ["E402"]
 "tests/wtf/test_http.py" = ["E402"]
-"examples/*" = ["T201"]  # Allow `print`
+"examples/*" = ["T201", "T203"]  # Allow `print` and `pprint`
 "cratedb_toolkit/retention/cli.py" = ["T201"]  # Allow `print`
 "cratedb_toolkit/sqlalchemy/__init__.py" = ["F401"]  # Allow `module´ imported but unused
 
@@ -339,17 +340,23 @@ docs-linkcheck = [
 ]
 
 format = [
-  { cmd = "black ." },
-  # Configure Ruff not to auto-fix (remove!):
-  # unused imports (F401), unused variables (F841), `print` statements (T201), and commented-out code (ERA001).
-  { cmd = "ruff format" },
-  { cmd = "ruff check --fix --ignore=ERA --ignore=F401 --ignore=F841 --ignore=T20 --ignore=ERA001 ." },
+  # Format project metadata.
   { cmd = "pyproject-fmt --keep-full-version pyproject.toml" },
+
+  # Format code.
+  # Configure Ruff not to auto-fix a few items that are useful in workbench mode.
+  # e.g.: unused imports (F401), unused variables (F841), `print` statements (T201), commented-out code (ERA001)
+  { cmd = "ruff format" },
+  { cmd = "ruff check --fix --ignore=ERA --ignore=F401 --ignore=F841 --ignore=T20 --ignore=ERA001" },
+
+  # Format examples.
+  # Use `black` for the files in `examples/*`, because it knows how to treat Jupyter files well.
+  { cmd = "black examples"},
 ]
 
 lint = [
-  { cmd = "ruff check ." },
-  { cmd = "black --check ." },
+  { cmd = "ruff format --check" },
+  { cmd = "ruff check" },
   { cmd = "validate-pyproject pyproject.toml" },
   { cmd = "mypy" },
 ]

tests/adapter/test_pymongo.py

@@ -302,24 +302,26 @@ def test_pymongo_tutorial(
 
     # Querying for More Than One Document.
     # https://pymongo.readthedocs.io/en/stable/tutorial.html#querying-for-more-than-one-document
-    assert list(posts.find({"author": "Mike"})) == [
-        {
-            "author": "Mike",
-            "text": "My first blog post!",
-            "tags": mock.ANY,
-            "date": mock.ANY,
-            "title": mock.ANY,
-            "_id": mock.ANY,
-        },
-        {
-            "author": "Mike",
-            "text": "Another post!",
-            "tags": mock.ANY,
-            "date": mock.ANY,
-            "title": mock.ANY,
-            "_id": mock.ANY,
-        },
-    ]
+    # TODO: Because the `ordered` option of `insert_many` is not being honored yet,
+    #       the result order of returned documents is indeterministic.
+    #       Using `.sort("_id", pymongo.ASCENDING)` does not improve the situation.
+    results = list(posts.find({"author": "Mike"}))
+    assert {
+        "author": "Mike",
+        "text": "My first blog post!",
+        "tags": mock.ANY,
+        "date": mock.ANY,
+        "title": mock.ANY,
+        "_id": mock.ANY,
+    } in results
+    assert {
+        "author": "Mike",
+        "text": "Another post!",
+        "tags": mock.ANY,
+        "date": mock.ANY,
+        "title": mock.ANY,
+        "_id": mock.ANY,
+    } in results
 
     # Counting.
     # https://pymongo.readthedocs.io/en/stable/tutorial.html#counting