Skip to content

helper — Utility helpers

ContextHelper

ContextHelper

Helper for extracting BaseBotContext from Message or CallbackQuery.

Normalizes user_id: if from_user is missing (e.g., a post in a channel), it uses chat_id as a fallback for session uniqueness.

Example 
ctx = ContextHelper.extract_base_context(callback)
director = Director(container=container, state=state,
                    user_id=ctx.user_id, chat_id=ctx.chat_id)
Source code in src/codex_bot/helper/context_helper.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
class ContextHelper:
    """
    Helper for extracting BaseBotContext from Message or CallbackQuery.

    Normalizes user_id: if from_user is missing (e.g., a post in a channel),
    it uses chat_id as a fallback for session uniqueness.

    Example:
        ```python
        ctx = ContextHelper.extract_base_context(callback)
        director = Director(container=container, state=state,
                            user_id=ctx.user_id, chat_id=ctx.chat_id)
        ```
    """

    @staticmethod
    def extract_base_context(event: Message | CallbackQuery) -> BaseBotContext:
        """
        Extracts base IDs from an event.

        Args:
            event: Message or CallbackQuery from the user.

        Returns:
            Immutable BaseBotContext with user_id, chat_id, message_id, thread_id.
        """
        user_id = event.from_user.id if event.from_user else 0
        chat_id = user_id
        message_id: int | None = None
        thread_id: int | None = None

        if isinstance(event, CallbackQuery):
            if isinstance(event.message, Message):
                chat_id = event.message.chat.id
                message_id = event.message.message_id
                thread_id = event.message.message_thread_id
            if user_id == 0:
                user_id = chat_id

        elif isinstance(event, Message):
            chat_id = event.chat.id
            message_id = event.message_id
            thread_id = event.message_thread_id
            if user_id == 0:
                user_id = chat_id

        return BaseBotContext(
            user_id=user_id,
            chat_id=chat_id,
            message_id=message_id,
            message_thread_id=thread_id,
        )

Functions

extract_base_context(event) staticmethod

Extracts base IDs from an event.

Parameters:

Name Type Description Default
event Message | CallbackQuery

Message or CallbackQuery from the user.

 required

Returns:

Type Description
BaseBotContext

Immutable BaseBotContext with user_id, chat_id, message_id, thread_id.
Source code in src/codex_bot/helper/context_helper.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
@staticmethod
def extract_base_context(event: Message | CallbackQuery) -> BaseBotContext:
    """
    Extracts base IDs from an event.

    Args:
        event: Message or CallbackQuery from the user.

    Returns:
        Immutable BaseBotContext with user_id, chat_id, message_id, thread_id.
    """
    user_id = event.from_user.id if event.from_user else 0
    chat_id = user_id
    message_id: int | None = None
    thread_id: int | None = None

    if isinstance(event, CallbackQuery):
        if isinstance(event.message, Message):
            chat_id = event.message.chat.id
            message_id = event.message.message_id
            thread_id = event.message.message_thread_id
        if user_id == 0:
            user_id = chat_id

    elif isinstance(event, Message):
        chat_id = event.chat.id
        message_id = event.message_id
        thread_id = event.message_thread_id
        if user_id == 0:
            user_id = chat_id

    return BaseBotContext(
        user_id=user_id,
        chat_id=chat_id,
        message_id=message_id,
        message_thread_id=thread_id,
    )