Uppladdade filer och uppladdningshanterare

Uppladdade filer

class UploadedFile[source]

Under filuppladdningar lagras de faktiska filuppgifterna i request.FILES. Varje post i denna ordbok är ett UploadedFile-objekt (eller en underklass) - ett omslag runt en uppladdad fil. Du kommer vanligtvis att använda en av dessa metoder för att komma åt det uppladdade innehållet:

UploadedFile.read()

Läs hela den uppladdade datan från filen. Var försiktig med den här metoden: om den uppladdade filen är enorm kan den överbelasta ditt system om du försöker läsa in den i minnet. Du vill förmodligen använda chunks() istället; se nedan.

UploadedFile.multiple_chunks(chunk_size=None)

Returnerar True om den uppladdade filen är tillräckligt stor för att kräva läsning i flera bitar. Som standard kommer detta att vara alla filer som är större än 2,5 megabyte, men det är konfigurerbart; se nedan.

UploadedFile.chunks(chunk_size=None)

En generator som returnerar bitar av filen. Om multiple_chunks() är True, bör du använda denna metod i en loop istället för read().

I praktiken är det ofta enklast att använda chunks() hela tiden. Att loopa över chunks() istället för att använda read() säkerställer att stora filer inte överväldigar systemets minne.

Här är några användbara attribut för UploadedFile:

UploadedFile.name

Namnet på den uppladdade filen (t.ex. my_file.txt).

UploadedFile.size

Storleken i byte på den uppladdade filen.

UploadedFile.content_type

Den innehållstyp som laddades upp med filen (t.ex. text/plain eller application/pdf). Som med alla data som tillhandahålls av användaren bör du inte lita på att den uppladdade filen faktiskt är av den här typen. Du måste fortfarande validera att filen innehåller det innehåll som innehållstypsrubriken anger - ”lita på men verifiera”

UploadedFile.content_type_extra

En ordbok som innehåller extra parametrar som skickas till rubriken content-type. Detta tillhandahålls vanligtvis av tjänster, t.ex. Google App Engine, som fångar upp och hanterar filuppladdningar för din räkning. Som ett resultat kanske din hanterare inte tar emot det uppladdade filinnehållet, utan istället en URL eller annan pekare till filen (se RFC 2388).

UploadedFile.charset

För innehållstyperna text/*, den teckenuppsättning (t.ex. utf8) som tillhandahålls av webbläsaren. Återigen, ”lita på men verifiera” är den bästa policyn här.

Observera

Precis som vanliga Python-filer kan du läsa filen rad för rad genom att iterera över den uppladdade filen:

for line in uploadedfile:
    do_something_with(line)

Rader delas med hjälp av universal newlines. En rad avslutas på följande sätt: Unix konvention för radavslut '\n', Windows konvention '\r\n' och den gamla Macintosh konventionen '\r'.

Underklasser av UploadedFile inkluderar:

class TemporaryUploadedFile[source]

En fil som laddas upp till en tillfällig plats (dvs. stream-to-disk). Den här klassen används av TemporaryFileUploadHandler. Förutom metoderna från UploadedFile har den ytterligare en metod:

TemporaryUploadedFile.temporary_file_path()[source]

Returnerar den fullständiga sökvägen till den temporärt uppladdade filen.

class InMemoryUploadedFile[source]

En fil som laddas upp till minnet (dvs. stream-to-memory). Den här klassen används av MemoryFileUploadHandler.

Inbyggda uppladdningshanterare

Tillsammans ger MemoryFileUploadHandler och TemporaryFileUploadHandler Djangos standardbeteende för filuppladdning genom att läsa små filer i minnet och stora filer på disken. De finns i django.core.files.uploadhandler.

class MemoryFileUploadHandler[source]

Filuppladdningshanterare för att strömma uppladdningar till minnet (används för små filer).

class TemporaryFileUploadHandler[source]

Uppladdningshanterare som strömmar data till en temporär fil med TemporaryUploadedFile.

Skriva anpassade uppladdningshanterare

class FileUploadHandler[source]

Alla filuppladdningshanterare bör vara underklasser till django.core.files.uploadhandler.FileUploadHandler. Du kan definiera uppladdningshanterare var du vill.

Erforderliga metoder

Anpassade filuppladdningshanterare måste definiera följande metoder:

FileUploadHandler.receive_data_chunk(raw_data, start)[source]

Tar emot en ”bit” data från filuppladdningen.

raw_data är en bytestring som innehåller den uppladdade datan.

start är den position i filen där den här raw_data-delen börjar.

De data du returnerar kommer att matas in i de efterföljande uppladdningshanterarnas receive_data_chunk-metoder. På så sätt kan en hanterare vara ett ”filter” för andra hanterare.

Returnera None från receive_data_chunk för att kortsluta återstående uppladdningshanterare från att hämta denna chunk. Detta är användbart om du lagrar den uppladdade datan själv och inte vill att framtida hanterare ska lagra en kopia av datan.

Om du skapar ett undantag för StopUpload eller SkipFile kommer uppladdningen att avbrytas eller filen att hoppas över helt.

FileUploadHandler.file_complete(file_size)[source]

Anropas när uppladdningen av en fil är klar.

Hanteraren bör returnera ett UploadedFile-objekt som kommer att lagras i request.FILES. Hanterare kan också returnera None för att ange att UploadedFile-objektet ska komma från efterföljande uppladdningshanterare.

Valfria metoder

Anpassade uppladdningshanterare kan också definiera någon av följande valfria metoder eller attribut:

FileUploadHandler.chunk_size

Storlek, i byte, på de ”chunks” som Django ska lagra i minnet och mata in i hanteraren. Det vill säga, detta attribut styr storleken på de chunks som matas in i FileUploadHandler.receive_data_chunk.

För maximal prestanda bör chunkstorlekarna vara delbara med 4 och bör inte överstiga 2 GB (2³¹ bytes) i storlek. När det finns flera chunkstorlekar som tillhandahålls av flera hanterare, kommer Django att använda den minsta chunkstorleken som definieras av någon hanterare.

Standardvärdet är 64*2¹⁰ bytes, eller 64 KB.

FileUploadHandler.new_file(field_name, file_name, content_type, content_length, charset, content_type_extra)[source]

Callback som signalerar att en ny filuppladdning startar. Detta anropas innan några data har matats till några uppladdningshanterare.

field_name är ett strängnamn på filens <input> fält.

file_name är filnamnet som tillhandahålls av webbläsaren.

content_type är den MIME-typ som tillhandahålls av webbläsaren - t.ex. 'image/jpeg'.

content_length är längden på bilden som anges av webbläsaren. Ibland kommer detta inte att tillhandahållas och kommer att vara None.

charset är den teckenuppsättning (t.ex. utf8) som anges av webbläsaren. Liksom content_length kommer detta ibland inte att tillhandahållas.

content_type_extra är extra information om filen från rubriken content-type. Se UploadedFile.content_type_extra <django.core.files.uploadedfile.UploadedFile.content_type_extra>`.

Denna metod kan ge upphov till ett StopFutureHandlers undantag för att förhindra att framtida handläggare hanterar denna fil.

FileUploadHandler.upload_complete()[source]

Återkallelse som signalerar att hela uppladdningen (alla filer) har slutförts.

FileUploadHandler.upload_interrupted()[source]

Återkallelse som signalerar att uppladdningen avbröts, t.ex. när användaren stängde sin webbläsare under filuppladdningen.

FileUploadHandler.handle_raw_input(input_data, META, content_length, boundary, encoding)[source]

Gör det möjligt för hanteraren att helt åsidosätta parsningen av den råa HTTP-ingången.

input_data är ett filliknande objekt som stöder read()-ing.

META är samma objekt som request.META.

content_length är längden på data i input_data. Läs inte mer än content_length bytes från input_data.

boundary är MIME-gränsen för denna begäran.

encoding är kodningen av begäran.

Returnera None om du vill att uppladdningshanteringen ska fortsätta, eller en tupel av (POST, FILES) om du vill returnera de nya datastrukturerna som passar för begäran direkt.