Fonctions utilitaires django.urls
¶
reverse()
¶
Si vous avez besoin d’utiliser quelque chose de semblable à la balise de gabarit url
dans votre code, Django fournit la fonction suivante :
viewname
peut être un nom de motif d’URL ou l’objet de vue lui-même. Par exemple, étant donné l”url
suivante :
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.
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.
reverse_lazy()
¶
Une version de reverse() à exécution différée.
-
reverse_lazy
(viewname, urlconf=None, args=None, kwargs=None, current_app=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écorateurdjango.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.
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 :
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
etextra_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
contientfoo:bar
, alorsapp_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 urlparse
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(urlparse(next)[2])
kwargs["request"] = request
try:
view(*args, **kwargs)
except Http404:
return HttpResponseRedirect("/")
return response
get_script_prefix()
¶
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.