アップロードされたファイルとアップロードハンドラー—Djangoドキュメント

アップロードされたファイルとアップロードハンドラー

アップロードされたファイル

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 ³¹ バイト）を超えないようにする必要があります。 複数のハンドラーによって提供されるチャンクサイズが複数ある場合、Djangoは任意のハンドラーによって定義された最小のチャンクサイズを使用します。

デフォルトは64 * 2 ¹⁰ バイト、つまり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.upload_interrupted()

バージョン3.2の新機能。

アップロードが中断されたことを通知するコールバック。 ファイルのアップロード中にユーザーがブラウザを閉じたとき。

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)のタプルを返します。