Documentation for using sessions outside of views should import SessionStore from session engine designated in settings

[Jim Dalton]

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

[Tim Graham]

Note that in master django.utils.importlib is deprecated and the example should use from importlib import import_module. If you would like to put together a patch I'll be happy to review and commit it. Thanks for the suggestion.

[Jim Dalton]

No problem. Just added a documentation patch. Let me know if that works for you.

[Tim Graham <timograham@…>]

In be48c6c19915f78f1378dba8b0c6c41ab8e8ab59:

Fixed #20997 -- Added SessionStore note to docs.

Thanks jsdalton.