Django Verktyg

Detta dokument täcker alla stabila moduler i django.utils. De flesta av modulerna i django.utils är utformade för internt bruk och endast följande delar kan betraktas som stabila och därmed bakåtkompatibla enligt internal release deprecation policy.

django.utils.cache

Denna modul innehåller hjälpfunktioner för att kontrollera HTTP-cachning. Detta görs genom att hantera Vary-headern i svaren. Den innehåller funktioner för att patcha svarsobjektens header direkt och dekoratorer som ändrar funktioner så att de själva gör header-patchningen.

För information om rubriken Vary, se RFC 9110#avsnitt-12.5.5.

I huvudsak definierar HTTP-headern Vary vilka headers en cache ska ta hänsyn till när den bygger sin cache-nyckel. Förfrågningar med samma sökväg men olika rubrikinnehåll för rubriker som namnges i Vary måste få olika cache-nycklar för att förhindra leverans av fel innehåll.

Exempelvis skulle internationization middleware behöva skilja cacher åt genom Accept-language-headern.

patch_cache_control(response, **kwargs)[source]

Denna funktion patchar Cache-Control-headern genom att lägga till alla nyckelordsargument till den. Omvandlingen är som följer:

• Alla parameternamn för nyckelord ändras till gemener och understrykningar konverteras till bindestreck.

• Om värdet på en parameter är True (exakt True, inte bara ett sant värde), läggs endast parameternamnet till i sidhuvudet.

• Alla andra parametrar läggs till med sitt värde, efter att ha applicerat str() på det.

get_max_age(response)[source]

Returnerar max-age från svarets Cache-Control-huvud som ett heltal (eller None om det inte hittades eller inte var ett heltal).

patch_response_headers(response, cache_timeout=None)[source]

Lägger till några användbara rubriker till det givna HttpResponse-objektet:

• Utgångsdatum

• Cache-Control

Varje rubrik läggs bara till om den inte redan är inställd.

cache_timeout anges i sekunder. Inställningen CACHE_MIDDLEWARE_SECONDS används som standard.

add_never_cache_headers(response)[source]

Lägger till en Expires-rubrik till aktuellt datum/tid.

Lägger till en Cache-Control: max-age=0, no-cache, no-store, must-revalidate, private header till ett svar för att ange att en sida aldrig ska cachas.

Varje rubrik läggs bara till om den inte redan är inställd.

patch_vary_headers(response, newheaders)[source]

Lägger till (eller uppdaterar) Vary-headern i det givna HttpResponse-objektet. newheaders är en lista med headernamn som bör finnas i Vary. Om headers innehåller en asterisk, då kommer Vary header att bestå av en enda asterisk '*', enligt RFC 9110 Section 12.5.5. Annars tas inte befintliga rubriker i Vary bort.

get_cache_key(request, key_prefix=None, method='GET', cache=None)[source]

Returnerar en cache-nyckel baserad på sökvägen för begäran. Den kan användas i begärandefasen eftersom den hämtar listan över rubriker att ta hänsyn till från det globala sökvägsregistret och använder dem för att bygga en cachekod att kontrollera mot.

Om det inte finns någon headerlist lagrad måste sidan byggas om, så denna funktion returnerar None.

learn_cache_key(request, response, cache_timeout=None, key_prefix=None, cache=None)[source]

Lär sig vilka rubriker som ska tas hänsyn till för en viss sökväg från svarsobjektet. Det lagrar dessa rubriker i ett globalt sökvägsregister så att senare åtkomst till sökvägen vet vilka rubriker som ska beaktas utan att bygga själva svarsobjektet. Rubrikerna namnges i Vary-rubriken i svaret, men vi vill förhindra att svaret genereras.

Listan över rubriker som ska användas för att generera cache-nyckeln lagras i samma cache som själva sidorna. Om cachen åldrar vissa data ur cachen innebär det att vi måste bygga svaret en gång för att komma åt Vary-rubriken och därmed listan över rubriker som ska användas för cachekoden.

django.utils.dateparse

De funktioner som definieras i denna modul har följande egenskaper:

• De accepterar strängar i ISO 8601 datum/tidsformat (eller några närliggande alternativ) och returnerar objekt från motsvarande klasser i Pythons datetime-modul.

• De ger upphov till ValueError om deras indata är väl formaterad men inte är ett giltigt datum eller en giltig tid.

• De returnerar None om det inte är väl formaterat alls.

• De accepterar upp till pikosekundupplösning i indata, men de trunkerar det till mikrosekunder, eftersom det är vad Python stöder.

parse_date(value)[source]

Parsar en sträng och returnerar en datetime.date.

parse_time(value)[source]

Analyserar en sträng och returnerar en datetime.time.

UTC-offsets stöds inte; om värde beskriver ett sådant är resultatet None.

parse_datetime(value)[source]

Analyserar en sträng och returnerar en datetime.datetime.

UTC-offset stöds; om värde beskriver en sådan, är resultatets tzinfo-attribut en datetime.timezone-instans.

parse_duration(value)[source]

Parsar en sträng och returnerar en datetime.timedelta.

Förväntar sig data i formatet "DD HH:MM:SS.uuuuuu", "DD HH:MM:SS,uuuuuu", eller som anges av ISO 8601 (t.ex. P4DT1H15M20S som motsvarar 4 1:15:20) eller PostgreSQLs dag-tidsintervallformat (t.ex. 3 dagar 04:05:06).

django.utils.dekoratorer

method_decorator(decorator, name='')[source]

Konverterar en funktionsdekorator till en metoddekorator. Den kan användas för att dekorera metoder eller klasser; i det senare fallet är name namnet på den metod som ska dekoreras och är obligatoriskt.

decorator kan också vara en lista eller en tupel av funktioner. De paketeras i omvänd ordning så att anropsordningen är den ordning i vilken funktionerna visas i listan/tupeln.

Se Dekorera klassbaserade vyer för exempel på användning.

decorator_from_middleware(middleware_class)[source]

Ger en middleware-klass och returnerar en vydekorator. Detta gör att du kan använda middleware-funktionalitet per vy. Mellanvaran skapas utan att några parametrar skickas med.

Det förutsätter mellanprogram som är kompatibla med den gamla stilen i Django 1.9 och tidigare (med metoder som process_request(), process_exception() och process_response()).

decorator_from_middleware_with_args(middleware_class)[source]

Som decorator_from_middleware, men returnerar en funktion som accepterar de argument som ska skickas till middleware_class. Till exempel: skapas cache_page()-dekoratorn från CacheMiddleware så här:

cache_page = decorator_from_middleware_with_args(CacheMiddleware)


@cache_page(3600)
def my_view(request):
    pass

sync_only_middleware(middleware)[source]

Markerar en mellanvara som synkron endast. (Standard i Django, men detta gör att du kan framtidssäkra om standard någonsin ändras i en framtida version)

async_only_middleware(middleware)[source]

Markerar ett mellanprogram som endast asynkront. Django kommer att linda in den i en asynkron händelseslinga när den anropas från WSGI-begärandesökvägen.

sync_and_async_middleware(middleware)[source]

Markerar en mellanvara som sync och async kompatibel, detta gör att man kan undvika att konvertera förfrågningar. Du måste implementera detektering av den aktuella förfrågningstypen för att använda denna dekorator. Se dokumentation för asynkrona mellanprogram för detaljer.

django.utils.encoding

smart_str(s, encoding='utf-8', strings_only=False, errors='strict')[source]

Returnerar ett str-objekt som representerar ett godtyckligt objekt s. Behandlar bytestrings med hjälp av codec encoding.

Om strings_only är True, konvertera inte (vissa) icke strängliknande objekt.

is_protected_type(obj)[source]

Avgör om objektinstansen är av en skyddad typ.

Objekt av skyddade typer bevaras som de är när de skickas till force_str(strings_only=True).

force_str(s, encoding='utf-8', strings_only=False, errors='strict')[source]

Liknar smart_str(), förutom att lata instanser löses upp till strängar i stället för att behållas som lata objekt.

Om strings_only är True, konvertera inte (vissa) icke strängliknande objekt.

smart_bytes(s, encoding='utf-8', strings_only=False, errors='strict')[source]

Returnerar en bytestringversion av godtyckligt objekt s, kodat enligt specifikationen i encoding.

Om strings_only är True, konvertera inte (vissa) icke strängliknande objekt.

force_bytes(s, encoding='utf-8', strings_only=False, errors='strict')[source]

Liknar smart_bytes, förutom att lata instanser löses upp till bytestrings, i stället för att behållas som lata objekt.

Om strings_only är True, konvertera inte (vissa) icke strängliknande objekt.

iri_to_uri(iri)[source]

Konvertera en IRI-del (Internationalized Resource Identifier) till en URI-del som är lämplig att inkludera i en URL.

Detta är algoritmen från avsnitt 3.1 i RFC 3987 Section 3.1, något förenklad eftersom indata antas vara en sträng snarare än en godtycklig byteström.

Tar emot en IRI (sträng eller UTF-8-byte) och returnerar en sträng som innehåller det kodade resultatet.

uri_to_iri(uri)[source]

Konverterar en enhetlig resursidentifierare till en internationaliserad resursidentifierare.

Detta är en algoritm från avsnitt 3.2 i RFC 3987 Section 3.2.

Tar emot en URI i ASCII-bytes och returnerar en sträng som innehåller det kodade resultatet.

filepath_to_uri(path)[source]

Konverterar en filsystemssökväg till en URI-del som är lämplig att inkludera i en URL. Sökvägen antas vara antingen UTF-8-byte, sträng eller en Path.

Den här metoden kodar vissa tecken som normalt skulle uppfattas som specialtecken för URI:er. Observera att den här metoden inte kodar tecknet ’, eftersom det är ett giltigt tecken inom URI:er. Se JavaScript-funktionen encodeURIComponent() för mer information.

Returnerar en ASCII-sträng som innehåller det kodade resultatet.

escape_uri_path(path)[source]

Escapar de osäkra tecknen från sökvägsdelen av en URI (Uniform Resource Identifier).

django.utils.feedgenerator

Exempel på användning:

>>> from django.utils import feedgenerator
>>> feed = feedgenerator.Rss201rev2Feed(
...     title="Poynter E-Media Tidbits",
...     link="https://www.poynter.org/tag/e-media-tidbits/",
...     description="A group blog by the sharpest minds in online media/journalism/publishing.",
...     language="en",
... )
>>> feed.add_item(
...     title="Hello",
...     link="https://www.holovaty.com/test/",
...     description="Testing.",
... )
>>> with open("test.rss", "w") as fp:
...     feed.write(fp, "utf-8")
...

För att förenkla valet av en generator används feedgenerator.DefaultFeed som för närvarande är Rss201rev2Feed

För definitioner av de olika versionerna av RSS, se: https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004/02/04/incompatible-rss

get_tag_uri(url, date)[source]

Skapar en TagURI.

Se https://web.archive.org/web/20110514113830/http://diveintomark.org/archives/2004/05/28/howto-atom-id

Stylesheet

New in Django 5.2.

class Stylesheet(url, mimetype='', media='screen')[source]

Representerar en RSS-formatmall.

url[source]

Obligatoriskt argument. Den URL där stilmallen finns.

mimetype[source]

En valfri sträng som innehåller stilmallens MIME-typ. Om den inte anges kommer Django att försöka gissa den genom att använda Pythons mimetypes.guess_type(). Använd mimetype=None om du inte vill att din stilmall ska ha en specificerad MIME-typ.

media

En valfri sträng som kommer att användas som media-attribut i stilmallen. Standard är "screen". Använd media=None om du inte vill att din stilmall ska ha ett media-attribut.

SyndicationFeed

class SyndicationFeed[source]

Basklass för alla syndikeringsflöden. Underklasser bör tillhandahålla write().

__init__(title, link, description, language=None, author_email=None, author_name=None, author_link=None, subtitle=None, categories=None, feed_url=None, feed_copyright=None, feed_guid=None, ttl=None, stylesheets=None, **kwargs)[source]

Initiera flödet med den angivna ordlistan med metadata, som gäller för hela flödet.

Eventuella extra nyckelordsargument som du skickar till __init__ kommer att lagras i self.feed.

Alla parametrar ska vara strängar, utom två:

• categories ska vara en sekvens av strängar.

• stylesheets bör vara en sekvens av antingen strängar eller Stylesheet-instanser.

Changed in Django 5.2:

Argumentet stylesheets har lagts till.

add_item(title, link, description, author_email=None, author_name=None, author_link=None, pubdate=None, comments=None, unique_id=None, categories=(), item_copyright=None, ttl=None, updateddate=None, enclosures=None, **kwargs)[source]

Lägger till ett objekt i flödet. Alla args förväntas vara strängar utom pubdate och updateddate, som är datetime.datetime-objekt, och enclosures, som är en lista över Enclosure-instanser.

num_items()[source]

root_attributes()[source]

Returnerar extra attribut att placera på rotelementet (dvs. feed/channel). Anropas från write().

add_root_elements(handler)[source]

Lägger till element i rotelementet (dvs. feed/channel). Anropas från write().

add_stylesheets(self, handler)[source]

New in Django 5.2.

Lägger till information om formatmallar i dokumentet. Anropas från write().

item_attributes(item)[source]

Returnerar extra attribut som ska placeras på varje element (t.ex. item/entry).

add_item_elements(handler, item)[source]

Lägg till element på varje element för objekt (t.ex. objekt/post).

write(outfile, encoding)[source]

Matar ut flödet i den angivna kodningen till outfile, som är ett filliknande objekt. Underklasser bör åsidosätta detta.

writeString(encoding)[source]

Returnerar matningen i den angivna kodningen som en sträng.

latest_post_date()[source]

Returnerar det senaste pubdate eller updateddate för alla artiklar i flödet. Om inga objekt har något av dessa attribut returneras aktuellt UTC-datum/tid.

Hölje

class Enclosure[source]

Representerar en RSS-kapsling

RssFeed

class RssFeed(SyndicationFeed)[source]

Rss201rev2Feed

class Rss201rev2Feed(RssFeed)[source]

Spec: https://cyber.harvard.edu/rss/rss.html

RssUserland091Feed

class RssUserland091Feed(RssFeed)[source]

Spec: http://backend.userland.com/rss091

Atom1Feed

class Atom1Feed(SyndicationFeed)[source]

Spec: RFC 4287

django.utils.functional

class cached_property(func)[source]

Dekoratorn @cached_property cachar resultatet av en metod med ett enda self-argument som en egenskap. Det cachade resultatet kommer att finnas kvar så länge som instansen gör det, så om instansen skickas runt och funktionen därefter anropas kommer det cachade resultatet att returneras.

Tänk på ett typiskt fall där en vy kan behöva anropa en modellmetod för att utföra en beräkning, innan modellinstansen placeras i kontexten, där mallen kan anropa metoden en gång till:

# the model
class Person(models.Model):
    def friends(self):
        # expensive computation
        ...
        return friends


# in the view:
if person.friends():
    ...

Och i mallen skulle du ha:

{% for friend in person.friends %}

Här kommer friends() att anropas två gånger. Eftersom instansen person i vyn och mallen är densamma kan man undvika detta genom att dekorera friends()-metoden med @cached_property:

from django.utils.functional import cached_property


class Person(models.Model):
    @cached_property
    def friends(self): ...

Observera att eftersom metoden nu är en egenskap, måste den i Python-koden nås på lämpligt sätt:

# in the view:
if person.friends:
    ...

Det cachade värdet kan behandlas som ett vanligt attribut för instansen:

# clear it, requiring re-computation next time it's called
person.__dict__.pop("friends", None)

# set a value manually, that will persist on the instance until cleared
person.friends = ["Huckleberry Finn", "Tom Sawyer"]

På grund av hur descriptor protocol fungerar, ger användning av del (eller delattr) på en cached_property som inte har blivit åtkommen upphov till AttributeError.

Förutom att erbjuda potentiella prestandafördelar kan @cached_property säkerställa att ett attributs värde inte ändras oväntat under en instants livstid. Detta kan inträffa med en metod vars beräkning baseras på datetime.now(), eller om en ändring sparas i databasen av någon annan process under det korta intervallet mellan efterföljande anrop av en metod på samma instans.

Du kan skapa cachade egenskaper för metoder. Om du till exempel har en dyr metod get_friends() och vill tillåta att den anropas utan att hämta det cachade värdet, kan du skriva:

friends = cached_property(get_friends)

Medan person.get_friends() räknar om vännerna vid varje anrop, kommer värdet på den cachade egenskapen att kvarstå tills du tar bort den enligt beskrivningen ovan:

x = person.friends  # calls first time
y = person.get_friends()  # calls again
z = person.friends  # does not call
x is z  # is True

class classproperty(method=None)[source]

I likhet med @classmethod konverterar dekoratorn @classproperty resultatet av en metod med ett enda cls-argument till en egenskap som kan nås direkt från klassen.

keep_lazy(func, *resultclasses)[source]

Django erbjuder många verktygsfunktioner (särskilt i django.utils) som tar en sträng som sitt första argument och gör något med den strängen. Dessa funktioner används av mallfilter såväl som direkt i annan kod.

Om du skriver dina egna liknande funktioner och hanterar översättningar kommer du att ställas inför problemet med vad du ska göra när det första argumentet är ett lazy translation-objekt. Du vill inte konvertera det till en sträng omedelbart, eftersom du kanske använder den här funktionen utanför en vy (och därmed kommer den aktuella trådens locale-inställning inte att vara korrekt).

För fall som detta kan du använda dekoratorn django.utils.functional.keep_lazy(). Den modifierar funktionen så att om den anropas med en lat översättning som ett av sina argument, fördröjs funktionsutvärderingen tills den behöver konverteras till en sträng.

Till exempel:

from django.utils.functional import keep_lazy, keep_lazy_text


def fancy_utility_function(s, *args, **kwargs):
    # Do some conversion on string 's'
    ...


fancy_utility_function = keep_lazy(str)(fancy_utility_function)


# Or more succinctly:
@keep_lazy(str)
def fancy_utility_function(s, *args, **kwargs): ...

Dekoratorn keep_lazy() tar ett antal extra argument (*args) som specificerar den eller de typer som den ursprungliga funktionen kan returnera. Ett vanligt användningsfall är att ha funktioner som returnerar text. För dessa kan du skicka typen str till keep_lazy (eller använda dekoratorn keep_lazy_text() som beskrivs i nästa avsnitt).

Med hjälp av den här dekoratorn kan du skriva din funktion och anta att indata är en korrekt sträng, och sedan lägga till stöd för lata översättningsobjekt i slutet.

keep_lazy_text(func)[source]

En genväg till keep_lazy(str)(func).

Om du har en funktion som returnerar text och du vill kunna ta lata argument medan du fördröjer utvärderingen av dem, kan du använda denna dekorator:

from django.utils.functional import keep_lazy, keep_lazy_text


# Our previous example was:
@keep_lazy(str)
def fancy_utility_function(s, *args, **kwargs): ...


# Which can be rewritten as:
@keep_lazy_text
def fancy_utility_function(s, *args, **kwargs): ...

django.utils.html

Vanligtvis bör du bygga upp HTML med hjälp av Djangos mallar för att använda dess autoescape-mekanism, med hjälp av verktygen i django.utils.safestring där det är lämpligt. Denna modul tillhandahåller några ytterligare verktyg på låg nivå för att escapa HTML.

escape(text)[source]

Returnerar den angivna texten med ampersand, citattecken och vinkelparenteser kodade för användning i HTML. Inmatningen är först tvingad till en sträng och utmatningen har mark_safe() tillämpad.

conditional_escape(text)[source]

Liknar escape(), förutom att den inte fungerar på strängar med preescaped, så den kommer inte att dubbel-eskape.

format_html(format_string, *args, **kwargs)[source]

Detta liknar str.format(), förutom att det är lämpligt för att bygga upp HTML-fragment. Det första argumentet format_string escapas inte men alla andra args och kwargs passerar genom conditional_escape() innan de skickas till str.format(). Slutligen har utdata mark_safe() tillämpats.

När det gäller att bygga upp små HTML-fragment är den här funktionen att föredra framför stränginterpolering med hjälp av % eller str.format() direkt, eftersom den tillämpar escaping på alla argument - precis som mallsystemet tillämpar escaping som standard.

Så istället för att skriva:

mark_safe(
    "%s <b>%s</b> %s"
    % (
        some_html,
        escape(some_text),
        escape(some_other_text),
    )
)

Du bör istället använda:

format_html(
    "{} <b>{}</b> {}",
    mark_safe(some_html),
    some_text,
    some_other_text,
)

Detta har fördelen att du inte behöver tillämpa escape() på varje argument och riskera en bugg och en XSS-sårbarhet om du glömmer bort ett.

Observera att även om denna funktion använder str.format() för att göra interpoleringen, kommer några av formateringsalternativen som tillhandahålls av str.format() (t.ex. nummerformatering) inte att fungera, eftersom alla argument skickas genom conditional_escape() som (i slutändan) anropar force_str() på värdena.

Deprecated since version 5.0: Stöd för att anropa format_html() utan att skicka args eller kwargs är föråldrat.

format_html_join(sep, format_string, args_generator)[source]

En omslutning av format_html(), för det vanliga fallet med en grupp argument som behöver formateras med samma formatsträng och sedan sammanfogas med sep. sep skickas också genom conditional_escape().

args_generator bör vara en iterator som ger argument att skicka till format_html(), antingen sekvenser av positionella argument eller mappningar av nyckelordsargument.

Tupler kan till exempel användas för positionella argument:

format_html_join(
    "\n",
    "<li>{} {}</li>",
    ((u.first_name, u.last_name) for u in users),
)

Eller så kan ordböcker användas för nyckelordsargument:

format_html_join(
    "\n",
    '<li data-id="{id}">{id} {title}</li>',
    ({"id": b.id, "title": b.title} for b in books),
)

Changed in Django 5.2:

Stöd för mappningar i args_generator har lagts till.

json_script(value, element_id=None, encoder=None)[source]

Escapar alla HTML/XML-specialtecken med deras Unicode-escape, så att värdet är säkert för användning med JavaScript. Omsluter också den undangömda JSON i en <script> tagg. Om parametern element_id inte är None får taggen <script> det angivna id:t. Till exempel:

>>> json_script({"hello": "world"}, element_id="hello-data")
'<script id="hello-data" type="application/json">{"hello": "world"}</script>'

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.

strip_tags(value)[source]

Försöker ta bort allt som ser ut som en HTML-tagg från strängen, det vill säga allt som finns inom <>.

Absolut INGEN garanti ges för att den resulterande strängen är HTML-säker. Så markera ALDRIG resultatet av ett strip_tags-anrop som säkert utan att först escapa det, till exempel med escape().

Till exempel:

strip_tags(value)

Om value är <b>"Joel</b> <button>is</button> a <span>slug</span>" kommer returvärdet att vara "Joel is a slug".

Om du letar efter en mer robust lösning kan du överväga att använda ett HTML-rensningsverktyg från tredje part.

html_safe()[source]

Metoden __html__() på en klass hjälper icke-Django-mallar att upptäcka klasser vars utdata inte kräver HTML-escaping.

Denna dekorator definierar metoden __html__() på den dekorerade klassen genom att omsluta __str__() i mark_safe(). Säkerställ att metoden __str__() verkligen returnerar text som inte kräver HTML-escape.

django.utils.http

urlencode(query, doseq=False)[source]

En version av Pythons urllib.parse.urlencode()-funktion som kan arbeta med MultiValueDict och värden som inte är strängar.

http_date(epoch_seconds=None)[source]

Formaterar tiden så att den matchar datumformatet RFC 1123 Section 5.2.14 som anges av HTTP RFC 9110 Section 5.6.7.

Accepterar ett flyttal uttryckt i sekunder sedan epoken i UTC - såsom det som matas ut av time.time(). Om inställningen är None, är standardvärdet den aktuella tiden.

Utmatning av en sträng i formatet Wdy, DD Mon YYYY HH:MM:SS GMT.

content_disposition_header(as_attachment, filename)[source]

Konstruerar ett HTTP-huvudvärde för Content-Disposition från det givna filnamnet enligt specifikationen i RFC 6266. Returnerar None om as_attachment är False och filnamn är None, annars returneras en sträng som passar för HTTP-huvudet Content-Disposition.

base36_to_int(s)[source]

Konverterar en bas 36-sträng till ett heltal.

int_to_base36(i)[source]

Konverterar ett positivt heltal till en bas 36-sträng.

urlsafe_base64_encode(s)[source]

Kodar en bytestring till en base64-sträng för användning i URL:er och tar bort eventuella efterföljande likhetstecken.

urlsafe_base64_decode(s)[source]

Avkodar en base64-kodad sträng och lägger tillbaka eventuella efterföljande likhetstecken som kan ha tagits bort.

django.utils.module_loading

Funktioner för att arbeta med Python-moduler.

import_string(dotted_path)[source]

Importerar en prickad modulväg och returnerar det attribut/den klass som anges med det sista namnet i sökvägen. Anger ImportError om importen misslyckades. Till exempel:

from django.utils.module_loading import import_string

ValidationError = import_string("django.core.exceptions.ValidationError")

är likvärdig med:

from django.core.exceptions import ValidationError

django.utils.safestring

Funktioner och klasser för att arbeta med ”säkra strängar”: strängar som kan visas säkert utan ytterligare escaping i HTML. Att markera något som en ”säker sträng” innebär att producenten av strängen redan har förvandlat tecken som inte bör tolkas av HTML-motorn (t.ex. ’<’) till lämpliga enheter.

class SafeString[source]

En str-underklass som särskilt har markerats som ”säker” (kräver ingen ytterligare escaping) för HTML-utdata.

mark_safe(s)[source]

Markera uttryckligen en sträng som säker för (HTML-)utdata. Det returnerade objektet kan användas överallt där en sträng är lämplig.

Kan anropas flera gånger på en och samma sträng.

Kan också användas som dekorationsmaterial.

För att bygga upp fragment av HTML bör du normalt använda django.utils.html.format_html() istället.

En sträng som är markerad som säker blir osäker igen om den ändras. Till exempel:

>>> mystr = "<b>Hello World</b>   "
>>> mystr = mark_safe(mystr)
>>> type(mystr)
<class 'django.utils.safestring.SafeString'>

>>> mystr = mystr.strip()  # removing whitespace
>>> type(mystr)
<type 'str'>

django.utils.text

format_lazy(format_string, *args, **kwargs)

En version av str.format() för när format_string, args och/eller kwargs innehåller lata objekt. Det första argumentet är den sträng som ska formateras. Till exempel:

from django.utils.text import format_lazy
from django.utils.translation import pgettext_lazy

urlpatterns = [
    path(
        format_lazy("{person}/<int:pk>/", person=pgettext_lazy("URL", "person")),
        PersonDetailView.as_view(),
    ),
]

Detta exempel tillåter översättare att översätta en del av URL:en. Om ”person” översätts till ”persona” kommer det reguljära uttrycket att matcha persona/(?P<pk>\d+)/$, t.ex. persona/5/.

slugify(value, allow_unicode=False)[source]

Konverterar en sträng till en URL-slog genom:

1. Konverterar till ASCII om allow_unicode är False (standard).

2. Konvertering till gemener.

3. Ta bort tecken som inte är alfanumeriska, understreck, bindestreck eller blanksteg.

4. Ersätter alla blanksteg eller upprepade streck med enkla streck.

5. Ta bort inledande och avslutande blanksteg, bindestreck och understrykningstecken.

Till exempel:

>>> slugify(" Joel is a slug ")
'joel-is-a-slug'

Om du vill tillåta Unicode-tecken ska du ange allow_unicode=True. Ett exempel:

>>> slugify("你好 World", allow_unicode=True)
'你好-world'

django.utils.timezone

get_fixed_timezone(offset)[source]

Returnerar en tzinfo-instans som representerar en tidszon med en fast förskjutning från UTC.

offset är en datetime.timedelta eller ett heltal i minuter. Använd positiva värden för tidszoner öster om UTC och negativa värden för väster om UTC.

get_default_timezone()[source]

Returnerar en tzinfo-instans som representerar standardtidszonen.

get_default_timezone_name()[source]

Returnerar namnet på standardtidszon.

get_current_timezone()[source]

Returnerar en tzinfo-instans som representerar aktuell tidszon.

get_current_timezone_name()[source]

Returnerar namnet på aktuell tidszon.

activate(timezone)[source]

Ställer in aktuell tidszon. Argumentet timezone måste vara en instans av en tzinfo-underklass eller ett namn på en tidszon.

deactivate()[source]

Återställer aktuell tidszon.

override(timezone)[source]

Detta är en Python-kontexthanterare som ställer in aktuell tidszon vid inmatning med activate(), och återställer den tidigare aktiva tidszonen vid utmatning. Om argumentet timezone är None, kommer current time zone att avaktiveras vid inmatning med deactivate() istället.

override kan också användas som en funktionsdekorator.

localtime(value=None, timezone=None)[source]

Konverterar en medveten datetime till en annan tidszon, som standard aktuell tidszon.

När value utelämnas, är standardvärdet now().

Den här funktionen fungerar inte på naiva datatider; använd make_aware() istället.

localdate(value=None, timezone=None)[source]

Använder localtime() för att konvertera en medveten datetime till en date() i en annan tidszon, som standard aktuell tidszon.

När value utelämnas, är standardvärdet now().

Denna funktion fungerar inte på naiva datatider.

now()[source]

Returnerar en datetime som representerar den aktuella tidpunkten. Exakt vad som returneras beror på värdet av USE_TZ:

• Om USE_TZ är False, kommer detta att vara en naive datatid (dvs. en datatid utan en associerad tidszon) som representerar den aktuella tiden i systemets lokala tidszon.

• Om USE_TZ är True, kommer detta att vara en aware datatid som representerar den aktuella tiden i UTC. Observera att now() alltid kommer att returnera tider i UTC oavsett värdet på TIME_ZONE; du kan använda localtime() för att få tiden i den aktuella tidszonen.

is_aware(value)[source]

Returnerar True om value är medveten, False om den är naiv. Denna funktion förutsätter att value är en datetime.

is_naive(value)[source]

Returnerar True om value är naivt, False om det är medvetet. Denna funktion förutsätter att value är en datetime.

make_aware(value, timezone=None)[source]

Returnerar en medveten datetime som representerar samma tidpunkt som value i timezone, value är en naiv datetime. Om timezone är satt till None, är standardvärdet aktuell tidszon.

make_naive(value, timezone=None)[source]

Returnerar en naiv datetime som representerar i timezone samma tidpunkt som value, value är en medveten datetime. Om timezone är satt till None, är standardvärdet aktuell tidszon.

django.utils.översättning

För en fullständig diskussion om användningen av följande, se Översättningsdokumentation.

gettext(message)[source]

Översätter message och returnerar det som en sträng.

pgettext(context, message)[source]

Översätter message givet context och returnerar det som en sträng.

För mer information, se Kontextuella markörer.

gettext_lazy(message)

pgettext_lazy(context, message)

Samma sak som de icke-lata versionerna ovan, men med lat utförande.

Se dokumentation för lättsamma översättningar.

gettext_noop(message)[source]

Markerar strängar för översättning men översätter dem inte nu. Detta kan användas för att lagra strängar i globala variabler som bör förbli på basspråket (eftersom de kan användas externt) och som kommer att översättas senare.

ngettext(singular, plural, number)[source]

Översätter ingular och plural och returnerar lämplig sträng baserat på number.

npgettext(context, singular, plural, number)[source]

Översätter ingular och plural och returnerar lämplig sträng baserat på number och context.

ngettext_lazy(singular, plural, number)[source]

npgettext_lazy(context, singular, plural, number)[source]

Samma sak som de icke-lata versionerna ovan, men med lat utförande.

Se dokumentation för lättsamma översättningar.

activate(language)[source]

Hämtar översättningsobjektet för ett visst språk och aktiverar det som det aktuella översättningsobjektet för den aktuella tråden.

deactivate()[source]

Avaktiverar det aktiva översättningsobjektet så att ytterligare _-anrop kommer att lösas mot standardöversättningsobjektet igen.

deactivate_all()[source]

Gör det aktiva översättningsobjektet till en NullTranslations()-instans. Detta är användbart när vi av någon anledning vill att försenade översättningar ska visas som originalsträngen.

override(language, deactivate=False)[source]

En Python-kontexthanterare som använder django.utils.translation.activate() för att hämta översättningsobjektet för ett visst språk, aktiverar det som översättningsobjekt för den aktuella tråden och återaktiverar det tidigare aktiva språket vid avslut. Eventuellt kan den avaktivera den tillfälliga översättningen vid avslut med django.utils.translation.deactivate() om argumentet deactivate är True. Om du skickar None som språkargument aktiveras en NullTranslations()-instans inom kontexten.

override kan också användas som en funktionsdekorator.

check_for_language(lang_code)[source]

Kontrollerar om det finns en global språkfil för den angivna språkkoden (t.ex. ’fr’, ’pt_BR’). Detta används för att avgöra om ett användartillhandahållet språk är tillgängligt.

get_language()[source]

Returnerar den för närvarande valda språkkoden. Returnerar None om översättningar är tillfälligt avaktiverade (genom deactivate_all() eller när None skickas till override()).

get_language_bidi()[source]

Returnerar det valda språkets BiDi-layout:

• False = layout från vänster till höger

• True = höger till vänster-layout

get_language_from_request(request, check_path=False)[source]

Analyserar begäran för att ta reda på vilket språk användaren vill att systemet ska visa. Endast språk som listas i settings.LANGUAGES beaktas. Om användaren begär ett underspråk där vi har ett huvudspråk, skickar vi ut huvudspråket.

Om check_path är True kontrollerar funktionen först om sökvägen till den begärda URL:en börjar med en språkkod som anges i inställningen LANGUAGES.

get_supported_language_variant(lang_code, strict=False)[source]

Returnerar lang_code om den finns i inställningen LANGUAGES, och väljer eventuellt en mer generisk variant. Till exempel: returneras 'es' om lang_code är 'es-ar' och 'es' finns i LANGUAGES men 'es-ar' inte gör det.

lang_code har en maximal accepterad längd på 500 tecken. Ett LookupError uppstår om lang_code överskrider denna gräns och strict är True, eller om det inte finns någon generisk variant och strict är False.

Om strict är False (standard), kan en landsspecifik variant returneras när varken språkkoden eller dess generiska variant hittas. Om till exempel endast 'es-co' finns i LANGUAGES, returneras det för lang_code som es' och 'es-ar'. Dessa matchningar returneras inte om strict=True.

Utlöser LookupError om inget hittas.

Changed in Django 4.2.15:

I äldre versioner bearbetades lang_code-värden med mer än 500 tecken utan att ge upphov till ett LookupError.

to_locale(language)[source]

Omvandlar ett språknamn (en-us) till ett lokalt namn (en_US).

templatize(src)[source]

Förvandlar en Django-mall till något som förstås av xgettext. Det gör det genom att översätta Django-översättningstaggarna till standard gettext-funktionsinbjudningar.