# Documentation Django 3.1.9.dev

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

`reverse`(viewname, urlconf=None, args=None, kwargs=None, current_app=None)

`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é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`

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

  `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>/'`.

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

`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 `"/"`.