アップロードされたファイルとアップロードハンドラー
アップロードされたファイル
- class UploadedFile
ファイルのアップロード中、実際のファイルデータは request.FILES に保存されます。 このディクショナリの各エントリは、UploadedFile
オブジェクト(またはサブクラス)–アップロードされたファイルのラッパーです。 通常、アップロードされたコンテンツにアクセスするには、次のいずれかの方法を使用します。
- UploadedFile.read()
- アップロードされたデータ全体をファイルから読み取ります。 この方法には注意してください。アップロードされたファイルが巨大な場合、メモリに読み込もうとするとシステムを圧倒する可能性があります。 代わりに
chunks()
を使用することをお勧めします。 下記参照。
- UploadedFile.multiple_chunks(chunk_size=None)
- アップロードされたファイルが複数のチャンクで読み取る必要があるほど大きい場合は、
True
を返します。 デフォルトでは、これは2.5メガバイトを超えるファイルになりますが、構成可能です。 下記参照。
- UploadedFile.chunks(chunk_size=None)
ファイルのチャンクを返すジェネレータ。
multiple_chunks()
がTrue
の場合、read()
の代わりに、このメソッドをループで使用する必要があります。実際には、
chunks()
を常に使用するのが最も簡単なことがよくあります。read()
を使用する代わりにchunks()
をループすることで、大きなファイルがシステムのメモリを圧倒しないようにします。
UploadedFile
のいくつかの便利な属性は次のとおりです。
- UploadedFile.name
- アップロードされたファイルの名前(例:
my_file.txt
)。
- UploadedFile.size
- アップロードされたファイルのサイズ(バイト単位)。
- UploadedFile.content_type
- ファイルとともにアップロードされたコンテンツタイプヘッダー(例: text / plain または application / pdf )。 ユーザーが提供する他のデータと同様に、アップロードされたファイルが実際にこのタイプであると信頼してはなりません。 それでも、ファイルにcontent-typeヘッダーが主張するコンテンツが含まれていることを検証する必要があります-「信頼するが検証する」。
- UploadedFile.content_type_extra
content-type
ヘッダーに渡される追加のパラメーターを含む辞書。 これは通常、Google App Engineなど、ユーザーに代わってファイルのアップロードを傍受して処理するサービスによって提供されます。 その結果、ハンドラーはアップロードされたファイルコンテンツを受信せず、代わりにファイルへのURLまたはその他のポインターを受信する場合があります( RFC 2388 を参照)。
- UploadedFile.charset
- text / * コンテンツタイプの場合、文字セット(つまり、
utf8
)ブラウザから提供されます。 ここでも、「信頼するが検証する」が最善のポリシーです。
ノート
通常のPythonファイルと同様に、アップロードされたファイルを反復処理することで、ファイルを1行ずつ読み取ることができます。
for line in uploadedfile:
do_something_with(line)
行はユニバーサルニューラインを使用して分割されます。 次の行の終わりとして認識されます:Unixの行末規則'\n'
、Windowsの規則'\r\n'
、および古いMacintoshの規則'\r'
。
UploadedFile
のサブクラスは次のとおりです。
- class TemporaryUploadedFile
- 一時的な場所にアップロードされたファイル(つまり ストリームからディスクへ)。 このクラスは、 TemporaryFileUploadHandler によって使用されます。 UploadedFile のメソッドに加えて、次の1つのメソッドが追加されています。
- TemporaryUploadedFile.temporary_file_path()
- 一時的にアップロードされたファイルへのフルパスを返します。
- class InMemoryUploadedFile
- メモリにアップロードされたファイル(つまり ストリームからメモリへ)。 このクラスは、 MemoryFileUploadHandler によって使用されます。
組み込みのアップロードハンドラ
MemoryFileUploadHandler と TemporaryFileUploadHandler を組み合わせることで、小さなファイルをメモリに、大きなファイルをディスクに読み込むというDjangoのデフォルトのファイルアップロード動作が提供されます。 それらはdjango.core.files.uploadhandler
にあります。
- class MemoryFileUploadHandler
アップロードをメモリにストリーミングするファイルアップロードハンドラー(小さなファイルに使用)。
- class TemporaryFileUploadHandler
TemporaryUploadedFile を使用してデータを一時ファイルにストリーミングするアップロードハンドラー。
カスタムアップロードハンドラーの作成
- class FileUploadHandler
すべてのファイルアップロードハンドラーは、django.core.files.uploadhandler.FileUploadHandler
のサブクラスである必要があります。 アップロードハンドラーはどこでも定義できます。
必要な方法
カスタムファイルアップロードハンドラーは、次のメソッドを定義する必要があります。
- FileUploadHandler.receive_data_chunk(raw_data, start)
ファイルのアップロードからデータの「チャンク」を受け取ります。
raw_data
は、アップロードされたデータを含むバイト文字列です。start
は、このraw_data
チャンクが始まるファイル内の位置です。返されたデータは、後続のアップロードハンドラーの
receive_data_chunk
メソッドに送られます。 このようにして、1つのハンドラーを他のハンドラーの「フィルター」にすることができます。None
をreceive_data_chunk
から返して、残りのアップロードハンドラーがこのチャンクを取得しないようにします。 これは、アップロードしたデータを自分で保存していて、将来のハンドラーにデータのコピーを保存させたくない場合に便利です。StopUpload
またはSkipFile
例外を発生させると、アップロードが中止されるか、ファイルが完全にスキップされます。
- FileUploadHandler.file_complete(file_size)
ファイルのアップロードが終了したときに呼び出されます。
ハンドラーは、
request.FILES
に格納されるUploadedFile
オブジェクトを返す必要があります。 ハンドラーは、None
を返し、UploadedFile
オブジェクトが後続のアップロードハンドラーから取得される必要があることを示す場合もあります。
オプションの方法
カスタムアップロードハンドラーは、次のオプションのメソッドまたは属性のいずれかを定義することもできます。
- FileUploadHandler.chunk_size
Djangoがメモリに保存してハンドラーにフィードする「チャンク」のサイズ(バイト単位)。 つまり、この属性は
FileUploadHandler.receive_data_chunk
に供給されるチャンクのサイズを制御します。最大のパフォーマンスを得るには、チャンクサイズを
4
で割り切れる必要があり、サイズが2 GB(2 31 バイト)を超えないようにする必要があります。 複数のハンドラーによって提供されるチャンクサイズが複数ある場合、Djangoは任意のハンドラーによって定義された最小のチャンクサイズを使用します。デフォルトは64 * 2 10 バイト、つまり64KBです。
- FileUploadHandler.new_file(field_name, file_name, content_type, content_length, charset, content_type_extra)
新しいファイルのアップロードが開始されていることを示すコールバック。 これは、データがアップロードハンドラーに送られる前に呼び出されます。
field_name
は、ファイル<input>
フィールドの文字列名です。file_name
は、ブラウザから提供されたファイル名です。content_type
は、ブラウザによって提供されるMIMEタイプです–例:'image/jpeg'
。content_length
は、ブラウザによって指定された画像の長さです。 これが提供されない場合があり、None
になります。charset
は文字セットです(つまり、utf8
)ブラウザによって指定されます。content_length
のように、これは提供されない場合があります。content_type_extra
は、content-type
ヘッダーからのファイルに関する追加情報です。 UploadedFile.content_type_extra を参照してください。このメソッドは、
StopFutureHandlers
例外を発生させて、将来のハンドラーがこのファイルを処理できないようにする場合があります。
- FileUploadHandler.upload_complete()
- アップロード全体(すべてのファイル)が完了したことを示すコールバック。
- FileUploadHandler.handle_raw_input(input_data, META, content_length, boundary, encoding)
ハンドラーが生のHTTP入力の解析を完全にオーバーライドできるようにします。
input_data
は、read()
-ingをサポートするファイルのようなオブジェクトです。META
はrequest.META
と同じオブジェクトです。content_length
は、input_data
のデータの長さです。input_data
からcontent_length
バイトを超えて読み取らないでください。boundary
は、このリクエストのMIME境界です。encoding
はリクエストのエンコーディングです。アップロード処理を続行する場合は
None
を返し、リクエストに適した新しいデータ構造を直接返す場合は(POST, FILES)
のタプルを返します。