この文書では、ユーザがアップロードしたようなファイルに対する Django のファイルアクセス API について説明します。下位レベルの API は十分一般的なので、他の目的にも使えます。"静的ファイル" (JS や CSS など) を扱いたい場合は、 静的ファイル (画像、JavaScript、CSS など) を管理する を参照してください。
\nデフォルトでは、Django は MEDIA_ROOT と MEDIA_URL の設定を使って、ファイルをローカルに保存します。以下の例では、これらのデフォルトを使うことを前提にしています。
しかしながら、Djangoは、 Djangoがどこにどうやってファイルを保存するかの複雑なカスタムを許可するファイルストレージシステム file storage systems を提供しています。このドキュメントの後半では、それらのストレージシステムの働きについて説明します。
\nFileField や ImageField を使うと、 Django はそのファイルを扱うために使える API を提供します。
次のモデルを考えてみましょう。 ImageField を使って写真を保存します:
from django.db import models\n\n\nclass Car(models.Model):\n name = models.CharField(max_length=255)\n price = models.DecimalField(max_digits=5, decimal_places=2)\n photo = models.ImageField(upload_to="cars")\n specs = models.FileField(upload_to="specs")\nどの Car インスタンスにも photo 属性があり、それを使って添付写真の詳細を見ることができます:
>>> car = Car.objects.get(name="57 Chevy")\n>>> car.photo\n<ImageFieldFile: cars/chevy.jpg>\n>>> car.photo.name\n'cars/chevy.jpg'\n>>> car.photo.path\n'/media/cars/chevy.jpg'\n>>> car.photo.url\n'https://media.example.com/cars/chevy.jpg'\nこのオブジェクト（例では car.photo ）は File オブジェクトであり、以下に説明するすべてのメソッドと属性を持ちます。
例えば、ファイルの name にファイルストレージの場所（デフォルトの FileSystemStorage を使用している場合は MEDIA_ROOT ）からの相対パスを指定することで、ファイル名を変更できます:
>>> import os\n>>> from django.conf import settings\n>>> initial_path = car.photo.path\n>>> car.photo.name = "cars/chevy_ii.jpg"\n>>> new_path = os.path.join(settings.MEDIA_ROOT, car.photo.name)\n>>> # Move the file on the filesystem\n>>> os.rename(initial_path, new_path)\n>>> car.save()\n>>> car.photo.path\n'/media/cars/chevy_ii.jpg'\n>>> car.photo.path == new_path\nTrue\nディスク上の既存のファイルを FileField に保存します:
>>> from pathlib import Path\n>>> from django.core.files import File\n>>> path = Path("/some/external/specs.pdf")\n>>> car = Car.objects.get(name="57 Chevy")\n>>> with path.open(mode="rb") as f:\n... car.specs = File(f, name=path.name)\n... car.save()\n...\nFile オブジェクトLink to this heading#内部的には、Django はファイルを表現する必要があるときは常に django.core.files.File インスタンスを使います。
たいていの場合、Django から与えられた ファイル を使うことになるでしょう (つまり、上記のようにモデルに添付されたファイルや、アップロードされたファイルなど)。
自分で File を作成する必要がある場合、最も簡単な方法は Python 組み込みの file オブジェクトを使って作成することです:
>>> from django.core.files import File\n\n# Create a Python file object using open()\n>>> f = open("/path/to/hello.world", "w")\n>>> myfile = File(f)\nこれで、 File クラスのドキュメント化された属性とメソッドのすべてを使えるようになりました。
この方法で作成されたファイルは、自動的に閉じないことに注意してください。ファイルを自動的に閉じるには、以下の方法が便利です:
\n>>> from django.core.files import File\n\n# Create a Python file object using open() and the with statement\n>>> with open("/path/to/hello.world", "w") as f:\n... myfile = File(f)\n... myfile.write("Hello World")\n...\n>>> myfile.closed\nTrue\n>>> f.closed\nTrue\nファイルを閉じることは、多数のオブジェクトをループしてファイルフィールドにアクセスする場合に特に重要です。ファイルにアクセスした後、ファイルを手動でクローズしないと、ファイル記述子が不足する危険性があります。これは以下のようなエラーにつながる可能性があります:
\nOSError: [Errno 24] Too many open files\n舞台裏では、Django はファイルをどこにどのように保存するかという決定を、ファイルストレージシステムに委譲します。これは、ファイルシステム、ファイルを開いたり読み込んだりといったことを実際に理解するオブジェクトです。
\nDjango のデフォルトのファイルストレージは 'django.core.files.storage.FileSystemStorage' です。もし STORAGES 設定の default キーでストレージシステムを明示的に指定しなければ、これが使われます。
組み込みのデフォルトのファイルストレージシステムの詳細については以下を参照してください。また、独自のファイルストレージシステムを作成する方法については カスタムのストレージクラスを書く を参照してください。
\nほとんどの場合、適切なストレージにそのファイルを委任する File オブジェクトを使用したいと思うでしょう。しかし、ファイルストレージシステムを直接使うこともできます。独自のファイルストレージクラスのインスタンスを作成するか、（たいていはより便利な）グローバルなデフォルトストレージシステムを使用できます。
>>> from django.core.files.base import ContentFile\n>>> from django.core.files.storage import default_storage\n\n>>> path = default_storage.save("path/to/file", ContentFile(b"new content"))\n>>> path\n'path/to/file'\n\n>>> default_storage.size(path)\n11\n>>> default_storage.open(path).read()\nb'new content'\n\n>>> default_storage.delete(path)\n>>> default_storage.exists(path)\nFalse\nファイルストレージAPIについては ファイルストレージ API を参照してください。
\nDjango には django.core.files.storage.FileSystemStorage クラスが同梱されており、基本的なローカルファイルシステムのファイルストレージを実装しています。
例えば、以下のコードは MEDIA_ROOT の設定に関係なく、アップロードされたファイルを /media/photos に保存します:
from django.core.files.storage import FileSystemStorage\nfrom django.db import models\n\nfs = FileSystemStorage(location="/media/photos")\n\n\nclass Car(models.Model):\n ...\n photo = models.ImageField(storage=fs)\nカスタムのストレージシステム も同じように動作します。 FileField の storage 引数として渡すことができます。
呼び出し可能オブジェクトは FileField や ImageField の storage パラメータとして使用できます。これにより、実行時に使用するストレージを変更し、例えば環境ごとに異なるストレージを選択できます。
Your callable will be evaluated when your model classes are loaded, and must\nreturn an instance of Storage.
例:
\nfrom django.conf import settings\nfrom django.db import models\nfrom .storages import MyLocalStorage, MyRemoteStorage\n\n\ndef select_storage():\n return MyLocalStorage() if settings.DEBUG else MyRemoteStorage()\n\n\nclass MyModel(models.Model):\n my_file = models.FileField(storage=select_storage)\nSTORAGES 設定で定義されたストレージを設定するには storages を使います:
from django.core.files.storage import storages\n\n\ndef select_storage():\n return storages["mystorage"]\n\n\nclass MyModel(models.Model):\n upload = models.FileField(storage=select_storage)\nBecause the callable is evaluated when your model classes are loaded, if you\nneed to override the STORAGES setting in tests, you should use a\nLazyObject subclass instead:
from django.core.files.storage import storages\nfrom django.utils.functional import LazyObject\n\n\nclass OtherStorage(LazyObject):\n def _setup(self):\n self._wrapped = storages["mystorage"]\n\n\nmy_storage = OtherStorage()\n\n\nclass MyModel(models.Model):\n upload = models.FileField(storage=my_storage)\nLazyObject はストレージの評価を実際に必要になるまで遅延させるため、 override_settings() の効果を反映できるようになります：
@override_settings(\n STORAGES={\n "mystorage": {\n "BACKEND": "django.core.files.storage.InMemoryStorage",\n }\n }\n)\ndef test_storage():\n model = MyModel()\n assert isinstance(model.upload.storage, InMemoryStorage)\n