docs: add docstring return type section to BigQueryOptions class (#964)

* docs: add docstring return type section to BigQueryOptions class

* docs: add docstring return type section to BigQueryOptions class

* docs: add docstrings to SamplingOptions class

* feat: add Gemini 1.5 stable models support (#945)

* feat: add Gemini 1.5 stable models support

* add to loader

* refactor: Simplify projection nodes (#961)

* docs: add docstring returns section to Options (#937)

* chore: drop unused columns at is_monotonic methods (#912)

* chore: drop unused columns at is_monotonic methods

* fixing mypy

* test: retry streaming tests to accommodate flakiness (#956)

* test: retry streaming tests to accommodate flakiness

* reduce delay, increase retries

* fix: make `read_gbq_function` work for multi-param functions (#947)

* fix: make `read_gbq_function` work for multi-param functions

* fix hyperlink

* specify hyperlink differently

* make hyperlink markdown format

* fix: support `read_gbq_function` for axis=1 application (#950)

* fix: support `read_gbq_function` for axis=1 application

* remove stray newline

* Update bigframes/session/__init__.py

* remove first person reference in the doc

* use correct product name

---------

Co-authored-by: Tim Sweña (Swast) <[email protected]>

* docs: update title of pypi notebook example to reflect use of the PyPI public dataset (#952)

In response to feedback on internal change 662899733.

* docs: add docstrings to SamplingOptions class

---------

Co-authored-by: Garrett Wu <[email protected]>
Co-authored-by: TrevorBergeron <[email protected]>
Co-authored-by: Chelsea Lin <[email protected]>
Co-authored-by: Shobhit Singh <[email protected]>
Co-authored-by: Tim Sweña (Swast) <[email protected]>

bigframes/_config/bigquery_options.py

@@ -111,6 +111,10 @@ def application_name(self) -> Optional[str]:
         The application name to amend to the user agent sent to Google APIs.
         The recommended format is  ``"application-name/major.minor.patch_version"``
         or ``"(gpn:PartnerName;)"`` for official Google partners.
+
+        Returns:
+            None or str:
+                Application name as a string if exists; otherwise None.
         """
         return self._application_name
 
@@ -124,7 +128,12 @@ def application_name(self, value: Optional[str]):
 
     @property
     def credentials(self) -> Optional[google.auth.credentials.Credentials]:
-        """The OAuth2 credentials to use for this client."""
+        """The OAuth2 credentials to use for this client.
+
+        Returns:
+            None or google.auth.credentials.Credentials:
+                google.auth.credentials.Credentials if exists; otherwise None.
+        """
         return self._credentials
 
     @credentials.setter
@@ -138,6 +147,10 @@ def location(self) -> Optional[str]:
         """Default location for job, datasets, and tables.
 
         For more information, see https://cloud.google.com/bigquery/docs/locations BigQuery locations.
+
+        Returns:
+            None or str:
+                Default location as a string; otherwise None.
         """
         return self._location
 
@@ -149,7 +162,12 @@ def location(self, value: Optional[str]):
 
     @property
     def project(self) -> Optional[str]:
-        """Google Cloud project ID to use for billing and as the default project."""
+        """Google Cloud project ID to use for billing and as the default project.
+
+        Returns:
+            None or str:
+                Google Cloud project ID as a string; otherwise None.
+        """
         return self._project
 
     @project.setter
@@ -172,6 +190,10 @@ 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.
+
+        Returns:
+            None or str:
+                Name of the BigQuery connection as a string; otherwise None.
         """
         return self._bq_connection
 
@@ -190,6 +212,12 @@ def skip_bq_connection_check(self) -> bool:
         connection (default or user-provided) does not exist, or it does not have
         necessary permissions set up to support BigQuery DataFrames operations,
         then a runtime error will be reported.
+
+        Returns:
+            bool:
+                A boolean value, where True indicates a BigQuery connection is
+                not created or the connection does not have necessary
+                permissions set up; otherwise False.
         """
         return self._skip_bq_connection_check
 
@@ -212,6 +240,11 @@ def use_regional_endpoints(self) -> bool:
         Requires that ``location`` is set. For example, to connect to
         asia-northeast1-bigquery.googleapis.com, specify
         ``location='asia-northeast1'`` and ``use_regional_endpoints=True``.
+
+        Returns:
+            bool:
+              A boolean value, where True indicates that a location is set;
+              otherwise False.
         """
         return self._use_regional_endpoints
 
@@ -244,6 +277,10 @@ def kms_key_name(self) -> Optional[str]:
         Cloud KMS CryptoKey Encrypter/Decrypter IAM role in the key's project.
         For more information, see https://cloud.google.com/bigquery/docs/customer-managed-encryption#assign_role
         Assign the Encrypter/Decrypter.
+
+        Returns:
+            None or str:
+                Name of the customer managed encryption key as a string; otherwise None.
         """
         return self._kms_key_name
 
@@ -256,7 +293,12 @@ def kms_key_name(self, value: str):
 
     @property
     def ordering_mode(self) -> Literal["strict", "partial"]:
-        """Controls whether total row order is always maintained for DataFrame/Series."""
+        """Controls whether total row order is always maintained for DataFrame/Series.
+
+        Returns:
+            Literal:
+                A literal string value of either strict or partial ordering mode.
+        """
         return self._ordering_mode.value
 
     @ordering_mode.setter

bigframes/_config/sampling_options.py

@@ -33,14 +33,44 @@ class SamplingOptions:
     random_state: Optional[int] = None
 
     def with_max_download_size(self, max_rows: Optional[int]) -> SamplingOptions:
+        """Configures the maximum download size for data sampling in MB
+
+        Args:
+            max_rows (None or int):
+                An int value for the maximum row size.
+
+        Returns:
+            bigframes._config.sampling_options.SamplingOptions:
+                The configuration for data sampling.
+        """
         return SamplingOptions(
             max_rows, self.enable_downsampling, self.sampling_method, self.random_state
         )
 
     def with_method(self, method: Literal["head", "uniform"]) -> SamplingOptions:
+        """Configures the downsampling algorithms to be chosen from
+
+        Args:
+            method (None or Literal):
+                A literal string value of either head or uniform data sampling method.
+
+        Returns:
+            bigframes._config.sampling_options.SamplingOptions:
+                The configuration for data sampling.
+        """
         return SamplingOptions(self.max_download_size, True, method, self.random_state)
 
     def with_random_state(self, state: Optional[int]) -> SamplingOptions:
+        """Configures the seed for the uniform downsampling algorithm
+
+        Args:
+            state (None or int):
+                An int value for the data sampling random state
+
+        Returns:
+            bigframes._config.sampling_options.SamplingOptions:
+                The configuration for data sampling.
+        """
         return SamplingOptions(
             self.max_download_size,
             self.enable_downsampling,
@@ -49,6 +79,12 @@ def with_random_state(self, state: Optional[int]) -> SamplingOptions:
         )
 
     def with_disabled(self) -> SamplingOptions:
+        """Configures whether to disable downsampling
+
+        Returns:
+            bigframes._config.sampling_options.SamplingOptions:
+                The configuration for data sampling.
+        """
         return SamplingOptions(
             self.max_download_size, False, self.sampling_method, self.random_state
         )