Metadata-Version: 2.4
Name: pywhats
Version: 0.2.0
Summary: Async Python client for the WhatsApp multi-device protocol
Project-URL: Homepage, https://github.com/sanjay3290/pywhats
Project-URL: Issues, https://github.com/sanjay3290/pywhats/issues
Author: Sanjay Ramadugu
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: messaging,multi-device,signal-protocol,whatsapp
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.11
Requires-Dist: cryptography>=43.0
Requires-Dist: protobuf>=7.35
Requires-Dist: qrcode[pil]>=7.4
Requires-Dist: websockets>=13.0
Provides-Extra: dev
Requires-Dist: grpcio-tools>=1.65; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: signal
Requires-Dist: signal-protocol>=0.2.2; extra == 'signal'
Description-Content-Type: text/markdown

# pywhats

[![CI](https://github.com/sanjay3290/pywhats/actions/workflows/ci.yml/badge.svg)](https://github.com/sanjay3290/pywhats/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/pywhats.svg)](https://pypi.org/project/pywhats/)
[![Python versions](https://img.shields.io/pypi/pyversions/pywhats.svg)](https://pypi.org/project/pywhats/)
[![License](https://img.shields.io/pypi/l/pywhats.svg)](https://github.com/sanjay3290/pywhats/blob/main/LICENSE)

Async Python client for the WhatsApp multi-device protocol.

> **Status:** pre-alpha (0.2.0). Implements QR pairing, connect,
> send/receive text, disconnect, app-state sync, media (images, video,
> audio/voice notes, documents, stickers), reactions, quoted replies,
> edits/revoke, history sync, read receipts, presence, and group
> messaging.

> ⚠️ **Use at your own risk.** This is an independent, unofficial client and
> may violate WhatsApp's Terms of Service — using it can get an account
> banned; prefer a dedicated number. The bundled Signal crypto
> (`pywhats.signal.experimental`) is clean-room and **unaudited** — see
> [SECURITY.md](SECURITY.md).

## Install

```bash
pip install pywhats
```

Requires Python 3.11+.

## Quick start

```python
import asyncio
from pywhats import Client

async def main():
    client = Client()

    @client.on("qr")
    async def on_qr(qr: str):
        print("Scan this QR in WhatsApp → Linked Devices:")
        print(qr)

    @client.on("message")
    async def on_message(msg):
        print(f"{msg.sender}: {msg.text}")
        if msg.text == "ping":
            # Event handlers run on the receive loop, so don't `await` a
            # client call that waits on a server reply (send, receipts,
            # group info) directly here — it would block the loop that has
            # to read that reply. Dispatch it as a task instead.
            asyncio.create_task(client.send_text(msg.chat, "pong"))

    await client.connect()
    await client.wait_closed()

asyncio.run(main())
```

> **Note:** event handlers are dispatched on the connection's receive loop.
> Keep them quick, and never `await` a `Client` call that waits on a server
> response (`send_text`, `send_image`, `mark_read`, `get_group_info`,
> `send_group_text`, …) from inside a handler — schedule it with
> `asyncio.create_task(...)` so the receive loop stays free to read the
> reply.

## Roadmap

- **0.1.0** — QR pair, connect, send/receive text, disconnect, app-state
  sync, media (send/receive images), history sync, read receipts, presence,
  group messaging
- **0.2.0** — more media types (video/audio/document/sticker), message
  features (reactions/replies/edits/revoke)
- **0.3.0+** — calls, newsletters, business

## License

Apache License 2.0. See [LICENSE](LICENSE).

This is an independent clean-room implementation of the WhatsApp multi-device
protocol. It is not affiliated with or endorsed by WhatsApp LLC or Meta.
Using unofficial clients may violate WhatsApp's Terms of Service and can get
an account banned — use at your own risk, preferably with a dedicated number.

## Acknowledgments

The protocol behavior implemented here was informed by public
reverse-engineering writeups and by studying the documented behavior of the
open-source [whatsmeow](https://github.com/tulir/whatsmeow) (Go) and
[Baileys](https://github.com/WhiskeySockets/Baileys) (TypeScript) projects.
No code was copied from either; pywhats is an independent implementation.
