class_docstr: Use the Google Cloud connection to interact with Google Cloud Storage.
class_docstr_tok: ["Use","the","Google","Cloud","connection","to","interact","with","Google","Cloud","Storage","."]
docstr: 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.
  :param user_project: The identifier of the Google Cloud project to bill for the request.
      Required for Requester Pays buckets.
docstr_tok: ["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",".",":","param","user_project",":","The","identifier","of","the","Google","Cloud","project","to","bill","for","the","request",".","Required","for","Requester","Pays","buckets","."]
code: def download(
      self,
      bucket_name: str,
      object_name: str,
      filename: str | None = None,
      chunk_size: int | None = None,
      timeout: int | None = DEFAULT_TIMEOUT,
      num_max_attempts: int | None = 1,
      user_project: str | None = None,
  ) -> str | bytes:
      """
      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.
      :param user_project: The identifier of the Google Cloud project to bill for the request.
          Required for Requester Pays buckets.
      """
      # TODO: future improvement check file size before downloading,
      #  to check for local space availability
  
      if num_max_attempts is None:
          num_max_attempts = 3
  
      for attempt in range(num_max_attempts):
          if attempt:
              # Wait with exponential backoff scheme before retrying.
              timeout_seconds = 2**attempt
              time.sleep(timeout_seconds)
  
          try:
              client = self.get_conn()
              bucket = client.bucket(
                  bucket_name, user_project=user_project
              )
              blob = bucket.blob(
                  blob_name=object_name, chunk_size=chunk_size
              )
  
              if filename:
                  blob.download_to_filename(filename, timeout=timeout)
                  self.log.info("File downloaded to %s", filename)
                  return filename
              else:
                  return blob.download_as_bytes()
  
          except GoogleCloudError:
              if attempt == num_max_attempts - 1:
                  self.log.error(
                      "Download attempt of object: %s from %s has failed. Attempt: %s, max %s.",
                      object_name,
                      bucket_name,
                      attempt,
                      num_max_attempts,
                  )
                  raise
      else:
          raise NotImplementedError
  
imports: from __future__ import annotations
  import functools
  import gzip
  import json
  import os
  import shutil
  import time
  import warnings
  from contextlib import contextmanager
  from functools import partial
  from io import BytesIO
  from tempfile import NamedTemporaryFile
  from typing import IO, TYPE_CHECKING, Any, Callable, Generator, Sequence, TypeVar, cast, overload
  from urllib.parse import urlsplit
  from gcloud.aio.storage import Storage
  from google.api_core.exceptions import GoogleAPICallError, NotFound
  from google.cloud import storage
  from google.cloud.exceptions import GoogleCloudError
  from google.cloud.storage.retry import DEFAULT_RETRY
  from requests import Session
  from airflow.exceptions import AirflowException, AirflowProviderDeprecationWarning
  from airflow.providers.google.cloud.utils.helpers import normalize_directory_path
  from airflow.providers.google.common.consts import CLIENT_INFO
  from airflow.providers.google.common.hooks.base_google import GoogleBaseAsyncHook, GoogleBaseHook
  from airflow.typing_compat import ParamSpec
  from airflow.utils import timezone
  from airflow.version import version
label_desc: Use image node_id 7 for calling the GCSHook obj's underlying member method code with example usage: obj.download(bucket_name, object_name, filename, chunk_size, timeout, num_max_attempts, user_project) and returns: filename, blob