Commit faf22fe4 authored by Florian Hatat's avatar Florian Hatat Committed by ntome

Doc: attempt to avoid misusing LoggedPage

parent 8071eb96
......@@ -339,6 +339,8 @@ On the browser side, you need to inherit from :func:`LoginBrowser <weboob.browse
if self.login_error.is_here():
raise BrowserIncorrectPassword(self.page.get_error())
You may provide a custom :func:`do_logout <weboob.browser.browsers.LoginBrowser.do_logout>`:: function if you need to customize the default logout process, which simply clears all cookies.
Also, your ``LoginPage`` may look like::
class LoginPage(HTMLPage):
......@@ -348,7 +350,7 @@ Also, your ``LoginPage`` may look like::
form['password'] = password
form.submit()
Then, each method on your browser which need your user to be authenticated may be decorated by :func:`need_login <weboob.browser.browsers.need_login>`::
Then, each method on your browser which needs your user to be authenticated may be decorated by :func:`need_login <weboob.browser.browsers.need_login>`::
class ExampleBrowser(LoginBrowser):
accounts = URL('/accounts$', ListPage)
......@@ -358,9 +360,17 @@ Then, each method on your browser which need your user to be authenticated may b
self.accounts.stay_or_go()
return self.page.get_accounts()
The last thing to know is that :func:`need_login <weboob.browser.browsers.need_login>` checks if the current page is a logged one by
reading the attribute :func:`logged <weboob.browser.pages.Page.logged>` of the instance. You can either define it yourself, as a
class boolean attribute or as a property, or to inherit your class from :class:`LoggedPage <weboob.browser.pages.LoggedPage>`.
You finally have to set correctly the :func:`logged <weboob.browser.pages.Page.logged>` attribute of each page you use. The
:func:`need_login <weboob.browser.browsers.need_login>` decorator checks if the current page is a logged one by reading the attribute
:func:`logged <weboob.browser.pages.Page.logged>` of the instance. This attributes defaults to ``False``, which means that :func:`need_login
<weboob.browser.browsers.need_login>` will first call :func:`do_logout <weboob.browser.browsers.LoginBrowser.do_logout>` before calling the
decorated method.
You can either define it yourself, as a class boolean attribute or as a property, or inherit your class from :class:`LoggedPage <weboob.browser.pages.LoggedPage>`.
In the latter case, remember that Python inheritance requires the :class:`LoggedPage <weboob.browser.pages.LoggedPage>` to be placed first such as in::
class OnlyForLoggedUserPage(LoggedPage, HTMLPage):
# ...
Parsing of pages
......
......@@ -777,10 +777,13 @@ def need_login(func):
Decorator used to require to be logged to access to this function.
This decorator can be used on any method whose first argument is a
browser (typically a :class:`LoginBrowser`). It checks if the login
procedure has succeeded by looking at the
:attr:`LoginBrowser.logged` attribute of the browser. When this
attribute does not exist or is not set to ``True``, the
browser (typically a :class:`LoginBrowser`). It checks for the
`logged` attribute in the current browser's page: when this
attribute is set to ``True`` (e.g., when the page inherits
:class:`LoggedPage`), then nothing special happens.
In all other cases (when the browser isn't on any defined page or
when the page's `logged` attribute is ``False``), the
:meth:`LoginBrowser.do_login` method of the browser is called before
calling :`func`.
"""
......@@ -811,11 +814,7 @@ class LoginBrowser(PagesBrowser):
"""
Abstract method to implement to login on website.
It is called when a login is needed. When login succeeds, this
method should set the :attr:`logged` attribute of the current
browser to ``True``. This tells the `need_login` decorator that
we have already logged in, hence no further call to `do_login`
needs to be performed.
It is called when a login is needed.
"""
raise NotImplementedError()
......@@ -823,12 +822,7 @@ class LoginBrowser(PagesBrowser):
"""
Logout from website.
By default, simply clears the cookies. If you took care of
setting the `logged` attribute to ``True`` in :meth:`do_login`,
you should override the `do_logout` method and unset this
attribute, or set it to ``False``. This will tell the
`need_login` decorator that it has to call again the
:meth:`do_login`.
By default, simply clears the cookies.
"""
self.session.cookies.clear()
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment