Ticket #1422: sessions-doc.2.diff

django/contrib/sessions/models.py

@@ -32 +32 @@
         return s
 
 class Session(models.Model):
+    """Django provides full support for anonymous sessions. The session framework lets you store and retrieve arbitrary data on a per-site-visitor basis. It stores data on the server side and abstracts the sending and receiving of cookies. Cookies contain a session ID -- not the data itself. Session functionality is enabled by default.
+
+    You can turn session functionality on and off by editing the MIDDLEWARE_CLASSES setting. To activate sessions, make sure MIDDLEWARE_CLASSES contains "django.contrib.sessions.middleware.SessionMiddleware". If you don't want to use sessions, turning them off will save you a small bit of overhead.
+
+    Each HttpRequest object -- the first argument to any Django view function -- has a session attribute, which is a dictionary-like object. You can read it and write to it. Because the session is a normal model, you can also access sessions using the normal Django database API.
+
+    The Django sessions framework is entirely, and solely, cookie-based. It does not fall back to putting session IDs in URLs as a last resort, as PHP does. This is an intentional design decision. Not only does that behavior make URLs ugly, it makes your site vulnerable to session-ID theft via the "Referer" header.
+    """
     session_key = models.CharField(_('session key'), maxlength=40, primary_key=True)
     session_data = models.TextField(_('session data'))
     expire_date = models.DateTimeField(_('expire date'))