Django stöder Unicode-data överallt.
\nI det här dokumentet beskrivs vad du behöver veta om du skriver program som använder data eller mallar som är kodade i något annat än ASCII.
\nSe till att din databas är konfigurerad för att kunna lagra godtyckliga strängdata. Normalt innebär detta att du ger den en kodning av UTF-8 eller UTF-16. Om du använder en mer restriktiv kodning, t.ex. latin1 (iso8859-1), kan du inte lagra vissa tecken i databasen och information går förlorad.
\nMySQL-användare, se MySQL manual för detaljer om hur du ställer in eller ändrar databasens teckenuppsättningskodning.
PostgreSQL-användare, se PostgreSQL-manualen för information om hur du skapar databaser med rätt kodning.
Oracle-användare, se Oracle manual för detaljer om hur man ställer in (section 2) eller ändrar (section 11) databasens teckenuppsättningskodning.
SQLite-användare, det finns inget du behöver göra. SQLite använder alltid UTF-8 för intern kodning.
Alla Djangos databasbackends konverterar automatiskt strängar till lämplig kodning för att prata med databasen. De konverterar också automatiskt strängar som hämtas från databasen till strängar. Du behöver inte ens tala om för Django vilken kodning din databas använder: det hanteras transparent.
\nMer information finns i avsnittet ”Databas-API:et” nedan.
\nNär du använder strängar med Django - t.ex. i databasuppslagningar, mallrendering eller någon annanstans - har du två val för att koda dessa strängar. Du kan använda vanliga strängar eller bytestrings (som börjar med ett ’b’).
\n\nOm din kod bara använder ASCII-data är det säkert att använda dina vanliga strängar och skicka runt dem som du vill, eftersom ASCII är en delmängd av UTF-8.
\nLåt dig inte luras att tro att om inställningen DEFAULT_CHARSET är satt till något annat än 'utf-8' så kan du använda den andra kodningen i dina bytestrings! DEFAULT_CHARSET gäller endast för de strängar som genereras som resultat av mallrendering (och e-post). Django kommer alltid att anta UTF-8-kodning för interna bytestrings. Anledningen till detta är att DEFAULT_CHARSET-inställningen faktiskt inte är under din kontroll (om du är applikationsutvecklare). Den kontrolleras av den person som installerar och använder din applikation - och om den personen väljer en annan inställning måste din kod fortfarande fungera. Den kan alltså inte förlita sig på den inställningen.
I de flesta fall när Django hanterar strängar kommer den att konvertera dem till strängar innan den gör något annat. Så, som en allmän regel, om du skickar in en bytestring, var beredd på att få en sträng tillbaka i resultatet.
\nBortsett från strängar och bytestrings finns det en tredje typ av strängliknande objekt som du kan stöta på när du använder Django. Ramverkets internationaliseringsfunktioner introducerar konceptet ”lazy translation” - en sträng som har markerats som översatt men vars faktiska översättningsresultat inte bestäms förrän objektet används i en sträng. Denna funktion är användbar i fall där översättningslokalen är okänd tills strängen används, även om strängen ursprungligen kan ha skapats när koden först importerades.
\nNormalt sett behöver du inte oroa dig för lata översättningar. Var bara medveten om att om du undersöker ett objekt och det påstår sig vara ett django.utils.functional.__proxy__-objekt, är det en lat översättning. Om du anropar str() med den lata översättningen som argument kommer en sträng att genereras i den aktuella språkdräkten.
Mer information om lata översättningsobjekt finns i dokumentationen internationalisering.
\nEftersom vissa strängoperationer dyker upp om och om igen levereras Django med några användbara funktioner som bör göra det lite enklare att arbeta med sträng- och bytestringobjekt.
\nModulen django.utils.encoding innehåller några funktioner som är praktiska för att konvertera fram och tillbaka mellan strängar och bytestrings.
smart_str(s, encoding='utf-8', strings_only=False, errors='strict') konverterar indata till en sträng. Parametern encoding anger kodningen för indata. (Django använder till exempel detta internt vid bearbetning av formulärinmatningsdata, som kanske inte är UTF-8-kodade) Parametern strings_only, om den sätts till True, kommer att resultera i att Python-tal, booleaner och None inte konverteras till en sträng (de behåller sina ursprungliga typer). Parametern errors tar något av de värden som accepteras av Pythons funktion str() för dess felhantering.
force_str(s, encoding='utf-8', strings_only=False, errors='strict') är identisk med smart_str() i nästan alla fall. Skillnaden är när det första argumentet är en lazy translation-instans. Medan smart_str() bevarar lata översättningar, tvingar force_str() dessa objekt till en sträng (vilket gör att översättningen sker). Normalt sett vill du använda smart_str(). Men force_str() är användbart i malltaggar och filter som absolut måste ha en sträng att arbeta med, inte bara något som kan konverteras till en sträng.
smart_bytes(s, encoding='utf-8', strings_only=False, errors='strict') är i princip motsatsen till smart_str(). Den tvingar det första argumentet till en bytestring. Parametern strings_only har samma beteende som för smart_str() och force_str(). Detta är något annorlunda semantik från Pythons inbyggda str()-funktion, men skillnaden behövs på några ställen inom Djangos internals.
Normalt sett behöver du bara använda force_str(). Anropa den så tidigt som möjligt på alla indata som kan vara antingen en sträng eller en bytestring, och från och med då kan du behandla resultatet som att det alltid är en sträng.
Webbramverk måste hantera URL:er (som är en typ av IRI). Ett krav på URL:er är att de kodas med enbart ASCII-tecken. I en internationell miljö kan du dock behöva konstruera en URL från en IRI – mycket löst uttryckt, en URI som kan innehålla Unicode-tecken. Använd dessa funktioner för att citera och konvertera en IRI till en URI:
\nThe django.utils.encoding.iri_to_uri() function, which implements the\nconversion from IRI to URI as required by RFC 3987 Section 3.1.
Funktionerna urllib.parse.quote() och urllib.parse.quote_plus() från Pythons standardbibliotek.
Dessa två grupper av funktioner har lite olika syften, och det är viktigt att hålla isär dem. Normalt sett använder du quote() på de enskilda delarna av IRI:n eller URI-sökvägen så att alla reserverade tecken som ’&’ eller ’%’ kodas korrekt. Sedan använder du iri_to_uri() på hela IRI:n och konverterar alla icke-ASCII-tecken till rätt kodade värden.
Funktionen iri_to_uri() ändrar inte ASCII-tecken som annars är tillåtna i en URL. Så till exempel kodas inte tecknet ’%’ ytterligare när det skickas till iri_to_uri(). Detta innebär att du kan skicka en fullständig URL till den här funktionen och den kommer inte att röra till frågesträngen eller något liknande.
Ett exempel skulle kunna förtydliga saken:
\n>>> from urllib.parse import quote\n>>> from django.utils.encoding import iri_to_uri\n>>> quote("Paris & Orléans")\n'Paris%20%26%20Orl%C3%A9ans'\n>>> iri_to_uri("/favorites/François/%s" % quote("Paris & Orléans"))\n'/favorites/Fran%C3%A7ois/Paris%20%26%20Orl%C3%A9ans'\nOm du tittar noga kan du se att den del som genererades av quote() i det andra exemplet inte var dubbelciterad när den skickades till iri_to_uri(). Detta är en mycket viktig och användbar funktion. Det innebär att du kan konstruera din IRI utan att oroa dig för om den innehåller icke-ASCII-tecken och sedan, precis i slutet, anropa iri_to_uri() på resultatet.
Similarly, Django provides django.utils.encoding.uri_to_iri() which\nimplements the conversion from URI to IRI as per RFC 3987 Section 3.2.
Ett exempel för att visa:
\n>>> from django.utils.encoding import uri_to_iri\n>>> uri_to_iri("/%E2%99%A5%E2%99%A5/?utf8=%E2%9C%93")\n'/♥♥/?utf8=✓'\n>>> uri_to_iri("%A9hello%3Fworld")\n'%A9hello%3Fworld'\nI det första exemplet är UTF-8-tecken inte citerade. I det andra förblir procentkodningarna oförändrade eftersom de ligger utanför det giltiga UTF-8-intervallet eller representerar ett reserverat tecken.
\nBåde funktionerna iri_to_uri() och uri_to_iri() är idempotenta, vilket innebär att följande alltid är sant:
iri_to_uri(iri_to_uri(some_string)) == iri_to_uri(some_string)\nuri_to_iri(uri_to_iri(some_string)) == uri_to_iri(some_string)\nSå du kan säkert anropa den flera gånger på samma URI/IRI utan att riskera problem med dubbelkvotering.
\nEftersom alla strängar returneras från databasen som str-objekt, kommer modellfält som är teckenbaserade (CharField, TextField, URLField, etc.) att innehålla Unicode-värden när Django hämtar data från databasen. Detta är alltid fallet, även om data skulle kunna passa in i en ASCII-bytestring.
Du kan skicka in bytestrings när du skapar en modell eller fyller i ett fält, och Django konverterar det till strängar när det behövs.
\nget_absolute_url()Link to this heading#Webbadresser kan bara innehålla ASCII-tecken. Om du konstruerar en URL från bitar av data som kan vara icke-ASCII, var noga med att koda resultaten på ett sätt som är lämpligt för en URL. Funktionen reverse() hanterar detta åt dig automatiskt.
Om du konstruerar en URL manuellt (dvs. inte använder funktionen reverse()), måste du själv ta hand om kodningen. I det här fallet använder du funktionerna iri_to_uri() och quote() som dokumenterades ovan. Till exempel:
from urllib.parse import quote\nfrom django.utils.encoding import iri_to_uri\n\n\ndef get_absolute_url(self):\n url = "/person/%s/?x=0&y=0" % quote(self.location)\n return iri_to_uri(url)\nDenna funktion returnerar en korrekt kodad URL även om self.location är något i stil med ”Jack besökte Paris & Orléans”. (I själva verket är anropet iri_to_uri() inte nödvändigt i exemplet ovan, eftersom alla icke-ASCII-tecken skulle ha tagits bort vid citering i den första raden)
Använd strängar när du skapar mallar manuellt:
\nfrom django.template import Template\n\nt2 = Template("This is a string template.")\nBut the common case is to read templates from the filesystem. If your template\nfiles are not stored with a UTF-8 encoding, adjust the TEMPLATES\nsetting. The built-in django backend\nprovides the 'file_charset' option to change the encoding used to read\nfiles from disk.
Inställningen DEFAULT_CHARSET styr kodningen av renderade mallar. Den är inställd på UTF-8 som standard.
Om du tänker tillåta användare att ladda upp filer måste du se till att miljön som används för att köra Django är konfigurerad för att fungera med icke-ASCII-filnamn. Om din miljö inte är korrekt konfigurerad kommer du att stöta på UnicodeEncodeError-undantag när du sparar filer med filnamn eller innehåll som innehåller icke-ASCII-tecken.
Filsystemets stöd för UTF-8-filnamn varierar och kan bero på miljön. Kontrollera din aktuella konfiguration i ett interaktivt Python-skal genom att köra:
\nimport sys\n\nsys.getfilesystemencoding()\nUtmatningen bör vara ”UTF-8”.
\nMiljövariabeln LANG är ansvarig för att ställa in den förväntade kodningen på Unix-plattformar. I dokumentationen för ditt operativsystem och din applikationsserver finns information om lämplig syntax och plats för att ange den här variabeln. Se Så här använder du Django med Apache och mod_wsgi för exempel.
I din utvecklingsmiljö kan du behöva lägga till en inställning i din ~.bashrc som motsvarar:
export LANG="en_US.UTF-8"\nInlämning av HTML-formulär är ett knepigt område. Det finns ingen garanti för att inlämningen kommer att innehålla kodningsinformation, vilket innebär att ramverket kan behöva gissa sig till kodningen av inlämnade data.
\nDjango använder ett ”lata” tillvägagångssätt för att avkoda formulärdata. Data i ett HttpRequest-objekt avkodas endast när du kommer åt det. Faktum är att de flesta data inte avkodas alls. Endast datastrukturerna HttpRequest.GET och HttpRequest.POST har någon avkodning tillämpad på dem. Dessa två fält kommer att returnera sina medlemmar som Unicode-data. Alla andra attribut och metoder i HttpRequest returnerar data exakt som de skickades av klienten.
Som standard används inställningen DEFAULT_CHARSET som den förmodade kodningen för formulärdata. Om du behöver ändra detta för ett visst formulär kan du ställa in attributet encoding på en HttpRequest-instans. Till exempel:
def some_view(request):\n # We know that the data must be encoded as KOI8-R (for some reason).\n request.encoding = "koi8-r"\n ...\nDu kan till och med ändra kodningen efter att ha använt request.GET eller request.POST, och alla efterföljande åtkomster kommer att använda den nya kodningen.
De flesta utvecklare behöver inte bekymra sig om att ändra formulärkodning, men det här är en användbar funktion för applikationer som pratar med äldre system vars kodning du inte kan kontrollera.
\nDjango avkodar inte data från filuppladdningar, eftersom dessa data normalt behandlas som samlingar av bytes, snarare än strängar. Varje automatisk avkodning där skulle ändra betydelsen av strömmen av bytes.
\n