Notebook/Jupyter: Add example using JupySQL

Author: amotl

.github/workflows/notebook-jupyter.yml

@@ -0,0 +1,94 @@
+name: pandas
+
+on:
+  pull_request:
+    branches: ~
+    paths:
+    - '.github/workflows/notebook-jupyter.yml'
+    - 'notebook/jupyter/**'
+    - '/requirements.txt'
+  push:
+    branches: [ main ]
+    paths:
+    - '.github/workflows/notebook-jupyter.yml'
+    - 'notebook/jupyter/**'
+    - '/requirements.txt'
+
+  # Allow job to be triggered manually.
+  workflow_dispatch:
+
+  # Run job each night after CrateDB nightly has been published.
+  schedule:
+    - cron: '0 3 * * *'
+
+# Cancel in-progress jobs when pushing to the same branch.
+concurrency:
+  cancel-in-progress: true
+  group: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  test:
+    name: "
+     Python: ${{ matrix.python-version }}
+     CrateDB: ${{ matrix.cratedb-version }}
+     on ${{ matrix.os }}"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ 'ubuntu-latest' ]
+        python-version: [ '3.8', '3.13' ]
+        cratedb-version: [ 'nightly' ]
+
+    env:
+      OS_TYPE: ${{ matrix.os }}
+      PYTHON_VERSION: ${{ matrix.python-version }}
+      UV_SYSTEM_PYTHON: true
+
+    services:
+      cratedb:
+        image: crate/crate:${{ matrix.cratedb-version }}
+        ports:
+          - 4200:4200
+          - 5432:5432
+        env:
+          CRATE_HEAP_SIZE: 4g
+
+    steps:
+
+      - name: Acquire sources
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          architecture: x64
+          cache: 'pip'
+          cache-dependency-path: |
+            notebook/jupyter/pyproject.toml
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          cache-dependency-glob: |
+            notebook/jupyter/pyproject.toml
+          cache-suffix: ${{ matrix.python-version }}
+          enable-cache: true
+          version: "latest"
+
+      - name: Install project
+        run: |
+          uv pip install notebook/jupyter[all]
+
+      - name: Validate notebook/jupyter
+        run: |
+          cd notebook/jupyter
+          pytest
+
+      - name: Build docs for notebook/jupyter
+        run: |
+          cd notebook/jupyter
+          poe check
+          poe docs-html
+          poe docs-linkcheck

.gitignore

@@ -1,6 +1,7 @@
 .idea
 .venv*
 __pycache__
+_build
 .coverage*
 .env
 .DS_Store
@@ -14,3 +15,4 @@ logs.log
 *.tmp
 *.swp
 *.bak
+*.egg-info

notebook/jupyter/README.md

@@ -0,0 +1,8 @@
+# CrateDB Jupyter Examples
+
+A few examples using CrateDB from Jupyter Notebooks.
+If you are here already, we recommend to check out the [JupySQL] examples
+at least.
+
+
+[JupySQL]: https://jupysql.ploomber.io/

notebook/jupyter/conftest.py

@@ -0,0 +1,31 @@
+import os
+from pathlib import Path
+
+import pytest
+import sqlalchemy as sa
+from pueblo.testing.notebook import generate_tests
+
+
+def pytest_generate_tests(metafunc):
+    """
+    Generate pytest test case per Jupyter Notebook.
+    """
+    here = Path(__file__).parent
+    generate_tests(metafunc, path=here)
+
+
+@pytest.fixture(autouse=True)
+def reset_database_tables():
+    """
+    Before running a test case, reset relevant tables in database.
+    """
+
+    connection_string = os.environ.get("CRATEDB_CONNECTION_STRING")
+
+    engine = sa.create_engine(connection_string, echo=os.environ.get("DEBUG"))
+    connection = engine.connect()
+
+    reset_tables = []
+
+    for table in reset_tables:
+        connection.execute(sa.text(f"DROP TABLE IF EXISTS {table};"))

notebook/jupyter/docs/conf.py

@@ -0,0 +1,6 @@
+project = "CrateDB Jupyter Examples"
+copyright = "2023-2025, The CrateDB Developers"
+author = "The CrateDB Developers"
+
+html_theme = "furo"
+extensions = ["myst_nb"]

notebook/jupyter/docs/index.md

@@ -0,0 +1,14 @@
+# CrateDB Jupyter Examples
+
+This is a little Sphinx documentation stub that includes Jupyter Notebooks,
+by using [MyST-NB].
+
+```{toctree}
+:maxdepth: 2
+:glob:
+
+*
+```
+
+
+[MyST-NB]: https://myst-nb.readthedocs.io/

notebook/jupyter/docs/jupysql.ipynb

@@ -0,0 +1 @@
+../jupysql.ipynb