English ▼
Skip to page content Skip to main navigation
e.g. "templates" or "datastore"

# Functions

The `google.appengine.ext.blobstore` package provides several functions. These functions allow applications to generate upload URLs, delete blobs, and fetch blob data.

create_rpc(deadline=None, callback=None)

  Creates and returns an RPC object.

  Arguments

  deadline

    The most amount of time to wait for a response from the remote host, as a number of seconds. If the remote host does not respond in this amount of time, an exception is raised when the `check_success()` method or the `get_result()` method of the RPC object is called.

    If the application attempts to access results before the remote host has responded and before the deadline has elapsed, the call will wait until either of these have occurred, and either return results or raise the exception. If the application request timer expires while the application is waiting, the call is canceled.

  callback

    A Python function to be called when the service returns results successfully. The function is called without arguments.

    The callback function is called when the `wait()` method of the RPC object is called, either directly by the application or implicitly with a call to `check_success()` or `get_result()`. The function does not get called in a background process or thread; it only gets called when one of these methods is called by the application.

    The callback function is called even if the request fails or if the RPC deadline elapses.

create_upload_url(success_path, max_bytes_per_blob=None, max_bytes_total=None, rpc=None)

  Generate an action URL for a Blobstore upload web form.

  When the user submits an upload web form, the uploaded data goes directly to the Blobstore. The Blobstore rewrites the incoming request to remove the uploaded data (the MIME part body) and add the Blobstore key (as a header in the MIME part), then passes the rewritten request to the application handler associated with the URL path given to create_upload_url() as success_path. The handler at that path can process the rest of the form.

  The generated URL will accept a Blobstore upload for up to 10 minutes after it is created. After 10 minutes Blobstore uploads to this URL will be rejected.

  Arguments

  success_path
    The URL path of the request handler that will process the upload request, after the file submitted with the form has been uploaded to the Blobstore.
  max_bytes_per_blob
    The maximum size in bytes that any one blob in the upload can be, or None if there is no maximum blob size. Must be a positive value or None.
  max_bytes_total
    The maximum aggregate size of all of the blobs in the upload, or None if there is no total maximum. Must be a positive value or None.
  rpc

    An RPC object that controls some settings of this request from the application to the Blobstore service (deadline and optional callback function). If this argument is `None` (the default), this request uses normal settings.

  Returns the URL to use as the action of an upload form.

create_upload_url_async(success_path, max_bytes_per_blob=None, max_bytes_total=None, rpc=None)

  Asynchronously generate an action URL for a Blobstore upload web form. This function is the asynchronous version of `create_upload_url()`.

  Arguments

  success_path
    The URL path of the request handler that will process the upload request, after the file submitted with the form has been uploaded to the Blobstore.
  max_bytes_per_blob
    The maximum size in bytes that any one blob in the upload can be, or None if there is no maximum blob size. Must be a positive value or None.
  max_bytes_total
    The maximum aggregate size of all of the blobs in the upload, or None if there is no total maximum. Must be a positive value or None.
  rpc

    An RPC object that controls some settings of this request from the application to the Blobstore service (deadline and optional callback function). If this argument is `None` (the default), this request uses normal settings.

  Returns an RPC object. If the `rpc` argument is specified, this return value is that RPC object. This RPC object's result will be the URL to use as the action of an upload form.

delete(blob_keys, rpc=None)

  Deletes a value or values from the Blobstore, and the corresponding BlobInfo entities from the datastore.

  Arguments

  blob_keys
    A `BlobKey` object or blob key string, or a list of BlobKey objects or blob key strings to delete.
  rpc

    An RPC object that controls some settings of this request from the application to the Blobstore service (deadline and optional callback function). If this argument is `None` (the default), this request uses normal settings.

  This function does not return a value. An application can confirm that a value has been deleted by attempting to get its correpsonding BlobInfo entity using the `get()` function.

delete_async(blob_keys, rpc=None)

  Asynchronously deletes a value or values from the Blobstore and the corresponding `BlobInfo` entities from the datastore. This function is the asynchronous version of `delete()`.

  Arguments

  blob_keys
    A `BlobKey` object or blob key string, or a list of `BlobKey` objects or blob key strings to delete.
  rpc

    An RPC object that controls some settings of this request from the application to the Blobstore service (deadline and optional callback function). If this argument is `None` (the default), this request uses normal settings.

  This function returns an RPC with result `None`. If the `rpc` argument is specified, this return value is that RPC object.

get(blob_key)

  A synonym for `BlobInfo.get()`.

parse_blob_info(field_storage)

  Parses a `cgi.FieldStorage` object into a `BlobInfo` object.

  When a Blobstore value is uploaded, the Blobstore creates a `BlobInfo` entity in the datastore. It also retains this data in the headers of the request passed to the upload handler. The upload handler can use `parse_blob_info()` to access this data from the header instead of making a call to the datastore.

  Arguments

  field_storage

    A `FieldStorage` object, from the `cgi` module in the Python standard library.

        import cgi
        from google.appengine.ext import blobstore

        blob_info = blobstore.parse_blob_info(cgi.FieldStorage()['file'])
        # blob_info.filename...

    The argument must be a `FieldStorage` object that represents a single file upload. If the user request contains more than one file upload (as multipart MIME data), you can iterate over the `FieldStorage` to get an inner `FieldStorage` object for each upload, and pass the inner object to the `parse_blob_info()` function. Here's an example that accommodates multiple files in a single form:

        fields = cgi.FieldStorage()
        file_fields = fields['file']  # all fields named "file" assumed to contain file uploads
        if not isinstance(file_fields, list):
            file_fields = [file_fields]

        for field in file_fields:
            blob_info = blobstore.parse_blob_info(field)
            # ...

fetch_data(blob, start_index, end_index, rpc=None)

  Retrieves the portion of a given Blobstore value described by the given byte indices.

  The size of the portion (end_index`-` start_index + 1) must not exceed `MAX_BLOB_FETCH_SIZE` (about 1 megabyte). fetch_data() allows your application to access data in Blobstore values without exceeding the size limit on API return values.

  Returns a `str` containing the requested portion of the Blobstore value. The return value may contain fewer than end_index`-` start_index + 1 bytes if either index is larger than the last index of the value.

  Byte indices are inclusive, with the first byte having an index of 0. For example, a `start_index` of 9 and an `end_index` of 19 will return up to 11 bytes, starting from the 10th byte (index 9) in the value.

  If blob does not refer to an actual Blobstore value, fetch_data raises a `BlobNotFoundError`.

  Arguments

  blob

    A `BlobInfo` object, a `BlobKey` object, or a `str` or `unicode` representation of the blob key for the Blobstore value.

  start_index

    The index of the first byte of the portion of the value to fetch. An index of 0 represents the first byte of the value. If start_index is larger than the last index of the value, fetch_data() returns an empty byte string.

  end_index

    The index of the last byte of the portion of the value to fetch. If end_index is larger than the last index of the value, all bytes from start_index to the end of the value are returned.

  rpc

    An RPC object that controls some settings of this request from the application to the Blobstore service (deadline and optional callback function). If this argument is `None` (the default), this request uses normal settings.

fetch_data_async(blob, start_index, end_index, rpc=None)

  Asynchronously retrieves the portion of a given Blobstore value described by the given byte indices. This function is the asynchronous version of `fetch_data()`.

  Arguments

  blob

    A `BlobInfo` object, a `BlobKey` object, or a `str` or `unicode` representation of the blob key for the Blobstore value.

  start_index

    The index of the first byte of the portion of the value to fetch. An index of 0 represents the first byte of the value. If start_index is larger than the last index of the value, fetch_data() returns an empty byte string.

  end_index

    The index of the last byte of the portion of the value to fetch. If end_index is larger than the last index of the value, all bytes from start_index to the end of the value are returned.

  rpc

    An RPC object that controls some settings of this request from the application to the Blobstore service (deadline and optional callback function). If this argument is `None` (the default), this request uses normal settings.

  Returns an RPC object. If the `rpc` argument is specified, this return value is that RPC object. The RPC object's result will be a string containing the requested portion of the Blobstore value. The return value may contain fewer than `end_index - start_index + 1` bytes if either index is larger than the last index of the value.