Add support for IPython magic

.github/workflows/cicd.yaml

@@ -12,7 +12,7 @@ on:
 env:
   POETRY_VERSION: 1.1.13
   PSR_VERSION: 7.28.1
-  CACHE_NUMBER: 4
+  CACHE_NUMBER: 5
 
 jobs:
   form:

docs/cli.md

@@ -1,4 +1,4 @@
-# The Command Line Interface
+# Command Line Interface
 
 In addition to providing the main entrypoint,
 documented below,

docs/conf.py

@@ -32,4 +32,5 @@
 myst_heading_anchors = 2
 myst_enable_extensions = [
     "html_admonition",
+    "colon_fence",
 ]

docs/index.md

@@ -23,6 +23,7 @@ we'd kindly ask you to abide by our [code of conduct](./coc.md).
 If you'd like to learn more about the project,
 please see the [README](./readme.md).
 For information about the source code,
+including the CLI and IPython/Jupyter Magic,
 please see the [documentation](./pyprql.md).
 If testing is your passion,
 take a peek at [testing](./tests.md).

docs/magic.md

@@ -0,0 +1,15 @@
+# IPython and Jupyter Magic
+
+For a "how-to" and usage instructions,
+please see our [magic README](./magic_readme.md).
+Documentation on extension loading [lives here](./magic_init.md),
+while documentation on the magic class implementation [lives here](./magic_implement.md).
+
+```{toctree}
+:hidden:
+:maxdepth: 3
+
+magic_readme
+magic_init
+magic_implement
+```

docs/magic_implement.md

@@ -0,0 +1,7 @@
+# The PyPRQL Magic Implementation
+
+```{eval-rst}
+.. automodule:: pyprql.magic.prql
+   :members:
+   :private-members:
+```

docs/magic_init.md

@@ -0,0 +1,7 @@
+# Loading PyPRQL Magic
+
+```{eval-rst}
+.. automodule:: pyprql.magic
+   :members:
+   :private-members:
+```

docs/magic_readme.md

@@ -0,0 +1,2 @@
+```{include} ../pyprql/magic/README.md
+```

docs/pyprql.md

@@ -1,14 +1,19 @@
+# Source Code
+
 Currently, the source code is divided as follows:
 
 - `cli` module contains the command line interface logic.
-  See [cli](./cli.md).
+  See [Command Line Interface](./cli.md).
+- `magic` module that implements the PRQL IPython/Jupyer magic.
+  See [IPython and Jupyter Magic](./magic.md).
 - `assets` sub-package that contains a number of useful references.
-  See [assets](./assets.md).
+  See [Assets](./assets.md).
 
 ```{toctree}
 :hidden:
 :maxdepth: 3
 
 cli
+magic
 assets
 ```

docs/requirements.txt

@@ -1,14 +1,18 @@
-icecream==2.1.1
-rich==12.2.0
-click==8.1.2
-prompt-toolkit==3.0.2
-Pygments==2.11.2
+icecream==2.1.2
+rich==12.4.1
+click==8.1.3
+prompt-toolkit==3.0.29
+Pygments==2.12.0
 fuzzyfinder==2.1.0
-SQLAlchemy==1.4.35
+SQLAlchemy==1.4.36
 pandas==1.4.2
 numpy==1.22.3
+prql_python==0.0.2
+ipython==7.33.0
+ipython-sql==0.4.0
+duckdb-engine==0.1.8
+traitlets==5.2.1.post0
 sphinx==4.3.2
 sphinx-rtd-theme==1.0.0
-myst-parser==0.17.0
-pytest==7.1.1
-prql_python==0.0.2
+myst-parser==0.17.2
+pytest==7.1.2

noxfile.py

@@ -38,7 +38,7 @@ def constrained_install(session: Session, *args: str, **kwargs: Any) -> None:
     os.remove("requirements.txt")
 
 
-@nox.session(python="3.8")
+@nox.session(python="3.10")
 def form(session: Session) -> None:
     """Format code with isort and black."""
     args = session.posargs or LOCATIONS