google-cloud-bigquery 3.34.0__tar.gz → 3.35.0__tar.gz

{google_cloud_bigquery-3.34.0/google_cloud_bigquery.egg-info → google_cloud_bigquery-3.35.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: google-cloud-bigquery
-Version: 3.34.0
+Version: 3.35.0
 Summary: Google BigQuery API client library
 Author-email: Google LLC <googleapis-packages@google.com>
 License: Apache 2.0
@@ -62,6 +62,7 @@ Requires-Dist: proto-plus<2.0.0,>=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,<7.0.0,>=3.20.2; extra == "bigquery-v2"
 Provides-Extra: all
 Requires-Dist: google-cloud-bigquery[bigquery_v2,bqstorage,geopandas,ipython,ipywidgets,matplotlib,opentelemetry,pandas,tqdm]; extra == "all"
+Dynamic: license-file
 
 Python Client for Google BigQuery
 =================================

{google_cloud_bigquery-3.34.0 → google_cloud_bigquery-3.35.0}/google/cloud/bigquery/_job_helpers.py

@@ -560,6 +560,7 @@ def query_and_wait(
             num_dml_affected_rows=query_results.num_dml_affected_rows,
             query=query,
             total_bytes_processed=query_results.total_bytes_processed,
+            slot_millis=query_results.slot_millis,
         )
 
     if job_retry is not None:

{google_cloud_bigquery-3.34.0 → google_cloud_bigquery-3.35.0}/google/cloud/bigquery/_pandas_helpers.py

@@ -337,13 +337,8 @@ def default_types_mapper(
             ):
                 return range_date_dtype
 
-            # TODO: this section does not have a test yet OR at least not one that is
-            # recognized by coverage, hence the pragma. See Issue: #2132
-            elif (
-                range_timestamp_dtype is not None
-                and arrow_data_type.equals(  # pragma: NO COVER
-                    range_timestamp_dtype.pyarrow_dtype
-                )
+            elif range_timestamp_dtype is not None and arrow_data_type.equals(
+                range_timestamp_dtype.pyarrow_dtype
             ):
                 return range_timestamp_dtype
 

{google_cloud_bigquery-3.34.0 → google_cloud_bigquery-3.35.0}/google/cloud/bigquery/client.py

@@ -90,7 +90,8 @@ from google.cloud.bigquery._job_helpers import make_job_id as _make_job_id
 from google.cloud.bigquery.dataset import Dataset
 from google.cloud.bigquery.dataset import DatasetListItem
 from google.cloud.bigquery.dataset import DatasetReference
-from google.cloud.bigquery.enums import AutoRowIDs
+
+from google.cloud.bigquery.enums import AutoRowIDs, DatasetView, UpdateMode
 from google.cloud.bigquery.format_options import ParquetOptions
 from google.cloud.bigquery.job import (
     CopyJob,
@@ -864,6 +865,7 @@ class Client(ClientWithProject):
         dataset_ref: Union[DatasetReference, str],
         retry: retries.Retry = DEFAULT_RETRY,
         timeout: TimeoutType = DEFAULT_TIMEOUT,
+        dataset_view: Optional[DatasetView] = None,
     ) -> Dataset:
         """Fetch the dataset referenced by ``dataset_ref``
 
@@ -881,7 +883,21 @@ class Client(ClientWithProject):
             timeout (Optional[float]):
                 The number of seconds to wait for the underlying HTTP transport
                 before using ``retry``.
-
+            dataset_view (Optional[google.cloud.bigquery.enums.DatasetView]):
+                Specifies the view that determines which dataset information is
+                returned. By default, dataset metadata (e.g. friendlyName, description,
+                labels, etc) and ACL information are returned. This argument can
+                take on the following possible enum values.
+
+                * :attr:`~google.cloud.bigquery.enums.DatasetView.ACL`:
+                    Includes dataset metadata and the ACL.
+                * :attr:`~google.cloud.bigquery.enums.DatasetView.FULL`:
+                    Includes all dataset metadata, including the ACL and table metadata.
+                    This view is not supported by the `datasets.list` API method.
+                * :attr:`~google.cloud.bigquery.enums.DatasetView.METADATA`:
+                    Includes basic dataset metadata, but not the ACL.
+                * :attr:`~google.cloud.bigquery.enums.DatasetView.DATASET_VIEW_UNSPECIFIED`:
+                    The server will decide which view to use. Currently defaults to FULL.
         Returns:
             google.cloud.bigquery.dataset.Dataset:
                 A ``Dataset`` instance.
@@ -891,6 +907,12 @@ class Client(ClientWithProject):
                 dataset_ref, default_project=self.project
             )
         path = dataset_ref.path
+
+        if dataset_view:
+            query_params = {"datasetView": dataset_view.value}
+        else:
+            query_params = {}
+
         span_attributes = {"path": path}
         api_response = self._call_api(
             retry,
@@ -899,6 +921,7 @@ class Client(ClientWithProject):
             method="GET",
             path=path,
             timeout=timeout,
+            query_params=query_params,
         )
         return Dataset.from_api_repr(api_response)
 
@@ -1198,6 +1221,7 @@ class Client(ClientWithProject):
         fields: Sequence[str],
         retry: retries.Retry = DEFAULT_RETRY,
         timeout: TimeoutType = DEFAULT_TIMEOUT,
+        update_mode: Optional[UpdateMode] = None,
     ) -> Dataset:
         """Change some fields of a dataset.
 
@@ -1237,6 +1261,20 @@ class Client(ClientWithProject):
             timeout (Optional[float]):
                 The number of seconds to wait for the underlying HTTP transport
                 before using ``retry``.
+            update_mode (Optional[google.cloud.bigquery.enums.UpdateMode]):
+                Specifies the kind of information to update in a dataset.
+                By default, dataset metadata (e.g. friendlyName, description,
+                labels, etc) and ACL information are updated. This argument can
+                take on the following possible enum values.
+
+                * :attr:`~google.cloud.bigquery.enums.UPDATE_MODE_UNSPECIFIED`:
+                    The default value. Behavior defaults to UPDATE_FULL.
+                * :attr:`~google.cloud.bigquery.enums.UpdateMode.UPDATE_METADATA`:
+                    Includes metadata information for the dataset, such as friendlyName, description, labels, etc.
+                * :attr:`~google.cloud.bigquery.enums.UpdateMode.UPDATE_ACL`:
+                    Includes ACL information for the dataset, which defines dataset access for one or more entities.
+                * :attr:`~google.cloud.bigquery.enums.UpdateMode.UPDATE_FULL`:
+                    Includes both dataset metadata and ACL information.
 
         Returns:
             google.cloud.bigquery.dataset.Dataset:
@@ -1250,6 +1288,11 @@ class Client(ClientWithProject):
         path = dataset.path
         span_attributes = {"path": path, "fields": fields}
 
+        if update_mode:
+            query_params = {"updateMode": update_mode.value}
+        else:
+            query_params = {}
+
         api_response = self._call_api(
             retry,
             span_name="BigQuery.updateDataset",
@@ -1259,6 +1302,7 @@ class Client(ClientWithProject):
             data=partial,
             headers=headers,
             timeout=timeout,
+            query_params=query_params,
         )
         return Dataset.from_api_repr(api_response)
 
@@ -2001,6 +2045,7 @@ class Client(ClientWithProject):
         location: Optional[str] = None,
         timeout: TimeoutType = DEFAULT_TIMEOUT,
         page_size: int = 0,
+        start_index: Optional[int] = None,
     ) -> _QueryResults:
         """Get the query results object for a query job.
 
@@ -2019,9 +2064,12 @@ class Client(ClientWithProject):
                 before using ``retry``. If set, this connection timeout may be
                 increased to a minimum value. This prevents retries on what
                 would otherwise be a successful response.
-            page_size (int):
+            page_size (Optional[int]):
                 Maximum number of rows in a single response. See maxResults in
                 the jobs.getQueryResults REST API.
+            start_index (Optional[int]):
+                Zero-based index of the starting row. See startIndex in the
+                jobs.getQueryResults REST API.
 
         Returns:
             google.cloud.bigquery.query._QueryResults:
@@ -2051,6 +2099,9 @@ class Client(ClientWithProject):
         if location is not None:
             extra_params["location"] = location
 
+        if start_index is not None:
+            extra_params["startIndex"] = start_index
+
         path = "/projects/{}/queries/{}".format(project, job_id)
 
         # This call is typically made in a polling loop that checks whether the
@@ -4093,6 +4144,7 @@ class Client(ClientWithProject):
         num_dml_affected_rows: Optional[int] = None,
         query: Optional[str] = None,
         total_bytes_processed: Optional[int] = None,
+        slot_millis: Optional[int] = None,
     ) -> RowIterator:
         """List the rows of a completed query.
         See
@@ -4144,6 +4196,8 @@ class Client(ClientWithProject):
                 The query text used.
             total_bytes_processed (Optional[int]):
                 total bytes processed from job statistics, if present.
+            slot_millis (Optional[int]):
+                Number of slot ms the user is actually billed for.
 
         Returns:
             google.cloud.bigquery.table.RowIterator:
@@ -4183,6 +4237,7 @@ class Client(ClientWithProject):
             num_dml_affected_rows=num_dml_affected_rows,
             query=query,
             total_bytes_processed=total_bytes_processed,
+            slot_millis=slot_millis,
         )
         return row_iterator
 

{google_cloud_bigquery-3.34.0 → google_cloud_bigquery-3.35.0}/google/cloud/bigquery/dataset.py

@@ -17,6 +17,7 @@
 from __future__ import absolute_import
 
 import copy
+import json
 
 import typing
 from typing import Optional, List, Dict, Any, Union
@@ -506,7 +507,20 @@ class AccessEntry(object):
     def __eq__(self, other):
         if not isinstance(other, AccessEntry):
             return NotImplemented
-        return self._key() == other._key()
+        return (
+            self.role == other.role
+            and self.entity_type == other.entity_type
+            and self._normalize_entity_id(self.entity_id)
+            == self._normalize_entity_id(other.entity_id)
+            and self.condition == other.condition
+        )
+
+    @staticmethod
+    def _normalize_entity_id(value):
+        """Ensure consistent equality for dicts like 'view'."""
+        if isinstance(value, dict):
+            return json.dumps(value, sort_keys=True)
+        return value
 
     def __ne__(self, other):
         return not self == other
@@ -557,7 +571,6 @@ class AccessEntry(object):
             google.cloud.bigquery.dataset.AccessEntry:
                 Access entry parsed from ``resource``.
         """
-
         access_entry = cls()
         access_entry._properties = resource.copy()
         return access_entry
@@ -574,6 +587,10 @@ class Dataset(object):
             A pointer to a dataset. If ``dataset_ref`` is a string, it must
             include both the project ID and the dataset ID, separated by
             ``.``.
+
+    Note:
+        Fields marked as "Output Only" are populated by the server and will only be
+        available after calling :meth:`google.cloud.bigquery.client.Client.get_dataset`.
     """
 
     _PROPERTY_TO_API_FIELD = {
@@ -692,7 +709,7 @@ class Dataset(object):
 
     @property
     def created(self):
-        """Union[datetime.datetime, None]: Datetime at which the dataset was
+        """Union[datetime.datetime, None]: Output only. Datetime at which the dataset was
         created (:data:`None` until set from the server).
         """
         creation_time = self._properties.get("creationTime")
@@ -709,8 +726,8 @@ class Dataset(object):
 
     @property
     def full_dataset_id(self):
-        """Union[str, None]: ID for the dataset resource (:data:`None` until
-        set from the server)
+        """Union[str, None]: Output only. ID for the dataset resource
+        (:data:`None` until set from the server).
 
         In the format ``project_id:dataset_id``.
         """
@@ -725,14 +742,14 @@ class Dataset(object):
 
     @property
     def etag(self):
-        """Union[str, None]: ETag for the dataset resource (:data:`None` until
-        set from the server).
+        """Union[str, None]: Output only. ETag for the dataset resource
+        (:data:`None` until set from the server).
         """
         return self._properties.get("etag")
 
     @property
     def modified(self):
-        """Union[datetime.datetime, None]: Datetime at which the dataset was
+        """Union[datetime.datetime, None]: Output only. Datetime at which the dataset was
         last modified (:data:`None` until set from the server).
         """
         modified_time = self._properties.get("lastModifiedTime")
@@ -744,8 +761,8 @@ class Dataset(object):
 
     @property
     def self_link(self):
-        """Union[str, None]: URL for the dataset resource (:data:`None` until
-        set from the server).
+        """Union[str, None]: Output only. URL for the dataset resource
+        (:data:`None` until set from the server).
         """
         return self._properties.get("selfLink")
 

{google_cloud_bigquery-3.34.0 → google_cloud_bigquery-3.35.0}/google/cloud/bigquery/enums.py

@@ -80,6 +80,24 @@ class CreateDisposition(object):
     returned in the job result."""
 
 
+class DatasetView(enum.Enum):
+    """DatasetView specifies which dataset information is returned."""
+
+    DATASET_VIEW_UNSPECIFIED = "DATASET_VIEW_UNSPECIFIED"
+    """The default value. Currently maps to the FULL view."""
+
+    METADATA = "METADATA"
+    """View metadata information for the dataset, such as friendlyName,
+    description, labels, etc."""
+
+    ACL = "ACL"
+    """View ACL information for the dataset, which defines dataset access
+    for one or more entities."""
+
+    FULL = "FULL"
+    """View both dataset metadata and ACL information."""
+
+
 class DefaultPandasDTypes(enum.Enum):
     """Default Pandas DataFrem DTypes to convert BigQuery data. These
     Sentinel values are used instead of None to maintain backward compatibility,
@@ -409,6 +427,24 @@ class BigLakeTableFormat(object):
     """Apache Iceberg format."""
 
 
+class UpdateMode(enum.Enum):
+    """Specifies the kind of information to update in a dataset."""
+
+    UPDATE_MODE_UNSPECIFIED = "UPDATE_MODE_UNSPECIFIED"
+    """The default value. Behavior defaults to UPDATE_FULL."""
+
+    UPDATE_METADATA = "UPDATE_METADATA"
+    """Includes metadata information for the dataset, such as friendlyName,
+    description, labels, etc."""
+
+    UPDATE_ACL = "UPDATE_ACL"
+    """Includes ACL information for the dataset, which defines dataset access
+    for one or more entities."""
+
+    UPDATE_FULL = "UPDATE_FULL"
+    """Includes both dataset metadata and ACL information."""
+
+
 class JobCreationMode(object):
     """Documented values for Job Creation Mode."""
 
@@ -426,3 +462,21 @@ class JobCreationMode(object):
     The conditions under which BigQuery can decide to not create a Job are
     subject to change.
     """
+
+
+class SourceColumnMatch(str, enum.Enum):
+    """Uses sensible defaults based on how the schema is provided.
+    If autodetect is used, then columns are matched by name. Otherwise, columns
+    are matched by position. This is done to keep the behavior backward-compatible.
+    """
+
+    SOURCE_COLUMN_MATCH_UNSPECIFIED = "SOURCE_COLUMN_MATCH_UNSPECIFIED"
+    """Unspecified column name match option."""
+
+    POSITION = "POSITION"
+    """Matches by position. This assumes that the columns are ordered the same
+    way as the schema."""
+
+    NAME = "NAME"
+    """Matches by name. This reads the header row as column names and reorders
+    columns to match the field names in the schema."""

{google_cloud_bigquery-3.34.0 → google_cloud_bigquery-3.35.0}/google/cloud/bigquery/external_config.py

@@ -22,6 +22,7 @@ from __future__ import absolute_import, annotations
 
 import base64
 import copy
+import typing
 from typing import Any, Dict, FrozenSet, Iterable, Optional, Union
 
 from google.cloud.bigquery._helpers import _to_bytes
@@ -29,6 +30,7 @@ from google.cloud.bigquery._helpers import _bytes_to_json
 from google.cloud.bigquery._helpers import _int_or_none
 from google.cloud.bigquery._helpers import _str_or_none
 from google.cloud.bigquery import _helpers
+from google.cloud.bigquery.enums import SourceColumnMatch
 from google.cloud.bigquery.format_options import AvroOptions, ParquetOptions
 from google.cloud.bigquery import schema
 from google.cloud.bigquery.schema import SchemaField
@@ -473,6 +475,60 @@ class CSVOptions(object):
     def skip_leading_rows(self, value):
         self._properties["skipLeadingRows"] = str(value)
 
+    @property
+    def source_column_match(self) -> Optional[SourceColumnMatch]:
+        """Optional[google.cloud.bigquery.enums.SourceColumnMatch]: Controls the
+        strategy used to match loaded columns to the schema. If not set, a sensible
+        default is chosen based on how the schema is provided. If autodetect is
+        used, then columns are matched by name. Otherwise, columns are matched by
+        position. This is done to keep the behavior backward-compatible.
+
+        Acceptable values are:
+
+            SOURCE_COLUMN_MATCH_UNSPECIFIED: Unspecified column name match option.
+            POSITION: matches by position. This assumes that the columns are ordered
+            the same way as the schema.
+            NAME: matches by name. This reads the header row as column names and
+            reorders columns to match the field names in the schema.
+
+        See
+        https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#CsvOptions.FIELDS.source_column_match
+        """
+
+        value = self._properties.get("sourceColumnMatch")
+        return SourceColumnMatch(value) if value is not None else None
+
+    @source_column_match.setter
+    def source_column_match(self, value: Union[SourceColumnMatch, str, None]):
+        if value is not None and not isinstance(value, (SourceColumnMatch, str)):
+            raise TypeError(
+                "value must be a google.cloud.bigquery.enums.SourceColumnMatch, str, or None"
+            )
+        if isinstance(value, SourceColumnMatch):
+            value = value.value
+        self._properties["sourceColumnMatch"] = value if value else None
+
+    @property
+    def null_markers(self) -> Optional[Iterable[str]]:
+        """Optional[Iterable[str]]: A list of strings represented as SQL NULL values in a CSV file.
+
+        .. note::
+            null_marker and null_markers can't be set at the same time.
+            If null_marker is set, null_markers has to be not set.
+            If null_markers is set, null_marker has to be not set.
+            If both null_marker and null_markers are set at the same time, a user error would be thrown.
+            Any strings listed in null_markers, including empty string would be interpreted as SQL NULL.
+            This applies to all column types.
+
+        See
+        https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#CsvOptions.FIELDS.null_markers
+        """
+        return self._properties.get("nullMarkers")
+
+    @null_markers.setter
+    def null_markers(self, value: Optional[Iterable[str]]):
+        self._properties["nullMarkers"] = value
+
     def to_api_repr(self) -> dict:
         """Build an API representation of this object.
 
@@ -835,10 +891,10 @@ class ExternalConfig(object):
         See
         https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#ExternalDataConfiguration.FIELDS.schema
         """
-        # TODO: The typehinting for this needs work. Setting this pragma to temporarily
-        # manage a pytype issue that came up in another PR. See Issue: #2132
-        prop = self._properties.get("schema", {})  # type: ignore
-        return [SchemaField.from_api_repr(field) for field in prop.get("fields", [])]  # type: ignore
+        prop: Dict[str, Any] = typing.cast(
+            Dict[str, Any], self._properties.get("schema", {})
+        )
+        return [SchemaField.from_api_repr(field) for field in prop.get("fields", [])]
 
     @schema.setter
     def schema(self, value):
@@ -847,6 +903,80 @@ class ExternalConfig(object):
             prop = {"fields": [field.to_api_repr() for field in value]}
         self._properties["schema"] = prop
 
+    @property
+    def date_format(self) -> Optional[str]:
+        """Optional[str]: Format used to parse DATE values. Supports C-style and SQL-style values.
+
+        See:
+        https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#ExternalDataConfiguration.FIELDS.date_format
+        """
+        result = self._properties.get("dateFormat")
+        return typing.cast(str, result)
+
+    @date_format.setter
+    def date_format(self, value: Optional[str]):
+        self._properties["dateFormat"] = value
+
+    @property
+    def datetime_format(self) -> Optional[str]:
+        """Optional[str]: Format used to parse DATETIME values. Supports C-style
+        and SQL-style values.
+
+        See:
+        https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#ExternalDataConfiguration.FIELDS.datetime_format
+        """
+        result = self._properties.get("datetimeFormat")
+        return typing.cast(str, result)
+
+    @datetime_format.setter
+    def datetime_format(self, value: Optional[str]):
+        self._properties["datetimeFormat"] = value
+
+    @property
+    def time_zone(self) -> Optional[str]:
+        """Optional[str]: Time zone used when parsing timestamp values that do not
+        have specific time zone information (e.g. 2024-04-20 12:34:56). The expected
+        format is an IANA timezone string (e.g. America/Los_Angeles).
+
+        See:
+        https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#ExternalDataConfiguration.FIELDS.time_zone
+        """
+
+        result = self._properties.get("timeZone")
+        return typing.cast(str, result)
+
+    @time_zone.setter
+    def time_zone(self, value: Optional[str]):
+        self._properties["timeZone"] = value
+
+    @property
+    def time_format(self) -> Optional[str]:
+        """Optional[str]: Format used to parse TIME values. Supports C-style and SQL-style values.
+
+        See:
+        https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#ExternalDataConfiguration.FIELDS.time_format
+        """
+        result = self._properties.get("timeFormat")
+        return typing.cast(str, result)
+
+    @time_format.setter
+    def time_format(self, value: Optional[str]):
+        self._properties["timeFormat"] = value
+
+    @property
+    def timestamp_format(self) -> Optional[str]:
+        """Optional[str]: Format used to parse TIMESTAMP values. Supports C-style and SQL-style values.
+
+        See:
+        https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#ExternalDataConfiguration.FIELDS.timestamp_format
+        """
+        result = self._properties.get("timestampFormat")
+        return typing.cast(str, result)
+
+    @timestamp_format.setter
+    def timestamp_format(self, value: Optional[str]):
+        self._properties["timestampFormat"] = value
+
     @property
     def connection_id(self):
         """Optional[str]: [Experimental] ID of a BigQuery Connection API

{google_cloud_bigquery-3.34.0 → google_cloud_bigquery-3.35.0}/google/cloud/bigquery/job/base.py

@@ -435,9 +435,7 @@ class _AsyncJob(google.api_core.future.polling.PollingFuture):
     @property
     def configuration(self) -> _JobConfig:
         """Job-type specific configurtion."""
-        # TODO: The typehinting for this needs work. Setting this pragma to temporarily
-        # manage a pytype issue that came up in another PR. See Issue: #2132
-        configuration = self._CONFIG_CLASS()  # pytype: disable=not-callable
+        configuration: _JobConfig = self._CONFIG_CLASS()  # pytype: disable=not-callable
         configuration._properties = self._properties.setdefault("configuration", {})
         return configuration