diff --git a/docs/source/_static/architecture.png b/docs/source/_static/architecture.png new file mode 100644 index 00000000..2951ce1e Binary files /dev/null and b/docs/source/_static/architecture.png differ diff --git a/docs/source/api/capabilities/account.rst b/docs/source/api/capabilities/account.rst new file mode 100644 index 00000000..43a7ba62 --- /dev/null +++ b/docs/source/api/capabilities/account.rst @@ -0,0 +1,6 @@ +:mod:`weboob.capabilities.account` +================================== + +.. automodule:: weboob.capabilities.account + :members: + :undoc-members: diff --git a/docs/source/api/capabilities/bank.rst b/docs/source/api/capabilities/bank.rst new file mode 100644 index 00000000..497126ad --- /dev/null +++ b/docs/source/api/capabilities/bank.rst @@ -0,0 +1,6 @@ +:mod:`weboob.capabilities.bank` +=============================== + +.. automodule:: weboob.capabilities.bank + :members: + :undoc-members: diff --git a/docs/source/api/capabilities/base.rst b/docs/source/api/capabilities/base.rst new file mode 100644 index 00000000..1725e06f --- /dev/null +++ b/docs/source/api/capabilities/base.rst @@ -0,0 +1,6 @@ +:mod:`weboob.capabilities.base` +=============================== + +.. automodule:: weboob.capabilities.base + :members: + :undoc-members: diff --git a/docs/source/api/capabilities/chat.rst b/docs/source/api/capabilities/chat.rst new file mode 100644 index 00000000..7c4f9569 --- /dev/null +++ b/docs/source/api/capabilities/chat.rst @@ -0,0 +1,6 @@ +:mod:`weboob.capabilities.chat` +=============================== + +.. automodule:: weboob.capabilities.chat + :members: + :undoc-members: diff --git a/docs/source/api/capabilities/contact.rst b/docs/source/api/capabilities/contact.rst new file mode 100644 index 00000000..4a1e9970 --- /dev/null +++ b/docs/source/api/capabilities/contact.rst @@ -0,0 +1,6 @@ +:mod:`weboob.capabilities.contact` +================================== + +.. automodule:: weboob.capabilities.contact + :members: + :undoc-members: diff --git a/docs/source/api/capabilities/content.rst b/docs/source/api/capabilities/content.rst new file mode 100644 index 00000000..e1763b55 --- /dev/null +++ b/docs/source/api/capabilities/content.rst @@ -0,0 +1,6 @@ +:mod:`weboob.capabilities.content` +================================== + +.. automodule:: weboob.capabilities.content + :members: + :undoc-members: diff --git a/docs/source/api/capabilities/dating.rst b/docs/source/api/capabilities/dating.rst new file mode 100644 index 00000000..2897b99e --- /dev/null +++ b/docs/source/api/capabilities/dating.rst @@ -0,0 +1,6 @@ +:mod:`weboob.capabilities.dating` +================================= + +.. automodule:: weboob.capabilities.dating + :members: + :undoc-members: diff --git a/docs/source/api/capabilities/geolocip.rst b/docs/source/api/capabilities/geolocip.rst new file mode 100644 index 00000000..d71b430b --- /dev/null +++ b/docs/source/api/capabilities/geolocip.rst @@ -0,0 +1,6 @@ +:mod:`weboob.capabilities.geolocip` +=================================== + +.. automodule:: weboob.capabilities.geolocip + :members: + :undoc-members: diff --git a/docs/source/api/capabilities/index.rst b/docs/source/api/capabilities/index.rst new file mode 100644 index 00000000..e3655947 --- /dev/null +++ b/docs/source/api/capabilities/index.rst @@ -0,0 +1,22 @@ +:mod:`weboob.capabilities` +========================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + account + bank + base + chat + contact + content + dating + geolocip + messages + radio + torrent + travel + video + weather diff --git a/docs/source/api/capabilities/messages.rst b/docs/source/api/capabilities/messages.rst new file mode 100644 index 00000000..cc669db2 --- /dev/null +++ b/docs/source/api/capabilities/messages.rst @@ -0,0 +1,6 @@ +:mod:`weboob.capabilities.messages` +=================================== + +.. automodule:: weboob.capabilities.messages + :members: + :undoc-members: diff --git a/docs/source/api/capabilities/radio.rst b/docs/source/api/capabilities/radio.rst new file mode 100644 index 00000000..645b98c3 --- /dev/null +++ b/docs/source/api/capabilities/radio.rst @@ -0,0 +1,6 @@ +:mod:`weboob.capabilities.radio` +================================ + +.. automodule:: weboob.capabilities.radio + :members: + :undoc-members: diff --git a/docs/source/api/capabilities/torrent.rst b/docs/source/api/capabilities/torrent.rst new file mode 100644 index 00000000..3fe8c196 --- /dev/null +++ b/docs/source/api/capabilities/torrent.rst @@ -0,0 +1,6 @@ +:mod:`weboob.capabilities.torrent` +================================== + +.. automodule:: weboob.capabilities.torrent + :members: + :undoc-members: diff --git a/docs/source/api/capabilities/travel.rst b/docs/source/api/capabilities/travel.rst new file mode 100644 index 00000000..d00de5e3 --- /dev/null +++ b/docs/source/api/capabilities/travel.rst @@ -0,0 +1,6 @@ +:mod:`weboob.capabilities.travel` +================================= + +.. automodule:: weboob.capabilities.travel + :members: + :undoc-members: diff --git a/docs/source/api/capabilities/video.rst b/docs/source/api/capabilities/video.rst new file mode 100644 index 00000000..55db098e --- /dev/null +++ b/docs/source/api/capabilities/video.rst @@ -0,0 +1,6 @@ +:mod:`weboob.capabilities.video` +================================ + +.. automodule:: weboob.capabilities.video + :members: + :undoc-members: diff --git a/docs/source/api/capabilities/weather.rst b/docs/source/api/capabilities/weather.rst new file mode 100644 index 00000000..8a834821 --- /dev/null +++ b/docs/source/api/capabilities/weather.rst @@ -0,0 +1,6 @@ +:mod:`weboob.capabilities.weather` +================================== + +.. automodule:: weboob.capabilities.weather + :members: + :undoc-members: diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst index 6523b659..a7d421ee 100644 --- a/docs/source/api/index.rst +++ b/docs/source/api/index.rst @@ -6,5 +6,6 @@ Contents: .. toctree:: :maxdepth: 2 + capabilities/index core/index tools/index diff --git a/docs/source/guides/backend.rst b/docs/source/guides/backend.rst index 4b649501..e4923f96 100644 --- a/docs/source/guides/backend.rst +++ b/docs/source/guides/backend.rst @@ -1,2 +1,56 @@ Backend development =================== + +Each backend implements one or many :doc:`capabilities ` to tell what kind of features the +website provides. A capability is a class derived from :class:`weboob.capabilities.base.ICap` and with some virtual +methods (which raise ``NotImplementedError``). + +A capability needs to be as generic as possible to allow a maximum number of backends to implements it. +Anyway, if you really need to handle website specificities, you can create more specific sub-capabilities. + +For example, there is the :class:`weboob.capabilities.messages.ICapMessages` capability, with the associated +:class:`weboob.capabilities.messages.ICapMessagesPost` capability to allow answers to messages. + +Pick an existing capability +--------------------------- + +When you want to create a new backend, you may have a look on existing capabilities to decide which one can be +implemented. It is quite important, because each already existing capability is supported by at least one application. +So if your new backend implements an existing capability, it will be usable from the existing applications right now. + +Create a new capability +----------------------- + +If the website you want to manage implements some extra-features which are not implemented by any capability, +you can introduce a new capability. + +There are some important rules: + +* A method can raise only its own exceptions. + + When you want to return an error, you *must* raise only your own exceptions defined in the capability module. + Never let Python raise his exceptions, for example ``KeyError`` if a parameter given to method isn't found in a local + list. + +* Prefer returning objects + + Python is an object-oriented language, so when your capability supports entities (for example + :class:`weboob.capabilities.video.BaseVideo` with the :class:`weboob.capabilities.video.ICapVideo` capability), + you have to create a class derivated from :class:`weboob.capabilities.base.CapBaseObject`, and create an unique method + to get it (for example :func:`get_video() `), instead of several methods like + ``get_video_url()``, ``get_video_preview()``, etc. + + An object has an unique ID. + +* Filled objects + + When an object is fetched, all of its fields are not necessarily loaded. + + For example, on a video search, if the backend gets information from the search page, the direct URL of the video + isn't available yet. + + A field which isn't loaded can be set to :class:`weboob.capabilities.base.NotLoaded`. + + By default, in the object constructor, every fields should be set to + :class:`NotLoaded `, and when the backend loads them, it replaces them with + the new values. diff --git a/docs/source/overview.rst b/docs/source/overview.rst index 50656886..c0981ce7 100644 --- a/docs/source/overview.rst +++ b/docs/source/overview.rst @@ -13,11 +13,19 @@ Weboob is written in Python and is distributed under the GPLv3 license. Why using Weboob? ----------------- -* you get essential information faster +* you get essential information from websites faster * you can write scripts using weboob to automate tasks -* it extends websites features +* you can extend websites features * it helps blind people using crappy websites +Architecture +------------ + +.. warning:: + This diagram has to be redrawn. + +.. image:: _static/architecture.png + Capabilities ------------ @@ -42,3 +50,9 @@ Applications ------------ Applications are toolkit-agnostic. They can use Gtk, Qt or just be text-only, more adapted to reuse data through pipes. + +Reporting a bug +--------------- + +When you report a bug on the tracker, it's important to correctly set the category as specific as possible. +Also, don't forget to give information about your version of Weboob, OS, implicated libraries.