# Documentation Django 6.0.7

# Fonctions utilitaires `django.urls`

## `reverse()`

La fonction `reverse()` peut être utilisée pour renvoyer un chemin absolut pour une vue donnée et ses paramètres facultatifs, de la même façon que la balise `url`:

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

`viewname` peut être un nom de motif d’URL ou l’objet de vue lui-même utilisé dans la configuration des URL. 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.

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'

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

Cependant, rappelez-vous que les vues avec espace de noms ne peuvent pas être inversées à partir de l’objet vue.

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

## `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)

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

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.