Opened 18 months ago

Closed 16 months ago

Last modified 16 months ago

#21941 closed Cleanup/optimization (fixed)

document kwargs parameter to url()

Reported by: cjerdonek Owned by: timmartin
Component: Documentation Version: 1.6
Severity: Normal Keywords: url, kwargs
Cc: chris.jerdonek@…, numerodix@…, timmartin 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 Changed 18 months ago by cjerdonek

  • Cc chris.jerdonek@… added
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

comment:2 Changed 18 months ago by timo

  • Triage Stage changed from Unreviewed to Accepted

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 Changed 18 months ago by cjerdonek

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 Changed 18 months ago by 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.

comment:5 Changed 17 months ago by numerodix

  • Cc numerodix@… added

comment:6 Changed 16 months ago by timmartin

  • Cc timmartin 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 Changed 16 months ago by timo

  • Patch needs improvement set

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

comment:8 Changed 16 months ago by timmartin

  • Owner changed from nobody to timmartin
  • Patch needs improvement unset
  • Status changed from new to assigned

I've updated the PR.

comment:9 Changed 16 months ago by Tim Graham <timograham@…>

  • Resolution set to fixed
  • Status changed from assigned to closed

In a779757706b19ef244dc1ede2e1e992735461623:

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

Thanks cjerdonek for the report.

comment:10 Changed 16 months ago by 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

comment:11 Changed 16 months ago by 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

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