Referens till modellfält

Det här dokumentet innehåller alla API-referenser för Field inklusive de field options och field types som Django erbjuder.

Se även

Om de inbyggda fälten inte räcker till kan du prova django-localflavor (dokumentation), som innehåller olika kodstycken som är användbara för vissa länder och kulturer.

Du kan också enkelt skriva dina egna anpassade modellfält.

Observera

Fält definieras i django.db.models.fields, men för enkelhetens skull importeras de till django.db.models. Standardkonventionen är att använda from django.db import models och referera till fält som models.<Foo>Field.

Alternativ för fält

Följande argument är tillgängliga för alla fälttyper. Alla är valfria.

null

Field.null

Om True, kommer Django att lagra tomma värden som NULL i databasen. Standard är False.

Undvik att använda null på strängbaserade fält som CharField och TextField. Django-konventionen är att använda en tom sträng, inte NULL, som ”inga data”-tillstånd för strängbaserade fält. Om ett strängbaserat fält har null=False kan tomma strängar fortfarande sparas för ”inga data”. Om ett strängbaserat fält har null=True, betyder det att det har två möjliga värden för ”no data”: NULL och den tomma strängen. I de flesta fall är det överflödigt att ha två möjliga värden för ”no data”. Ett undantag är när en CharField har både unique=True och blank=True inställda. I den här situationen krävs null=True för att undvika brott mot unika begränsningar när flera objekt med tomma värden sparas.

För både strängbaserade och icke-strängbaserade fält måste du också ange blank=True om du vill tillåta tomma värden i formulär, eftersom parametern null endast påverkar databaslagring (se blank).

Observera

Vid användning av Oracle databas backend kommer värdet NULL att lagras för att beteckna den tomma strängen oavsett detta attribut.

blank

Field.blank

Om True, får fältet vara tomt. Standard är False.

Observera att detta skiljer sig från null. null är rent databasrelaterat, medan blank är valideringsrelaterat. Om ett fält har blank=True, tillåter formulärvalidering att ett tomt värde anges. Om ett fält har blank=False kommer fältet att vara obligatoriskt.

Tillhandahållande av saknade värden

blank=True kan användas med fält som har null=False, men detta kommer att kräva implementering av clean() på modellen för att programmatiskt tillhandahålla eventuella saknade värden.

val

Field.choices[source]

En mappning eller iterabel i det format som beskrivs nedan för att användas som val för detta fält. Om val anges, verkställs de av modellvalidering och standardformulärwidgeten kommer att vara en valbox med dessa val istället för standardtextfältet.

Om en mappning anges är nyckelelementet det faktiska värde som ska anges i modellen och det andra elementet är det lättlästa namnet. Till exempel:

YEAR_IN_SCHOOL_CHOICES = {
    "FR": "Freshman",
    "SO": "Sophomore",
    "JR": "Junior",
    "SR": "Senior",
    "GR": "Graduate",
}

Du kan också skicka en sequence som i sig består av iterabler med exakt två element (t.ex. [(A1, B1), (A2, B2), ...]). Det första elementet i varje tupel är det faktiska värde som ska anges i modellen, och det andra elementet är det mänskligt läsbara namnet. Till exempel:

YEAR_IN_SCHOOL_CHOICES = [
    ("FR", "Freshman"),
    ("SO", "Sophomore"),
    ("JR", "Junior"),
    ("SR", "Senior"),
    ("GR", "Graduate"),
]

choices kan också definieras som en callable som inte förväntar sig några argument och som returnerar något av de format som beskrivs ovan. Till exempel:

def get_currencies():
    return {i: i for i in settings.CURRENCIES}


class Expense(models.Model):
    amount = models.DecimalField(max_digits=10, decimal_places=2)
    currency = models.CharField(max_length=3, choices=get_currencies)

Att skicka en callable för choices kan vara särskilt praktiskt när, till exempel, alternativen är:

  • resultatet av I/O-bundna operationer (som potentiellt kan cachas), t.ex. att fråga en tabell i samma eller en extern databas, eller att komma åt val från en statisk fil.

  • en lista som för det mesta är stabil men som kan variera från tid till annan eller från projekt till projekt. Exempel i denna kategori är att använda tredjepartsappar som tillhandahåller en välkänd förteckning över värden, t.ex. valutor, länder, språk, tidszoner etc.

I allmänhet är det bäst att definiera val i en modellklass och att definiera en konstant med lämpligt namn för varje värde:

from django.db import models


class Student(models.Model):
    FRESHMAN = "FR"
    SOPHOMORE = "SO"
    JUNIOR = "JR"
    SENIOR = "SR"
    GRADUATE = "GR"
    YEAR_IN_SCHOOL_CHOICES = {
        FRESHMAN: "Freshman",
        SOPHOMORE: "Sophomore",
        JUNIOR: "Junior",
        SENIOR: "Senior",
        GRADUATE: "Graduate",
    }
    year_in_school = models.CharField(
        max_length=2,
        choices=YEAR_IN_SCHOOL_CHOICES,
        default=FRESHMAN,
    )

    def is_upperclass(self):
        return self.year_in_school in {self.JUNIOR, self.SENIOR}

Du kan definiera en lista med val utanför en modellklass och sedan hänvisa till den, men om du definierar valen och namnen för varje val i modellklassen behålls all denna information i den klass som använder den och hjälper till att hänvisa till valen (t.ex. fungerar Student.SOPHOMORE överallt där modellen Student har importerats).

Du kan också samla dina tillgängliga val i namngivna grupper som kan användas för organisatoriska ändamål:

MEDIA_CHOICES = {
    "Audio": {
        "vinyl": "Vinyl",
        "cd": "CD",
    },
    "Video": {
        "vhs": "VHS Tape",
        "dvd": "DVD",
    },
    "unknown": "Unknown",
}

Mappningens nyckel är det namn som ska användas för gruppen och värdet är alternativen i gruppen, som består av fältvärdet och ett lättläst namn för ett alternativ. Grupperade alternativ kan kombineras med ogrupperade alternativ i en enda mappning (som alternativet "unknown" i det här exemplet).

Du kan också använda en sekvens, t.ex. en lista med 2-tupler:

MEDIA_CHOICES = [
    (
        "Audio",
        (
            ("vinyl", "Vinyl"),
            ("cd", "CD"),
        ),
    ),
    (
        "Video",
        (
            ("vhs", "VHS Tape"),
            ("dvd", "DVD"),
        ),
    ),
    ("unknown", "Unknown"),
]

Observera att val kan vara vilket sekvensobjekt som helst - inte nödvändigtvis en lista eller tupel. Detta gör att du kan konstruera val dynamiskt. Men om du hackar choices för att vara dynamisk, är det förmodligen bättre att använda en riktig databastabell med en ForeignKey. choices är avsedd för statiska data som inte ändras mycket, om ens någonsin.

Observera

En ny migration skapas varje gång ordningen på valen ändras.

För varje modellfält som har choices inställt, kommer Django att normalisera valen till en lista med 2-tuples och lägga till en metod för att hämta det mänskliga läsbara namnet för fältets aktuella värde. Se get_FOO_display() i API-dokumentationen för databasen.

Om inte blank=False anges för fältet tillsammans med default kommer en etikett som innehåller "---------" att återges med valboxen. Om du vill åsidosätta detta beteende lägger du till en tupel i choices som innehåller None, t.ex. (None, 'Your String For Display'). Alternativt kan du använda en tom sträng istället för None där detta är meningsfullt - till exempel på en CharField.

Uppräkningstyper

Dessutom tillhandahåller Django enumerationstyper som du kan underklassa för att definiera val på ett koncist sätt:

from django.utils.translation import gettext_lazy as _


class Student(models.Model):
    class YearInSchool(models.TextChoices):
        FRESHMAN = "FR", _("Freshman")
        SOPHOMORE = "SO", _("Sophomore")
        JUNIOR = "JR", _("Junior")
        SENIOR = "SR", _("Senior")
        GRADUATE = "GR", _("Graduate")

    year_in_school = models.CharField(
        max_length=2,
        choices=YearInSchool,
        default=YearInSchool.FRESHMAN,
    )

    def is_upperclass(self):
        return self.year_in_school in {
            self.YearInSchool.JUNIOR,
            self.YearInSchool.SENIOR,
        }

Dessa fungerar på liknande sätt som enum från Pythons standardbibliotek, men med vissa ändringar:

  • Enum-medlemsvärden är en tupel av argument som ska användas när den konkreta datatypen konstrueras. Django stöder att lägga till ett extra strängvärde i slutet av denna tuple som ska användas som det mänskliga läsbara namnet, eller label. label kan vara en lat översättningsbar sträng. I de flesta fall kommer alltså medlemsvärdet att vara en (värde, etikett) 2-tupel. Se nedan för :ref:ett exempel underklassning av val <field-choices-enum-subclassing>` med en mer komplex datatyp. Om en tupel inte tillhandahålls, eller om det sista objektet inte är en (lat) sträng, är ``label :ref:``automatiskt genererad <field-choices-enum-auto-label>` från medlemsnamnet.

  • En .label-egenskap läggs till på värden för att returnera det mänskligt läsbara namnet.

  • Ett antal anpassade egenskaper läggs till i uppräkningsklasserna - .choices, .labels, .values och .names - för att göra det lättare att komma åt listor över dessa separata delar av uppräkningen.

    Varning

    Dessa egenskapsnamn kan inte användas som medlemsnamn eftersom de då skulle stå i konflikt med varandra.

  • Användningen av enum.unique() är tvingande för att säkerställa att värden inte kan definieras flera gånger. Det är osannolikt att detta förväntas i val för ett fält.

Observera att användning av YearInSchool.SENIOR, YearInSchool['SENIOR'] eller YearInSchool('SR') för att komma åt eller slå upp enum-medlemmar fungerar som förväntat, liksom egenskaperna .name och .value på medlemmarna.

Om du inte behöver översätta de lättlästa namnen kan du låta dem härledas från medlemsnamnet (genom att ersätta understreck med mellanslag och använda titelfas):

>>> class Vehicle(models.TextChoices):
...     CAR = "C"
...     TRUCK = "T"
...     JET_SKI = "J"
...
>>> Vehicle.JET_SKI.label
'Jet Ski'

Eftersom fallet där enumvärdena måste vara heltal är extremt vanligt, tillhandahåller Django en IntegerChoices-klass. Till exempel:

class Card(models.Model):
    class Suit(models.IntegerChoices):
        DIAMOND = 1
        SPADE = 2
        HEART = 3
        CLUB = 4

    suit = models.IntegerField(choices=Suit)

Det är också möjligt att använda Enum Functional API med förbehållet att etiketter genereras automatiskt enligt ovan:

>>> MedalType = models.TextChoices("MedalType", "GOLD SILVER BRONZE")
>>> MedalType.choices
[('GOLD', 'Gold'), ('SILVER', 'Silver'), ('BRONZE', 'Bronze')]
>>> Place = models.IntegerChoices("Place", "FIRST SECOND THIRD")
>>> Place.choices
[(1, 'First'), (2, 'Second'), (3, 'Third')]

Om du behöver stöd för en annan konkret datatyp än int eller str kan du subklassa Choices och den nödvändiga konkreta datatypen, t.ex. date för användning med DateField:

class MoonLandings(datetime.date, models.Choices):
    APOLLO_11 = 1969, 7, 20, "Apollo 11 (Eagle)"
    APOLLO_12 = 1969, 11, 19, "Apollo 12 (Intrepid)"
    APOLLO_14 = 1971, 2, 5, "Apollo 14 (Antares)"
    APOLLO_15 = 1971, 7, 30, "Apollo 15 (Falcon)"
    APOLLO_16 = 1972, 4, 21, "Apollo 16 (Orion)"
    APOLLO_17 = 1972, 12, 11, "Apollo 17 (Challenger)"

Det finns några ytterligare förbehåll att vara medveten om:

  • Uppräkningstyper stöder inte :ref:``namngivna grupper <field-choices-named-groups>`.

  • Eftersom en uppräkning med en konkret datatyp kräver att alla värden matchar typen, kan åsidosättande av blank label inte uppnås genom att skapa en medlem med värdet None. Istället ställer du in attributet __empty__ på klassen:

    class Answer(models.IntegerChoices):
        NO = 0, _("No")
        YES = 1, _("Yes")
    
        __empty__ = _("(Unknown)")
    

db_kolumn

Field.db_column

Namnet på den databaskolumn som ska användas för detta fält. Om detta inte anges kommer Django att använda fältets namn.

Om kolumnnamnet i din databas är ett reserverat SQL-ord eller innehåller tecken som inte är tillåtna i Python-variabelnamn - särskilt bindestrecket - är det OK. Django citerar kolumn- och tabellnamn bakom kulisserna.

db_kommentar

Field.db_comment

Kommentaren till den databaskolumn som ska användas för detta fält. Det är användbart för att dokumentera fält för personer med direkt databasåtkomst som kanske inte tittar på din Django-kod. Till exempel:

pub_date = models.DateTimeField(
    db_comment="Date and time when the article was published",
)

db_default

Field.db_default

Det databasberäknade standardvärdet för detta fält. Detta kan vara ett bokstavligt värde eller en databasfunktion, t.ex. Now:

created = models.DateTimeField(db_default=Now())

Mer komplexa uttryck kan användas, så länge de är uppbyggda av literaler och databasfunktioner:

month_due = models.DateField(
    db_default=TruncMonth(
        Now() + timedelta(days=90),
        output_field=models.DateField(),
    )
)

Databasens standardvärden kan inte referera till andra fält eller modeller. Detta är till exempel ogiltigt:

end = models.IntegerField(db_default=F("start") + 50)

Om både db_default och Field.default` är inställda kommer default att ha företräde när instanser skapas i Python-kod. db_default kommer fortfarande att vara inställt på databasnivå och kommer att användas när rader infogas utanför ORM eller när ett nytt fält läggs till i en migrering.

Om ett fält har ett db_default utan att ett default har angetts och inget värde har tilldelats fältet, returneras ett DatabaseDefault-objekt som fältvärde på osparade modellinstanser. Det faktiska värdet för fältet bestäms av databasen när modellinstansen sparas.

db_index

Field.db_index

Om True, skapas ett databasindex för detta fält.

Använd alternativet indexes istället.

Där det är möjligt, använd alternativet Meta.indexes istället. I nästan alla fall ger indexes mer funktionalitet än db_index. db_index kan bli föråldrad i framtiden.

db_tablespace

Field.db_tablespace[source]

Namnet på database tablespace som ska användas för fältets index, om fältet är indexerat. Standardvärdet är projektets DEFAULT_INDEX_TABLESPACE-inställning, om den är inställd, eller modellens db_tablespace, om det finns någon. Om backend inte stöder tablespaces för index, ignoreras detta alternativ.

standard

Field.default

Standardvärdet för fältet. Detta kan vara ett värde eller ett anropsbart objekt. Om det är anropsbart kommer det att anropas varje gång ett nytt objekt skapas.

Standardvärdet kan inte vara ett föränderligt objekt (modellinstans, list, set, etc.), eftersom en referens till samma instans av det objektet skulle användas som standardvärde i alla nya modellinstanser. Istället kan du paketera det önskade standardvärdet i en callable. Om du till exempel vill ange en standard dict för JSONField, använd en funktion:

def contact_default():
    return {"email": "to1@example.com"}


contact_info = JSONField("ContactInfo", default=contact_default)

lambda kan inte användas för fältalternativ som default eftersom de inte kan serialiseras av migreringar. Se den dokumentationen för andra varningar.

För fält som ForeignKey som mappar till modellinstanser bör standardvärdena vara värdet för det fält som de refererar till (pk om inte to_field är inställt) i stället för modellinstanser.

Standardvärdet används när nya modellinstanser skapas och inget värde har angetts för fältet. När fältet är en primärnyckel används standardvärdet även när fältet är inställt på None.

Standardvärdet kan också ställas in på databasnivå med Field.db_default.

”redigerbar

Field.editable

Om False, kommer fältet inte att visas i admin eller någon annan ModelForm. Det kommer också att hoppas över under modellvalidering. Standard är True.

Felmeddelanden

Field.error_messages[source]

Med argumentet error_messages kan du åsidosätta de standardmeddelanden som fältet kommer att ge upphov till. Skicka in en ordbok med nycklar som matchar de felmeddelanden som du vill åsidosätta.

Felmeddelanden inkluderar null, blank, invalid, invalid_choice, unique och unique_for_date. Ytterligare nycklar för felmeddelanden anges för varje fält i avsnittet ”Fälttyper” nedan.

Dessa felmeddelanden sprids ofta inte till formulär. Se betraktelser-om-modell-felmeddelanden.

hjälp_text

Field.help_text

Extra ”hjälp”-text som ska visas med formulärwidgeten. Det är användbart för dokumentation även om ditt fält inte används i ett formulär.

Observera att detta värde inte är HTML-escaped i automatiskt genererade formulär. Detta gör att du kan inkludera HTML i help_text om du så önskar. Till exempel:

help_text = "Please use the following format: <em>YYYY-MM-DD</em>."

Alternativt kan du använda vanlig text och django.utils.html.escape() för att undkomma alla HTML-specialtecken. Se till att du undandrar all hjälptext som kan komma från icke betrodda användare för att undvika en cross-site scripting-attack.

primär_nyckel

Field.primary_key

Om True, är detta fält primärnyckel för modellen.

Om du inte anger primary_key=True för något fält i din modell och inte har definierat en sammansatt primärnyckel, kommer Django automatiskt att lägga till ett fält för att hålla primärnyckeln. Så du behöver inte ställa in primary_key=True på något av dina fält om du inte vill åsidosätta standardbeteendet för primärnyckeln. Typen av automatiskt skapade primärnyckelfält kan anges per app i AppConfig.default_auto_field eller globalt i inställningen DEFAULT_AUTO_FIELD. För mer information, se Automatiska primärnyckelfält.

primary_key=True innebär null=False och unique=True. Endast ett fält per modell kan ange primary_key=True. Sammansatta primärnycklar måste definieras med hjälp av CompositePrimaryKey i stället för att sätta denna flagga till True för alla fält för att bibehålla denna invariant.

Fältet primary key är skrivskyddat. Om du ändrar värdet på primärnyckeln i ett befintligt objekt och sedan sparar det, skapas ett nytt objekt vid sidan av det gamla.

Primärnyckelfältet sätts till None när deleting ett objekt.

Changed in Django 5.2:

Fältet CompositePrimaryKey har lagts till.

unique

Field.unique[source]

Om True måste detta fält vara unikt i hela tabellen.

Detta verkställs på databasnivå och genom modellvalidering. Om du försöker spara en modell med ett duplicerat värde i ett unique-fält, kommer ett django.db.IntegrityError att skapas av modellens save()-metod.

Detta alternativ är giltigt för alla fälttyper utom ManyToManyField och OneToOneField.

Observera att när unique är True behöver du inte ange db_index, eftersom unique innebär att ett index skapas.

unique_for_date

Field.unique_for_date

Ange detta till namnet på en DateField eller DateTimeField för att kräva att detta fält är unikt för datumfältets värde.

Om du till exempel har ett fält title som har unique_for_date="pub_date", så skulle Django inte tillåta att två poster med samma title och pub_date registreras.

Observera att om du ställer in detta så att det pekar på en DateTimeField, kommer endast datumdelen av fältet att beaktas. Dessutom, när USE_TZ är True, kommer kontrollen att utföras i :ref:current time zone <default-current-time-zone> vid den tidpunkt då objektet sparas.

Detta verkställs av Model.validate_unique() under modellvalidering men inte på databasnivå. Om någon unique_for_date-restriktion involverar fält som inte är en del av en ModelForm (till exempel om ett av fälten är listat i exclude eller har editable=False), kommer Model.validate_unique() att hoppa över valideringen för den specifika restriktionen.

unika_för_månad

Field.unique_for_month

Som unique_for_date, men kräver att fältet är unikt med avseende på månaden.

unique_for_year

Field.unique_for_year

Som unique_for_date och unique_for_month.

verbose_namn

Field.verbose_name

Ett mänskligt läsbart namn för fältet. Om verbose-namnet inte anges kommer Django automatiskt att skapa det med hjälp av fältets attributnamn och konvertera understreck till mellanslag. Se Verbose field names.

validerare

Field.validators[source]

En lista över validerare som ska köras för detta fält. Se validators dokumentation för mer information.

Fälttyper

AutoField

class AutoField(**options)[source]

En IntegerField som automatiskt ökar i enlighet med tillgängliga ID:n. Du behöver vanligtvis inte använda detta direkt; ett primärnyckelfält kommer automatiskt att läggas till i din modell om du inte anger något annat. Se Automatiska primärnyckelfält.

BigAutoField

class BigAutoField(**options)[source]

Ett 64-bitars heltal, ungefär som en AutoField förutom att det garanterat passar siffror från 1 till 9223372036854775807.

BigIntegerField

class BigIntegerField(**options)[source]

Ett 64-bitars heltal, ungefär som ett IntegerField förutom att det garanterat passar siffror från -9223372036854775808 till 9223372036854775807. Standardformulärwidgeten för detta fält är en NumberInput.

BinaryField

class BinaryField(max_length=None, **options)[source]

Ett fält för att lagra binära rådata. Det kan tilldelas bytes, bytearray eller memoryview.

Som standard ställer BinaryField in editable till False, i vilket fall den inte kan inkluderas i en ModelForm.

BinaryField.max_length

Valfritt. Den maximala längden (i byte) på fältet. Den maximala längden verkställs i Djangos validering med hjälp av MaxLengthValidator.

Missbruk av BinaryField

Även om du kanske funderar på att lagra filer i databasen, tänk på att det är dålig design i 99% o av fallen. Det här fältet är inte en ersättning för korrekt hantering av statiska filer.

BooleanField

class BooleanField(**options)[source]

Ett sant/falskt fält.

Standardformulärwidgeten för detta fält är CheckboxInput, eller NullBooleanSelect om null=True.

Standardvärdet för BooleanField är None när Field.default inte är definierat.

SammansattPrimärnyckel

New in Django 5.2.
class CompositePrimaryKey(*field_names, **options)[source]

Ett virtuellt fält som används för att definiera en sammansatt primärnyckel.

Detta fält måste definieras som modellens pk-attribut. Om det finns kommer Django att skapa den underliggande modelltabellen med en sammansatt primärnyckel.

Argumentet *field_names är en lista med positionella fältnamn som utgör primärnyckeln.

Se Sammansatta primärnycklar för mer information.

CharField

class CharField(max_length=None, **options)[source]

Ett strängfält, för små till stora strängar.

För stora mängder text, använd TextField.

Standardformulärwidgeten för detta fält är en TextInput.

CharField har följande extra argument:

CharField.max_length

Den maximala längden (i tecken) på fältet. max_length verkställs på databasnivå och i Djangos validering med hjälp av MaxLengthValidator. Det krävs för alla databasbackends som ingår i Django utom PostgreSQL och SQLite, som stöder obegränsade VARCHAR-kolumner.

Observera

Om du skriver en applikation som måste kunna portas till flera databasbackends bör du vara medveten om att det finns begränsningar för max_length för vissa backends. Se Databas backend notes för mer information.

Changed in Django 5.2:

Stöd för obegränsade VARCHAR-kolumner har lagts till i SQLite.

CharField.db_collation

Valfritt. Databasens kollationsnamn för fältet.

Observera

Kollationeringsnamn är inte standardiserade. Därför kommer detta inte att vara portabelt mellan olika databasbackends.

Oracle

Oracle stöder endast kollationering när databasinitialiseringsparametern MAX_STRING_SIZE är inställd på EXTENDED.

DateField

class DateField(auto_now=False, auto_now_add=False, **options)[source]

Ett datum, representerat i Python av en datetime.date-instans. Har några extra, valfria argument:

DateField.auto_now

Ställ automatiskt in fältet på now varje gång objektet sparas. Användbart för tidsstämplar för ”senast ändrad”. Observera att det aktuella datumet alltid används; det är inte bara ett standardvärde som du kan åsidosätta.

Fältet uppdateras endast automatiskt när du anropar Model.save(). Fältet uppdateras inte när du gör uppdateringar av andra fält på andra sätt, t.ex. QuerySet.update(), men du kan ange ett anpassat värde för fältet i en sådan uppdatering.

DateField.auto_now_add

Ställ automatiskt in fältet på now när objektet skapas för första gången. Användbart för skapande av tidsstämplar. Observera att det aktuella datumet alltid används; det är inte bara ett standardvärde som du kan åsidosätta. Så även om du anger ett värde för det här fältet när du skapar objektet kommer det att ignoreras. Om du vill kunna ändra det här fältet anger du följande i stället för auto_now_add=True:

Standardformulärwidgeten för detta fält är en DateInput. Administratören lägger till en JavaScript-kalender och en genväg för ”Today”. Inkluderar ytterligare en nyckel för felmeddelandet invalid_date.

Alternativen auto_now_add, auto_now och default är ömsesidigt uteslutande. Varje kombination av dessa alternativ kommer att resultera i ett fel.

Observera

Som det nu är implementerat kommer fältet att få inställningarna editable=False och blank=True om auto_now eller auto_now_add sätts till True.

Observera

Alternativen auto_now och auto_now_add kommer alltid att använda datumet i default timezone <default-current-time-zone>` vid skapandet eller uppdateringen. Om du behöver något annat kan du överväga att använda din egen anropsbara standard eller åsidosätta save() istället för att använda auto_now eller auto_now_add; eller använda en DateTimeField istället för en DateField och bestämma hur konverteringen från datetime till datum ska hanteras vid visningstillfället.

Varning

Använd alltid DateField med en datetime.date-instans.

Om du har en datetime.datetime-instans rekommenderas det att du konverterar den till en datetime.date först. Om du inte gör det kommer DateField att lokalisera datetime.datetime till default timezone och konvertera den till en datetime.date-instans och ta bort dess tidskomponent. Detta gäller både för lagring och jämförelse.

DatumTimeField

class DateTimeField(auto_now=False, auto_now_add=False, **options)[source]

Ett datum och en tid, representerade i Python av en datetime.datetime-instans. Tar samma extra argument som DateField.

Standardformulärwidgeten för detta fält är en enda DateTimeInput. Administratören använder två separata TextInput-widgetar med JavaScript-genvägar.

Varning

Använd alltid DateTimeField med en datetime.datetime-instans.

Om du har en datetime.date-instans rekommenderas att du konverterar den till en datetime.datetime först. Om du inte gör det kommer DateTimeField att använda midnatt i default timezone för tidskomponenten. Detta gäller både för lagring och jämförelse. För att jämföra datumdelen av en DateTimeField med en datetime.date-instans, använd date lookup.

DecimalField

class DecimalField(max_digits=None, decimal_places=None, **options)[source]

Ett decimaltal med fast precision, representerat i Python av en Decimal-instans. Den validerar indata med hjälp av DecimalValidator.

Har följande krävda argument:

DecimalField.max_digits

Det maximala antalet siffror som tillåts i talet. Observera att detta tal måste vara större än eller lika med decimal_places.

DecimalField.decimal_places

Antalet decimaler som ska lagras med talet.

Om du t.ex. vill lagra siffror upp till 999,99 med en upplösning på 2 decimaler använder du:

models.DecimalField(..., max_digits=5, decimal_places=2)

Och för att lagra tal upp till cirka en miljard med en upplösning på 10 decimaler:

models.DecimalField(..., max_digits=19, decimal_places=10)

Standardformulärwidgeten för detta fält är en NumberInput när localize är False eller annars TextInput.

Observera

För mer information om skillnaderna mellan klasserna FloatField och DecimalField, se FloatField vs. DecimalField. Du bör också vara medveten om SQLite-begränsningar av decimalfält.

DurationField

class DurationField(**options)[source]

Ett fält för lagring av tidsperioder - modellerat i Python av timedelta. När den används på PostgreSQL är datatypen som används ett intervall och på Oracle är datatypen INTERVAL DAY (9) TO SECOND (6) ``. Annars används en ``bigint av mikrosekunder.

Observera

Aritmetik med DurationField fungerar i de flesta fall. Men på alla andra databaser än PostgreSQL fungerar det inte som förväntat att jämföra värdet på en DurationField med aritmetik på DateTimeField -instanser.

EmailField

class EmailField(max_length=254, **options)[source]

En CharField som kontrollerar att värdet är en giltig e-postadress med hjälp av EmailValidator.

FileField

class FileField(upload_to='', storage=None, max_length=100, **options)[source]

Ett fält för filuppladdning.

Observera

Argumentet primary_key stöds inte och kommer att ge upphov till ett fel om det används.

Har följande valfria argument:

FileField.upload_to

Detta attribut ger ett sätt att ställa in uppladdningskatalogen och filnamnet, och kan ställas in på två sätt. I båda fallen skickas värdet till metoden Storage.save().

Om du anger ett strängvärde eller en Path kan det innehålla strftime()-formatering, som ersätts med datumet/tiden för filuppladdningen (så att uppladdade filer inte fyller upp den angivna katalogen). Till exempel:

class MyModel(models.Model):
    # file will be uploaded to MEDIA_ROOT/uploads
    upload = models.FileField(upload_to="uploads/")
    # or...
    # file will be saved to MEDIA_ROOT/uploads/2015/01/30
    upload = models.FileField(upload_to="uploads/%Y/%m/%d/")

Om du använder standard FileSystemStorage, kommer strängvärdet att läggas till din MEDIA_ROOT sökväg för att bilda platsen på det lokala filsystemet där uppladdade filer kommer att lagras. Om du använder en annan lagring, kontrollera dokumentationen för den lagringen för att se hur den hanterar upload_to.

upload_to kan också vara en anropbar funktion, t.ex. en funktion. Denna kommer att anropas för att erhålla uppladdningssökvägen, inklusive filnamnet. Denna anropbara funktion måste acceptera två argument och returnera en sökväg i Unix-stil (med snedstreck) som ska skickas vidare till lagringssystemet. De två argumenten är:

Argument

Beskrivning

instans

En instans av modellen där FileField är definierad. Mer specifikt är detta den särskilda instans där den aktuella filen bifogas.

I de flesta fall har det här objektet inte sparats i databasen ännu, så om det använder standardinställningen AutoField kanske det ännu inte har något värde för sitt primärnyckelfält.

filnamn

Det filnamn som ursprungligen gavs till filen. Detta kan eller kan inte tas med i beräkningen när den slutliga destinationssökvägen bestäms.

Till exempel:

def user_directory_path(instance, filename):
    # file will be uploaded to MEDIA_ROOT/user_<id>/<filename>
    return "user_{0}/{1}".format(instance.user.id, filename)


class MyModel(models.Model):
    upload = models.FileField(upload_to=user_directory_path)
FileField.storage

Ett lagringsobjekt eller en anropsbar funktion som returnerar ett lagringsobjekt. Detta hanterar lagring och hämtning av dina filer. Se Hantera filer för mer information om hur du tillhandahåller detta objekt.

Standardformulärwidgeten för detta fält är en ClearableFileInput.

Att använda en FileField eller en ImageField (se nedan) i en modell kräver några steg:

  1. I din inställningsfil måste du definiera MEDIA_ROOT som den fullständiga sökvägen till en katalog där du vill att Django ska lagra uppladdade filer. (Av prestandaskäl lagras inte dessa filer i databasen.) Definiera MEDIA_URL som den publika URL:en för den katalogen. Se till att den här katalogen är skrivbar av webbserverns användarkonto.

  2. Lägg till FileField eller ImageField i din modell och definiera alternativet upload_to för att ange en underkatalog i MEDIA_ROOT som ska användas för uppladdade filer.

  3. Allt som kommer att lagras i din databas är en sökväg till filen (i förhållande till MEDIA_ROOT). Du kommer troligen att vilja använda det praktiska attributet url som tillhandahålls av Django. Om din ImageField till exempel heter mug_shot kan du få den absoluta sökvägen till din bild i en mall med {{ object.mug_shot.url }}.

Anta till exempel att din MEDIA_ROOT är inställd på '/home/media' och upload_to är inställd på 'photos/%Y/%m/%d'. Delen '%Y/%m/%d' i upload_to är strftime()-formatering; '%Y' är det fyrsiffriga året, '%m' är den tvåsiffriga månaden och '%d' är den tvåsiffriga dagen. Om du laddar upp en fil den 15 januari 2007 kommer den att sparas i katalogen /home/media/photos/2007/01/15.

Om du vill hämta den uppladdade filens filnamn på disken eller filens storlek kan du använda attributen name respektive size; för mer information om tillgängliga attribut och metoder, se klassreferensen File och ämnesguiden Hantera filer.

Observera

Filen sparas som en del av att modellen sparas i databasen, så det faktiska filnamnet som används på disken kan man inte lita på förrän efter att modellen har sparats.

Den uppladdade filens relativa URL kan erhållas med hjälp av attributet url. Internt anropar detta url()-metoden för den underliggande Storage-klassen.

Observera att när du hanterar uppladdade filer bör du vara mycket uppmärksam på var du laddar upp dem och vilken typ av filer de är, för att undvika säkerhetshål. Validera alla uppladdade filer så att du är säker på att filerna är vad du tror att de är. Om du till exempel blint låter någon ladda upp filer, utan validering, till en katalog som ligger i din webbservers dokumentrot, kan någon ladda upp ett CGI- eller PHP-skript och köra det skriptet genom att besöka dess URL på din webbplats. Tillåt inte det.

Observera också att även en uppladdad HTML-fil, eftersom den kan köras av webbläsaren (men inte av servern), kan utgöra säkerhetshot som motsvarar XSS- eller CSRF-attacker.

FileField-instanser skapas i din databas som varchar-kolumner med en maximal standardlängd på 100 tecken. Precis som för andra fält kan du ändra den maximala längden med argumentet max_length.

FileField och FieldFile

class FieldFile[source]

När du öppnar en FileField på en modell får du en instans av FieldFile som en proxy för åtkomst till den underliggande filen.

API:et för FieldFile speglar det för File, med en viktig skillnad: *Objektet som klassen omsluter är inte nödvändigtvis en omslutning kring Pythons inbyggda filobjekt * Istället är det en omslutning kring resultatet av Storage.open()-metoden, som kan vara ett File-objekt, eller det kan vara en anpassad lagrings implementering av File API.

Utöver API:et som ärvs från File, såsom read() och write(), innehåller FieldFile flera metoder som kan användas för att interagera med den underliggande filen:

Varning

Två metoder i den här klassen, save() och delete(), sparar som standard modellobjektet för den associerade FieldFile i databasen.

FieldFile.name

Namnet på filen inklusive den relativa sökvägen från roten till Storage för den associerade FileField.

FieldFile.path[source]

En skrivskyddad egenskap för att komma åt filens lokala filsystemssökväg genom att anropa path()-metoden i den underliggande Storage-klassen.

FieldFile.size[source]

Resultatet av den underliggande Storage.size()-metoden.

FieldFile.url[source]

En skrivskyddad egenskap för att komma åt filens relativa URL genom att anropa url()-metoden i den underliggande Storage-klassen.

FieldFile.open(mode='rb')[source]

Öppnar eller återöppnar filen som är associerad med denna instans i angivet mode. Till skillnad från Pythons standardmetod open() returnerar den inte en filbeskrivare.

Eftersom den underliggande filen öppnas implicit vid åtkomst till den, kan det vara onödigt att anropa denna metod förutom för att återställa pekaren till den underliggande filen eller för att ändra mode.

FieldFile.close()[source]

Uppträder som Pythons standardmetod file.close() och stänger den fil som är kopplad till denna instans.

FieldFile.save(name, content, save=True)[source]

Den här metoden tar ett filnamn och filinnehåll och skickar dem till lagringsklassen för fältet och associerar sedan den lagrade filen med modellfältet. Om du manuellt vill associera fildata med FileField-instanser i din modell, används metoden save() för att bevara fildata.

Tar två obligatoriska argument: name som är namnet på filen och content som är ett objekt som innehåller filens innehåll. Det valfria argumentet save styr om modellinstansen sparas eller inte efter att filen som är associerad med detta fält har ändrats. Standardvärdet är True.

Observera att argumentet content ska vara en instans av django.core.files.File, inte Pythons inbyggda filobjekt. Du kan konstruera en File från ett befintligt Python-filobjekt så här:

from django.core.files import File

# Open an existing file using Python's built-in open()
f = open("/path/to/hello.world")
myfile = File(f)

Eller så kan du konstruera en från en Python-sträng så här:

from django.core.files.base import ContentFile

myfile = ContentFile("hello world")

För mer information, se Hantera filer.

FieldFile.delete(save=True)[source]

Raderar filen som är kopplad till denna instans och rensar alla attribut på fältet. Observera: Den här metoden stänger filen om den råkar vara öppen när delete() anropas.

Det valfria argumentet save styr om modellinstansen sparas eller inte efter att filen som är associerad med detta fält har tagits bort. Standardvärdet är True.

Observera att när en modell tas bort tas inte relaterade filer bort. Om du behöver rensa bort föräldralösa filer måste du hantera det själv (t.ex. med ett anpassat hanteringskommando som kan köras manuellt eller schemaläggas för att köras regelbundet via t.ex. cron).

FilePathField

class FilePathField(path='', match=None, recursive=False, allow_files=True, allow_folders=False, max_length=100, **options)[source]

En CharField vars valmöjligheter är begränsade till filnamnen i en viss katalog på filsystemet. Har några specialargument, varav det första är obligatoriskt:

FilePathField.path

Obligatorisk. Den absoluta filsystemssökvägen till en katalog från vilken denna FilePathField ska hämta sina val. Exempel: "/home/images".

path kan också vara en anropsbar funktion, t.ex. en funktion för att dynamiskt ställa in sökvägen vid körning. Exempel:

import os
from django.conf import settings
from django.db import models


def images_path():
    return os.path.join(settings.LOCAL_FILE_DIR, "images")


class MyModel(models.Model):
    file = models.FilePathField(path=images_path)
FilePathField.match

Valfritt. Ett reguljärt uttryck, som en sträng, som FilePathField kommer att använda för att filtrera filnamn. Observera att regex kommer att tillämpas på basfilnamnet, inte på hela sökvägen. Exempel: "foo.*\.txt$", vilket matchar en fil som heter foo23.txt men inte bar.txt eller foo23.png.

FilePathField.recursive

Valfritt. Antingen True eller False. Standard är False. Anger om alla underkataloger till path ska inkluderas

FilePathField.allow_files

Valfritt. Antingen True eller False. Standard är True. Anger om filer på den angivna platsen ska inkluderas. Antingen detta eller allow_folders måste vara True.

FilePathField.allow_folders

Valfritt. Antingen True eller False. Standard är False. Anger om mappar på den angivna platsen ska inkluderas. Antingen detta eller allow_files måste vara True.

Det enda potentiella problemet är att match gäller för det grundläggande filnamnet, inte den fullständiga sökvägen. Så i det här exemplet:

FilePathField(path="/home/images", match="foo.*", recursive=True)

…kommer att matcha /home/images/foo.png men inte /home/images/foo/bar.png eftersom match gäller för basfilnamnet (foo.png och bar.png).

FilePathField-instanser skapas i din databas som varchar-kolumner med en maximal standardlängd på 100 tecken. Precis som för andra fält kan du ändra den maximala längden med hjälp av argumentet max_length.

FloatField

class FloatField(**options)[source]

Ett flyttal som i Python representeras av en float-instans.

Standardformulärwidgeten för detta fält är en NumberInput när localize är False eller annars TextInput.

FloatField vs. DecimalField

Klassen FloatField blandas ibland ihop med klassen DecimalField. Även om de båda representerar verkliga tal, representerar de dessa tal på olika sätt. FloatField använder Pythons typ float internt, medan DecimalField använder Pythons typ Decimal. För information om skillnaden mellan de två, se Pythons dokumentation för modulen decimal.

GeneratedField

class GeneratedField(expression, output_field, db_persist=None, **kwargs)[source]

Ett fält som alltid beräknas baserat på andra fält i modellen. Detta fält hanteras och uppdateras av databasen själv. Använder SQL-syntaxen GENERATED ALWAYS.

Det finns två typer av genererade kolumner: lagrade och virtuella. En lagrad genererad kolumn beräknas när den skrivs (infogas eller uppdateras) och tar upp lagringsutrymme som om det vore en vanlig kolumn. En virtuell genererad kolumn upptar ingen lagringsplats och beräknas när den läses. En virtuell genererad kolumn liknar alltså en vy och en lagrad genererad kolumn liknar en materialiserad vy.

GeneratedField.expression

Ett Expression som används av databasen för att automatiskt ställa in fältvärdet varje gång modellen ändras.

Uttrycken ska vara deterministiska och endast referera till fält inom modellen (i samma databastabell). Genererade fält kan inte referera till andra genererade fält. Databasbackends kan införa ytterligare begränsningar.

GeneratedField.output_field

En modellfältsinstans för att definiera fältets datatyp.

GeneratedField.db_persist

Bestämmer om databaskolumnen ska ta upp lagringsutrymme som om den vore en riktig kolumn. Om False, fungerar kolumnen som en virtuell kolumn och tar inte upp lagringsutrymme i databasen.

PostgreSQL stöder endast kvarvarande kolumner. Oracle stöder endast virtuella kolumner.

Uppdatera uppgifterna

Eftersom databasen beräknar värdet måste objektet laddas om för att få tillgång till det nya värdet efter save(), till exempel genom att använda refresh_from_db().

Begränsningar i databasen

Det finns många databasspecifika begränsningar för genererade fält som Django inte validerar och databasen kan ge upphov till ett fel, t.ex. PostgreSQL kräver att funktioner och operatörer som refereras till i en genererad kolumn markeras som IMMUTABLE.

Du bör alltid kontrollera att expression stöds i din databas. Kolla in MariaDB, MySQL, Oracle, PostgreSQL eller SQLite docs.

GenericIPAddressField

class GenericIPAddressField(protocol='both', unpack_ipv4=False, **options)[source]

En IPv4- eller IPv6-adress i strängformat (t.ex. 192.0.2.30 eller 2a02:42fe::4). Standardformulärwidgeten för detta fält är en TextInput.

Normaliseringen av IPv6-adresser följer RFC 4291 Section 2.2 avsnitt 2.2, inklusive användning av det IPv4-format som föreslås i punkt 3 i det avsnittet, som ::ffff:192.0.2.0. Till exempel: skulle 2001:0::0:01 normaliseras till 2001::1, och ::ffff:0a0a:0a0a till ::ffff:10.10.10.10. Alla tecken konverteras till gemener.

GenericIPAddressField.protocol

Begränsar giltiga indata till det angivna protokollet. Accepterade värden är 'both' (standard), 'IPv4' eller 'IPv6'. Matchningen är okänslig för skiftlägesskillnader.

GenericIPAddressField.unpack_ipv4

Packar upp IPv4-mappade adresser som ::ffff:192.0.2.1. Om detta alternativ är aktiverat kommer den adressen att packas upp till 192.0.2.1. Standard är inaktiverat. Kan endast användas när protocol är inställt på 'both'.

Om du tillåter tomma värden måste du tillåta null-värden eftersom tomma värden lagras som null.

ImageField

class ImageField(upload_to=None, height_field=None, width_field=None, max_length=100, **options)[source]

Ärver alla attribut och metoder från FileField, men validerar också att det uppladdade objektet är en giltig bild.

Förutom de specialattribut som finns för FileField har en ImageField även attributen height och width.

För att göra det lättare att ställa frågor om dessa attribut har ImageField följande valfria argument:

ImageField.height_field

Namn på ett modellfält som automatiskt fylls i med bildens höjd varje gång ett bildobjekt ställs in.

ImageField.width_field

Namn på ett modellfält som automatiskt fylls i med bildens bredd varje gång ett bildobjekt ställs in.

Kräver biblioteket pillow.

ImageField-instanser skapas i din databas som varchar-kolumner med en maximal standardlängd på 100 tecken. Precis som för andra fält kan du ändra den maximala längden med argumentet max_length.

Standardformulärwidgeten för detta fält är en ClearableFileInput.

IntegerField

class IntegerField(**options)[source]

Ett heltal. Värden är endast tillåtna mellan vissa (databasberoende) punkter. Värden från -2147483648 till 2147483647 är kompatibla i alla databaser som stöds av Django.

Den använder MinValueValidator och MaxValueValidator för att validera inmatningen baserat på de värden som standarddatabasen stöder.

Standardformulärwidgeten för detta fält är en NumberInput när localize är False eller annars TextInput.

JSONField

class JSONField(encoder=None, decoder=None, **options)[source]

Ett fält för lagring av JSON-kodade data. I Python representeras data i Pythons ursprungliga format: ordböcker, listor, strängar, siffror, booleaner och None.

JSONField stöds på MariaDB, MySQL, Oracle, PostgreSQL och SQLite (med JSON1-tillägget aktiverat).

JSONField.encoder

En valfri json.JSONEncoder-underklass för att serialisera datatyper som inte stöds av standard JSON serializer (t.ex. datetime.datetime eller UUID). Du kan till exempel använda klassen DjangoJSONEncoder.

Standardvärdet är json.JSONEncoder.

JSONField.decoder

En valfri json.JSONDecoder-underklass för att deserialisera värdet som hämtats från databasen. Värdet kommer att vara i det format som valts av den anpassade kodaren (oftast en sträng). Din deserialisering kan behöva ta hänsyn till det faktum att du inte kan vara säker på indatatypen. Du riskerar till exempel att returnera en datetime som faktiskt var en sträng som bara råkade vara i samma format som valts för datetime.

Standardvärdet är json.JSONDecoder.

För att fråga JSONField i databasen, se Fråga om JSONField.

Standardvärde

Om du ger fältet en default, se till att det är en callable som t.ex. dict-klassen eller en funktion som returnerar ett nytt objekt varje gång. Felaktig användning av ett föränderligt objekt som default={} eller default=[] skapar en föränderlig standard som delas mellan alla instanser.

Indexering

Index och Field.db_index skapar båda ett B-trädindex, vilket inte är särskilt användbart när man frågar JSONField. Endast på PostgreSQL kan du använda GinIndex som är bättre lämpad.

PostgreSQL-användare

PostgreSQL har två inbyggda JSON-baserade datatyper: `` json`` och `` jsonb``. Huvudskillnaden mellan dem är hur de lagras och hur de kan frågas. PostgreSQL: s `` json``-fält lagras som den ursprungliga strängrepresentationen av JSON och måste avkodas i farten när det frågas baserat på nycklar. Fältet jsonb lagras baserat på den faktiska strukturen i JSON som tillåter indexering. Avvägningen är en liten extra kostnad för att skriva till fältet jsonb. JSONField använder jsonb.

Oracle-användare

Oracle Database stöder inte lagring av JSON-skalärvärden. Endast JSON-objekt och matriser (representerade i Python med hjälp av dict och list) stöds.

PositivBigIntegerField

class PositiveBigIntegerField(**options)[source]

Som en PositiveIntegerField, men tillåter bara värden under en viss (databasberoende) punkt. Värden från 0 till 9223372036854775807 är kompatibla i alla databaser som stöds av Django.

PositivIntegerField

class PositiveIntegerField(**options)[source]

Som en IntegerField, men måste vara antingen positiv eller noll (0). Värden är endast tillåtna under en viss (databasberoende) punkt. Värden från 0 till 2147483647 är kompatibla i alla databaser som stöds av Django. Värdet 0 accepteras av bakåtkompatibilitetsskäl.

Positiv liten heltalsfält

class PositiveSmallIntegerField(**options)[source]

Som en PositiveIntegerField, men tillåter bara värden under en viss (databasberoende) punkt. Värden från 0 till 32767 är kompatibla i alla databaser som stöds av Django.

SlugField

class SlugField(max_length=50, **options)[source]

Slug är en term för tidningar. En slug är en kort etikett för något, som bara innehåller bokstäver, siffror, understrykningar eller bindestreck. De används i allmänhet i webbadresser.

Precis som en CharField kan du ange max_length (läs även anmärkningen om databasportabilitet och max_length i det avsnittet). Om max_length inte anges kommer Django att använda en standardlängd på 50.

Innebär att Field.db_index sätts till True.

Det är ofta användbart att automatiskt fylla i en SlugField baserat på värdet av något annat värde. Du kan göra detta automatiskt i admin med prepopulated_fields.

Den använder validate_slug eller validate_unicode_slug för validering.

SlugField.allow_unicode

Om True, accepterar fältet Unicode-bokstäver utöver ASCII-bokstäver. Standardvärdet är False.

SmallAutoField

class SmallAutoField(**options)[source]

Som en AutoField, men tillåter bara värden under en viss (databasberoende) gräns. Värden från 1 till 32767 är kompatibla i alla databaser som stöds av Django.

LitenIntegerField

class SmallIntegerField(**options)[source]

Som en IntegerField, men tillåter bara värden under en viss (databasberoende) punkt. Värden från -32768 till 32767 är kompatibla i alla databaser som stöds av Django.

Textfält

class TextField(**options)[source]

Ett stort textfält. Standardformulärwidgeten för detta fält är en Textarea.

Om du anger ett max_length-attribut kommer det att återspeglas i Textarea-widgeten i det autogenererade formulärfältet. Det verkställs dock inte på modell- eller databasnivå. Använd en CharField för det.

TextField.db_collation

Valfritt. Databasens kollationsnamn för fältet.

Observera

Kollationeringsnamn är inte standardiserade. Därför kommer detta inte att vara portabelt mellan olika databasbackends.

Oracle

Oracle stöder inte kollationer för en TextField.

TimeField

class TimeField(auto_now=False, auto_now_add=False, **options)[source]

En tid, representerad i Python av en datetime.time-instans. Accepterar samma autopopuleringsalternativ som DateField.

Standardformulärwidgeten för detta fält är en TimeInput. Administratören lägger till några JavaScript-genvägar.

URL-fält

class URLField(max_length=200, **options)[source]

En CharField för en URL, validerad av URLValidator.

Standardformulärwidgeten för det här fältet är en URLInput.

Som alla CharField-subklasser tar URLField det valfria argumentet max_length. Om du inte anger max_length används standardvärdet 200.

UUIDField

class UUIDField(**options)[source]

Ett fält för lagring av universellt unika identifierare. Använder Pythons UUID klass. När det används på PostgreSQL och MariaDB 10.7+ lagras detta i en uuid datatyp, annars i en ``char (32) ``.

Universellt unika identifierare är ett bra alternativ till AutoField för primary_key. Databasen kommer inte att generera UUID åt dig, så det rekommenderas att du använder default:

import uuid
from django.db import models


class MyUUIDModel(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
    # other fields

Observera att en callable (med parenteserna utelämnade) skickas till default, inte en instans av UUID.

Uppslagningar på PostgreSQL och MariaDB 10.7+

Att använda iexact, contains, icontains, startswith, istartswith, endswith eller iendswith lookups på PostgreSQL fungerar inte för värden utan bindestreck, eftersom PostgreSQL och MariaDB 10.7+ lagrar dem i en bindestreckad uuid-datatypstyp.

Relationsfält

Django definierar också en uppsättning fält som representerar relationer.

ForeignKey

class ForeignKey(to, on_delete, **options)[source]

En många-till-en-relation. Kräver två positionsargument: den klass som modellen är relaterad till och alternativet on_delete:

from django.db import models


class Manufacturer(models.Model):
    name = models.TextField()


class Car(models.Model):
    manufacturer = models.ForeignKey(Manufacturer, on_delete=models.CASCADE)

Det första positionella argumentet kan vara antingen en konkret modellklass eller en lazy reference till en modellklass. Recursive relationships, där en modell har en relation med sig själv, stöds också.

Se ForeignKey.on_delete för detaljer om det andra positionella argumentet.

Ett databasindex skapas automatiskt för ForeignKey. Du kan inaktivera detta genom att sätta db_index till False. Du kanske vill undvika omkostnaderna för ett index om du skapar en främmande nyckel för konsistens snarare än för sammanfogningar, eller om du kommer att skapa ett alternativt index som ett partiellt index eller ett index med flera kolumner.

Databasrepresentation

Bakom kulisserna lägger Django till "_id" till fältnamnet för att skapa dess kolumnnamn i databasen. I exemplet ovan kommer databastabellen för modellen Car att ha en kolumn med namnet manufacturer_id. Du kan ändra detta explicit genom att ange db_column, men din kod ska aldrig behöva hantera databasens kolumnnamn (såvida du inte skriver anpassad SQL). Du kommer alltid att hantera fältnamnen på ditt modellobjekt.

Argument

ForeignKey accepterar andra argument som definierar detaljerna i hur relationen fungerar.

ForeignKey.on_delete

När ett objekt som refereras till av en ForeignKey raderas, kommer Django att emulera beteendet hos SQL-begränsningen som anges av argumentet on_delete. Till exempel:, om du har en nullable ForeignKey och du vill att den ska sättas till null när det refererade objektet raderas:

user = models.ForeignKey(
    User,
    models.SET_NULL,
    blank=True,
    null=True,
)

on_delete skapar inte en SQL-begränsning i databasen. Stöd för kaskadalternativ på databasnivå kan komma att implementeras senare.

De möjliga värdena för on_delete finns i django.db.models:

  • CASCADE[source]

    Kaskad raderingar. Django emulerar beteendet hos SQL-begränsningen ON DELETE CASCADE och raderar också objektet som innehåller ForeignKey.

    Model.delete() anropas inte på relaterade modeller, men signalerna pre_delete och post_delete skickas för alla borttagna objekt.

  • PROTECT[source]

    Förhindra radering av det refererade objektet genom att skapa ProtectedError, en underklass av django.db.IntegrityError.

  • RESTRICT[source]

    Förhindra radering av det refererade objektet genom att skapa RestrictedError (en underklass av django.db.IntegrityError). Till skillnad från PROTECT är radering av det refererade objektet tillåtet om det också refererar till ett annat objekt som raderas i samma operation, men via en CASCADE-relation.

    Tänk på denna uppsättning modeller:

    class Artist(models.Model):
        name = models.CharField(max_length=10)
    
    
    class Album(models.Model):
        artist = models.ForeignKey(Artist, on_delete=models.CASCADE)
    
    
    class Song(models.Model):
        artist = models.ForeignKey(Artist, on_delete=models.CASCADE)
        album = models.ForeignKey(Album, on_delete=models.RESTRICT)
    

    Artist kan tas bort även om det innebär att ett Album som refereras av en Song måste tas bort, eftersom Song också refererar till Artist själv genom en kaskadrelation. Ett exempel:

    >>> artist_one = Artist.objects.create(name="artist one")
    >>> artist_two = Artist.objects.create(name="artist two")
    >>> album_one = Album.objects.create(artist=artist_one)
    >>> album_two = Album.objects.create(artist=artist_two)
    >>> song_one = Song.objects.create(artist=artist_one, album=album_one)
    >>> song_two = Song.objects.create(artist=artist_one, album=album_two)
    >>> album_one.delete()
    # Raises RestrictedError.
    >>> artist_two.delete()
    # Raises RestrictedError.
    >>> artist_one.delete()
    (4, {'Song': 2, 'Album': 1, 'Artist': 1})
    
  • SET_NULL[source]

    Ställ in ForeignKey null; detta är endast möjligt om null är True.

  • SET_DEFAULT[source]

    Sätt ForeignKey till dess standardvärde; en standard för ForeignKey måste anges.

  • SET()[source]

    Ställ in ForeignKey till det värde som skickades till SET(), eller om en callable skickas in, resultatet av att anropa den. I de flesta fall kommer det att vara nödvändigt att skicka en anropbar för att undvika att köra frågor när din models.py importeras:

    from django.conf import settings
    from django.contrib.auth import get_user_model
    from django.db import models
    
    
    def get_sentinel_user():
        return get_user_model().objects.get_or_create(username="deleted")[0]
    
    
    class MyModel(models.Model):
        user = models.ForeignKey(
            settings.AUTH_USER_MODEL,
            on_delete=models.SET(get_sentinel_user),
        )
    
  • DO_NOTHING[source]

    Vidta inga åtgärder. Om din databas backend tillämpar referentiell integritet kommer detta att orsaka en IntegrityError om du inte manuellt lägger till en SQL ON DELETE begränsning till databasfältet.

ForeignKey.limit_choices_to

Ställer in en gräns för de tillgängliga valen för detta fält när fältet återges med hjälp av en ModelForm eller administratören (som standard är alla objekt i frågeuppsättningen tillgängliga att välja). Antingen en ordbok, ett Q-objekt eller en callable som returnerar en ordbok eller ett Q-objekt kan användas.

Till exempel:

staff_member = models.ForeignKey(
    User,
    on_delete=models.CASCADE,
    limit_choices_to={"is_staff": True},
)

gör att motsvarande fält på ModelForm endast listar User-instanser som har is_staff=True. Detta kan vara till hjälp i Django admin.

Den anropsbara formen kan vara till hjälp, till exempel när den används tillsammans med Python-modulen datetime för att begränsa urval efter datumintervall. Till exempel:

def limit_pub_date_choices():
    return {"pub_date__lte": datetime.date.today()}


limit_choices_to = limit_pub_date_choices

Om limit_choices_to är eller returnerar ett Q-objekt, vilket är användbart för komplexa frågor, så kommer det bara att ha en effekt på de val som finns tillgängliga i admin när fältet inte är listat i raw_id_fields i ModelAdmin för modellen.

Observera

Om en callable används för limit_choices_to kommer den att anropas varje gång ett nytt formulär instansieras. Den kan också anropas när en modell valideras, t.ex. av hanteringskommandon eller administratören. Administratören konstruerar querysets för att validera sina formulärinmatningar i olika kantfall flera gånger, så det finns en möjlighet att din callable kan anropas flera gånger.

ForeignKey.related_name

Det namn som ska användas för relationen från det relaterade objektet tillbaka till detta. Det är också standardvärdet för related_query_name (det namn som ska användas för det omvända filternamnet från målmodellen). Se :ref:``related objects documentation <backwards-related-objects>` för en fullständig förklaring och exempel. Observera att du måste ange detta värde när du definierar relationer på abstrakta modeller; och när du gör det finns viss speciell syntax tillgänglig.

Om du föredrar att Django inte skapar en bakåtriktad relation, sätt related_name till '+' eller avsluta det med '+'. Till exempel: kommer detta att säkerställa att modellen User inte kommer att ha en bakåtriktad relation till denna modell:

user = models.ForeignKey(
    User,
    on_delete=models.CASCADE,
    related_name="+",
)
ForeignKey.related_query_name

Namnet som ska användas för det omvända filternamnet från målmodellen. Det är standardvärdet för related_name eller default_related_name om det är inställt, annars är det standardvärdet för namnet på modellen:

# Declare the ForeignKey with related_query_name
class Tag(models.Model):
    article = models.ForeignKey(
        Article,
        on_delete=models.CASCADE,
        related_name="tags",
        related_query_name="tag",
    )
    name = models.CharField(max_length=255)


# That's now the name of the reverse filter
Article.objects.filter(tag__name="important")

Precis som related_name stöder related_query_name interpolering av appetiketter och klasser via :ref:en speciell syntax <abstract-related-name>.

ForeignKey.to_field

Det fält på det relaterade objektet som relationen är till. Som standard använder Django primärnyckeln för det relaterade objektet. Om du refererar till ett annat fält måste det fältet ha unique=True.

ForeignKey.db_constraint

Styr om en begränsning ska skapas i databasen för den här främmande nyckeln eller inte. Standardvärdet är True, och det är nästan säkert vad du vill ha; att ställa in detta på False kan vara mycket dåligt för dataintegriteten. Som sagt, här är några scenarier där du kanske vill göra detta:

  • Du har äldre data som inte är giltiga.

  • Du shardar din databas.

Om detta är inställt på False kommer åtkomst till ett relaterat objekt som inte finns att ge upphov till dess DoesNotExist undantag.

ForeignKey.swappable

Styr migreringsramverkets reaktion om denna ForeignKey pekar på en utbytbar modell. Om det är True - standard - och om ForeignKey pekar på en modell som matchar det aktuella värdet för settings.AUTH_USER_MODEL (eller en annan inställning för en utbytbar modell) kommer relationen att lagras i migreringen med en referens till inställningen, inte direkt till modellen.

Du vill bara åsidosätta detta till ”False” om du är säker på att din modell alltid ska peka mot den inbytta modellen - till exempel om det är en profilmodell som är utformad specifikt för din anpassade användarmodell.

Om du ställer in den på False betyder det inte att du kan referera till en utbytbar modell även om den byts ut - False betyder att de migreringar som görs med denna ForeignKey alltid kommer att referera till exakt den modell du anger (så det kommer att misslyckas hårt om användaren försöker köra med en User-modell som du inte stöder, till exempel).

Om du är osäker, låt den vara inställd på standardvärdet True.

ManyToManyField

class ManyToManyField(to, **options)[source]

En relation mellan många och många. Kräver ett positionellt argument: den klass som modellen är relaterad till, vilket fungerar exakt som för ForeignKey, inklusive :ref:``recursive <recursive-relationships>` och lazy relationer.

Relaterade objekt kan läggas till, tas bort eller skapas med fältets RelatedManager.

Databasrepresentation

Bakom kulisserna skapar Django en mellanliggande join-tabell för att representera förhållandet många-till-många. Som standard genereras detta tabellnamn med hjälp av namnet på many-to-many-fältet och namnet på tabellen för den modell som innehåller det. Eftersom vissa databaser inte stöder tabellnamn över en viss längd kommer dessa tabellnamn att trunkeras automatiskt och en unik hash kommer att användas, t.ex. author_books_9cdf. Du kan manuellt ange namnet på join-tabellen med hjälp av alternativet db_table.

Argument

ManyToManyField accepterar en extra uppsättning argument - alla valfria - som styr hur relationen fungerar.

ManyToManyField.related_name

Samma som ForeignKey.related_name.

ManyToManyField.related_query_name

Samma som ForeignKey.related_query_name.

ManyToManyField.limit_choices_to

Samma som ForeignKey.limit_choices_to.

ManyToManyField.symmetrical

Används endast i definitionen av ManyToManyFields på self. Tänk på följande modell:

from django.db import models


class Person(models.Model):
    friends = models.ManyToManyField("self")

När Django bearbetar den här modellen identifierar den att den har en ManyToManyField på sig själv, och som ett resultat lägger den inte till ett person_set-attribut till Person-klassen. Istället antas ManyToManyField vara symmetrisk - det vill säga, om jag är din vän, då är du min vän.

Om du inte vill ha symmetri i många-till-många-relationer med själv, sätt symmetrical till False. Detta kommer att tvinga Django att lägga till beskrivningen för den omvända relationen, vilket gör att ManyToManyField-relationer kan vara icke-symmetriska.

ManyToManyField.through

Django kommer automatiskt att generera en tabell för att hantera många-till-många-relationer. Men om du vill ange den mellanliggande tabellen manuellt kan du använda alternativet through för att ange den Django-modell som representerar den mellanliggande tabell som du vill använda.

En genom-modell kan specificeras antingen med hjälp av modellklassen direkt eller med en :ref:lazy reference <lazy-relationships> till modellklassen.

Den vanligaste användningen av detta alternativ är när du vill associera extra data med en många-till-många-relation.

Observera

Rekursiva relationer som använder en mellanliggande modell kan inte bestämma de omvända accessorernas namn, eftersom de skulle vara desamma. Du måste ställa in en related_name till minst en av dem. Om du föredrar att Django inte skapar en baklängesrelation, sätt related_name till '+'`.

Ordning på främmande nycklar i intermediära modeller

När du definierar en asymmetrisk many-to-many-relation från en modell till sig själv med hjälp av en mellanliggande modell utan att definiera through_fields, kommer den första främmande nyckeln i den mellanliggande modellen att behandlas som att den representerar källsidan av ManyToManyField, och den andra som målsidan. Till exempel:

from django.db import models


class Manufacturer(models.Model):
    name = models.CharField(max_length=255)
    clients = models.ManyToManyField(
        "self", symmetrical=False, related_name="suppliers", through="Supply"
    )


class Supply(models.Model):
    supplier = models.ForeignKey(
        Manufacturer, models.CASCADE, related_name="supplies_given"
    )
    client = models.ForeignKey(
        Manufacturer, models.CASCADE, related_name="supplies_received"
    )
    product = models.CharField(max_length=255)

Här definierar modellen Manufacturer många-till-många-relationen med clients i sin roll som leverantör. Därför måste leverantörens främmande nyckel (källan) komma före klientens främmande nyckel (målet) i den mellanliggande Supply-modellen.

Om du anger through_fields=("supplier", "client")ManyToManyField blir ordningen på främmande nycklar i through-modellen irrelevant.

Om du inte anger en explicit through-modell finns det fortfarande en implicit through-modellklass som du kan använda för att få direkt åtkomst till den tabell som skapats för att innehålla associationen. Den har tre fält för att länka modellerna, en primärnyckel och två främmande nycklar. Det finns en unik begränsning på de två främmande nycklarna.

Om käll- och målmodellerna skiljer sig åt genereras följande fält:

  • id: relationens primärnyckel.

  • <containing_model>_id: id för den modell som deklarerar ManyToManyField.

  • <other_model>_id: id för den modell som ManyToManyField pekar på.

Om ManyToManyField pekar från och till samma modell, genereras följande fält:

  • id: relationens primärnyckel.

  • from_<model>_id``: id för den instans som pekar på modellen (dvs. källinstansen).

  • to<model>_id``: id för den instans som relationen pekar på (dvs. målmodellinstansen).

Denna klass kan användas för att fråga efter associerade poster för en viss modellinstans som en vanlig modell:

Model.m2mfield.through.objects.all()
ManyToManyField.through_fields

Används endast när en anpassad mellanliggande modell anges. Django kommer normalt att avgöra vilka fält i den mellanliggande modellen som ska användas för att automatiskt upprätta en många-till-många-relation. Tänk dock på följande modeller:

from django.db import models


class Person(models.Model):
    name = models.CharField(max_length=50)


class Group(models.Model):
    name = models.CharField(max_length=128)
    members = models.ManyToManyField(
        Person,
        through="Membership",
        through_fields=("group", "person"),
    )


class Membership(models.Model):
    group = models.ForeignKey(Group, on_delete=models.CASCADE)
    person = models.ForeignKey(Person, on_delete=models.CASCADE)
    inviter = models.ForeignKey(
        Person,
        on_delete=models.CASCADE,
        related_name="membership_invites",
    )
    invite_reason = models.CharField(max_length=64)

Membership har två främmande nycklar till Person (person och inviter), vilket gör förhållandet tvetydigt och Django kan inte veta vilken som ska användas. I det här fallet måste du uttryckligen ange vilka främmande nycklar Django ska använda med hjälp av through_fields, som i exemplet ovan.

through_fields accepterar en 2-tupel ('field1', 'field2'), där field1 är namnet på den främmande nyckeln till modellen som ManyToManyField definieras på (group i det här fallet), och field2 är namnet på den främmande nyckeln till målmodellen (person i det här fallet).

När du har mer än en främmande nyckel på en mellanliggande modell till någon (eller till och med båda) av de modeller som deltar i en många-till-många-relation, måste du måste ange through_fields. Detta gäller även :ref:recursive relationships <recursive-relationships> när en mellanliggande modell används och det finns mer än två främmande nycklar till modellen, eller om du uttryckligen vill ange vilka två Django ska använda.

ManyToManyField.db_table

Namnet på den tabell som ska skapas för att lagra data för många-till-många. Om detta inte anges kommer Django att anta ett standardnamn baserat på namnen på: tabellen för den modell som definierar relationen och namnet på själva fältet.

ManyToManyField.db_constraint

Styr om begränsningar ska skapas i databasen för de utländska nycklarna i den mellanliggande tabellen eller inte. Standardvärdet är True, och det är nästan säkert vad du vill ha; att ställa in detta på False kan vara mycket dåligt för dataintegriteten. Med detta sagt, här är några scenarier där du kanske vill göra detta:

  • Du har äldre data som inte är giltiga.

  • Du shardar din databas.

Det är ett fel att skicka både db_constraint och through.

ManyToManyField.swappable

Styr migreringsramverkets reaktion om denna ManyToManyField pekar på en utbytbar modell. Om det är True - standard - och om ManyToManyField pekar på en modell som matchar det aktuella värdet för settings.AUTH_USER_MODEL (eller en annan utbytbar modellinställning) kommer relationen att lagras i migreringen med en referens till inställningen, inte direkt till modellen.

Du vill bara åsidosätta detta till ”False” om du är säker på att din modell alltid ska peka mot den inbytta modellen - till exempel om det är en profilmodell som är utformad specifikt för din anpassade användarmodell.

Om du är osäker, låt den vara inställd på standardvärdet True.

ManyToManyField har inte stöd för validators.

null har ingen effekt eftersom det inte finns något sätt att kräva en relation på databasnivå.

OneToOneField

class OneToOneField(to, on_delete, parent_link=False, **options)[source]

Ett ett-till-ett-förhållande. Konceptuellt liknar detta en ForeignKey med unique=True, men den ”omvända” sidan av relationen kommer direkt att returnera ett enda objekt.

Detta är mest användbart som primärnyckel för en modell som ”utvidgar” en annan modell på något sätt; Arv från flera tabeller implementeras till exempel genom att lägga till en implicit en-till-en-relation från barnmodellen till föräldramodellen.

Ett positionellt argument krävs: den klass som modellen ska relateras till. Detta fungerar på exakt samma sätt som för ForeignKey, inklusive alla alternativ för :ref:``recursive <recursive-relationships>` och :ref:``lazy <lazy-relationships>` relationer.

Om du inte anger argumentet related_name för OneToOneField, kommer Django att använda den aktuella modellens namn med gemener som standardvärde.

Med följande exempel:

from django.conf import settings
from django.db import models


class MySpecialUser(models.Model):
    user = models.OneToOneField(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
    )
    supervisor = models.OneToOneField(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name="supervisor_of",
    )

din resulterande User-modell kommer att ha följande attribut:

>>> user = User.objects.get(pk=1)
>>> hasattr(user, "myspecialuser")
True
>>> hasattr(user, "supervisor_of")
True

Ett RelatedObjectDoesNotExist-undantag uppstår vid åtkomst till det omvända förhållandet om en post i den relaterade tabellen inte finns. Detta är en underklass av målmodellens Model.DoesNotExist undantag och kan nås som ett attribut för den omvända accessorn. Till exempel:, om en användare inte har en handledare som anges av MySpecialUser:

try:
    user.supervisor_of
except User.supervisor_of.RelatedObjectDoesNotExist:
    pass

Dessutom accepterar OneToOneField alla de extra argument som accepteras av ForeignKey, plus ett extra argument:

När True och används i en modell som ärver från en annan concrete model, anger att detta fält ska användas som länk tillbaka till moderklassen, snarare än det extra OneToOneField som normalt skulle skapas implicit genom subklassning.

Se One-to-one relationships för användningsexempel på OneToOneField.

Lata relationer

Lazy relationships gör det möjligt att referera till modeller med deras namn (som strängar) eller skapa rekursiva relationer. Strängar kan användas som första argument i alla relationsfält för att referera till modeller på ett latent sätt. En lat referens kan vara antingen recursive, relative eller absolute.

Rekursiv

Om du vill definiera en relation där en modell refererar till sig själv använder du "self" som första argument i relationsfältet:

from django.db import models


class Manufacturer(models.Model):
    name = models.TextField()
    suppliers = models.ManyToManyField("self", symmetrical=False)

När den används i en abstrakt modell, löses det rekursiva förhållandet så att varje konkret underklass refererar till sig själv.

Relativ

När en relation behöver skapas med en modell som ännu inte har definierats, kan den refereras till med sitt namn i stället för med själva modellobjektet:

from django.db import models


class Car(models.Model):
    manufacturer = models.ForeignKey(
        "Manufacturer",
        on_delete=models.CASCADE,
    )


class Manufacturer(models.Model):
    name = models.TextField()
    suppliers = models.ManyToManyField("self", symmetrical=False)

Relationer som definieras på detta sätt på abstrakta modeller löses när modellen underklassas som en konkret modell och är inte relativa till den abstrakta modellens app_label:

produkter/modeller.py
from django.db import models


class AbstractCar(models.Model):
    manufacturer = models.ForeignKey("Manufacturer", on_delete=models.CASCADE)

    class Meta:
        abstract = True
produktion/modeller.py
from django.db import models
from products.models import AbstractCar


class Manufacturer(models.Model):
    name = models.TextField()


class Car(AbstractCar):
    pass

I det här exemplet kommer relationen Car.manufacturer att lösas upp till production.Manufacturer, eftersom den pekar på den konkreta modell som definieras i filen production/models.py.

Återanvändbara modeller med relativa referenser

Relativa referenser gör det möjligt att skapa återanvändbara abstrakta modeller med relationer som kan leda till olika implementeringar av de refererade modellerna i olika subklasser i olika applikationer.

Absolut

Absoluta referenser specificerar en modell med hjälp av dess app_label och klassnamn, vilket möjliggör modellreferenser mellan olika applikationer. Denna typ av latent relation kan också hjälpa till att lösa cirkulär import.

Om t.ex. modellen Manufacturer definieras i en annan applikation som heter thirdpartyapp, kan den refereras som:

class Car(models.Model):
    manufacturer = models.ForeignKey(
        "thirdpartyapp.Manufacturer",
        on_delete=models.CASCADE,
    )

Absoluta referenser pekar alltid på samma modell, även när de används i en abstrakt modell.

API-referens för fält

class Field[source]

Field är en abstrakt klass som representerar en kolumn i en databastabell. Django använder fält för att skapa databastabellen (db_type()), för att mappa Python-typer till databasen (get_prep_value()) och vice versa (from_db_value()).

Ett fält är således en grundläggande del i olika Django API:er, i synnerhet models och querysets.

I modeller är ett fält instansierat som ett klassattribut och representerar en viss tabellkolumn, se Modeller. Det har attribut som null och unique, och metoder som Django använder för att mappa fältvärdet till databasspecifika värden.

En Field är en underklass av RegisterLookupMixin och därmed kan både Transform och Lookup` registreras på den för att användas i QuerySet (t.ex. field_name__exact="foo"). Alla :ref:inbyggda lookups <field-lookups> är registrerade som standard.

Alla Djangos inbyggda fält, till exempel CharField, är särskilda implementeringar av Field. Om du behöver ett anpassat fält kan du antingen subklassa något av de inbyggda fälten eller skriva ett Field från början. I båda fallen, se Så här skapar du anpassade modellfält.

description

En utförlig beskrivning av fältet, t.ex. för programmet django.contrib.admindocs.

Beskrivningen kan vara av formen:

description = _("String (up to %(max_length)s)")

där argumenten interpoleras från fältets __dict__.

descriptor_class

En klass som implementerar descriptor protocol som instansieras och tilldelas attributet för modellinstansen. Konstruktören måste acceptera ett enda argument, Field-instansen. Åsidosättande av detta klassattribut gör det möjligt att anpassa get- och set-beteendet.

För att mappa en Field till en databasspecifik typ, exponerar Django flera metoder:

get_internal_type()[source]

Returnerar en sträng som namnger detta fält för backend-specifika ändamål. Som standard returneras klassnamnet.

Se Emulering av inbyggda fälttyper för användning i anpassade fält.

db_type(connection)[source]

Returnerar databaskolumnens datatyp för Field, med hänsyn tagen till connection.

Se Anpassade databastyper för användning i anpassade fält.

rel_db_type(connection)[source]

Returnerar databasens kolumndatatyp för fält som ForeignKey och OneToOneField som pekar på Field, med hänsyn tagen till connection.

Se Anpassade databastyper för användning i anpassade fält.

Det finns tre huvudsakliga situationer där Django behöver interagera med databasens backend och fält:

  • när den frågar databasen (Python-värde -> databasens backend-värde)

  • när den laddar data från databasen (databasens backend-värde -> Python-värde)

  • när den sparar i databasen (Python-värde -> databasens backend-värde)

Vid frågor används get_db_prep_value() och get_prep_value():

get_prep_value(value)[source]

value är det aktuella värdet för modellens attribut och metoden ska returnera data i ett format som har förberetts för att användas som en parameter i en fråga.

Se Konvertera Python-objekt till frågevärden för användning.

get_db_prep_value(value, connection, prepared=False)[source]

Konverterar value till ett backend-specifikt värde. Som standard returnerar den value om prepared=True och get_prep_value() om är False.

Se Konvertering av frågevärden till databasvärden för användning.

Vid laddning av data används from_db_value():

from_db_value(value, expression, connection)

Konverterar ett värde som returneras av databasen till ett Python-objekt. Det är det omvända av get_prep_value().

Den här metoden används inte för de flesta inbyggda fält eftersom databasens backend redan returnerar rätt Python-typ, eller så gör backend själv konverteringen.

uttryck är detsamma som själv.

Se Konvertera värden till Python-objekt för användning.

Observera

Av prestandaskäl implementeras inte from_db_value som en no-op på fält som inte kräver det (alla Django-fält). Följaktligen får du inte anropa super i din definition.

När du sparar används pre_save() och get_db_prep_save():

get_db_prep_save(value, connection)[source]

Samma som get_db_prep_value(), men anropas när fältvärdet måste sparas till databasen. Som standard returneras get_db_prep_value().

pre_save(model_instance, add)[source]

Metod som anropas före get_db_prep_save() för att förbereda värdet innan det sparas (t.ex. för DateField.auto_now).

model_instance är den instans som detta fält tillhör och add är om instansen sparas i databasen för första gången.

Det bör returnera värdet på lämpligt attribut från model_instance för detta fält. Attributnamnet finns i self.attname (detta ställs in av Field).

Se Förbehandling av värden före lagring för användning.

Fält får ofta sina värden som en annan typ, antingen från serialisering eller från formulär.

to_python(value)[source]

Konverterar värdet till det korrekta Python-objektet. Det fungerar som det omvända av value_to_string(), och anropas också i clean().

Se Konvertera värden till Python-objekt för användning.

Förutom att spara i databasen måste fältet också veta hur det ska serialisera sitt värde:

value_from_object(obj)[source]

Returnerar fältets värde för den angivna modellinstansen.

Denna metod används ofta av value_to_string().

value_to_string(obj)[source]

Konverterar obj till en sträng. Används för att serialisera fältets värde.

Se Konvertering av fältdata för serialisering för användning.

När man använder model forms, måste Field veta vilket formulärfält den ska representeras av:

formfield(form_class=None, choices_form_class=None, **kwargs)[source]

Returnerar standard django.forms.Field för detta fält för ModelForm.

Om formfield() åsidosätts för att returnera None, utesluts detta fält från ModelForm.

Som standard, om både form_class och choices_form_class är None, används CharField. Om fältet har choices och choices_form_class inte är specificerat, används TypedChoiceField.

Se specificerande-form-fält-för-modell-fält för användning.

deconstruct()[source]

Returnerar en 4-tupel med tillräckligt med information för att återskapa fältet:

  1. Namnet på fältet i modellen.

  2. Importsökvägen för fältet (t.ex. "django.db.models.IntegerField"). Detta bör vara den mest portabla versionen, så mindre specifik kan vara bättre.

  3. En lista med positionella argument.

  4. En dikt av nyckelordsargument.

Denna metod måste läggas till fält före 1.7 för att migrera dess data med hjälp av Migreringar.

Registrering och hämtning av uppslagsord

Field implementerar :ref:lookup registration API <lookup-registration-api>. API:et kan användas för att anpassa vilka uppslagsord som är tillgängliga för en fältklass och dess instanser, och hur uppslagsord hämtas från ett fält.

Referens till fältattribut

Varje Field-instans innehåller flera attribut som gör det möjligt att introspektera dess beteende. Använd dessa attribut istället för isinstance-kontroller när du behöver skriva kod som är beroende av ett fälts funktionalitet. Dessa attribut kan användas tillsammans med Model._meta API för att begränsa en sökning efter specifika fälttyper. Anpassade modellfält bör implementera dessa flaggor.

Attribut för fält

Field.auto_created

Boolesk flagga som anger om fältet skapades automatiskt, t.ex. OneToOneField som används vid modellarv.

Field.concrete

Boolesk flagga som anger om fältet har en databaskolumn associerad med sig.

Field.hidden

Boolesk flagga som anger om ett fält är dolt och inte ska returneras av Options.get_fields() som standard. Ett exempel är det omvända fältet för en ForeignKey med ett related_name som börjar med '+'.

Field.is_relation

Boolesk flagga som anger om ett fält innehåller referenser till en eller flera andra modeller för dess funktionalitet (t.ex. ForeignKey, ManyToManyField, OneToOneField, etc.).

Field.model

Returnerar den modell som fältet är definierat för. Om ett fält definieras på en superklass av en modell, kommer model att hänvisa till superklassen, inte klassen för instansen.

Attribut för fält med relationer

Dessa attribut används för att fråga efter kardinalitet och andra detaljer i en relation. Dessa attribut finns på alla fält, men de har endast booleska värden (i stället för None) om fältet är en relationstyp (Field.is_relation=True).

Field.many_to_many

Boolesk flagga som är True om fältet har en many-to-many-relation; False annars. Det enda fältet som ingår i Django där detta är True är ManyToManyField.

Field.many_to_one

Boolesk flagga som är True om fältet har en många-till-en-relation, t.ex. en ForeignKey; annars False.

Field.one_to_many

Boolesk flagga som är True om fältet har en en-till-många-relation, t.ex. en GenericRelation eller motsatsen till en ForeignKey; annars False.

Field.one_to_one

Boolesk flagga som är True om fältet har en en-till-en-relation, t.ex. ett OneToOneField; annars False.

Field.related_model

Pekar på den modell som fältet hänför sig till. Till exempel: Author i ForeignKey(Author, on_delete=models.CASCADE). Den related_model för en GenericForeignKey är alltid None.