Move feat from %sqlrender to %sqlcmd snippets

Moved features, added FutureWarning, update API Reference documentation, modified test functions update changelog update changelog for #647 Update CHANGELOG.md documentation change of moving sqlrender feature manually relocating changes resolving docs build failed lint fixing readthedocs remove invalid snippet from documenation subquery and more detailed error message added lint change in formatting update toc
ploomber · Jun 28, 2023 · b84b85b · b84b85b
1 parent ece54c1
commit b84b85b
Show file tree

Hide file tree

Showing 18 changed files with 122 additions and 132 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,8 +2,9 @@
 
 ## 0.7.10dev
 
-* [Feature] Modified `TableDescription` to add styling, generate messages and format the calculated outputs (#459)
 * [Feature] Support flexible spacing `myvar=<<` operator ([#525](https://github.com/ploomber/jupysql/issues/525))
+* [Feature] Moved `%sqlrender` feature to `%sqlcmd snippets` (#647)
+* [Feature] Modified `TableDescription` to add styling, generate messages and format the calculated outputs (#459)
 * [Doc] Modified integrations content to ensure they're all consistent (#523)
 * [Doc] Document --persist-replace in API section (#539)
 * [Fix] Fixed CI issue by updating `invalid_connection_string_duckdb` in `test_magic.py` (#631)

diff --git a/doc/_toc.yml b/doc/_toc.yml
@@ -43,7 +43,6 @@ parts:
     chapters:
     - file: api/magic-sql
     - file: api/magic-plot
-    - file: api/magic-render
     - file: api/magic-snippets
     - file: api/configuration
     - file: api/python

diff --git a/doc/api/magic-render.md b/doc/api/magic-render.md
diff --git a/doc/api/magic-snippets.md b/doc/api/magic-snippets.md
@@ -5,15 +5,14 @@ jupytext:
     extension: .md
     format_name: myst
     format_version: 0.13
-    jupytext_version: 1.14.5
+    jupytext_version: 1.14.6
 kernelspec:
   display_name: Python 3 (ipykernel)
   language: python
   name: python3
 myst:
   html_meta:
-    description lang=en: Documentation for  %sqlcmd snippets
-      from JupySQL
+    description lang=en: Documentation for  %sqlcmd snippets from JupySQL
     keywords: jupyter, sql, jupysql, snippets
     property=og:locale: en_US
 ---
@@ -73,28 +72,46 @@ Returns all the snippets saved in the environment
 
 Arguments:
 
+`{snippet_name}` Return a snippet.
+
 `-d`/`--delete` Delete a snippet.
 
 `-D`/`--delete-force` Force delete a snippet. This may be useful if there are other dependent snippets, and you still need to delete this snippet.
 
 `-A`/`--delete-force-all` Force delete a snippet and all dependent snippets.
 
 ```{code-cell} ipython3
+chinstrap_snippet = %sqlcmd snippets chinstrap
+print(chinstrap_snippet)
+```
+
+This returns the stored snippet `chinstrap`.
+
+Calling `%sqlcmd snippets {snippet_name}` also works on a snippet that is dependent on others. To demonstrate it, let's create a snippet dependent on `chinstrap` snippet.
+
+```{code-cell} ipython3
+%%sql --save chinstrap_sub
+SELECT * FROM chinstrap where island == 'Dream'
+```
+
+```{code-cell} ipython3
+chinstrap_sub_snippet = %sqlcmd snippets chinstrap_sub
+print(chinstrap_sub_snippet)
+```
+
+This returns the stored snippet `chinstrap_sub`.
 
+```{code-cell} ipython3
 %sqlcmd snippets -d gentoo
 ```
 
 This deletes the stored snippet `gentoo`.
 
-To demonstrate `force-delete` let's create a snippet dependent on `chinstrap` snippet.
+To demonstrate `force-delete` let's first confirm there is a snippet dependent on `chinstrap` snippet.
 
 ```{code-cell} ipython3
-:tags: [hide-output]
-
-%%sql --save chinstrap_sub
-SELECT * FROM chinstrap where island == 'Dream'
+%sqlcmd snippets
 ```
-+++
 
 Trying to delete the `chinstrap` snippet will display an error message:
 
@@ -104,10 +121,9 @@ Trying to delete the `chinstrap` snippet will display an error message:
 %sqlcmd snippets -d chinstrap
 ```
 
-If you still wish to delete this snippet, you can run the below command:
+If you still wish to delete this snippet, you should use `force-delete` by running the below command:
 
 ```{code-cell} ipython3
-
 %sqlcmd snippets -D chinstrap
 ```
 
@@ -130,6 +146,5 @@ SELECT * FROM chinstrap where island == 'Dream'
 Now, force delete `chinstrap` and its dependent `chinstrap_sub`:
 
 ```{code-cell} ipython3
-
 %sqlcmd snippets -A chinstrap
 ```
diff --git a/doc/compose.md b/doc/compose.md
@@ -5,16 +5,16 @@ jupytext:
     extension: .md
     format_name: myst
     format_version: 0.13
-    jupytext_version: 1.14.4
+    jupytext_version: 1.14.6
 kernelspec:
   display_name: Python 3 (ipykernel)
   language: python
   name: python3
 myst:
   html_meta:
-    description lang=en: "Use JupySQL to organize large SQL queries in a Jupyter notebook"
-    keywords: "jupyter, sql, jupysql"
-    property=og:locale: "en_US"
+    description lang=en: Use JupySQL to organize large SQL queries in a Jupyter notebook
+    keywords: jupyter, sql, jupysql
+    property=og:locale: en_US
 ---
 
 # Organizing Large Queries
@@ -109,7 +109,6 @@ Join the filtered genres and tracks, so we only get Rock and Metal tracks, and s
 
 We automatically extract the tables from the query and infer the dependencies from all the saved snippets.
 
-
 ```{code-cell} ipython3
 %%sql --save track_fav
 SELECT t.*
@@ -127,7 +126,6 @@ GROUP BY artist
 ORDER BY COUNT(*) DESC
 ```
 
-
 ```{note}
 A saved snippet will override an existing table with the same name during query formation. If you wish to delete a snippet please refer to [sqlcmd snippets API](api/magic-snippets.md).
 
@@ -144,10 +142,10 @@ top_artist.bar()
 
 It looks like Iron Maiden had the highest number of rock and metal songs in the table.
 
-We can render the full query with the `%sqlrender` magic:
+We can render the full query with the `%sqlcmd snippets {name}` magic:
 
 ```{code-cell} ipython3
-final = %sqlrender top_artist
+final = %sqlcmd snippets top_artist
 print(final)
 ```
 
@@ -160,4 +158,4 @@ We can verify the retrieved query returns the same result:
 
 ## Summary
 
-In the given example, we demonstrated JupySQL's usage as a tool for managing large SQL queries in Jupyter Notebooks. It effectively broke down a complex query into smaller, organized parts, simplifying the process of analyzing a record store's sales database. By using JupySQL, users can easily maintain and reuse their queries, enhancing the overall data analysis experience.
+In the given example, we demonstrated JupySQL's usage as a tool for managing large SQL queries in Jupyter Notebooks. It effectively broke down a complex query into smaller, organized parts, simplifying the process of analyzing a record store's sales database. By using JupySQL, users can easily maintain and reuse their queries, enhancing the overall data analysis experience.
diff --git a/doc/integrations/mariadb.ipynb b/doc/integrations/mariadb.ipynb
@@ -847,7 +847,7 @@
     }
    ],
    "source": [
-    "query = %sqlrender trip_stats\n",
+    "query = %sqlcmd snippets trip_stats\n",
     "print(query)"
    ]
   },

diff --git a/doc/integrations/mssql.ipynb b/doc/integrations/mssql.ipynb
@@ -1049,7 +1049,7 @@
     }
    ],
    "source": [
-    "query = %sqlrender trip_stats\n",
+    "query = %sqlcmd snippets trip_stats\n",
     "print(query)"
    ]
   },

diff --git a/doc/integrations/mysql.ipynb b/doc/integrations/mysql.ipynb
@@ -903,7 +903,7 @@
     }
    ],
    "source": [
-    "query = %sqlrender trip_stats\n",
+    "query = %sqlcmd snippets trip_stats\n",
     "print(query)"
    ]
   },

diff --git a/doc/integrations/oracle.ipynb b/doc/integrations/oracle.ipynb
@@ -613,7 +613,7 @@
     }
    ],
    "source": [
-    "query = %sqlrender saved_cte\n",
+    "query = %sqlcmd snippets saved_cte\n",
     "print(query)"
    ]
   },
@@ -757,7 +757,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.10"
+   "version": "3.10.11"
   },
   "myst": {
    "html_meta": {

diff --git a/doc/integrations/postgres-connect.ipynb b/doc/integrations/postgres-connect.ipynb
@@ -771,7 +771,7 @@
     }
    ],
    "source": [
-    "query = %sqlrender trip_stats\n",
+    "query = %sqlcmd snippets trip_stats\n",
     "print(query)"
    ]
   },
@@ -1058,7 +1058,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.9"
+   "version": "3.10.11"
   },
   "myst": {
    "html_meta": {

diff --git a/doc/integrations/snowflake.ipynb b/doc/integrations/snowflake.ipynb
@@ -751,7 +751,7 @@
     }
    ],
    "source": [
-    "final = %sqlrender no_nulls\n",
+    "final = %sqlcmd snippets no_nulls\n",
     "print(final)"
    ]
   },

diff --git a/doc/integrations/trinodb.ipynb b/doc/integrations/trinodb.ipynb
@@ -775,7 +775,7 @@
     }
    ],
    "source": [
-    "query = %sqlrender trip_stats\n",
+    "query = %sqlcmd snippets trip_stats\n",
     "print(query)"
    ]
   },