Skip to content

docs: fix links in blob module #759

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’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 12, 2022
Merged

docs: fix links in blob module #759

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
74efa04
docs: fix links in blob
cojenco Apr 7, 2022
e4f3fea
Merge branch 'main' into blob-links
cojenco Apr 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 29 additions & 40 deletions google/cloud/storage/blob.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,14 +15,6 @@
# pylint: disable=too-many-lines

"""Create / interact with Google Cloud Storage blobs.

.. _API reference docs: https://cloud.google.com/storage/docs/\
json_api/v1/objects
.. _customer-supplied: https://cloud.google.com/storage/docs/\
encryption#customer-supplied
.. _google-resumable-media: https://googleapis.github.io/\
google-resumable-media-python/latest/\
google.resumable_media.requests.html
"""

import base64
Expand Down Expand Up @@ -1048,7 +1040,8 @@ def download_to_file(
If the server-set property, :attr:`media_link`, is not yet
initialized, makes an additional API request to load it.

Downloading a file that has been encrypted with a `customer-supplied`_
Downloading a file that has been encrypted with a
[`customer-supplied`](https://cloud.google.com/storage/docs/encryption#customer-supplied)
encryption key:

.. literalinclude:: snippets.py
Expand All @@ -1064,8 +1057,8 @@ def download_to_file(
of data in each request.

For more fine-grained control over the download process, check out
`google-resumable-media`_. For example, this library allows
downloading **parts** of a blob rather than the whole thing.
[`google-resumable-media`](https://googleapis.dev/python/google-resumable-media/latest/index.html).
For example, this library allows downloading **parts** of a blob rather than the whole thing.

If :attr:`user_project` is set on the bucket, bills the API request
to that project.
Expand Down Expand Up @@ -1694,8 +1687,8 @@ def _get_writable_metadata(self):

This is intended to be used when creating a new object / blob.

See the `API reference docs`_ for more information, the fields
marked as writable are:
See the [`API reference docs`](https://cloud.google.com/storage/docs/json_api/v1/objects)
for more information, the fields marked as writable are:

* ``acl``
* ``cacheControl``
Expand Down Expand Up @@ -2445,7 +2438,8 @@ def upload_from_file(
See the `object versioning`_ and `lifecycle`_ API documents
for details.

Uploading a file with a `customer-supplied`_ encryption key:
Uploading a file with a
[`customer-supplied`](https://cloud.google.com/storage/docs/encryption#customer-supplied) encryption key:

.. literalinclude:: snippets.py
:start-after: [START upload_from_file]
Expand All @@ -2460,7 +2454,7 @@ def upload_from_file(
uploaded in a single multipart upload request.

For more fine-grained over the upload process, check out
`google-resumable-media`_.
[`google-resumable-media`](https://googleapis.dev/python/google-resumable-media/latest/index.html).

If :attr:`user_project` is set on the bucket, bills the API request
to that project.
Expand Down Expand Up @@ -2911,7 +2905,8 @@ def create_resumable_upload_session(
API documents for details.

If :attr:`encryption_key` is set, the blob will be encrypted with
a `customer-supplied`_ encryption key.
a [`customer-supplied`](https://cloud.google.com/storage/docs/encryption#customer-supplied)
encryption key.

If :attr:`user_project` is set on the bucket, bills the API request
to that project.
Expand Down Expand Up @@ -3931,51 +3926,47 @@ def open(
cache_control = _scalar_property("cacheControl")
"""HTTP 'Cache-Control' header for this object.

See `RFC 7234`_ and `API reference docs`_.
See [`RFC 7234`](https://tools.ietf.org/html/rfc7234#section-5.2)
and [`API reference docs`](https://cloud.google.com/storage/docs/json_api/v1/objects).

:rtype: str or ``NoneType``

.. _RFC 7234: https://tools.ietf.org/html/rfc7234#section-5.2
"""

content_disposition = _scalar_property("contentDisposition")
"""HTTP 'Content-Disposition' header for this object.

See `RFC 6266`_ and `API reference docs`_.
See [`RFC 6266`](https://tools.ietf.org/html/rfc7234#section-5.2) and
[`API reference docs`](https://cloud.google.com/storage/docs/json_api/v1/objects).

:rtype: str or ``NoneType``

.. _RFC 6266: https://tools.ietf.org/html/rfc7234#section-5.2
"""

content_encoding = _scalar_property("contentEncoding")
"""HTTP 'Content-Encoding' header for this object.

See `RFC 7231`_ and `API reference docs`_.
See [`RFC 7231`](https://tools.ietf.org/html/rfc7231#section-3.1.2.2) and
[`API reference docs`](https://cloud.google.com/storage/docs/json_api/v1/objects).

:rtype: str or ``NoneType``

.. _RFC 7231: https://tools.ietf.org/html/rfc7231#section-3.1.2.2
"""

content_language = _scalar_property("contentLanguage")
"""HTTP 'Content-Language' header for this object.

See `BCP47`_ and `API reference docs`_.
See [`BCP47`](https://tools.ietf.org/html/bcp47) and
[`API reference docs`](https://cloud.google.com/storage/docs/json_api/v1/objects).

:rtype: str or ``NoneType``

.. _BCP47: https://tools.ietf.org/html/bcp47
"""

content_type = _scalar_property(_CONTENT_TYPE_FIELD)
"""HTTP 'Content-Type' header for this object.

See `RFC 2616`_ and `API reference docs`_.
See [`RFC 2616`](https://tools.ietf.org/html/rfc2616#section-14.17) and
[`API reference docs`](https://cloud.google.com/storage/docs/json_api/v1/objects).

:rtype: str or ``NoneType``

.. _RFC 2616: https://tools.ietf.org/html/rfc2616#section-14.17
"""

crc32c = _scalar_property("crc32c")
Expand All @@ -3984,13 +3975,13 @@ def open(
This returns the blob's CRC32C checksum. To retrieve the value, first use a
reload method of the Blob class which loads the blob's properties from the server.

See `RFC 4960`_ and `API reference docs`_.
See [`RFC 4960`](https://tools.ietf.org/html/rfc4960#appendix-B) and
[`API reference docs`](https://cloud.google.com/storage/docs/json_api/v1/objects).

If not set before upload, the server will compute the hash.

:rtype: str or ``NoneType``

.. _RFC 4960: https://tools.ietf.org/html/rfc4960#appendix-B

Example:
Retrieve the crc32c hash of blob.
Expand Down Expand Up @@ -4029,20 +4020,19 @@ def component_count(self):
def etag(self):
"""Retrieve the ETag for the object.

See `RFC 2616 (etags)`_ and `API reference docs`_.
See [`RFC 2616 (etags)`](https://tools.ietf.org/html/rfc2616#section-3.11) and
[`API reference docs`](https://cloud.google.com/storage/docs/json_api/v1/objects).

:rtype: str or ``NoneType``
:returns: The blob etag or ``None`` if the blob's resource has not
been loaded from the server.

.. _RFC 2616 (etags): https://tools.ietf.org/html/rfc2616#section-3.11
"""
return self._properties.get("etag")

event_based_hold = _scalar_property("eventBasedHold")
"""Is an event-based hold active on the object?

See `API reference docs`_.
See [`API reference docs`](https://cloud.google.com/storage/docs/json_api/v1/objects).

If the property is not set locally, returns :data:`None`.

Expand Down Expand Up @@ -4083,14 +4073,13 @@ def id(self):
This returns the blob's MD5 hash. To retrieve the value, first use a
reload method of the Blob class which loads the blob's properties from the server.

See `RFC 1321`_ and `API reference docs`_.
See [`RFC 1321`](https://tools.ietf.org/html/rfc1321) and
[`API reference docs`](https://cloud.google.com/storage/docs/json_api/v1/objects).

If not set before upload, the server will compute the hash.

:rtype: str or ``NoneType``

.. _RFC 1321: https://tools.ietf.org/html/rfc1321

Example:
Retrieve the md5 hash of blob.

Expand Down Expand Up @@ -4265,7 +4254,7 @@ def kms_key_name(self, value):
temporary_hold = _scalar_property("temporaryHold")
"""Is a temporary hold active on the object?

See `API reference docs`_.
See [`API reference docs`](https://cloud.google.com/storage/docs/json_api/v1/objects).

If the property is not set locally, returns :data:`None`.

Expand Down