[1.9.x] Fixed #18348 -- Documented SesssionStore.create()

Backport of 32cf01c1c1dcd5fa5d700d0e5117778caf947b74 from master

1 files changed, 8 insertions, 2 deletions

diff --git a/docs/topics/http/sessions.txt b/docs/topics/http/sessions.txt
index 69b291ded6..a042d62229 100644
--- a/docs/topics/http/sessions.txt
+++ b/docs/topics/http/sessions.txt
@@ -493,14 +493,20 @@ An API is available to manipulate session data outside of a view::
     >>> s = SessionStore()
     >>> # stored as seconds since epoch since datetimes are not serializable in JSON.
     >>> s['last_login'] = 1376587691
-    >>> s.save()
+    >>> s.create()
     >>> s.session_key
     '2b1189a188b44ad18c35e113ac6ceead'
-
     >>> s = SessionStore(session_key='2b1189a188b44ad18c35e113ac6ceead')
     >>> s['last_login']
     1376587691
 
+``SessionStore.create()`` is designed to create a new session (i.e. one not
+loaded from the session store and with ``session_key=None``). ``save()`` is
+designed to save an existing session (i.e. one loaded from the session store).
+Calling ``save()`` on a new session may also work but has a small chance of
+generating a ``session_key`` that collides with an existing one. ``create()``
+calls ``save()`` and loops until an unused ``session_key`` is generated.
+
 If you're using the ``django.contrib.sessions.backends.db`` backend, each
 session is just a normal Django model. The ``Session`` model is defined in
 ``django/contrib/sessions/models.py``. Because it's a normal model, you can