jupyter-duckdb 0.3.3__tar.gz → 0.4.1__tar.gz

jupyter-duckdb-0.4.1/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.1
+Name: jupyter-duckdb
+Version: 0.4.1
+Summary: a basic wrapper kernel for DuckDB
+Home-page: https://github.com/erictroebs/jupyter-duckdb
+Author: Eric Tröbs
+Author-email: eric.troebs@tu-ilmenau.de
+Project-URL: Bug Tracker, https://github.com/erictroebs/jupyter-duckdb/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+
+# DuckDB Kernel for Jupyter
+
+This is a simple DuckDB wrapper kernel which accepts SQL as input, executes it using a previously loaded DuckDB instance
+and formats the output as a table. There are some magic commands that make teaching easier with this kernel.
+
+## Quick Start
+
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/git/https%3A%2F%2Fdbgit.prakinf.tu-ilmenau.de%2Fertr8623%2Fjupyter-duckdb.git/master)
+
+## Table of Contents
+
+- [Setup](#setup)
+    - [Using pip](#using-pip)
+    - [Using Docker](#using-docker)
+- [Usage](#usage)
+    - [A Note on Magic Commands](#a-note-on-magic-commands)
+    - [Load a Database](#load-a-database)
+    - [Schema Diagrams](#schema-diagrams)
+    - [Number of Rows](#number-of-rows)
+    - [Ship Tests With Your Notebook](#ship-tests-with-your-notebooks)
+
+## Setup
+
+### Using pip
+
+Run `pip` to install the corresponding package from [pypi](https://pypi.org/project/jupyter-duckdb/) **after**
+Jupyter is already installed.
+
+```bash
+pip install jupyter-duckdb
+```
+
+Register the kernel.
+
+```bash
+jupyter kernelspec install <path to the site-packages directory>/duckdb_kernel
+```
+
+Now start Jupyter the usual way and the kernel should be available.
+
+### Using Docker
+
+Execute the following command to pull a and run a prepared image.
+
+```bash
+docker run -p 8888:8888 troebs/jupyter:duckdb
+```
+
+This image can also be used with JupyterHub and the
+[DockerSpawner / SwarmSpawner](https://github.com/jupyterhub/dockerspawner)
+and probably with the
+[kubespawner](https://github.com/jupyterhub/kubespawner).
+You can also build your own image using the [Dockerfile](Dockerfile) in the repository.
+
+## Usage
+
+A detailed example can be found [in the repository](example/). The rest of this section describes the magic commands.
+
+### A Note on Magic Commands
+
+Many Jupyter kernels make a difference between magic commands for a single line starting with one percent sign and
+others for a whole cell starting with two percent signs. The upcoming magic commands always apply to a whole cell.
+Therefore, it does not matter whether you use a single or two percent signs. However, the magic commands must always
+be used at the beginning of a cell.
+
+It is also possible to use more than one magic command per cell.
+
+### Load a Database
+
+To load the database two magic commands are available.
+
+`CREATE` creates a new database and therefore overwrites files with the same name without prompting. Using the optional
+parameter `OF` you can either provide another DuckDB file or a file with SQL statements. In the first case the included
+tables will be copied to the new database, while in the second case the SQL statements are just executed. We find this
+feature very useful to work in a temporary copy of the data and therefore be able to restart at any time. The last
+optional parameter `WITH_TESTS` is described in detail [below](#ship-tests-with-your-notebooks).
+
+```
+%CREATE data.duckdb OF my_statements.sql
+```
+
+`LOAD` on the other hand loads an existing database and returns an error if it does not exist. (That is why `OF` cannot
+be used with `LOAD`! `WITH_TESTS` on the other hand is available also with this magic command.)
+
+```
+%LOAD data.duckdb
+```
+
+Only one database can be open at any time. If a new database is created or loaded, the current one is closed first and
+saved to disk if necessary.
+
+Please note that `:memory:` is also a valid file path for DuckDB. The data is then stored exclusively in the main
+memory. In combination with `CREATE` and `OF` this makes it possible to work on a temporary copy in memory.
+
+### Schema Diagrams
+
+The magic command `SCHEMA` can be used to create a simple schema diagram of the loaded database, showing all created
+tables, their columns and data types, but without any views. Primary keys are printed in bold and unique keys are
+underlined. Foreign keys are also highlighted and the dependencies between the tables are shown by arrows.
+
+The optional parameter `LR` can be set to a true value to force a horizontal layout. This saves visual space especially
+for larger amounts of tables.
+
+```
+%SCHEMA LR 1
+```
+
+### Number of Rows
+
+By default, only 20 rows are shown. All further lines are replaced by three dots. When hovering over the three dots
+using the cursor, the number of omitted lines is displayed. Of course, the number of lines displayed can be changed.
+
+The magic command `ALL_ROWS` and its short form `ALL` can be used to display **all** rows of the query in the same
+cell. **Caution**: With large result sets this can lead to a frozen Jupyter instance.
+
+```sql
+%ALL_ROWS
+SELECT *
+FROM foo
+-- all rows
+```
+
+The magic command `QUERY_MAX_ROWS` followed by an integer can be used to change the number of displayed rows for the
+current cell.
+
+```sql
+%QUERY_MAX_ROWS 50
+SELECT *
+FROM foo
+-- 50 rows
+```
+
+The magic command `MAX_ROWS` followed by an integer can be used to change the number of displayed rows for all future
+queries including the current cell.
+
+```sql
+%MAX_ROWS 30
+SELECT *
+FROM foo
+-- 30 rows
+```
+
+```sql
+SELECT *
+FROM bar
+-- 30 rows
+```
+
+### Ship Tests With Your Notebooks
+
+Simple tests can be loaded together with the database with the help of the `WITH_TESTS` parameter. These tests are
+stored as a JSON file. Each test is assigned a unique name, a result set and whether the test should check the order
+of the result. A very simple test file looks like the following JSON object:
+
+```json
+{
+  "task1": {
+    "ordered": false,
+    "equals": [
+      [
+        1,
+        "Name 1"
+      ],
+      [
+        2,
+        "Name 2"
+      ]
+    ]
+  }
+}
+```
+
+To bind a test to a cell, use the magic command `TEST` in combination with a name. After the cell is executed, the
+result is evaluated and then displayed below the query result.
+
+```sql
+%TEST task1
+SELECT 2, 'Name 2'
+UNION
+SELECT 1, 'Name 1'
+```
+
+Disclaimer: The integrated testing is work-in-progress and thus subject to potentially incompatible changes and
+enhancements.

jupyter-duckdb-0.4.1/README.md

@@ -0,0 +1,184 @@
+# DuckDB Kernel for Jupyter
+
+This is a simple DuckDB wrapper kernel which accepts SQL as input, executes it using a previously loaded DuckDB instance
+and formats the output as a table. There are some magic commands that make teaching easier with this kernel.
+
+## Quick Start
+
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/git/https%3A%2F%2Fdbgit.prakinf.tu-ilmenau.de%2Fertr8623%2Fjupyter-duckdb.git/master)
+
+## Table of Contents
+
+- [Setup](#setup)
+    - [Using pip](#using-pip)
+    - [Using Docker](#using-docker)
+- [Usage](#usage)
+    - [A Note on Magic Commands](#a-note-on-magic-commands)
+    - [Load a Database](#load-a-database)
+    - [Schema Diagrams](#schema-diagrams)
+    - [Number of Rows](#number-of-rows)
+    - [Ship Tests With Your Notebook](#ship-tests-with-your-notebooks)
+
+## Setup
+
+### Using pip
+
+Run `pip` to install the corresponding package from [pypi](https://pypi.org/project/jupyter-duckdb/) **after**
+Jupyter is already installed.
+
+```bash
+pip install jupyter-duckdb
+```
+
+Register the kernel.
+
+```bash
+jupyter kernelspec install <path to the site-packages directory>/duckdb_kernel
+```
+
+Now start Jupyter the usual way and the kernel should be available.
+
+### Using Docker
+
+Execute the following command to pull a and run a prepared image.
+
+```bash
+docker run -p 8888:8888 troebs/jupyter:duckdb
+```
+
+This image can also be used with JupyterHub and the
+[DockerSpawner / SwarmSpawner](https://github.com/jupyterhub/dockerspawner)
+and probably with the
+[kubespawner](https://github.com/jupyterhub/kubespawner).
+You can also build your own image using the [Dockerfile](Dockerfile) in the repository.
+
+## Usage
+
+A detailed example can be found [in the repository](example/). The rest of this section describes the magic commands.
+
+### A Note on Magic Commands
+
+Many Jupyter kernels make a difference between magic commands for a single line starting with one percent sign and
+others for a whole cell starting with two percent signs. The upcoming magic commands always apply to a whole cell.
+Therefore, it does not matter whether you use a single or two percent signs. However, the magic commands must always
+be used at the beginning of a cell.
+
+It is also possible to use more than one magic command per cell.
+
+### Load a Database
+
+To load the database two magic commands are available.
+
+`CREATE` creates a new database and therefore overwrites files with the same name without prompting. Using the optional
+parameter `OF` you can either provide another DuckDB file or a file with SQL statements. In the first case the included
+tables will be copied to the new database, while in the second case the SQL statements are just executed. We find this
+feature very useful to work in a temporary copy of the data and therefore be able to restart at any time. The last
+optional parameter `WITH_TESTS` is described in detail [below](#ship-tests-with-your-notebooks).
+
+```
+%CREATE data.duckdb OF my_statements.sql
+```
+
+`LOAD` on the other hand loads an existing database and returns an error if it does not exist. (That is why `OF` cannot
+be used with `LOAD`! `WITH_TESTS` on the other hand is available also with this magic command.)
+
+```
+%LOAD data.duckdb
+```
+
+Only one database can be open at any time. If a new database is created or loaded, the current one is closed first and
+saved to disk if necessary.
+
+Please note that `:memory:` is also a valid file path for DuckDB. The data is then stored exclusively in the main
+memory. In combination with `CREATE` and `OF` this makes it possible to work on a temporary copy in memory.
+
+### Schema Diagrams
+
+The magic command `SCHEMA` can be used to create a simple schema diagram of the loaded database, showing all created
+tables, their columns and data types, but without any views. Primary keys are printed in bold and unique keys are
+underlined. Foreign keys are also highlighted and the dependencies between the tables are shown by arrows.
+
+The optional parameter `LR` can be set to a true value to force a horizontal layout. This saves visual space especially
+for larger amounts of tables.
+
+```
+%SCHEMA LR 1
+```
+
+### Number of Rows
+
+By default, only 20 rows are shown. All further lines are replaced by three dots. When hovering over the three dots
+using the cursor, the number of omitted lines is displayed. Of course, the number of lines displayed can be changed.
+
+The magic command `ALL_ROWS` and its short form `ALL` can be used to display **all** rows of the query in the same
+cell. **Caution**: With large result sets this can lead to a frozen Jupyter instance.
+
+```sql
+%ALL_ROWS
+SELECT *
+FROM foo
+-- all rows
+```
+
+The magic command `QUERY_MAX_ROWS` followed by an integer can be used to change the number of displayed rows for the
+current cell.
+
+```sql
+%QUERY_MAX_ROWS 50
+SELECT *
+FROM foo
+-- 50 rows
+```
+
+The magic command `MAX_ROWS` followed by an integer can be used to change the number of displayed rows for all future
+queries including the current cell.
+
+```sql
+%MAX_ROWS 30
+SELECT *
+FROM foo
+-- 30 rows
+```
+
+```sql
+SELECT *
+FROM bar
+-- 30 rows
+```
+
+### Ship Tests With Your Notebooks
+
+Simple tests can be loaded together with the database with the help of the `WITH_TESTS` parameter. These tests are
+stored as a JSON file. Each test is assigned a unique name, a result set and whether the test should check the order
+of the result. A very simple test file looks like the following JSON object:
+
+```json
+{
+  "task1": {
+    "ordered": false,
+    "equals": [
+      [
+        1,
+        "Name 1"
+      ],
+      [
+        2,
+        "Name 2"
+      ]
+    ]
+  }
+}
+```
+
+To bind a test to a cell, use the magic command `TEST` in combination with a name. After the cell is executed, the
+result is evaluated and then displayed below the query result.
+
+```sql
+%TEST task1
+SELECT 2, 'Name 2'
+UNION
+SELECT 1, 'Name 1'
+```
+
+Disclaimer: The integrated testing is work-in-progress and thus subject to potentially incompatible changes and
+enhancements.

{jupyter-duckdb-0.3.3 → jupyter-duckdb-0.4.1}/setup.py

@@ -5,7 +5,7 @@ with open('README.md', 'r', encoding='utf-8') as file:
 
 setup(
     name='jupyter-duckdb',
-    version='0.3.3',
+    version='0.4.1',
     author='Eric Tröbs',
     author_email='eric.troebs@tu-ilmenau.de',
     description='a basic wrapper kernel for DuckDB',
@@ -22,10 +22,11 @@ setup(
     ],
     package_dir={'': 'src'},
     packages=find_packages(where='src'),
-    python_requires='>=3.6',
+    python_requires='>=3.7',
     install_requires=[
         'jupyter',
-        'duckdb==0.6.1',
+        'duckdb==0.8.1',
+        'graphviz==0.20.1',
         'checkmarkandcross'
     ],
     package_data={
@@ -33,5 +34,5 @@ setup(
             'kernel.json'
         ]
     },
-    include_package_data=True,
+    include_package_data=True
 )

jupyter-duckdb-0.4.1/src/duckdb_kernel/__init__.py

@@ -0,0 +1 @@
+from .kernel import DuckDBKernel