Merge pull request #215 from david-lev/dev

Deprecate properties, improve error handling, and enhance documentation

Author: david-lev

.pre-commit-config.yaml

@@ -22,7 +22,7 @@ repos:
 
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.10
+    rev: v0.15.20
     hooks:
       - id: ruff-check
         args: [ --fix ]

CHANGELOG.md

@@ -3,7 +3,16 @@
 
 > NOTE: pywa follows the [semver](https://semver.org/) versioning standard.
 
-#### 4.2.1 (2026-07-01) **Latest**
+#### 4.3.0 (2026-08-07) **Latest**
+
+- [filters] make `Filter` class generic
+- [signups] adding support for creating listing and updating signups
+- [templates] add documentation and strict typing for `ContactInfoRequestButton`
+- [message] deprecate `sender` and `recipient` properties and update user identifier priority
+- [cli] move uvicorn import to runtime and improve error handling
+- [errors] add more error codes for throttling, sending, and migration, and fix template error code
+
+#### 4.2.1 (2026-07-01)
 
 - [others] fix parsing contact with field `request contact`
 - [others] fix parsing contact without name

CONTRIBUTING.md

@@ -1,9 +1,11 @@
 🤝 **Contributing**
 --------------------
 
-Thank you for considering contributing to pywa! We appreciate your time and effort in helping improve this project. This guide will walk you through the steps and standards to follow for contributing.
+Thank you for considering contributing to pywa! We appreciate your time and effort in helping improve this project. This
+guide will walk you through the steps and standards to follow for contributing.
 
 ## Prerequisites
+
 - [Python](https://www.python.org/downloads/) 3.10 or higher
 - A [GitHub account](https://github.com)
 - Familiarity with [git](https://git-scm.com/) for version control
@@ -15,7 +17,7 @@ Thank you for considering contributing to pywa! We appreciate your time and effo
    ```bash
    git clone https://github.com/<your-username>/pywa.git
    cd pywa
-    ```
+   ```
 
 
 2. Set up a [virtual environment](https://docs.python.org/3/library/venv.html) and install the required dependencies:
@@ -44,8 +46,14 @@ Now you are ready to start contributing!
 ## Code Standards
 
 - Follow the [PEP 8](https://pep8.org/) style guide.
-- Use [Google Style Python Docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) for docstrings.
+- Use [Google Style Python Docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) for
+  docstrings.
 - Include type annotations for all function parameters and return types.
+- The project uses [Ruff](https://astral.sh/ruff) for linting and code formatting. You can run checks manually:
+  ```bash
+  ruff check .
+  ruff format .
+  ```
 
 ## Making Changes
 
@@ -54,6 +62,7 @@ Now you are ready to start contributing!
    ```bash
    git checkout -b my-new-feature
    ```
+
 > Use descriptive names like `feature-add-listeners` or `bugfix-handler-issue.`
 
 2. Test your changes:
@@ -64,15 +73,15 @@ Now you are ready to start contributing!
 
    If you're making doc changes, you can build the docs locally:
 
-      ```bash
-      make -C docs html
-      ```
+   ```bash
+   make -C docs html
+   ```
 
    And run a local server to view the changes:
 
-      ```bash
-      python3 -m http.server 8000 -d docs/build/html
-      ```
+   ```bash
+   python3 -m http.server 8000 -d docs/build/html
+   ```
 
    Then launch your browser and navigate to `http://localhost:8000`.
 
@@ -90,18 +99,63 @@ Now you are ready to start contributing!
 
 ## Communication
 
-If you have questions, feel free to reach out via our issue tracker or other communication channels listed in the repository.
+If you have questions, need help, or want to discuss changes, feel free to reach out via:
 
+- Our **Telegram Group**: [pywa Chat](https://t.me/pywachat)
+- GitHub [Issues](https://github.com/david-lev/pywa/issues) for bug reports and feature requests.
+- GitHub [Discussions](https://github.com/david-lev/pywa/discussions) for general questions, ideas, and showcase.
 
 ## License
 
-By contributing to pywa, you agree that your contributions will be licensed under the MIT License. See the [LICENSE](https://github.com/david-lev/pywa/blob/master/LICENSE) file for details.
+By contributing to pywa, you agree that your contributions will be licensed under the MIT License. See
+the [LICENSE](https://github.com/david-lev/pywa/blob/master/LICENSE) file for details.
 
 ## Project Structure
 
+This project provides both synchronous (`pywa`) and asynchronous (`pywa_async`) implementations. The asynchronous
+implementation structure mirrors the synchronous implementation structure.
+
+### Synchronous Structure (`pywa`)
+
 ```bash
 pywa/
 ├── __init__.py
+├── __main__.py
+├── _helpers.py
+├── api.py
+├── cli.py
+├── client.py
+├── errors.py
+├── filters.py
+├── handlers.py
+├── listeners.py
+├── server.py
+├── types/
+│   ├── __init__.py
+│   ├── base_update.py
+│   ├── account_update.py
+│   ├── callback.py
+│   ├── calls.py
+│   ├── chat.py
+│   ├── flows.py
+│   ├── groups.py
+│   ├── media.py
+│   ├── message.py
+│   ├── message_status.py
+│   ├── others.py
+│   ├── sent_update.py
+│   ├── system.py
+│   ├── templates.py
+│   ├── user.py
+│   └── user_preferences.py
+└── utils.py
+```
+
+### Asynchronous Structure (`pywa_async`)
+
+```bash
+pywa_async/
+├── __init__.py
 ├── _helpers.py
 ├── api.py
 ├── client.py
@@ -110,59 +164,96 @@ pywa/
 ├── handlers.py
 ├── listeners.py
 ├── server.py
-├── types
-│   ├── __init__.py
-│   ├── base_update.py
-│   ├── callback.py
-│   ├── chat_opened.py
-│   ├── flows.py
-│   ├── media.py
-│   ├── message.py
-│   ├── message_status.py
-│   ├── others.py
-│   ├── sent_message.py
-│   └── templates.py
+├── types/
+│   ├── __init__.py
+│   ├── base_update.py
+│   ├── account_update.py
+│   ├── callback.py
+│   ├── calls.py
+│   ├── chat.py
+│   ├── flows.py
+│   ├── groups.py
+│   ├── media.py
+│   ├── message.py
+│   ├── message_status.py
+│   ├── others.py
+│   ├── sent_update.py
+│   ├── system.py
+│   ├── templates.py
+│   ├── user.py
+│   └── user_preferences.py
 └── utils.py
 ```
 
-**Let me explain how the library is structured:**
+### Project Components
+
+#### API
+
+The `api.py` file contains all the api calls to the WhatsApp Cloud API. It is responsible for sending requests to the
+WhatsApp Cloud API and returning their raw responses.
+
+#### Client
+
+The `WhatsApp` class in the `client.py` file is a wrapper around the api calls. It is responsible for sending requests
+to the WhatsApp Cloud API and returning the parsed responses. It allows to send messages, upload media, manage profiles,
+flows, templates, and more.
+
+#### Server
+
+The `Server` class in the `server.py` file is responsible for handling, verifying and parsing the incoming updates from
+the webhook. It is also responsible for registering the webhook routes and the callback url.
 
-### API
-The `api.py` file contains all the api calls to the WhatsApp Cloud API. It responsible for sending requests to the WhatsApp Cloud API and returning their raw responses.
+#### Handlers
 
-### Client
-The `WhatsApp` class in the `client.py` file is a wrapper around the api calls. It responsible for sending requests to the WhatsApp Cloud API and returning the parsed responses.
-It allows to send messages, upload media, manage profiles, flows, templates, and more.
+The `handlers.py` file contains the handler decorators and their respective handler objects. The handlers are used to
+handle incoming updates from the webhook.
 
-### Server
-The `Server` class in the `server.py` file is responsible for handling, verifying and parsing the incoming updates from the webhook.
-It also responsible for registering the webhook routes and the callback url.
+#### Listeners
 
-### Handlers
-The `handlers.py` file contains the handler decorators and their respective handler objects. The handlers are used to handle incoming updates from the webhook.
+The `listeners.py` file contains the listener functions and the logic to wait and listen to specific updates.
 
-### Listeners
-The `listeners.py` file contains the listener functions and the logic to wait and listen to specific user updates.
+#### Filters
 
-### Filters
 The `filters.py` file contains the filters to use in the handlers to filter incoming updates.
 
-### Types
-The `types` package contains the data classes representing the different types of updates and messages.
+#### Types
 
-### Utils
-Contains utility functions used across the library and by the users (not like `_helpers.py` which is used internally).
+The `types` package contains the data classes representing the different types of updates, messages, templates, flows,
+business profiles, calling settings, etc.
+
+#### Utils
+
+Contains utility functions used across the library and by the users (unlike `_helpers.py` which is used internally).
+
+#### Errors
 
-### Errors
 Contains the custom exceptions used in the library.
 
-### Async
-The async version of pywa preserves the same structure as the sync version.
-Most of the code in the async version is inherited from the sync version, while overriding every api-related method to be async.
-So when you make changes to the sync version, make sure to apply the same changes to the async version.
+#### CLI
+
+The `cli.py` and `__main__.py` files implement the command line interface (run using the `pywa` command) to run the dev
+server, send messages etc.
+
+#### Async
+
+The async version of pywa (`pywa_async`) preserves the same structure as the sync version (`pywa`). Most of the code in
+the async version is inherited from the sync version, while overriding every api-related method to be async. So when you
+make changes to the sync version, make sure to apply the same changes to the async version.
+
+#### Docs
+
+The documentation is written in reStructuredText and is located in the `docs/source/content` directory. The
+documentation is built using Sphinx and hosted on ReadTheDocs.
+
+#### Tests
 
-### Docs
-The documentation is written in reStructuredText and is located in the `docs/source/content` directory. The documentation is built using Sphinx and hosted on ReadTheDocs.
+The tests are located in the `tests` directory and are written using `pytest`.
 
-### Tests
-The tests are located in the `tests` directory. The tests are written using `pytest`.
+- Run all tests:
+  ```bash
+  pytest
+  ```
+- When adding new features or fixing bugs, please write corresponding tests:
+    - Add tests for client methods/options in `test_client.py` and `test_async.py`.
+    - Add tests for new filters in `test_filters.py`.
+    - Add tests for new types/updates in `test_types.py` or `test_updates.py`.

README.md

@@ -20,7 +20,7 @@
   <a href="https://pywa.readthedocs.io"><img src="https://readthedocs.org/projects/pywa/badge/?version=latest&" alt="Docs"/></a>
   <a href="https://github.com/david-lev/pywa/blob/master/LICENSE"><img src="https://img.shields.io/github/license/david-lev/pywa?color=%2334D058" alt="License"/></a>
   <a href="https://www.codefactor.io/repository/github/david-lev/pywa/overview/master"><img src="https://www.codefactor.io/repository/github/david-lev/pywa/badge/master" alt="Code Quality"/></a>
-  <a href="https://t.me/py_wa"><img src="https://badges.aleen42.com/src/telegram.svg" /></a></p>
+  <a href="https://t.me/py_wa"><img src="https://badges.aleen42.com/src/telegram.svg"  alt="Updates"/></a></p>
 
 ---
 

.readthedocs.yaml docs/.readthedocs.yaml.readthedocs.yaml renamed to docs/.readthedocs.yaml

@@ -83,7 +83,10 @@ Client Reference
 .. automethod:: WhatsApp.get_current_username
 .. automethod:: WhatsApp.get_reserved_usernames
 .. automethod:: WhatsApp.delete_username
-.. automethod:: WhatsApp.delete_qr_code
+.. automethod:: WhatsApp.create_signup
+.. automethod:: WhatsApp.get_signup
+.. automethod:: WhatsApp.get_signups
+.. automethod:: WhatsApp.update_signup
 .. automethod:: WhatsApp.get_call_permissions
 .. automethod:: WhatsApp.pre_accept_call
 .. automethod:: WhatsApp.accept_call

docs/source/content/client/client_reference.rst

@@ -365,6 +365,23 @@ QR Codes
    * - :meth:`~WhatsApp.delete_qr_code`
      - Delete a QR code
 
+Signups
+--------
+.. list-table::
+   :widths: 40 60
+   :header-rows: 1
+
+   * - Method
+     - Description
+   * - :meth:`~WhatsApp.create_signup`
+     - Create a signup
+   * - :meth:`~WhatsApp.get_signup`
+     - Get details of a signup
+   * - :meth:`~WhatsApp.get_signups`
+     - List all signups
+   * - :meth:`~WhatsApp.update_signup`
+     - Update a signup
+
 
 Commerce
 --------

docs/source/content/client/overview.rst

@@ -61,7 +61,7 @@ That’s why it’s **important to always register a handler** for failed messag
     @wa.on_message_status(filters.failed)
     def handle_failed_message(client: WhatsApp, status: types.MessageStatus):
         logging.error("Message failed to send to %s: %s",
-            status.sender, status.error
+            status.fron_user, status.error
         )
 
 ------------------------------

docs/source/content/errors/overview.rst

@@ -55,3 +55,5 @@ Sending Messages Errors
     :show-inheritance:
 .. autoclass:: MarketingTemplatesDisabledForCloudAPI()
     :show-inheritance:
+.. autoclass:: PhoneNumberDisplayNameNotApproved()
+    :show-inheritance:

docs/source/content/errors/sending_messages_errors.rst

@@ -47,7 +47,7 @@ This is a simple bot that echoes back the user's message.
     @wa.on_message
     def echo(_: WhatsApp, msg: types.Message):
         try:
-            msg.copy(to=msg.sender, reply_to_message_id=msg.message_id_to_reply)
+            msg.copy(to=msg.from_user.bsuid, reply_to_message_id=msg.message_id_to_reply)
         except ValueError:
             msg.reply("I can't echo this message")