Metadata-Version: 2.4
Name: whatsloon
Version: 3.1.0
Summary: A user-friendly Python wrapper for the WhatsApp Cloud API.
Author-email: Maharana Sarkar <maharana.sarkar2000@gmail.com>
Maintainer-email: Maharana Sarkar <maharana.sarkar2000@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/maharanasarkar/whatsloon
Project-URL: Documentation, https://maharanasarkar.github.io/whatsloon/
Project-URL: Repository, https://github.com/maharanasarkar/whatsloon
Project-URL: Issues, https://github.com/maharanasarkar/whatsloon/issues
Project-URL: Changelog, https://github.com/maharanasarkar/whatsloon/blob/main/CHANGELOG.md
Keywords: whatsloon,whatsapp,whatsapp-cloud-api,whatsapp-sdk
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31; python_version < "3.10"
Requires-Dist: requests>=2.34.2; python_version >= "3.10"
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Requires-Dist: pytest-cov>=5; extra == "test"
Provides-Extra: dev
Requires-Dist: whatsloon[test]; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: black>=24; extra == "dev"
Requires-Dist: mypy<2,>=1.10; extra == "dev"
Requires-Dist: pre-commit>=4.6.2; extra == "dev"
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Requires-Dist: interrogate>=1.7; extra == "dev"
Requires-Dist: bandit>=1.7; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.7.7; extra == "docs"
Requires-Dist: mkdocstrings[python]>=1.0.6; extra == "docs"
Provides-Extra: sql
Requires-Dist: sqlalchemy>=2.0; extra == "sql"
Requires-Dist: alembic>=1.13; extra == "sql"
Provides-Extra: admin
Requires-Dist: whatsloon[sql]; extra == "admin"
Requires-Dist: fastapi>=0.110; extra == "admin"
Requires-Dist: uvicorn>=0.29; extra == "admin"
Requires-Dist: jinja2>=3.1; extra == "admin"
Requires-Dist: python-multipart>=0.0.18; extra == "admin"
Provides-Extra: flows
Requires-Dist: cryptography>=42; extra == "flows"
Provides-Extra: observability
Requires-Dist: opentelemetry-api>=1.20; extra == "observability"
Provides-Extra: all
Requires-Dist: whatsloon[admin,flows,observability,sql]; extra == "all"
Dynamic: license-file

<div align="center">
  <h1>whatsloon</h1>
  <p>Python SDK for the <a href="https://developers.facebook.com/docs/whatsapp/cloud-api">WhatsApp Cloud API</a> — sync + async, typed, tested.</p>
  <a href="https://pypi.org/project/whatsloon/"><img src="https://img.shields.io/pypi/v/whatsloon" alt="PyPI version"></a>
  <a href="https://github.com/maharanasarkar/whatsloon/actions/workflows/ci.yml"><img src="https://github.com/maharanasarkar/whatsloon/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://codecov.io/gh/maharanasarkar/whatsloon"><img src="https://codecov.io/gh/maharanasarkar/whatsloon/branch/main/graph/badge.svg" alt="Coverage"></a>
  <a href="https://maharanasarkar.github.io/whatsloon/"><img src="https://img.shields.io/badge/docs-mkdocs-blue" alt="Docs"></a>
  <a href="https://pypistats.org/packages/whatsloon"><img src="https://img.shields.io/pypi/dm/whatsloon" alt="Downloads"></a>
  <a href="https://github.com/maharanasarkar/whatsloon/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/whatsloon" alt="License: MIT"></a>
  <img src="https://img.shields.io/pypi/pyversions/whatsloon" alt="Python versions">
</div>

## Overview

`whatsloon` wraps the WhatsApp Cloud API (`graph.facebook.com`) with composable mixins for every message type: text, image, video, audio, document, sticker, reaction, location, contacts, templates, interactive lists / reply buttons / CTA / flows, typing indicators, and read receipts.

- Sync via `requests`, async via `httpx`
- Validated payload builders with WhatsApp API limits
- `{"success": bool, "data" | "error"}` result shape + `logging`
- Full test suite, typed package (`py.typed`), docs on GitHub Pages

## Installation

```sh
pip install whatsloon
```

Requires Python >=3.9.

## Quickstart

> **New code should use the v3 client** (`WhatsApp` with per-send `to=`,
> typed models, retries, observability) — see the
> [messages guide](https://maharanasarkar.github.io/whatsloon/messages/).
> Below is the frozen 2.x API (critical fixes only).

```python
from whatsloon import WhatsAppCloudAPIClient

client = WhatsAppCloudAPIClient(
    access_token="YOUR_API_KEY",
    phone_number_id="phone_number_id",
    recipient_country_code="91",
    recipient_mobile_number="9876543210",
)

result = client.send_text_message("Hello, world!", preview_url=True)
print(result)
```

Async:

```python
import asyncio
from whatsloon import WhatsAppCloudAPIClient


async def main():
    client = WhatsAppCloudAPIClient(
        access_token="YOUR_API_KEY",
        phone_number_id="phone_number_id",
        recipient_country_code="91",
        recipient_mobile_number="9876543210",
    )
    print(await client.async_send_text_message("Hello async!"))


asyncio.run(main())
```

Custom client with only needed features:

```python
from whatsloon import WhatsAppBaseClient, TextSender, ImageSender


class MyClient(WhatsAppBaseClient, TextSender, ImageSender):
    pass
```

See [`docs/quickstart.md`](docs/quickstart.md), [`docs/usage.md`](docs/usage.md), and [`examples/`](examples/) for more.

Full docs: https://maharanasarkar.github.io/whatsloon/

## Features

- Text, image, video, audio, document, sticker
- Interactive: lists, reply buttons, CTA, flows
- Location + location request, contacts, address
- Templates with components, reactions, typing indicators, read receipts
- Sync + async for every sender

## Development

```sh
git clone https://github.com/maharanasarkar/whatsloon.git
cd whatsloon
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pre-commit install
pytest
ruff check .
ruff format --check .
mypy whatsloon
python -m build
```

See [CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), [SECURITY.md](SECURITY.md).

## Testing

```sh
pip install -e ".[test]"
pytest
pytest --cov=whatsloon tests/
```

## Changelog

See [CHANGELOG.md](CHANGELOG.md). Releases are cut from tags `v*` via Trusted Publishing to PyPI.

## License

MIT — see [LICENSE](LICENSE).
