Skip to content

Commit 61141ee

Browse files
tswasttswast
authored
docs: add code samples for Jupyter/IPython magics (#1013)
Follow-up to GoogleCloudPlatform/python-docs-samples#6889, which removed a BigQuery magics sample for using query parameters. Note: jupyter_tutorial_test.py is a copy of what is in the `samples/snippets` folder. Once the docs have been updated to point to this new version, we can remove that copy and remove the Jupyter/IPython depedencencies from `samples/snippets/requirements.txt`. Thank you for opening a Pull Request! Before submitting your PR, there are a few things you can do to make sure it goes smoothly: - [ ] Make sure to open an issue as a [bug/issue](https://github.com/googleapis/python-bigquery/issues/new/choose) before writing your code! That way we can discuss the change, evaluate designs, and agree on the general idea - [ ] Ensure the tests and linter pass - [ ] Code coverage does not decrease (if any source code was changed) - [ ] Appropriate docs were updated (if necessary)
1 parent d64f5b6 commit 61141ee

File tree

13 files changed

+503
-67
lines changed

13 files changed

+503
-67
lines changed

‎docs/magics.rst‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,34 @@
11
IPython Magics for BigQuery
22
===========================
33

4+
To use these magics, you must first register them. Run the ``%load_ext`` magic
5+
in a Jupyter notebook cell.
6+
7+
.. code::
8+
9+
%load_ext google.cloud.bigquery
10+
11+
This makes the ``%%bigquery`` magic available.
12+
13+
Code Samples
14+
------------
15+
16+
Running a query:
17+
18+
.. literalinclude:: ./samples/magics/query.py
19+
:dedent: 4
20+
:start-after: [START bigquery_jupyter_query]
21+
:end-before: [END bigquery_jupyter_query]
22+
23+
Running a parameterized query:
24+
25+
.. literalinclude:: ./samples/magics/query_params_scalars.py
26+
:dedent: 4
27+
:start-after: [START bigquery_jupyter_query_params_scalars]
28+
:end-before: [END bigquery_jupyter_query_params_scalars]
29+
30+
API Reference
31+
-------------
32+
433
.. automodule:: google.cloud.bigquery.magics.magics
534
:members:

‎google/cloud/bigquery/magics/magics.py‎

Lines changed: 0 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -14,15 +14,6 @@
1414

1515
"""IPython Magics
1616
17-
To use these magics, you must first register them. Run the ``%load_ext`` magic
18-
in a Jupyter notebook cell.
19-
20-
.. code::
21-
22-
%load_ext google.cloud.bigquery
23-
24-
This makes the ``%%bigquery`` magic available.
25-
2617
.. function:: %%bigquery
2718
2819
IPython cell magic to run a query and display the result as a DataFrame
@@ -85,63 +76,6 @@
8576
.. note::
8677
All queries run using this magic will run using the context
8778
:attr:`~google.cloud.bigquery.magics.Context.credentials`.
88-
89-
Examples:
90-
The following examples can be run in an IPython notebook after loading
91-
the bigquery IPython extension (see ``In[1]``) and setting up
92-
Application Default Credentials.
93-
94-
.. code-block:: none
95-
96-
In [1]: %load_ext google.cloud.bigquery
97-
98-
In [2]: %%bigquery
99-
...: SELECT name, SUM(number) as count
100-
...: FROM `bigquery-public-data.usa_names.usa_1910_current`
101-
...: GROUP BY name
102-
...: ORDER BY count DESC
103-
...: LIMIT 3
104-
105-
Out[2]: name count
106-
...: -------------------
107-
...: 0 James 4987296
108-
...: 1 John 4866302
109-
...: 2 Robert 4738204
110-
111-
In [3]: %%bigquery df --project my-alternate-project --verbose
112-
...: SELECT name, SUM(number) as count
113-
...: FROM `bigquery-public-data.usa_names.usa_1910_current`
114-
...: WHERE gender = 'F'
115-
...: GROUP BY name
116-
...: ORDER BY count DESC
117-
...: LIMIT 3
118-
Executing query with job ID: bf633912-af2c-4780-b568-5d868058632b
119-
Query executing: 2.61s
120-
Query complete after 2.92s
121-
122-
In [4]: df
123-
124-
Out[4]: name count
125-
...: ----------------------
126-
...: 0 Mary 3736239
127-
...: 1 Patricia 1568495
128-
...: 2 Elizabeth 1519946
129-
130-
In [5]: %%bigquery --params {"num": 17}
131-
...: SELECT @num AS num
132-
133-
Out[5]: num
134-
...: -------
135-
...: 0 17
136-
137-
In [6]: params = {"num": 17}
138-
139-
In [7]: %%bigquery --params $params
140-
...: SELECT @num AS num
141-
142-
Out[7]: num
143-
...: -------
144-
...: 0 17
14579
"""
14680

14781
from __future__ import print_function

‎noxfile.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -186,8 +186,9 @@ def snippets(session):
186186
session.run(
187187
"py.test",
188188
"samples",
189-
"--ignore=samples/snippets",
189+
"--ignore=samples/magics",
190190
"--ignore=samples/geography",
191+
"--ignore=samples/snippets",
191192
*session.posargs,
192193
)
193194

‎samples/magics/__init__.py‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Copyright 2021 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# https://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.

‎samples/magics/_helpers.py‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Copyright 2021 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# https://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
16+
def strip_region_tags(sample_text):
17+
"""Remove blank lines and region tags from sample text"""
18+
magic_lines = [
19+
line for line in sample_text.split("\n") if len(line) > 0 and "# [" not in line
20+
]
21+
return "\n".join(magic_lines)

‎samples/magics/conftest.py‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Copyright 2021 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# https://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
import pytest
16+
17+
interactiveshell = pytest.importorskip("IPython.terminal.interactiveshell")
18+
tools = pytest.importorskip("IPython.testing.tools")
19+
20+
21+
@pytest.fixture(scope="session")
22+
def ipython():
23+
config = tools.default_config()
24+
config.TerminalInteractiveShell.simple_prompt = True
25+
shell = interactiveshell.TerminalInteractiveShell.instance(config=config)
26+
return shell
27+
28+
29+
@pytest.fixture(autouse=True)
30+
def ipython_interactive(ipython):
31+
"""Activate IPython's builtin hooks
32+
33+
for the duration of the test scope.
34+
"""
35+
with ipython.builtin_trap:
36+
yield ipython

0 commit comments

Comments
 (0)