Merge branch 'main' into owl-bot-update-lock-8e3e7e18255c22d1489258d0374c901c01f9c4fd77a12088670cd73d580aa737

Author: tswast

.github/sync-repo-settings.yaml

@@ -16,8 +16,8 @@ branchProtectionRules:
     - 'docs'
     - 'unit (3.7)'
     - 'unit (3.8)'
-    - 'unit (3.11)'
     - 'unit (3.12)'
+    - 'unit (3.13)'
     - 'cover'
     - 'Samples - Lint'
     - 'Samples - Python 3.8'
@@ -37,4 +37,4 @@ permissionRules:
   - team: python-samples-owners
     permission: push
   - team: python-samples-reviewers
-    permission: push
+    permission: push

.github/workflows/unittest.yml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python: ['3.7', '3.8', '3.11', '3.12']
+        python: ['3.7', '3.8', '3.11', '3.12', '3.13']
     steps:
     - name: Checkout
       uses: actions/checkout@v4

.kokoro/continuous/prerelease-deps-3.13.cfg

@@ -0,0 +1,7 @@
+# Format: //devtools/kokoro/config/proto/build.proto
+
+# Only run this nox session.
+env_vars: {
+    key: "NOX_SESSION"
+    value: "prerelease_deps-3.13"
+}

.kokoro/presubmit/prerelease-deps-3.13.cfg

@@ -0,0 +1,7 @@
+# Format: //devtools/kokoro/config/proto/build.proto
+
+# Only run this nox session.
+env_vars: {
+    key: "NOX_SESSION"
+    value: "prerelease_deps-3.13"
+}

.kokoro/presubmit/system-3.13.cfg

@@ -0,0 +1,7 @@
+# Format: //devtools/kokoro/config/proto/build.proto
+
+# Only run this nox session.
+env_vars: {
+    key: "NOX_SESSION"
+    value: "system-3.13"
+}

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.5.0](https://github.com/googleapis/python-bigquery-magics/compare/v0.4.0...v0.5.0) (2024-12-17)
+
+
+### Features
+
+* Add `%%bqsql` as an alias to the `%%bigquery` magic ([#72](https://github.com/googleapis/python-bigquery-magics/issues/72)) ([03fe1d5](https://github.com/googleapis/python-bigquery-magics/commit/03fe1d544ef22865c07c680873f980c64bbc7abc))
+* Add `bigquery_magics.context.default_variable` option ([#70](https://github.com/googleapis/python-bigquery-magics/issues/70)) ([72ed882](https://github.com/googleapis/python-bigquery-magics/commit/72ed882c9359718a702bab2bca76933548650064))
+
 ## [0.4.0](https://github.com/googleapis/python-bigquery-magics/compare/v0.3.0...v0.4.0) (2024-09-24)
 
 

CONTRIBUTING.rst

@@ -22,7 +22,7 @@ In order to add a feature:
   documentation.
 
 - The feature must work fully on the following CPython versions:
-  3.7, 3.8, 3.9, 3.11 and 3.12 on both UNIX and Windows.
+  3.7, 3.8, 3.9, 3.11, 3.12 and 3.13 on both UNIX and Windows.
 
 - The feature must not add unnecessary dependencies (where
   "unnecessary" is of course subjective, but new dependencies should
@@ -72,7 +72,7 @@ We use `nox <https://nox.readthedocs.io/en/latest/>`__ to instrument our tests.
 
 - To run a single unit test::
 
-    $ nox -s unit-3.12 -- -k <name of test>
+    $ nox -s unit-3.13 -- -k <name of test>
 
 
   .. note::
@@ -143,12 +143,12 @@ Running System Tests
    $ nox -s system
 
    # Run a single system test
-   $ nox -s system-3.12 -- -k <name of test>
+   $ nox -s system-3.13 -- -k <name of test>
 
 
   .. note::
 
-      System tests are only configured to run under Python 3.8, 3.9, 3.11 and 3.12.
+      System tests are only configured to run under Python 3.8, 3.11, 3.12 and 3.13.
       For expediency, we do not run them in older versions of Python 3.
 
   This alone will not run the tests. You'll need to change some local
@@ -226,12 +226,14 @@ We support:
 -  `Python 3.9`_
 -  `Python 3.11`_
 -  `Python 3.12`_
+-  `Python 3.13`_
 
 .. _Python 3.7: https://docs.python.org/3.7/
 .. _Python 3.8: https://docs.python.org/3.8/
 .. _Python 3.9: https://docs.python.org/3.9/
 .. _Python 3.11: https://docs.python.org/3.11/
 .. _Python 3.12: https://docs.python.org/3.12/
+.. _Python 3.13: https://docs.python.org/3.13/
 
 
 Supported versions can be found in our ``noxfile.py`` `config`_.

README.rst

@@ -101,3 +101,15 @@ Perform a query
     GROUP BY name
     ORDER BY count DESC
     LIMIT 3
+
+Since BigQuery supports Python via BigQuery DataFrames, `%%bqsql` is offered as
+an alias to clarify the language of these cells.
+
+.. code:: python
+
+    %%bqsql
+    SELECT name, SUM(number) as count
+    FROM 'bigquery-public-data.usa_names.usa_1910_current'
+    GROUP BY name
+    ORDER BY count DESC
+    LIMIT 3

bigquery_magics/__init__.py

@@ -27,6 +27,7 @@ def load_ipython_extension(ipython):
     ipython.register_magic_function(
         _cell_magic, magic_kind="cell", magic_name="bigquery"
     )
+    ipython.register_magic_function(_cell_magic, magic_kind="cell", magic_name="bqsql")
 
 
 __all__ = (

bigquery_magics/bigquery.py

@@ -14,13 +14,13 @@
 
 """IPython Magics
 
-.. function:: %%bigquery
+.. function:: ``%%bigquery`` or ``%%bqsql``
 
     IPython cell magic to run a query and display the result as a DataFrame
 
     .. code-block:: python
 
-        %%bigquery [<destination_var>] [--project <project>] [--use_legacy_sql]
+        %%bqsql [<destination_var>] [--project <project>] [--use_legacy_sql]
                    [--verbose] [--params <params>]
         <query>
 
@@ -30,7 +30,8 @@
         variable to store the query results. The results are not displayed if
         this parameter is used. If an error occurs during the query execution,
         the corresponding ``QueryJob`` instance (if available) is stored in
-        the variable instead.
+        the variable instead. Set ``bigquery_magics.context.default_variable``
+        to set a destination variable without specifying this argument.
     * ``--destination_table`` (Optional[line argument]):
         A dataset and table to store the query results. If table does not exists,
         it will be created. If table already exists, its data will be overwritten.
@@ -73,11 +74,12 @@
         fully-qualified table ID, and the latter's data will be fetched.
 
     Returns:
-        A :class:`pandas.DataFrame` with the query results.
+        A :class:`pandas.DataFrame` or :class:`bigframes.pandas.DataFrame`
+        with the query results, depending on the ``engine`` chosen.
 
     .. note::
         All queries run using this magic will run using the context
-        :attr:`~google.cloud.bigquery.magics.Context.credentials`.
+        :attr:`~bigquery_magics.config.Context.credentials`.
 """
 
 from __future__ import print_function
@@ -478,10 +480,7 @@ def _query_with_bigframes(query: str, params: List[Any], args: Any):
         configuration=_create_job_config(args, params).to_api_repr(),
     )
 
-    if args.destination_var:
-        get_ipython().push({args.destination_var: result})
-    else:
-        return result
+    return _handle_result(result, args)
 
 
 def _query_with_pandas(query: str, params: List[Any], args: Any):
@@ -545,6 +544,28 @@ def _create_clients(args: Any) -> Tuple[bigquery.Client, Any]:
     return bq_client, bqstorage_client
 
 
+def _handle_result(result, args):
+    """Determine the output of the cell, depending on options set.
+
+    If an explicit destination is set, that takes precedence. Write to that
+    variable and skip showing any results.
+
+    Otherwise, if there is a default variable set (such as if this module is
+    initialized by bigframes), then set that but also show the output.
+
+    Finally, there is no variable to save to, so just show the output.
+    """
+    if args.destination_var:
+        get_ipython().push({args.destination_var: result})
+        return None
+
+    if context.default_variable:
+        # If a default variable is set, save the result _and_ show the results.
+        get_ipython().push({context.default_variable: result})
+
+    return result
+
+
 def _make_bq_query(
     query: str,
     args: Any,
@@ -567,11 +588,7 @@ def _make_bq_query(
             bqstorage_client=bqstorage_client,
             create_bqstorage_client=False,
         )
-        if args.destination_var:
-            get_ipython().push({args.destination_var: result})
-            return
-        else:
-            return result
+        return _handle_result(result, args)
 
     job_config = _create_job_config(args, params)
     if args.destination_table:
@@ -599,6 +616,9 @@ def _make_bq_query(
         display.clear_output()
 
     if args.dry_run:
+        # TODO(tswast): Use _handle_result() here, too, but perhaps change the
+        # format to match the dry run schema from bigframes and pandas-gbq.
+        # See: https://github.com/googleapis/python-bigquery-pandas/issues/585
         if args.destination_var:
             get_ipython().push({args.destination_var: query_job})
             return
@@ -625,10 +645,7 @@ def _make_bq_query(
             progress_bar_type=progress_bar,
         )
 
-    if args.destination_var:
-        get_ipython().push({args.destination_var: result})
-    else:
-        return result
+    return _handle_result(result, args)
 
 
 def _validate_and_resolve_query(query: str, args: Any) -> str: