google-cloud-bigquery 3.42.3__tar.gz → 3.44.0__tar.gz

{google_cloud_bigquery-3.42.3/google_cloud_bigquery.egg-info → google_cloud_bigquery-3.44.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-cloud-bigquery
-Version: 3.42.3
+Version: 3.44.0
 Summary: Google BigQuery API client library
 Author-email: Google LLC <googleapis-packages@google.com>
 License: Apache 2.0
@@ -19,7 +19,7 @@ Classifier: Topic :: Internet
 Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE
-Requires-Dist: google-api-core[grpc]<3.0.0,>=2.25.0
+Requires-Dist: google-api-core[grpc]<3.0.0,>=2.28.0
 Requires-Dist: google-auth[pyopenssl]<3.0.0,>=2.14.1
 Requires-Dist: google-cloud-core<3.0.0,>=2.4.1
 Requires-Dist: google-resumable-media<3.0.0,>=2.0.0
@@ -85,6 +85,26 @@ processing power of Google's infrastructure.
 .. _Client Library Documentation: https://cloud.google.com/python/docs/reference/bigquery/latest/summary_overview
 .. _Product Documentation: https://cloud.google.com/bigquery/docs/reference/v2/
 
+
+Related Libraries
+-----------------
+
+For higher-level data analysis and DataFrame operations, consider using one of the following connector libraries:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Library
+     - Description
+     - Documentation
+   * - `BigQuery DataFrames (bigframes) <https://dataframes.bigquery.dev/>`_
+     - Flexible pandas-like and scikit-learn-like API powered by BigQuery engine for large-scale data analysis and ML.
+     - `BigFrames Docs <https://dataframes.bigquery.dev/>`_
+   * - `pandas-gbq <https://pandas-gbq.readthedocs.io/>`_
+     - Convenient integration allowing pandas DataFrames to load from and write to BigQuery.
+     - `pandas-gbq Docs <https://pandas-gbq.readthedocs.io/>`_
+
+
 Quick Start
 -----------
 

{google_cloud_bigquery-3.42.3 → google_cloud_bigquery-3.44.0}/README.rst

@@ -21,6 +21,26 @@ processing power of Google's infrastructure.
 .. _Client Library Documentation: https://cloud.google.com/python/docs/reference/bigquery/latest/summary_overview
 .. _Product Documentation: https://cloud.google.com/bigquery/docs/reference/v2/
 
+
+Related Libraries
+-----------------
+
+For higher-level data analysis and DataFrame operations, consider using one of the following connector libraries:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Library
+     - Description
+     - Documentation
+   * - `BigQuery DataFrames (bigframes) <https://dataframes.bigquery.dev/>`_
+     - Flexible pandas-like and scikit-learn-like API powered by BigQuery engine for large-scale data analysis and ML.
+     - `BigFrames Docs <https://dataframes.bigquery.dev/>`_
+   * - `pandas-gbq <https://pandas-gbq.readthedocs.io/>`_
+     - Convenient integration allowing pandas DataFrames to load from and write to BigQuery.
+     - `pandas-gbq Docs <https://pandas-gbq.readthedocs.io/>`_
+
+
 Quick Start
 -----------
 

{google_cloud_bigquery-3.42.3 → google_cloud_bigquery-3.44.0}/google/cloud/bigquery/__init__.py

@@ -30,6 +30,8 @@ The main concepts with this API are:
 import sys
 import warnings
 
+import google.api_core as api_core
+
 from google.cloud.bigquery import version as bigquery_version
 
 __version__ = bigquery_version.__version__
@@ -57,6 +59,8 @@ from google.cloud.bigquery.external_config import ExternalSourceFormat
 from google.cloud.bigquery.external_config import HivePartitioningOptions
 from google.cloud.bigquery.format_options import AvroOptions
 from google.cloud.bigquery.format_options import ParquetOptions
+from google.cloud.bigquery.enums import QueryResultsCompressionCodec
+from google.cloud.bigquery.enums import QueryResultsFormat
 from google.cloud.bigquery.job.base import SessionInfo
 from google.cloud.bigquery.job import Compression
 from google.cloud.bigquery.job import CopyJob
@@ -132,6 +136,9 @@ if sys.version_info < (3, 10):  # pragma: NO COVER
         FutureWarning,
     )
 
+api_core.check_python_version(__name__)
+api_core.check_dependency_versions(__name__)
+
 __all__ = [
     "__version__",
     "Client",
@@ -216,6 +223,8 @@ __all__ = [
     "KeyResultStatementKind",
     "OperationType",
     "QueryPriority",
+    "QueryResultsCompressionCodec",
+    "QueryResultsFormat",
     "RoutineType",
     "SchemaUpdateOption",
     "SourceFormat",

{google_cloud_bigquery-3.42.3 → google_cloud_bigquery-3.44.0}/google/cloud/bigquery/_helpers.py

@@ -295,7 +295,7 @@ class CellDataParser:
             return _date_from_iso8601_date(value)
 
     def time_to_py(self, value, field):
-        """Coerce 'value' to a datetime date, if set or not nullable"""
+        """Coerce 'value' to a datetime time, if set or not nullable"""
         if _not_null(value, field):
             if len(value) == 8:  # HH:MM:SS
                 fmt = _TIMEONLY_WO_MICROS

{google_cloud_bigquery-3.42.3 → google_cloud_bigquery-3.44.0}/google/cloud/bigquery/_job_helpers.py

@@ -430,6 +430,8 @@ def query_and_wait(
     job_retry: Optional[retries.Retry],
     page_size: Optional[int] = None,
     max_results: Optional[int] = None,
+    query_results_format: Optional[str] = None,
+    compression_codec: Optional[str] = None,
     callback: Callable = lambda _: None,
 ) -> table.RowIterator:
     """Run the query, wait for it to finish, and return the results.
@@ -475,6 +477,10 @@ def query_and_wait(
             request. Non-positive values are ignored.
         max_results (Optional[int]):
             The maximum total number of rows from this request.
+        query_results_format (Optional[Union[str, google.cloud.bigquery.enums.QueryResultsFormat]]):
+            [Beta] The format for query results (e.g. "ARROW" or :class:`~google.cloud.bigquery.enums.QueryResultsFormat.ARROW`).
+        compression_codec (Optional[Union[str, google.cloud.bigquery.enums.QueryResultsCompressionCodec]]):
+            [Beta] Compression codec for Arrow serialization (e.g. "LZ4_FRAME" or :class:`~google.cloud.bigquery.enums.QueryResultsCompressionCodec.LZ4_FRAME`).
         callback (Callable):
             A callback function used by bigframes to report query progress.
 
@@ -499,6 +505,13 @@ def query_and_wait(
     request_body = _to_query_request(
         query=query, job_config=job_config, location=location, timeout=api_timeout
     )
+    if query_results_format is not None:
+        request_body["queryResultsFormat"] = query_results_format
+    if compression_codec is not None:
+        request_body.setdefault("formatOptions", {})
+        request_body["formatOptions"]["arrowSerializationOptions"] = {
+            "bufferCompression": compression_codec
+        }
 
     # Some API parameters aren't supported by the jobs.query API. In these
     # cases, fallback to a jobs.insert call.
@@ -522,6 +535,7 @@ def query_and_wait(
             retry=retry,
             page_size=page_size,
             max_results=max_results,
+            query_results_format=query_results_format,
             callback=callback,
         )
 
@@ -594,6 +608,7 @@ def query_and_wait(
                 retry=retry,
                 page_size=page_size,
                 max_results=max_results,
+                query_results_format=query_results_format,
                 callback=callback,
             )
 
@@ -633,6 +648,7 @@ def query_and_wait(
             created=query_results.created,
             started=query_results.started,
             ended=query_results.ended,
+            query_results_format=query_results_format,
         )
 
     if job_retry is not None:
@@ -673,6 +689,7 @@ def _supported_by_jobs_query(request_body: Dict[str, Any]) -> bool:
         "jobTimeoutMs",
         "reservation",
         "maxSlots",
+        "queryResultsFormat",
     }
 
     unsupported_keys = request_keys - keys_allowlist
@@ -687,6 +704,7 @@ def _wait_or_cancel(
     page_size: Optional[int],
     max_results: Optional[int],
     *,
+    query_results_format: Optional[str] = None,
     callback: Callable = lambda _: None,
 ) -> table.RowIterator:
     """Wait for a job to complete and return the results.
@@ -731,6 +749,7 @@ def _wait_or_cancel(
                     ended=job.ended,
                 )
             )
+        query_results._query_results_format = query_results_format
         return query_results
     except Exception:
         # Attempt to cancel the job since we can't return the results.

{google_cloud_bigquery-3.42.3 → google_cloud_bigquery-3.44.0}/google/cloud/bigquery/_versions_helpers.py

@@ -16,10 +16,8 @@
 from typing import Any
 
 import packaging.version
-
 from google.cloud.bigquery import exceptions
 
-
 _MIN_PYARROW_VERSION = packaging.version.Version("3.0.0")
 _MIN_BQ_STORAGE_VERSION = packaging.version.Version("2.0.0")
 _BQ_STORAGE_OPTIONAL_READ_SESSION_VERSION = packaging.version.Version("2.6.0")
@@ -27,6 +25,7 @@ _MIN_PANDAS_VERSION = packaging.version.Version("1.1.0")
 
 _MIN_PANDAS_VERSION_RANGE = packaging.version.Version("1.5.0")
 _MIN_PYARROW_VERSION_RANGE = packaging.version.Version("10.0.1")
+_MIN_PANDAS_GBQ_DELEGATION_VERSION = packaging.version.Version("1.0.0")
 
 
 class PyarrowVersions:
@@ -247,3 +246,52 @@ SUPPORTS_RANGE_PYARROW = (
     and PYARROW_VERSIONS.try_import() is not None
     and PYARROW_VERSIONS.installed_version >= _MIN_PYARROW_VERSION_RANGE
 )
+
+
+class PandasGBQVersions:
+    """Version and delegation comparisons for pandas-gbq package."""
+
+    def __init__(self):
+        self._installed_version = None
+        self._delegation_api_version = None
+
+    @property
+    def installed_version(self) -> packaging.version.Version:
+        """Return the parsed version of pandas-gbq."""
+        if self._installed_version is not None:
+            return self._installed_version
+
+        try:
+            import pandas_gbq  # type: ignore
+
+            self._installed_version = packaging.version.parse(
+                getattr(pandas_gbq, "__version__", "0.0.0")
+            )
+        except Exception:
+            self._installed_version = packaging.version.parse("0.0.0")
+        return self._installed_version
+
+    @property
+    def delegation_api_version(self) -> packaging.version.Version:
+        """Return the delegation API version of pandas-gbq if installed, otherwise 0.0.0."""
+        if self._delegation_api_version is not None:
+            return self._delegation_api_version
+
+        try:
+            import pandas_gbq  # type: ignore
+
+            raw_version = getattr(
+                pandas_gbq, "_internal_delegation_api_version", "0.0.0"
+            )
+            self._delegation_api_version = packaging.version.parse(str(raw_version))
+        except Exception:
+            self._delegation_api_version = packaging.version.parse("0.0.0")
+        return self._delegation_api_version
+
+    @property
+    def is_delegation_supported(self) -> bool:
+        """True if the installed pandas-gbq version supports query delegation API."""
+        return self.delegation_api_version >= _MIN_PANDAS_GBQ_DELEGATION_VERSION
+
+
+PANDAS_GBQ_VERSIONS = PandasGBQVersions()

{google_cloud_bigquery-3.42.3 → google_cloud_bigquery-3.44.0}/google/cloud/bigquery/client.py

@@ -163,6 +163,16 @@ _LIST_ROWS_FROM_QUERY_RESULTS_FIELDS = "jobReference,totalRows,pageToken,rows"
 # https://github.com/googleapis/python-bigquery/issues/438
 _MIN_GET_QUERY_RESULTS_TIMEOUT = 120
 
+_LOAD_TABLE_FROM_DATAFRAME_DEPRECATED = (
+    "Loading DataFrames via google-cloud-bigquery is deprecated. "
+    "For direct, optimized loading, please call 'pandas_gbq.to_gbq()' directly."
+)
+
+_INSERT_ROWS_FROM_DATAFRAME_DEPRECATED = (
+    "Inserting rows from DataFrames via google-cloud-bigquery is deprecated. "
+    "For direct, optimized access, please call 'pandas_gbq.to_gbq()' directly."
+)
+
 TIMEOUT_HEADER = "X-Server-Timeout"
 
 
@@ -2830,6 +2840,12 @@ class Client(ClientWithProject):
                 If ``job_config`` is not an instance of
                 :class:`~google.cloud.bigquery.job.LoadJobConfig` class.
         """
+        warnings.warn(
+            _LOAD_TABLE_FROM_DATAFRAME_DEPRECATED,
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
+
         job_id = _make_job_id(job_id, job_id_prefix)
 
         if job_config is not None:
@@ -3649,6 +3665,8 @@ class Client(ClientWithProject):
         job_retry: retries.Retry = DEFAULT_JOB_RETRY,
         page_size: Optional[int] = None,
         max_results: Optional[int] = None,
+        query_results_format: Optional[str] = None,
+        compression_codec: Optional[str] = None,
     ) -> RowIterator:
         """Run the query, wait for it to finish, and return the results.
 
@@ -3696,6 +3714,10 @@ class Client(ClientWithProject):
                 by this parameter.
             max_results (Optional[int]):
                 The maximum total number of rows from this request.
+            query_results_format (Optional[Union[str, google.cloud.bigquery.enums.QueryResultsFormat]]):
+                [Beta] The format for query results (e.g. "ARROW" or :class:`~google.cloud.bigquery.enums.QueryResultsFormat.ARROW`).
+            compression_codec (Optional[Union[str, google.cloud.bigquery.enums.QueryResultsCompressionCodec]]):
+                [Beta] Compression codec for Arrow serialization (e.g. "LZ4_FRAME" or :class:`~google.cloud.bigquery.enums.QueryResultsCompressionCodec.LZ4_FRAME`).
 
         Returns:
             google.cloud.bigquery.table.RowIterator:
@@ -3726,6 +3748,8 @@ class Client(ClientWithProject):
             job_retry=job_retry,
             page_size=page_size,
             max_results=max_results,
+            query_results_format=query_results_format,
+            compression_codec=compression_codec,
         )
 
     def _query_and_wait_bigframes(
@@ -3741,6 +3765,8 @@ class Client(ClientWithProject):
         job_retry: retries.Retry = DEFAULT_JOB_RETRY,
         page_size: Optional[int] = None,
         max_results: Optional[int] = None,
+        query_results_format: Optional[str] = None,
+        compression_codec: Optional[str] = None,
         callback: Callable = lambda _: None,
     ) -> RowIterator:
         """See query_and_wait.
@@ -3773,6 +3799,8 @@ class Client(ClientWithProject):
             job_retry=job_retry,
             page_size=page_size,
             max_results=max_results,
+            query_results_format=query_results_format,
+            compression_codec=compression_codec,
             callback=callback,
         )
 
@@ -3900,6 +3928,12 @@ class Client(ClientWithProject):
         Raises:
             ValueError: if table's schema is not set
         """
+        warnings.warn(
+            _INSERT_ROWS_FROM_DATAFRAME_DEPRECATED,
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
+
         insert_results = []
 
         chunk_count = int(math.ceil(len(dataframe) / chunk_size))

{google_cloud_bigquery-3.42.3 → google_cloud_bigquery-3.44.0}/google/cloud/bigquery/dbapi/connection.py

@@ -78,10 +78,14 @@ class Connection(object):
         """
         self._closed = True
 
-        if self._owns_client:
+        for cursor_ in list(self._cursors_created):
+            if not cursor_._closed:
+                cursor_.close()
+
+        if self._owns_client and self._client is not None:
             self._client.close()
 
-        if self._owns_bqstorage_client:
+        if self._owns_bqstorage_client and self._bqstorage_client is not None:
             # There is no close() on the BQ Storage client itself.
             transport = self._bqstorage_client.transport
             transport.close()
@@ -95,10 +99,6 @@ class Connection(object):
             if channel is not None:
                 channel.close()
 
-        for cursor_ in self._cursors_created:
-            if not cursor_._closed:
-                cursor_.close()
-
     def commit(self):
         """No-op, but for consistency raise an error if connection is closed."""
 

{google_cloud_bigquery-3.42.3 → google_cloud_bigquery-3.44.0}/google/cloud/bigquery/enums.py

@@ -495,3 +495,20 @@ class TimestampPrecision(enum.Enum):
     """
     For TIMESTAMP type with picosecond precision.
     """
+
+
+class QueryResultsFormat(str, enum.Enum):
+    """[Beta] Format for query results response."""
+
+    ARROW = "ARROW"
+    """Specifies Apache Arrow format for query results."""
+
+
+class QueryResultsCompressionCodec(str, enum.Enum):
+    """[Beta] Compression codec for Arrow query results serialization."""
+
+    LZ4_FRAME = "LZ4_FRAME"
+    """Specifies LZ4_FRAME compression codec."""
+
+    ZSTD = "ZSTD"
+    """Specifies ZSTD compression codec."""

{google_cloud_bigquery-3.42.3 → google_cloud_bigquery-3.44.0}/google/cloud/bigquery/query.py

@@ -1020,7 +1020,6 @@ class RangeQueryParameter(_AbstractQueryParameter):
     ):
         self.name = name
         self.range_element_type = self._parse_range_element_type(range_element_type)
-        print(self.range_element_type.type_._type)
         self.start = start
         self.end = end