# Django 1.8.18.dev20170123152445 documentation

# File storage API

## Getting the current storage class

Django provides two convenient ways to access the current storage class:

class `DefaultStorage`

  `DefaultStorage` provides lazy access to the current default storage system as defined by `DEFAULT_FILE_STORAGE`. `DefaultStorage` uses `get_storage_class()` internally.

`get_storage_class`(import_path=None)

  Returns a class or module which implements the storage API.

  When called without the `import_path` parameter `get_storage_class` will return the current default storage system as defined by `DEFAULT_FILE_STORAGE`. If `import_path` is provided, `get_storage_class` will attempt to import the class or module from the given path and will return it if successful. An exception will be raised if the import is unsuccessful.

## The FileSystemStorage Class

class `FileSystemStorage`(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None)

  The `FileSystemStorage` class implements basic file storage on a local filesystem. It inherits from `Storage` and provides implementations for all the public methods thereof.

  `location`

    Absolute path to the directory that will hold the files. Defaults to the value of your `MEDIA_ROOT` setting.

  `base_url`

    URL that serves the files stored at this location. Defaults to the value of your `MEDIA_URL` setting.

  `file_permissions_mode`

    The file system permissions that the file will receive when it is saved. Defaults to `FILE_UPLOAD_PERMISSIONS`.

    The `file_permissions_mode` attribute was added. Previously files always received `FILE_UPLOAD_PERMISSIONS` permissions.

  `directory_permissions_mode`

    The file system permissions that the directory will receive when it is saved. Defaults to `FILE_UPLOAD_DIRECTORY_PERMISSIONS`.

    The `directory_permissions_mode` attribute was added. Previously directories always received `FILE_UPLOAD_DIRECTORY_PERMISSIONS` permissions.

  Note

  The `FileSystemStorage.delete()` method will not raise an exception if the given file name does not exist.

## The Storage Class

class `Storage`

  The `Storage` class provides a standardized API for storing files, along with a set of default behaviors that all other storage systems can inherit or override as necessary.

  Note

  For methods returning naive `datetime` objects, the effective timezone used will be the current value of `os.environ['TZ']`; note that this is usually set from Django’s `TIME_ZONE`.

  `accessed_time`(name)

    Returns a naive `datetime` object containing the last accessed time of the file. For storage systems that aren’t able to return the last accessed time this will raise `NotImplementedError` instead.

  `created_time`(name)

    Returns a naive `datetime` object containing the creation time of the file. For storage systems that aren’t able to return the creation time this will raise `NotImplementedError` instead.

  `delete`(name)

    Deletes the file referenced by `name`. If deletion is not supported on the target storage system this will raise `NotImplementedError` instead

  `exists`(name)

    Returns `True` if a file referenced by the given name already exists in the storage system, or `False` if the name is available for a new file.

  `get_available_name`(name, max_length=None)

    Returns a filename based on the `name` parameter that’s free and available for new content to be written to on the target storage system.

    The length of the filename will not exceed `max_length`, if provided. If a free unique filename cannot be found, a `SuspiciousFileOperation` exception will be raised.

    If a file with `name` already exists, an underscore plus a random 7 character alphanumeric string is appended to the filename before the extension.

    Previously, an underscore followed by a number (e.g. `"_1"`, `"_2"`, etc.) was appended to the filename until an available name in the destination directory was found. A malicious user could exploit this deterministic algorithm to create a denial-of-service attack. This change was also made in Django 1.6.6, 1.5.9, and 1.4.14.

    The `max_length` argument was added.

  `get_valid_name`(name)

    Returns a filename based on the `name` parameter that’s suitable for use on the target storage system.

  `listdir`(path)

    Lists the contents of the specified path, returning a 2-tuple of lists; the first item being directories, the second item being files. For storage systems that aren’t able to provide such a listing, this will raise a `NotImplementedError` instead.

  `modified_time`(name)

    Returns a naive `datetime` object containing the last modified time. For storage systems that aren’t able to return the last modified time, this will raise `NotImplementedError` instead.

  `open`(name, mode='rb')

    Opens the file given by `name`. Note that although the returned file is guaranteed to be a `File` object, it might actually be some subclass. In the case of remote file storage this means that reading/writing could be quite slow, so be warned.

  `path`(name)

    The local filesystem path where the file can be opened using Python’s standard `open()`. For storage systems that aren’t accessible from the local filesystem, this will raise `NotImplementedError` instead.

  `save`(name, content, max_length=None)

    Saves a new file using the storage system, preferably with the name specified. If there already exists a file with this name `name`, the storage system may modify the filename as necessary to get a unique name. The actual name of the stored file will be returned.

    The `max_length` argument is passed along to `get_available_name()`.

    The `content` argument must be an instance of `django.core.files.File` or of a subclass of `File`.

    The `max_length` argument was added.

  `size`(name)

    Returns the total size, in bytes, of the file referenced by `name`. For storage systems that aren’t able to return the file size this will raise `NotImplementedError` instead.

  `url`(name)

    Returns the URL where the contents of the file referenced by `name` can be accessed. For storage systems that don’t support access by URL this will raise `NotImplementedError` instead.