google-cloud-bigquery 3.25.0__tar.gz → 3.27.0__tar.gz

{google-cloud-bigquery-3.25.0 → google_cloud_bigquery-3.27.0}/MANIFEST.in

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# Copyright 2023 Google LLC
+# Copyright 2024 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

{google-cloud-bigquery-3.25.0/google_cloud_bigquery.egg-info → google_cloud_bigquery-3.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: google-cloud-bigquery
-Version: 3.25.0
+Version: 3.27.0
 Summary: Google BigQuery API client library
 Home-page: https://github.com/googleapis/python-bigquery
 Author: Google LLC
@@ -22,12 +22,12 @@ Classifier: Operating System :: OS Independent
 Classifier: Topic :: Internet
 Requires-Python: >=3.7
 License-File: LICENSE
-Requires-Dist: google-api-core[grpc]!=2.0.*,!=2.1.*,!=2.10.*,!=2.2.*,!=2.3.*,!=2.4.*,!=2.5.*,!=2.6.*,!=2.7.*,!=2.8.*,!=2.9.*,<3.0.0dev,>=1.34.1
+Requires-Dist: google-api-core[grpc]<3.0.0dev,>=2.11.1
 Requires-Dist: google-auth<3.0.0dev,>=2.14.1
-Requires-Dist: google-cloud-core<3.0.0dev,>=1.6.0
-Requires-Dist: google-resumable-media<3.0dev,>=0.6.0
+Requires-Dist: google-cloud-core<3.0.0dev,>=2.4.1
+Requires-Dist: google-resumable-media<3.0dev,>=2.0.0
 Requires-Dist: packaging>=20.0.0
-Requires-Dist: python-dateutil<3.0dev,>=2.7.2
+Requires-Dist: python-dateutil<3.0dev,>=2.7.3
 Requires-Dist: requests<3.0.0dev,>=2.21.0
 Provides-Extra: bqstorage
 Requires-Dist: google-cloud-bigquery-storage<3.0.0dev,>=2.6.0; extra == "bqstorage"
@@ -46,8 +46,7 @@ Provides-Extra: geopandas
 Requires-Dist: geopandas<1.0dev,>=0.9.0; extra == "geopandas"
 Requires-Dist: Shapely<3.0.0dev,>=1.8.4; extra == "geopandas"
 Provides-Extra: ipython
-Requires-Dist: ipython!=8.1.0,>=7.23.1; extra == "ipython"
-Requires-Dist: ipykernel>=6.0.0; extra == "ipython"
+Requires-Dist: bigquery-magics>=0.1.0; extra == "ipython"
 Provides-Extra: tqdm
 Requires-Dist: tqdm<5.0.0dev,>=4.7.4; extra == "tqdm"
 Provides-Extra: opentelemetry
@@ -55,8 +54,8 @@ Requires-Dist: opentelemetry-api>=1.1.0; extra == "opentelemetry"
 Requires-Dist: opentelemetry-sdk>=1.1.0; extra == "opentelemetry"
 Requires-Dist: opentelemetry-instrumentation>=0.20b0; extra == "opentelemetry"
 Provides-Extra: bigquery-v2
-Requires-Dist: proto-plus<2.0.0dev,>=1.15.0; extra == "bigquery-v2"
-Requires-Dist: protobuf!=3.20.0,!=3.20.1,!=4.21.0,!=4.21.1,!=4.21.2,!=4.21.3,!=4.21.4,!=4.21.5,<5.0.0dev,>=3.19.5; extra == "bigquery-v2"
+Requires-Dist: proto-plus<2.0.0dev,>=1.22.3; extra == "bigquery-v2"
+Requires-Dist: protobuf!=4.21.0,!=4.21.1,!=4.21.2,!=4.21.3,!=4.21.4,!=4.21.5,<6.0.0dev,>=3.20.2; extra == "bigquery-v2"
 Provides-Extra: all
 Requires-Dist: google-cloud-bigquery-storage<3.0.0dev,>=2.6.0; extra == "all"
 Requires-Dist: grpcio<2.0dev,>=1.47.0; extra == "all"
@@ -70,14 +69,13 @@ Requires-Dist: ipywidgets>=7.7.0; extra == "all"
 Requires-Dist: ipykernel>=6.0.0; extra == "all"
 Requires-Dist: geopandas<1.0dev,>=0.9.0; extra == "all"
 Requires-Dist: Shapely<3.0.0dev,>=1.8.4; extra == "all"
-Requires-Dist: ipython!=8.1.0,>=7.23.1; extra == "all"
-Requires-Dist: ipykernel>=6.0.0; extra == "all"
+Requires-Dist: bigquery-magics>=0.1.0; extra == "all"
 Requires-Dist: tqdm<5.0.0dev,>=4.7.4; extra == "all"
 Requires-Dist: opentelemetry-api>=1.1.0; extra == "all"
 Requires-Dist: opentelemetry-sdk>=1.1.0; extra == "all"
 Requires-Dist: opentelemetry-instrumentation>=0.20b0; extra == "all"
-Requires-Dist: proto-plus<2.0.0dev,>=1.15.0; extra == "all"
-Requires-Dist: protobuf!=3.20.0,!=3.20.1,!=4.21.0,!=4.21.1,!=4.21.2,!=4.21.3,!=4.21.4,!=4.21.5,<5.0.0dev,>=3.19.5; extra == "all"
+Requires-Dist: proto-plus<2.0.0dev,>=1.22.3; extra == "all"
+Requires-Dist: protobuf!=4.21.0,!=4.21.1,!=4.21.2,!=4.21.3,!=4.21.4,!=4.21.5,<6.0.0dev,>=3.20.2; extra == "all"
 
 Python Client for Google BigQuery
 =================================

{google-cloud-bigquery-3.25.0 → google_cloud_bigquery-3.27.0}/google/cloud/bigquery/__init__.py

@@ -27,6 +27,7 @@ The main concepts with this API are:
 - :class:`~google.cloud.bigquery.table.Table` represents a single "relation".
 """
 
+import warnings
 
 from google.cloud.bigquery import version as bigquery_version
 
@@ -43,6 +44,7 @@ from google.cloud.bigquery.enums import KeyResultStatementKind
 from google.cloud.bigquery.enums import SqlTypeNames
 from google.cloud.bigquery.enums import StandardSqlTypeNames
 from google.cloud.bigquery.exceptions import LegacyBigQueryStorageError
+from google.cloud.bigquery.exceptions import LegacyPandasError
 from google.cloud.bigquery.exceptions import LegacyPyarrowError
 from google.cloud.bigquery.external_config import ExternalConfig
 from google.cloud.bigquery.external_config import BigtableOptions
@@ -113,6 +115,24 @@ from google.cloud.bigquery.table import TableReference
 from google.cloud.bigquery.table import TimePartitioningType
 from google.cloud.bigquery.table import TimePartitioning
 from google.cloud.bigquery.encryption_configuration import EncryptionConfiguration
+from google.cloud.bigquery import _versions_helpers
+
+try:
+    import bigquery_magics  # type: ignore
+except ImportError:
+    bigquery_magics = None
+
+sys_major, sys_minor, sys_micro = _versions_helpers.extract_runtime_version()
+
+if sys_major == 3 and sys_minor in (7, 8):
+    warnings.warn(
+        "The python-bigquery library will stop supporting Python 3.7 "
+        "and Python 3.8 in a future major release expected in Q4 2024. "
+        f"Your Python version is {sys_major}.{sys_minor}.{sys_micro}. We "
+        "recommend that you update soon to ensure ongoing support. For "
+        "more details, see: [Google Cloud Client Libraries Supported Python Versions policy](https://cloud.google.com/python/docs/supported-python-versions)",
+        PendingDeprecationWarning,
+    )
 
 __all__ = [
     "__version__",
@@ -214,8 +234,16 @@ __all__ = [
 
 def load_ipython_extension(ipython):
     """Called by IPython when this module is loaded as an IPython extension."""
-    from google.cloud.bigquery.magics.magics import _cell_magic
-
-    ipython.register_magic_function(
-        _cell_magic, magic_kind="cell", magic_name="bigquery"
+    warnings.warn(
+        "%load_ext google.cloud.bigquery is deprecated. Install bigquery-magics package and use `%load_ext bigquery_magics`, instead.",
+        category=FutureWarning,
     )
+
+    if bigquery_magics is not None:
+        bigquery_magics.load_ipython_extension(ipython)
+    else:
+        from google.cloud.bigquery.magics.magics import _cell_magic
+
+        ipython.register_magic_function(
+            _cell_magic, magic_kind="cell", magic_name="bigquery"
+        )

{google-cloud-bigquery-3.25.0 → google_cloud_bigquery-3.27.0}/google/cloud/bigquery/_helpers.py

@@ -21,6 +21,7 @@ import json
 import math
 import re
 import os
+import warnings
 from typing import Optional, Union
 
 from dateutil import relativedelta
@@ -297,12 +298,7 @@ def _record_from_json(value, field):
         record = {}
         record_iter = zip(field.fields, value["f"])
         for subfield, cell in record_iter:
-            converter = _CELLDATA_FROM_JSON[subfield.field_type]
-            if subfield.mode == "REPEATED":
-                value = [converter(item["v"], subfield) for item in cell["v"]]
-            else:
-                value = converter(cell["v"], subfield)
-            record[subfield.name] = value
+            record[subfield.name] = _field_from_json(cell["v"], subfield)
         return record
 
 
@@ -382,7 +378,11 @@ def _field_to_index_mapping(schema):
 
 
 def _field_from_json(resource, field):
-    converter = _CELLDATA_FROM_JSON.get(field.field_type, lambda value, _: value)
+    def default_converter(value, field):
+        _warn_unknown_field_type(field)
+        return value
+
+    converter = _CELLDATA_FROM_JSON.get(field.field_type, default_converter)
     if field.mode == "REPEATED":
         return [converter(item["v"], field) for item in resource]
     else:
@@ -484,6 +484,11 @@ def _json_to_json(value):
     return json.dumps(value)
 
 
+def _string_to_json(value):
+    """NOOP string -> string coercion"""
+    return value
+
+
 def _timestamp_to_json_parameter(value):
     """Coerce 'value' to an JSON-compatible representation.
 
@@ -596,6 +601,7 @@ _SCALAR_VALUE_TO_JSON_ROW = {
     "DATE": _date_to_json,
     "TIME": _time_to_json,
     "JSON": _json_to_json,
+    "STRING": _string_to_json,
     # Make sure DECIMAL and BIGDECIMAL are handled, even though
     # requests for them should be converted to NUMERIC.  Better safe
     # than sorry.
@@ -609,6 +615,15 @@ _SCALAR_VALUE_TO_JSON_PARAM = _SCALAR_VALUE_TO_JSON_ROW.copy()
 _SCALAR_VALUE_TO_JSON_PARAM["TIMESTAMP"] = _timestamp_to_json_parameter
 
 
+def _warn_unknown_field_type(field):
+    warnings.warn(
+        "Unknown type '{}' for field '{}'. Behavior reading and writing this type is not officially supported and may change in the future.".format(
+            field.field_type, field.name
+        ),
+        FutureWarning,
+    )
+
+
 def _scalar_field_to_json(field, row_value):
     """Maps a field and value to a JSON-safe value.
 
@@ -621,9 +636,12 @@ def _scalar_field_to_json(field, row_value):
     Returns:
         Any: A JSON-serializable object.
     """
-    converter = _SCALAR_VALUE_TO_JSON_ROW.get(field.field_type)
-    if converter is None:  # STRING doesn't need converting
-        return row_value
+
+    def default_converter(value):
+        _warn_unknown_field_type(field)
+        return value
+
+    converter = _SCALAR_VALUE_TO_JSON_ROW.get(field.field_type, default_converter)
     return converter(row_value)
 
 

{google-cloud-bigquery-3.25.0 → google_cloud_bigquery-3.27.0}/google/cloud/bigquery/_pandas_helpers.py

@@ -21,13 +21,14 @@ from itertools import islice
 import logging
 import queue
 import warnings
-from typing import Any, Union
+from typing import Any, Union, Optional, Callable, Generator, List
 
 
 from google.cloud.bigquery import _pyarrow_helpers
 from google.cloud.bigquery import _versions_helpers
 from google.cloud.bigquery import schema
 
+
 try:
     import pandas  # type: ignore
 
@@ -75,7 +76,7 @@ else:
         _to_wkb = _to_wkb()
 
 try:
-    from google.cloud.bigquery_storage import ArrowSerializationOptions
+    from google.cloud.bigquery_storage_v1.types import ArrowSerializationOptions
 except ImportError:
     _ARROW_COMPRESSION_SUPPORT = False
 else:
@@ -200,11 +201,13 @@ def bq_to_arrow_field(bq_field, array_type=None):
             # local NULL values. Arrow will gladly interpret these NULL values
             # as non-NULL and give you an arbitrary value. See:
             # https://github.com/googleapis/python-bigquery/issues/1692
-            nullable=True,
+            nullable=False if bq_field.mode.upper() == "REPEATED" else True,
             metadata=metadata,
         )
 
-    warnings.warn("Unable to determine type for field '{}'.".format(bq_field.name))
+    warnings.warn(
+        "Unable to determine Arrow type for field '{}'.".format(bq_field.name)
+    )
     return None
 
 
@@ -814,18 +817,54 @@ def _nowait(futures):
 
 
 def _download_table_bqstorage(
-    project_id,
-    table,
-    bqstorage_client,
-    preserve_order=False,
-    selected_fields=None,
-    page_to_item=None,
-    max_queue_size=_MAX_QUEUE_SIZE_DEFAULT,
-):
-    """Use (faster, but billable) BQ Storage API to construct DataFrame."""
+    project_id: str,
+    table: Any,
+    bqstorage_client: Any,
+    preserve_order: bool = False,
+    selected_fields: Optional[List[Any]] = None,
+    page_to_item: Optional[Callable] = None,
+    max_queue_size: Any = _MAX_QUEUE_SIZE_DEFAULT,
+    max_stream_count: Optional[int] = None,
+) -> Generator[Any, None, None]:
+    """Downloads a BigQuery table using the BigQuery Storage API.
+
+    This method uses the faster, but potentially more expensive, BigQuery
+    Storage API to download a table as a Pandas DataFrame. It supports
+    parallel downloads and optional data transformations.
+
+    Args:
+        project_id (str): The ID of the Google Cloud project containing
+            the table.
+        table (Any): The BigQuery table to download.
+        bqstorage_client (Any): An
+            authenticated BigQuery Storage API client.
+        preserve_order (bool, optional): Whether to preserve the order
+            of the rows as they are read from BigQuery. If True this limits
+            the number of streams to one and overrides `max_stream_count`.
+            Defaults to False.
+        selected_fields (Optional[List[SchemaField]]):
+            A list of BigQuery schema fields to select for download. If None,
+            all fields are downloaded. Defaults to None.
+        page_to_item (Optional[Callable]): An optional callable
+            function that takes a page of data from the BigQuery Storage API
+        max_stream_count (Optional[int]): The maximum number of
+            concurrent streams to use for downloading data. If `preserve_order`
+            is True, the requested streams are limited to 1 regardless of the
+            `max_stream_count` value. If 0 or None, then the number of
+            requested streams will be unbounded. Defaults to None.
+
+    Yields:
+        pandas.DataFrame: Pandas DataFrames, one for each chunk of data
+            downloaded from BigQuery.
+
+    Raises:
+        ValueError: If attempting to read from a specific partition or snapshot.
+
+    Note:
+        This method requires the `google-cloud-bigquery-storage` library
+        to be installed.
+    """
 
-    # Passing a BQ Storage client in implies that the BigQuery Storage library
-    # is available and can be imported.
     from google.cloud import bigquery_storage
 
     if "$" in table.table_id:
@@ -835,10 +874,11 @@ def _download_table_bqstorage(
     if "@" in table.table_id:
         raise ValueError("Reading from a specific snapshot is not currently supported.")
 
-    requested_streams = 1 if preserve_order else 0
+    requested_streams = determine_requested_streams(preserve_order, max_stream_count)
 
-    requested_session = bigquery_storage.types.ReadSession(
-        table=table.to_bqstorage(), data_format=bigquery_storage.types.DataFormat.ARROW
+    requested_session = bigquery_storage.types.stream.ReadSession(
+        table=table.to_bqstorage(),
+        data_format=bigquery_storage.types.stream.DataFormat.ARROW,
     )
     if selected_fields is not None:
         for field in selected_fields:
@@ -846,7 +886,8 @@ def _download_table_bqstorage(
 
     if _ARROW_COMPRESSION_SUPPORT:
         requested_session.read_options.arrow_serialization_options.buffer_compression = (
-            ArrowSerializationOptions.CompressionCodec.LZ4_FRAME
+            # CompressionCodec(1) -> LZ4_FRAME
+            ArrowSerializationOptions.CompressionCodec(1)
         )
 
     session = bqstorage_client.create_read_session(
@@ -882,7 +923,7 @@ def _download_table_bqstorage(
     elif max_queue_size is None:
         max_queue_size = 0  # unbounded
 
-    worker_queue = queue.Queue(maxsize=max_queue_size)
+    worker_queue: queue.Queue[int] = queue.Queue(maxsize=max_queue_size)
 
     with concurrent.futures.ThreadPoolExecutor(max_workers=total_streams) as pool:
         try:
@@ -908,7 +949,7 @@ def _download_table_bqstorage(
                 # we want to block on the queue's get method, instead. This
                 # prevents the queue from filling up, because the main thread
                 # has smaller gaps in time between calls to the queue's get
-                # method. For a detailed explaination, see:
+                # method. For a detailed explanation, see:
                 # https://friendliness.dev/2019/06/18/python-nowait/
                 done, not_done = _nowait(not_done)
                 for future in done:
@@ -947,6 +988,7 @@ def download_arrow_bqstorage(
     preserve_order=False,
     selected_fields=None,
     max_queue_size=_MAX_QUEUE_SIZE_DEFAULT,
+    max_stream_count=None,
 ):
     return _download_table_bqstorage(
         project_id,
@@ -956,6 +998,7 @@ def download_arrow_bqstorage(
         selected_fields=selected_fields,
         page_to_item=_bqstorage_page_to_arrow,
         max_queue_size=max_queue_size,
+        max_stream_count=max_stream_count,
     )
 
 
@@ -968,6 +1011,7 @@ def download_dataframe_bqstorage(
     preserve_order=False,
     selected_fields=None,
     max_queue_size=_MAX_QUEUE_SIZE_DEFAULT,
+    max_stream_count=None,
 ):
     page_to_item = functools.partial(_bqstorage_page_to_dataframe, column_names, dtypes)
     return _download_table_bqstorage(
@@ -978,6 +1022,7 @@ def download_dataframe_bqstorage(
         selected_fields=selected_fields,
         page_to_item=page_to_item,
         max_queue_size=max_queue_size,
+        max_stream_count=max_stream_count,
     )
 
 
@@ -1022,3 +1067,40 @@ def verify_pandas_imports():
         raise ValueError(_NO_PANDAS_ERROR) from pandas_import_exception
     if db_dtypes is None:
         raise ValueError(_NO_DB_TYPES_ERROR) from db_dtypes_import_exception
+
+
+def determine_requested_streams(
+    preserve_order: bool,
+    max_stream_count: Union[int, None],
+) -> int:
+    """Determines the value of requested_streams based on the values of
+    `preserve_order` and `max_stream_count`.
+
+    Args:
+        preserve_order (bool): Whether to preserve the order of streams. If True,
+            this limits the number of streams to one. `preserve_order` takes
+            precedence over `max_stream_count`.
+        max_stream_count (Union[int, None]]): The maximum number of streams
+            allowed. Must be a non-negative number or None, where None indicates
+            the value is unset. NOTE: if `preserve_order` is also set, it takes
+            precedence over `max_stream_count`, thus to ensure that `max_stream_count`
+            is used, ensure that `preserve_order` is None.
+
+    Returns:
+        (int) The appropriate value for requested_streams.
+    """
+
+    if preserve_order:
+        # If preserve order is set, it takes precendence.
+        # Limit the requested streams to 1, to ensure that order
+        # is preserved)
+        return 1
+
+    elif max_stream_count is not None:
+        # If preserve_order is not set, only then do we consider max_stream_count
+        if max_stream_count <= -1:
+            raise ValueError("max_stream_count must be non-negative OR None")
+        return max_stream_count
+
+    # Default to zero requested streams (unbounded).
+    return 0

{google-cloud-bigquery-3.25.0 → google_cloud_bigquery-3.27.0}/google/cloud/bigquery/_versions_helpers.py

@@ -14,6 +14,7 @@
 
 """Shared helper functions for verifying versions of installed modules."""
 
+import sys
 from typing import Any
 
 import packaging.version
@@ -248,3 +249,16 @@ SUPPORTS_RANGE_PYARROW = (
     and PYARROW_VERSIONS.try_import() is not None
     and PYARROW_VERSIONS.installed_version >= _MIN_PYARROW_VERSION_RANGE
 )
+
+
+def extract_runtime_version():
+    # Retrieve the version information
+    version_info = sys.version_info
+
+    # Extract the major, minor, and micro components
+    major = version_info.major
+    minor = version_info.minor
+    micro = version_info.micro
+
+    # Display the version number in a clear format
+    return major, minor, micro

{google-cloud-bigquery-3.25.0 → google_cloud_bigquery-3.27.0}/google/cloud/bigquery/client.py

@@ -328,6 +328,15 @@ class Client(ClientWithProject):
     ) -> str:
         """Get the email address of the project's BigQuery service account
 
+        Example:
+
+        .. code-block:: python
+
+            from google.cloud import bigquery
+            client = bigquery.Client()
+            client.get_service_account_email()
+            # returns an email similar to: my_service_account@my-project.iam.gserviceaccount.com
+
         Note:
             This is the service account that BigQuery uses to manage tables
             encrypted by a key in KMS.
@@ -345,13 +354,6 @@ class Client(ClientWithProject):
             str:
                 service account email address
 
-        Example:
-
-            >>> from google.cloud import bigquery
-            >>> client = bigquery.Client()
-            >>> client.get_service_account_email()
-            my_service_account@my-project.iam.gserviceaccount.com
-
         """
         if project is None:
             project = self.project
@@ -629,9 +631,19 @@ class Client(ClientWithProject):
     ) -> Dataset:
         """API call: create the dataset via a POST request.
 
+
         See
         https://cloud.google.com/bigquery/docs/reference/rest/v2/datasets/insert
 
+        Example:
+
+        .. code-block:: python
+
+            from google.cloud import bigquery
+            client = bigquery.Client()
+            dataset = bigquery.Dataset('my_project.my_dataset')
+            dataset = client.create_dataset(dataset)
+
         Args:
             dataset (Union[ \
                 google.cloud.bigquery.dataset.Dataset, \
@@ -658,14 +670,6 @@ class Client(ClientWithProject):
         Raises:
             google.cloud.exceptions.Conflict:
                 If the dataset already exists.
-
-        Example:
-
-            >>> from google.cloud import bigquery
-            >>> client = bigquery.Client()
-            >>> dataset = bigquery.Dataset('my_project.my_dataset')
-            >>> dataset = client.create_dataset(dataset)
-
         """
         dataset = self._dataset_from_arg(dataset)
         if isinstance(dataset, DatasetReference):

{google-cloud-bigquery-3.25.0 → google_cloud_bigquery-3.27.0}/google/cloud/bigquery/job/base.py

@@ -49,7 +49,7 @@ _ERROR_REASON_TO_EXCEPTION = {
     "notImplemented": http.client.NOT_IMPLEMENTED,
     "policyViolation": http.client.FORBIDDEN,
     "quotaExceeded": http.client.FORBIDDEN,
-    "rateLimitExceeded": http.client.FORBIDDEN,
+    "rateLimitExceeded": http.client.TOO_MANY_REQUESTS,
     "resourceInUse": http.client.BAD_REQUEST,
     "resourcesExceeded": http.client.BAD_REQUEST,
     "responseTooLarge": http.client.FORBIDDEN,
@@ -218,8 +218,11 @@ class _JobConfig(object):
                 err.__traceback__
             )
 
-        """ Docs indicate a string is expected by the API """
-        self._properties["jobTimeoutMs"] = str(value)
+        if value is not None:
+            # docs indicate a string is expected by the API
+            self._properties["jobTimeoutMs"] = str(value)
+        else:
+            self._properties.pop("jobTimeoutMs", None)
 
     @property
     def labels(self):

{google-cloud-bigquery-3.25.0 → google_cloud_bigquery-3.27.0}/google/cloud/bigquery/job/query.py

@@ -476,6 +476,11 @@ class QueryJobConfig(_JobConfig):
           ID, each separated by ``.``. For example:
           ``your-project.your_dataset.your_table``.
 
+        .. note::
+
+            Only table ID is passed to the backend, so any configuration
+            in `~google.cloud.bigquery.table.Table` is discarded.
+
         See
         https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationQuery.FIELDS.destination_table
         """

{google-cloud-bigquery-3.25.0 → google_cloud_bigquery-3.27.0}/google/cloud/bigquery/magics/magics.py

@@ -14,70 +14,11 @@
 
 """IPython Magics
 
-.. function:: %%bigquery
-
-    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]
-                   [--verbose] [--params <params>]
-        <query>
-
-    Parameters:
-
-    * ``<destination_var>`` (Optional[line argument]):
-        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.
-    * ``--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.
-        Variable should be in a format <dataset_id>.<table_id>.
-    * ``--no_query_cache`` (Optional[line argument]):
-        Do not use cached query results.
-    * ``--project <project>`` (Optional[line argument]):
-        Project to use for running the query. Defaults to the context
-        :attr:`~google.cloud.bigquery.magics.Context.project`.
-    * ``--use_bqstorage_api`` (Optional[line argument]):
-        [Deprecated] Not used anymore, as BigQuery Storage API is used by default.
-    * ``--use_rest_api`` (Optional[line argument]):
-        Use the BigQuery REST API instead of the Storage API.
-    * ``--use_legacy_sql`` (Optional[line argument]):
-        Runs the query using Legacy SQL syntax. Defaults to Standard SQL if
-        this argument not used.
-    * ``--verbose`` (Optional[line argument]):
-        If this flag is used, information including the query job ID and the
-        amount of time for the query to complete will not be cleared after the
-        query is finished. By default, this information will be displayed but
-        will be cleared after the query is finished.
-    * ``--params <params>`` (Optional[line argument]):
-        If present, the argument following the ``--params`` flag must be
-        either:
-
-        * :class:`str` - A JSON string representation of a dictionary in the
-          format ``{"param_name": "param_value"}`` (ex. ``{"num": 17}``). Use
-          of the parameter in the query should be indicated with
-          ``@param_name``. See ``In[5]`` in the Examples section below.
-
-        * :class:`dict` reference - A reference to a ``dict`` in the format
-          ``{"param_name": "param_value"}``, where the value types must be JSON
-          serializable. The variable reference is indicated by a ``$`` before
-          the variable name (ex. ``$my_dict_var``). See ``In[6]`` and ``In[7]``
-          in the Examples section below.
-
-    * ``<query>`` (required, cell argument):
-        SQL query to run. If the query does not contain any whitespace (aside
-        from leading and trailing whitespace), it is assumed to represent a
-        fully-qualified table ID, and the latter's data will be fetched.
+Install ``bigquery-magics`` and call ``%load_ext bigquery_magics`` to use the
+``%%bigquery`` cell magic.
 
-    Returns:
-        A :class:`pandas.DataFrame` with the query results.
-
-    .. note::
-        All queries run using this magic will run using the context
-        :attr:`~google.cloud.bigquery.magics.Context.credentials`.
+See the `BigQuery Magics reference documentation
+<https://googleapis.dev/python/bigquery-magics/latest/>`_.
 """
 
 from __future__ import print_function
@@ -109,6 +50,11 @@ from google.cloud.bigquery import exceptions
 from google.cloud.bigquery.dbapi import _helpers
 from google.cloud.bigquery.magics import line_arg_parser as lap
 
+try:
+    import bigquery_magics  # type: ignore
+except ImportError:
+    bigquery_magics = None
+
 
 IPYTHON_USER_AGENT = "ipython-{}".format(IPython.__version__)
 
@@ -280,7 +226,14 @@ class Context(object):
         self._progress_bar_type = value
 
 
-context = Context()
+# If bigquery_magics is available, we load that extension rather than this one.
+# Ensure google.cloud.bigquery.magics.context setters are on the correct magics
+# implementation in case the user has installed the package but hasn't updated
+# their code.
+if bigquery_magics is not None:
+    context = bigquery_magics.context
+else:
+    context = Context()
 
 
 def _handle_error(error, destination_var=None):