get_script_path and request.path_info undocumented

[leovitch]

As near as I can tell by reading the code, the new django.path support for mod_python in 1.0 has a couple implications for code in cases where the application needs to do URL manipulations itself (I found this while testing django-cms). While the normal urlresolver takes care of anything done through reverse() or the url template tag, code that does its own manipulations on URLs need to:

• Call get_script_prefix() to get the script prefix portion to use when constructing an URL from scratch
• Use request.path_info rather than request.path when parsing an URL

Unfortunately, both of those seem to be undocumented (at least, I can't find the documentation). Shouldn't they be described?

Purely in the spirit of being helpful rather than just complaining, below is my understanding of what the documentation would be -- but I didn't write the original code, so please disregard/correct/wordsmith this as appropriate.

Leo

---

get_script_prefix() would be described under URL Dispatcher > Utility Methods as follows.

Normally, you should always use reverse() or permalink() to define URLs within your application. However, if your application constructs part of the URL hierarchy itself you may occasionally need to generate URLs. In that case, you need to be able to find the base URL of the Django project within its web server (normally, the urlresolver takes care of this for you). In that case, you can call get_script_prefix(), which will return the script prefix portion of the URL for your Django project. If your Django project is at the root of its webserver, this is always '/', but it can be changed for instance by using the django.root option in the modpython handler under Apache.

The path_info attribute of a request object would be documented under Request and Response Objects > HTTPRequest objects > Attributes as follows:

HttpRequest.path_info

Under some web server configurations, the path to the page after the host name is split up into a script prefix portion and a path info portion (this happens, for example, when using the modpython handler from Apache). The path_info attribute always contains the path_info portion of the path, no matter what web server is being used. Using this instead of path can make your code much easier to move between web servers, since you won't need to care what your URL within the overall web server is.

[dc]

Accepting as improved version of #8650

[Chris Beaven]

This would be more helpful as a patch. Want to try providing that, leovitch? (ask in irc if you need assistance)

[leovitch]

How's this?

--- docs/ref/request-response.txt	(revision 9904)
+++ docs/ref/request-response.txt	(working copy)
@@ -37,6 +37,25 @@
 
    Example: ``"/music/bands/the_beatles/"``
 
+.. attribute:: HttpRequest.path_info
+
+   Under some web server configurations, 
+   the portion of the URL after the host name is split up  
+   into a script prefix portion and a path info portion  
+   (this happens, for example, when using the ``django.root`` option
+   with the
+   :ref:`modpython handler from Apache <howto-deployment-modpython>`).  
+   The ``path_info`` attribute always contains the  
+   path info portion of the path,  
+   no matter what web server is being used.  
+   Using this instead of ``path`` can make your code  
+   much easier to move between test and deployment servers. 
+
+   Example: If the ``django.root`` for your application is set to 
+   ``"/minfo"``, then ``path`` might be 
+   ``"/minfo/music/bands/the_beatles/"`` but ``path_info`` 
+   would be ``"/music/bands/the_beatles/"``.
+
 .. attribute:: HttpRequest.method
 
     A string representing the HTTP method used in the request. This is

--- docs/topics/http/urls.txt	(revision 9904)
+++ docs/topics/http/urls.txt	(working copy)
@@ -640,3 +640,28 @@
 The :func:`django.db.models.permalink` decorator is useful for writing short
 methods that return a full URL path. For example, a model's
 ``get_absolute_url()`` method. See :func:`django.db.models.permalink` for more.
+
+get_script_prefix()
+-------------------
+
+.. versionadded:: 1.0
+
+Normally, you should always use 
+:func:`~django.core.urlresolvers.reverse` or 
+:func:`~django.db.models.permalink` to define URLs 
+within your application. 
+However, if your application constructs 
+part of the URL hierarchy itself you may occasionally 
+need to generate URLs. 
+In that case, you need to be able to find the base URL 
+of the Django project within its web server 
+(normally, :func:`~django.core.urlresolvers.reverse` 
+takes care of this for you). 
+In that case, you can call ``get_script_prefix()``, 
+which will return the script prefix portion of the URL 
+for your Django project. 
+If your Django project is at the root of its webserver, 
+this is always ``"/"``, but it can be changed, for instance 
+by using the ``django.root`` (see 
+:ref:`How to use Django with Apache and mod_python <howto-deployment-modpython>`).
+

[leovitch]

diff for docs/ref/request-reponse.txt

[leovitch]

diff for docs/topics/http/urls.txt

[Chris Beaven]

malcolm may want to work on the wording, but it's a good addition. Thanks leovitch.

[Tim Graham]

combining existing diffs into a single patch + minor edits

[Malcolm Tredinnick]

(In [13772]) Documented how to manually piece together URLs with get_script_name().

Thanks to timo and leovitch for the patch. Fixed #10328.