From b807a0047c4a9d6a6f2fb80b82d8b1bb8e6d48f4 Mon Sep 17 00:00:00 2001 From: Danny Hermes Date: Tue, 16 May 2017 09:31:15 -0700 Subject: [PATCH] Clean up a documentation for the storage blob module. (#3376) Many of the links were formatted incorrectly, etc. --- storage/google/cloud/storage/blob.py | 104 ++++++++++++++++----------- 1 file changed, 61 insertions(+), 43 deletions(-) diff --git a/storage/google/cloud/storage/blob.py b/storage/google/cloud/storage/blob.py index b52092072d1e..eb57c34c6ebb 100644 --- a/storage/google/cloud/storage/blob.py +++ b/storage/google/cloud/storage/blob.py @@ -14,7 +14,16 @@ # pylint: disable=too-many-lines -"""Create / interact with Google Cloud Storage blobs.""" +"""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://googlecloudplatform.github.io/\ + google-resumable-media-python/latest/\ + google.resumable_media.requests.html +""" import base64 import copy @@ -427,18 +436,20 @@ def download_to_file(self, file_obj, client=None): 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`_ - encryption key: + Downloading a file that has been encrypted with a `customer-supplied`_ + encryption key: .. literalinclude:: storage_snippets.py :start-after: [START download_to_file] :end-before: [END download_to_file] + :dedent: 4 The ``encryption_key`` should be a str or bytes with a length of at least 32. - .. _customer-supplied: https://cloud.google.com/storage/docs/\ - encryption#customer-supplied + For more fine-grained over the download process, check out + `google-resumable-media`_. For example, this library allows + downloading **parts** of a blob rather than the whole thing. :type file_obj: file :param file_obj: A file handle to which to write the blob's data. @@ -531,8 +542,8 @@ def _get_writable_metadata(self): This is intended to be used when creating a new object / blob. - See the `API reference`_ for more information, the fields marked as - writable are: + See the `API reference docs`_ for more information, the fields + marked as writable are: * ``acl`` * ``cacheControl`` @@ -548,9 +559,6 @@ def _get_writable_metadata(self): For now, we don't support ``acl``, access control lists should be managed directly through :class:`ObjectACL` methods. - - .. _API reference: https://cloud.google.com/storage/\ - docs/json_api/v1/objects """ # NOTE: This assumes `self.name` is unicode. object_metadata = {'name': self.name} @@ -828,22 +836,21 @@ def upload_from_file(self, file_obj, rewind=False, size=None, bucket. In the absence of those policies, upload will overwrite any existing contents. - See the `object versioning - `_ and - `lifecycle `_ - API documents for details. + See the `object versioning`_ and `lifecycle`_ API documents + for details. Uploading a file with a `customer-supplied`_ encryption key: .. literalinclude:: storage_snippets.py :start-after: [START upload_from_file] :end-before: [END upload_from_file] + :dedent: 4 The ``encryption_key`` should be a str or bytes with a length of at least 32. - .. _customer-supplied: https://cloud.google.com/storage/docs/\ - encryption#customer-supplied + For more fine-grained over the upload process, check out + `google-resumable-media`_. :type file_obj: file :param file_obj: A file handle open for reading. @@ -870,6 +877,10 @@ def upload_from_file(self, file_obj, rewind=False, size=None, :raises: :class:`~google.cloud.exceptions.GoogleCloudError` if the upload response returns an error status. + + .. _object versioning: https://cloud.google.com/storage/\ + docs/object-versioning + .. _lifecycle: https://cloud.google.com/storage/docs/lifecycle """ if num_retries is not None: warnings.warn(_NUM_RETRIES_MESSAGE, DeprecationWarning) @@ -972,8 +983,9 @@ def create_resumable_upload_session( access-controlled bucket. For more details, see the `documentation on signed URLs`_. - .. _documentation on signed URLs: https://cloud.google.com/storage\ - /docs/access-control/signed-urls#signing-resumable + .. _documentation on signed URLs: + https://cloud.google.com/storage/\ + docs/access-control/signed-urls#signing-resumable The content type of the upload will be determined in order of precedence: @@ -993,10 +1005,8 @@ def create_resumable_upload_session( `lifecycle `_ API documents for details. - If :attr:`encryption_key` is set, the blob will be `encrypted`_. - - .. _encrypted: https://cloud.google.com/storage/docs/\ - encryption#customer-supplied + If :attr:`encryption_key` is set, the blob will be encrypted with + a `customer-supplied`_ encryption key. :type size: int :param size: (Optional). The maximum number of bytes that can be @@ -1236,67 +1246,73 @@ def update_storage_class(self, new_class, client=None): cache_control = _scalar_property('cacheControl') """HTTP 'Cache-Control' header for this object. - See: https://tools.ietf.org/html/rfc7234#section-5.2 and - https://cloud.google.com/storage/docs/json_api/v1/objects + See: `RFC 7234`_ and `API reference docs`_. - If the property is not set locally, returns ``None``. + If the property is not set locally, returns :data:`None`. :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: https://tools.ietf.org/html/rfc6266 and - https://cloud.google.com/storage/docs/json_api/v1/objects + See: `RFC 6266`_ and `API reference docs`_. - If the property is not set locally, returns ``None``. + If the property is not set locally, returns :data:`None`. :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: https://tools.ietf.org/html/rfc7231#section-3.1.2.2 and - https://cloud.google.com/storage/docs/json_api/v1/objects + See: `RFC 7231`_ and `API reference docs`_. If the property is not set locally, returns ``None``. :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: https://tools.ietf.org/html/bcp47 and - https://cloud.google.com/storage/docs/json_api/v1/objects + See: `BCP47`_ and `API reference docs`_. - If the property is not set locally, returns ``None``. + If the property is not set locally, returns :data:`None`. :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: https://tools.ietf.org/html/rfc2616#section-14.17 and - https://cloud.google.com/storage/docs/json_api/v1/objects + See: `RFC 2616`_ and `API reference docs`_. - If the property is not set locally, returns ``None``. + If the property is not set locally, returns :data:`None`. :rtype: str or ``NoneType`` + + .. _RFC 2616: https://tools.ietf.org/html/rfc2616#section-14.17 """ crc32c = _scalar_property('crc32c') """CRC32C checksum for this object. - See: https://tools.ietf.org/html/rfc4960#appendix-B and - https://cloud.google.com/storage/docs/json_api/v1/objects + See: `RFC 4960`_ and `API reference docs`_. - If the property is not set locally, returns ``None``. + If the property is not set locally, returns :data:`None`. :rtype: str or ``NoneType`` + + .. _RFC 4960: https://tools.ietf.org/html/rfc4960#appendix-B """ @property @@ -1318,11 +1334,12 @@ def component_count(self): def etag(self): """Retrieve the ETag for the object. - See: https://tools.ietf.org/html/rfc2616#section-3.11 and - https://cloud.google.com/storage/docs/json_api/v1/objects + See: `RFC 2616 (etags)`_ and `API reference docs`_. :rtype: str or ``NoneType`` :returns: The blob etag or ``None`` if the property is not set locally. + + .. _RFC 2616 (etags): https://tools.ietf.org/html/rfc2616#section-3.11 """ return self._properties.get('etag') @@ -1355,12 +1372,13 @@ def id(self): md5_hash = _scalar_property('md5Hash') """MD5 hash for this object. - See: https://tools.ietf.org/html/rfc4960#appendix-B and - https://cloud.google.com/storage/docs/json_api/v1/objects + See: `RFC 1321`_ and `API reference docs`_. If the property is not set locally, returns ``None``. :rtype: str or ``NoneType`` + + .. _RFC 1321: https://tools.ietf.org/html/rfc1321 """ @property