Groups

Bases: SignalAPIError

Raised when fetching group data from the API fails.

Bases: GroupEntry

A group the bot is a member of, as returned by GroupRegistry.

Fields:

• admins (list[str])
• blocked (bool)
• description (str)
• id (str)
• internal_id (str)
• invite_link (str)
• members (list[str])
• name (str)
• pending_invites (list[str])
• pending_requests (list[str])
• permissions (GroupPermissions)

Bases: GroupPermissions

Who is allowed to perform which actions in a group.

Fields:

• add_members (AddMembers)
• edit_group (EditGroup)
• send_messages (SendMessages)

List-like cache of the groups the bot is a member of, with lookup helpers.

To update a group's metadata, use actions (bot.groups.actions) instead.

26
27
28
29
30
31
32

def __init__(self, signal: SignalAPI, logger: logging.Logger) -> None:
    self._signal = signal
    self._logger = logger

    self._by_id: dict[str, GroupEntry] = {}
    self._by_internal_id: dict[str, GroupEntry] = {}
    self._by_name: defaultdict[str, list[GroupEntry]] = defaultdict(list)

actions: GroupActions

get(internal_id: str) -> GroupEntry | None

46
47
48
49
50
51
52
53
54
55
56
57
58

def get(self, internal_id: str) -> GroupEntry | None:
    """Look up a cached group by its internal id, without hitting the network.

    Args:
        internal_id: The group's internal id, as used by `__iter__`,
            `__getitem__`, and `refresh()`/`refresh_one()`.

    Returns:
        The cached `GroupEntry`, or `None` if it isn't in the cache.
    """
    if internal_id in self._by_internal_id:
        return copy.deepcopy(self._by_internal_id[internal_id])
    return None

get_id(internal_id: str) -> str | None

60
61
62
63
64
65
66
67
68
69
70
71
72

def get_id(self, internal_id: str) -> str | None:
    """Look up a group's canonical id by its internal id, without copying
    the full `GroupEntry`. For hot-path callers (e.g. per-message,
    per-handler dispatch checks) that only need the id.

    Args:
        internal_id: The group's internal id.

    Returns:
        The group's canonical id, or `None` if it isn't in the cache.
    """
    group = self._by_internal_id.get(internal_id)
    return group.id if group is not None else None

Bases: BaseMessage

Notification that a group's metadata (name, members, ...) was updated.

Fields:

• server_delivered_timestamp (int)
• server_received_timestamp (int)
• source (str | None)
• source_device (int | None)
• source_name (str | None)
• source_number (str | None)
• source_uuid (str | None)
• timestamp (int)
• group_info (GroupUpdateInfo)

Bases: BaseModel

The group metadata attached to a group-update event.

Fields:

• group_id (str)
• group_name (str)
• revision (int)
• type (Literal['UPDATE'])

Bases: BaseModel

The fields to change on a group. If a field is None, it is left unchanged.

Fields:

• avatar (PydanticPath | str | None)
• description (str | None)
• expiration_in_seconds (int | None)
• group_link (GroupLink | None)
• name (str | None)
• permissions (GroupPermissions | None)

avatar: PydanticPath | str | None = None

description: str | None = None

expiration_in_seconds: int | None = None

group_link: GroupLink | None = None

name: str | None = None

permissions: GroupPermissions | None = None

Bases: SignalAPIError

Raised when the API rejects a group metadata update.

Bases: StrEnum

Bases: StrEnum

Bases: StrEnum

Bases: StrEnum