Opened 5 years ago

Closed 5 years ago

Last modified 13 months ago

#30515 closed Cleanup/optimization (wontfix)

Document django.shortcuts.resolve_url.

Reported by: Sage Abdullah Owned by: nobody
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: Adam Johnson Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

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.

Change History (7)

comment:1 by Mariusz Felisiak, 5 years ago

Resolution: wontfix
Status: newclosed
Summary: Document django.shortcuts.resolve_urlDocument django.shortcuts.resolve_url.

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.

comment:2 by Adam Johnson, 5 years ago

Resolution: wontfix
Status: closednew

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

comment:3 by Adam Johnson, 5 years ago

Cc: Adam Johnson added

comment:4 by Mariusz Felisiak, 5 years ago

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.

comment:5 by Carlton Gibson, 5 years ago

Resolution: wontfix
Status: newclosed

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... 🤷‍♀️

comment:6 by Adam Johnson, 5 years ago

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.

comment:7 by Adam Johnson, 13 months ago

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.

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