API Reference

This part of the documentation covers all the public classes in Depot.

Application Support

class depot.manager.DepotManager

Takes care of managing the whole Depot environment for the application.

DepotManager tracks the created depots, the current default depot, and the WSGI middleware in charge of serving files for local depots.

While this is used to create the default depot used by the application it can also create additional depots using the new() method.

In case you need to migrate your application to a different storage while keeping compatibility with previously stored file simply change the default depot through set_default() all previously stored file will continue to work on the old depot while new files will be uploaded to the new default one.

classmethod configure(name, config, prefix='depot.')

Configures an application depot.

This configures the application wide depot from a settings dictionary. The settings dictionary is usually loaded from an application configuration file where all the depot options are specified with a given prefix.

The default prefix is depot., the minimum required setting is depot.backend which specified the required backend for files storage. Additional options depend on the choosen backend.

classmethod from_config(config, prefix='depot.')

Creates a new depot from a settings dictionary.

Behaves like the configure() method but instead of configuring the application depot it creates a new one each time.

classmethod get(name=None)

Gets the application wide depot instance.

Might return None if configure() has not been called yet.

classmethod get_default()

Retrieves the current application default depot

classmethod get_file(path)

Retrieves a file by storage name and fileid in the form of a path

Path is expected to be storage_name/fileid.

classmethod make_middleware(app, **options)

Creates the application WSGI middleware in charge of serving local files.

A Depot middleware is required if your application wants to serve files from storages that don’t directly provide and HTTP interface like depot.io.local.LocalFileStorage and depot.io.gridfs.GridFSStorage

classmethod set_default(name)

Replaces the current application default depot

classmethod url_for(path)

Given path of a file uploaded on depot returns the url that serves it

Path is expected to be storage_name/fileid.

Database Support

class depot.fields.interfaces.DepotFileInfo(content, depot_name=None)

Keeps information on a content related to a specific depot.

By itself the DepotFileInfo does nothing, it is required to implement a process_content() method that actually saves inside the file info the information related to the content. The only information which is saved by default is the depot name itself.

It is a specialized dictionary that provides also attribute style access, the dictionary parent permits easy encoding/decoding to most marshalling systems.

abstract process_content(content, filename=None, content_type=None)

Process content in the given depot.

This is implemented by subclasses to provide some kind of behaviour on the content in the related Depot. The default implementation is provided by depot.fields.upload.UploadedFile which stores the content into the depot.

class depot.fields.interfaces.FileFilter

Interface that must be implemented by file filters.

File filters get executed whenever a file is stored on the database using one of the supported fields. Can be used to add additional data to the stored file or change it. When file filters are run the file has already been stored.

abstract on_save(uploaded_file)

Filters are required to provide their own implementation

class depot.fields.upload.UploadedFile(content, depot_name=None)

Simple depot.fields.interfaces.DepotFileInfo implementation that stores files.

Takes a file as content and uploads it to the depot while saving around most file information. Pay attention that if the file gets replaced through depot manually the UploadedFile will continue to have the old data.

Also provides support for encoding/decoding using JSON for storage inside databases as a plain string.

Default attributes provided for all UploadedFile include:

  • filename - This is the name of the uploaded file

  • file_id - This is the ID of the uploaded file

  • path - This is a depot_name/file_id path which can

    be used with DepotManager.get_file() to retrieve the file

  • content_type - This is the content type of the uploaded file

  • uploaded_at - This is the upload date in YYYY-MM-DD HH:MM:SS format

  • url - Public url of the uploaded file

  • file - The depot.io.interfaces.StoredFile instance of the stored file

process_content(content, filename=None, content_type=None)

Standard implementation of DepotFileInfo.process_content()

This is the standard depot implementation of files upload, it will store the file on the default depot and will provide the standard attributes.

Subclasses will need to call this method to ensure the standard set of attributes is provided.

Filters

Specialized FileTypes

Storing Files

class depot.io.interfaces.StoredFile(file_id, filename=None, content_type=None, last_modified=None, content_length=None)

Interface for already saved files.

It provides metadata on the stored file through following properties:

  • file_id

  • filename

  • content_type

  • last_modified

  • content_length

Already stored files can only be read back, so they are required to only provide read(self, n=-1), close() methods and closed property so that they can be read.

To replace/overwrite a file content do not try to call the write method, instead use the storage backend to replace the file content.

abstract close(*args, **kwargs)

Closes the file.

After closing the file it won’t be possible to read from it anymore. Some implementation might not do anything when closing the file, but they still are required to prevent further reads from a closed file.

abstract property closed

Returns if the file has been closed.

When closed return True it won’t be possible to read anoymore from this file.

fileno()

Returns underlying file descriptor if one exists.

OSError is raised if the IO object does not use a file descriptor.

flush()

Flush write buffers, if applicable.

This is not implemented for read-only and non-blocking streams.

isatty()

Return whether this is an ‘interactive’ stream.

Return False if it can’t be determined.

property name

This is the filename of the saved file

If a filename was not available when the file was created this will return “unnamed” as filename.

property public_url

The public HTTP url from which file can be accessed.

When supported by the storage this will provide the public url to which the file content can be accessed. In case this returns None it means that the file can only be served by the DepotMiddleware itself.

abstract read(n=- 1)

Reads n bytes from the file.

If n is not specified or is -1 the whole file content is read in memory and returned

readable()

Returns if the stored file is readable or not

Usually all stored files are readable

readline(size=- 1, /)

Read and return a line from the stream.

If size is specified, at most size bytes will be read.

The line terminator is always b’n’ for binary files; for text files, the newlines argument to open can be used to select the line terminator(s) recognized.

readlines(hint=- 1, /)

Return a list of lines from the stream.

hint can be specified to control the number of lines read: no more lines will be read if the total size (in bytes/characters) of all lines so far exceeds hint.

seek()

Change stream position.

Change the stream position to the given byte offset. The offset is interpreted relative to the position indicated by whence. Values for whence are:

  • 0 – start of stream (the default); offset should be zero or positive

  • 1 – current stream position; offset may be negative

  • 2 – end of stream; offset is usually negative

Return the new absolute position.

seekable()

Returns if the stored file is seekable or not

By default stored files are not seekable

tell()

Return current stream position.

truncate()

Truncate file to size bytes.

File pointer is left unchanged. Size defaults to the current IO position as reported by tell(). Returns the new size.

writable()

Returns if the stored file is writable or not

Stored files are not writable, you should rely on the relative FileStorage to overwrite their content

writelines(lines, /)

Write a list of lines to stream.

Line separators are not added, so it is usual for each of the lines provided to have a line separator at the end.

class depot.io.interfaces.FileStorage

Interface for storage providers.

The FileStorage base class declares a standard interface for storing and retrieving files in an underlying storage system.

Each storage system implementation is required to provide this interface to correctly work with filedepot.

abstract create(content, filename=None, content_type=None)

Saves a new file and returns the ID of the newly created file.

content parameter can either be bytes, another file object or a cgi.FieldStorage. When filename and content_type parameters are not provided they are deducted from the content itself.

abstract delete(file_or_id)

Deletes a file. If the file didn’t exist it will just do nothing.

abstract exists(file_or_id)

Returns if a file or its ID still exist.

static fileid(file_or_id)

Gets the ID of a given StoredFile

If the given parameter is already a StoredFile id it will directly return it.

static fileinfo(fileobj, filename=None, content_type=None, existing=None)

Tries to extract from the given input the actual file object, filename and content_type

This is used by the create and replace methods to correctly deduce their parameters from the available information when possible.

abstract get(file_or_id)

Opens the file given by its unique id.

This operation is guaranteed to return a StoredFile instance or should raise IOError if the file is not found.

abstract list()

Returns a list of file IDs that exist in the Storage.

Depending on the implementation there is the possibility that this returns more IDs than there have been created. Therefore this method is NOT guaranteed to be RELIABLE.

abstract replace(file_or_id, content, filename=None, content_type=None)

Replaces an existing file, an IOError is raised if the file didn’t already exist.

Given a StoredFile or its ID it will replace the current content with the provided content value. If filename and content_type are provided or can be deducted by the content itself they will also replace the previous values, otherwise the current values are kept.

class depot.io.local.LocalFileStorage(storage_path)

depot.io.interfaces.FileStorage implementation that stores files locally.

All the files are stored inside a directory specified by the storage_path parameter.

create(content, filename=None, content_type=None)

Saves a new file and returns the ID of the newly created file.

content parameter can either be bytes, another file object or a cgi.FieldStorage. When filename and content_type parameters are not provided they are deducted from the content itself.

delete(file_or_id)

Deletes a file. If the file didn’t exist it will just do nothing.

exists(file_or_id)

Returns if a file or its ID still exist.

get(file_or_id)

Opens the file given by its unique id.

This operation is guaranteed to return a StoredFile instance or should raise IOError if the file is not found.

list()

Returns a list of file IDs that exist in the Storage.

Depending on the implementation there is the possibility that this returns more IDs than there have been created. Therefore this method is NOT guaranteed to be RELIABLE.

replace(file_or_id, content, filename=None, content_type=None)

Replaces an existing file, an IOError is raised if the file didn’t already exist.

Given a StoredFile or its ID it will replace the current content with the provided content value. If filename and content_type are provided or can be deducted by the content itself they will also replace the previous values, otherwise the current values are kept.

class depot.io.memory.MemoryFileStorage(**kwargs)

depot.io.interfaces.FileStorage implementation that keeps files in memory.

This is generally useful for caches and tests.

create(content, filename=None, content_type=None)

Saves a new file and returns the ID of the newly created file.

content parameter can either be bytes, another file object or a cgi.FieldStorage. When filename and content_type parameters are not provided they are deducted from the content itself.

delete(file_or_id)

Deletes a file. If the file didn’t exist it will just do nothing.

exists(file_or_id)

Returns if a file or its ID still exist.

get(file_or_id)

Opens the file given by its unique id.

This operation is guaranteed to return a StoredFile instance or should raise IOError if the file is not found.

list()

Returns a list of file IDs that exist in the Storage.

Depending on the implementation there is the possibility that this returns more IDs than there have been created. Therefore this method is NOT guaranteed to be RELIABLE.

replace(file_or_id, content, filename=None, content_type=None)

Replaces an existing file, an IOError is raised if the file didn’t already exist.

Given a StoredFile or its ID it will replace the current content with the provided content value. If filename and content_type are provided or can be deducted by the content itself they will also replace the previous values, otherwise the current values are kept.

Utilities

depot.io.utils.file_from_content(content)

Provides a real file object from file content

Converts FileStorage, FileIntent and bytes to an actual file.

class depot.io.utils.FileIntent(fileobj, filename, content_type)

Represents the intention to upload a file

Whenever a file can be stored by depot, a FileIntent can be passed instead of the file itself. This permits to easily upload objects that are not files or to add missing information to the uploaded files.