Notice: Over the next few months, we're reorganizing the App Engine documentation site to make it easier to find content and better align with the rest of Google Cloud products. The same content will be available, but the navigation will now match the rest of the Cloud products. If you have feedback or questions as you navigate the site, click Send Feedback.

Python 2 is no longer supported by the community. We recommend that you migrate Python 2 apps to Python 3.
Stay organized with collections Save and categorize content based on your preferences.

google.appengine.api.files.file module


Files API.

Deprecated since version 1.8.1: Use Google Cloud Storage Client library instead.


exception google.appengine.api.files.file.ApiTemporaryUnavailableErrorsource

Bases: google.appengine.api.files.file.Error

Files API is temporary unavailable. Request should be retried soon.

exception google.appengine.api.files.file.Errorsource

Bases: exceptions.Exception

Base error class for this module.

exception google.appengine.api.files.file.ExclusiveLockFailedErrorsource

Bases: google.appengine.api.files.file.Error

Exclusive lock can’t be obtained.

exception google.appengine.api.files.file.ExistenceErrorsource

Bases: google.appengine.api.files.file.Error

File is in wrong existence state.

exception google.appengine.api.files.file.FileNotOpenedErrorsource

Bases: google.appengine.api.files.file.Error

File was not opened.

exception google.appengine.api.files.file.FileTemporaryUnavailableErrorsource

Bases: google.appengine.api.files.file.Error

File is temporary unavailable. Request should be retried soon.

exception google.appengine.api.files.file.FinalizationErrorsource

Bases: google.appengine.api.files.file.Error

File is in wrong finalization state.

exception google.appengine.api.files.file.InvalidArgumentErrorsource

Bases: google.appengine.api.files.file.Error

Function argument has invalid value.

exception google.appengine.api.files.file.InvalidFileNameErrorsource

Bases: google.appengine.api.files.file.Error

File name is invalid.

exception google.appengine.api.files.file.InvalidParameterErrorsource

Bases: google.appengine.api.files.file.Error

Parameter specified in Create() call is invalid.

exception google.appengine.api.files.file.OperationNotSupportedErrorsource

Bases: google.appengine.api.files.file.Error

Incorrect file open mode.

exception google.appengine.api.files.file.PermissionDeniedErrorsource

Bases: google.appengine.api.files.file.Error

Application doesn’t have permissions to perform the operation.

exception google.appengine.api.files.file.ReadOnlyErrorsource

Bases: google.appengine.api.files.file.Error

File is read-only mode.

exception google.appengine.api.files.file.SequenceKeyOutOfOrderError(last_sequence_key, cause=None)source

Bases: google.appengine.api.files.file.Error

Sequence key specified is out of order.


last sequence key which was written to the file.

exception google.appengine.api.files.file.UnknownErrorsource

Bases: google.appengine.api.files.file.Error

Unknown unexpected io error occured.

exception google.appengine.api.files.file.UnsupportedContentTypeErrorsource

Bases: google.appengine.api.files.file.Error

Specified file content type is not supported by this api.

exception google.appengine.api.files.file.UnsupportedOpenModeErrorsource

Bases: google.appengine.api.files.file.Error

Unsupported file open mode was specified.

exception google.appengine.api.files.file.WrongContentTypeErrorsource

Bases: google.appengine.api.files.file.Error

File has a different content type.

exception google.appengine.api.files.file.WrongOpenModeErrorsource

Bases: google.appengine.api.files.file.Error

Incorrect file open mode.


Permanently delete files.

Delete on non-finalized/non-existent files is a no-op.


filenames – finalized file names as strings. filename should has format “/gs/bucket/filename” or “/blobstore/blobkey”.

  • InvalidFileNameError – Raised when any filename is not of valid format or not a finalized name.

  • IOError – Raised if any problem occurs contacting the backend system.

google.appengine.api.files.file.finalize(filename, content_type=0)source

Finalize a file.

  • filename – File name as string.

  • content_type – File’s content type. Value from FileContentType.ContentType enum.

google.appengine.api.files.file.listdir(path, **kwargs)source

Return a sorted list of filenames (matching a pattern) in the given path.

Only Google Cloud Storage paths are supported in current implementation.

  • path – a Google Cloud Storage path of “/gs/bucketname” form.

  • kwargs – other keyword arguments to be relayed to Google Cloud Storage. This can be used to select certain files with names matching a pattern. See for details.


a list containing filenames (matching a pattern) from the given path. Sorted by Python String., mode='r', content_type=0, exclusive_lock=False, buffering=0)source

Open a file.

  • filename – A name of the file as string.

  • mode – File open mode. Either ‘a’ or ‘r’.

  • content_type – File’s content type. Value from FileContentType.ContentType enum.

  • exclusive_lock – If file should be exclusively locked. All other exclusive lock attempts will file until file is correctly closed.

  • buffering – optional argument similar to the one in Python’s open. It specifies the file’s desired buffer size: 0 means unbuffered, positive value means use a buffer of that size, any negative value means the default size. Only read buffering is supported.


File object.


InvalidArgumentError – Raised when given illegal argument value or type.


Get status of a finalized file given it’s full path filename.


a _FileStat object similar to that returned by python’s os.stat(path).


FinalizationError if file is not finalized.

class google.appengine.api.files.file.BufferedFile(filename, buffer_size=524288)source

Bases: object

BufferedFile is a file-like object reading underlying file in chunks.


Read data from RAW file.


size – Number of bytes to read as integer. Actual number of bytes read is always equal to size unless end if file was reached.


A string with data read.


Read one line delimited by ‘ ‘ from the file.

A trailing newline character is kept in the string. It may be absent when a file ends with an incomplete line. If the size argument is non-negative, it specifies the maximum string size (counting the newline) to return. An empty string is returned only when EOF is encountered immediately.

size: Maximum number of bytes to read. If not specified, readline stops

only on ‘

‘ or EOF.


The data read as a string.

seek(offset, whence=0)source

Set the file’s current position.

  • offset – seek offset as number.

  • whence – seek mode. Supported modes are os.SEEK_SET (absolute seek), os.SEEK_CUR (seek relative to the current position), and os.SEEK_END (seek relative to the end, offset should be negative).


Return file’s current position.