From 0eefb21a1ec02e78fbe4b2eaea023391a2e40cf3 Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Fri, 31 Oct 2014 22:26:10 -0400
Subject: [PATCH] Document semantics of upload to existing key.

Point to the 'object versioning' and 'lifetime' specs for details about
how to override the default (overwrite unconditionally).

Fixes #162.
---
 gcloud/storage/key.py | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/gcloud/storage/key.py b/gcloud/storage/key.py
index 217f98ee29e3..97aaf1208612 100644
--- a/gcloud/storage/key.py
+++ b/gcloud/storage/key.py
@@ -214,6 +214,18 @@ def upload_from_file(self, file_obj, rewind=False, size=None,
                          content_type=None):
         """Upload the contents of this key from a file-like object.
 
+        .. note::
+
+           The effect of uploading to an existing key depends on the
+           "versioning" and "lifecycle" policies defined on the key's
+           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.
+
         :type file_obj: file
         :param file_obj: A file handle open for reading.
 
@@ -276,6 +288,18 @@ def upload_from_file(self, file_obj, rewind=False, size=None,
     def upload_from_filename(self, filename):
         """Upload this key's contents from the content of f named file.
 
+        .. note::
+
+           The effect of uploading to an existing key depends on the
+           "versioning" and "lifecycle" policies defined on the key's
+           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.
+
         :type filename: string
         :param filename: The path to the file.
         """
@@ -290,6 +314,18 @@ def upload_from_filename(self, filename):
     def upload_from_string(self, data, content_type='text/plain'):
         """Upload contents of this key from the provided string.
 
+        .. note::
+
+           The effect of uploading to an existing key depends on the
+           "versioning" and "lifecycle" policies defined on the key's
+           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.
+
         :type data: string
         :param data: The data to store in this key.