nojhan/weboob-devel
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Upgrade documentation with s/ICap/Cap

Browse source
This commit is contained in:
Florent 2014-07-07 16:32:54 +02:00
commit b5da172488
2 changed files with 16 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

2
README
View file

@ -5,7 +5,7 @@ Overview
The core library defines capabilities: features common to various websites. The core library defines capabilities: features common to various websites.
For example, http://www.youtube.com/ and http://www.dailymotion.com/ both For example, http://www.youtube.com/ and http://www.dailymotion.com/ both
provide videos; Weboob defines the "ICapVideo" capability for them. provide videos; Weboob defines the "CapVideo" capability for them.
Each module interfaces with a website and implements one or many of these Each module interfaces with a website and implements one or many of these
capabilities. Modules can be configured (becoming a "backend"), which means capabilities. Modules can be configured (becoming a "backend"), which means

30
docs/source/guides/module.rst
View file

@ -25,8 +25,8 @@ methods (which raise ``NotImplementedError``).
A capability needs to be as generic as possible to allow a maximum number of modules to implements it. A capability needs to be as generic as possible to allow a maximum number of modules to implements it.
Anyway, if you really need to handle website specificities, you can create more specific sub-capabilities. Anyway, if you really need to handle website specificities, you can create more specific sub-capabilities.
For example, there is the :class:`ICapMessages <weboob.capabilities.messages.ICapMessages>` capability, with the associated For example, there is the :class:`CapMessages <weboob.capabilities.messages.CapMessages>` capability, with the associated
:class:`ICapMessagesPost <weboob.capabilities.messages.ICapMessagesPost>` capability to allow answers to messages. :class:`CapMessagesPost <weboob.capabilities.messages.CapMessagesPost>` capability to allow answers to messages.
Pick an existing capability Pick an existing capability
--------------------------- ---------------------------
@ -48,7 +48,7 @@ The module tree
Create a new directory in ``modules/`` with the name of your module. In this example, we assume that we want to create a Create a new directory in ``modules/`` with the name of your module. In this example, we assume that we want to create a
module for a forum website which URL is http://www.example.com. So we will call our module **example**, and the selected module for a forum website which URL is http://www.example.com. So we will call our module **example**, and the selected
capability is :class:`ICapMessages <weboob.capabilities.messages.ICapMessages>`. capability is :class:`CapMessages <weboob.capabilities.messages.CapMessages>`.
So, use this command:: So, use this command::
@ -76,12 +76,12 @@ Then, you can edit ``backend.py`` and create your :class:`BaseBackend <weboob.to
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
from weboob.capabilities.messages import ICapMessages from weboob.capabilities.messages import CapMessages
from weboob.tools.backend import BaseBackend from weboob.tools.backend import BaseBackend
__all__ = ['ExampleBackend'] __all__ = ['ExampleBackend']
class ExampleBackend(BaseBackend, ICapMessages): class ExampleBackend(BaseBackend, CapMessages):
# The name of module # The name of module
NAME = 'example' NAME = 'example'
# Name of maintainer of this backend # Name of maintainer of this backend
@ -95,7 +95,7 @@ Then, you can edit ``backend.py`` and create your :class:`BaseBackend <weboob.to
# License of your module # License of your module
LICENSE = 'AGPLv3+' LICENSE = 'AGPLv3+'
In the code above, you can see that your ``ExampleBackend`` inherits :class:`ICapMessages <weboob.capabilities.messages.ICapMessages>`, as In the code above, you can see that your ``ExampleBackend`` inherits :class:`CapMessages <weboob.capabilities.messages.CapMessages>`, as
we have selected it for the supported website. we have selected it for the supported website.
Update modules list Update modules list
@ -115,7 +115,7 @@ To be sure your module is correctly added, use this command::
| Maintainer | John Smith <john.smith@example.com> | Maintainer | John Smith <john.smith@example.com>
| License | AGPLv3+ | License | AGPLv3+
| Description | Example forum website | Description | Example forum website
| Capabilities | ICapMessages | Capabilities | CapMessages
| Installed | yes | Installed | yes
| Location | /home/me/src/weboob/modules/example | Location | /home/me/src/weboob/modules/example
'-----------------' '-----------------'
@ -146,7 +146,7 @@ For example::
from weboob.tools.backend import BackendConfig from weboob.tools.backend import BackendConfig
# ... # ...
class ExampleBackend(BaseBackend, ICapMessages): class ExampleBackend(BaseBackend, CapMessages):
# ... # ...
CONFIG = BackendConfig(Value('username', label='Username', regexp='.+'), CONFIG = BackendConfig(Value('username', label='Username', regexp='.+'),
ValueBackendPassword('password', label='Password'), ValueBackendPassword('password', label='Password'),
@ -174,7 +174,7 @@ Implement capabilities
You need to implement each method of all of the capabilities your module implements. For example, in our case:: You need to implement each method of all of the capabilities your module implements. For example, in our case::
# ... # ...
class ExampleBackend(BaseBackend, ICapMessages): class ExampleBackend(BaseBackend, CapMessages):
# ... # ...
def iter_threads(self): def iter_threads(self):
@ -189,7 +189,7 @@ You need to implement each method of all of the capabilities your module impleme
def set_message_read(self, message): def set_message_read(self, message):
raise NotImplementedError() raise NotImplementedError()
Read :class:`documentation of the capability <weboob.capabilities.messages.ICapMessages>` to know what are types of arguments, Read :class:`documentation of the capability <weboob.capabilities.messages.CapMessages>` to know what are types of arguments,
what are expected returned objects, and what exceptions it may raises. what are expected returned objects, and what exceptions it may raises.
@ -287,14 +287,14 @@ Once you have a functional browser, you can use it in your class ``ExampleBacken
from .browser import ExampleBrowser from .browser import ExampleBrowser
# ... # ...
class ExampleBackend(BaseBackend, ICapMessages): class ExampleBackend(BaseBackend, CapMessages):
# ... # ...
BROWSER = ExampleBrowser BROWSER = ExampleBrowser
You can now access it with member ``browser``. The class is instanced at the first call to this attribute. It is often better to use You can now access it with member ``browser``. The class is instanced at the first call to this attribute. It is often better to use
your browser only in a ``with`` block, to prevent problems when your backend is called in a multi-threading environment. your browser only in a ``with`` block, to prevent problems when your backend is called in a multi-threading environment.
For example, we can now implement :func:`ICapMessages.iter_threads <weboob.capabilities.messages.ICapMessages.iter_threads>`:: For example, we can now implement :func:`CapMessages.iter_threads <weboob.capabilities.messages.CapMessages.iter_threads>`::
def iter_threads(self): def iter_threads(self):
with self.browser: with self.browser:
@ -309,7 +309,7 @@ Login management
When the website requires to be authenticated, you have to give credentials to the constructor of the browser. You can redefine When the website requires to be authenticated, you have to give credentials to the constructor of the browser. You can redefine
the method :func:`create_default_browser <weboob.tools.backend.BaseBackend.create_default_browser>`:: the method :func:`create_default_browser <weboob.tools.backend.BaseBackend.create_default_browser>`::
class ExampleBackend(BaseBackend, ICapMessages): class ExampleBackend(BaseBackend, CapMessages):
# ... # ...
def create_default_browser(self): def create_default_browser(self):
return self.create_browser(self.config['username'].get(), self.config['password'].get()) return self.create_browser(self.config['username'].get(), self.config['password'].get())
@ -490,11 +490,11 @@ Then, the function might, for each requested fields, fetch the right data and fi
return thread return thread
Here, when the application has got a :class:`Thread <weboob.capabilities.messages.Thread>` object with Here, when the application has got a :class:`Thread <weboob.capabilities.messages.Thread>` object with
:func:`iter_threads <weboob.capabilities.messages.ICapMessages.iter_threads>`, only two fields :func:`iter_threads <weboob.capabilities.messages.CapMessages.iter_threads>`, only two fields
are empty (set to ``NotLoaded``): are empty (set to ``NotLoaded``):
* **root** - tree of messages in the thread * **root** - tree of messages in the thread
* **date** - date of thread * **date** - date of thread
As our method :func:`get_thread <weboob.capabilities.messages.ICapMessages.get_thread>` will get all As our method :func:`get_thread <weboob.capabilities.messages.CapMessages.get_thread>` will get all
of the missing informations, we just call it with the object as parameter to complete it. of the missing informations, we just call it with the object as parameter to complete it.