🤝 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 3.10 or higher
A GitHub account
Familiarity with git for version control

Getting Started#

Fork the repository and clone your fork locally:

git clone https://github.com/<your-username>/pywa.git
cd pywa

Set up a virtual environment and install the required dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt -r docs/requirements.txt

Activate pre-commit to ensure code quality:
```
pre-commit install
```
Run the tests to make sure everything is working:
```
pytest
```

Now you are ready to start contributing!

Code Standards#

Follow the PEP 8 style guide.
Use Google Style Python Docstrings for docstrings.
Include type annotations for all function parameters and return types.

Making Changes#

Create a new branch for your changes
```
git checkout -b my-new-feature
```

Use descriptive names like feature-add-listeners or bugfix-handler-issue.

Test your changes:
```
pytest
```
If you’re making doc changes, you can build the docs locally:
```
make -C docs html
```
And run a local server to view the changes:
```
python3 -m http.server 8000 -d docs/build/html
```
Then launch your browser and navigate to http://localhost:8000.

Commit your changes:

git add .
git commit -m "[listeners] add `.ask(...)` shortcut"

Push your changes to your fork and submit a pull request targeting the dev branch:
```
git push origin my-new-feature
```

Communication#

If you have questions, feel free to reach out via our issue tracker or other communication channels listed in the repository.

License#

By contributing to pywa, you agree that your contributions will be licensed under the MIT License. See the LICENSE file for details.

Project Structure#

pywa/
├── __init__.py
├── _helpers.py
├── api.py
├── client.py
├── errors.py
├── filters.py
├── 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
└── utils.py

Let me explain how the library is structured:

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.

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.

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.

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.

Listeners#

The listeners.py file contains the listener functions and the logic to wait and listen to specific user updates.

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.

Utils#

Contains utility functions used across the library and by the users (not like _helpers.py which is used internally).

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.

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#

The tests are located in the tests directory. The tests are written using pytest.

🤝 Contributing

Contents