Opened 10 years ago

Closed 10 years ago

Last modified 10 years ago

#21941 closed Cleanup/optimization (fixed)

document kwargs parameter to url()

Reported by: Chris Jerdonek Owned by: Tim Martin
Component: Documentation Version: 1.6
Severity: Normal Keywords: url, kwargs
Cc: chris.jerdonek@…, numerodix@…, Tim Martin Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

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.

Change History (11)

comment:1 by Chris Jerdonek, 10 years ago

Cc: chris.jerdonek@… added

comment:2 by Tim Graham, 10 years ago

Triage Stage: UnreviewedAccepted

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"?

comment:3 by Chris Jerdonek, 10 years ago

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

comment:4 by mkaurkhalsa@…, 10 years ago

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.

comment:5 by Martin Matusiak, 10 years ago

Cc: numerodix@… added

comment:6 by Tim Martin, 10 years ago

Cc: Tim Martin added
Has patch: set

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.

comment:7 by Tim Graham, 10 years ago

Patch needs improvement: set

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

comment:8 by Tim Martin, 10 years ago

Owner: changed from nobody to Tim Martin
Patch needs improvement: unset
Status: newassigned

I've updated the PR.

comment:9 by Tim Graham <timograham@…>, 10 years ago

Resolution: fixed
Status: assignedclosed

In a779757706b19ef244dc1ede2e1e992735461623:

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

Thanks cjerdonek for the report.

comment:10 by Tim Graham <timograham@…>, 10 years ago

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

comment:11 by Tim Graham <timograham@…>, 10 years ago

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

Note: See TracTickets for help on using tickets.
Back to Top