google-cloud-bigquery 3.31.0__tar.gz → 3.32.0__tar.gz

{google_cloud_bigquery-3.31.0/google_cloud_bigquery.egg-info → google_cloud_bigquery-3.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: google-cloud-bigquery
-Version: 3.31.0
+Version: 3.32.0
 Summary: Google BigQuery API client library
 Author-email: Google LLC <googleapis-packages@google.com>
 License: Apache 2.0
@@ -33,7 +33,7 @@ Requires-Dist: grpcio<2.0.0,>=1.47.0; extra == "bqstorage"
 Requires-Dist: grpcio<2.0.0,>=1.49.1; python_version >= "3.11" and extra == "bqstorage"
 Requires-Dist: pyarrow>=4.0.0; extra == "bqstorage"
 Provides-Extra: pandas
-Requires-Dist: pandas>=1.1.4; extra == "pandas"
+Requires-Dist: pandas>=1.3.0; extra == "pandas"
 Requires-Dist: pandas-gbq>=0.26.1; extra == "pandas"
 Requires-Dist: grpcio<2.0.0,>=1.47.0; extra == "pandas"
 Requires-Dist: grpcio<2.0.0,>=1.49.1; python_version >= "3.11" and extra == "pandas"

{google_cloud_bigquery-3.31.0 → google_cloud_bigquery-3.32.0}/google/cloud/bigquery/_job_helpers.py

@@ -39,7 +39,9 @@ import copy
 import functools
 import os
 import uuid
+import textwrap
 from typing import Any, Dict, Optional, TYPE_CHECKING, Union
+import warnings
 
 import google.api_core.exceptions as core_exceptions
 from google.api_core import retry as retries
@@ -198,6 +200,44 @@ def _validate_job_config(request_body: Dict[str, Any], invalid_key: str):
         raise ValueError(f"got unexpected key {repr(invalid_key)} in job_config")
 
 
+def validate_job_retry(job_id: Optional[str], job_retry: Optional[retries.Retry]):
+    """Catch common mistakes, such as setting a job_id and job_retry at the same
+    time.
+    """
+    if job_id is not None and job_retry is not None:
+        # TODO(tswast): To avoid breaking changes but still allow a default
+        # query job retry, we currently only raise if they explicitly set a
+        # job_retry other than the default. In a future version, we may want to
+        # avoid this check for DEFAULT_JOB_RETRY and always raise.
+        if job_retry is not google.cloud.bigquery.retry.DEFAULT_JOB_RETRY:
+            raise TypeError(
+                textwrap.dedent(
+                    """
+                    `job_retry` was provided, but the returned job is
+                    not retryable, because a custom `job_id` was
+                    provided. To customize the job ID and allow for job
+                    retries, set job_id_prefix, instead.
+                    """
+                ).strip()
+            )
+        else:
+            warnings.warn(
+                textwrap.dedent(
+                    """
+                    job_retry must be explicitly set to None if job_id is set.
+                    BigQuery cannot retry a failed job by using the exact
+                    same ID. Setting job_id without explicitly disabling
+                    job_retry will raise an error in the future. To avoid this
+                    warning, either use job_id_prefix instead (preferred) or
+                    set job_retry=None.
+                    """
+                ).strip(),
+                category=FutureWarning,
+                # user code -> client.query / client.query_and_wait -> validate_job_retry
+                stacklevel=3,
+            )
+
+
 def _to_query_request(
     job_config: Optional[job.QueryJobConfig] = None,
     *,
@@ -308,7 +348,7 @@ def query_jobs_query(
     project: str,
     retry: retries.Retry,
     timeout: Optional[float],
-    job_retry: retries.Retry,
+    job_retry: Optional[retries.Retry],
 ) -> job.QueryJob:
     """Initiate a query using jobs.query with jobCreationMode=JOB_CREATION_REQUIRED.
 
@@ -564,6 +604,7 @@ def _supported_by_jobs_query(request_body: Dict[str, Any]) -> bool:
         "maximumBytesBilled",
         "requestId",
         "createSession",
+        "writeIncrementalResults",
     }
 
     unsupported_keys = request_keys - keys_allowlist

{google_cloud_bigquery-3.31.0 → google_cloud_bigquery-3.32.0}/google/cloud/bigquery/client.py

@@ -3388,7 +3388,7 @@ class Client(ClientWithProject):
         project: Optional[str] = None,
         retry: retries.Retry = DEFAULT_RETRY,
         timeout: TimeoutType = DEFAULT_TIMEOUT,
-        job_retry: retries.Retry = DEFAULT_JOB_RETRY,
+        job_retry: Optional[retries.Retry] = DEFAULT_JOB_RETRY,
         api_method: Union[str, enums.QueryApiMethod] = enums.QueryApiMethod.INSERT,
     ) -> job.QueryJob:
         """Run a SQL query.
@@ -3455,18 +3455,9 @@ class Client(ClientWithProject):
                 class, or if both ``job_id`` and non-``None`` non-default
                 ``job_retry`` are provided.
         """
-        job_id_given = job_id is not None
-        if (
-            job_id_given
-            and job_retry is not None
-            and job_retry is not DEFAULT_JOB_RETRY
-        ):
-            raise TypeError(
-                "`job_retry` was provided, but the returned job is"
-                " not retryable, because a custom `job_id` was"
-                " provided."
-            )
+        _job_helpers.validate_job_retry(job_id, job_retry)
 
+        job_id_given = job_id is not None
         if job_id_given and api_method == enums.QueryApiMethod.QUERY:
             raise TypeError(
                 "`job_id` was provided, but the 'QUERY' `api_method` was requested."

{google_cloud_bigquery-3.31.0 → google_cloud_bigquery-3.32.0}/google/cloud/bigquery/dataset.py

@@ -19,6 +19,7 @@ from __future__ import absolute_import
 import copy
 
 import typing
+from typing import Optional, List, Dict, Any, Union
 
 import google.cloud._helpers  # type: ignore
 
@@ -29,8 +30,6 @@ from google.cloud.bigquery.table import Table, TableReference
 from google.cloud.bigquery.encryption_configuration import EncryptionConfiguration
 from google.cloud.bigquery import external_config
 
-from typing import Optional, List, Dict, Any, Union
-
 
 def _get_table_reference(self, table_id: str) -> TableReference:
     """Constructs a TableReference.
@@ -299,12 +298,15 @@ class AccessEntry(object):
         role: Optional[str] = None,
         entity_type: Optional[str] = None,
         entity_id: Optional[Union[Dict[str, Any], str]] = None,
+        **kwargs,
     ):
-        self._properties = {}
+        self._properties: Dict[str, Any] = {}
         if entity_type is not None:
             self._properties[entity_type] = entity_id
         self._properties["role"] = role
-        self._entity_type = entity_type
+        self._entity_type: Optional[str] = entity_type
+        for prop, val in kwargs.items():
+            setattr(self, prop, val)
 
     @property
     def role(self) -> Optional[str]:
@@ -331,6 +333,9 @@ class AccessEntry(object):
         if isinstance(value, str):
             value = DatasetReference.from_string(value).to_api_repr()
 
+        if isinstance(value, DatasetReference):
+            value = value.to_api_repr()
+
         if isinstance(value, (Dataset, DatasetListItem)):
             value = value.reference.to_api_repr()
 
@@ -438,15 +443,65 @@ class AccessEntry(object):
     def special_group(self, value):
         self._properties["specialGroup"] = value
 
+    @property
+    def condition(self) -> Optional["Condition"]:
+        """Optional[Condition]: The IAM condition associated with this entry."""
+        value = typing.cast(Dict[str, Any], self._properties.get("condition"))
+        return Condition.from_api_repr(value) if value else None
+
+    @condition.setter
+    def condition(self, value: Union["Condition", dict, None]):
+        """Set the IAM condition for this entry."""
+        if value is None:
+            self._properties["condition"] = None
+        elif isinstance(value, Condition):
+            self._properties["condition"] = value.to_api_repr()
+        elif isinstance(value, dict):
+            self._properties["condition"] = value
+        else:
+            raise TypeError("condition must be a Condition object, dict, or None")
+
     @property
     def entity_type(self) -> Optional[str]:
         """The entity_type of the entry."""
+
+        # The api_repr for an AccessEntry object is expected to be a dict with
+        # only a few keys. Two keys that may be present are role and condition.
+        # Any additional key is going to have one of ~eight different names:
+        #   userByEmail, groupByEmail, domain, dataset, specialGroup, view,
+        #   routine, iamMember
+
+        # if self._entity_type is None, see if it needs setting
+        # i.e. is there a key: value pair that should be associated with
+        # entity_type and entity_id?
+        if self._entity_type is None:
+            resource = self._properties.copy()
+            # we are empyting the dict to get to the last `key: value`` pair
+            # so we don't keep these first entries
+            _ = resource.pop("role", None)
+            _ = resource.pop("condition", None)
+
+            try:
+                # we only need entity_type, because entity_id gets set elsewhere.
+                entity_type, _ = resource.popitem()
+            except KeyError:
+                entity_type = None
+
+            self._entity_type = entity_type
+
         return self._entity_type
 
     @property
     def entity_id(self) -> Optional[Union[Dict[str, Any], str]]:
         """The entity_id of the entry."""
-        return self._properties.get(self._entity_type) if self._entity_type else None
+        if self.entity_type:
+            entity_type = self.entity_type
+        else:
+            return None
+        return typing.cast(
+            Optional[Union[Dict[str, Any], str]],
+            self._properties.get(entity_type, None),
+        )
 
     def __eq__(self, other):
         if not isinstance(other, AccessEntry):
@@ -465,7 +520,16 @@ class AccessEntry(object):
         Returns:
             Tuple: The contents of this :class:`~google.cloud.bigquery.dataset.AccessEntry`.
         """
+
         properties = self._properties.copy()
+
+        # Dicts are not hashable.
+        # Convert condition to a hashable datatype(s)
+        condition = properties.get("condition")
+        if isinstance(condition, dict):
+            condition_key = tuple(sorted(condition.items()))
+            properties["condition"] = condition_key
+
         prop_tup = tuple(sorted(properties.items()))
         return (self.role, self._entity_type, self.entity_id, prop_tup)
 
@@ -492,19 +556,11 @@ class AccessEntry(object):
         Returns:
             google.cloud.bigquery.dataset.AccessEntry:
                 Access entry parsed from ``resource``.
-
-        Raises:
-            ValueError:
-                If the resource has more keys than ``role`` and one additional
-                key.
         """
-        entry = resource.copy()
-        role = entry.pop("role", None)
-        entity_type, entity_id = entry.popitem()
-        if len(entry) != 0:
-            raise ValueError("Entry has unexpected keys remaining.", entry)
 
-        return cls(role, entity_type, entity_id)
+        access_entry = cls()
+        access_entry._properties = resource.copy()
+        return access_entry
 
 
 class Dataset(object):
@@ -533,6 +589,7 @@ class Dataset(object):
         "default_rounding_mode": "defaultRoundingMode",
         "resource_tags": "resourceTags",
         "external_catalog_dataset_options": "externalCatalogDatasetOptions",
+        "access_policy_version": "accessPolicyVersion",
     }
 
     def __init__(self, dataset_ref) -> None:
@@ -923,6 +980,16 @@ class Dataset(object):
             self._PROPERTY_TO_API_FIELD["external_catalog_dataset_options"]
         ] = (value.to_api_repr() if value is not None else None)
 
+    @property
+    def access_policy_version(self):
+        return self._properties.get("accessPolicyVersion")
+
+    @access_policy_version.setter
+    def access_policy_version(self, value):
+        if not isinstance(value, int) and value is not None:
+            raise ValueError("Pass an integer, or None")
+        self._properties["accessPolicyVersion"] = value
+
     @classmethod
     def from_string(cls, full_dataset_id: str) -> "Dataset":
         """Construct a dataset from fully-qualified dataset ID.
@@ -1074,3 +1141,130 @@ class DatasetListItem(object):
     model = _get_model_reference
 
     routine = _get_routine_reference
+
+
+class Condition(object):
+    """Represents a textual expression in the Common Expression Language (CEL) syntax.
+
+    Typically used for filtering or policy rules, such as in IAM Conditions
+    or BigQuery row/column access policies.
+
+    See:
+        https://cloud.google.com/iam/docs/reference/rest/Shared.Types/Expr
+        https://github.com/google/cel-spec
+
+    Args:
+        expression (str):
+            The condition expression string using CEL syntax. This is required.
+            Example: ``resource.type == "compute.googleapis.com/Instance"``
+        title (Optional[str]):
+            An optional title for the condition, providing a short summary.
+            Example: ``"Request is for a GCE instance"``
+        description (Optional[str]):
+            An optional description of the condition, providing a detailed explanation.
+            Example: ``"This condition checks whether the resource is a GCE instance."``
+    """
+
+    def __init__(
+        self,
+        expression: str,
+        title: Optional[str] = None,
+        description: Optional[str] = None,
+    ):
+        self._properties: Dict[str, Any] = {}
+        # Use setters to initialize properties, which also handle validation
+        self.expression = expression
+        self.title = title
+        self.description = description
+
+    @property
+    def title(self) -> Optional[str]:
+        """Optional[str]: The title for the condition."""
+        return self._properties.get("title")
+
+    @title.setter
+    def title(self, value: Optional[str]):
+        if value is not None and not isinstance(value, str):
+            raise ValueError("Pass a string for title, or None")
+        self._properties["title"] = value
+
+    @property
+    def description(self) -> Optional[str]:
+        """Optional[str]: The description for the condition."""
+        return self._properties.get("description")
+
+    @description.setter
+    def description(self, value: Optional[str]):
+        if value is not None and not isinstance(value, str):
+            raise ValueError("Pass a string for description, or None")
+        self._properties["description"] = value
+
+    @property
+    def expression(self) -> str:
+        """str: The expression string for the condition."""
+
+        # Cast assumes expression is always set due to __init__ validation
+        return typing.cast(str, self._properties.get("expression"))
+
+    @expression.setter
+    def expression(self, value: str):
+        if not isinstance(value, str):
+            raise ValueError("Pass a non-empty string for expression")
+        if not value:
+            raise ValueError("expression cannot be an empty string")
+        self._properties["expression"] = value
+
+    def to_api_repr(self) -> Dict[str, Any]:
+        """Construct the API resource representation of this Condition."""
+        return self._properties
+
+    @classmethod
+    def from_api_repr(cls, resource: Dict[str, Any]) -> "Condition":
+        """Factory: construct a Condition instance given its API representation."""
+
+        # Ensure required fields are present in the resource if necessary
+        if "expression" not in resource:
+            raise ValueError("API representation missing required 'expression' field.")
+
+        return cls(
+            expression=resource["expression"],
+            title=resource.get("title"),
+            description=resource.get("description"),
+        )
+
+    def __eq__(self, other: object) -> bool:
+        """Check for equality based on expression, title, and description."""
+        if not isinstance(other, Condition):
+            return NotImplemented
+        return self._key() == other._key()
+
+    def _key(self):
+        """A tuple key that uniquely describes this field.
+        Used to compute this instance's hashcode and evaluate equality.
+        Returns:
+            Tuple: The contents of this :class:`~google.cloud.bigquery.dataset.AccessEntry`.
+        """
+
+        properties = self._properties.copy()
+
+        # Dicts are not hashable.
+        # Convert object to a hashable datatype(s)
+        prop_tup = tuple(sorted(properties.items()))
+        return prop_tup
+
+    def __ne__(self, other: object) -> bool:
+        """Check for inequality."""
+        return not self == other
+
+    def __hash__(self) -> int:
+        """Generate a hash based on expression, title, and description."""
+        return hash(self._key())
+
+    def __repr__(self) -> str:
+        """Return a string representation of the Condition object."""
+        parts = [f"expression={self.expression!r}"]
+        if self.title is not None:
+            parts.append(f"title={self.title!r}")
+        if self.description is not None:
+            parts.append(f"description={self.description!r}")
+        return f"Condition({', '.join(parts)})"

{google_cloud_bigquery-3.31.0 → google_cloud_bigquery-3.32.0}/google/cloud/bigquery/enums.py

@@ -338,6 +338,10 @@ class WriteDisposition(object):
     WRITE_TRUNCATE = "WRITE_TRUNCATE"
     """If the table already exists, BigQuery overwrites the table data."""
 
+    WRITE_TRUNCATE_DATA = "WRITE_TRUNCATE_DATA"
+    """For existing tables, truncate data but preserve existing schema
+    and constraints."""
+
     WRITE_EMPTY = "WRITE_EMPTY"
     """If the table already exists and contains data, a 'duplicate' error is
     returned in the job result."""
@@ -387,3 +391,19 @@ class RoundingMode(str, enum.Enum):
     ROUNDING_MODE_UNSPECIFIED = enum.auto()
     ROUND_HALF_AWAY_FROM_ZERO = enum.auto()
     ROUND_HALF_EVEN = enum.auto()
+
+
+class BigLakeFileFormat(object):
+    FILE_FORMAT_UNSPECIFIED = "FILE_FORMAT_UNSPECIFIED"
+    """The default unspecified value."""
+
+    PARQUET = "PARQUET"
+    """Apache Parquet format."""
+
+
+class BigLakeTableFormat(object):
+    TABLE_FORMAT_UNSPECIFIED = "TABLE_FORMAT_UNSPECIFIED"
+    """The default unspecified value."""
+
+    ICEBERG = "ICEBERG"
+    """Apache Iceberg format."""

{google_cloud_bigquery-3.31.0 → google_cloud_bigquery-3.32.0}/google/cloud/bigquery/job/query.py

@@ -674,6 +674,21 @@ class QueryJobConfig(_JobConfig):
     def write_disposition(self, value):
         self._set_sub_prop("writeDisposition", value)
 
+    @property
+    def write_incremental_results(self) -> Optional[bool]:
+        """This is only supported for a SELECT query using a temporary table.
+
+        If set, the query is allowed to write results incrementally to the temporary result
+        table. This may incur a performance penalty. This option cannot be used with Legacy SQL.
+
+        This feature is not generally available.
+        """
+        return self._get_sub_prop("writeIncrementalResults")
+
+    @write_incremental_results.setter
+    def write_incremental_results(self, value):
+        self._set_sub_prop("writeIncrementalResults", value)
+
     @property
     def table_definitions(self):
         """Dict[str, google.cloud.bigquery.external_config.ExternalConfig]: