Standard filesystem storage
Attributes
| Attribute | Type | Description |
|---|
| base_location | string | The raw directory path where files are stored, defaulting to the MEDIA_ROOT setting if not provided. |
| location | string | The absolute file system path to the storage directory used for joining file names. |
| base_url | string | The base URL that serves the files from this storage, ensuring it ends with a trailing slash. |
| file_permissions_mode | integer | The numeric mode used to set permissions on saved files, falling back to the FILE_UPLOAD_PERMISSIONS setting. |
| directory_permissions_mode | integer | The numeric mode used when creating intermediate directories, falling back to the FILE_UPLOAD_DIRECTORY_PERMISSIONS setting. |
Constructor
Signature
def FileSystemStorage(
location: string = None,
base_url: string = None,
file_permissions_mode: int = None,
directory_permissions_mode: int = None,
allow_overwrite: boolean = False
) - > null
Parameters
| Name | Type | Description |
|---|
| location | string = None | The absolute path to the directory that will hold the files. |
| base_url | string = None | The URL that serves the files stored at this location. |
| file_permissions_mode | int = None | The file system permissions that the file will receive. |
| directory_permissions_mode | int = None | The file system permissions that the directory will receive. |
| allow_overwrite | boolean = False | A boolean indicating whether to overwrite existing files with the same name. |
Methods
base_location()
@classmethod
def base_location() - > string
Retrieves the raw base path for storage, defaulting to the MEDIA_ROOT setting if no specific location was provided.
Returns
| Type | Description |
|---|
string | The configured base directory path before absolute path resolution |
location()
@classmethod
def location() - > string
Provides the absolute file system path to the storage root directory.
Returns
| Type | Description |
|---|
string | The normalized absolute path of the storage location |
base_url()
@classmethod
def base_url() - > string
Retrieves the base URL used to serve files, ensuring it ends with a trailing slash for consistent URL joining.
Returns
| Type | Description |
|---|
string | The root URL for file access, defaulting to the MEDIA_URL setting |
file_permissions_mode()
@classmethod
def file_permissions_mode() - > integer
Determines the numeric mode used for setting permissions on newly created files.
Returns
| Type | Description |
|---|
integer | The file permission bitmask, such as 0o644 |
directory_permissions_mode()
@classmethod
def directory_permissions_mode() - > integer
Determines the numeric mode used for setting permissions on newly created directories.
Returns
| Type | Description |
|---|
integer | The directory permission bitmask, such as 0o755 |
delete()
@classmethod
def delete(
name: string
)
Removes the specified file or empty directory from the filesystem.
Parameters
| Name | Type | Description |
|---|
| name | string | The relative path of the file or directory to be deleted |
is_name_available()
@classmethod
def is_name_available(
name: string,
max_length: integer = null
) - > boolean
Checks if a filename can be used, bypassing existence checks if allow_overwrite is enabled.
Parameters
| Name | Type | Description |
|---|
| name | string | The filename to check for availability |
| max_length | integer = null | The maximum allowed length for the filename |
Returns
| Type | Description |
|---|
boolean | True if the name is available or overwriting is permitted, False otherwise |
get_alternative_name()
@classmethod
def get_alternative_name(
file_root: string,
file_ext: string
) - > string
Generates a variation of a filename to avoid collisions, or returns the original if overwriting is allowed.
Parameters
| Name | Type | Description |
|---|
| file_root | string | The filename without the extension |
| file_ext | string | The file extension including the leading dot |
Returns
| Type | Description |
|---|
string | A unique filename or the original filename if overwriting is enabled |
exists()
@classmethod
def exists(
name: string
) - > boolean
Checks whether the specified path exists on the filesystem, including broken symbolic links.
Parameters
| Name | Type | Description |
|---|
| name | string | The relative path to check for existence |
Returns
| Type | Description |
|---|
boolean | True if the path exists, False otherwise |
listdir()
@classmethod
def listdir(
path: string
) - > tuple
Lists the contents of the specified directory path.
Parameters
| Name | Type | Description |
|---|
| path | string | The relative directory path to inspect |
Returns
| Type | Description |
|---|
tuple | A tuple containing two lists: (directories, files) found at the path |
path()
@classmethod
def path(
name: string
) - > string
Converts a relative name into an absolute filesystem path while preventing directory traversal attacks.
Parameters
| Name | Type | Description |
|---|
| name | string | The relative path to be joined with the storage root |
Returns
| Type | Description |
|---|
string | The safe, absolute filesystem path |
size()
@classmethod
def size(
name: string
) - > integer
Retrieves the total size of the specified file in bytes.
Parameters
| Name | Type | Description |
|---|
| name | string | The relative path of the file to measure |
Returns
| Type | Description |
|---|
integer | The file size in bytes |
url()
@classmethod
def url(
name: string
) - > string
Constructs an absolute URL for accessing the file via a web browser.
Parameters
| Name | Type | Description |
|---|
| name | string | The relative path of the file to generate a URL for |
Returns
| Type | Description |
|---|
string | The full URL to the file |
get_accessed_time()
@classmethod
def get_accessed_time(
name: string
) - > datetime
Retrieves the last access time of the specified file.
Parameters
| Name | Type | Description |
|---|
| name | string | The relative path of the file |
Returns
| Type | Description |
|---|
datetime | The datetime when the file was last accessed |
get_created_time()
@classmethod
def get_created_time(
name: string
) - > datetime
Retrieves the creation time of the specified file.
Parameters
| Name | Type | Description |
|---|
| name | string | The relative path of the file |
Returns
| Type | Description |
|---|
datetime | The datetime when the file was created |
get_modified_time()
@classmethod
def get_modified_time(
name: string
) - > datetime
Retrieves the last modification time of the specified file.
Parameters
| Name | Type | Description |
|---|
| name | string | The relative path of the file |
Returns
| Type | Description |
|---|
datetime | The datetime when the file content was last changed |