.. |badge-python-versions| image:: https://img.shields.io/pypi/pyversions/whalesong.svg :alt: Python versions
.. |badge-version| image:: https://img.shields.io/pypi/v/whalesong.svg :alt: Last version :target: https://pypi.org/project/whalesong/
.. |badge-license| image:: https://img.shields.io/pypi/l/whalesong.svg :alt: License
.. |badge-status| image:: https://img.shields.io/pypi/status/whalesong.svg :alt: Status
|badge-status| |badge-license| |badge-version| |badge-python-versions|
.. warning::
NEW VERSION 0.7.0
With new version some new requirements have been defined and some API change have been committed.
Version 0.7.0 introduces new driver for Chromium browser. It has required some changes on base driver's API. It should not affect anyone. But be aware.
.. warning::
NEW VERSION 0.7.0
Stream model now uses enumerations. It means that if you check stream states
you must be aware that they are not a string anymore, now they are enumerations. Look at
:class:documentation <whalesong.managers.stream.Stream>
.
Whalesong is an asyncio python library to manage WebApps remotely. Currently WhatsappWeb is implemented
http://whalesong.readthedocs.io/
............. Using Firefox .............
.............. Using Chromium ..............
Execute this after installation:
.. code-block:: bash
$ pyppeteer-install
........................ Development requirements ........................
Starting with version 0.7.0
Whalesong introduces new browsers backends <browser_backends>
_. It means you must
decide which browser backend you want to use. So, depending on it:
.. tip::
You could install both with no problems.
............. Using Firefox .............
.. code-block:: bash
$ pip3 install whalesong[firefox]
.. _using_chromium:
.............. Using Chronium ..............
.. code-block:: bash
$ pip3 install whalesong[chromium]
If you choose Chromium backend, you should execute this after installation:
.. code-block:: bash
$ pyppeteer-install
It will download a patched Chromium distribution needed for that backend.
................. Whatsapp features .................
See documentation <https://whalesong.readthedocs.io/en/latest/changelog.html>
_
Work in progress <https://whalesong.readthedocs.io>
_)Android Messages <https://messages.android.com/>
_)... _browser_backends:
Whalesong use a browser backend in order to execute a WebApp (currently only WhatsAppWeb). All backends have
an interface to manage webviews and that is what Whalesong use to manage applications. That interface change
depending on browser, but there is a standard interface called
WebDriver <https://developer.mozilla.org/en-US/docs/Web/WebDriver>
. Firsts Whalesong versions used to use a
Selenium <https://www.seleniumhq.org/>
library in order to communicate with Firefox browser.
This backend is the default one for now, but it will be deprecated in next versions and removed in version 1.0.
............... Firefox backend ...............
It was the first backend developed. It uses Selenium <https://www.seleniumhq.org/>
library and
Geckodriver <https://firefox-source-docs.mozilla.org/testing/geckodriver/geckodriver/>
to communicate with
Firefox process. It is the most tested (the most, but not well).
Selenium is a huge library. It is wonderful for what it was created, but not for Whalsong.
Selenium is a synchronous library. It is a problem, because Whalesong is an asynchronous library. It means, Whalesong creates a thread pool to communicate with Selenium.
We need Geckodriver. Firefox does not implement Webdriver protocol by itself. Firefox has its
own protocol called Marionette <https://firefox-source-docs.mozilla.org/testing/marionette/marionette/Intro.html>
_.
So Geckodriver is used as proxy between Webdriver protocol and Marionette protocol.
As Webdriver is a synchronous protocol. Whalesong must poll continuously to Firefox in order to get new events. There is no way to make Firefox notify Whalesong proactively. It means, Whalesong is polling for new results continuously, with an interval (by default 0.5 seconds).
.. note::
**There is only one way for the Firefox backend to survive:**
Drop Selenium, drop Geckodriver, implement Marionette protocol directly and implement a notification
system (I'm not sure it is possible in Marionette, currently).
Currently Firefox backend is the default one. But it will change on next versions. So, in order to ensure you use Firefox backend you must instantiate Whalesong with proper driver.
.. code-block:: python3
from whalesong import Whalesong from whalesong.driver_firefox import WhalesongDriver
driver = WhalesongDriver(profile='/path/to/your/firefox/profile') whaleapp = Whalesong(driver=driver)
................ Chromium backend ................
It is the new one. It is implemented using Pyppetter <https://github.com/miyakogi/pyppeteer>
which is inspired
on Puppetter <https://pptr.dev/>
(a node
library to control Chromium headless, mainly, for testing). It uses
Devtools protocol <https://chromedevtools.github.io/devtools-protocol/>
_ in order to communicate with the browser.
It is an asynchronous protocol over websocket.
sleeps
, no more waitings.It is Chromium. It uses Blink: over-vitaminized Webkit render. A memory eater.
Currently Pypperter has a bug. It makes to loose connection after 20 seconds. It is resolved in
miyakogi/pyppeteer/#160 <https://github.com/miyakogi/pyppeteer/pull/160>
_ but is not approved
yet (some test errors).
It uses a patched Chromium version from Puppetter. Whalesong needs this patch because it uses Runtime.addBinding
command. It is not available in regular stable version. So, you must download it <using_chromium>
_ before
use the backend.
Poorly tested.
There is a bug in Chromium under Wayland. It makes impossible to get WhastappWeb QR when Chromium is executed with window (no headless).
In order to use Chromium backend you must inject Chromium driver to Whalesong service constructor.
.. code-block:: python3
from whalesong import Whalesong from whalesong.driver_chromium import WhalesongDriver
driver = WhalesongDriver(profile='/path/to/your/chromium/profile') whaleapp = Whalesong(driver=driver)
.............. Other backends ..............
No, there are no other backends. But I'm thinking about other possibilities:
Of course, any contribution will be welcome (so much).
............................ Install library requirements ............................
.. code-block:: bash
$ make requirements
......................... Build Javascript scriplet .........................
You have to rebuild scriptlet after any change if you want to use in Python code.
.. code-block:: bash
$ make build-js
............. Beautify code .............
You must beautify code before to make a pull request. Ugly code will not be accepted.
.. code-block:: bash
$ make beautify
See documentation <https://whalesong.readthedocs.io/en/latest/examples.html>
_
............ whalesong-js ............
Port of Whalesong to Node.js.
Author: @jabolina <https://github.com/jabolina>
_
Repository: https://github.com/jabolina/whalesong-js
This code is in no way affiliated with, authorized, maintained, sponsored or endorsed by WhatsApp or any of its affiliates or subsidiaries. This is an independent and unofficial software. Use at your own risk.