[Django] #21941: document kwargs parameter to url()
Django
--------------------------------------+------------------------
Reporter: cjerdonek | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.6
Severity: Normal | Keywords: url,kwargs
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------
Currently, the documentation of the
[https://docs.djangoproject.com/en/dev/ref/urls/#url 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
[https://docs.djangoproject.com/en/dev/topics/http/urls/#how-django-
processes-a-request "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.
--
Ticket URL: <https://code.djangoproject.com/ticket/21941>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: cjerdonek | Owner: nobody
Type: | Status: new
Cleanup/optimization | Version: 1.6
Component: Documentation | Resolution:
Severity: Normal | Triage Stage:
Keywords: url,kwargs | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by cjerdonek):
* cc: chris.jerdonek@… (added)
* needs_better_patch: => 0
* needs_tests: => 0
* needs_docs: => 0
--
Ticket URL: <https://code.djangoproject.com/ticket/21941#comment:1>
Django
Reporter: cjerdonek | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.6
Keywords: url,kwargs | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Changes (by timo):
* stage: Unreviewed => Accepted
Comment:
For `kwargs` we could add a sentence about the usage and then link to
[https://docs.djangoproject.com/en/dev/topics/http/urls/#passing-extra-
options-to-view-functions this example].
Is the issue for the second point just that it should say something like
"remaining arguments or keyword arguments"?
--
Ticket URL: <https://code.djangoproject.com/ticket/21941#comment:2>
Django
Reporter: cjerdonek | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.6
Keywords: url,kwargs | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Comment (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()`."
--
Ticket URL: <https://code.djangoproject.com/ticket/21941#comment:3>
Django
Reporter: cjerdonek | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.6
Keywords: url,kwargs | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Comment (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.
--
Ticket URL: <https://code.djangoproject.com/ticket/21941#comment:4>
Django
Reporter: cjerdonek | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.6
Keywords: url,kwargs | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Changes (by numerodix):
* cc: numerodix@… (added)
--
Ticket URL: <https://code.djangoproject.com/ticket/21941#comment:5>
Django
Reporter: cjerdonek | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.6
Keywords: url,kwargs | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by timmartin):
* cc: timmartin (added)
* has_patch: 0 => 1
Comment:
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/21941#comment:6>
Django
Reporter: cjerdonek | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.6
Keywords: url,kwargs | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
Changes (by timo):
* needs_better_patch: 0 => 1
Comment:
Left comments for improvement on the PR. Please uncheck "patch needs
improvement" when it's updated, thanks!
--
Ticket URL: <https://code.djangoproject.com/ticket/21941#comment:7>
Django
Reporter: cjerdonek | Owner: timmartin
Type: | Status: assigned
Cleanup/optimization | Version: 1.6
Component: Documentation | Resolution:
Keywords: url,kwargs | Needs documentation: 0
Has patch: 1 | Patch needs improvement: 0
Needs tests: 0 | UI/UX: 0
Easy pickings: 1 |
-------------------------------------+-------------------------------------
Changes (by timmartin):
* owner: nobody => timmartin
* needs_better_patch: 1 => 0
* status: new => assigned
Comment:
I've updated the PR.
--
Ticket URL: <https://code.djangoproject.com/ticket/21941#comment:8>
Django
Reporter: cjerdonek | Owner: timmartin
Cleanup/optimization | Version: 1.6
Component: Documentation | Resolution: fixed
Severity: Normal | Triage Stage: Accepted
Keywords: url,kwargs | Needs documentation: 0
Has patch: 1 | Patch needs improvement: 0
Needs tests: 0 | UI/UX: 0
Easy pickings: 1 |
-------------------------------------+-------------------------------------
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"a779757706b19ef244dc1ede2e1e992735461623"]:
{{{
#!CommitTicketReference repository=""
revision="a779757706b19ef244dc1ede2e1e992735461623"
Fixed #21941 -- Documented the kwargs param of django.conf.urls.url().
Thanks cjerdonek for the report.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/21941#comment:9>
Django
Reporter: cjerdonek | Owner: timmartin
Type: | Status: closed
Cleanup/optimization | Version: 1.6
Component: Documentation | Resolution: fixed
Severity: Normal | Triage Stage: Accepted
Keywords: url,kwargs | Needs documentation: 0
Has patch: 1 | Patch needs improvement: 0
Needs tests: 0 | UI/UX: 0
Easy pickings: 1 |
-------------------------------------+-------------------------------------
Comment (by Tim Graham <timograham@…>):
In [changeset:"fe83cfe9eddae67838d453fa247bd47e1b3bf277"]:
{{{
#!CommitTicketReference repository=""
revision="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
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/21941#comment:10>
Django
Reporter: cjerdonek | Owner: timmartin
Type: | Status: closed
Cleanup/optimization | Version: 1.6
Component: Documentation | Resolution: fixed
Severity: Normal | Triage Stage: Accepted
Keywords: url,kwargs | Needs documentation: 0
Has patch: 1 | Patch needs improvement: 0
Needs tests: 0 | UI/UX: 0
Easy pickings: 1 |
-------------------------------------+-------------------------------------
Comment (by Tim Graham <timograham@…>):
In [changeset:"e2e773c04abeab04866eac14c0040ef3aa653e1b"]:
{{{
#!CommitTicketReference repository=""
revision="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
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/21941#comment:11>