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) <swast@google.com> * 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 <6505921+GarrettWu@users.noreply.github.com> Co-authored-by: TrevorBergeron <tbergeron@google.com> Co-authored-by: Chelsea Lin <124939984+chelsea-lin@users.noreply.github.com> Co-authored-by: Shobhit Singh <shobs@google.com> Co-authored-by: Tim Sweña (Swast) <swast@google.com>

Author: 6 people

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
  )