ファイルアップロード¶

revision-up-to:	17812 (1.4)

多くの Web サイトにとって、ファイルアップロードのサポートは不可欠ですね。 Django がアップロードされたファイルを扱うとき、ファイルデータは最終的に request.FILES に入ります (request オブジェクトの詳細はリクエスト／レスポンスオブジェクトのドキュメントを参照してください)。このドキュメントでは、ファイルがどのようにしてディスクやメモリ上に保存されるかを説明し、そのデフォルトの動作をカスタマイズする方法について説明します。

ファイルアップロードの基本¶

FileField を含む以下のような簡単なフォームを考えてみましょう:

from django import forms

class UploadFileForm(forms.Form):
    title = forms.CharField(max_length=50)
    file  = forms.FileField()

このフォームからの入力を扱うビューは、ファイルデータを request.FILES で受け取ります。 request.FILES はファイルデータの入った辞書で、辞書のキーはフォームクラス中の FileField (または ImageField や FileField のサブクラス) の名前です。従って、上の例では、 request.FILES['file'] でファイルデータにアクセスできます。

もしリクエストメソッドが POST であり、尚且つ <form> においてアトリビュート enctype="multipart/form-data" を含むリクエストがポストされたのであれば、 request.FILES はデータのみを含んでいる事に注意して下さい。そうでない場合 request.FILES は空です。

ほとんどの場合は、「アップロードされたファイルをフォームに結びつける」の節で説明した方法に従って、 request からデータを取り出してフォームに渡すだけでアップロードファイルを処理できます:

from django.http import HttpResponseRedirect
from django.shortcuts import render_to_response
# アップロードファイルを処理する関数を import します
from somewhere import handle_uploaded_file

def upload_file(request):
    if request.method == 'POST':
        form = UploadFileForm(request.POST, request.FILES)
        if form.is_valid():
            handle_uploaded_file(request.FILES['file'])
            return HttpResponseRedirect('/success/url/')
    else:
        form = UploadFileForm()
    return render_to_response('upload.html', {'form': form})

request.FILES を明示的にフォームのコンストラクタに渡さねばならないので注意してください。これはフォームにファイルデータを結びつけるために必要な手順です。

アップロードファイルの処理¶

class UploadedFile¶

パズルの最後のピースは request.FILES からの実際のデータファイルをハンドリングすることです。この辞書の各エントリーはアップロードされたファイルをシンプルなラッパで包んだ UploadedFile オブジェクトです。通常、アップロードされた内容にアクセスする為にこれらのメソッドのいずれかを使う事になるでしょう:

read()¶: アップロードされたデータ全体をファイルから読み出します。このメソッドを使うときに十分注意してください。というのも、アップロードされたファイルが巨大だと、メモリに読み込む際にシステムの容量を越してしまうかもしれないからです。そのようなときは、後述の chunks() を使うとよいでしょう。

multiple_chunks()¶: ファイルが大きくて、複数のチャンクに分けて読み出すべきである場合に True を返します。デフォルトの設定では、 2.5 Mbytes より大きなファイルに対して True を返します。サイズの閾値は設定でき、後で説明します。

chunks¶

ファイルのチャンクを返すジェネレータです。 multiple_chunks() が True の場合には、 read() ではなくこのメソッドを使ってください。

実際には、常に chunks() を使うのがよいでしょう。後述の例を参照してください。

name¶: my_file.txt のような、アップロードされたファイルの名前です。

size¶: アップロードファイルのサイズ(単位バイト)です。

UploadedFile オブジェクトは他にもいくつかメソッドや属性を備えています。詳しくは UploadedFile オブジェクトを参照してください。

まとめると、アップロードファイルの一般的な処理例は以下の通りです:

def handle_uploaded_file(f):
    destination = open('some/file/name.txt', 'wb+')
    for chunk in f.chunks():
        destination.write(chunk)
    destination.close()

上の例では、巨大なファイルを read() してシステムの容量を超えないように、 UploadedFile.chunks() を使っています。

アップロードされたファイルの保存先¶

アップロードされたファイルデータは、処理され保存される前に、システムのどこかに一時的に記憶されていなければなりません。

デフォルトの設定では、アップロードされたファイルデータが 2.5 Mbytes より小さければ、 Django はファイルデータ全体をメモリに保持します。そのため、ファイルデータの保存処理はメモリからディスクへの書き込みだけで実現され、高速です。

しかし、ファイルデータが大きすぎる場合、 Django はファイルデータをシステムのテンポラリディレクトリに一時ファイルとして保存します。従って、 *nix ライクのプラットフォームでは、 Django は /tmp/tmpzfp6I6.upload のようなファイルを生成します。ファイルデータがとても大きければ、 Django がデータをディスクにストリーム書き込みするにつれて、一時ファイルのサイズが増えてゆくのを観察できるでしょう。

2.5 Mbytes や /tmp といった仕様は、単に「妥当なデフォルト値」にすぎません。アップロード時の挙動をカスタマイズしたり完全に置き換えたりしたければ、この後の詳細説明に進んでください。

アップロードファイルハンドラの挙動を変更する¶

ファイルアップロードの挙動は、以下の 3 つの設定で制御できます:

FILE_UPLOAD_MAX_MEMORY_SIZE

アップロードされたファイルをメモリに保存する上限のサイズです。設定値よりも大きなファイルがアップロードされると、ファイルデータはディスクに書き込まれます。デフォルト値は 2.5 Mbytes です。

FILE_UPLOAD_TEMP_DIR

FILE_UPLOAD_MAX_MEMORY_SIZE より大きなファイルがアップロードされたときにファイルデータを保存するディレクトリです。

デフォルト値はシステム標準の一時ファイルディレクトリです (UNIX ライクのシステムでは /tmp です)。

FILE_UPLOAD_PERMISSIONS

アップロードされたファイルに設定するファイルモードで、数字で表現 (例: 0644) します。ファイルモードの意味は os.chmod() のドキュメントを参照してください。

この値を設定しないか、 None にすると、アップロードされたファイルのモードはオペレーティングシステムに依存します。ほとんどのプラットフォームでは、一時ファイルのファイルモードは 0600 で、メモリからファイルにデータを書き出すときにはシステム標準の umask を使います。

Warning

ファイルモードにあまりくわしくないのなら、先頭の 0 がとても重要だということに注意してください。先頭の 0 は、値が 8 進数であることを示しています。 644 のように指定すると、全くおかしな挙動になってしまうでしょう。

ファイルモードの先頭には常に 0 をつけてください.

FILE_UPLOAD_HANDLERS

アップロードファイルを処理する実際のハンドラです。この設定を変更すると、ファイルアップロードの処理を完全にカスタマイズでき、 Django のアップロード処理全体の置き換えすらできます。詳しくは後述のアップロードハンドラを参照してください。

デフォルト値は以下の通りです:

("django.core.files.uploadhandler.MemoryFileUploadHandler",
 "django.core.files.uploadhandler.TemporaryFileUploadHandler",)

このデフォルトの設定では、アップロードされたファイルをまずメモリに保存しようと試み、その後ファイルへの保存を試みます。

`UploadedFile` オブジェクト¶

File から継承したものの他に、 UploadedFile オブジェクトは、以下のメソッドや属性を定義しています。

UploadedFile.content_type¶: content-type ヘッダの内容 (text/plain や application/pdf など) です。ユーザが指定した他のデータ同様、この値がアップロードされたファイルのコンテンツタイプを正確に表していると信用してはなりません。アップロードされたファイルのコンテンツタイプが content-type ヘッダと一致しているか確かめておく必要があります。「値は一応信用するが、検証し」てください。

UploadedFile.charset¶: content-type が text/* のときに、ブラウザが指定した文字セット (utf8 など) です。「値は一応信用するが、検証する」ようにしてください。

UploadedFile.temporary_file_path¶: アップロードファイルがディスクに一時保存されているときにのみ使えるメソッドで、一時ファイルの完全なパスを返します。

Note

通常の Python のファイルオブジェクトと同じく、アップロードファイルをイテレータとして扱うと、ファイルの内容を一行づつ読めます:

for line in uploadedfile:
    do_something_with(line)

しかし、標準の Python ファイルとは 違って 、 UploadedFile は改行文字として \n (いわゆる Unix形式) しか認識しません。 \n 以外の改行で終端されたアップロードファイルを処理する必要があるのなら、ビュー内で適切に処理する必要があります。

アップロードハンドラ¶

ユーザがファイルをアップロードすると、 Django はファイルデータを アップロードハンドラ (upload handler) と呼ばれるクラスに渡します。このクラスはアップロードされたファイルデータを処理するためのクラスです。デフォルトのアップロードハンドラは FILE_UPLOAD_HANDLERS で以下のように定義されています:

("django.core.files.uploadhandler.MemoryFileUploadHandler",
 "django.core.files.uploadhandler.TemporaryFileUploadHandler",)

MemoryFileUploadHandler と TemporaryFileUploadHandler は、Django のデフォルトのファイルアップロード処理、すなわち、小さいファイルはメモリに読み込み、大きいファイルはディスクに読み込むという動作を実現します。

カスタムのハンドラを書けば、ファイルの処理方法をカスタマイズできます。例えば、カスタムハンドラによってユーザレベルで容量制限を課したり、データをオンザフライで圧縮したり、プログレスバーを描画したり、受け取ったデータをローカルに保存せず、直接別のストレージに送ったりできます。

アップロードハンドラをオンザフライで変更する¶

ビューごとに別々のアップロード処理を行いたい場合があります。その場合、リクエストごとに request.upload_handlers を変更してアップロードハンドラのチェインをオーバライドできます。デフォルトでは、 request.upload_handlers には FILE_UPLOAD_HANDLERS に指定したハンドラのリストが入っていますが、これを他のリストに変更できます。

例えば、 ProgressBarUploadHandler というハンドラを書いて、 Ajax ウィジェットに何らかのアップロード状態のフィードバックを返させたいとしましょう。以下のようにすれば、アップロードハンドラチェインに自作のハンドラを付加できます:

request.upload_handlers.insert(0, ProgressBarUploadHandler())

この場合は、プログレスバーのハンドラを他のハンドラ よりも前に 実行したいので、 (append() ではなく) list.insert() を使うことになるでしょう。アップロードハンドラチェインは、順番に実行されることを思い出してください。

完全にアップロードハンドラチェインを置き換えてしまいたければ、単にリストを代入してください:

request.upload_handlers = [ProgressBarUploadHandler()]

Note

アップロードハンドラチェインを変更できるのは、 request.POST や request.FILES にアクセスする よりも前 だけです。アップロードの処理が始まってしまった後でハンドラを変更しても何の意味もありません。 request.POST や request.FILES を読み出した後で request.upload_handlers を変更しようとすると、 Django はエラーを送出します。

従って、アップロードハンドラチェインはビュー処理の出来るだけ早い段階で変更しておくことになるでしょう。また request.POST は通常与えられる CsrfViewMiddleware によって許可されます。これはビューの中でアップロードハンドラの変更をする為に csrf_exempt() を使う必要がある事を意味します。またそのとき csrf_protect() をリクエストの実際のプロセスの関数上で使う必要があります。このときハンドラがCSRFチェックが行われる前にファイルアップロードを受け取り始める可能性がある事に注意して下さい。 Example code:

from django.views.decorators.csrf import csrf_exempt, csrf_protect

@csrf_exempt
def upload_file_view(request):
    request.upload_handlers.insert(0, ProgressBarUploadHandler())
    return _upload_file_view(request)

@csrf_protect
def _upload_file_view(request):
    ... # Process request

カスタムのアップロードハンドラを書く¶

ファイルアップロードハンドラは、全て django.core.files.uploadhandler.FileUploadHandler のサブクラスでなければなりません。アップロードハンドラはどこに記述してもかまいません。

必須のメソッド¶

カスタムのファイルアップロードハンドラは以下のメソッドを必ず定義せねばなりません:

FileUploadHandler.receive_data_chunk(self, raw_data, start)

ファイルアップロード時に、データの「チャンク」を受け取ったときに呼び出されます。

raw_data はアップロードされたデータの入ったバイト文字列です。

start は raw_data チャンクのファイルデータ中の開始位置です。

このメソッドが返すデータは、次のアップロードハンドラの receive_data_chunk メソッドにフィードされます。この仕組みによって、あるハンドラにデータを「フィルタ」させ、他のハンドラに入力できます。

receive_data_chunk で受け取ったデータを後続のハンドラに処理させたくない場合には None を返してください。このメソッドは、アップロードされたデータを自分で処理して、他のハンドラにデータを保存させたくない場合に便利です。

StopUpload や SkipFile といった例外を送出すると、アップロード処理は中断し、アップロードファイルの処理を行いません。

FileUploadHandler.file_complete(self, file_size)

ファイルのアップロードが終了したときに呼び出されます。

このハンドラは request.FILES に入れるための UploadedFile オブジェクトを返さねばなりません。後続のアップロードハンドラに UploadedFile を返させたい場合は None を返してください。

オプションのメソッド¶

カスタムのアップロードハンドラでは、以下のオプションのメソッドや属性を定義できます:

FileUploadHandler.chunk_size

Django がアップロードファイルをメモリ上に読み込み、ハンドラに渡すときに使うチャンクのサイズです。バイト単位です。この属性は、 FileUploadHandler.receive_data_chunk で読み込まれるチャンクのサイズ指定でもあります。

パフォーマンスを最大化するには、チャンクのサイズを 4 の倍数とし、 2GB (2³¹ バイト) 以下とすべきです。複数のハンドラがそれぞれ別々のチャンクサイズを提供していた場合、 Django は最小のチャンクサイズを使います。

デフォルト値は 64*2¹⁰ バイトまたは 64 KB です。

FileUploadHandler.new_file(self, field_name, file_name, content_type, content_length, charset)

新たなファイルアップロードが開始されるときに呼び出されるコールバックです。このメソッドは、アップロードハンドラがまだデータを受け取っていない段階で呼び出されます。

field_name はファイルの <input> フィールドの名前です。

file_name は unicode のファイル名としてブラウザから提供された値です。

content_type は 'image/jpeg' のような MIME タイプで、ブラウザから提供された値です。

content_length はファイルの長さで、ブラウザから提供された値です。ブラウザがファイルサイズを提供しないこともあり、その場合は None です。

charset は (utf8 のような) 文字セットで、ブラウザから提供された値です。 content_length と同様、指定されないこともあります。

他のハンドラにファイルを処理させたくない場合、このメソッドから StopFutureHandlers 例外を送出してもかまいません。

FileUploadHandler.upload_complete(self)

ファイル全体のアップロードが終了したときに呼び出されるコールバックです。

FileUploadHandler.handle_raw_input(self, input_data, META, content_length, boundary, encoding)

このメソッドを使うと、生の HTTP 入力の解析を完全にオーバライドできます。

input_data は read() をサポートするファイルライクオブジェクトです。

META は request.META と同じです。

content_length は input_data に入っているデータの長さです。 input_data から content_length バイト以上を読み出そうとしてはなりません。

boundary はリクエストの MIME バウンダリです。

encoding はリクエストのエンコーディングです。

アップロードの処理を他のハンドラに継続させたい場合には None を、リクエストの直接処理に適したデータ構造を新たに生成して返したければ (POST, FILES) のタプルを返してください。

Django 1.4 documentation

ファイルアップロード¶