ファイルストレージ API

デフォルトのストレージクラスの取得

Djangoでは、デフォルトストレージクラスにアクセスするための便利な方法を提供しています。

storages

A dictionary-like object that allows retrieving a storage instance using its alias as defined by STORAGES.

storages has an attribute backends, which defaults to the raw value provided in STORAGES.

Additionally, storages provides a create_storage() method that accepts the dictionary used in STORAGES for a backend, and returns a storage instance based on that backend definition. This may be useful for third-party packages needing to instantiate storages in tests:

>>> from django.core.files.storage import storages
>>> storages.backends
{'default': {'BACKEND': 'django.core.files.storage.FileSystemStorage'},
 'staticfiles': {'BACKEND': 'django.contrib.staticfiles.storage.StaticFilesStorage'},
 'custom': {'BACKEND': 'package.storage.CustomStorage'}}
>>> storage_instance = storages.create_storage({"BACKEND": "package.storage.CustomStorage"})

class DefaultStorage[ソース]

DefaultStorage は、STORAGES で定義された default キーによって定義されたデフォルトのストレージシステムへの遅延アクセスを提供します。 DefaultStorage は、内部的に storages を使用します。

default_storage

default_storage は DefaultStorage のインスタンスです。

FileSystemStorage クラス

class FileSystemStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None, allow_overwrite=False)[ソース]

FileSystemStorage クラスは、ローカルファイルシステム上での基本的なファイルストレージを実装しています。これは Storage から継承し、そこで定義されたすべてのパブリックメソッドに対する実装を提供します。

注釈

FileSystemStorage.delete() メソッドは、指定されたファイル名が存在しない場合に例外を発生させません。

location[ソース]

ファイルを格納するディレクトリの絶対パス。デフォルトは MEDIA_ROOT 設定の値です。

base_url[ソース]

この場所に保存されているファイルが提供される URL。デフォルトは MEDIA_URL 設定の値です。

file_permissions_mode[ソース]

保存される際にファイルが受け取るファイルシステムの権限。デフォルトは FILE_UPLOAD_PERMISSIONS です。

directory_permissions_mode[ソース]

保存された際にそのディレクトリが受け取るファイルシステムの権限。デフォルトは FILE_UPLOAD_DIRECTORY_PERMISSIONS です。

allow_overwrite

New in Django 5.1.

Flag to control allowing saving a new file over an existing one. Defaults to False.

get_created_time(name)[ソース]

システムの ctime、つまり os.path.getctime() の datetime を返します。一部のシステム(例えば Unix)では、これは最後のメタデータ変更の時間ですが、他のシステム(例えば Windows)では、ファイルの作成時間です。

InMemoryStorage クラス

class InMemoryStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None)[ソース]

InMemoryStorage クラスはメモリベースのファイルストレージを実装しています。永続性はありませんが、ディスクアクセスを避けることでテストの高速化に役立ちます。

location[ソース]

ファイルに割り当てられたディレクトリ名の絶対パス。デフォルトは、MEDIA_ROOT 設定値を使います。

base_url[ソース]

この場所に保存されているファイルが提供される URL。デフォルトは MEDIA_URL 設定の値です。

file_permissions_mode[ソース]

ファイルに割り当てられたファイルシステムの権限は、 FileSystemStorage との互換性を提供するために用意されています。デフォルトは FILE_UPLOAD_PERMISSIONS です。

directory_permissions_mode[ソース]

ディレクトリに割り当てられたファイルシステムの権限であり、 FileSystemStorage との互換性のために提供されます。デフォルトは FILE_UPLOAD_DIRECTORY_PERMISSIONS です。

Storage クラス

class Storage[ソース]

Storage クラスは、ファイルを保存するための標準化された API と、他のすべてのストレージシステムが継承または必要に応じてオーバーライドできる一連のデフォルト動作を提供します。

注釈

メソッドが naive な datetime オブジェクトを返す場合、実際に使用されるタイムゾーンは os.environ['TZ'] の現在の値になります。これは通常、Djangoの TIME_ZONE から設定されることに注意してください。

delete(name)[ソース]

name で参照されるファイルを削除します。対象のストレージシステムで削除がサポートされていない場合は、代わりに NotImplementedError を発生させます。

exists(name)[ソース]

Returns True if a file referenced by the given name already exists in the storage system.

get_accessed_time(name)[ソース]

ファイルの最終アクセス時刻を datetime で返します。最終アクセス時刻を返すことができないストレージシステムの場合は NotImplementedError を発生させます。

USE_TZ が True の場合、意識的（aware）な datetime を返します。それ以外の場合、ローカルタイムゾーンのナイーブ（naive）な datetime を返します。

get_alternative_name(file_root, file_ext)[ソース]

file_root および file_ext パラメータに基づいて代替ファイル名を返します。拡張子の前にアンダースコアとランダムな7文字の英数字文字列がファイル名に追加されます。

get_available_name(name, max_length=None)[ソース]

name パラメータに基づいて、ターゲットのストレージシステム上で新しいコンテンツを書き込むために利用可能かつ空いているファイル名を返します。

max_length を指定した場合、ファイル名の長さはその値を超えません。自由な一意のファイル名が見つからない場合、 SuspiciousFileOperation 例外が発生します。

name という名前のファイルが既に存在する場合、代替名を取得するために get_alternative_name() が呼び出されます。

get_created_time(name)[ソース]

ファイルの作成時間を datetime で返します。作成時間を返すことができないストレージシステムの場合、 NotImplementedError を発生させます。

USE_TZ が True の場合、意識的（aware）な datetime を返します。それ以外の場合、ローカルタイムゾーンのナイーブ（naive）な datetime を返します。

get_modified_time(name)[ソース]

ファイルの最終更新時間の datetime を返します。最終更新時間を返すことができないストレージシステムの場合、 NotImplementedError を発生させます。

USE_TZ が True の場合、意識的（aware）な datetime を返します。それ以外の場合、ローカルタイムゾーンのナイーブ（naive）な datetime を返します。

get_valid_name(name)[ソース]

name パラメータに基づいて、ターゲットのストレージシステムで使用に適したファイル名を返します。

generate_filename(filename)[ソース]

filename を get_valid_name() によって検証し、save() メソッドに渡すべきファイル名を返します。

filename 引数には、 FileField.upload_to によって返されたパスを含むことができます。その場合、パスは get_valid_name() に渡されることはありませんが、結果として得られた名前の前に再び追加されます。

デフォルトの実装では os.path 操作を使用しています。この方法があなたのストレージに適していない場合は、このメソッドをオーバーライドしてください。

listdir(path)[ソース]

指定されたパスの内容をリストアップし、2つのリストからなるタプルを返します。最初のアイテムはディレクトリで、2番目のアイテムはファイルです。このようなリストを提供できないストレージシステムでは、代わりに NotImplementedError を発生させます。

open(name, mode='rb')[ソース]

name で指定されたファイルを開きます。返されるファイルは必ず File オブジェクトである保証がありますが、実際にはサブクラスである可能性があります。リモートファイルストレージの場合、読み書きがかなり遅いかもしれないので注意してください。

path(name)[ソース]

ファイルがPythonの標準 open() を使って開けるローカルファイルシステムのパス。ローカルファイルシステムからアクセスできないストレージシステムの場合、代わりに NotImplementedError を発生させます。

save(name, content, max_length=None)[ソース]

ストレージシステムを使用して新しいファイルを保存します。すでに name という名前のファイルが存在する場合、ストレージシステムは一意な名前を得るために必要に応じてファイル名を変更することがあります。保存されたファイルの実際の名前が返されます。

max_length 引数は get_available_name() に渡されます。

content 引数は、django.core.files.File のインスタンス、または File でラップできるファイルライクオブジェクトでなければなりません。

size(name)[ソース]

name で参照されるファイルの総サイズ(バイト単位)を返します。ファイルサイズを返せないストレージシステムの場合は、代わりに NotImplementedError を発生させます。

url(name)[ソース]

name で参照されているファイルの内容にアクセスできるURLを返します。URLによるアクセスをサポートしていないストレージシステムの場合は、代わりに NotImplementedError を発生させます。