id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
20997	Documentation for using sessions outside of views should import SessionStore from session engine designated in settings	Jim Dalton	nobody	"Briefly, the current documentation for using sessions outside of views (https://docs.djangoproject.com/en/dev/topics/http/sessions/#using-sessions-out-of-views) mistakenly (in my opinion) encourages the developer to import `SessionStore` from an arbitrary session engine:

{{{
>>> from django.contrib.sessions.backends.db import SessionStore
}}}

Most likely, if you're using `SessionStore` outside of the view you still want to respect the designation made in `settings.SESSION_ENGINE`. The example code doesn't do that. Something like this would be more appropriate:


{{{
>>> from django.conf import settings
>>> from django.utils.importlib import import_module
>>> SessionStore = import_module(settings.SESSION_ENGINE).SessionStore
}}}


This is how the session middleware acquires the `SessionStore` object, which it sets on the `request` object. It makes sense to encourage developers to do the same if they're using `SessionStore` outside the view.

This actually bit me in some old code I'm in the process of upgrading. I was importing `db.SessionStore` directly and calling `flush()` on it, but the project itself was using `cached_db.SessionStore` -- so the session was getting flushed from the database but not from the cache.

Perhaps it makes sense to add a documentation note at the top of the using sessions outside of views section along the lines of:

Note
The examples below import the `SessionStore` object from the database session engine. In your own code, you should consider importing `SessionStore` from the session engine designated by the `SESSION_ENGINE` configuration setting, as below:

{{{
>>> from django.conf import settings
>>> from django.utils.importlib import import_module
>>> SessionStore = import_module(settings.SESSION_ENGINE).SessionStore
}}}"	Cleanup/optimization	closed	Documentation	dev	Normal	fixed			Accepted	0	0	0	0	1	0