djangodocs

Django 6.1
Svenska
Documentation contents

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.

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).

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.

val

Field.choices

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:

Code
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:

Code
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:

Code
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:

Code
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:

Code
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:

Code
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.

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.

Unless blank=False is set on the field along with a default then a label containing "- Select an option -" will be rendered with the select box. To override this behavior, add a tuple to choices containing None; e.g. (None, 'Your String For Display'). Alternatively, you can use an empty string instead of None where this makes sense - such as on a CharField.

Uppräkningstyper

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

Code
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 ett exempel på underklassning av val med en mer komplex datatyp. Om en tupel inte tillhandahålls, eller om det sista objektet inte är en (lat) sträng, är label automatiskt genererad 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.

  • The use of enum.unique() is enforced to ensure that values cannot be defined multiple times. This is unlikely to be expected in choices for a field.

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):

Python console
>>> 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:

Code
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:

Python console
>>> 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:

Code
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 namngivna grupper.

  • 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:

    Code
    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:

Code
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:

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

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

Code
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:

Code
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.

db_tablespace

Field.db_tablespace

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:

Code
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

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:

Code
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.

The primary key field is set to None when calling a model instance’s delete() method.

unique

Field.unique

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 current time zone vid den tidpunkt då objektet sparas.

This is enforced by Model.validate_unique() during model validation but not at the database level. If any unique_for_date constraint involves fields that are not part of a ModelForm (for example, if one of the fields is listed in exclude or has editable=False), Model.validate_unique() will skip validation for that particular constraint.

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

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)

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)

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)

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)

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.

BooleanField

class BooleanField(**options)

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

class CompositePrimaryKey(*field_names, **options)

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)

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.

CharField.db_collation

Valfritt. Databasens kollationsnamn för fältet.

DateField

class DateField(auto_now=False, auto_now_add=False, **options)

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.

DatumTimeField

class DateTimeField(auto_now=False, auto_now_add=False, **options)

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.

DecimalField

class DecimalField(max_digits=None, decimal_places=None, **options)

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

Has the following arguments:

DecimalField.max_digits

The maximum number of digits allowed in the number. Note that this number must be greater than or equal to decimal_places. It’s always required on MySQL because this database doesn’t support numeric fields with no precision. It’s also required for all database backends when decimal_places is provided.

DecimalField.decimal_places

The number of decimal places to store with the number. It’s always required on MySQL because this database doesn’t support numeric fields with no precision. It’s also required for all database backends when max_digits is provided.

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

Code
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:

Code
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.

DurationField

class DurationField(**options)

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.

EmailField

class EmailField(max_length=254, **options)

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)

Ett fält för filuppladdning.

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:

Code
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:

Code
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.

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

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:

FieldFile.name

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

FieldFile.path

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

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

FieldFile.url

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')

Ö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()

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

FieldFile.save(name, content, save=True)

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.

Takes two required arguments: name which is the name of the file, and content which is an object containing the file’s contents. The optional save argument controls whether or not the model instance is saved after the file associated with this field has been altered. Defaults to 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:

Code
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:

Code
from django.core.files.base import ContentFile

myfile = ContentFile("hello world")

För mer information, se Hantera filer.

FieldFile.delete(save=True)

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)

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:

Code
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

Optional. Either True or False. Default is True. Specifies whether files in the specified location should be included. Either this or allow_folders must be True.

FilePathField.allow_folders

Optional. Either True or False. Default is False. Specifies whether folders in the specified location should be included. Either this or allow_files must be 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:

Code
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)

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.

GeneratedField

class GeneratedField(*, expression, output_field, db_persist, **kwargs)

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 < 18 only supports persisted columns. Oracle < 23ai/26ai (23.7) only supports virtual columns.

null has no effect on GeneratedField since whether the column is nullable depends on the database and expression used.

GenericIPAddressField

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

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)

Ä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)

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)

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

An optional json.JSONEncoder subclass to serialize data types not supported by the standard JSON serializer (e.g. datetime.datetime or UUID). For example, you can use the DjangoJSONEncoder class.

Standardvärdet är json.JSONEncoder.

JSONField.decoder

An optional json.JSONDecoder subclass to deserialize the value retrieved from the database. The value will be in the format chosen by the custom encoder (most often a string). Your deserialization may need to account for the fact that you can’t be certain of the input type. For example, you run the risk of returning a datetime that was actually a string that just happened to be in the same format chosen for datetimes.

Standardvärdet är json.JSONDecoder.

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

PositivBigIntegerField

class PositiveBigIntegerField(**options)

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)

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)

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)

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.

It is often useful to automatically prepopulate a SlugField based on the value of some other value. You can do this automatically in the admin using 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)

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)

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)

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.

TimeField

class TimeField(auto_now=False, auto_now_add=False, **options)

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)

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)

A field for storing universally unique identifiers. Uses Python’s UUID class. When used on PostgreSQL and MariaDB, this stores in a uuid datatype, otherwise in a 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:

Code
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.

Relationsfält

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

ForeignKey

class ForeignKey(to, on_delete, **options)

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

Code
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.

A database index is automatically created on the ForeignKey. You can disable this by setting db_index to False. You may want to avoid the overhead of an index if you are creating a foreign key for consistency rather than joins, or if you will be creating an alternative index like a partial or multiple column index.

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

When an object referenced by a ForeignKey is deleted, the referring objects need updating. The on_delete argument specifies how this is done, and whether Django or your database makes the updates. For example, if you have a nullable ForeignKey and you want Django to set it to None when the referenced object is deleted:

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

The possible values for on_delete are listed below. Import them from django.db.models. The DB_* variants use the database to prevent deletions or update referring objects, whilst the other values make Django perform the relevant actions.

The database variants are more efficient because they avoid fetching related objects, but pre_delete and post_delete signals won’t be sent when DB_CASCADE is used.

The database variants cannot be mixed with Python variants (other than DO_NOTHING) in the same model and in models related to each other.

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

  • CASCADE

    Cascade raderar. Django emulerar beteendet hos SQL-begränsningen ON DELETE CASCADE och raderar även 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.

  • DB_CASCADE

    Cascade deletes. Database-level version of CASCADE: the database deletes referred-to rows and the one containing the ForeignKey.

  • PROTECT

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

  • RESTRICT

    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:

    Code
    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:

    Python console
    >>> 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

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

  • DB_SET_NULL

    Set the ForeignKey value to NULL. This is only possible if null is True. Database-level version of SET_NULL.

  • SET_DEFAULT

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

  • DB_SET_DEFAULT

    Set the ForeignKey value to its Field.db_default value, which must be set. If a row in the referenced table is deleted, the foreign key values in the referencing table will be updated to their Field.db_default values.

    DB_SET_DEFAULT is not supported on MySQL and MariaDB.

  • SET()

    Set the ForeignKey to the value passed to SET(), or if a callable is passed in, the result of calling it. In most cases, passing a callable will be necessary to avoid executing queries at the time your models.py is imported:

    Code
    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

    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:

Code
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:

Code
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.

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 related objects documentation 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:

Code
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:

Code
# 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 en speciell syntax.

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.

Att ställa in den på False betyder inte att du kan referera till en utbytbar modell även om den byts ut - False betyder att migrationerna som görs med denna ForeignKey alltid kommer att referera till exakt den modell du anger (så det kommer att misslyckas 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)

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 recursive 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:

Code
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 lazy reference 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.

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:

Code
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:

Code
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 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)

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 recursive och lazy 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:

Code
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:

Python console
>>> 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:

Code
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:

Code
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:

Code
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
Python
from django.db import models


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

    class Meta:
        abstract = True
produktion/modeller.py
Python
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.

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:

Code
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

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()).

A field is thus a fundamental piece in different Django APIs, notably the Model and the QuerySet APIs.

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 inbyggda 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:

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

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

descriptor_class

A class implementing the descriptor protocol that is instantiated and assigned to the model instance attribute. The constructor must accept a single argument, the Field instance. Overriding this class attribute allows for customizing the get and set behavior.

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

get_internal_type()

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)

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)

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)

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)

Converts value to a backend-specific value. By default it returns value if prepared=True, and get_prep_value(value) otherwise.

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.

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

get_db_prep_save(value, connection)

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)

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)

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)

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

Denna metod används ofta av value_to_string().

value_to_string(obj)

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.

When using model forms, the Field needs to know which form field it should be represented by:

formfield(form_class=None, choices_form_class=None, **kwargs)

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()

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 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.

View as Markdown View as JSON Edit this page on GitHub Official version