URL dispatcher docs should mention path_info

[Roy Smith]

At ​https://docs.djangoproject.com/en/2.2/topics/http/urls/#how-django-processes-a-request, it says:

Django runs through each URL pattern, in order, and stops at the first one that matches the requested URL.

it should mention here that it's matching against request.path_info, and provide a link to ​https://docs.djangoproject.com/en/2.2/ref/request-response/ which explains how request.path differs from request.path_info.

In addition, the debug 404 page, where it says:

The current path ... didn't match any of these.

instead of "current path", it should say something like, "current path (request.path_info)", which would give a hint about what to read to understand why the current path isn't what's shown above, as the "Request URL".

[Roy Smith]

Also, the docs for urls.staticfiles_urlpatterns() (i.e. ​https://docs.djangoproject.com/en/2.2/ref/contrib/staticfiles/) should also mention that staticfiles_urlpatterns() will produce incorrect patterns for an environment where request.path differs from request.path_info. I suppose you could add additional configuration options to handle this case properly, but I think it would be good enough to point out the issue and note that you need to fall back to writing the re_path() expression yourself. And, in that case, the statement:

Note, the beginning of the pattern (r'^static/') should be your STATIC_URL setting.

is not correct. It needs to be STATIC_URL, as modified by the upstream web server.

[Carlton Gibson]

Hi Roy, thanks for the report.

A small, "matching HttpRequest.path_info" clause in the URL Dispatcher docs seems reasonable, yes.
I'll accept on that basis. Are you up for doing a PR?

I'm not convinced by the other two cases.

• The debug 404 page has both full URL and the path that attempted to match in plain site. It's not often they are different but, I would expect the difference there to be noticed, and for folks to know enough about their app to work out what's they're missing.
• STATIC_URL is the URL prefix for your static files. When there's a web server in play you need to configure it to serve the files in STATIC_ROOT from that URL — As I read it the sentence you quote it seems correct: the URL prefix should match STATIC_URL

"It's not often that they're different..." — You have some mount point going on, what is that, if you don't mind me asking? Is this a local development server? Which one? Thanks

[Roy Smith]

I'm building a tool in the Mediawiki Foundation environment (​https://wikitech.wikimedia.org/wiki/Help:Toolforge/Python). It's running under uwsgi. The way they've set things up, URLs look like ​https://tools.wmflabs.org/TOOL-NAME/rest/of/route. They use the TOOL-NAME part to route the request to the correct tool, and deliver /rest/of/route to your django app as the path_info. And, yes, this is a development server. The production server uses a different mechanism to serve statics.

I encourage you to take a step back and look at this from the point of view of somebody who's not intimately familiar with the system. I've got a fair bit of experience with web servers in general, but I'm not very familiar with the uwsgi setup I'm running under now, and not very familiar with the django staticfiles app. So, when you say, " I would expect the difference there to be noticed, and for folks to know enough about their app to work out what's they're missing.", my response would be, "I'm giving you an example of it not being noticed, and a suggestion for how to make it more obvious".

[Carlton Gibson]

Hi Roy, yes, I understand.

If you have concrete suggestions to make in PRs, I'm happy to look at them but your situation is somewhat unusual, and my concern is making things more complex for the vast majority of users. Hence, yes, I think the link in the URL dispatcher docs is appropriate, but my skepticism about the other suggestions.

In particular, the STATIC_URL docs are quiet explicit, and backed by the staticfiles app docs which are quite extensive. — I appreciate users still find these topics hard (which is because they're complex) so (again) if you have a concrete change in mind, please do suggest it.

At the least, are you up for making the change to the URL dispatcher docs?

[Roy Smith]

​https://github.com/roysmith/django/pull/1

[Mariusz Felisiak <felisiak.mariusz@…>]

In cf493e5c:

Fixed #31184 -- Clarified URL matching behavior in URL dispatcher docs.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 27739ad:

[3.0.x] Fixed #31184 -- Clarified URL matching behavior in URL dispatcher docs.

Backport of cf493e5c819f5ee49b96954f026bec722e19d9c3 from master