Django v1.0 documentation

ファイルの管理

revision-up-to:8961 (1.0)
Django 1.0 で新たに登場しました.

このドキュメントでは、 Django のファイルアクセス API について解説します。

デフォルトの構成では、 Django は MEDIA_ROOTMEDIA_URL に基づいてファイルをローカルのファイルシステムに保存し ます。このドキュメントの以降の例では、デフォルトの構成での動作を想定してい ます。

ただし、 Django には ファイルストレージシステム をカスタマイズして、ファイルの保存方法を完全にカスタマイズする方法がありま す。このドキュメントの後半部分では、ストレージシステムの仕組みを説明します。

モデル内でファイルを扱う

モデル内で FileFieldImageField を使うと、 Django はフィールドに対し てファイルを操作するための API を提供します。

以下のような、写真の保存に FileField を使っているモデルを考えましょう:

class Car(models.Model):
    name = models.CharField(max_length=255)
    price = models.DecimalField(max_digits=5, decimal_places=2)
    photo = models.ImageField(upload_to='cars')

Car インスタンスには photo という属性ができ、この属性を使ってモデル に結びつけられたファイルの詳細を取得できます:

>>> car = Car.object.get(name="57 Chevy")
>>> car.photo
<ImageFieldFile: chevy.jpg>
>>> car.photo.name
u'cars/chevy.jpg'
>>> car.photo.path
u'/media/cars/chevy.jpg'
>>> car.photo.url
u'http://media.example.com/cars/chevy.jpg'

このオブジェクト (例中の car.photo) が File オブジェクトで、後で述 べるメソッドや属性を備えています。

File オブジェクト

内部的には、 Django はファイルを表現する必要がある場合には常に django.core.files.File を使います。このオブジェクトは Python の 組み込みファイルオブジェクト に対する薄いラッパで、 Django 固有の機能が追加されています。

普段は、単に (モデルに結びつけられたファイルや、アップロードされたファイル として) Django から渡される File オブジェクトを使うだけでしょう。

File オブジェクトを自分で生成したければ、 Python 組み込みの file オブジェクトを使うのが最も簡単です:

>>> from django.core.files import File

# Create a Python file object using open()
>>> f = open('/tmp/hello.world', 'w')
>>> myfile = File(f)

これで、 File の全ての属性やメソッドを使えます。 File の属性やメソッ ドは File オブジェクト で解説しています。

ファイルストレージ

舞台裏では、 Django はファイルの保存方法に関する決定をファイルストレージシ ステムに委ねています。ファイルストレージシステムは、ファイルシステムの構造 や、ファイルの開き方、データの読み出し方などを知っているオブジェクトです。

Django のデフォルトのファイルストレージは DEFAULT_FILE_STORAGE に設定します。明示的にストレージシステムを指定しなければ、デフォルトのファ イルストレージとしてこの設定の値を使います。組み込みのファイルストレージシ ステムの詳細は下記を参照してください。また、ファイルストレージシステムを自 作する方法は カスタムのストレージシステムを作成する を参照してください。

ストレージオブジェクト

ほとんどの場合は File オブジェクトを使い (File オブジェクトに実際 のストレージの操作を肩代りさせ) ますが、ストレージシステムの直接操作もでき ます。カスタムのファイルストレージクラスのインスタンスを生成したり、グロー バルなデフォルトのストレージシステムに設定したりできるのです:

>>> from django.core.files.storage import default_storage
>>> from django.core.files.base import ContentFile

>>> path = default_storage.save('/path/to/file', ContentFile('new content'))
>>> path
u'/path/to/file'

>>> default_storage.filesize(path)
11
>>> default_storage.open(path).read()
'new content'

>>> default_storage.delete(path)
>>> default_storage.exists(path)
False

ファイルストレージの API については ファイルストレージ API を参照してくだ さい。

組み込みのファイルシステムストレージクラス

Django には組み込みの FileSystemStorage クラスが付属しています (このク ラスは django.core.files.storage で定義されています)。 FileSystemStorage は基本的な機能を持ったローカルファイルシステムストレー ジの実装です。初期かメソッドは以下の二つの引数をとります:

引数 説明
location 省略可能です。ファイルを保存するディレクトリの絶対 パスです。省略すると、 MEDIA_ROOT の設定値を使 います。
base_url 省略可能です。保存されているファイルを公開する URL です。省略すると、 MEDIA_URL の設定値を使いま す。

例えば、以下のコードは、アップロードされたファイルを MEDIA_ROOT の設定 値と関係なく、 /media/photos 以下に保存します:

from django.db import models
from django.core.files.storage import FileSystemStorage

fs = FileSystemStorage(location='/media/photos')

class Car(models.Model):
    ...
    photo = models.ImageField(storage=fs)

カスタムのストレージシステム でも同じで、 FileFieldstorage にストレージのインスタンスを渡します。