About whatstk

whatstk is a python package providing tools to parse, analyze and visualize WhatsApp chats developed by Lucas Rodés-Guirao. Easily convert your chats to csv or simply visualize statistics using the python library. The package uses pandas to process the data and plotly to visualise it.

You can also try a live demo.

The project is distributed under the GPL-3.0 license and is available on GitHub.


First contact with whatstk

whatstk is built around BaseChat object interface, which requires class method from_source to be implemented. This method loads and parses the source chat file into a pandas.DataFrame.

Below, we use method df_from_whatsapp to load LOREM chat. To test it with your own chat, simply export it as a txt file to your computer and then use class argument filepath, as shown in the following example.

>>> from whatstk import df_from_whatsapp
>>> from whatstk.data import whatsapp_urls
>>> df = df_from_whatsapp(filepath=whatsapp_urls.LOREM)
>>> df.head(5)
                 date        username                                            message
0 2020-01-15 02:22:56            Mary                     Nostrud exercitation magna id.
1 2020-01-15 03:33:01            Mary     Non elit irure irure pariatur exercitation. 🇩🇰
2 2020-01-15 04:18:42  +1 123 456 789  Exercitation esse lorem reprehenderit ut ex ve...
3 2020-01-15 06:05:14        Giuseppe  Aliquip dolor reprehenderit voluptate dolore e...
4 2020-01-15 06:56:00            Mary              Ullamco duis et commodo exercitation.

Installation & compatibility

This project is on PyPI, install it with pip:

pip install whatstk

Project has been tested in Python>=3.11.

From source

Clone the project from the official repository and install it locally

git clone https://github.com/lucasrodes/whatstk.git
cd whatstk
pip install .

Extensions

Plotting is optional. Parsing a chat needs neither plotly nor seaborn, so they are not installed by default. To use FigureBuilder or the whatstk-graph command:

pip install whatstk[viz]

Note

Google Drive support was removed in 0.10.0, after being deprecated in 0.9.0. Download the file from Drive and pass the local path instead.

Develop

You can also install the version in development directly from github develop branch.

pip install git+https://github.com/lucasrodes/whatstk.git@develop

Note: It requires git to be installed.


Support

You can ask questions and join the development discussion on GitHub. Use the GitHub issues section to report bugs or request features and GitHub discussions to open up broader discussions.

For more details, refer to the contribute section.

If you are working with an AI assistant, llms.txt is a condensed map of the library — the public API, the header format model and the known limitations — in a single fetch.


Why this name, whatstk?

whatstk stands for “WhatsApp Toolkit”, since the project was initially conceived as a python library to read and process WhatsApp chats. It currently only supports WhatsApp chats, but this might be extended in the future.


Content: