:py:mod:`airflow.providers.google.cloud.hooks.gcs`
==================================================

.. py:module:: airflow.providers.google.cloud.hooks.gcs

.. autoapi-nested-parse::

   This module contains a Google Cloud Storage hook.


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   airflow.providers.google.cloud.hooks.gcs.GCSHook


Functions
~~~~~~~~~

.. autoapisummary::

   airflow.providers.google.cloud.hooks.gcs.gcs_object_is_directory


Attributes
~~~~~~~~~~

.. autoapisummary::

   airflow.providers.google.cloud.hooks.gcs.RT
   airflow.providers.google.cloud.hooks.gcs.T
   airflow.providers.google.cloud.hooks.gcs.List
   airflow.providers.google.cloud.hooks.gcs.DEFAULT_TIMEOUT
   airflow.providers.google.cloud.hooks.gcs.PROVIDE_BUCKET


.. py:data:: RT
   

.. py:data:: T
   

.. py:data:: List
   

.. py:data:: DEFAULT_TIMEOUT
   :annotation: = 60

   
.. py:data:: PROVIDE_BUCKET
   :annotation: :str

   
.. py:class:: GCSHook(gcp_conn_id = 'google_cloud_default', delegate_to = None, impersonation_chain = None)

   Bases: :py:obj:`airflow.providers.google.common.hooks.base_google.GoogleBaseHook`

   Interact with Google Cloud Storage. This hook uses the Google Cloud
   connection.

   .. py:method:: get_conn()

      Returns a Google Cloud Storage service object.


   .. py:method:: copy(source_bucket, source_object, destination_bucket = None, destination_object = None)

      Copies an object from a bucket to another, with renaming if requested.

      destination_bucket or destination_object can be omitted, in which case
      source bucket/object is used, but not both.

      :param source_bucket: The bucket of the object to copy from.
      :param source_object: The object to copy.
      :param destination_bucket: The destination of the object to copied to.
          Can be omitted; then the same bucket is used.
      :param destination_object: The (renamed) path of the object if given.
          Can be omitted; then the same name is used.


   .. py:method:: rewrite(source_bucket, source_object, destination_bucket, destination_object = None)

      Has the same functionality as copy, except that will work on files
      over 5 TB, as well as when copying between locations and/or storage
      classes.

      destination_object can be omitted, in which case source_object is used.

      :param source_bucket: The bucket of the object to copy from.
      :param source_object: The object to copy.
      :param destination_bucket: The destination of the object to copied to.
      :param destination_object: The (renamed) path of the object if given.
          Can be omitted; then the same name is used.


   .. py:method:: download(bucket_name: str, object_name: str, filename: None = None, chunk_size: int | None = None, timeout: int | None = DEFAULT_TIMEOUT, num_max_attempts: int | None = 1) -> bytes
               download(bucket_name: str, object_name: str, filename: str, chunk_size: int | None = None, timeout: int | None = DEFAULT_TIMEOUT, num_max_attempts: int | None = 1) -> str

      Downloads a file from Google Cloud Storage.

      When no filename is supplied, the operator loads the file into memory and returns its
      content. When a filename is supplied, it writes the file to the specified location and
      returns the location. For file sizes that exceed the available memory it is recommended
      to write to a file.

      :param bucket_name: The bucket to fetch from.
      :param object_name: The object to fetch.
      :param filename: If set, a local file path where the file should be written to.
      :param chunk_size: Blob chunk size.
      :param timeout: Request timeout in seconds.
      :param num_max_attempts: Number of attempts to download the file.


   .. py:method:: download_as_byte_array(bucket_name, object_name, chunk_size = None, timeout = DEFAULT_TIMEOUT, num_max_attempts = 1)

      Downloads a file from Google Cloud Storage.

      When no filename is supplied, the operator loads the file into memory and returns its
      content. When a filename is supplied, it writes the file to the specified location and
      returns the location. For file sizes that exceed the available memory it is recommended
      to write to a file.

      :param bucket_name: The bucket to fetch from.
      :param object_name: The object to fetch.
      :param chunk_size: Blob chunk size.
      :param timeout: Request timeout in seconds.
      :param num_max_attempts: Number of attempts to download the file.


   .. py:method:: provide_file(bucket_name = PROVIDE_BUCKET, object_name = None, object_url = None, dir = None)

      Downloads the file to a temporary directory and returns a file handle

      You can use this method by passing the bucket_name and object_name parameters
      or just object_url parameter.

      :param bucket_name: The bucket to fetch from.
      :param object_name: The object to fetch.
      :param object_url: File reference url. Must start with "gs: //"
      :param dir: The tmp sub directory to download the file to. (passed to NamedTemporaryFile)
      :return: File handler


   .. py:method:: provide_file_and_upload(bucket_name = PROVIDE_BUCKET, object_name = None, object_url = None)

      Creates temporary file, returns a file handle and uploads the files content
      on close.

      You can use this method by passing the bucket_name and object_name parameters
      or just object_url parameter.

      :param bucket_name: The bucket to fetch from.
      :param object_name: The object to fetch.
      :param object_url: File reference url. Must start with "gs: //"
      :return: File handler


   .. py:method:: upload(bucket_name, object_name, filename = None, data = None, mime_type = None, gzip = False, encoding = 'utf-8', chunk_size = None, timeout = DEFAULT_TIMEOUT, num_max_attempts = 1, metadata = None)

      Uploads a local file or file data as string or bytes to Google Cloud Storage.

      :param bucket_name: The bucket to upload to.
      :param object_name: The object name to set when uploading the file.
      :param filename: The local file path to the file to be uploaded.
      :param data: The file's data as a string or bytes to be uploaded.
      :param mime_type: The file's mime type set when uploading the file.
      :param gzip: Option to compress local file or file data for upload
      :param encoding: bytes encoding for file data if provided as string
      :param chunk_size: Blob chunk size.
      :param timeout: Request timeout in seconds.
      :param num_max_attempts: Number of attempts to try to upload the file.
      :param metadata: The metadata to be uploaded with the file.


   .. py:method:: exists(bucket_name, object_name)

      Checks for the existence of a file in Google Cloud Storage.

      :param bucket_name: The Google Cloud Storage bucket where the object is.
      :param object_name: The name of the blob_name to check in the Google cloud
          storage bucket.


   .. py:method:: get_blob_update_time(bucket_name, object_name)

      Get the update time of a file in Google Cloud Storage

      :param bucket_name: The Google Cloud Storage bucket where the object is.
      :param object_name: The name of the blob to get updated time from the Google cloud
          storage bucket.


   .. py:method:: is_updated_after(bucket_name, object_name, ts)

      Checks if an blob_name is updated in Google Cloud Storage.

      :param bucket_name: The Google Cloud Storage bucket where the object is.
      :param object_name: The name of the object to check in the Google cloud
          storage bucket.
      :param ts: The timestamp to check against.


   .. py:method:: is_updated_between(bucket_name, object_name, min_ts, max_ts)

      Checks if an blob_name is updated in Google Cloud Storage.

      :param bucket_name: The Google Cloud Storage bucket where the object is.
      :param object_name: The name of the object to check in the Google cloud
              storage bucket.
      :param min_ts: The minimum timestamp to check against.
      :param max_ts: The maximum timestamp to check against.


   .. py:method:: is_updated_before(bucket_name, object_name, ts)

      Checks if an blob_name is updated before given time in Google Cloud Storage.

      :param bucket_name: The Google Cloud Storage bucket where the object is.
      :param object_name: The name of the object to check in the Google cloud
          storage bucket.
      :param ts: The timestamp to check against.


   .. py:method:: is_older_than(bucket_name, object_name, seconds)

      Check if object is older than given time

      :param bucket_name: The Google Cloud Storage bucket where the object is.
      :param object_name: The name of the object to check in the Google cloud
          storage bucket.
      :param seconds: The time in seconds to check against


   .. py:method:: delete(bucket_name, object_name)

      Deletes an object from the bucket.

      :param bucket_name: name of the bucket, where the object resides
      :param object_name: name of the object to delete


   .. py:method:: delete_bucket(bucket_name, force = False)

      Delete a bucket object from the Google Cloud Storage.

      :param bucket_name: name of the bucket which will be deleted
      :param force: false not allow to delete non empty bucket, set force=True
          allows to delete non empty bucket


   .. py:method:: list(bucket_name, versions=None, max_results=None, prefix=None, delimiter=None)

      List all objects from the bucket with the give string prefix in name

      :param bucket_name: bucket name
      :param versions: if true, list all versions of the objects
      :param max_results: max count of items to return in a single page of responses
      :param prefix: prefix string which filters objects whose name begin with
          this prefix
      :param delimiter: filters objects based on the delimiter (for e.g '.csv')
      :return: a stream of object names matching the filtering criteria


   .. py:method:: list_by_timespan(bucket_name, timespan_start, timespan_end, versions = None, max_results = None, prefix = None, delimiter = None)

      List all objects from the bucket with the give string prefix in name that were
      updated in the time between ``timespan_start`` and ``timespan_end``.

      :param bucket_name: bucket name
      :param timespan_start: will return objects that were updated at or after this datetime (UTC)
      :param timespan_end: will return objects that were updated before this datetime (UTC)
      :param versions: if true, list all versions of the objects
      :param max_results: max count of items to return in a single page of responses
      :param prefix: prefix string which filters objects whose name begin with
          this prefix
      :param delimiter: filters objects based on the delimiter (for e.g '.csv')
      :return: a stream of object names matching the filtering criteria


   .. py:method:: get_size(bucket_name, object_name)

      Gets the size of a file in Google Cloud Storage.

      :param bucket_name: The Google Cloud Storage bucket where the blob_name is.
      :param object_name: The name of the object to check in the Google
          cloud storage bucket_name.


   .. py:method:: get_crc32c(bucket_name, object_name)

      Gets the CRC32c checksum of an object in Google Cloud Storage.

      :param bucket_name: The Google Cloud Storage bucket where the blob_name is.
      :param object_name: The name of the object to check in the Google cloud
          storage bucket_name.


   .. py:method:: get_md5hash(bucket_name, object_name)

      Gets the MD5 hash of an object in Google Cloud Storage.

      :param bucket_name: The Google Cloud Storage bucket where the blob_name is.
      :param object_name: The name of the object to check in the Google cloud
          storage bucket_name.


   .. py:method:: create_bucket(bucket_name, resource = None, storage_class = 'MULTI_REGIONAL', location = 'US', project_id = None, labels = None)

      Creates a new bucket. Google Cloud Storage uses a flat namespace, so
      you can't create a bucket with a name that is already in use.

      .. seealso::
          For more information, see Bucket Naming Guidelines:
          https://cloud.google.com/storage/docs/bucketnaming.html#requirements

      :param bucket_name: The name of the bucket.
      :param resource: An optional dict with parameters for creating the bucket.
          For information on available parameters, see Cloud Storage API doc:
          https://cloud.google.com/storage/docs/json_api/v1/buckets/insert
      :param storage_class: This defines how objects in the bucket are stored
          and determines the SLA and the cost of storage. Values include

          - ``MULTI_REGIONAL``
          - ``REGIONAL``
          - ``STANDARD``
          - ``NEARLINE``
          - ``COLDLINE``.

          If this value is not specified when the bucket is
          created, it will default to STANDARD.
      :param location: The location of the bucket.
          Object data for objects in the bucket resides in physical storage
          within this region. Defaults to US.

          .. seealso::
              https://developers.google.com/storage/docs/bucket-locations

      :param project_id: The ID of the Google Cloud Project.
      :param labels: User-provided labels, in key/value pairs.
      :return: If successful, it returns the ``id`` of the bucket.


   .. py:method:: insert_bucket_acl(bucket_name, entity, role, user_project = None)

      Creates a new ACL entry on the specified bucket_name.
      See: https://cloud.google.com/storage/docs/json_api/v1/bucketAccessControls/insert

      :param bucket_name: Name of a bucket_name.
      :param entity: The entity holding the permission, in one of the following forms:
          user-userId, user-email, group-groupId, group-email, domain-domain,
          project-team-projectId, allUsers, allAuthenticatedUsers.
          See: https://cloud.google.com/storage/docs/access-control/lists#scopes
      :param role: The access permission for the entity.
          Acceptable values are: "OWNER", "READER", "WRITER".
      :param user_project: (Optional) The project to be billed for this request.
          Required for Requester Pays buckets.


   .. py:method:: insert_object_acl(bucket_name, object_name, entity, role, generation = None, user_project = None)

      Creates a new ACL entry on the specified object.
      See: https://cloud.google.com/storage/docs/json_api/v1/objectAccessControls/insert

      :param bucket_name: Name of a bucket_name.
      :param object_name: Name of the object. For information about how to URL encode
          object names to be path safe, see:
          https://cloud.google.com/storage/docs/json_api/#encoding
      :param entity: The entity holding the permission, in one of the following forms:
          user-userId, user-email, group-groupId, group-email, domain-domain,
          project-team-projectId, allUsers, allAuthenticatedUsers
          See: https://cloud.google.com/storage/docs/access-control/lists#scopes
      :param role: The access permission for the entity.
          Acceptable values are: "OWNER", "READER".
      :param generation: Optional. If present, selects a specific revision of this object.
      :param user_project: (Optional) The project to be billed for this request.
          Required for Requester Pays buckets.


   .. py:method:: compose(bucket_name, source_objects, destination_object)

      Composes a list of existing object into a new object in the same storage bucket_name

      Currently it only supports up to 32 objects that can be concatenated
      in a single operation

      https://cloud.google.com/storage/docs/json_api/v1/objects/compose

      :param bucket_name: The name of the bucket containing the source objects.
          This is also the same bucket to store the composed destination object.
      :param source_objects: The list of source objects that will be composed
          into a single object.
      :param destination_object: The path of the object if given.


   .. py:method:: sync(source_bucket, destination_bucket, source_object = None, destination_object = None, recursive = True, allow_overwrite = False, delete_extra_files = False)

      Synchronizes the contents of the buckets.

      Parameters ``source_object`` and ``destination_object`` describe the root sync directories. If they
      are not passed, the entire bucket will be synchronized. If they are passed, they should point
      to directories.

      .. note::
          The synchronization of individual files is not supported. Only entire directories can be
          synchronized.

      :param source_bucket: The name of the bucket containing the source objects.
      :param destination_bucket: The name of the bucket containing the destination objects.
      :param source_object: The root sync directory in the source bucket.
      :param destination_object: The root sync directory in the destination bucket.
      :param recursive: If True, subdirectories will be considered
      :param recursive: If True, subdirectories will be considered
      :param allow_overwrite: if True, the files will be overwritten if a mismatched file is found.
          By default, overwriting files is not allowed
      :param delete_extra_files: if True, deletes additional files from the source that not found in the
          destination. By default extra files are not deleted.

          .. note::
              This option can delete data quickly if you specify the wrong source/destination combination.

      :return: none


.. py:function:: gcs_object_is_directory(bucket)

   Return True if given Google Cloud Storage URL (gs://<bucket>/<blob>)
   is a directory or an empty bucket. Otherwise return False.