Merge pull request #211 from david-lev/dev

Enhance filters and contacts with new properties and fixes

Author: david-lev

CHANGELOG.md

@@ -3,7 +3,13 @@
 
 > NOTE: pywa follows the [semver](https://semver.org/) versioning standard.
 
-#### 4.1.0 (2026-06-16) **Latest**
+#### 4.2.0 (2026-06-19) **Latest**
+
+- [filters] allowing `filters.new` to be used as decorator:
+- [contacts] adding `first_wa_id` property to `ContactList`
+- [api] fix `recipient_type` in `send_marketing_message`
+
+#### 4.1.0 (2026-06-16)
 
 - [client] add `archive_templates` and `unarchive_templates` methods for template archival management
 - [client] add `force_transfer` option to `set_username` method for username management

docs/source/content/filters/overview.rst

@@ -81,20 +81,22 @@ Write a function that accepts the client and the update, and returns a boolean.
    - Async functions can be used as filters **only** with the async client.
 
 .. code-block:: python
-    :emphasize-lines: 3-4, 8, 13
+    :emphasize-lines: 3-5, 9, 14
 
     from pywa import WhatsApp, types, filters
 
+    @filters.new
     def without_xyz_filter(_: WhatsApp, msg: types.Message) -> bool:
-        return msg.text and "xyz" not in msg.text
+        return "xyz" not in msg.text
 
     wa = WhatsApp(...)
 
-    @wa.on_message(filters.new(without_xyz_filter))
+    # Using the new filter:
+    @wa.on_message(filters.text & without_xyz_filter)
     def messages_without_xyz(wa: WhatsApp, msg: types.Message):
         msg.reply("You said something without xyz!")
 
-    # Or inline with a lambda — combine with built-in filters:
+    # Or passing the function directly:
     @wa.on_message(filters.text & filters.new(lambda _, msg: "xyz" not in msg.text))
     def messages_without_xyz(wa: WhatsApp, msg: types.Message):
         msg.reply("You said something without xyz!")

docs/source/content/updates/message.rst

@@ -45,7 +45,7 @@ The :class:`Message` type is used to represent incoming messages from WhatsApp u
 
 .. autoclass:: pywa.types.others.ContactList()
     :show-inheritance:
-    :members: first
+    :members: first, first_wa_id
 
 .. autoclass:: pywa.types.others.ContactsOrigin()
 

pywa/__init__.py

@@ -9,6 +9,6 @@
 from pywa.client import WhatsApp
 from pywa.utils import Version
 
-__version__ = "4.1.0"
+__version__ = "4.2.0"
 __author__ = "David Lev"
 __license__ = "MIT"

pywa/_helpers.py

@@ -88,20 +88,14 @@ def _missing_(cls, value: str):
         return cls.UNKNOWN
 
 
-@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
 class FromDict:
     """Allows to ignore extra fields when creating a dataclass from a dict."""
 
     # noinspection PyArgumentList
     @classmethod
-    def from_dict(cls, data: dict, **kwargs):
-        return cls(
-            **{
-                k: v
-                for k, v in (data | kwargs).items()
-                if k in (f.name for f in dataclasses.fields(cls))
-            }
-        )
+    def from_dict(cls, data: dict):
+        fields = {f.name for f in dataclasses.fields(cls)}
+        return cls(**{k: v for k, v in data.items() if k in fields})
 
 
 class APIObject:

pywa/api.py

@@ -583,6 +583,7 @@ def send_marketing_message(
         sender: str,
         to: str,
         recipient: str,
+        recipient_type: str,
         template: dict,
         reply_to_message_id: str | None = None,
         message_activity_sharing: bool | None = None,
@@ -599,6 +600,7 @@ def send_marketing_message(
             sender: The phone id to send the message from.
             to: The WhatsApp ID to send the message to.
             recipient: The recipient unique identifier (BSUID).
+            recipient_type: The type of the recipient (e.g. ``individual``, ``group``).
             template: The template object to send.
             reply_to_message_id: The ID of the message to reply to.
             message_activity_sharing: Toggles on / off sharing message activities (e.g. message read) for that specific marketing message to Meta to help optimize marketing messages.
@@ -610,7 +612,7 @@ def send_marketing_message(
         """
         body = self._filter_none(
             messaging_product="whatsapp",
-            recipient_type="individual",
+            recipient_type=recipient_type,
             to=to,
             type="template",
             template=template,

pywa/filters.py

@@ -116,7 +116,7 @@
 ]
 
 import re
-from typing import TYPE_CHECKING, Any, Awaitable, Callable, Iterable, TypeVar
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Iterable, TypeVar, overload
 
 from . import _helpers as helpers
 from .errors import WhatsAppError
@@ -245,10 +245,50 @@ def has_async(self) -> bool:
         return self.filter.has_async()
 
 
+@overload
+def new() -> Callable[[Callable[[_Wa, _T], bool | Awaitable[bool]]], Filter]: ...
+
+
+@overload
+def new(
+    name: str,
+) -> Callable[[Callable[[_Wa, _T], bool | Awaitable[bool]]], Filter]: ...
+
+
+@overload
 def new(
     func: Callable[[_Wa, _T], bool | Awaitable[bool]], name: str | None = None
+) -> Filter: ...
+
+
+def new(
+    func: Callable[[_Wa, _T], bool | Awaitable[bool]] | str | None = None,
+    name: str | None = None,
 ) -> Filter:
-    """Factory function to create a filter from a function (sync or async)."""
+    """
+    A factory function to create custom filter from a function (sync or async).
+
+    >>> @filters.new
+    ... def is_registered(_: WhatsApp, msg: types.Message) -> bool:
+    ...     return my_db.is_user_registered(msg.from_user.bsuid)
+
+    Using it:
+
+    >>> @wa.on_message(is_registered)
+    ... def only_registered_users(wa: WhatsApp, msg: types.Message):
+    ...     msg.reply("Hello registered user!")
+
+    Or passing the function directly:
+
+    >>> @wa.on_message(filters.new(lambda _, msg: my_db.is_user_registered(msg.from_user.bsuid)))
+    ... def only_registered_users(wa: WhatsApp, msg: types.Message):
+    ...     msg.reply("Hello registered user!")"""
+    if func is None or not callable(func):
+
+        def decorator(f: Callable[[_Wa, _T], bool | Awaitable[bool]]) -> Filter:
+            return new(f, name=name or (func if isinstance(func, str) else None))
+
+        return decorator
 
     is_async = helpers.is_async_callable(func)
 
@@ -264,7 +304,9 @@ def has_async(self) -> bool:
         return is_async
 
     return type(
-        name or func.__name__ or Filter,
+        name or getattr(func, "__name__", None) or Filter.__name__
+        if hasattr(Filter, "__name__")
+        else "Filter",
         (Filter,),
         {
             "check_sync": check_sync,

pywa/types/others.py

@@ -201,10 +201,10 @@ class Contact:
 
     name: Name
     birthday: str | None = None
-    phones: Iterable[Phone] = dataclasses.field(default_factory=tuple)
-    emails: Iterable[Email] = dataclasses.field(default_factory=tuple)
-    urls: Iterable[Url] = dataclasses.field(default_factory=tuple)
-    addresses: Iterable[Address] = dataclasses.field(default_factory=tuple)
+    phones: Sequence[Phone] = dataclasses.field(default_factory=tuple)
+    emails: Sequence[Email] = dataclasses.field(default_factory=tuple)
+    urls: Sequence[Url] = dataclasses.field(default_factory=tuple)
+    addresses: Sequence[Address] = dataclasses.field(default_factory=tuple)
     org: Org | None = None
 
     @classmethod
@@ -398,7 +398,7 @@ class ContactList(tuple[Contact, ...]):
     Represents an shared contacts in a message, which can be iterated over to get the individual contacts.
 
     Attributes:
-        origin: The origin of the shared contacts (e.g. ``contact_request`` if the contacts were shared as a contact request, ``other`` otherwise).
+        origin: The origin of the shared contacts (e.g. ``contact_request`` if the contacts were shared as a contact info request, ``other`` otherwise).
     """
 
     origin: ContactsOrigin
@@ -422,6 +422,11 @@ def first(self) -> Contact:
         """Get the first contact in the list."""
         return self[0]
 
+    @property
+    def first_wa_id(self) -> str | None:
+        """Get the WhatsApp ID of the first contact in the list. Shortcut for ``msg.contacts[0].phones[0].wa_id``."""
+        return self.first.phones[0].wa_id
+
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class ReferredProduct:

pywa_async/api.py

@@ -569,6 +569,7 @@ async def send_marketing_message(
         sender: str,
         to: str,
         recipient: str,
+        recipient_type: str,
         template: dict,
         reply_to_message_id: str | None = None,
         message_activity_sharing: bool | None = None,
@@ -585,6 +586,7 @@ async def send_marketing_message(
             sender: The phone id to send the message from.
             to: The WhatsApp ID to send the message to.
             recipient: The recipient unique identifier (BSUID).
+            recipient_type: The type of the recipient (e.g. ``individual``, ``group``).
             template: The template object to send.
             reply_to_message_id: The ID of the message to reply to.
             message_activity_sharing: Toggles on / off sharing message activities (e.g. message read) for that specific marketing message to Meta to help optimize marketing messages.
@@ -596,7 +598,7 @@ async def send_marketing_message(
         """
         body = self._filter_none(
             messaging_product="whatsapp",
-            recipient_type="individual",
+            recipient_type=recipient_type,
             to=to,
             type="template",
             template=template,

tests/test_filters.py

@@ -327,6 +327,52 @@ def test_filters():
                         ) from e
 
 
+def test_new():
+    @fil.new
+    def my_filter(_, __): ...
+
+    assert isinstance(my_filter, Filter)
+    assert my_filter.__class__.__name__ == "my_filter"
+
+    @fil.new
+    async def my_filter(_, __): ...
+
+    assert isinstance(my_filter, Filter)
+    assert my_filter.__class__.__name__ == "my_filter"
+
+    @fil.new()
+    def my_filter(_, __): ...
+
+    assert isinstance(my_filter, Filter)
+    assert my_filter.__class__.__name__ == "my_filter"
+
+    @fil.new()
+    async def my_filter(_, __): ...
+
+    assert isinstance(my_filter, Filter)
+    assert my_filter.__class__.__name__ == "my_filter"
+
+    @fil.new("custom_name")
+    def my_filter(_, __): ...
+
+    assert isinstance(my_filter, Filter)
+    assert my_filter.__class__.__name__ == "custom_name"
+
+    @fil.new("custom_name")
+    async def my_filter(_, __): ...
+
+    assert isinstance(my_filter, Filter)
+    assert my_filter.__class__.__name__ == "custom_name"
+
+    my_filter = fil.new(lambda _, __: True)
+    assert isinstance(my_filter, Filter)
+    assert my_filter.__class__.__name__ == "<lambda>"
+
+    my_filter = fil.new(func=lambda _, __: True, name="custom_name")
+    assert isinstance(my_filter, Filter)
+    assert my_filter.__class__.__name__ == "custom_name"
+
+
 def modify_text(msg: Message, to: str):
     return dataclasses.replace(msg, text=to)