Fonctions utilitaires django.urls

reverse()

The reverse() function can be used to return an absolute path reference for a given view and optional parameters, similar to the url tag:

reverse(viewname, urlconf=None, args=None, kwargs=None, current_app=None, *, query=None, fragment=None)[source]

viewname can be a URL pattern name or the callable view object used in the URLconf. For example, given the following url:

from news import views

path("archive/", views.archive, name="news-archive")

vous pouvez utiliser indifféremment les appels suivants pour obtenir l’URL :

# using the named URL
reverse("news-archive")

# passing a callable object
# (This is discouraged because you can't reverse namespaced views this way.)
from news import views

reverse(views.archive)

Si l’URL accepte des paramètres, vous pouvez les transmettre dans args. par exemple :

from django.urls import reverse


def myview(request):
    return HttpResponseRedirect(reverse("arch-summary", args=[1945]))

Vous pouvez aussi transmettre kwargs au lieu de args. Par exemple :

>>> reverse("admin:app_list", kwargs={"app_label": "auth"})
'/admin/auth/'

Il n’est pas possible de passer à la fois args et kwargs à reverse().

Si aucune correspondance n’est trouvée, reverse() génère une exception NoReverseMatch.

La fonction reverse() peut résoudre une large palette de motifs d’expressions régulières correspondant à des URL, mais pas tous. La principale restriction actuellement est que le motif ne peut pas contenir différents choix possibles indiqués par la barre verticale ("|"). De tels motifs peuvent sans problème être utilisés pour résoudre des URL entrantes et faire appel à la vue correspondante, mais il n’est pas possible de les utiliser pour effectuer des résolutions inverses.

Le paramètre current_app vous permet de donner une indication au résolveur pour signaler l’application à laquelle appartient la vue en cours d’exécution. Ce paramètre current_app est employé comme indication pour résoudre des espaces de noms d’application en URL d’instances spécifiques d’application, en accord avec la stratégie de résolution d’URL avec espaces de noms.

Le paramètre urlconf est le module de configuration d’URL contenant les motifs d’URL à utiliser pour la résolution. Par défaut, la configuration d’URL racine du fil d’exécution en cours est utilisée.

The query keyword argument specifies parameters to be added to the returned URL. It can accept an instance of QueryDict (such as request.GET) or any value compatible with urllib.parse.urlencode(). The encoded query string is appended to the resolved URL, prefixed by a ?.

The fragment keyword argument specifies a fragment identifier to be appended to the returned URL (that is, after the path and query string, preceded by a #).

Par exemple :

>>> from django.urls import reverse
>>> reverse("admin:index", query={"q": "biscuits", "page": 2}, fragment="results")
'/admin/?q=biscuits&page=2#results'
>>> reverse("admin:index", query=[("color", "blue"), ("color", 1), ("none", None)])
'/admin/?color=blue&color=1&none=None'
>>> reverse("admin:index", query={"has empty spaces": "also has empty spaces!"})
'/admin/?has+empty+spaces=also+has+empty+spaces%21'
>>> reverse("admin:index", fragment="no encoding is done")
'/admin/#no encoding is done'

Changed in Django 5.2:

The query and fragment arguments were added.

Note

La chaîne d’URL renvoyée par reverse() est déjà échappée. Par exemple :

>>> reverse("cities", args=["Orléans"])
'.../Orl%C3%A9ans/'

Si vous appliquez d’autres codages (tel que urllib.parse.quote()) à la valeur renvoyée par reverse(), cela peut produire des résultats non désirés.

Reversing class-based views by view object

The view object can also be the result of calling as_view() if the same view object is used in the URLConf. Following the original example, the view object could be defined as:

news/views.py

 from django.views import View


 class ArchiveView(View): ...


 archive = ArchiveView.as_view()

However, remember that namespaced views cannot be reversed by view object.

reverse_lazy()

Une version de reverse() à exécution différée.

reverse_lazy(viewname, urlconf=None, args=None, kwargs=None, current_app=None, *, query=None, fragment=None)

Cette fonction est utile lorsque vous avez besoin de procéder à une résolution d’URL avant le chargement de la configuration des URL. Voici quelques cas fréquents d’utilisation de cette fonction :

• attribution d’une URL inversée comme attribut url d’une vue générique fondée sur les classes.

• attribution d’une URL inversée à un décorateur (comme pour le paramètre login_url du décorateur django.contrib.auth.decorators.permission_required()).

• attribution d’une URL inversée comme valeur par défaut d’un paramètre dans une signature de fonction.

Changed in Django 5.2:

The query and fragment arguments were added.

resolve()

La fonction resolve() peut être utilisée pour résoudre un chemin d’URL en sa fonction de vue correspondante. Sa signature est la suivante :

resolve(path, urlconf=None)[source]

path est le chemin d’URL à résoudre. Comme pour reverse(), il n’y a pas besoin de se préoccuper du paramètre urlconf. La focntion renvoie un objet ResolverMatch permettant d’accéder à diverses métadonnées au sujet de l’URL résolue.

Si l’URL n’est pas résolue, la fonction génère l’exception Resolver404 (qui est une sous-classe de Http404).

class ResolverMatch[source]

func

La fonction de vue qui aurait été utilisée pour servir l’URL.

args

Les paramètres qui auraient été transmis à la fonction de vue, tels qu’ils ont été extraits de l’URL.

kwargs

Tous les paramètres nommés qui ont été transmis à la fonction de vue, c’est-à-dire captured_kwargs et extra_kwargs.

captured_kwargs

Les paramètres nommés capturés qui auraient été transmis à la fonction de vue, tels qu’ils ont été extraits de l’URL.

extra_kwargs

Les paramètres nommés supplémentaires qui auraient été transmis à la fonction de vue.

url_name

Le nom du motif d’URL correspondant à l’URL.

route

La route du motif d’URL correspondant.

Par exemple, si path('users/<id>/', ...) set le motif de correspondance, route contiendra 'users/<id>/'.

tried

La liste des motifs d’URL essayés avant que l’URL ait trouvé une correspondance ou que tous les motifs aient été essayés.

app_name

L’espace de noms d’application pour le motif d’URL correspondant à l’URL.

app_names

La liste des composants d’espace de noms individuels dans l’espace de noms d’application complet du motif d’URL correspondant à l’URL. Si par exemple app_name contient foo:bar, alors app_names contiendra ['foo', 'bar'].

namespace

L’espace de noms d’instance pour le motif d’URL correspondant à l’URL.

namespaces

La liste des composants d’espace de noms individuels dans l’espace de noms d’instance complet du motif d’URL correspondant à l’URL. Si par exemple l’espace de noms est foo:bar, namespaces contiendra ['foo', 'bar'].

view_name

Le nom de la vue qui correspond à l’URL, y compris l’espace de noms s’il y en a un.

Un objet ResolverMatch peut ensuite être interrogé pour fournir des informations au sujet du motif d’URL correspondant à une URL :

# Resolve a URL
match = resolve("/some/path/")
# Print the URL pattern that matches the URL
print(match.url_name)

Un objet ResolverMatch peut aussi être attribué à une triplette :

func, args, kwargs = resolve("/some/path/")

L’une des utilisations possibles de resolve() pourrait être de tester si une vue produit une erreur Http404 avant de l’utiliser comme cible de redirection :

from urllib.parse import urlsplit
from django.urls import resolve
from django.http import Http404, HttpResponseRedirect


def myview(request):
    next = request.META.get("HTTP_REFERER", None) or "/"
    response = HttpResponseRedirect(next)

    # modify the request and response as required, e.g. change locale
    # and set corresponding locale cookie

    view, args, kwargs = resolve(urlsplit(next).path)
    kwargs["request"] = request
    try:
        view(*args, **kwargs)
    except Http404:
        return HttpResponseRedirect("/")
    return response

get_script_prefix()

get_script_prefix()[source]

Normalement, vous devriez toujours utiliser reverse() pour définir des URL dans votre application. Cependant, si l’application construit elle-même une partie de la hiérarchie des URL, il peut parfois être utile de produire soi-même des URL. Dans ce cas, il est nécessaire de pouvoir connaître l’URL de base du projet Django dans le contexte du serveur web (reverse() s’occupe en principe de le faire à votre place). Dans ce cas, vous pouvez appeler get_script_prefix(), qui renvoie la portion de préfixe de script des URL du projet Django. Si ce projet est placé à la racine de son serveur web, la valeur est toujours "/".

Avertissement

Cette fonction ne peut pas être utilisée en dehors du cycle requête-réponse car elle compte sur des valeurs initialisées durant ce cycle.