From faf22fe4806f423fa3ff1050bcde139596a53f5b Mon Sep 17 00:00:00 2001 From: Florian Hatat Date: Sun, 18 Nov 2018 21:43:36 +0100 Subject: [PATCH] Doc: attempt to avoid misusing LoggedPage --- docs/source/guides/module.rst | 18 ++++++++++++++---- weboob/browser/browsers.py | 24 +++++++++--------------- 2 files changed, 23 insertions(+), 19 deletions(-) diff --git a/docs/source/guides/module.rst b/docs/source/guides/module.rst index 3814240953..e681202aa5 100644 --- a/docs/source/guides/module.rst +++ b/docs/source/guides/module.rst @@ -339,6 +339,8 @@ On the browser side, you need to inherit from :func:`LoginBrowser `:: 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 `:: +Then, each method on your browser which needs your user to be authenticated may be decorated by :func:`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 ` checks if the current page is a logged one by -reading the attribute :func:`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 `. +You finally have to set correctly the :func:`logged ` attribute of each page you use. The +:func:`need_login ` decorator checks if the current page is a logged one by reading the attribute +:func:`logged ` of the instance. This attributes defaults to ``False``, which means that :func:`need_login +` will first call :func:`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 `. +In the latter case, remember that Python inheritance requires the :class:`LoggedPage ` to be placed first such as in:: + + class OnlyForLoggedUserPage(LoggedPage, HTMLPage): + # ... Parsing of pages diff --git a/weboob/browser/browsers.py b/weboob/browser/browsers.py index c74a9a071a..dbdf4471a2 100644 --- a/weboob/browser/browsers.py +++ b/weboob/browser/browsers.py @@ -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 @@ def do_login(self): """ 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 @@ def do_logout(self): """ 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() -- GitLab