docs: add docs signed_url expiration take default utc (#250)

Co-authored-by: Frank Natividad <[email protected]>
Co-authored-by: Tres Seaver <[email protected]>

Author: 3 people

google/cloud/storage/_signing.py

@@ -91,7 +91,9 @@ def get_expiration_seconds_v2(expiration):
     """Convert 'expiration' to a number of seconds in the future.
 
     :type expiration: Union[Integer, datetime.datetime, datetime.timedelta]
-    :param expiration: Point in time when the signed URL should expire.
+    :param expiration: Point in time when the signed URL should expire. If
+                       a ``datetime`` instance is passed without an explicit
+                       ``tzinfo`` set,  it will be assumed to be ``UTC``.
 
     :raises: :exc:`TypeError` when expiration is not a valid type.
 
@@ -123,7 +125,9 @@ def get_expiration_seconds_v4(expiration):
     """Convert 'expiration' to a number of seconds offset from the current time.
 
     :type expiration: Union[Integer, datetime.datetime, datetime.timedelta]
-    :param expiration: Point in time when the signed URL should expire.
+    :param expiration: Point in time when the signed URL should expire. If
+                       a ``datetime`` instance is passed without an explicit
+                       ``tzinfo`` set,  it will be assumed to be ``UTC``.
 
     :raises: :exc:`TypeError` when expiration is not a valid type.
     :raises: :exc:`ValueError` when expiration is too large.
@@ -299,7 +303,9 @@ def generate_signed_url_v2(
                      Caller should have already URL-encoded the value.
 
     :type expiration: Union[Integer, datetime.datetime, datetime.timedelta]
-    :param expiration: Point in time when the signed URL should expire.
+    :param expiration: Point in time when the signed URL should expire. If
+                       a ``datetime`` instance is passed without an explicit
+                       ``tzinfo`` set,  it will be assumed to be ``UTC``.
 
     :type api_access_endpoint: str
     :param api_access_endpoint: (Optional) URI base. Defaults to empty string.
@@ -461,7 +467,9 @@ def generate_signed_url_v4(
                      Caller should have already URL-encoded the value.
 
     :type expiration: Union[Integer, datetime.datetime, datetime.timedelta]
-    :param expiration: Point in time when the signed URL should expire.
+    :param expiration: Point in time when the signed URL should expire. If
+                       a ``datetime`` instance is passed without an explicit
+                       ``tzinfo`` set,  it will be assumed to be ``UTC``.
 
     :type api_access_endpoint: str
     :param api_access_endpoint: (Optional) URI base. Defaults to

google/cloud/storage/blob.py

@@ -418,7 +418,9 @@ def generate_signed_url(
         log in.
 
         :type expiration: Union[Integer, datetime.datetime, datetime.timedelta]
-        :param expiration: Point in time when the signed URL should expire.
+        :param expiration: Point in time when the signed URL should expire. If
+                           a ``datetime`` instance is passed without an explicit
+                           ``tzinfo`` set,  it will be assumed to be ``UTC``.
 
         :type api_access_endpoint: str
         :param api_access_endpoint: (Optional) URI base.

google/cloud/storage/bucket.py

@@ -3020,7 +3020,9 @@ def generate_signed_url(
         log in.
 
         :type expiration: Union[Integer, datetime.datetime, datetime.timedelta]
-        :param expiration: Point in time when the signed URL should expire.
+        :param expiration: Point in time when the signed URL should expire. If
+                           a ``datetime`` instance is passed without an explicit
+                           ``tzinfo`` set,  it will be assumed to be ``UTC``.
 
         :type api_access_endpoint: str
         :param api_access_endpoint: (Optional) URI base.

google/cloud/storage/client.py

@@ -962,7 +962,9 @@ def generate_signed_post_policy_v4(
         :param blob_name: Object name.
 
         :type expiration: Union[Integer, datetime.datetime, datetime.timedelta]
-        :param expiration: Policy expiration time.
+        :param expiration: Policy expiration time. If a ``datetime`` instance is
+                           passed without an explicit ``tzinfo`` set,  it will be
+                           assumed to be ``UTC``.
 
         :type conditions: list
         :param conditions: (Optional) List of POST policy conditions, which are
@@ -1004,11 +1006,13 @@ def generate_signed_post_policy_v4(
             Generate signed POST policy and upload a file.
 
             >>> from google.cloud import storage
+            >>> import pytz
             >>> client = storage.Client()
+            >>> tz = pytz.timezone('America/New_York')
             >>> policy = client.generate_signed_post_policy_v4(
                 "bucket-name",
                 "blob-name",
-                expiration=datetime.datetime(2020, 3, 17),
+                expiration=datetime.datetime(2020, 3, 17, tzinfo=tz),
                 conditions=[
                     ["content-length-range", 0, 255]
                 ],