Add code examples to configuration docstrings

Added usage examples to the docstrings of configuration properties in:
- `bigframes/_config/bigquery_options.py`
- `bigframes/_config/compute_options.py`
- `bigframes/_config/experiment_options.py`
- `bigframes/_config/sampling_options.py`
- `third_party/bigframes_vendored/pandas/core/config_init.py`

This makes it easier for users to understand how to set global options via
`bigframes.pandas.options`.

Author: google-labs-jules[bot]

bigframes/_config/bigquery_options.py

@@ -127,6 +127,11 @@ def application_name(self) -> Optional[str]:
         The recommended format is  ``"application-name/major.minor.patch_version"``
         or ``"(gpn:PartnerName;)"`` for official Google partners.
 
+        **Examples:**
+
+            >>> import bigframes.pandas as bpd
+            >>> bpd.options.bigquery.application_name = "my-app/1.0.0"
+
         Returns:
             None or str:
                 Application name as a string if exists; otherwise None.
@@ -145,6 +150,13 @@ def application_name(self, value: Optional[str]):
     def credentials(self) -> Optional[google.auth.credentials.Credentials]:
         """The OAuth2 credentials to use for this client.
 
+        **Examples:**
+
+            >>> import bigframes.pandas as bpd
+            >>> import google.auth
+            >>> credentials, project = google.auth.default()
+            >>> bpd.options.bigquery.credentials = credentials
+
         Returns:
             None or google.auth.credentials.Credentials:
                 google.auth.credentials.Credentials if exists; otherwise None.
@@ -163,6 +175,11 @@ def location(self) -> Optional[str]:
 
         For more information, see https://cloud.google.com/bigquery/docs/locations BigQuery locations.
 
+        **Examples:**
+
+            >>> import bigframes.pandas as bpd
+            >>> bpd.options.bigquery.location = "US"
+
         Returns:
             None or str:
                 Default location as a string; otherwise None.
@@ -179,6 +196,11 @@ def location(self, value: Optional[str]):
     def project(self) -> Optional[str]:
         """Google Cloud project ID to use for billing and as the default project.
 
+        **Examples:**
+
+            >>> import bigframes.pandas as bpd
+            >>> bpd.options.bigquery.project = "my-project"
+
         Returns:
             None or str:
                 Google Cloud project ID as a string; otherwise None.
@@ -206,6 +228,11 @@ def bq_connection(self) -> Optional[str]:
         If this option isn't provided, or project or location aren't provided,
         session will use its default project/location/connection_id as default connection.
 
+        **Examples:**
+
+            >>> import bigframes.pandas as bpd
+            >>> bpd.options.bigquery.bq_connection = "my-project.us.my-connection"
+
         Returns:
             None or str:
                 Name of the BigQuery connection as a string; otherwise None.
@@ -228,6 +255,11 @@ def skip_bq_connection_check(self) -> bool:
         necessary permissions set up to support BigQuery DataFrames operations,
         then a runtime error will be reported.
 
+        **Examples:**
+
+            >>> import bigframes.pandas as bpd
+            >>> bpd.options.bigquery.skip_bq_connection_check = True
+
         Returns:
             bool:
                 A boolean value, where True indicates a BigQuery connection is
@@ -300,6 +332,12 @@ def use_regional_endpoints(self) -> bool:
         does not promise any guarantee on the request remaining within the
         location during transit.
 
+        **Examples:**
+
+            >>> import bigframes.pandas as bpd
+            >>> bpd.options.bigquery.location = "europe-west3"
+            >>> bpd.options.bigquery.use_regional_endpoints = True
+
         Returns:
             bool:
               A boolean value, where True indicates that regional endpoints
@@ -339,6 +377,11 @@ def kms_key_name(self) -> Optional[str]:
         For more information, see https://cloud.google.com/bigquery/docs/customer-managed-encryption#assign_role
         Assign the Encrypter/Decrypter.
 
+        **Examples:**
+
+            >>> import bigframes.pandas as bpd
+            >>> bpd.options.bigquery.kms_key_name = "projects/my-project/locations/us/keyRings/my-ring/cryptoKeys/my-key"
+
         Returns:
             None or str:
                 Name of the customer managed encryption key as a string; otherwise None.
@@ -356,6 +399,11 @@ def kms_key_name(self, value: str):
     def ordering_mode(self) -> Literal["strict", "partial"]:
         """Controls whether total row order is always maintained for DataFrame/Series.
 
+        **Examples:**
+
+            >>> import bigframes.pandas as bpd
+            >>> bpd.options.bigquery.ordering_mode = "partial"
+
         Returns:
             Literal:
                 A literal string value of either strict or partial ordering mode.
@@ -432,7 +480,14 @@ def requests_transport_adapters(
 
     @property
     def enable_polars_execution(self) -> bool:
-        """If True, will use polars to execute some simple query plans locally."""
+        """If True, will use polars to execute some simple query plans locally.
+
+        **Examples:**
+
+            >>> import bigframes.pandas as bpd
+            >>> bpd.options.bigquery.enable_polars_execution = True
+
+        """
         return self._enable_polars_execution
 
     @enable_polars_execution.setter

bigframes/_config/compute_options.py

@@ -63,6 +63,11 @@ class ComputeOptions:
     their operations to resume. The default value is 0. Set the value to None
     to turn off the guard.
 
+    **Examples:**
+
+        >>> import bigframes.pandas as bpd
+        >>> bpd.options.compute.ai_ops_confirmation_threshold = 100
+
     Returns:
         Optional[int]: Number of rows.
     """
@@ -73,6 +78,11 @@ class ComputeOptions:
 
     When set to True, the operation automatically fails without asking for user inputs.
 
+    **Examples:**
+
+        >>> import bigframes.pandas as bpd
+        >>> bpd.options.compute.ai_ops_threshold_autofail = True
+
     Returns:
         bool: True if the guard is enabled.
     """
@@ -85,6 +95,10 @@ class ComputeOptions:
     10 GB for potentially faster execution; BigQuery will raise an error if this
     limit is exceeded. Setting to True removes this result size limit.
 
+    **Examples:**
+
+        >>> import bigframes.pandas as bpd
+        >>> bpd.options.compute.allow_large_results = True
 
     Returns:
         bool | None: True if results > 10 GB are enabled.
@@ -97,6 +111,10 @@ class ComputeOptions:
     query engine to handle. However this comes at the cost of increase cost and
     latency.
 
+    **Examples:**
+
+        >>> import bigframes.pandas as bpd
+        >>> bpd.options.compute.enable_multi_query_execution = True
 
     Returns:
         bool | None: True if enabled.
@@ -121,6 +139,11 @@ class ComputeOptions:
     default.  See `maximum_bytes_billed`:
     https://cloud.google.com/python/docs/reference/bigquery/latest/google.cloud.bigquery.job.QueryJobConfig#google_cloud_bigquery_job_QueryJobConfig_maximum_bytes_billed.
 
+    **Examples:**
+
+        >>> import bigframes.pandas as bpd
+        >>> bpd.options.compute.maximum_bytes_billed = 1000
+
     Returns:
         int | None: Number of bytes, if set.
     """
@@ -136,6 +159,11 @@ class ComputeOptions:
     of rows to be downloaded exceeds this limit, a
     ``bigframes.exceptions.MaximumResultRowsExceeded`` exception is raised.
 
+    **Examples:**
+
+        >>> import bigframes.pandas as bpd
+        >>> bpd.options.compute.maximum_result_rows = 1000
+
     Returns:
         int | None: Number of rows, if set.
     """

bigframes/_config/experiment_options.py

@@ -30,6 +30,13 @@ def __init__(self):
 
     @property
     def semantic_operators(self) -> bool:
+        """Deprecated.
+
+        **Examples:**
+
+            >>> import bigframes.pandas as bpd
+            >>> bpd.options.experiments.semantic_operators = True
+        """
         return self._semantic_operators
 
     @semantic_operators.setter
@@ -43,6 +50,13 @@ def semantic_operators(self, value: bool):
 
     @property
     def ai_operators(self) -> bool:
+        """If True, allow using the AI operators.
+
+        **Examples:**
+
+            >>> import bigframes.pandas as bpd
+            >>> bpd.options.experiments.ai_operators = True
+        """
         return self._ai_operators
 
     @ai_operators.setter

bigframes/_config/sampling_options.py

@@ -31,6 +31,11 @@ class SamplingOptions:
     Download size threshold in MB. Default 500.
 
     If value set to None, the download size won't be checked.
+
+    **Examples:**
+
+        >>> import bigframes.pandas as bpd
+        >>> bpd.options.sampling.max_download_size = 1000
     """
 
     enable_downsampling: bool = False
@@ -40,6 +45,11 @@ class SamplingOptions:
     If max_download_size is exceeded when downloading data (e.g., to_pandas()),
     the data will be downsampled if enable_downsampling is True, otherwise, an
     error will be raised.
+
+    **Examples:**
+
+        >>> import bigframes.pandas as bpd
+        >>> bpd.options.sampling.enable_downsampling = True
     """
 
     sampling_method: Literal["head", "uniform"] = "uniform"
@@ -50,6 +60,11 @@ class SamplingOptions:
     the beginning. It is fast and requires minimal computations to perform the
     downsampling.; "uniform": This algorithm returns uniform random samples of
     the data.
+
+    **Examples:**
+
+        >>> import bigframes.pandas as bpd
+        >>> bpd.options.sampling.sampling_method = "head"
     """
 
     random_state: Optional[int] = None
@@ -58,6 +73,11 @@ class SamplingOptions:
 
     If provided, the uniform method may take longer to execute and require more
     computation.
+
+    **Examples:**
+
+        >>> import bigframes.pandas as bpd
+        >>> bpd.options.sampling.random_state = 42
     """
 
     def with_max_download_size(self, max_rows: Optional[int]) -> SamplingOptions: