Objekt för begäran och svar

Snabb översikt

Django använder request- och response-objekt för att skicka tillstånd genom systemet.

När en sida begärs skapar Django ett HttpRequest-objekt som innehåller metadata om begäran. Sedan laddar Django den lämpliga vyn och skickar HttpRequest som första argument till view-funktionen. Varje vy är ansvarig för att returnera ett HttpResponse-objekt.

Detta dokument förklarar API:erna för objekten HttpRequest och HttpResponse, som definieras i modulen django.http.

HttpRequest-objekt

class HttpRequest[source]

Attribut

Alla attribut ska betraktas som skrivskyddade, om inget annat anges.

HttpRequest.scheme[source]

En sträng som representerar schemat för begäran (vanligtvis http eller https).

HttpRequest.body[source]

Den råa HTTP-begärans kropp som en bytestring. Detta är användbart för att bearbeta data på andra sätt än konventionella HTML-formulär: binära bilder, XML-nyttolast etc. För bearbetning av konventionella formulärdata, använd HttpRequest.POST.

Du kan också läsa från en HttpRequest med hjälp av ett filliknande gränssnitt med HttpRequest.read() eller HttpRequest.readline(). Om du kommer åt attributet body efter att du har läst begäran med någon av dessa I/O-strömmetoder kommer du att få ett RawPostDataException.

HttpRequest.path

En sträng som representerar den fullständiga sökvägen till den begärda sidan, exklusive schema, domän eller frågesträng.

Exempel: "/musik/band/the_beatles/"

HttpRequest.path_info

I vissa webbserverkonfigurationer delas den del av URL:en som följer efter värdnamnet upp i en del med skriptprefix och en del med sökvägsinformation. Attributet path_info innehåller alltid sökvägsinformationsdelen av sökvägen, oavsett vilken webbserver som används. Om du använder detta istället för path kan din kod bli enklare att flytta mellan test- och distributionsservrar.

Om till exempel WSGIScriptAlias för din applikation är inställd på "/minfo", kan path vara "/minfo/music/bands/the_beatles/" och path_info skulle vara "/music/bands/the_beatles/".

HttpRequest.method

En sträng som representerar den HTTP-metod som används i begäran. Detta är garanterat versaler. Till exempel:

if request.method == "GET":
    do_something()
elif request.method == "POST":
    do_something_else()

HttpRequest.encoding[source]

En sträng som representerar den aktuella kodning som används för att avkoda data från formuläret (eller None, vilket innebär att inställningen DEFAULT_CHARSET används). Du kan skriva till detta attribut för att ändra den kodning som används vid åtkomst till formulärdata. Alla efterföljande attributåtkomster (t.ex. läsning från GET eller POST) kommer att använda det nya encoding-värdet. Användbart om du vet att formulärdata inte är i DEFAULT_CHARSET-kodningen.

HttpRequest.content_type

En sträng som representerar MIME-typen för begäran, hämtad från rubriken CONTENT_TYPE.

HttpRequest.content_params

En ordbok med nyckel-/värdeparametrar som ingår i rubriken CONTENT_TYPE.

HttpRequest.GET

Ett ordboksliknande objekt som innehåller alla givna HTTP GET-parametrar. Se QueryDict-dokumentationen nedan.

HttpRequest.POST

Ett ordboksliknande objekt som innehåller alla angivna HTTP POST-parametrar, förutsatt att begäran innehåller formulärdata. Se dokumentationen för QueryDict nedan. Om du behöver komma åt rådata eller data som inte är formulärdata som skickas i begäran, kan du komma åt detta via attributet HttpRequest.body istället.

Det är möjligt att en begäran kan komma in via POST med en tom POST-ordbok - om, säg, ett formulär begärs via POST HTTP-metoden men inte innehåller formulärdata. Därför bör du inte använda if request.POST för att kontrollera om POST-metoden används; använd istället if request.method == "POST" (se HttpRequest.method).

POST innehåller inte information om filuppladdning. Se FILES.

HttpRequest.COOKIES

En ordbok som innehåller alla cookies. Nycklar och värden är strängar.

HttpRequest.FILES

Ett ordboksliknande objekt som innehåller alla uppladdade filer. Varje nyckel i FILES är namnet från <input type="file" name="">. Varje värde i FILES är en UploadedFile.

Se Hantera filer för mer information.

FILES kommer endast att innehålla data om förfrågningsmetoden var POST och <form> som skickade till förfrågan hade enctype="multipart/form-data". Annars kommer FILES att vara ett tomt ordboksliknande objekt.

HttpRequest.META

En ordbok som innehåller alla tillgängliga HTTP-rubriker. Vilka headers som finns beror på klient och server, men här är några exempel:

• CONTENT_LENGTH – Längden på begäran (som en sträng).

• CONTENT_TYPE – MIME-typen för förfrågningsunderlaget.

• HTTP_ACCEPT – Acceptabla innehållstyper för svaret.

• HTTP_ACCEPT_ENCODING – Godtagbara kodningar för svaret.

• HTTP_ACCEPT_LANGUAGE – Godtagbara språk för svaret.

• HTTP_HOST – HTTP-värdhuvudet som skickas av klienten.

• HTTP_REFERER – Hänvisningssidan, om sådan finns.

• HTTP_USER_AGENT – Klientens user-agent-sträng.

• QUERY_STRING – Frågesträngen, som en enda (oanalyserad) sträng.

• REMOTE_ADDR – Klientens IP-adress.

• REMOTE_HOST – Klientens värdnamn.

• REMOTE_USER – Den användare som autentiserats av webbservern, om sådan finns.

• REQUEST_METHOD – En sträng som till exempel "GET" eller "POST".

• SERVER_NAME – Värdnamnet på servern.

• SERVER_PORT – Serverns port (som en sträng).

Med undantag för CONTENT_LENGTH och CONTENT_TYPE, som anges ovan, konverteras alla HTTP-rubriker i begäran till META-nycklar genom att konvertera alla tecken till versaler, ersätta eventuella bindestreck med understreck och lägga till ett HTTP_-prefix till namnet. Så till exempel skulle en header som heter X-Bender mappas till META-nyckeln HTTP_X_BENDER.

Observera att runserver tar bort alla headers med understreck i namnet, så du kommer inte att se dem i META. Detta förhindrar header-spoofing baserat på tvetydighet mellan understreck och bindestreck som båda normaliseras till understreck i WSGI-miljövariabler. Det matchar beteendet hos webbservrar som Nginx och Apache 2.4+.

HttpRequest.headers är ett enklare sätt att komma åt alla HTTP-prefixerade headers, plus CONTENT_LENGTH och CONTENT_TYPE.

HttpRequest.headers[source]

Ett diktliknande objekt utan skiftlägeskänslighet som ger tillgång till alla HTTP-prefixerade rubriker (plus Content-Length och Content-Type) från begäran.

Namnet på varje rubrik stiliseras med title-casing (t.ex. User-Agent) när den visas. Du kan komma åt rubrikerna utan hänsyn till versaler:

>>> request.headers
{'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6', ...}

>>> "User-Agent" in request.headers
True
>>> "user-agent" in request.headers
True

>>> request.headers["User-Agent"]
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6)
>>> request.headers["user-agent"]
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6)

>>> request.headers.get("User-Agent")
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6)
>>> request.headers.get("user-agent")
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6)

För användning i t.ex. Django-mallar kan rubriker också sökas upp med hjälp av understrykningar i stället för bindestreck:

{{ request.headers.user_agent }}

HttpRequest.resolver_match

En instans av ResolverMatch som representerar den upplösta URL:en. Detta attribut anges endast efter att URL-lösningen har ägt rum, vilket innebär att det är tillgängligt i alla vyer men inte i mellanprogram som körs innan URL-lösningen äger rum (du kan dock använda det i process_view()).

Attribut som ställs in av applikationskoden

Django ställer inte in dessa attribut själv, men använder dem om de ställs in av din applikation.

HttpRequest.current_app

Malltaggen url kommer att använda dess värde som argumentet current_app till reverse().

HttpRequest.urlconf

Detta kommer att användas som rot-URLconf för den aktuella begäran och åsidosätter inställningen ROOT_URLCONF. Se Hur Django behandlar en förfrågan för detaljer.

urlconf kan sättas till None för att återställa alla ändringar som gjorts av tidigare middleware och återgå till att använda :inställningen:`ROOT_URLCONF`.

HttpRequest.exception_reporter_filter

Detta kommer att användas istället för DEFAULT_EXCEPTION_REPORTER_FILTER för den aktuella begäran. Se Anpassade felrapporter för detaljer.

HttpRequest.exception_reporter_class

Detta kommer att användas i stället för DEFAULT_EXCEPTION_REPORTER för den aktuella begäran. Se Anpassade felrapporter för detaljer.

Attribut som ställs in av mellanprogram

Vissa av de mellanprogram som ingår i Djangos Contrib-appar ställer in attribut på begäran. Om du inte ser attributet på en begäran, se till att lämplig middleware-klass är listad i MIDDLEWARE.

HttpRequest.session

Från :klass:`~django.contrib.sessions.middleware.SessionMiddleware`: Ett läsbart och skrivbart, ordboksliknande objekt som representerar den aktuella sessionen.

HttpRequest.site

Från CurrentSiteMiddleware: En instans av Site eller RequestSite som returneras av get_current_site() som representerar den aktuella webbplatsen.

HttpRequest.user

Från :klassen:`~django.contrib.auth.middleware.AuthenticationMiddleware`: En instans av AUTH_USER_MODEL som representerar den användare som för närvarande är inloggad. Om användaren inte är inloggad för närvarande kommer user att sättas till en instans av AnonymousUser. Du kan skilja dem åt med is_authenticated, så här:

if request.user.is_authenticated:
    ...  # Do something for logged-in users.
else:
    ...  # Do something for anonymous users.

Metoden auser() gör samma sak men kan användas från asynkrona kontexter.

Metoder

HttpRequest.auser()

Från :klass:`~django.contrib.auth.middleware.AuthenticationMiddleware`: Coroutine. Returnerar en instans av AUTH_USER_MODEL som representerar den användare som för närvarande är inloggad. Om användaren inte är inloggad för närvarande kommer auser att returnera en instans av AnonymousUser. Detta liknar attributet user men det fungerar i asynkrona sammanhang.

HttpRequest.get_host()[source]

Returnerar den ursprungliga värden för begäran med hjälp av information från rubrikerna HTTP_X_FORWARDED_HOST (om USE_X_FORWARDED_HOST` är aktiverat) och HTTP_HOST, i den ordningen. Om de inte ger något värde använder metoden en kombination av SERVER_NAME och SERVER_PORT enligt PEP 3333.

Exempel: "127.0.0.1:8000"

Utlöser django.core.exceptions.DisallowedHost om värden inte finns i ALLOWED_HOSTS eller domännamnet är ogiltigt enligt RFC 1034/1035.

Observera

Metoden get_host() misslyckas när värden ligger bakom flera proxyservrar. En lösning är att använda middleware för att skriva om proxy-rubrikerna, som i följande exempel:

class MultipleProxyMiddleware:
    FORWARDED_FOR_FIELDS = [
        "HTTP_X_FORWARDED_FOR",
        "HTTP_X_FORWARDED_HOST",
        "HTTP_X_FORWARDED_SERVER",
    ]

    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        """
        Rewrites the proxy headers so that only the most
        recent proxy is used.
        """
        for field in self.FORWARDED_FOR_FIELDS:
            if field in request.META:
                if "," in request.META[field]:
                    parts = request.META[field].split(",")
                    request.META[field] = parts[-1].strip()
        return self.get_response(request)

Denna middleware bör placeras före alla andra middleware som förlitar sig på värdet av get_host() – till exempel CommonMiddleware eller CsrfViewMiddleware.

HttpRequest.get_port()[source]

Returnerar den ursprungliga porten för begäran med hjälp av information från variablerna HTTP_X_FORWARDED_PORT (om USE_X_FORWARDED_PORT är aktiverat) och SERVER_PORT META, i den ordningen.

HttpRequest.get_full_path()[source]

Returnerar ”sökvägen”, plus en bifogad frågesträng, om tillämpligt.

Exempel: "/music/band/the_beatles/?print=true"

HttpRequest.get_full_path_info()[source]

Som get_full_path(), men använder path_info istället för path.

Exempel: "/minfo/music/bands/the_beatles/?print=true"

HttpRequest.build_absolute_uri(location=None)[source]

Returnerar den absoluta URI-formen av placering. Om ingen plats anges kommer platsen att sättas till request.get_full_path().

Om platsen redan är en absolut URI kommer den inte att ändras. I annat fall byggs den absoluta URI:n upp med hjälp av de servervariabler som finns tillgängliga i denna begäran. Exempelvis:

>>> request.build_absolute_uri()
'https://example.com/music/bands/the_beatles/?print=true'
>>> request.build_absolute_uri("/bands/")
'https://example.com/bands/'
>>> request.build_absolute_uri("https://example2.com/bands/")
'https://example2.com/bands/'

Observera

Att blanda HTTP och HTTPS på samma webbplats är inte önskvärt, därför kommer build_absolute_uri() alltid att generera en absolut URI med samma schema som den aktuella begäran har. Om du behöver omdirigera användare till HTTPS är det bäst att låta din webbserver omdirigera all HTTP-trafik till HTTPS.

HttpRequest.get_signed_cookie(key, default=RAISE_ERROR, salt='', max_age=None)[source]

Returnerar ett cookie-värde för en signerad cookie, eller ger upphov till ett django.core.signing.BadSignature undantag om signaturen inte längre är giltig. Om du anger argumentet default kommer undantaget att undertryckas och standardvärdet kommer att returneras istället.

Det valfria argumentet salt kan användas för att ge extra skydd mot brute force-attacker på din hemliga nyckel. Om det anges kommer argumentet max_age att kontrolleras mot den signerade tidsstämpel som är kopplad till cookie-värdet för att säkerställa att cookien inte är äldre än max_age sekunder.

Till exempel:

>>> request.get_signed_cookie("name")
'Tony'
>>> request.get_signed_cookie("name", salt="name-salt")
'Tony' # assuming cookie was set using the same salt
>>> request.get_signed_cookie("nonexistent-cookie")
KeyError: 'nonexistent-cookie'
>>> request.get_signed_cookie("nonexistent-cookie", False)
False
>>> request.get_signed_cookie("cookie-that-was-tampered-with")
BadSignature: ...
>>> request.get_signed_cookie("name", max_age=60)
SignatureExpired: Signature age 1677.3839159 > 60 seconds
>>> request.get_signed_cookie("name", False, max_age=60)
False

Se kryptografisk signering för mer information.

HttpRequest.is_secure()[source]

Returnerar True om begäran är säker, det vill säga om den gjordes med HTTPS.

HttpRequest.get_preferred_type(media_types)[source]

New in Django 5.2.

Returnerar den föredragna mimetypen från media_types, baserat på Accept-huvudet, eller None om klienten inte accepterar någon av de angivna typerna.

Anta att klienten skickar en Accept header av text/html,application/json;q=0.8:

>>> request.get_preferred_type(["text/html", "application/json"])
"text/html"
>>> request.get_preferred_type(["application/json", "text/plain"])
"application/json"
>>> request.get_preferred_type(["application/xml", "text/plain"])
None

Om mimetypen innehåller parametrar beaktas även dessa när den föredragna mediatypen bestäms. Till exempel:, med en Accept header av text/vcard;version=3.0,text/html;q=0.5, returvärdet av request.get_preferred_type() beror på de tillgängliga mediatyperna:

>>> request.get_preferred_type(
...     [
...         "text/vcard; version=4.0",
...         "text/vcard; version=3.0",
...         "text/vcard",
...         "text/directory",
...     ]
... )
"text/vcard; version=3.0"
>>> request.get_preferred_type(
...     [
...         "text/vcard; version=4.0",
...         "text/html",
...     ]
... )
"text/html"
>>> request.get_preferred_type(
...     [
...         "text/vcard; version=4.0",
...         "text/vcard",
...         "text/directory",
...     ]
... )
None

(För ytterligare information om hur innehållsförhandling utförs, se RFC 9110 Section 12.5.1)

De flesta webbläsare skickar Accept: */* som standard, vilket innebär att de inte har någon preferens, i vilket fall det första objektet i media_types skulle returneras.

Att ange ett explicit Accept-huvud i API-förfrågningar kan vara användbart för att returnera en annan innehållstyp endast för dessa konsumenter. Se Exempel på förhandling om innehåll för ett exempel på returnering av olika innehåll baserat på Accept-headern.

Observera

Om ett svar varierar beroende på innehållet i rubriken Accept och du använder någon form av cachning som Djangos cache middleware, bör du dekorera vyn med vary_on_headers('Accept') så att svaren cachas korrekt.

HttpRequest.accepts(mime_type)[source]

Returnerar True om begäran Accept header matchar mime_type argumentet:

>>> request.accepts("text/html")
True

De flesta webbläsare skickar Accept: */* som standard, så detta skulle returnera True för alla innehållstyper.

Se Exempel på förhandling om innehåll för ett exempel på hur man använder accepts() för att returnera olika innehåll baserat på Accept-huvudet.

HttpRequest.read(size=None)[source]

HttpRequest.readline()[source]

HttpRequest.readlines()[source]

HttpRequest.__iter__()[source]

Metoder som implementerar ett filliknande gränssnitt för att läsa från en HttpRequest-instans. Detta gör det möjligt att konsumera en inkommande begäran på ett strömmande sätt. Ett vanligt användningsfall skulle vara att bearbeta en stor XML-nyttolast med en iterativ parser utan att konstruera ett helt XML-träd i minnet.

Givet detta standardgränssnitt kan en HttpRequest-instans skickas direkt till en XML-parser som ElementTree:

import xml.etree.ElementTree as ET

for element in ET.iterparse(request):
    process(element)

QueryDict-objekt

class QueryDict[source]

I ett HttpRequest-objekt är attributen GET och POST instanser av django.http.QueryDict, en ordboksliknande klass som är anpassad för att hantera flera värden för samma nyckel. Detta är nödvändigt eftersom vissa HTML-formulärelement, särskilt <select multiple>, skickar flera värden för samma nyckel.

De QueryDict s på request.POST och request.GET kommer att vara oföränderliga när de nås i en normal begäran / svarscykel. För att få en föränderlig version måste du använda QueryDict.copy().

Metoder

QueryDict implementerar alla standardmetoder för ordböcker eftersom det är en underklass till dictionary. Undantag beskrivs här:

QueryDict.__init__(query_string=None, mutable=False, encoding=None)[source]

Instansierar ett QueryDict-objekt baserat på query_string.

>>> QueryDict("a=1&a=2&c=3")
<QueryDict: {'a': ['1', '2'], 'c': ['3']}>

Om query_string inte skickas in kommer den resulterande QueryDict att vara tom (den kommer inte att ha några nycklar eller värden).

De flesta QueryDict du stöter på, och i synnerhet de vid request.POST och request.GET, kommer att vara oföränderliga. Om du instansierar en själv kan du göra den mutabel genom att skicka mutable=True till dess __init__().

Strängar för inställning av både nycklar och värden konverteras från encoding till str. Om encoding inte är inställd, är standardvärdet DEFAULT_CHARSET.

classmethod QueryDict.fromkeys(iterable, value='', mutable=False, encoding=None)[source]

Skapar en ny QueryDict med nycklar från iterable och varje värde lika med value. Till exempel:

>>> QueryDict.fromkeys(["a", "a", "b"], value="val")
<QueryDict: {'a': ['val', 'val'], 'b': ['val']}>

QueryDict.__getitem__(key)

Returnerar det senaste värdet för den angivna nyckeln; eller en tom lista ([]) om nyckeln finns men inte har några värden. Utlöser django.utils.datastructures.MultiValueDictKeyError om nyckeln inte finns. (Detta är en subklass av Pythons standard KeyError, så du kan hålla dig till att fånga KeyError.)

>>> q = QueryDict("a=1&a=2&a=3", mutable=True)
>>> q.__getitem__("a")
'3'
>>> q.__setitem__("b", [])
>>> q.__getitem__("b")
[]

QueryDict.__setitem__(key, value)[source]

Sätter den angivna nyckeln till [value] (en lista vars enda element är value). Observera att denna, liksom andra ordboksfunktioner som har bieffekter, endast kan anropas på en föränderlig QueryDict (t.ex. en som skapades via QueryDict.copy()).

QueryDict.__contains__(key)

Returnerar True om den angivna nyckeln är inställd. Detta låter dig göra, t.ex., if "foo" in request.GET.

QueryDict.get(key, default=None)

Använder samma logik som __getitem__(), med en krok för att returnera ett standardvärde om nyckeln inte finns.

QueryDict.setdefault(key, default=None)[source]

Som dict.setdefault(), förutom att den använder __setitem__() internt.

QueryDict.update(other_dict)

Tar antingen en QueryDict eller en ordbok. Som dict.update(), förutom att den tillägger till de aktuella ordboksobjekten i stället för att ersätta dem. Till exempel:

>>> q = QueryDict("a=1", mutable=True)
>>> q.update({"a": "2"})
>>> q.getlist("a")
['1', '2']
>>> q["a"]  # returns the last
'2'

QueryDict.items()

Som dict.items(), men använder samma logik för sista värde som __getitem__() och returnerar ett iteratorobjekt i stället för ett vyobjekt. Till exempel:

>>> q = QueryDict("a=1&a=2&a=3")
>>> list(q.items())
[('a', '3')]

QueryDict.values()

Som dict.values(), men använder samma logik för sista värde som __getitem__() och returnerar en iterator i stället för ett vyobjekt. Till exempel:

>>> q = QueryDict("a=1&a=2&a=3")
>>> list(q.values())
['3']

Dessutom har QueryDict följande metoder:

QueryDict.copy()[source]

Returnerar en kopia av objektet med hjälp av copy.deepcopy(). Denna kopia kommer att vara mutabel även om originalet inte var det.

QueryDict.getlist(key, default=None)

Returnerar en lista över data med den begärda nyckeln. Returnerar en tom lista om nyckeln inte finns och default är None. Det är garanterat att en lista returneras om inte det angivna standardvärdet inte är en lista.

QueryDict.setlist(key, list_)[source]

Ställer in den angivna nyckeln till list_ (till skillnad från __setitem__`()).

QueryDict.appendlist(key, item)[source]

Lägger till ett objekt i den interna lista som är kopplad till nyckeln.

QueryDict.setlistdefault(key, default_list=None)[source]

Som setdefault(), men den tar en lista med värden i stället för ett enda värde.

QueryDict.lists()

Som items(), men innehåller alla värden, i form av en lista, för varje medlem i ordlistan. Till exempel:

>>> q = QueryDict("a=1&a=2&a=3")
>>> q.lists()
[('a', ['1', '2', '3'])]

QueryDict.pop(key)[source]

Returnerar en lista med värden för den angivna nyckeln och tar bort dem från ordlistan. Ger KeyError om nyckeln inte finns. Till exempel:

>>> q = QueryDict("a=1&a=2&a=3", mutable=True)
>>> q.pop("a")
['1', '2', '3']

QueryDict.popitem()[source]

Tar bort en godtycklig medlem i ordboken (eftersom det inte finns något begrepp för ordning) och returnerar en tupel med två värden som innehåller nyckeln och en lista över alla värden för nyckeln. Orsakar KeyError när den anropas på en tom ordbok. Till exempel:

>>> q = QueryDict("a=1&a=2&a=3", mutable=True)
>>> q.popitem()
('a', ['1', '2', '3'])

QueryDict.dict()

Returnerar en dict representation av QueryDict. För varje (nyckel, lista) par i QueryDict, kommer dict att ha (nyckel, objekt), där objektet är ett element i listan, med samma logik som QueryDict.__getitem__`():

>>> q = QueryDict("a=1&a=3&a=5")
>>> q.dict()
{'a': '5'}

QueryDict.urlencode(safe=None)[source]

Returnerar en sträng med data i frågesträngformat. Till exempel:

>>> q = QueryDict("a=2&b=3&b=5")
>>> q.urlencode()
'a=2&b=3&b=5'

Använd parametern safe för att skicka tecken som inte behöver kodas. Till exempel:

>>> q = QueryDict(mutable=True)
>>> q["next"] = "/a&b/"
>>> q.urlencode(safe="/")
'next=/a%26b/'

objekt för HttpResponse

class HttpResponse[source]

I motsats till HttpRequest-objekt, som skapas automatiskt av Django, är HttpResponse-objekt ditt ansvar. Varje vy du skriver är ansvarig för att instansiera, fylla i och returnera en HttpResponse.

Klassen HttpResponse finns i modulen django.http.

Användning

Överföring av strängar

Typisk användning är att skicka innehållet på sidan, som en sträng, bytestring eller memoryview, till HttpResponse-konstruktören:

>>> from django.http import HttpResponse
>>> response = HttpResponse("Here's the text of the web page.")
>>> response = HttpResponse("Text only, please.", content_type="text/plain")
>>> response = HttpResponse(b"Bytestrings are also accepted.")
>>> response = HttpResponse(memoryview(b"Memoryview as well."))

Men om du vill lägga till innehåll stegvis kan du använda response som ett filliknande objekt:

>>> response = HttpResponse()
>>> response.write("<p>Here's the text of the web page.</p>")
>>> response.write("<p>Here's another paragraph.</p>")

Överföra iteratorer

Slutligen kan du skicka HttpResponse en iterator i stället för strängar. HttpResponse kommer att konsumera iteratorn omedelbart, lagra dess innehåll som en sträng och kasta den. Objekt med en close()-metod, t.ex. filer och generatorer, stängs omedelbart.

Om du vill att svaret ska strömmas från iteratorn till klienten måste du använda klassen StreamingHttpResponse istället.

Ställa in rubrikfält

Om du vill ange eller ta bort ett rubrikfält i svaret använder du HttpResponse.headers:

>>> response = HttpResponse()
>>> response.headers["Age"] = 120
>>> del response.headers["Age"]

Du kan också manipulera rubriker genom att behandla ditt svar som en ordbok:

>>> response = HttpResponse()
>>> response["Age"] = 120
>>> del response["Age"]

Detta proxy till HttpResponse.headers, och är det ursprungliga gränssnittet som erbjuds av HttpResponse.

När du använder detta gränssnitt, till skillnad från en ordbok, ger inte del upphov till KeyError om rubrikfältet inte finns.

Du kan också ställa in rubriker vid instansiering:

>>> response = HttpResponse(headers={"Age": 120})

För att ställa in rubrikfälten Cache-Control och Vary rekommenderas det att använda metoderna patch_cache_control() och patch_vary_headers() från django.utils.cache, eftersom dessa fält kan ha flera kommaseparerade värden. ”Patch”-metoderna säkerställer att andra värden, t.ex. som lagts till av ett mellanprogram, inte tas bort.

HTTP-headerfält kan inte innehålla nya rader. Ett försök att ställa in ett rubrikfält som innehåller ett tecken för nya rader (CR eller LF) kommer att ge upphov till BadHeaderError

Tala om för webbläsaren att behandla svaret som en bifogad fil

Om du vill att webbläsaren ska behandla svaret som en bifogad fil anger du rubrikerna Content-Type och Content-Disposition. Så här kan du t.ex. returnera ett Microsoft Excel-kalkylblad:

>>> response = HttpResponse(
...     my_data,
...     headers={
...         "Content-Type": "application/vnd.ms-excel",
...         "Content-Disposition": 'attachment; filename="foo.xls"',
...     },
... )

Det finns inget Django-specifikt med Content-Disposition-headern, men det är lätt att glömma syntaxen, så vi har inkluderat den här.

Attribut

HttpResponse.content[source]

En bytestring som representerar innehållet, kodad från en sträng om så behövs.

HttpResponse.text[source]

New in Django 5.2.

En strängrepresentation av HttpResponse.content, avkodad med hjälp av svarets HttpResponse.charset (standard är UTF-8 om den är tom).

HttpResponse.cookies

Ett http.cookies.SimpleCookie-objekt som innehåller de cookies som ingår i svaret.

HttpResponse.headers

Ett diktliknande objekt som inte skiljer på skiftlägeskod och som ger ett gränssnitt till alla HTTP-rubriker i svaret, utom en Set-Cookie-rubrik. Se Ställa in rubrikfält och HttpResponse.cookies.

HttpResponse.charset

En sträng som anger den teckenuppsättning som svaret kommer att kodas med. Om den inte anges vid instantiering av HttpResponse kommer den att extraheras från content_type och om det inte lyckas kommer inställningen DEFAULT_CHARSET` att användas.

HttpResponse.status_code

Den HTTP-statuskod för svaret.

Om inte reason_phrase uttryckligen har angetts, kommer en ändring av värdet för status_code utanför konstruktören också att ändra värdet för reason_phrase.

HttpResponse.reason_phrase

HTTP-anledningsfras för svaret. Den använder HTTP-standardens standardanledningsfraser.

Om det inte uttryckligen anges bestäms reason_phrase av värdet på status_code.

HttpResponse.streaming

Detta är alltid False.

Detta attribut finns för att middleware ska kunna behandla strömmande svar på ett annat sätt än vanliga svar.

HttpResponse.closed

True om svaret har avslutats.

Metoder

HttpResponse.__init__(content=b'', content_type=None, status=200, reason=None, charset=None, headers=None)[source]

Instansierar ett HttpResponse-objekt med det angivna sidinnehållet, innehållstypen och sidhuvudena.

content är oftast en iterator, bytestring, memoryview, eller sträng. Andra typer konverteras till en bytestring genom att deras strängrepresentation kodas. Iteratorer bör returnera strängar eller bytestringar och dessa kommer att sammanfogas för att bilda innehållet i svaret.

content_type är MIME-typen som eventuellt kompletteras med en teckenuppsättningskodning och används för att fylla HTTP Content-Type-headern. Om den inte specificeras, bildas den av 'text/html' och DEFAULT_CHARSET-inställningarna, som standard: "text/html; charset=utf-8".

status är HTTP statuskod för svaret. Du kan använda Pythons http.HTTPStatus för meningsfulla alias, till exempel HTTPStatus.NO_CONTENT.

reason är HTTP-svarsfrasen. Om det inte anges kommer en standardfras att användas.

charset är den teckenuppsättning som svaret kommer att kodas med. Om det inte anges kommer det att extraheras från content_type, och om det inte lyckas kommer inställningen DEFAULT_CHARSET` att användas.

headers är en dict av HTTP-rubriker för svaret.

HttpResponse.__setitem__(header, value)

Sätter det angivna headernamnet till det angivna värdet. Både header och value bör vara strängar.

HttpResponse.__delitem__(header)

Raderar sidhuvudet med det angivna namnet. Misslyckas tyst om rubriken inte finns. Känslig för skiftlägesändringar.

HttpResponse.__getitem__(header)

Returnerar värdet för det angivna rubriknamnet. Saknar hänsyn till versaler.

HttpResponse.get(header, alternate=None)

Returnerar värdet för det angivna sidhuvudet, eller ett alternativ om sidhuvudet inte finns.

HttpResponse.has_header(header)

Returnerar True eller False baserat på en skiftlägesokänslig kontroll av en header med det angivna namnet.

HttpResponse.items()

Fungerar som dict.items() för HTTP-rubriker i svaret.

HttpResponse.setdefault(header, value)

Ställer in en header om den inte redan har ställts in.

HttpResponse.set_cookie(key, value='', max_age=None, expires=None, path='/', domain=None, secure=False, httponly=False, samesite=None)

Ställer in en cookie. Parametrarna är desamma som i Morsel cookie-objektet i Pythons standardbibliotek.

• max_age ska vara ett timedelta-objekt, ett heltal i sekunder eller None (standard) om cookien bara ska vara lika länge som klientens webbläsarsession. Om expires inte anges kommer den att beräknas.

• expires ska antingen vara en sträng i formatet "Wdy, DD-Mon-YY HH:MM:SS GMT" eller ett datetime.datetime-objekt i UTC. Om expires är ett datetime-objekt kommer max_age att beräknas.

• Använd domain om du vill ställa in en cookie för flera domäner. Till exempel: kommer domain="example.com" att ställa in en cookie som kan läsas av domänerna www.example.com, blog.example.com, etc. I annat fall kan en cookie endast läsas av den domän som satte den.

• Använd secure=True om du vill att cookien endast ska skickas till servern när en begäran görs med https-schema.

• Använd httponly=True om du vill förhindra att JavaScript på klientsidan får tillgång till cookien.

  HttpOnly är en flagga som ingår i en Set-Cookie HTTP-svarshuvud. Det är en del av RFC 6265-standarden för cookies och kan vara ett användbart sätt att minska risken för att ett skript på klientsidan får tillgång till skyddade cookie-data.

• Använd samesite='Strict' eller samesite='Lax' för att tala om för webbläsaren att inte skicka denna cookie när du utför en cross-origin begäran. SameSite stöds inte av alla webbläsare, så det är inte en ersättning för Djangos CSRF-skydd, utan snarare en åtgärd för djupförsvar.

  Använd samesite='None' (sträng) för att uttryckligen ange att denna cookie skickas med alla förfrågningar på samma webbplats och mellan webbplatser.

Varning

RFC 6265 anger att användaragenter bör stödja cookies på minst 4096 byte. För många webbläsare är detta också den maximala storleken. Django kommer inte att göra ett undantag om det finns ett försök att lagra en cookie på mer än 4096 byte, men många webbläsare kommer inte att ställa in cookien korrekt.

HttpResponse.set_signed_cookie(key, value, salt='', max_age=None, expires=None, path='/', domain=None, secure=False, httponly=False, samesite=None)

Som set_cookie(), men cryptographic signing cookien innan den sätts. Används tillsammans med HttpRequest.get_signed_cookie(). Du kan använda det valfria salt-argumentet för extra nyckelstyrka, men du måste komma ihåg att skicka det till motsvarande HttpRequest.get_signed_cookie()-anrop.

HttpResponse.delete_cookie(key, path='/', domain=None, samesite=None)

Raderar cookien med den angivna nyckeln. Misslyckas tyst om nyckeln inte finns.

På grund av hur cookies fungerar bör path och domain vara samma värden som du använde i set_cookie() - annars kanske cookien inte raderas.

HttpResponse.close()

Denna metod anropas i slutet av begäran direkt av WSGI-servern.

HttpResponse.write(content)[source]

Denna metod gör en HttpResponse-instans till ett filliknande objekt.

HttpResponse.flush()

Denna metod gör en HttpResponse-instans till ett filliknande objekt.

HttpResponse.tell()[source]

Denna metod gör en HttpResponse-instans till ett filliknande objekt.

HttpResponse.getvalue()[source]

Returnerar värdet av HttpResponse.content. Den här metoden gör en HttpResponse-instans till ett strömliknande objekt.

HttpResponse.readable()

Alltid False. Denna metod gör en HttpResponse-instans till ett strömliknande objekt.

HttpResponse.seekable()

Alltid False. Denna metod gör en HttpResponse-instans till ett strömliknande objekt.

HttpResponse.writable()[source]

Alltid True. Denna metod gör en HttpResponse-instans till ett strömliknande objekt.

HttpResponse.writelines(lines)[source]

Skriver en lista med rader till svaret. Linjeseparatorer läggs inte till. Den här metoden gör en HttpResponse-instans till ett strömliknande objekt.

underklasser till HttpResponse

Django innehåller ett antal underklasser av HttpResponse som hanterar olika typer av HTTP-svar. Precis som HttpResponse finns dessa underklasser i django.http.

class HttpResponseRedirect[source]

Det första argumentet till konstruktören är obligatoriskt - sökvägen som ska omdirigeras till. Detta kan vara en fullständigt kvalificerad URL (t.ex. 'https://www.yahoo.com/search/'), en absolut sökväg utan domän (t.ex. '/search/') eller till och med en relativ sökväg (t.ex. 'search/'). I det sista fallet kommer klientens webbläsare att rekonstruera den fullständiga URL:en själv enligt den aktuella sökvägen.

Konstruktören accepterar ett valfritt nyckelordsargument preserve_request som standard är False, vilket ger ett svar med en 302-statuskod. Om preserve_request är True blir statuskoden 307 istället.

Se HttpResponse för andra valfria konstruktörsargument.

url

Detta skrivskyddade attribut representerar den URL som svaret kommer att omdirigera till (motsvarande svarshuvudet Location).

Changed in Django 5.2:

Argumentet preserve_request lades till.

class HttpResponsePermanentRedirect[source]

Som HttpResponseRedirect, men den returnerar en permanent omdirigering (HTTP-statuskod 301) i stället för en ”hittad” omdirigering (statuskod 302). När preserve_request=True är statuskoden för svaret 308.

Changed in Django 5.2:

Argumentet preserve_request lades till.

class HttpResponseNotModified[source]

Konstruktören tar inte emot några argument och inget innehåll ska läggas till i detta svar. Använd detta för att ange att en sida inte har ändrats sedan användarens senaste begäran (statuskod 304).

class HttpResponseBadRequest[source]

Fungerar precis som HttpResponse men använder en 400-statuskod.

class HttpResponseNotFound[source]

Fungerar precis som HttpResponse men använder en 404-statuskod.

class HttpResponseForbidden[source]

Fungerar precis som HttpResponse men använder en 403-statuskod.

class HttpResponseNotAllowed[source]

Som HttpResponse, men använder en 405-statuskod. Det första argumentet till konstruktören är obligatoriskt: en lista över tillåtna metoder (t.ex. ['GET', 'POST']).

class HttpResponseGone[source]

Fungerar precis som HttpResponse men använder en 410-statuskod.

class HttpResponseServerError[source]

Fungerar precis som HttpResponse men använder en 500-statuskod.

Observera

Om en anpassad underklass av HttpResponse implementerar en render-metod, kommer Django att behandla den som en emulering av en SimpleTemplateResponse, och render-metoden måste själv returnera ett giltigt svarsobjekt.

Anpassade svarsklasser

Om du behöver en svarsklass som Django inte tillhandahåller kan du skapa den med hjälp av http.HTTPStatus. Till exempel:

from http import HTTPStatus
from django.http import HttpResponse


class HttpResponseNoContent(HttpResponse):
    status_code = HTTPStatus.NO_CONTENT

objekt för JsonResponse

class JsonResponse(data, encoder=DjangoJSONEncoder, safe=True, json_dumps_params=None, **kwargs)[source]

En HttpResponse-underklass som hjälper till att skapa ett JSON-kodat svar. Den ärver de flesta beteenden från sin superklass med ett par skillnader:

Dess standardrubrik Content-Type är inställd på application/json.

Den första parametern, data, bör vara en dict-instans. Om parametern afe är satt till False (se nedan) kan det vara vilket JSON-serialiserbart objekt som helst.

encoder, som som standard är django.core.serializers.json.DjangoJSONEncoder, kommer att användas för att serialisera data. Se JSON serialization för mer information om denna serialiserare.

Den booleska parametern safe är som standard inställd på True. Om den är inställd på False kan vilket objekt som helst skickas för serialisering (annars är endast dict-instanser tillåtna). Om afe är True och ett objekt som inte är dict skickas som första argument, kommer ett TypeError` att uppstå.

Parametern json_dumps_params är en ordlista med nyckelordsargument som ska skickas till anropet json.dumps() som används för att generera svaret.

Användning

Typisk användning kan se ut som:

>>> from django.http import JsonResponse
>>> response = JsonResponse({"foo": "bar"})
>>> response.content
b'{"foo": "bar"}'

Serialisering av objekt som inte är ordböcker

För att kunna serialisera andra objekt än dict måste du ställa in parametern afe till False:

>>> response = JsonResponse([1, 2, 3], safe=False)

Utan att ange safe=False kommer ett TypeError att uppstå.

Observera att ett API som baseras på dict-objekt är mer utbyggbart, flexibelt och gör det lättare att upprätthålla framåtkompatibilitet. Därför bör du undvika att använda icke-dict-objekt i JSON-kodade svar.

Varning

Före den 5:e upplagan av ECMAScript var det möjligt att förgifta JavaScript Array-konstruktören. Av denna anledning tillåter Django inte att skicka icke-dict-objekt till JsonResponse-konstruktören som standard. De flesta moderna webbläsare implementerar dock ECMAScript 5 som tar bort denna attackvektor. Därför är det möjligt att inaktivera denna säkerhetsåtgärd.

Ändra standard JSON-kodare

Om du behöver använda en annan JSON-kodningsklass kan du skicka parametern encoder till konstruktörsmetoden:

>>> response = JsonResponse(data, encoder=MyJSONEncoder)

StreamingHttpResponse-objekt

class StreamingHttpResponse[source]

Klassen StreamingHttpResponse används för att strömma ett svar från Django till webbläsaren.

Avancerad användning

StreamingHttpResponse är något avancerad, eftersom det är viktigt att veta om du kommer att servera din applikation synkront under WSGI eller asynkront under ASGI, och anpassa din användning på lämpligt sätt.

Läs dessa anvisningar med försiktighet.

Ett exempel på användning av StreamingHttpResponse under WSGI är att strömma innehåll när generering av svaret skulle ta för lång tid eller använda för mycket minne. Det är till exempel användbart för generering av stora CSV-filer.

Det finns dock prestandaöverväganden när du gör detta. Django, under WSGI, är utformad för kortlivade förfrågningar. Strömmande svar kommer att binda en arbetsprocess under hela svarets varaktighet. Detta kan resultera i dålig prestanda.

Generellt sett skulle du utföra dyra uppgifter utanför begäran-svar-cykeln, snarare än att tillgripa ett strömmat svar.

Vid servering under ASGI behöver dock en StreamingHttpResponse inte stoppa andra förfrågningar från att serveras medan de väntar på I/O. Detta öppnar upp för möjligheten till långlivade förfrågningar för strömmande innehåll och implementering av mönster som lång polling och server-sända händelser.

Även enligt ASGI note bör StreamingHttpResponse endast användas i situationer där det är absolut nödvändigt att hela innehållet inte itereras innan data överförs till klienten. Eftersom innehållet inte kan nås kan många mellanprogram inte fungera normalt. Till exempel: kan inte rubrikerna ETag och Content-Length genereras för strömmande svar.

Klassen StreamingHttpResponse är inte en underklass till HttpResponse, eftersom den har ett något annorlunda API. Den är dock nästan identisk, med följande anmärkningsvärda skillnader:

• Den bör ges en iterator som ger bytestrings, memoryview, eller strängar som innehåll. Vid servering under WSGI bör detta vara en sync-iterator. När det används under ASGI bör det vara en async-iterator.

• Du kan inte komma åt dess innehåll, förutom genom att iterera själva svarsobjektet. Detta bör endast ske när svaret returneras till klienten: du bör inte iterera svaret själv.

  Under WSGI kommer svaret att itereras synkront. Under ASGI kommer svaret att itereras asynkront. (Det är därför iterator-typen måste matcha det protokoll du använder)

  För att undvika en krasch kommer en felaktig iteratortyp att mappas till rätt typ under iterationen och en varning kommer att utfärdas, men för att göra detta måste iteratorn konsumeras helt och hållet, vilket motverkar syftet med att använda en StreamingHttpResponse överhuvudtaget.

• Den har inget content-attribut. Istället har den ett streaming_content-attribut. Detta kan användas i middleware för att omsluta svarets iterabel, men bör inte konsumeras.

• Det har inget text-attribut, eftersom det skulle kräva iterering av svarsobjektet.

• Du kan inte använda de filliknande objekten tell() eller write() metoderna. Om du gör det kommer ett undantag att uppstå.

Basklassen HttpResponseBase är gemensam för HttpResponse och StreamingHttpResponse.

Attribut

StreamingHttpResponse.streaming_content[source]

En iterator av svarsinnehållet, bytestringskodat enligt HttpResponse.charset.

StreamingHttpResponse.status_code

Den HTTP-statuskod för svaret.

Om inte reason_phrase uttryckligen har angetts, kommer en ändring av värdet för status_code utanför konstruktören också att ändra värdet för reason_phrase.

StreamingHttpResponse.reason_phrase

HTTP-anledningsfras för svaret. Den använder HTTP-standardens standardanledningsfraser.

Om det inte uttryckligen anges bestäms reason_phrase av värdet på status_code.

StreamingHttpResponse.streaming

Detta är alltid True.

StreamingHttpResponse.is_async

Boolean som anger om StreamingHttpResponse.streaming_content är en asynkron iterator eller inte.

Detta är användbart för mellanprogram som behöver omsluta StreamingHttpResponse.streaming_content.

Hantering av frånkopplingar

Om klienten kopplar bort sig under ett strömmande svar kommer Django att avbryta den coroutine som hanterar svaret. Om du vill städa upp resurser manuellt kan du göra det genom att fånga asyncio.CancelledError:

async def streaming_response():
    try:
        # Do some work here
        async for chunk in my_streaming_iterator():
            yield chunk
    except asyncio.CancelledError:
        # Handle disconnect
        ...
        raise


async def my_streaming_view(request):
    return StreamingHttpResponse(streaming_response())

Detta exempel visar bara hur man hanterar frånkoppling av klienten medan svaret strömmas. Om du utför långvariga operationer i din vy innan du returnerar objektet StreamingHttpResponse kanske du också vill :ref:hantera frånkopplingar i vyn <async-handling-disconnect> själv.

FileResponse-objekt

class FileResponse(open_file, as_attachment=False, filename='', **kwargs)[source]

FileResponse är en underklass till StreamingHttpResponse som är optimerad för binära filer. Den använder wsgi.file_wrapper om den tillhandahålls av wsgi-servern, annars strömmar den ut filen i små bitar.

Om as_attachment=True, sätts Content-Disposition rubriken till attachment, vilket ber webbläsaren att erbjuda filen till användaren som en nedladdning. I annat fall kommer ett Content-Disposition-huvud med värdet inline (webbläsarens standard) att anges endast om ett filnamn finns tillgängligt.

Om open_file inte har något namn eller om namnet på open_file inte är lämpligt, ange ett eget filnamn med hjälp av parametern filename. Observera att om du skickar ett filliknande objekt som io.BytesIO, är det din uppgift att seek() det innan du skickar det till FileResponse.

Rubriken Content-Length sätts automatiskt när den kan gissas från innehållet i open_file.

Rubriken Content-Type ställs in automatiskt när den kan gissas från filnamnet eller namnet på open_file.

FileResponse accepterar alla filliknande objekt med binärt innehåll, till exempel en fil som öppnas i binärt läge så här:

>>> from django.http import FileResponse
>>> response = FileResponse(open("myfile.png", "rb"))

Filen kommer att stängas automatiskt, så öppna den inte med en kontexthanterare.

Användning under ASGI

Pythons fil-API är synkront. Detta innebär att filen måste vara helt förbrukad för att kunna serveras under ASGI.

För att strömma en fil asynkront måste du använda ett tredjepartspaket som tillhandahåller ett API för asynkrona filer, t.ex. aiofiles.

Metoder

FileResponse.set_headers(open_file)[source]

Denna metod anropas automatiskt under initieringen av svaret och ställer in olika rubriker (Content-Length, Content-Type och Content-Disposition) beroende på open_file.

klassen ``HttpResponseBase

class HttpResponseBase[source]

Klassen HttpResponseBase är gemensam för alla Django-svar. Den bör inte användas för att skapa svar direkt, men den kan vara användbar för typkontroll.