http.cookiejar — Cookiehantering för HTTP-klienter

Källkod: Lib/http/cookiejar.py

Modulen http.cookiejar definierar klasser för automatisk hantering av HTTP-cookies. Den är användbar för att komma åt webbplatser som kräver att små bitar av data – cookies – sätts på klientmaskinen av ett HTTP-svar från en webbserver och sedan returneras till servern i senare HTTP-förfrågningar.

Både det vanliga Netscape-cookieprotokollet och det protokoll som definieras av RFC 2965 hanteras. RFC 2965-hanteringen är avstängd som standard. RFC 2109-cookies analyseras som Netscape-cookies och behandlas därefter antingen som Netscape- eller RFC 2965-cookies enligt gällande ”policy”. Observera att de allra flesta cookies på Internet är Netscape-cookies. http.cookiejar försöker följa Netscapes de facto cookieprotokoll (som skiljer sig väsentligt från det som anges i den ursprungliga Netscape-specifikationen), inklusive att notera cookieattributen max-age och port som introducerades med RFC 2965.

Anteckning

De olika namngivna parametrarna som finns i Set-Cookie och Set-Cookie2 (t.ex. domain och expires) kallas konventionellt för attributes. För att skilja dem från Python-attribut använder dokumentationen för den här modulen termen cookie-attribut istället.

Modulen definierar följande undantag:

exception http.cookiejar.LoadError

Instanser av FileCookieJar ger upphov till detta undantag om det inte går att ladda cookies från en fil. LoadError är en underklass till OSError.

Ändrad i version 3.3: LoadError var tidigare en subtyp av IOError, som nu är ett alias av OSError.

Följande klasser erbjuds:

class http.cookiejar.CookieJar(policy=None)

policy är ett objekt som implementerar gränssnittet CookiePolicy.

Klassen CookieJar lagrar HTTP-cookies. Den extraherar cookies från HTTP-förfrågningar och returnerar dem i HTTP-svar. Instanser av CookieJar förfaller automatiskt när det behövs. Underklasser är också ansvariga för att lagra och hämta cookies från en fil eller databas.

class http.cookiejar.FileCookieJar(filename=None, delayload=None, policy=None)

policy är ett objekt som implementerar gränssnittet CookiePolicy. För övriga argument, se dokumentationen för motsvarande attribut.

En CookieJar som kan ladda cookies från, och kanske spara cookies till, en fil på disken. Kakor laddas INTE från den angivna filen förrän antingen metoden load() eller revert() anropas. Underklasser till denna klass finns dokumenterade i avsnitt FileCookieJar-underklasser och samarbete med webbläsare.

Denna ska inte initieras direkt - använd istället dess underklasser nedan.

Ändrad i version 3.8: Filnamnsparametern stöder en path-like object.

class http.cookiejar.CookiePolicy

Denna klass ansvarar för att avgöra om varje cookie ska accepteras från/returneras till servern.

class http.cookiejar.DefaultCookiePolicy(blocked_domains=None, allowed_domains=None, netscape=True, rfc2965=False, rfc2109_as_netscape=None, hide_cookie2=False, strict_domain=False, strict_rfc2965_unverifiable=True, strict_ns_unverifiable=False, strict_ns_domain=DefaultCookiePolicy.DomainLiberal, strict_ns_set_initial_dollar=False, strict_ns_set_path=False, secure_protocols=('https', 'wss'))

Konstruktörsargument ska endast skickas som nyckelordsargument. blocked_domains är en sekvens av domännamn som vi aldrig accepterar cookies från eller returnerar cookies till. allowed_domains om inte None, är detta en sekvens av de enda domäner som vi accepterar och returnerar cookies för. secure_protocols är en sekvens av protokoll för vilka säkra cookies kan läggas till. Som standard anses https och wss (secure websocket) vara säkra protokoll. För alla andra argument, se dokumentationen för objekten CookiePolicy och DefaultCookiePolicy.

DefaultCookiePolicy implementerar standardreglerna för att acceptera och avvisa cookies från Netscape och RFC 2965. Som standard behandlas RFC 2109 cookies (dvs. cookies som tas emot i en Set-Cookie header med en version cookie-attribut på 1) enligt RFC 2965-reglerna. Men om RFC 2965-hanteringen är avstängd eller om rfc2109_as_netscape är True, ”nedgraderas” RFC 2109-cookies av CookieJar-instansen till Netscape-cookies, genom att attributet version i Cookie-instansen sätts till 0. DefaultCookiePolicy innehåller också några parametrar som gör det möjligt att finjustera policyn.

class http.cookiejar.Cookie

Denna klass representerar Netscape, RFC 2109 och RFC 2965 cookies. Det förväntas inte att användare av http.cookiejar konstruerar sina egna Cookie-instanser. Anropa istället, om nödvändigt, make_cookies() på en CookieJar-instans.

Se även

Modulen urllib.request

URL-öppning med automatisk cookiehantering.

Modul http.cookies

HTTP-cookieklasser, främst användbara för kod på serversidan. Modulerna http.cookiejar och http.cookies är inte beroende av varandra.

https://curl.se/rfc/cookie_spec.html

Specifikationen av det ursprungliga Netscape cookie-protokollet. Även om detta fortfarande är det dominerande protokollet, har ”Netscape cookie protocol” som implementeras av alla större webbläsare (och http.cookiejar) bara en flyktig likhet med det som skisseras i cookie_spec.html.

RFC 2109 - HTTP:s mekanism för tillståndshantering

Föråldrad av RFC 2965. Använder Set-Cookie med version=1.

RFC 2965 - HTTP:s mekanism för tillståndshantering

Netscape-protokollet med rättade buggar. Använder Set-Cookie2 i stället för Set-Cookie. Används inte i någon större utsträckning.

https://kristol.org/cookie/errata.html

Oavslutad errata till RFC 2965.

RFC 2964 - Användning av HTTP State Management

CookieJar- och FileCookieJar-objekten

CookieJar-objekt stöder iterator-protokollet för iterering över ingående Cookie-objekt.

CookieJar har följande metoder:

Lägg till korrekt Cookie header i request.

Om policyn tillåter det (dvs. attributen rfc2965 och hide_cookie2 i CookieJar:s CookiePolicy-instans är true respektive false), läggs även rubriken Cookie2 till när så är lämpligt.

Objektet request (vanligtvis en instans av urllib.request.Request) måste stödja metoderna get_full_url(), has_header(), get_header(), header_items(), add_unredirected_header() och attributen host, type, unverifiable och origin_req_host som dokumenteras av urllib.request.

Ändrad i version 3.3: request-objektet behöver attributet origin_req_host. Beroendet av en föråldrad metod get_origin_req_host() har tagits bort.

CookieJar.extract_cookies(response, request)

Extrahera cookies från HTTP svar och lagra dem i CookieJar, där det är tillåtet enligt policy.

CookieJar letar efter tillåtna Set-Cookie och Set-Cookie2-rubriker i argumentet response och lagrar cookies på lämpligt sätt (med förbehåll för godkännande av metoden CookiePolicy.set_ok()).

Objektet response (vanligtvis resultatet av ett anrop till urllib.request.urlopen(), eller liknande) bör stödja en info()-metod, som returnerar en email.message.Message-instans.

Objektet request (vanligtvis en instans av urllib.request.Request) måste stödja metoden get_full_url() och attributen host, unverifiable och origin_req_host, enligt dokumentationen i urllib.request. Begäran används för att ange standardvärden för cookie-attribut samt för att kontrollera att cookien får sättas.

Ändrad i version 3.3: request-objektet behöver attributet origin_req_host. Beroendet av en föråldrad metod get_origin_req_host() har tagits bort.

CookieJar.set_policy(policy)

Ange vilken instans av CookiePolicy som ska användas.

CookieJar.make_cookies(response, request)

Returnerar sekvens av Cookie-objekt extraherade från response-objektet.

Se dokumentationen för extract_cookies() för de gränssnitt som krävs av argumenten response och request.

Ange en Cookie om policyn säger att det är OK att göra det.

Ställ in en Cookie, utan att kontrollera med policyn om den ska ställas in eller inte.

CookieJar.clear([domain[, path[, name]]])

Rensa några cookies.

Om den anropas utan argument rensas alla cookies. Om ett enda argument anges kommer endast cookies som tillhör den domänen att tas bort. Om två argument anges tas cookies som hör till den angivna domänen och URL-adressen sökväg bort. Om tre argument anges tas cookien med de angivna domän, sökväg och namn bort.

Utlöser KeyError om ingen matchande cookie finns.

CookieJar.clear_session_cookies()

Kassera alla sessionscookies.

Slänger alla cookies som har attributet true discard (vanligtvis för att de antingen inte hade något cookie-attribut max-age eller expires, eller ett explicit cookie-attribut discard). För interaktiva webbläsare motsvarar slutet på en session vanligtvis att webbläsarfönstret stängs.

Observera att metoden save() ändå inte sparar sessionskakor, såvida du inte begär något annat genom att ange ett sant ignore_discard-argument.

FileCookieJar implementerar följande ytterligare metoder:

FileCookieJar.save(filename=None, ignore_discard=False, ignore_expires=False)

Spara cookies till en fil.

Denna basklass ger upphov till NotImplementedError. Subklasser kan lämna denna metod oimplementerad.

filename är namnet på den fil där cookies ska sparas. Om filename inte anges används self.filename (vars standard är det värde som skickas till konstruktören, om det finns något); om self.filename är None, uppstår ValueError.

ignore_discard: sparar även cookies som är inställda på att kastas. ignore_expires: spara även cookies som har löpt ut

Filen skrivs över om den redan finns, vilket innebär att alla cookies som den innehåller raderas. Sparade cookies kan återställas senare med hjälp av metoderna load() eller revert().

FileCookieJar.load(filename=None, ignore_discard=False, ignore_expires=False)

Ladda cookies från en fil.

Gamla cookies sparas om de inte skrivs över av nya cookies.

Argumenten är desamma som för save().

Den namngivna filen måste vara i det format som klassen förstår, annars kommer LoadError att visas. Även OSError kan visas, t.ex. om filen inte finns.

Ändrad i version 3.3: IOError användes tidigare, nu är det ett alias för OSError.

FileCookieJar.revert(filename=None, ignore_discard=False, ignore_expires=False)

Rensa alla cookies och ladda om cookies från en sparad fil.

revert() kan ge upphov till samma undantag som load(). Om det blir ett misslyckande kommer objektets tillstånd inte att ändras.

FileCookieJar-instanser har följande publika attribut:

FileCookieJar.filename

Filnamn för standardfilen där cookies ska sparas. Detta attribut kan tilldelas till.

FileCookieJar.delayload

Om true, ladda cookies från disken. Detta attribut bör inte tilldelas till. Det är bara en antydan, eftersom det bara påverkar prestanda, inte beteende (såvida inte kakorna på disken ändras). Ett CookieJar-objekt kan ignorera det. Ingen av klasserna FileCookieJar som ingår i standardbiblioteket laddar cookies på ett lättsinnigt sätt.

FileCookieJar-underklasser och samarbete med webbläsare

Följande CookieJar-subklasser finns för läsning och skrivning.

class http.cookiejar.MozillaCookieJar(filename=None, delayload=None, policy=None)

En FileCookieJar som kan ladda från och spara cookies till disk i Mozillas filformat cookies.txt (som också används av curl och webbläsarna Lynx och Netscape).

Anteckning

Detta gör att information om RFC 2965-cookies försvinner, och även om nyare eller icke-standardiserade cookie-attribut som port.

Varning

Säkerhetskopiera dina cookies innan du sparar om du har cookies vars förlust / korruption skulle vara obekvämt (det finns vissa subtiliteter som kan leda till små förändringar i filen under en laddning / spara tur och retur).

Observera också att cookies som sparas medan Mozilla körs kommer att bli överkörda av Mozilla.

class http.cookiejar.LWPCookieJar(filename=None, delayload=None, policy=None)

En FileCookieJar som kan ladda från och spara cookies till disk i ett format som är kompatibelt med libwww-perl-bibliotekets Set-Cookie3 filformat. Detta är praktiskt om du vill lagra cookies i en fil som är läsbar för människor.

Ändrad i version 3.8: Filnamnsparametern stöder en path-like object.

CookiePolicy-objekt

Objekt som implementerar gränssnittet CookiePolicy har följande metoder:

CookiePolicy.set_ok(cookie, request)

Returnerar ett booleskt värde som anger om cookien ska accepteras från servern.

cookie är en instans av Cookie. request är ett objekt som implementerar det gränssnitt som definieras av dokumentationen för CookieJar.extract_cookies().

CookiePolicy.return_ok(cookie, request)

Returnerar ett booleskt värde som anger om cookien ska returneras till servern.

cookie är en instans av Cookie. request är ett objekt som implementerar det gränssnitt som definieras av dokumentationen för CookieJar.add_cookie_header().

CookiePolicy.domain_return_ok(domain, request)

Returnerar False om cookies inte ska returneras, givet cookie-domän.

Den här metoden är en optimering. Den tar bort behovet av att kontrollera varje cookie med en viss domän (vilket kan innebära att många filer måste läsas). Att returnera true från domain_return_ok() och path_return_ok() lämnar allt arbete till return_ok().

Om domain_return_ok() returnerar true för cookiedomänen anropas path_return_ok() för cookie-sökvägen. Annars anropas aldrig path_return_ok() och return_ok() för den cookiedomänen. Om path_return_ok() returnerar true, anropas return_ok() med själva Cookie-objektet för en fullständig kontroll. Annars anropas aldrig return_ok() för den cookie-sökvägen.

Observera att domain_return_ok() anropas för varje cookie-domän, inte bara för request-domänen. Funktionen kan till exempel anropas med både ".example.com" och "www.example.com" om domänen för begäran är "www.example.com". Detsamma gäller för path_return_ok().

Argumentet request är som dokumenterat för return_ok().

CookiePolicy.path_return_ok(path, request)

Returnerar False om cookies inte ska returneras, givet cookie-sökväg.

Se dokumentationen för domain_return_ok().

Förutom att implementera metoderna ovan måste implementationer av CookiePolicy-gränssnittet också tillhandahålla följande attribut, som anger vilka protokoll som skall användas och hur. Alla dessa attribut kan tilldelas till.

CookiePolicy.netscape

Implementera Netscape-protokollet.

CookiePolicy.rfc2965

Implementera RFC 2965 protokoll.

CookiePolicy.hide_cookie2

Lägg inte till Cookie2 header till förfrågningar (närvaron av denna header indikerar för servern att vi förstår RFC 2965 cookies).

Det mest användbara sättet att definiera en CookiePolicy-klass är genom att subklassa från DefaultCookiePolicy och åsidosätta några eller alla metoder ovan. CookiePolicy i sig kan användas som en ”nollpolicy” för att tillåta inställning och mottagning av alla cookies (detta är troligen inte användbart).

DefaultCookiePolicy-objekt

Implementerar standardreglerna för att acceptera och returnera cookies.

Både RFC 2965 och Netscape cookies omfattas. RFC 2965-hantering är avstängd som standard.

Det enklaste sättet att skapa en egen policy är att överskriva denna klass och anropa dess metoder i dina överskrivna implementationer innan du lägger till dina egna ytterligare kontroller:

import http.cookiejar
class MyCookiePolicy(http.cookiejar.DefaultCookiePolicy):
    def set_ok(self, cookie, request):
        if not http.cookiejar.DefaultCookiePolicy.set_ok(self, cookie, request):
            return False
        if i_dont_want_to_store_this_cookie(cookie):
            return False
        return True

Förutom de funktioner som krävs för att implementera CookiePolicy-gränssnittet, kan du med den här klassen blockera och tillåta domäner från att sätta och ta emot cookies. Det finns också några strikthetsomkopplare som gör att du kan skärpa de ganska lösa Netscape-protokollreglerna lite grann (på bekostnad av att blockera vissa godartade cookies).

En blockeringslista och en tillåtelselista för domäner tillhandahålls (båda är avstängda som standard). Endast domäner som inte finns i blockeringslistan och som finns i tillåtelselistan (om tillåtelselistan är aktiv) deltar i inställning och returnering av cookies. Använd konstruktörsargumentet blocked_domains och metoderna blocked_domains() och set_blocked_domains() (och motsvarande argument och metoder för allowed_domains). Om du ställer in en tillåtelselista kan du stänga av den igen genom att ställa in den till None.

Domäner i block- eller tillåt-listor som inte börjar med en punkt måste vara lika med cookiedomänen för att matchas. Till exempel matchar "example.com" en post i blocklistan för "example.com", men "www.example.com" gör det inte. Domäner som börjar med en punkt matchas också av mer specifika domäner. Till exempel matchar både "www.example.com" och "www.coyote.example.com" ".example.com" (men "example.com" gör det inte). IP-adresser är ett undantag och måste matcha exakt. Om blocked_domains till exempel innehåller "192.168.1.2" och ".168.1.2" blockeras 192.168.1.2, men inte 193.168.1.2.

DefaultCookiePolicy implementerar följande ytterligare metoder:

DefaultCookiePolicy.blocked_domains()

Returnerar sekvensen av blockerade domäner (som en tupel).

DefaultCookiePolicy.set_blocked_domains(blocked_domains)

Ange ordningsföljden för blockerade domäner.

DefaultCookiePolicy.is_blocked(domain)

Returnerar True om domain finns på blocklistan för att ställa in eller ta emot cookies.

DefaultCookiePolicy.allowed_domains()

Returnerar None, eller sekvensen av tillåtna domäner (som en tupel).

DefaultCookiePolicy.set_allowed_domains(allowed_domains)

Ange sekvensen av tillåtna domäner, eller None.

DefaultCookiePolicy.is_not_allowed(domain)

Returnerar True om domän inte finns med på listan över tillåtna cookies för inställning eller mottagning.

DefaultCookiePolicy-instanser har följande attribut, som alla initialiseras från konstruktorargumenten med samma namn, och som alla kan tilldelas.

DefaultCookiePolicy.rfc2109_as_netscape

Om true, begär att CookieJar-instansen nedgraderar RFC 2109-cookies (dvs. cookies som tas emot i en Set-Cookie-header med ett version cookie-attribut på 1) till Netscape-cookies genom att sätta version-attributet för Cookie-instansen till 0. Standardvärdet är None, i vilket fall RFC 2109-cookies nedgraderas om och endast om RFC 2965-hanteringen är avstängd. Därför är RFC 2109-cookies nedgraderade som standard.

Allmänna strikthetsbrytare:

DefaultCookiePolicy.strict_domain

Tillåt inte webbplatser att ställa in tvåkomponentsdomäner med toppdomäner med landskod som .co.uk, .gov.uk, .co.nz.etc. Detta är långt ifrån perfekt och det är inte garanterat att det fungerar!

RFC 2965 växlar för strikthet i protokoll:

DefaultCookiePolicy.strict_rfc2965_unverifiable

Följ RFC 2965 regler för transaktioner som inte kan verifieras (vanligtvis är en transaktion som inte kan verifieras en transaktion som beror på en omdirigering eller en begäran om en bild som finns på en annan webbplats). Om detta är felaktigt blockeras cookies aldrig på grundval av verifierbarhet

Omkopplare för strikthet i Netscape-protokollet:

DefaultCookiePolicy.strict_ns_unverifiable

Tillämpa RFC 2965 regler om overifierbara transaktioner även på Netscape cookies.

DefaultCookiePolicy.strict_ns_domain

Flaggor som anger hur strikt man ska vara med reglerna för domänmatchning för Netscape-cookies. Se nedan för acceptabla värden.

DefaultCookiePolicy.strict_ns_set_initial_dollar

Ignorera cookies i Set-Cookie: rubriker som har namn som börjar med '$'.

DefaultCookiePolicy.strict_ns_set_path

Tillåt inte inställning av cookies vars sökväg inte matchar sökvägen för begäran URI.

strict_ns_domain är en samling flaggor. Dess värde konstrueras genom att sätta ihop eller (t.ex. DomainStrictNoDots|DomainStrictNonDomain betyder att båda flaggorna är inställda).

DefaultCookiePolicy.DomainStrictNoDots

När du ställer in cookies får ”värdprefixet” inte innehålla en punkt (t.ex. www.foo.bar.com kan inte ställa in en cookie för .bar.com, eftersom www.foo innehåller en punkt).

DefaultCookiePolicy.DomainStrictNonDomain

Cookies som inte uttryckligen angav ett cookie-attribut domän kan endast returneras till en domän som är lika med den domän som satte cookien (t.ex. kommer spam.example.com inte att returneras cookies från example.com som inte hade något cookie-attribut domän).

DefaultCookiePolicy.DomainRFC2965Match

Vid inställning av cookies krävs en fullständig RFC 2965 domänmatchning.

Följande attribut tillhandahålls för enkelhetens skull och är de mest användbara kombinationerna av ovanstående flaggor:

DefaultCookiePolicy.DomainLiberal

Motsvarar 0 (dvs. alla ovanstående flaggor för Netscape-domänens strikthet är avstängda).

DefaultCookiePolicy.DomainStrict

Motsvarar DomainStrictNoDots|DomainStrictNonDomain.

Exempel

Det första exemplet visar den vanligaste användningen av http.cookiejar:

import http.cookiejar, urllib.request
cj = http.cookiejar.CookieJar()
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")

Detta exempel visar hur du öppnar en URL med hjälp av dina Netscape-, Mozilla- eller Lynx-cookies (förutsätter Unix/Netscape-konvention för placering av cookie-filen):

import os, http.cookiejar, urllib.request
cj = http.cookiejar.MozillaCookieJar()
cj.load(os.path.join(os.path.expanduser("~"), ".netscape", "cookies.txt"))
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")

Nästa exempel illustrerar användningen av DefaultCookiePolicy. Aktivera RFC 2965-cookies, var mer strikt mot domäner när du ställer in och returnerar Netscape-cookies och blockera vissa domäner från att ställa in cookies eller få dem returnerade:

import urllib.request
from http.cookiejar import CookieJar, DefaultCookiePolicy
policy = DefaultCookiePolicy(
    rfc2965=True, strict_ns_domain=Policy.DomainStrict,
    blocked_domains=["ads.net", ".ads.net"])
cj = CookieJar(policy)
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")