From 79d8c61064cca18b596a24b6f738c7611721dd5c Mon Sep 17 00:00:00 2001 From: HemangChothani <50404902+HemangChothani@users.noreply.github.com> Date: Tue, 30 Jun 2020 18:56:04 +0530 Subject: [PATCH] docs(bigquery): consistent use of optional keyword (#153) * docs(bigquery): consistent use of optional keyword * docs(bigquery): nit --- google/cloud/bigquery/_helpers.py | 10 +- google/cloud/bigquery/_http.py | 2 +- google/cloud/bigquery/_pandas_helpers.py | 7 +- google/cloud/bigquery/client.py | 449 +++++++++++------------ google/cloud/bigquery/dataset.py | 6 +- google/cloud/bigquery/job.py | 136 +++---- google/cloud/bigquery/magics.py | 18 +- google/cloud/bigquery/model.py | 12 +- google/cloud/bigquery/query.py | 62 ++-- google/cloud/bigquery/routine.py | 8 +- google/cloud/bigquery/schema.py | 16 +- google/cloud/bigquery/table.py | 79 ++-- 12 files changed, 392 insertions(+), 413 deletions(-) diff --git a/google/cloud/bigquery/_helpers.py b/google/cloud/bigquery/_helpers.py index 21a8e3636..d814eec8c 100644 --- a/google/cloud/bigquery/_helpers.py +++ b/google/cloud/bigquery/_helpers.py @@ -471,7 +471,7 @@ def _get_sub_prop(container, keys, default=None): This method works like ``dict.get(key)``, but for nested values. - Arguments: + Args: container (Dict): A dictionary which may contain other dictionaries as values. keys (Iterable): @@ -479,8 +479,8 @@ def _get_sub_prop(container, keys, default=None): the sequence represents a deeper nesting. The first key is for the top level. If there is a dictionary there, the second key attempts to get the value within that, and so on. - default (object): - (Optional) Value to returned if any of the keys are not found. + default (Optional[object]): + Value to returned if any of the keys are not found. Defaults to ``None``. Examples: @@ -514,7 +514,7 @@ def _get_sub_prop(container, keys, default=None): def _set_sub_prop(container, keys, value): """Set a nested value in a dictionary. - Arguments: + Args: container (Dict): A dictionary which may contain other dictionaries as values. keys (Iterable): @@ -557,7 +557,7 @@ def _set_sub_prop(container, keys, value): def _del_sub_prop(container, keys): """Remove a nested key fro a dictionary. - Arguments: + Args: container (Dict): A dictionary which may contain other dictionaries as values. keys (Iterable): diff --git a/google/cloud/bigquery/_http.py b/google/cloud/bigquery/_http.py index 2ff4effef..8ee633e64 100644 --- a/google/cloud/bigquery/_http.py +++ b/google/cloud/bigquery/_http.py @@ -25,7 +25,7 @@ class Connection(_http.JSONConnection): Args: client (google.cloud.bigquery.client.Client): The client that owns the current connection. - client_info (google.api_core.client_info.ClientInfo): (Optional) instance used to generate user agent. + client_info (Optional[google.api_core.client_info.ClientInfo]): Instance used to generate user agent. """ DEFAULT_API_ENDPOINT = "https://bigquery.googleapis.com" diff --git a/google/cloud/bigquery/_pandas_helpers.py b/google/cloud/bigquery/_pandas_helpers.py index f5f9d4a99..bced246e8 100644 --- a/google/cloud/bigquery/_pandas_helpers.py +++ b/google/cloud/bigquery/_pandas_helpers.py @@ -472,10 +472,9 @@ def dataframe_to_parquet(dataframe, bq_schema, filepath, parquet_compression="SN columns in the DataFrame. filepath (str): Path to write Parquet file to. - parquet_compression (str): - (optional) The compression codec to use by the the - ``pyarrow.parquet.write_table`` serializing method. Defaults to - "SNAPPY". + parquet_compression (Optional[str]): + The compression codec to use by the the ``pyarrow.parquet.write_table`` + serializing method. Defaults to "SNAPPY". https://arrow.apache.org/docs/python/generated/pyarrow.parquet.write_table.html#pyarrow-parquet-write-table """ if pyarrow is None: diff --git a/google/cloud/bigquery/client.py b/google/cloud/bigquery/client.py index 8e265d971..eceedcd67 100644 --- a/google/cloud/bigquery/client.py +++ b/google/cloud/bigquery/client.py @@ -123,35 +123,35 @@ class Client(ClientWithProject): """Client to bundle configuration needed for API requests. Args: - project (str): + project (Optional[str]): Project ID for the project which the client acts on behalf of. Will be passed when creating a dataset / job. If not passed, falls back to the default inferred from the environment. - credentials (google.auth.credentials.Credentials): - (Optional) The OAuth2 Credentials to use for this client. If not - passed (and if no ``_http`` object is passed), falls back to the + credentials (Optional[google.auth.credentials.Credentials]): + The OAuth2 Credentials to use for this client. If not passed + (and if no ``_http`` object is passed), falls back to the default inferred from the environment. - _http (requests.Session): - (Optional) HTTP object to make requests. Can be any object that + _http (Optional[requests.Session]): + HTTP object to make requests. Can be any object that defines ``request()`` with the same interface as :meth:`requests.Session.request`. If not passed, an ``_http`` object is created that is bound to the ``credentials`` for the current object. This parameter should be considered private, and could change in the future. - location (str): - (Optional) Default location for jobs / datasets / tables. - default_query_job_config (google.cloud.bigquery.job.QueryJobConfig): - (Optional) Default ``QueryJobConfig``. + location (Optional[str]): + Default location for jobs / datasets / tables. + default_query_job_config (Optional[google.cloud.bigquery.job.QueryJobConfig]): + Default ``QueryJobConfig``. Will be merged into job configs passed into the ``query`` method. - client_info (google.api_core.client_info.ClientInfo): + client_info (Optional[google.api_core.client_info.ClientInfo]): The client info used to send a user-agent string along with API requests. If ``None``, then default info will be used. Generally, you only need to set this if you're developing your own library or partner tool. - client_options (Union[google.api_core.client_options.ClientOptions, Dict]): - (Optional) Client options used to set user options on the client. - API Endpoint should be set through client_options. + client_options (Optional[Union[google.api_core.client_options.ClientOptions, Dict]]): + Client options used to set user options on the client. API Endpoint + should be set through client_options. Raises: google.auth.exceptions.DefaultCredentialsError: @@ -220,7 +220,7 @@ def get_service_account_email( encrypted by a key in KMS. Args: - project (str, optional): + project (Optional[str]): Project ID to use for retreiving service account email. Defaults to the client's project. retry (Optional[google.api_core.retry.Retry]): How to retry the RPC. @@ -255,19 +255,18 @@ def list_projects( https://cloud.google.com/bigquery/docs/reference/rest/v2/projects/list Args: - max_results (int): - (Optional) maximum number of projects to return, - If not passed, defaults to a value set by the API. - - page_token (str): - (Optional) Token representing a cursor into the projects. If - not passed, the API will return the first page of projects. - The token marks the beginning of the iterator to be returned - and the value of the ``page_token`` can be accessed at - ``next_page_token`` of the + max_results (Optional[int]): + Maximum number of projects to return, If not passed, + defaults to a value set by the API. + + page_token (Optional[str]): + Token representing a cursor into the projects. If not passed, + the API will return the first page of projects. The token marks + the beginning of the iterator to be returned and the value of + the ``page_token`` can be accessed at ``next_page_token`` of the :class:`~google.api_core.page_iterator.HTTPIterator`. - retry (google.api_core.retry.Retry): (Optional) How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport @@ -304,27 +303,25 @@ def list_datasets( https://cloud.google.com/bigquery/docs/reference/rest/v2/datasets/list Args: - project (str): - Optional. Project ID to use for retreiving datasets. Defaults - to the client's project. - include_all (bool): - Optional. True if results include hidden datasets. Defaults - to False. - filter (str): - Optional. An expression for filtering the results by label. + project (Optional[str]): + Project ID to use for retreiving datasets. Defaults to the + client's project. + include_all (Optional[bool]): + True if results include hidden datasets. Defaults to False. + filter (Optional[str]): + An expression for filtering the results by label. For syntax, see https://cloud.google.com/bigquery/docs/reference/rest/v2/datasets/list#body.QUERY_PARAMETERS.filter - max_results (int): - Optional. Maximum number of datasets to return. - page_token (str): - Optional. Token representing a cursor into the datasets. If - not passed, the API will return the first page of datasets. - The token marks the beginning of the iterator to be returned - and the value of the ``page_token`` can be accessed at - ``next_page_token`` of the + max_results (Optional[int]): + Maximum number of datasets to return. + page_token (Optional[str]): + Token representing a cursor into the datasets. If not passed, + the API will return the first page of datasets. The token marks + the beginning of the iterator to be returned and the value of + the ``page_token`` can be accessed at ``next_page_token`` of the :class:`~google.api_core.page_iterator.HTTPIterator`. - retry (google.api_core.retry.Retry): - Optional. How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -374,9 +371,8 @@ def dataset(self, dataset_id, project=None): Args: dataset_id (str): ID of the dataset. - project (str): - (Optional) project ID for the dataset (defaults to - the project of the client). + project (Optional[str]): + Project ID for the dataset (defaults to the project of the client). Returns: google.cloud.bigquery.dataset.DatasetReference: @@ -432,11 +428,11 @@ def create_dataset( A :class:`~google.cloud.bigquery.dataset.Dataset` to create. If ``dataset`` is a reference, an empty dataset is created with the specified ID and client's default location. - exists_ok (bool): + exists_ok (Optional[bool]): Defaults to ``False``. If ``True``, ignore "already exists" errors when creating the dataset. - retry (google.api_core.retry.Retry): - Optional. How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -488,11 +484,11 @@ def create_routine( routine (google.cloud.bigquery.routine.Routine): A :class:`~google.cloud.bigquery.routine.Routine` to create. The dataset that the routine belongs to must already exist. - exists_ok (bool): + exists_ok (Optional[bool]): Defaults to ``False``. If ``True``, ignore "already exists" errors when creating the routine. - retry (google.api_core.retry.Retry): - Optional. How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -532,11 +528,11 @@ def create_table(self, table, exists_ok=False, retry=DEFAULT_RETRY, timeout=None If ``table`` is a reference, an empty table is created with the specified ID. The dataset that the table belongs to must already exist. - exists_ok (bool): + exists_ok (Optional[bool]): Defaults to ``False``. If ``True``, ignore "already exists" errors when creating the table. - retry (google.api_core.retry.Retry): - Optional. How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -577,8 +573,8 @@ def get_dataset(self, dataset_ref, retry=DEFAULT_RETRY, timeout=None): If a string is passed in, this method attempts to create a dataset reference from a string using :func:`~google.cloud.bigquery.dataset.DatasetReference.from_string`. - retry (google.api_core.retry.Retry): - (Optional) How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -609,8 +605,8 @@ def get_model(self, model_ref, retry=DEFAULT_RETRY, timeout=None): If a string is passed in, this method attempts to create a model reference from a string using :func:`google.cloud.bigquery.model.ModelReference.from_string`. - retry (google.api_core.retry.Retry): - (Optional) How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -641,8 +637,8 @@ def get_routine(self, routine_ref, retry=DEFAULT_RETRY, timeout=None): a string is passed in, this method attempts to create a reference from a string using :func:`google.cloud.bigquery.routine.RoutineReference.from_string`. - retry (google.api_core.retry.Retry): - (Optional) How to retry the API call. + retry (Optional[google.api_core.retry.Retry]): + How to retry the API call. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -674,8 +670,8 @@ def get_table(self, table, retry=DEFAULT_RETRY, timeout=None): If a string is passed in, this method attempts to create a table reference from a string using :func:`google.cloud.bigquery.table.TableReference.from_string`. - retry (google.api_core.retry.Retry): - (Optional) How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -709,7 +705,7 @@ def update_dataset(self, dataset, fields, retry=DEFAULT_RETRY, timeout=None): The dataset to update. fields (Sequence[str]): The properties of ``dataset`` to change (e.g. "friendly_name"). - retry (google.api_core.retry.Retry, optional): + retry (Optional[google.api_core.retry.Retry]): How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport @@ -752,8 +748,8 @@ def update_model(self, model, fields, retry=DEFAULT_RETRY, timeout=None): fields (Sequence[str]): The fields of ``model`` to change, spelled as the Model properties (e.g. "friendly_name"). - retry (google.api_core.retry.Retry): - (Optional) A description of how to retry the API call. + retry (Optional[google.api_core.retry.Retry]): + A description of how to retry the API call. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -802,8 +798,8 @@ def update_routine(self, routine, fields, retry=DEFAULT_RETRY, timeout=None): The fields of ``routine`` to change, spelled as the :class:`~google.cloud.bigquery.routine.Routine` properties (e.g. ``type_``). - retry (google.api_core.retry.Retry): - (Optional) A description of how to retry the API call. + retry (Optional[google.api_core.retry.Retry]): + A description of how to retry the API call. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -849,8 +845,8 @@ def update_table(self, table, fields, retry=DEFAULT_RETRY, timeout=None): fields (Sequence[str]): The fields of ``table`` to change, spelled as the Table properties (e.g. "friendly_name"). - retry (google.api_core.retry.Retry): - (Optional) A description of how to retry the API call. + retry (Optional[google.api_core.retry.Retry]): + A description of how to retry the API call. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -897,18 +893,17 @@ def list_models( BigQuery API. If a string is passed in, this method attempts to create a dataset reference from a string using :func:`google.cloud.bigquery.dataset.DatasetReference.from_string`. - max_results (int): - (Optional) Maximum number of models to return. If not passed, - defaults to a value set by the API. - page_token (str): - (Optional) Token representing a cursor into the models. If - not passed, the API will return the first page of models. The - token marks the beginning of the iterator to be returned and - the value of the ``page_token`` can be accessed at - ``next_page_token`` of the + max_results (Optional[int]): + Maximum number of models to return. If not passed, defaults to a + value set by the API. + page_token (Optional[str]): + Token representing a cursor into the models. If not passed, + the API will return the first page of models. The token marks + the beginning of the iterator to be returned and the value of + the ``page_token`` can be accessed at ``next_page_token`` of the :class:`~google.api_core.page_iterator.HTTPIterator`. - retry (google.api_core.retry.Retry): - (Optional) How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -963,18 +958,17 @@ def list_routines( BigQuery API. If a string is passed in, this method attempts to create a dataset reference from a string using :func:`google.cloud.bigquery.dataset.DatasetReference.from_string`. - max_results (int): - (Optional) Maximum number of routines to return. If not passed, - defaults to a value set by the API. - page_token (str): - (Optional) Token representing a cursor into the routines. If - not passed, the API will return the first page of routines. The - token marks the beginning of the iterator to be returned and - the value of the ``page_token`` can be accessed at - ``next_page_token`` of the + max_results (Optional[int]): + Maximum number of routines to return. If not passed, defaults + to a value set by the API. + page_token (Optional[str]): + Token representing a cursor into the routines. If not passed, + the API will return the first page of routines. The token marks + the beginning of the iterator to be returned and the value of the + ``page_token`` can be accessed at ``next_page_token`` of the :class:`~google.api_core.page_iterator.HTTPIterator`. - retry (google.api_core.retry.Retry): - (Optional) How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -1029,18 +1023,17 @@ def list_tables( BigQuery API. If a string is passed in, this method attempts to create a dataset reference from a string using :func:`google.cloud.bigquery.dataset.DatasetReference.from_string`. - max_results (int): - (Optional) Maximum number of tables to return. If not passed, - defaults to a value set by the API. - page_token (str): - (Optional) Token representing a cursor into the tables. If - not passed, the API will return the first page of tables. The - token marks the beginning of the iterator to be returned and - the value of the ``page_token`` can be accessed at - ``next_page_token`` of the + max_results (Optional[int]): + Maximum number of tables to return. If not passed, defaults + to a value set by the API. + page_token (Optional[str]): + Token representing a cursor into the tables. If not passed, + the API will return the first page of tables. The token marks + the beginning of the iterator to be returned and the value of + the ``page_token`` can be accessed at ``next_page_token`` of the :class:`~google.api_core.page_iterator.HTTPIterator`. - retry (google.api_core.retry.Retry): - (Optional) How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -1085,7 +1078,7 @@ def delete_dataset( See https://cloud.google.com/bigquery/docs/reference/rest/v2/datasets/delete - Args + Args: dataset (Union[ \ google.cloud.bigquery.dataset.Dataset, \ google.cloud.bigquery.dataset.DatasetReference, \ @@ -1095,16 +1088,16 @@ def delete_dataset( in, this method attempts to create a dataset reference from a string using :func:`google.cloud.bigquery.dataset.DatasetReference.from_string`. - delete_contents (boolean): - (Optional) If True, delete all the tables in the dataset. If - False and the dataset contains tables, the request will fail. + delete_contents (Optional[bool]): + If True, delete all the tables in the dataset. If False and + the dataset contains tables, the request will fail. Default is False. - retry (google.api_core.retry.Retry): - (Optional) How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. - not_found_ok (bool): + not_found_ok (Optional[bool]): Defaults to ``False``. If ``True``, ignore "not found" errors when deleting the dataset. """ @@ -1150,12 +1143,12 @@ def delete_model( this method attempts to create a model reference from a string using :func:`google.cloud.bigquery.model.ModelReference.from_string`. - retry (google.api_core.retry.Retry): - (Optional) How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. - not_found_ok (bool): + not_found_ok (Optional[bool]): Defaults to ``False``. If ``True``, ignore "not found" errors when deleting the model. """ @@ -1180,7 +1173,7 @@ def delete_routine( https://cloud.google.com/bigquery/docs/reference/rest/v2/routines/delete Args: - model (Union[ \ + routine (Union[ \ google.cloud.bigquery.routine.Routine, \ google.cloud.bigquery.routine.RoutineReference, \ str, \ @@ -1189,12 +1182,12 @@ def delete_routine( in, this method attempts to create a routine reference from a string using :func:`google.cloud.bigquery.routine.RoutineReference.from_string`. - retry (google.api_core.retry.Retry): - (Optional) How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. - not_found_ok (bool): + not_found_ok (Optional[bool]): Defaults to ``False``. If ``True``, ignore "not found" errors when deleting the routine. """ @@ -1230,12 +1223,12 @@ def delete_table( this method attempts to create a table reference from a string using :func:`google.cloud.bigquery.table.TableReference.from_string`. - retry (google.api_core.retry.Retry): - (Optional) How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. - not_found_ok (bool): + not_found_ok (Optional[bool]): Defaults to ``False``. If ``True``, ignore "not found" errors when deleting the table. """ @@ -1254,17 +1247,16 @@ def _get_query_results( ): """Get the query results object for a query job. - Arguments: + Args: job_id (str): Name of the query job. retry (google.api_core.retry.Retry): - (Optional) How to retry the RPC. - project (str): - (Optional) project ID for the query job (defaults to the - project of the client). - timeout_ms (int): - (Optional) number of milliseconds the the API call should - wait for the query to complete before the request times out. - location (str): Location of the query job. + How to retry the RPC. + project (Optional[str]): + Project ID for the query job (defaults to the project of the client). + timeout_ms (Optional[int]): + Number of milliseconds the the API call should wait for the query + to complete before the request times out. + location (Optional[str]): Location of the query job. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -1326,12 +1318,12 @@ def job_from_resource(self, resource): def create_job(self, job_config, retry=DEFAULT_RETRY): """Create a new job. - Arguments: + Args: job_config (dict): configuration job representation returned from the API. Keyword Arguments: - retry (google.api_core.retry.Retry): - (Optional) How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. Returns: Union[ \ @@ -1404,16 +1396,15 @@ def get_job( See https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/get - Arguments: + Args: job_id (str): Unique job identifier. Keyword Arguments: - project (str): - (Optional) ID of the project which ownsthe job (defaults to - the client's project). - location (str): Location where the job was run. - retry (google.api_core.retry.Retry): - (Optional) How to retry the RPC. + project (Optional[str]): + ID of the project which owns the job (defaults to the client's project). + location (Optional[str]): Location where the job was run. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -1458,12 +1449,11 @@ def cancel_job( job_id (str): Unique job identifier. Keyword Arguments: - project (str): - (Optional) ID of the project which owns the job (defaults to - the client's project). - location (str): Location where the job was run. - retry (google.api_core.retry.Retry): - (Optional) How to retry the RPC. + project (Optional[str]): + ID of the project which owns the job (defaults to the client's project). + location (Optional[str]): Location where the job was run. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -1610,7 +1600,7 @@ def load_table_from_uri( See https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#jobconfigurationload - Arguments: + Args: source_uris (Union[str, Sequence[str]]): URIs of data files to be loaded; in format ``gs:///``. @@ -1625,21 +1615,20 @@ def load_table_from_uri( :func:`google.cloud.bigquery.table.TableReference.from_string`. Keyword Arguments: - job_id (str): (Optional) Name of the job. - job_id_prefix (str): - (Optional) the user-provided prefix for a randomly generated - job ID. This parameter will be ignored if a ``job_id`` is - also given. - location (str): + job_id (Optional[str]): Name of the job. + job_id_prefix (Optional[str]): + The user-provided prefix for a randomly generated job ID. + This parameter will be ignored if a ``job_id`` is also given. + location (Optional[str]): Location where to run the job. Must match the location of the destination table. - project (str): + project (Optional[str]): Project ID of the project of where to run the job. Defaults to the client's project. - job_config (google.cloud.bigquery.job.LoadJobConfig): - (Optional) Extra configuration options for the job. - retry (google.api_core.retry.Retry): - (Optional) How to retry the RPC. + job_config (Optional[google.cloud.bigquery.job.LoadJobConfig]): + Extra configuration options for the job. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -1694,7 +1683,7 @@ def load_table_from_file( Similar to :meth:`load_table_from_uri`, this method creates, starts and returns a :class:`~google.cloud.bigquery.job.LoadJob`. - Arguments: + Args: file_obj (file): A file handle opened in binary mode for reading. destination (Union[ \ google.cloud.bigquery.table.Table, \ @@ -1707,27 +1696,26 @@ def load_table_from_file( :func:`google.cloud.bigquery.table.TableReference.from_string`. Keyword Arguments: - rewind (bool): + rewind (Optional[bool]): If True, seek to the beginning of the file handle before reading the file. - size (int): + size (Optional[int]): The number of bytes to read from the file handle. If size is ``None`` or large, resumable upload will be used. Otherwise, multipart upload will be used. - num_retries (int): Number of upload retries. Defaults to 6. - job_id (str): (Optional) Name of the job. - job_id_prefix (str): - (Optional) the user-provided prefix for a randomly generated - job ID. This parameter will be ignored if a ``job_id`` is - also given. - location (str): + num_retries (Optional[int]): Number of upload retries. Defaults to 6. + job_id (Optional[str]): Name of the job. + job_id_prefix (Optional[str]): + The user-provided prefix for a randomly generated job ID. + This parameter will be ignored if a ``job_id`` is also given. + location (Optional[str]): Location where to run the job. Must match the location of the destination table. - project (str): + project (Optional[str]): Project ID of the project of where to run the job. Defaults to the client's project. - job_config (google.cloud.bigquery.job.LoadJobConfig): - (Optional) Extra configuration options for the job. + job_config (Optional[google.cloud.bigquery.job.LoadJobConfig]): + Extra configuration options for the job. Returns: google.cloud.bigquery.job.LoadJob: A new load job. @@ -1802,7 +1790,7 @@ def load_table_from_dataframe( https://github.com/googleapis/python-bigquery/issues/17 - Arguments: + Args: dataframe (pandas.DataFrame): A :class:`~pandas.DataFrame` containing the data to load. destination (google.cloud.bigquery.table.TableReference): @@ -1823,7 +1811,7 @@ def load_table_from_dataframe( The user-provided prefix for a randomly generated job ID. This parameter will be ignored if a ``job_id`` is also given. - location (str): + location (Optional[str]): Location where to run the job. Must match the location of the destination table. project (Optional[str]): @@ -1838,7 +1826,7 @@ def load_table_from_dataframe( column names matching those of the dataframe. The BigQuery schema is used to determine the correct data type conversion. Indexes are not loaded. Requires the :mod:`pyarrow` library. - parquet_compression (str): + parquet_compression (Optional[str]): [Beta] The compression method to use if intermittently serializing ``dataframe`` to a parquet file. @@ -2013,20 +2001,19 @@ def load_table_from_json( Keyword Arguments: num_retries (Optional[int]): Number of upload retries. - job_id (str): (Optional) Name of the job. - job_id_prefix (str): - (Optional) the user-provided prefix for a randomly generated - job ID. This parameter will be ignored if a ``job_id`` is - also given. - location (str): + job_id (Optional[str]): Name of the job. + job_id_prefix (Optional[str]): + The user-provided prefix for a randomly generated job ID. + This parameter will be ignored if a ``job_id`` is also given. + location (Optional[str]): Location where to run the job. Must match the location of the destination table. - project (str): + project (Optional[str]): Project ID of the project of where to run the job. Defaults to the client's project. - job_config (google.cloud.bigquery.job.LoadJobConfig): - (Optional) Extra configuration options for the job. The - ``source_format`` setting is always set to + job_config (Optional[google.cloud.bigquery.job.LoadJobConfig]): + Extra configuration options for the job. The ``source_format`` + setting is always set to :attr:`~google.cloud.bigquery.job.SourceFormat.NEWLINE_DELIMITED_JSON`. Returns: @@ -2223,21 +2210,20 @@ def copy_table( Table into which data is to be copied. Keyword Arguments: - job_id (str): (Optional) The ID of the job. - job_id_prefix (str) - (Optional) the user-provided prefix for a randomly generated - job ID. This parameter will be ignored if a ``job_id`` is - also given. - location (str): + job_id (Optional[str]): The ID of the job. + job_id_prefix (Optional[str]): + The user-provided prefix for a randomly generated job ID. + This parameter will be ignored if a ``job_id`` is also given. + location (Optional[str]): Location where to run the job. Must match the location of any source table as well as the destination table. - project (str): + project (Optional[str]): Project ID of the project of where to run the job. Defaults to the client's project. - job_config (google.cloud.bigquery.job.CopyJobConfig): - (Optional) Extra configuration options for the job. - retry (google.api_core.retry.Retry): - (Optional) How to retry the RPC. + job_config (Optional[google.cloud.bigquery.job.CopyJobConfig]): + Extra configuration options for the job. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -2321,27 +2307,25 @@ def extract_table( ``gs:///``. Keyword Arguments: - job_id (str): (Optional) The ID of the job. - job_id_prefix (str) - (Optional) the user-provided prefix for a randomly generated - job ID. This parameter will be ignored if a ``job_id`` is - also given. - location (str): + job_id (Optional[str]): The ID of the job. + job_id_prefix (Optional[str]): + The user-provided prefix for a randomly generated job ID. + This parameter will be ignored if a ``job_id`` is also given. + location (Optional[str]): Location where to run the job. Must match the location of the source table. - project (str): + project (Optional[str]): Project ID of the project of where to run the job. Defaults to the client's project. - job_config (google.cloud.bigquery.job.ExtractJobConfig): - (Optional) Extra configuration options for the job. - retry (google.api_core.retry.Retry): - (Optional) How to retry the RPC. + job_config (Optional[google.cloud.bigquery.job.ExtractJobConfig]): + Extra configuration options for the job. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. - source_type (str): - (Optional) Type of source to be extracted.``Table`` or ``Model``. - Defaults to ``Table``. + source_type (Optional[str]): + Type of source to be extracted.``Table`` or ``Model``. Defaults to ``Table``. Returns: google.cloud.bigquery.job.ExtractJob: A new extract job instance. @@ -2411,24 +2395,24 @@ def query( dialect. Use the ``job_config`` parameter to change dialects. Keyword Arguments: - job_config (google.cloud.bigquery.job.QueryJobConfig): - (Optional) Extra configuration options for the job. + job_config (Optional[google.cloud.bigquery.job.QueryJobConfig]): + Extra configuration options for the job. To override any options that were previously set in the ``default_query_job_config`` given to the ``Client`` constructor, manually set those options to ``None``, or whatever value is preferred. - job_id (str): (Optional) ID to use for the query job. - job_id_prefix (str): - (Optional) The prefix to use for a randomly generated job ID. - This parameter will be ignored if a ``job_id`` is also given. - location (str): + job_id (Optional[str]): ID to use for the query job. + job_id_prefix (Optional[str]): + The prefix to use for a randomly generated job ID. This parameter + will be ignored if a ``job_id`` is also given. + location (Optional[str]): Location where to run the job. Must match the location of the any table used in the query as well as the destination table. - project (str): + project (Optional[str]): Project ID of the project of where to run the job. Defaults to the client's project. - retry (google.api_core.retry.Retry): - (Optional) How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -2699,8 +2683,8 @@ def list_partitions(self, table, retry=DEFAULT_RETRY, timeout=None): str, \ ]): The table or reference from which to get partition info - retry (google.api_core.retry.Retry): - (Optional) How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -2766,23 +2750,22 @@ def list_rows( selected_fields (Sequence[google.cloud.bigquery.schema.SchemaField]): The fields to return. If not supplied, data for all columns are downloaded. - max_results (int): - (Optional) maximum number of rows to return. - page_token (str): - (Optional) Token representing a cursor into the table's rows. + max_results (Optional[int]): + Maximum number of rows to return. + page_token (Optional[str]): + Token representing a cursor into the table's rows. If not passed, the API will return the first page of the rows. The token marks the beginning of the iterator to be returned and the value of the ``page_token`` can be accessed at ``next_page_token`` of the :class:`~google.cloud.bigquery.table.RowIterator`. - start_index (int): - (Optional) The zero-based index of the starting row to read. - page_size (int): - Optional. The maximum number of rows in each page of results - from this request. Non-positive values are ignored. Defaults - to a sensible value set by the API. - retry (google.api_core.retry.Retry): - (Optional) How to retry the RPC. + start_index (Optional[int]): + The zero-based index of the starting row to read. + page_size (Optional[int]): + The maximum number of rows in each page of results from this request. + Non-positive values are ignored. Defaults to a sensible value set by the API. + retry (Optional[google.api_core.retry.Retry]): + How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. diff --git a/google/cloud/bigquery/dataset.py b/google/cloud/bigquery/dataset.py index c804c1c17..9a80f30b5 100644 --- a/google/cloud/bigquery/dataset.py +++ b/google/cloud/bigquery/dataset.py @@ -295,9 +295,9 @@ def from_string(cls, dataset_id, default_project=None): A dataset ID in standard SQL format. If ``default_project`` is not specified, this must include both the project ID and the dataset ID, separated by ``.``. - default_project (str): - Optional. The project ID to use when ``dataset_id`` does not - include a project ID. + default_project (Optional[str]): + The project ID to use when ``dataset_id`` does not include a + project ID. Returns: DatasetReference: diff --git a/google/cloud/bigquery/job.py b/google/cloud/bigquery/job.py index 930dc413d..753307b2a 100644 --- a/google/cloud/bigquery/job.py +++ b/google/cloud/bigquery/job.py @@ -267,7 +267,7 @@ class SchemaUpdateOption(object): class _JobReference(object): """A reference to a job. - Arguments: + Args: job_id (str): ID of the job to run. project (str): ID of the project where the job runs. location (str): Location of where the job runs. @@ -311,7 +311,7 @@ def _from_api_repr(cls, resource): class _AsyncJob(google.api_core.future.polling.PollingFuture): """Base class for asynchronous jobs. - Arguments: + Args: job_id (Union[str, _JobReference]): Job's ID in the project associated with the client or a fully-qualified job reference. @@ -650,7 +650,7 @@ def exists(self, client=None, retry=DEFAULT_RETRY, timeout=None): the client to use. If not passed, falls back to the ``client`` stored on the current dataset. - retry (google.api_core.retry.Retry): (Optional) How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -688,7 +688,7 @@ def reload(self, client=None, retry=DEFAULT_RETRY, timeout=None): the client to use. If not passed, falls back to the ``client`` stored on the current dataset. - retry (google.api_core.retry.Retry): (Optional) How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -772,7 +772,7 @@ def done(self, retry=DEFAULT_RETRY, timeout=None): """Refresh the job and checks if it is complete. Args: - retry (google.api_core.retry.Retry): (Optional) How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -790,7 +790,7 @@ def result(self, retry=DEFAULT_RETRY, timeout=None): """Start the job and wait for it to complete and get the result. Args: - retry (google.api_core.retry.Retry): (Optional) How to retry the RPC. + retry (Optional[google.api_core.retry.Retry]): How to retry the RPC. timeout (Optional[float]): The number of seconds to wait for the underlying HTTP transport before using ``retry``. @@ -877,8 +877,8 @@ def _get_sub_prop(self, key, default=None): key (str): Key for the value to get in the ``self._properties[self._job_type]`` dictionary. - default (object): - (Optional) Default value to return if the key is not found. + default (Optional[object]): + Default value to return if the key is not found. Defaults to :data:`None`. Returns: @@ -1003,9 +1003,9 @@ def __init__(self, **kwargs): @property def allow_jagged_rows(self): - """bool: Allow missing trailing optional columns (CSV only). + """Optional[bool]: Allow missing trailing optional columns (CSV only). - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad.FIELDS.allow_jagged_rows """ return self._get_sub_prop("allowJaggedRows") @@ -1016,9 +1016,9 @@ def allow_jagged_rows(self, value): @property def allow_quoted_newlines(self): - """bool: Allow quoted data containing newline characters (CSV only). + """Optional[bool]: Allow quoted data containing newline characters (CSV only). - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad.FIELDS.allow_quoted_newlines """ return self._get_sub_prop("allowQuotedNewlines") @@ -1029,9 +1029,9 @@ def allow_quoted_newlines(self, value): @property def autodetect(self): - """bool: Automatically infer the schema from a sample of the data. + """Optional[bool]: Automatically infer the schema from a sample of the data. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad.FIELDS.autodetect """ return self._get_sub_prop("autodetect") @@ -1042,7 +1042,7 @@ def autodetect(self, value): @property def clustering_fields(self): - """Union[List[str], None]: Fields defining clustering for the table + """Optional[List[str]]: Fields defining clustering for the table (Defaults to :data:`None`). @@ -1059,7 +1059,7 @@ def clustering_fields(self): @clustering_fields.setter def clustering_fields(self, value): - """Union[List[str], None]: Fields defining clustering for the table + """Optional[List[str]]: Fields defining clustering for the table (Defaults to :data:`None`). """ @@ -1070,10 +1070,10 @@ def clustering_fields(self, value): @property def create_disposition(self): - """google.cloud.bigquery.job.CreateDisposition: Specifies behavior + """Optional[google.cloud.bigquery.job.CreateDisposition]: Specifies behavior for creating tables. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad.FIELDS.create_disposition """ return self._get_sub_prop("createDisposition") @@ -1084,13 +1084,13 @@ def create_disposition(self, value): @property def destination_encryption_configuration(self): - """google.cloud.bigquery.encryption_configuration.EncryptionConfiguration: Custom + """Optional[google.cloud.bigquery.encryption_configuration.EncryptionConfiguration]: Custom encryption configuration for the destination table. Custom encryption configuration (e.g., Cloud KMS keys) or :data:`None` if using default encryption. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad.FIELDS.destination_encryption_configuration """ prop = self._get_sub_prop("destinationEncryptionConfiguration") @@ -1109,7 +1109,7 @@ def destination_encryption_configuration(self, value): @property def destination_table_description(self): - """Union[str, None] name given to destination table. + """Optional[str]: Name given to destination table. See: https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#DestinationTableProperties.FIELDS.description @@ -1128,7 +1128,7 @@ def destination_table_description(self, value): @property def destination_table_friendly_name(self): - """Union[str, None] name given to destination table. + """Optional[str]: Name given to destination table. See: https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#DestinationTableProperties.FIELDS.friendly_name @@ -1147,10 +1147,10 @@ def destination_table_friendly_name(self, value): @property def encoding(self): - """google.cloud.bigquery.job.Encoding: The character encoding of the + """Optional[google.cloud.bigquery.job.Encoding]: The character encoding of the data. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad.FIELDS.encoding """ return self._get_sub_prop("encoding") @@ -1161,9 +1161,9 @@ def encoding(self, value): @property def field_delimiter(self): - """str: The separator for fields in a CSV file. + """Optional[str]: The separator for fields in a CSV file. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad.FIELDS.field_delimiter """ return self._get_sub_prop("fieldDelimiter") @@ -1181,7 +1181,7 @@ def hive_partitioning(self): **Experimental**. This feature is experimental and might change or have limited support. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad.FIELDS.hive_partitioning_options """ prop = self._get_sub_prop("hivePartitioningOptions") @@ -1201,9 +1201,9 @@ def hive_partitioning(self, value): @property def ignore_unknown_values(self): - """bool: Ignore extra values not represented in the table schema. + """Optional[bool]: Ignore extra values not represented in the table schema. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad.FIELDS.ignore_unknown_values """ return self._get_sub_prop("ignoreUnknownValues") @@ -1214,9 +1214,9 @@ def ignore_unknown_values(self, value): @property def max_bad_records(self): - """int: Number of invalid rows to ignore. + """Optional[int]: Number of invalid rows to ignore. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad.FIELDS.max_bad_records """ return _helpers._int_or_none(self._get_sub_prop("maxBadRecords")) @@ -1227,9 +1227,9 @@ def max_bad_records(self, value): @property def null_marker(self): - """str: Represents a null value (CSV only). + """Optional[str]: Represents a null value (CSV only). - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad.FIELDS.null_marker """ return self._get_sub_prop("nullMarker") @@ -1240,9 +1240,9 @@ def null_marker(self, value): @property def quote_character(self): - """str: Character used to quote data sections (CSV only). + """Optional[str]: Character used to quote data sections (CSV only). - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad.FIELDS.quote """ return self._get_sub_prop("quote") @@ -1287,12 +1287,12 @@ def range_partitioning(self, value): @property def schema(self): - """Sequence[Union[ \ + """Optional[Sequence[Union[ \ :class:`~google.cloud.bigquery.schema.SchemaField`, \ Mapping[str, Any] \ - ]]: Schema of the destination table. + ]]]: Schema of the destination table. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad.FIELDS.schema """ schema = _helpers._get_sub_prop(self._properties, ["load", "schema", "fields"]) @@ -1316,7 +1316,7 @@ def schema(self, value): @property def schema_update_options(self): - """List[google.cloud.bigquery.job.SchemaUpdateOption]: Specifies + """Optional[List[google.cloud.bigquery.job.SchemaUpdateOption]]: Specifies updates to the destination table schema to allow as a side effect of the load job. """ @@ -1328,9 +1328,9 @@ def schema_update_options(self, values): @property def skip_leading_rows(self): - """int: Number of rows to skip when reading data (CSV only). + """Optional[int]: Number of rows to skip when reading data (CSV only). - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad.FIELDS.skip_leading_rows """ return _helpers._int_or_none(self._get_sub_prop("skipLeadingRows")) @@ -1341,9 +1341,9 @@ def skip_leading_rows(self, value): @property def source_format(self): - """google.cloud.bigquery.job.SourceFormat: File format of the data. + """Optional[google.cloud.bigquery.job.SourceFormat]: File format of the data. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad.FIELDS.source_format """ return self._get_sub_prop("sourceFormat") @@ -1354,7 +1354,7 @@ def source_format(self, value): @property def time_partitioning(self): - """google.cloud.bigquery.table.TimePartitioning: Specifies time-based + """Optional[google.cloud.bigquery.table.TimePartitioning]: Specifies time-based partitioning for the destination table. Only specify at most one of @@ -1377,7 +1377,7 @@ def time_partitioning(self, value): @property def use_avro_logical_types(self): - """bool: For loads of Avro data, governs whether Avro logical types are + """Optional[bool]: For loads of Avro data, governs whether Avro logical types are converted to their corresponding BigQuery types (e.g. TIMESTAMP) rather than raw types (e.g. INTEGER). """ @@ -1389,10 +1389,10 @@ def use_avro_logical_types(self, value): @property def write_disposition(self): - """google.cloud.bigquery.job.WriteDisposition: Action that occurs if + """Optional[google.cloud.bigquery.job.WriteDisposition]: Action that occurs if the destination table already exists. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad.FIELDS.write_disposition """ return self._get_sub_prop("writeDisposition") @@ -1792,8 +1792,8 @@ class CopyJob(_AsyncJob): A client which holds credentials and project configuration for the dataset (which requires a project). - job_config (google.cloud.bigquery.job.CopyJobConfig): - (Optional) Extra configuration options for the copy job. + job_config (Optional[google.cloud.bigquery.job.CopyJobConfig]): + Extra configuration options for the copy job. """ _JOB_TYPE = "copy" @@ -2003,8 +2003,8 @@ class ExtractJob(_AsyncJob): client (google.cloud.bigquery.client.Client): A client which holds credentials and project configuration. - job_config (google.cloud.bigquery.job.ExtractJobConfig): - (Optional) Extra configuration options for the extract job. + job_config (Optional[google.cloud.bigquery.job.ExtractJobConfig]): + Extra configuration options for the extract job. """ _JOB_TYPE = "extract" @@ -2593,8 +2593,8 @@ class QueryJob(_AsyncJob): A client which holds credentials and project configuration for the dataset (which requires a project). - job_config (google.cloud.bigquery.job.QueryJobConfig): - (Optional) Extra configuration options for the query job. + job_config (Optional[google.cloud.bigquery.job.QueryJobConfig]): + Extra configuration options for the query job. """ _JOB_TYPE = "query" @@ -3274,19 +3274,19 @@ def to_arrow( ``'tqdm_gui'`` Use the :func:`tqdm.tqdm_gui` function to display a progress bar as a graphical dialog box. - bqstorage_client (google.cloud.bigquery_storage_v1.BigQueryReadClient): - Optional. A BigQuery Storage API client. If supplied, use the - faster BigQuery Storage API to fetch rows from BigQuery. - This API is a billable API. + bqstorage_client (Optional[google.cloud.bigquery_storage_v1.BigQueryReadClient]): + A BigQuery Storage API client. If supplied, use the faster + BigQuery Storage API to fetch rows from BigQuery. This API + is a billable API. This method requires the ``pyarrow`` and ``google-cloud-bigquery-storage`` libraries. Reading from a specific partition or snapshot is not currently supported by this method. - create_bqstorage_client (bool): - Optional. If ``True`` (default), create a BigQuery Storage API - client using the default API settings. The BigQuery Storage API + create_bqstorage_client (Optional[bool]): + If ``True`` (default), create a BigQuery Storage API client + using the default API settings. The BigQuery Storage API is a faster way to fetch rows from BigQuery. See the ``bqstorage_client`` parameter for more information. @@ -3325,9 +3325,9 @@ def to_dataframe( """Return a pandas DataFrame from a QueryJob Args: - bqstorage_client (google.cloud.bigquery_storage_v1.BigQueryReadClient): - Optional. A BigQuery Storage API client. If supplied, use the - faster BigQuery Storage API to fetch rows from BigQuery. This + bqstorage_client (Optional[google.cloud.bigquery_storage_v1.BigQueryReadClient]): + A BigQuery Storage API client. If supplied, use the faster + BigQuery Storage API to fetch rows from BigQuery. This API is a billable API. This method requires the ``fastavro`` and @@ -3336,11 +3336,11 @@ def to_dataframe( Reading from a specific partition or snapshot is not currently supported by this method. - dtypes (Map[str, Union[str, pandas.Series.dtype]]): - Optional. A dictionary of column names pandas ``dtype``s. The - provided ``dtype`` is used when constructing the series for - the column specified. Otherwise, the default pandas behavior - is used. + dtypes (Optional[Map[str, Union[str, pandas.Series.dtype]]]): + A dictionary of column names pandas ``dtype``s. The provided + ``dtype`` is used when constructing the series for the column + specified. Otherwise, the default pandas behavior is used. + progress_bar_type (Optional[str]): If set, use the `tqdm `_ library to display a progress bar while the data downloads. Install the diff --git a/google/cloud/bigquery/magics.py b/google/cloud/bigquery/magics.py index 40dda3d13..7128e32bf 100644 --- a/google/cloud/bigquery/magics.py +++ b/google/cloud/bigquery/magics.py @@ -26,31 +26,31 @@ Parameters: - * ```` (optional, line argument): + * ```` (Optional[line argument]): variable to store the query results. The results are not displayed if this parameter is used. If an error occurs during the query execution, the corresponding ``QueryJob`` instance (if available) is stored in the variable instead. - * ``--destination_table`` (optional, line argument): + * ``--destination_table`` (Optional[line argument]): A dataset and table to store the query results. If table does not exists, it will be created. If table already exists, its data will be overwritten. Variable should be in a format .. - * ``--project `` (optional, line argument): + * ``--project `` (Optional[line argument]): Project to use for running the query. Defaults to the context :attr:`~google.cloud.bigquery.magics.Context.project`. - * ``--use_bqstorage_api`` (optional, line argument): + * ``--use_bqstorage_api`` (Optional[line argument]): [Deprecated] Not used anymore, as BigQuery Storage API is used by default. - * ``--use_rest_api`` (optional, line argument): + * ``--use_rest_api`` (Optional[line argument]): Use the BigQuery REST API instead of the Storage API. - * ``--use_legacy_sql`` (optional, line argument): + * ``--use_legacy_sql`` (Optional[line argument]): Runs the query using Legacy SQL syntax. Defaults to Standard SQL if this argument not used. - * ``--verbose`` (optional, line argument): + * ``--verbose`` (Optional[line argument]): If this flag is used, information including the query job ID and the amount of time for the query to complete will not be cleared after the query is finished. By default, this information will be displayed but will be cleared after the query is finished. - * ``--params `` (optional, line argument): + * ``--params `` (Optional[line argument]): If present, the argument following the ``--params`` flag must be either: @@ -304,7 +304,7 @@ def _run_query(client, query, job_config=None): query (str): SQL query to be executed. Defaults to the standard SQL dialect. Use the ``job_config`` parameter to change dialects. - job_config (google.cloud.bigquery.job.QueryJobConfig, optional): + job_config (Optional[google.cloud.bigquery.job.QueryJobConfig]): Extra configuration options for the job. Returns: diff --git a/google/cloud/bigquery/model.py b/google/cloud/bigquery/model.py index eb459f57a..d3fe8a937 100644 --- a/google/cloud/bigquery/model.py +++ b/google/cloud/bigquery/model.py @@ -228,7 +228,7 @@ def description(self, value): @property def friendly_name(self): - """Union[str, None]: Title of the table (defaults to :data:`None`). + """Optional[str]: Title of the table (defaults to :data:`None`). Raises: ValueError: For invalid value types. @@ -241,7 +241,7 @@ def friendly_name(self, value): @property def labels(self): - """Dict[str, str]: Labels for the table. + """Optional[Dict[str, str]]: Labels for the table. This method always returns a dict. To change a model's labels, modify the dict, then call ``Client.update_model``. To delete a @@ -257,7 +257,7 @@ def labels(self, value): @property def encryption_configuration(self): - """google.cloud.bigquery.encryption_configuration.EncryptionConfiguration: Custom + """Optional[google.cloud.bigquery.encryption_configuration.EncryptionConfiguration]: Custom encryption configuration for the model. Custom encryption configuration (e.g., Cloud KMS keys) or :data:`None` @@ -383,9 +383,9 @@ def from_string(cls, model_id, default_project=None): A model ID in standard SQL format. If ``default_project`` is not specified, this must included a project ID, dataset ID, and model ID, each separated by ``.``. - default_project (str): - Optional. The project ID to use when ``model_id`` does not - include a project ID. + default_project (Optional[str]): + The project ID to use when ``model_id`` does not include + a project ID. Returns: google.cloud.bigquery.model.ModelReference: diff --git a/google/cloud/bigquery/query.py b/google/cloud/bigquery/query.py index 925f3e29d..0f4c80686 100644 --- a/google/cloud/bigquery/query.py +++ b/google/cloud/bigquery/query.py @@ -27,11 +27,11 @@ class UDFResource(object): """Describe a single user-defined function (UDF) resource. Args: - udf_type (str): the type of the resource ('inlineCode' or 'resourceUri') + udf_type (str): The type of the resource ('inlineCode' or 'resourceUri') - value (str): the inline code or resource URI. + value (str): The inline code or resource URI. - See + See: https://cloud.google.com/bigquery/user-defined-functions#api """ @@ -82,12 +82,12 @@ class ScalarQueryParameter(_AbstractQueryParameter): parameter can only be addressed via position (``?``). type_ (str): - name of parameter type. One of 'STRING', 'INT64', + Name of parameter type. One of 'STRING', 'INT64', 'FLOAT64', 'NUMERIC', 'BOOL', 'TIMESTAMP', 'DATETIME', or 'DATE'. value (Union[str, int, float, decimal.Decimal, bool, - datetime.datetime, datetime.date]): the scalar parameter value. + datetime.datetime, datetime.date]): The scalar parameter value. """ def __init__(self, name, type_, value): @@ -101,16 +101,16 @@ def positional(cls, type_, value): Args: type_ (str): - name of parameter type. One of 'STRING', 'INT64', + Name of parameter type. One of 'STRING', 'INT64', 'FLOAT64', 'NUMERIC', 'BOOL', 'TIMESTAMP', 'DATETIME', or 'DATE'. value (Union[str, int, float, decimal.Decimal, bool, datetime.datetime, - datetime.date]): the scalar parameter value. + datetime.date]): The scalar parameter value. Returns: - google.cloud.bigquery.query.ScalarQueryParameter: instance without name + google.cloud.bigquery.query.ScalarQueryParameter: Instance without name """ return cls(None, type_, value) @@ -122,7 +122,7 @@ def from_api_repr(cls, resource): resource (Dict): JSON mapping of parameter Returns: - google.cloud.bigquery.query.ScalarQueryParameter: instance + google.cloud.bigquery.query.ScalarQueryParameter: Instance """ name = resource.get("name") type_ = resource["parameterType"]["type"] @@ -186,10 +186,10 @@ class ArrayQueryParameter(_AbstractQueryParameter): parameter can only be addressed via position (``?``). array_type (str): - name of type of array elements. One of `'STRING'`, `'INT64'`, + Name of type of array elements. One of `'STRING'`, `'INT64'`, `'FLOAT64'`, `'NUMERIC'`, `'BOOL'`, `'TIMESTAMP'`, or `'DATE'`. - values (List[appropriate scalar type]): the parameter array values. + values (List[appropriate scalar type]): The parameter array values. """ def __init__(self, name, array_type, values): @@ -203,13 +203,13 @@ def positional(cls, array_type, values): Args: array_type (str): - name of type of array elements. One of `'STRING'`, `'INT64'`, + Name of type of array elements. One of `'STRING'`, `'INT64'`, `'FLOAT64'`, `'NUMERIC'`, `'BOOL'`, `'TIMESTAMP'`, or `'DATE'`. - values (List[appropriate scalar type]): the parameter array values. + values (List[appropriate scalar type]): The parameter array values. Returns: - google.cloud.bigquery.query.ArrayQueryParameter: instance without name + google.cloud.bigquery.query.ArrayQueryParameter: Instance without name """ return cls(None, array_type, values) @@ -250,7 +250,7 @@ def from_api_repr(cls, resource): resource (Dict): JSON mapping of parameter Returns: - google.cloud.bigquery.query.ArrayQueryParameter: instance + google.cloud.bigquery.query.ArrayQueryParameter: Instance """ array_type = resource["parameterType"]["arrayType"]["type"] if array_type == "STRUCT": @@ -316,7 +316,7 @@ class StructQueryParameter(_AbstractQueryParameter): google.cloud.bigquery.query.ScalarQueryParameter, google.cloud.bigquery.query.ArrayQueryParameter, google.cloud.bigquery.query.StructQueryParameter - ]]): the sub-parameters for the struct + ]]): The sub-parameters for the struct """ def __init__(self, name, *sub_params): @@ -343,10 +343,10 @@ def positional(cls, *sub_params): google.cloud.bigquery.query.ScalarQueryParameter, google.cloud.bigquery.query.ArrayQueryParameter, google.cloud.bigquery.query.StructQueryParameter - ]]): the sub-parameters for the struct + ]]): The sub-parameters for the struct Returns: - google.cloud.bigquery.query.StructQueryParameter: instance without name + google.cloud.bigquery.query.StructQueryParameter: Instance without name """ return cls(None, *sub_params) @@ -358,7 +358,7 @@ def from_api_repr(cls, resource): resource (Dict): JSON mapping of parameter Returns: - google.cloud.bigquery.query.StructQueryParameter: instance + google.cloud.bigquery.query.StructQueryParameter: Instance """ name = resource.get("name") instance = cls(name) @@ -473,7 +473,7 @@ def project(self): def cache_hit(self): """Query results served from cache. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query#body.QueryResponse.FIELDS.cache_hit Returns: @@ -487,7 +487,7 @@ def cache_hit(self): def complete(self): """Server completed query. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query#body.QueryResponse.FIELDS.job_complete Returns: @@ -501,7 +501,7 @@ def complete(self): def errors(self): """Errors generated by the query. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query#body.QueryResponse.FIELDS.errors Returns: @@ -515,7 +515,7 @@ def errors(self): def job_id(self): """Job ID of the query job these results are from. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query#body.QueryResponse.FIELDS.job_reference Returns: @@ -527,7 +527,7 @@ def job_id(self): def page_token(self): """Token for fetching next bach of results. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query#body.QueryResponse.FIELDS.page_token Returns: @@ -539,7 +539,7 @@ def page_token(self): def total_rows(self): """Total number of rows returned by the query. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query#body.QueryResponse.FIELDS.total_rows Returns: @@ -553,7 +553,7 @@ def total_rows(self): def total_bytes_processed(self): """Total number of bytes processed by the query. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query#body.QueryResponse.FIELDS.total_bytes_processed Returns: @@ -567,7 +567,7 @@ def total_bytes_processed(self): def num_dml_affected_rows(self): """Total number of rows affected by a DML query. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query#body.QueryResponse.FIELDS.num_dml_affected_rows Returns: @@ -581,7 +581,7 @@ def num_dml_affected_rows(self): def rows(self): """Query results. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query#body.QueryResponse.FIELDS.rows Returns: @@ -594,7 +594,7 @@ def rows(self): def schema(self): """Schema for query results. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query#body.QueryResponse.FIELDS.schema Returns: @@ -607,7 +607,7 @@ def _set_properties(self, api_response): """Update properties from resource in body of ``api_response`` Args: - api_response (Dict): response returned from an API call + api_response (Dict): Response returned from an API call """ job_id_present = ( "jobReference" in api_response @@ -622,7 +622,7 @@ def _set_properties(self, api_response): def _query_param_from_api_repr(resource): - """Helper: construct concrete query parameter from JSON resource.""" + """Helper: Construct concrete query parameter from JSON resource.""" qp_type = resource["parameterType"] if "arrayType" in qp_type: klass = ArrayQueryParameter diff --git a/google/cloud/bigquery/routine.py b/google/cloud/bigquery/routine.py index e99d9c6fa..03423c01b 100644 --- a/google/cloud/bigquery/routine.py +++ b/google/cloud/bigquery/routine.py @@ -288,7 +288,7 @@ def __repr__(self): class RoutineArgument(object): """Input/output argument of a function or a stored procedure. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/routines#argument Args: @@ -411,7 +411,7 @@ def __repr__(self): class RoutineReference(object): """A pointer to a routine. - See + See: https://cloud.google.com/bigquery/docs/reference/rest/v2/routines#routinereference """ @@ -467,8 +467,8 @@ def from_string(cls, routine_id, default_project=None): A routine ID in standard SQL format. If ``default_project`` is not specified, this must included a project ID, dataset ID, and routine ID, each separated by ``.``. - default_project (str): - Optional. The project ID to use when ``routine_id`` does not + default_project (Optional[str]): + The project ID to use when ``routine_id`` does not include a project ID. Returns: diff --git a/google/cloud/bigquery/schema.py b/google/cloud/bigquery/schema.py index 0eaf1201b..c1b2588be 100644 --- a/google/cloud/bigquery/schema.py +++ b/google/cloud/bigquery/schema.py @@ -50,18 +50,18 @@ class SchemaField(object): """Describe a single field within a table schema. Args: - name (str): the name of the field. + name (str): The name of the field. - field_type (str): the type of the field. See + field_type (str): The type of the field. See https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#TableFieldSchema.FIELDS.type - mode (str): the mode of the field. See + mode (Optional[str]): The mode of the field. See https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#TableFieldSchema.FIELDS.mode - description (Optional[str]): description for the field. + description (Optional[str]): Description for the field. - fields (Tuple[google.cloud.bigquery.schema.SchemaField]): - subfields (requires ``field_type`` of 'RECORD'). + fields (Optional[Tuple[google.cloud.bigquery.schema.SchemaField]]): + Subfields (requires ``field_type`` of 'RECORD'). policy_tags (Optional[PolicyTagList]): The policy tag list for the field. @@ -125,7 +125,7 @@ def field_type(self): @property def mode(self): - """str: The mode of the field. + """Optional[str]: The mode of the field. See: https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#TableFieldSchema.FIELDS.mode @@ -144,7 +144,7 @@ def description(self): @property def fields(self): - """tuple: Subfields contained in this field. + """Optional[tuple]: Subfields contained in this field. Must be empty unset if ``field_type`` is not 'RECORD'. """ diff --git a/google/cloud/bigquery/table.py b/google/cloud/bigquery/table.py index 5f557d28a..5766f5fbe 100644 --- a/google/cloud/bigquery/table.py +++ b/google/cloud/bigquery/table.py @@ -166,8 +166,8 @@ def from_string(cls, table_id, default_project=None): A table ID in standard SQL format. If ``default_project`` is not specified, this must included a project ID, dataset ID, and table ID, each separated by ``.``. - default_project (str): - Optional. The project ID to use when ``table_id`` does not + default_project (Optional[str]): + The project ID to use when ``table_id`` does not include a project ID. Returns: @@ -1322,20 +1322,20 @@ class RowIterator(HTTPIterator): :meth:`~google.cloud.bigquery.schema.SchemaField.from_api_repr`. page_token (str): A token identifying a page in a result set to start fetching results from. - max_results (int, optional): The maximum number of results to fetch. - page_size (int, optional): The maximum number of rows in each page + max_results (Optional[int]): The maximum number of results to fetch. + page_size (Optional[int]): The maximum number of rows in each page of results from this request. Non-positive values are ignored. Defaults to a sensible value set by the API. - extra_params (Dict[str, object]): + extra_params (Optional[Dict[str, object]]): Extra query string parameters for the API call. - table (Union[ \ + table (Optional[Union[ \ google.cloud.bigquery.table.Table, \ google.cloud.bigquery.table.TableReference, \ - ]): - Optional. The table which these rows belong to, or a reference to - it. Used to call the BigQuery Storage API to fetch rows. - selected_fields (Sequence[google.cloud.bigquery.schema.SchemaField]): - Optional. A subset of columns to select from this table. + ]]): + The table which these rows belong to, or a reference to it. Used to + call the BigQuery Storage API to fetch rows. + selected_fields (Optional[Sequence[google.cloud.bigquery.schema.SchemaField]]): + A subset of columns to select from this table. """ @@ -1487,10 +1487,9 @@ def to_arrow( ``'tqdm_gui'`` Use the :func:`tqdm.tqdm_gui` function to display a progress bar as a graphical dialog box. - bqstorage_client (google.cloud.bigquery_storage_v1.BigQueryReadClient): - Optional. A BigQuery Storage API client. If supplied, use the - faster BigQuery Storage API to fetch rows from BigQuery. This - API is a billable API. + bqstorage_client (Optional[google.cloud.bigquery_storage_v1.BigQueryReadClient]): + A BigQuery Storage API client. If supplied, use the faster BigQuery + Storage API to fetch rows from BigQuery. This API is a billable API. This method requires the ``pyarrow`` and ``google-cloud-bigquery-storage`` libraries. @@ -1498,11 +1497,11 @@ def to_arrow( This method only exposes a subset of the capabilities of the BigQuery Storage API. For full access to all features (projections, filters, snapshots) use the Storage API directly. - create_bqstorage_client (bool): - Optional. If ``True`` (default), create a BigQuery Storage API - client using the default API settings. The BigQuery Storage API - is a faster way to fetch rows from BigQuery. See the - ``bqstorage_client`` parameter for more information. + create_bqstorage_client (Optional[bool]): + If ``True`` (default), create a BigQuery Storage API client using + the default API settings. The BigQuery Storage API is a faster way + to fetch rows from BigQuery. See the ``bqstorage_client`` parameter + for more information. This argument does nothing if ``bqstorage_client`` is supplied. @@ -1572,9 +1571,9 @@ def to_dataframe_iterable(self, bqstorage_client=None, dtypes=None): """Create an iterable of pandas DataFrames, to process the table as a stream. Args: - bqstorage_client (google.cloud.bigquery_storage_v1.BigQueryReadClient): - Optional. A BigQuery Storage API client. If supplied, use the - faster BigQuery Storage API to fetch rows from BigQuery. + bqstorage_client (Optional[google.cloud.bigquery_storage_v1.BigQueryReadClient]): + A BigQuery Storage API client. If supplied, use the faster + BigQuery Storage API to fetch rows from BigQuery. This method requires the ``pyarrow`` and ``google-cloud-bigquery-storage`` libraries. @@ -1583,11 +1582,10 @@ def to_dataframe_iterable(self, bqstorage_client=None, dtypes=None): BigQuery Storage API. For full access to all features (projections, filters, snapshots) use the Storage API directly. - dtypes (Map[str, Union[str, pandas.Series.dtype]]): - Optional. A dictionary of column names pandas ``dtype``s. The - provided ``dtype`` is used when constructing the series for - the column specified. Otherwise, the default pandas behavior - is used. + dtypes (Optional[Map[str, Union[str, pandas.Series.dtype]]]): + A dictionary of column names pandas ``dtype``s. The provided + ``dtype`` is used when constructing the series for the column + specified. Otherwise, the default pandas behavior is used. Returns: pandas.DataFrame: @@ -1638,9 +1636,9 @@ def to_dataframe( """Create a pandas DataFrame by loading all pages of a query. Args: - bqstorage_client (google.cloud.bigquery_storage_v1.BigQueryReadClient): - Optional. A BigQuery Storage API client. If supplied, use the - faster BigQuery Storage API to fetch rows from BigQuery. + bqstorage_client (Optional[google.cloud.bigquery_storage_v1.BigQueryReadClient]): + A BigQuery Storage API client. If supplied, use the faster + BigQuery Storage API to fetch rows from BigQuery. This method requires the ``pyarrow`` and ``google-cloud-bigquery-storage`` libraries. @@ -1649,11 +1647,10 @@ def to_dataframe( BigQuery Storage API. For full access to all features (projections, filters, snapshots) use the Storage API directly. - dtypes (Map[str, Union[str, pandas.Series.dtype]]): - Optional. A dictionary of column names pandas ``dtype``s. The - provided ``dtype`` is used when constructing the series for - the column specified. Otherwise, the default pandas behavior - is used. + dtypes (Optional[Map[str, Union[str, pandas.Series.dtype]]]): + A dictionary of column names pandas ``dtype``s. The provided + ``dtype`` is used when constructing the series for the column + specified. Otherwise, the default pandas behavior is used. progress_bar_type (Optional[str]): If set, use the `tqdm `_ library to display a progress bar while the data downloads. Install the @@ -1789,7 +1786,7 @@ def to_arrow( """[Beta] Create an empty class:`pyarrow.Table`. Args: - progress_bar_type (Optional[str]): Ignored. Added for compatibility with RowIterator. + progress_bar_type (str): Ignored. Added for compatibility with RowIterator. bqstorage_client (Any): Ignored. Added for compatibility with RowIterator. create_bqstorage_client (bool): Ignored. Added for compatibility with RowIterator. @@ -1983,19 +1980,19 @@ class TimePartitioning(object): """Configures time-based partitioning for a table. Args: - type_ (google.cloud.bigquery.table.TimePartitioningType, optional): + type_ (Optional[google.cloud.bigquery.table.TimePartitioningType]): Specifies the type of time partitioning to perform. Defaults to :attr:`~google.cloud.bigquery.table.TimePartitioningType.DAY`, which is the only currently supported type. - field (str, optional): + field (Optional[str]): If set, the table is partitioned by this field. If not set, the table is partitioned by pseudo column ``_PARTITIONTIME``. The field must be a top-level ``TIMESTAMP`` or ``DATE`` field. Its mode must be ``NULLABLE`` or ``REQUIRED``. - expiration_ms(int, optional): + expiration_ms(Optional[int]): Number of milliseconds for which to keep the storage for a partition. - require_partition_filter (bool, optional): + require_partition_filter (Optional[bool]): DEPRECATED: Use :attr:`~google.cloud.bigquery.table.Table.require_partition_filter`, instead.