[Python-modules-commits] [python-social-auth] 221/322: Add docs about disconnection and logging out difference. Fixes #568

[Wolfgang Borgert]

This is an automated email from the git hooks/post-receive script.

debacle pushed a commit to tag v0.2.10
in repository python-social-auth.

commit 63a2e76dc77cffa20e5f35e07ffdd9f0a9e0124c
Author: Matías Aguirre <matiasaguirre at gmail.com>
Date:   Sat Apr 4 00:19:05 2015 -0300

    Add docs about disconnection and logging out difference. Fixes #568
---
 docs/index.rst       |  1 +
 docs/logging_out.rst | 25 +++++++++++++++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/docs/index.rst b/docs/index.rst
index e585355..2829f7b 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -26,6 +26,7 @@ Contents:
    storage
    exceptions
    backends/index
+   logging_out
    tests
    use_cases
    thanks
diff --git a/docs/logging_out.rst b/docs/logging_out.rst
new file mode 100644
index 0000000..102f001
--- /dev/null
+++ b/docs/logging_out.rst
@@ -0,0 +1,25 @@
+Logging Out
+===========
+
+It's a common misconception that ``disconnect`` action is the same as logging
+the user out, but is far from it.
+
+``Disconnect`` is the way that your users have to say to you "forget about my
+account", that implies removing the ``UserSocialAuth`` instance that was
+created, this also implies that the user won't be able to login back into your
+site with the social account, instead the action will be a signup, a new user
+instance will be created, not related to the previous one.
+
+Logging out is just a way to say "forget my current session", and usually
+implies removing cookies, invalidating a session hash, etc. The many frameworks
+have their own ways to logout an account (Django has ``django.contrib.auth.logout``),
+``flask-login`` has it's own way too with `logout_user()`_.
+
+Since disconnecting a social account means that the user won't be able to log
+back in with that social provider into the same user, python-social-auth will
+check that the user account is in a valid state for disconnection (it has at
+least one more social account associated, or a password, etc). This behavior
+can be overridden by changing the `Disconnection Pipeline`_.
+
+.. _logout_user(): https://github.com/maxcountryman/flask-login/blob/a96de342eae560deec008a02179f593c3799b3ba/flask_login.py#L718-L739
+.. _DISCONNECT_PIPELINE: pipeline.html#disconnection-pipeline

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/python-social-auth.git