document kwargs parameter to url()

[Chris Jerdonek]

Currently, the documentation of the ​url() function does not document the kwargs parameter. This issue is to document that parameter. The documentation should be sure to cover the cases of both function views and class-based views.

I believe step (4) of the ​How Django processes a request section should also be updated in this regard:

"Once one of the regexes matches, Django imports and calls the given view, which is a simple Python function (or a class based view). The view gets passed an HttpRequest as its first argument and any values captured in the regex as remaining arguments."

I don't know if the kwargs parameter is documented somewhere else in the docs.

[Tim Graham]

For kwargs we could add a sentence about the usage and then link to ​this example.

Is the issue for the second point just that it should say something like "remaining arguments or keyword arguments"?

[Chris Jerdonek]

Is the issue for the second point just that it should say something like "remaining arguments or keyword arguments"?

That would be good to add, too (since regex groups can be named or not named). But the issue I was raising is that it doesn't mention also passing the values in kwargs. So it could say something along the lines of (also including your language), "The view gets passed an HttpRequest as its first argument and any values captured in the regex as remaining arguments or keyword arguments, combined with any extra arguments in the optional kwargs argument to url()."

[mkaurkhalsa@…]

The url function can be explained as

A convenient way to return the url pattern is url function :

url(regex, view, kwargs=None, name=None, prefix='')

Most of these are optional though. Lets demonstrate the use of all and few arguments in here

url(r'^index/$', index_view),
url(r'^index/$', index_view, name="main-view"),
url(r'^archive-summary/(\d{4})/$', archive, {'summary': True}, name="arch-summary"),
url(r'^archive-summary/(\d{4})/$', archive, {'summary': True}, name="arch-summary" prefix='myapp'),

• The first url function has mandatory arguments where a url pattern points to some view named index_view.
• It’s fairly common to use the same view function in multiple URL patterns in your URLconf. In those cases the second url function that is Naming URL Pattern(​https://docs.djangoproject.com/en/dev/topics/http/urls/#naming-url-patterns) is used.
• In third url function, kwarg argument is used. url function can take an other optional argument which should be a dictionary of extra keyword arguments to pass to the view function.(Refer : ​https://docs.djangoproject.com/en/dev/topics/http/urls/#passing-extra-options-to-view-functions )
• In the fourth url function prefix argument is used. When you name your URL patterns, make sure you use names that are unlikely to clash with any other application’s choice of names. If you call your URL pattern comment, and another application does the same thing, there’s no guarantee which URL will be inserted into your template when you use this name. Putting a prefix on your URL names, perhaps derived from the application name, will decrease the chances of collision. We recommend something like myapp-comment instead of comment.

[Tim Martin]

I've opened a pull request at ​https://github.com/django/django/pull/2480

I had some trouble figuring out the exact handling of the keyword arguments to the view function. I think I got it right in the end, but I had to make a few guesses based on the code. I found it was sufficiently complex to make it worth breaking out into a list of parameters rather than trying to explain it all in one sentence.

[Tim Graham]

Left comments for improvement on the PR. Please uncheck "patch needs improvement" when it's updated, thanks!

[Tim Martin]

I've updated the PR.

[Tim Graham <timograham@…>]

In a779757706b19ef244dc1ede2e1e992735461623:

Fixed #21941 -- Documented the kwargs param of django.conf.urls.url().

Thanks cjerdonek for the report.

[Tim Graham <timograham@…>]

In fe83cfe9eddae67838d453fa247bd47e1b3bf277:

[1.6.x] Fixed #21941 -- Documented the kwargs param of django.conf.urls.url().

Thanks cjerdonek for the report.

Backport of a779757706 from master

[Tim Graham <timograham@…>]

In e2e773c04abeab04866eac14c0040ef3aa653e1b:

[1.7.x] Fixed #21941 -- Documented the kwargs param of django.conf.urls.url().

Thanks cjerdonek for the report.

Backport of a779757706 from master