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 ...@@ -339,6 +339,8 @@ On the browser side, you need to inherit from :func:`LoginBrowser <weboob.browse
if self.login_error.is_here(): if self.login_error.is_here():
raise BrowserIncorrectPassword(self.page.get_error()) 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:: Also, your ``LoginPage`` may look like::
class LoginPage(HTMLPage): class LoginPage(HTMLPage):
...@@ -348,7 +350,7 @@ Also, your ``LoginPage`` may look like:: ...@@ -348,7 +350,7 @@ Also, your ``LoginPage`` may look like::
form['password'] = password form['password'] = password
form.submit() 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): class ExampleBrowser(LoginBrowser):
accounts = URL('/accounts$', ListPage) accounts = URL('/accounts$', ListPage)
...@@ -358,9 +360,17 @@ Then, each method on your browser which need your user to be authenticated may b ...@@ -358,9 +360,17 @@ Then, each method on your browser which need your user to be authenticated may b
self.accounts.stay_or_go() self.accounts.stay_or_go()
return self.page.get_accounts() 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 You finally have to set correctly the :func:`logged <weboob.browser.pages.Page.logged>` attribute of each page you use. The
reading the attribute :func:`logged <weboob.browser.pages.Page.logged>` of the instance. You can either define it yourself, as a :func:`need_login <weboob.browser.browsers.need_login>` decorator checks if the current page is a logged one by reading the attribute
class boolean attribute or as a property, or to inherit your class from :class:`LoggedPage <weboob.browser.pages.LoggedPage>`. :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 Parsing of pages
......
...@@ -777,10 +777,13 @@ def need_login(func): ...@@ -777,10 +777,13 @@ def need_login(func):
Decorator used to require to be logged to access to this function. 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 This decorator can be used on any method whose first argument is a
browser (typically a :class:`LoginBrowser`). It checks if the login browser (typically a :class:`LoginBrowser`). It checks for the
procedure has succeeded by looking at the `logged` attribute in the current browser's page: when this
:attr:`LoginBrowser.logged` attribute of the browser. When this attribute is set to ``True`` (e.g., when the page inherits
attribute does not exist or is not set to ``True``, the :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 :meth:`LoginBrowser.do_login` method of the browser is called before
calling :`func`. calling :`func`.
""" """
...@@ -811,11 +814,7 @@ class LoginBrowser(PagesBrowser): ...@@ -811,11 +814,7 @@ class LoginBrowser(PagesBrowser):
""" """
Abstract method to implement to login on website. Abstract method to implement to login on website.
It is called when a login is needed. When login succeeds, this It is called when a login is needed.
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.
""" """
raise NotImplementedError() raise NotImplementedError()
...@@ -823,12 +822,7 @@ class LoginBrowser(PagesBrowser): ...@@ -823,12 +822,7 @@ class LoginBrowser(PagesBrowser):
""" """
Logout from website. Logout from website.
By default, simply clears the cookies. If you took care of By default, simply clears the cookies.
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`.
""" """
self.session.cookies.clear() 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