Document django.shortcuts.resolve_url.

[Sage Abdullah]

The documentation for django.shortcuts currently doesn't document resolve_url. However, the section for ​redirect pretty much explains how resolve_url works. It would be helpful to document resolve_url and state that redirect uses resolve_url in its process.

[Mariusz Felisiak]

Thanks for this ticket, however as you mentioned the way how redirect() resolves URLs is already described in documentation. I don't see many (if any) use cases for resolve_url() (beyond the current), hence adding it to shortcuts can be confusing for users. IMO this should remain part of internal API.

[Adam Johnson]

I disagree, I think this could be pretty useful and it seems well documented internally already

[Mariusz Felisiak]

The way how resolve_url() works is already described in the ​redirect() documentation. Have you checked it? Can you describe any use cases for resolve_url() (except the current)?

Please see ​follow triaging guidelines with regards to wontfix tickets.

[Carlton Gibson]

Eeek. This goes back some way. From #15552:

I placed it in utils because I wasn't sure you'd want resolve_url as part of the "public" shortcuts module.
But if that is ok I'll update the patch.

To which Jannis replied:

Yeah, that's fine.

"Yes that's fine, it can be part of the public API" vs "Yes, that's fine to put it there, but we'll leave it private"? — Not sure.

Either way it was never documented.

I can see a use-case: wanting the URL for a get_context_data() maybe (but I can't remember ever using this myself: I'd be inclined to want to know if I had a model or a view name and a URL at the call site; by the time I don't know that I've discovered resolve_url() anyhow.)

_Meh_...

Closing in line with TicketClosingReasons/DontReopenTickets. Happy to look at a patch and/or discuss on django-developers but... 🤷‍♀️

[Adam Johnson]

Okay fair enough, I don't care that much about making it documented and public. I can imagine other use cases like creating a custom redirect() that sends a 307 or 308 but I guess they're quite niche.

[Adam Johnson]

I've seen another use case, which lead me to create duplicate ticket #34650 because I'm a fool who doesn't check for old ones.

The new use case is htmx redirect responses, which django-htmx provides wrappers for like ​HttpResponseClientRedirect. These are a different kind of redirect response but their usage can still benefit from the convenience of resolve_url(), as I found in a client project.

Also see these GitHub code search results: ​https://github.com/search?q=NOT+%28path%3A**%2F__init__.py+OR+path%3A**shortcuts.py%29+%22django.shortcuts%22+resolve_url&type=code&ref=advsearch

They reveal usage in 4.1k files including popular packages Wagtail, and django-allauth.