Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

fix: keyword rendering and docstring improvements #1829

Merged
merged 5 commits into from
Feb 27, 2024
Merged

fix: keyword rendering and docstring improvements #1829

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
8803aee
fix: keyword rendering and docstring improvements
kiraksi Feb 25, 2024
9165f62
fix error
kiraksi Feb 26, 2024
e1a67ab
small lint fix
kiraksi Feb 26, 2024
3a89896
Merge branch 'main' into keyword-rendering
chalmerlowe Feb 27, 2024
231fb36
Merge branch 'main' into keyword-rendering
chalmerlowe Feb 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
174 changes: 84 additions & 90 deletions google/cloud/bigquery/client.py
View file
Open in desktop
Expand Up @@ -1716,20 +1716,24 @@ def delete_job_metadata(
:func:`~google.cloud.bigquery.client.Client.cancel_job` instead.

Args:
job_id: Job or job identifier.

Keyword Arguments:
project:
job_id (Union[ \
str, \
LoadJob, \
CopyJob, \
ExtractJob, \
QueryJob \
]): Job or job identifier.
project (Optional[str]):
ID of the project which owns the job (defaults to the client's project).
location:
location (Optional[str]):
Location where the job was run. Ignored if ``job_id`` is a job
object.
retry:
retry (Optional[google.api_core.retry.Retry]):
How to retry the RPC.
timeout:
timeout (Optional[float]):
The number of seconds to wait for the underlying HTTP transport
before using ``retry``.
not_found_ok:
not_found_ok (Optional[bool]):
Defaults to ``False``. If ``True``, ignore "not found" errors
when deleting the job.
"""
Expand Down Expand Up @@ -1970,12 +1974,10 @@ def create_job(
timeout: TimeoutType = DEFAULT_TIMEOUT,
) -> Union[job.LoadJob, job.CopyJob, job.ExtractJob, job.QueryJob]:
"""Create a new job.

Args:
job_config (dict): configuration job representation returned from the API.

Keyword Arguments:
retry (Optional[google.api_core.retry.Retry]):
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``.
Expand Down Expand Up @@ -2066,10 +2068,14 @@ def get_job(
https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/get

Args:
job_id:
job_id (Union[ \
str, \
job.LoadJob, \
job.CopyJob, \
job.ExtractJob, \
job.QueryJob \
]):
Job identifier.

Keyword Arguments:
project (Optional[str]):
ID of the project which owns the job (defaults to the client's project).
location (Optional[str]):
Expand Down Expand Up @@ -2137,8 +2143,6 @@ def cancel_job(
google.cloud.bigquery.job.ExtractJob, \
google.cloud.bigquery.job.QueryJob \
]): Job identifier.

Keyword Arguments:
project (Optional[str]):
ID of the project which owns the job (defaults to the client's project).
location (Optional[str]):
Expand Down Expand Up @@ -2340,8 +2344,6 @@ def load_table_from_uri(
in, this method attempts to create a table reference from a
string using
:func:`google.cloud.bigquery.table.TableReference.from_string`.

Keyword Arguments:
job_id (Optional[str]): Name of the job.
job_id_prefix (Optional[str]):
The user-provided prefix for a randomly generated job ID.
Expand Down Expand Up @@ -2415,39 +2417,42 @@ def load_table_from_file(
returns a :class:`~google.cloud.bigquery.job.LoadJob`.

Args:
file_obj:
file_obj (IO[bytes]):
A file handle opened in binary mode for reading.
destination:
destination (Union[Table, \
TableReference, \
TableListItem, \
str \
]):
Table into which data is to be loaded. 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`.

Keyword Arguments:
rewind:
rewind (Optional[bool]):
If True, seek to the beginning of the file handle before
reading the file.
size:
reading the file. Defaults to False.
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: Number of upload retries. Defaults to 6.
job_id: Name of the job.
job_id_prefix:
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:
location (Optional[str]):
Location where to run the job. Must match the location of the
destination table.
project:
project (Optional[str]):
Project ID of the project of where to run the job. Defaults
to the client's project.
job_config:
job_config (Optional[LoadJobConfig]):
Extra configuration options for the job.
timeout:
timeout (Optional[float]):
The number of seconds to wait for the underlying HTTP transport
before using ``retry``. Depending on the retry strategy, a request
may be repeated several times using the same timeout each time.
Defaults to None.

Can also be passed as a tuple (connect_timeout, read_timeout).
See :meth:`requests.Session.request` documentation for details.
Expand Down Expand Up @@ -2535,9 +2540,13 @@ def load_table_from_dataframe(
https://github.com/googleapis/python-bigquery/issues/19

Args:
dataframe:
dataframe (pandas.Dataframe):
A :class:`~pandas.DataFrame` containing the data to load.
destination:
destination (Union[ \
Table, \
TableReference, \
str \
]):
The destination table to use for loading the data. If it is an
existing table, the schema of the :class:`~pandas.DataFrame`
must match the schema of the destination table. If the table
Expand All @@ -2547,21 +2556,19 @@ def load_table_from_dataframe(
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`.

Keyword Arguments:
num_retries: Number of upload retries.
job_id: Name of the job.
job_id_prefix:
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:
location (Optional[str]):
Location where to run the job. Must match the location of the
destination table.
project:
project (Optional[str]):
Project ID of the project of where to run the job. Defaults
to the client's project.
job_config:
job_config (Optional[LoadJobConfig]):
Extra configuration options for the job.

To override the default pandas data type conversions, supply
Expand All @@ -2578,9 +2585,10 @@ def load_table_from_dataframe(
:attr:`~google.cloud.bigquery.job.SourceFormat.CSV` and
:attr:`~google.cloud.bigquery.job.SourceFormat.PARQUET` are
supported.
parquet_compression:
parquet_compression (Optional[str]):
[Beta] The compression method to use if intermittently
serializing ``dataframe`` to a parquet file.
Defaults to "snappy".

The argument is directly passed as the ``compression``
argument to the underlying ``pyarrow.parquet.write_table()``
Expand All @@ -2591,10 +2599,11 @@ def load_table_from_dataframe(
passed as the ``compression`` argument to the underlying
``DataFrame.to_parquet()`` method.
https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.to_parquet.html#pandas.DataFrame.to_parquet
timeout:
timeout (Optional[flaot]):
The number of seconds to wait for the underlying HTTP transport
before using ``retry``. Depending on the retry strategy, a request may
be repeated several times using the same timeout each time.
Defaults to None.

Can also be passed as a tuple (connect_timeout, read_timeout).
See :meth:`requests.Session.request` documentation for details.
Expand Down Expand Up @@ -2784,32 +2793,36 @@ def load_table_from_json(
client = bigquery.Client()
client.load_table_from_file(data_as_file, ...)

destination:
destination (Union[ \
Table, \
TableReference, \
TableListItem, \
str \
]):
Table into which data is to be loaded. 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`.

Keyword Arguments:
num_retries: Number of upload retries.
job_id: Name of the job.
job_id_prefix:
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:
location (Optional[str]):
Location where to run the job. Must match the location of the
destination table.
project:
project (Optional[str]):
Project ID of the project of where to run the job. Defaults
to the client's project.
job_config:
job_config (Optional[LoadJobConfig]):
Extra configuration options for the job. The ``source_format``
setting is always set to
:attr:`~google.cloud.bigquery.job.SourceFormat.NEWLINE_DELIMITED_JSON`.
timeout:
timeout (Optional[float]):
The number of seconds to wait for the underlying HTTP transport
before using ``retry``. Depending on the retry strategy, a request may
be repeated several times using the same timeout each time.
Defaults to None.

Can also be passed as a tuple (connect_timeout, read_timeout).
See :meth:`requests.Session.request` documentation for details.
Expand Down Expand Up @@ -2885,23 +2898,19 @@ def _do_resumable_upload(
"""Perform a resumable upload.

Args:
stream: A bytes IO object open for reading.

metadata: The metadata associated with the upload.

num_retries:
stream (IO[bytes]): A bytes IO object open for reading.
metadata (Mapping[str, str]): The metadata associated with the upload.
num_retries (int):
Number of upload retries. (Deprecated: This
argument will be removed in a future release.)

timeout:
timeout (Optional[float]):
The number of seconds to wait for the underlying HTTP transport
before using ``retry``. Depending on the retry strategy, a request may
be repeated several times using the same timeout each time.

Can also be passed as a tuple (connect_timeout, read_timeout).
See :meth:`requests.Session.request` documentation for details.

project:
project (Optional[str]):
Project ID of the project of where to run the upload. Defaults
to the client's project.

Expand Down Expand Up @@ -2929,23 +2938,19 @@ def _initiate_resumable_upload(
"""Initiate a resumable upload.

Args:
stream: A bytes IO object open for reading.

metadata: The metadata associated with the upload.

num_retries:
stream (IO[bytes]): A bytes IO object open for reading.
metadata (Mapping[str, str]): The metadata associated with the upload.
num_retries (int):
Number of upload retries. (Deprecated: This
argument will be removed in a future release.)

timeout:
timeout (Optional[float]):
The number of seconds to wait for the underlying HTTP transport
before using ``retry``. Depending on the retry strategy, a request may
be repeated several times using the same timeout each time.

Can also be passed as a tuple (connect_timeout, read_timeout).
See :meth:`requests.Session.request` documentation for details.

project:
project (Optional[str]):
Project ID of the project of where to run the upload. Defaults
to the client's project.

Expand Down Expand Up @@ -3005,28 +3010,23 @@ def _do_multipart_upload(
"""Perform a multipart upload.

Args:
stream: A bytes IO object open for reading.

metadata: The metadata associated with the upload.

size:
stream (IO[bytes]): A bytes IO object open for reading.
metadata (Mapping[str, str]): The metadata associated with the upload.
size (int):
The number of bytes to be uploaded (which will be read
from ``stream``). If not provided, the upload will be
concluded once ``stream`` is exhausted (or :data:`None`).

num_retries:
num_retries (int):
Number of upload retries. (Deprecated: This
argument will be removed in a future release.)

timeout:
timeout (Optional[float]):
The number of seconds to wait for the underlying HTTP transport
before using ``retry``. Depending on the retry strategy, a request may
be repeated several times using the same timeout each time.

Can also be passed as a tuple (connect_timeout, read_timeout).
See :meth:`requests.Session.request` documentation for details.

project:
project (Optional[str]):
Project ID of the project of where to run the upload. Defaults
to the client's project.

Expand Down Expand Up @@ -3118,8 +3118,6 @@ def copy_table(
str, \
]):
Table into which data is to be copied.

Keyword Arguments:
job_id (Optional[str]): The ID of the job.
job_id_prefix (Optional[str]):
The user-provided prefix for a randomly generated job ID.
Expand Down Expand Up @@ -3216,8 +3214,6 @@ def extract_table(
URIs of Cloud Storage file(s) into which table data is to be
extracted; in format
``gs://<bucket_name>/<object_name_or_glob>``.

Keyword Arguments:
job_id (Optional[str]): The ID of the job.
job_id_prefix (Optional[str]):
The user-provided prefix for a randomly generated job ID.
Expand Down Expand Up @@ -3306,8 +3302,6 @@ def query(
query (str):
SQL query to be executed. Defaults to the standard SQL
dialect. Use the ``job_config`` parameter to change dialects.

Keyword Arguments:
job_config (Optional[google.cloud.bigquery.job.QueryJobConfig]):
Extra configuration options for the job.
To override any options that were previously set in
Expand Down