Removed docs for @permalink decorator.

    are using unicode strings containing characters outside the ASCII range at

    all.

The ``permalink`` decorator

~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. warning::

    The ``permalink`` decorator is no longer recommended. You should use

    :func:`~django.core.urlresolvers.reverse` in the body of your

    ``get_absolute_url`` method instead.

In early versions of Django, there wasn't an easy way to use URLs defined in

URLconf file inside :meth:`~django.db.models.Model.get_absolute_url`. That

meant you would need to define the URL both in URLConf and

:meth:`~django.db.models.Model.get_absolute_url`. The ``permalink`` decorator

was added to overcome this DRY principle violation. However, since the

introduction of :func:`~django.core.urlresolvers.reverse` there is no

reason to use ``permalink`` any more.

.. function:: permalink()

This decorator takes the name of a URL pattern (either a view name or a URL

pattern name) and a list of position or keyword arguments and uses the URLconf

patterns to construct the correct, full URL. It returns a string for the

correct URL, with all parameters substituted in the correct positions.

The ``permalink`` decorator is a Python-level equivalent to the :ttag:`url`

template tag and a high-level wrapper for the

:func:`~django.core.urlresolvers.reverse` function.

An example should make it clear how to use ``permalink()``. Suppose your URLconf

contains a line such as::

    (r'^people/([0-9]+)/$', 'people.views.details'),

...your model could have a :meth:`~django.db.models.Model.get_absolute_url`

method that looked like this::

    from django.db import models

    @models.permalink

    def get_absolute_url(self):

        return ('people.views.details', [str(self.id)])

Similarly, if you had a URLconf entry that looked like::

    (r'/archive/(?P<year>[0-9]{4})/(?P<month>[0-9]{2})/(?P<day>[0-9]{2})/$', archive_view)

...you could reference this using ``permalink()`` as follows::

    @models.permalink

    def get_absolute_url(self):

        return ('archive_view', (), {

            'year': self.created.year,

            'month': self.created.strftime('%m'),

            'day': self.created.strftime('%d')})

Notice that we specify an empty sequence for the second parameter in this case,

because we only want to pass keyword parameters, not positional ones.

In this way, you're associating the model's absolute path with the view that is

used to display it, without repeating the view's URL information anywhere. You

can still use the :meth:`~django.db.models.Model.get_absolute_url()` method in

templates, as before.

In some cases, such as the use of generic views or the re-use of custom views

for multiple models, specifying the view function may confuse the reverse URL

matcher (because multiple patterns point to the same view). For that case,

Django has :ref:`named URL patterns <naming-url-patterns>`. Using a named URL

pattern, it's possible to give a name to a pattern, and then reference the name

rather than the view function. A named URL pattern is defined by replacing the

pattern tuple by a call to the ``url`` function)::

    from django.conf.urls import url

    url(r'^people/([0-9]+)/$', 'blog_views.generic_detail', name='people_view'),

...and then using that name to perform the reverse URL resolution instead

of the view name::

    from django.db import models

    @models.permalink

    def get_absolute_url(self):

        return ('people_view', [str(self.id)])

More details on named URL patterns are in the :doc:`URL dispatch documentation

</topics/http/urls>`.

Extra instance methods

======================