From 307385f5295ae6918e7d42dcca2c0e0c32e82446 Mon Sep 17 00:00:00 2001 From: Arwa Sharif <146148342+arwas11@users.noreply.github.com> Date: Thu, 3 Oct 2024 16:11:10 -0500 Subject: [PATCH] docs: add docstring return type section to BigQueryOptions class (#964) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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) * 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 Co-authored-by: Chelsea Lin <124939984+chelsea-lin@users.noreply.github.com> Co-authored-by: Shobhit Singh Co-authored-by: Tim Sweña (Swast) --- bigframes/_config/bigquery_options.py | 48 +++++++++++++++++++++++++-- bigframes/_config/sampling_options.py | 36 ++++++++++++++++++++ 2 files changed, 81 insertions(+), 3 deletions(-) diff --git a/bigframes/_config/bigquery_options.py b/bigframes/_config/bigquery_options.py index e81557e343..42007a388e 100644 --- a/bigframes/_config/bigquery_options.py +++ b/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 diff --git a/bigframes/_config/sampling_options.py b/bigframes/_config/sampling_options.py index f4fa0928e1..ddb2a49713 100644 --- a/bigframes/_config/sampling_options.py +++ b/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 )