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

Already on GitHub? Sign in to your account

Clean up a documentation for the storage blob module. #3376

Merged
merged 1 commit into from
May 16, 2017
Merged

Clean up a documentation for the storage blob module. #3376

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
104 changes: 61 additions & 43 deletions storage/google/cloud/storage/blob.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -426,18 +435,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.
Expand Down Expand Up @@ -530,8 +541,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``
Expand All @@ -547,9 +558,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}
Expand Down Expand Up @@ -798,22 +806,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
<https://cloud.google.com/storage/docs/object-versioning>`_ and
`lifecycle <https://cloud.google.com/storage/docs/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.
Expand All @@ -839,6 +846,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

This comment was marked as spam.

Sign in to view

"""
if num_retries is not None:
warnings.warn(_NUM_RETRIES_MESSAGE, DeprecationWarning)
Expand Down Expand Up @@ -941,8 +952,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:
Expand All @@ -962,10 +974,8 @@ def create_resumable_upload_session(
`lifecycle <https://cloud.google.com/storage/docs/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
Expand Down Expand Up @@ -1205,67 +1215,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

This comment was marked as spam.

Sign in to view

"""

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

This comment was marked as spam.

Sign in to view

"""

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

This comment was marked as spam.

Sign in to view

"""

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

This comment was marked as spam.

Sign in to view

"""

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

This comment was marked as spam.

Sign in to view

"""

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

This comment was marked as spam.

Sign in to view

"""

@property
Expand All @@ -1287,11 +1303,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

This comment was marked as spam.

Sign in to view

"""
return self._properties.get('etag')

Expand Down Expand Up @@ -1324,12 +1341,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

This comment was marked as spam.

Sign in to view

"""

@property
Expand Down