Django 5.1 release notes

7 augusti 2024

Välkommen till Django 5.1!

Dessa release notes täcker nya funktioner, samt några bakåtkompatibla förändringar som du bör vara medveten om när du uppgraderar från Django 5.0 eller tidigare. Vi har börjat utfasningsprocessen för vissa funktioner.

Se guiden Så här uppgraderar du Django till en nyare version om du ska uppdatera ett befintligt projekt.

Kompatibilitet med Python

Django 5.1 stöder Python 3.10, 3.11, 3.12 och 3.13 (från och med 5.1.3). Vi rekommenderar starkt och stöder endast officiellt den senaste utgåvan av varje serie.

Vad är nytt i Django 5.1

{% frågestring %} mall tagg

Django 5.1 introducerar {% querystring %}, vilket förenklar modifieringen av frågeparametrar i webbadresser, vilket gör det lättare att generera länkar som behåller befintliga frågeparametrar samtidigt som de lägger till eller ändrar specifika parametrar.

Det kan t.ex. vara besvärligt att navigera mellan paginering och frågesträngar i mallar. Tänk på det här mallfragmentet som dynamiskt genererar en URL för att navigera till nästa sida i en paginerad vy:

{# Linebreaks added for readability, this should be one, long line. #}
<a href="?{% for key, values in request.GET.iterlists %}
  {% if key != "page" %}
    {% for value in values %}
      {{ key }}={{ value }}&amp;
    {% endfor %}
  {% endif %}
{% endfor %}page={{ page.next_page_number }}">Next page</a>

När du byter till att använda denna nya malltagg blir ovanstående magiskt:

<a href="{% querystring page=page.next_page_number %}">Next page</a>

PostgreSQL anslutningspooler

Django 5.1 introducerar också :ref:connection pool <postgresql-pool> stöd för PostgreSQL. Eftersom tiden för att upprätta en ny anslutning kan vara relativt lång kan det minska latensen att hålla anslutningar öppna.

För att använda en anslutningspool med psycopg kan du ställa in alternativet "pool" i OPTIONS till att vara en dict som ska skickas till ConnectionPool, eller till True för att använda ConnectionPool standardvärden:

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        # ...
        "OPTIONS": {
            "pool": {
                "min_size": 2,
                "max_size": 4,
                "timeout": 10,
            }
        },
    },
}

Middleware kräver autentisering som standard

Den nya LoginRequiredMiddleware omdirigerar alla oautentiserade förfrågningar till en inloggningssida. Vyer kan tillåta oautentiserade förfrågningar genom att använda den nya login_not_required() dekoratorn.

LoginRequiredMiddleware respekterar värdena login_url och redirect_field_name som anges via login_required()-dekoratorn, men stöder inte inställning av login_url eller redirect_field_name via LoginRequiredMixin.

För att aktivera detta, lägg till "django.contrib.auth.middleware.LoginRequiredMiddleware" till din MIDDLEWARE inställning.

Mindre funktioner

django.contrib.admin

• ModelAdmin.list_display stöder nu användning av __-uppslagningar för att lista fält från relaterade modeller.

django.contrib.auth

• Standardantalet iterationer för PBKDF2-lösenordshashen ökas från 720.000 till 870.000.

• Standardvärdet för parallelism för ScryptPasswordHasher har ökats från 1 till 5 för att följa OWASP:s rekommendationer.

• Den nya AdminUserCreationForm och den befintliga AdminPasswordChangeForm stöder nu inaktivering av lösenordsbaserad autentisering genom att ange ett oanvändbart lösenord när formuläret sparas. Detta är nu tillgängligt i admin när du besöker sidorna för skapande av användare och lösenordsändring.

• dekoratorerna login_required(), permission_required() och user_passes_test() stöder nu omslag av asynkrona vyfunktioner.

• ReadOnlyPasswordHashWidget innehåller nu en knapp för att återställa användarens lösenord, som ersätter den länk som tidigare var inbäddad i ReadOnlyPasswordHashField hjälptext, vilket förbättrar den övergripande tillgängligheten för UserChangeForm.

django.contrib.gis

• BoundingCircle stöds nu på SpatiaLite 5.1+.

• Collect stöds nu på MySQL 8.0.24+.

• GeoIP2 tillåter nu frågor som använder ipaddress.IPv4Address eller ipaddress.IPv6Address objekt.

• GeoIP2.country() exponerar nu värdena continent_code, continent_name och is_in_european_union.

• GeoIP2.city() exponerar nu värdena accuracy_radius och region_name. Dessutom exponeras värdena dma_code och region nu som metro_code och region_code, men de tidigare nycklarna behålls också för bakåtkompatibilitet.

• Area har nu stöd för enheten ha.

• Det nya attributet OGRGeometry.is_3d gör det möjligt att kontrollera om en geometri har en Z koordinatdimension.

• Den nya metoden OGRGeometry.set_3d() gör det möjligt att lägga till och ta bort koordinatdimensionen Z.

• OGRGeometry, Point, LineString, Polygon och GeometryCollection och dess underklasser stöder nu uppmätta geometrier via de nya egenskaperna OGRGeometry.is_measured och m, och metoden OGRGeometry.set_measured().

• OGRGeometry.centroid är nu tillgänglig för alla geometrityper som stöds.

• funktionerna FromWKB() och FromWKT() stöder nu det valfria argumentet srid (utom för Oracle där det ignoreras).

django.contrib.postgres

• BTreeIndex har nu stöd för parametern deduplicate_items.

django.contrib.sessions

• django.contrib.sessions.backends.cached_db.SessionStore hanterar nu undantag när sessionsinformation lagras i cacheminnet, och loggar korrekta felmeddelanden med deras traceback via den nyligen tillagda sessions logger.

• django.contrib.sessions.backends.base.SessionBase och alla inbyggda sessionsmotorer tillhandahåller nu asynkrona API. De nya asynkrona metoderna har alla namn med prefixet a, t.ex. aget(), akeys() eller acycle_key().

Databas backends

• alternativet "init_command" stöds nu i OPTIONS på SQLite för att möjliggöra specificering av pragma options att ställa in vid anslutning.

• alternativet "transaction_mode" stöds nu i OPTIONS på SQLite för att möjliggöra specificering av Transaktionsbeteende.

• alternativet `` ”pool” `` stöds nu i OPTIONS på PostgreSQL för att tillåta användning av connection pools.

Felrapportering

• För att förbättra tillgängligheten använder de tekniska 404- och 500-felsidorna nu HTML-landmärkeselement för sidhuvud, sidfot och huvudinnehåll.

Fil delning

• Parametern allow_overwrite i FileSystemStorage tillåter nu att nya filer sparas över befintliga.

Formulär

• För att förbättra tillgängligheten och göra det möjligt för skärmläsare att associera fältuppsättningar med hjälptexten innehåller formulärfältuppsättningen nu HTML-attributet ”aria-describedby”.

Kommandon för hantering

• Kommandot makemigrations visar nu meningsfulla symboler för varje operation för att markera operation categories.

Migreringar

• Det nya attributet Operation.category gör det möjligt att ange en operationskategori som används av makemigrations för att visa en meningsfull symbol för operationen.

Modeller

• QuerySet.explain() stöder nu alternativet `` generic_plan`` på PostgreSQL 16+.

• RowRange accepterar nu positiva heltal för start-argumentet och negativa heltal för slut-argumentet.

• Det nya argumentet exclusion i RowRange och ValueRange gör det möjligt att utesluta rader, grupper och band från fönsterramarna.

• QuerySet.order_by() stöder nu beställning av annotationstransformationer som JSONObject-nycklar och ArrayAgg-index.

• F() och OuterRef() uttryck som ger ut CharField, EmailField, SlugField, URLField, TextField, eller ArrayField kan nu sliced.

• Det nya argumentet from_queryset i Model.refresh_from_db() och Model.arefresh_from_db() gör det möjligt att anpassa den queryset som används för att ladda om en modells värde. Detta kan användas för att låsa raden innan den laddas om eller för att välja relaterade objekt.

• Det nya attributet Expression.constraint_validation_compatible gör det möjligt att ange att uttrycket ska ignoreras under en constraint-validering.

Mallar

• Anpassade taggar kan nu ange extra data på objektet Parser som senare kommer att göras tillgängliga på instansen Template. Sådana data kan användas av t.ex. mallladdaren eller andra mallklienter.

• :ref:Template engines <field-checking>` implementerar nu en ``check()-metod som redan är registrerad med check-ramverket.

Tester

• assertContains(), assertNotContains() och assertInHTML() lägger nu till höstackar i felmeddelanden för påståenden.

• Klasserna RequestFactory, AsyncRequestFactory, Client och AsyncClient har nu stöd för parametern query_params, som accepterar en ordbok med nycklar och värden för frågesträngar. Detta gör det lättare att ställa in frågesträngar på alla HTTP-metoder.

  self.client.post("/items/1", query_params={"action": "delete"})
  await self.async_client.post("/items/1", query_params={"action": "delete"})
  

• Den nya SimpleTestCase.assertNotInHTML()-assertionen gör det möjligt att testa att ett HTML-fragment inte finns i den givna HTML-höbacken.

• För att upprätthålla testisolering är databasanslutningar i trådar inte längre tillåtna i SimpleTestCase.

Validerare

• Den nya DomainNameValidator validerar domännamn, inklusive internationaliserade domännamn. Den nya funktionen validate_domain_name() returnerar en instans av DomainNameValidator.

Bakåtkompatibla ändringar i 5.1

django.contrib.gis

• Stöd för PostGIS 2.5 har tagits bort.

• Stöd för PROJ < 6 har tagits bort.

• Stöd för GDAL 2.4 har tagits bort.

• GeoIP2 öppnar inte längre både stads- och landsdatabaser när en katalogväg anges, utan föredrar stadsdatabasen om den är tillgänglig. Landsdatabasen är en delmängd av stadsdatabasen och båda behövs normalt inte. Om du behöver använda landsdatabasen när den finns i samma katalog som stadsdatabasen, ska du uttryckligen skicka sökvägen till landsdatabasen till konstruktören.

Upphört stöd för MariaDB 10.4

Uppströmsstöd för MariaDB 10.4 upphör i juni 2024. Django 5.1 stöder MariaDB 10.5 och senare.

Slopat stöd för PostgreSQL 12

Uppströmsstöd för PostgreSQL 12 slutar i november 2024. Django 5.1 stöder PostgreSQL 13 och högre.

Diverse

• För att förbättra tillgängligheten återges nu administratörens filter för ändringslistan i en tagg av typen <nav> istället för <div>.

• För att förbättra tillgängligheten återges admins sidfot nu i en ”<footer>”-tagg i stället för en ”<div>”-tagg, och den har också flyttats under ”<div id=”main”>”-elementet.

• För att förbättra tillgängligheten innehåller den expanderbara widget som används för ModelAdmin.fieldsets och InlineModelAdmin.fieldsets, när fieldsetet har ett namn och använder klassen collapse, nu elementen <details> och <summary>.

• JavaScript-filen collapse.js tas bort eftersom den inte längre behövs på Django-adminsidan.

• SimpleTestCase.assertURLEqual() och assertInHTML() lägger nu till ": " till msg_prefix. Detta överensstämmer med beteendet hos andra påståenden.

• django.utils.text.Truncator som används av truncatechars_html och truncatewords_html mallfilter använder nu html.parser.HTMLParser subklasser. Detta resulterar i en mer robust och snabbare operation, men det kan finnas små skillnader i utdata.

• Den odokumenterade funktionen django.urls.converters.get_converter() har tagits bort.

• Den lägsta versionen av SQLite som stöds har ökats från 3.27.0 till 3.31.0.

• FileField ger nu upphov till ett FieldError när man sparar en fil utan namn.

• ImageField.update_dimension_fields(force=True) anropas inte längre efter att bilden har sparats i lagringsutrymmet. Om din lagringsbackend ändrar storlek på bilder kommer width_field och height_field inte att matcha bildens bredd och höjd.

• Den lägsta versionen av asgiref som stöds har ökats från 3.7.0 till 3.8.1.

• För att förbättra prestandan använder admin-åtgärden delete_selected nu QuerySet.bulk_create() när flera LogEntry-objekt skapas. Som ett resultat skickas inte signalerna pre_save och post_save för LogEntry när flera objekt tas bort via denna admin-åtgärd.

Funktioner som inte längre är aktuella i 5.1

Diverse

• Metoderna ModelAdmin.log_deletion() och LogEntryManager.log_action() är föråldrade. Underklasser bör implementera ModelAdmin.log_deletions() och LogEntryManager.log_actions() istället.

• Den odokumenterade funktionen django.utils.itercompat.is_iterable() och modulen django.utils.itercompat är föråldrade. Använd isinstance(..., collections.abc.Iterable) istället.

• Metoden django.contrib.gis.geoip2.GeoIP2.coords() är föråldrad. Använd django.contrib.gis.geoip2.GeoIP2.lon_lat() istället.

• Metoden django.contrib.gis.geoip2.GeoIP2.open() är föråldrad. Använd GeoIP2-konstruktören istället.

• Att skicka positionella argument till Model.save() och Model.asave() är föråldrat till förmån för argument som endast innehåller nyckelord.

• Inställningen django.contrib.gis.gdal.OGRGeometry.coord_dim är föråldrad. Använd set_3d() istället.

• Att åsidosätta befintliga omvandlare med django.urls.register_converter() är föråldrat.

• Nyckelordsargumentet check i CheckConstraint är avfört till förmån för condition.

• Den odokumenterade egenskapen OS_OPEN_FLAGS i FileSystemStorage är föråldrad. För att tillåta överskrivning av filer i lagring, ställ in det nya allow_overwrite-alternativet till True istället.

• Metoden get_cache_name() i FieldCacheMixin är utfasad till förmån för den cachade egenskapen cache_name.

Funktioner borttagna i 5.1

Dessa funktioner har nått slutet av sin utfasningscykel och tas bort i Django 5.1.

Se Funktioner som inte längre är aktuella i 4.2 för detaljer om dessa ändringar, inklusive hur man tar bort användningen av dessa funktioner.

• Metoden BaseUserManager.make_random_password() har tagits bort.

• Modellens alternativ Meta.index_together tas bort.

• Mallfiltret length_is har tagits bort.

• django.contrib.auth.hashers.SHA1PasswordHasher, django.contrib.auth.hashers.UnsaltedSHA1PasswordHasher och django.contrib.auth.hashers.UnsaltedMD5PasswordHasher tas bort.

• Modellerna django.contrib.postgres.fields.CICharField, django.contrib.postgres.fields.CIEmailField och django.contrib.postgres.fields.CITextField tas bort, förutom för stöd i historiska migreringar.

• Mixinen django.contrib.postgres.fields.CIText är borttagen.

• Attributen map_width och map_height för BaseGeometryWidget tas bort.

• Metoden SimpleTestCase.assertFormsetError() har tagits bort.

• Metoden TransactionTestCase.assertQuerysetEqual() har tagits bort.

• Stöd för att skicka kodade JSON-stränglitteraler till JSONField och tillhörande uppslagningar och uttryck har tagits bort.

• Stöd för att skicka positionella argument till Signer och TimestampSigner har tagits bort.

• Inställningarna DEFAULT_FILE_STORAGE och STATICFILES_STORAGE tas bort.

• Funktionen django.core.files.storage.get_storage_class() har tagits bort.