File オブジェクト

django.core.files モジュールとそのサブモジュールでは、Django の基本的なファイルハンドリングに関するビルトインクラスが定義されています。

File クラス

class File(file_object, name=None)[ソース]

File クラスは、Python の file object に Django 特有の追加機能を付け加えた薄いラッパーです。内部的でファイルを表現する必要がある場合には、Django はこのクラスを使います。

File オブジェクトには次の属性とメソッドを持ちます。

name

MEDIA_ROOT からの相対パスを含むファイル名です。

size

バイト単位で表されたファイルサイズ。

file

このクラスがラッピングしている、素の file object クラスです。

この属性をサブクラスで扱う場合には注意が必要です。

ContentFile や FieldFile など File のサブクラスは、この属性を Python の file object 以外のオブジェクトに置き換えることがあります。このような場合には、この属性自体は File のサブクラスであるかもしれません (が、同じサブクラスとは限りません)。そのため、可能な限り、サブクラスの file 属性ではなく、サブクラス自身が持つ属性やメソッドを使用するようにしてください。

mode

ファイルの読み込み/書き込みのモードです。

open(mode=None, *args, **kwargs)[ソース]

ファイルを開くか再オープンします（これは File.seek(0) も行います）。 mode 引数は、Python の組み込み関数 open() と同じ値を許可します。 *args と **kwargs は、mode の後に、Python の組み込み関数 open() に渡されます。

ファイルを再オープンする際、 mode はファイルが元々開かれていたモードを上書きします。 None はオリジナルのモードで再オープンすることを意味します。

コンテキストマネージャとして使用できます。たとえば、 with file.open() as f: のようにです。

Changed in Django 5.0:

*args と **kwargs を渡すためのサポートが追加されました。

__iter__()[ソース]

ファイルをイテレートして、1行ずつ返します。

chunks(chunk_size=None)[ソース]

ファイルをイテレートし、指定されたサイズの「チャンク」を生成します。 chunk_size のデフォルトは 64 KB です。

これは非常に大きなファイルに特に便利であり、ディスクからストリーミングしてメモリ全体にファイルを保存することを避けることができます。

multiple_chunks(chunk_size=None)[ソース]

chunk_size (一括サイズ) で指定されたファイルの全内容にアクセスするために複数のチャンクが必要な場合は True を返します。

close()[ソース]

ファイルを閉じてください。

リストされたメソッドに加えて、File は、その file オブジェクトの以下の属性とメソッドを公開しています: encoding, fileno, flush, isatty, newlines, read, readinto, readline, readlines, seek, tell, truncate, write, writelines, readable(), writable(), および seekable() 。

ContentFile クラス

class ContentFile(content, name=None)[ソース]

ContentFile クラスは File を継承していますが、File とは異なり、実際のファイルではなく文字列コンテンツ(バイトもサポート)で操作します。例えば：

from django.core.files.base import ContentFile

f1 = ContentFile("esta frase está en español")
f2 = ContentFile(b"these are bytes")

ImageFile クラス

class ImageFile(file_object, name=None)[ソース]

Django には画像専用の組み込みクラスがあります。 django.core.files.images.ImageFile は File のすべての属性とメソッドを継承し、さらに次のものを提供します:

width

画像の幅 (ピクセル単位)。

height

画像の高さ(ピクセル単位)。

オブジェクトに添付されたファイルに関する追加メソッド

オブジェクト（以下の Car.photo のように）に関連付けられた File には、いくつかの追加メソッドも用意されています。

File.save(name, content, save=True)

提供されたファイル名と内容で新しいファイルを保存します。これは既存のファイルを置き換えるものではありませんが、新しいファイルを作成し、オブジェクトがそれを指すように更新します。 save が True の場合、ファイルが保存されたらモデルの save() メソッドが一度呼び出されます。つまり、次の二行です:

>>> car.photo.save("myphoto.jpg", content, save=False)
>>> car.save()

これは以下と同等です:

>>> car.photo.save("myphoto.jpg", content, save=True)

content 引数は、 File または File のサブクラス（例えば、 ContentFile など）のインスタンスでなければなりません。

File.delete(save=True)

モデルインスタンスからファイルを削除し、基になるファイルも削除します。 save が True の場合、ファイルが削除された後にモデルの save() メソッドが一度呼び出されます。