telekit 2.2.0a0__tar.gz → 2.2.0a2__tar.gz

{telekit-2.2.0a0/telekit.egg-info → telekit-2.2.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telekit
-Version: 2.2.0a0
+Version: 2.2.0a2
 Summary: Declarative, developer-friendly library for building Telegram bots
 Home-page: https://github.com/Romashkaa/telekit
 Author: romashka
@@ -378,11 +378,29 @@ It tries to make Telegram bot development easier.
 
 ---
 
-# Changes in version 2.2.0a0
+# Changes in version 2.2.0a2
 
 ## New Button Types
 
-| **Name** | **Description** |
-|----------|-----------------|
-| `AlertButton` | A callback button that shows a popup alert when pressed. |
-| `NotificationButton` | A callback button that shows a brief notification at the top of the chat screen. |
+| **Name**             | **Description**                                          |
+|----------------------|----------------------------------------------------------|
+| `AlertButton`        | A callback button that shows a popup alert when pressed. |
+| `NotificationButton` | A callback button that shows a notification.             |
+
+## User Improvements
+
+| **Name**               | **Description**                                           |
+| ---------------------- | --------------------------------------------------------- |
+| `bio`                  | Bio of the user or description of the chat.               |
+| `birthdate`            | Birthdate of the user, if set and visible.                |
+| `description`          | Description of the group or channel.                      |
+| `mention`              | `tg://user?id=` deep link, works even without a username. |
+| `is_private`           | Whether the message was sent in a private chat.           |
+| `is_group`             | Whether the message was sent in a group.                  |
+| `is_supergroup`        | Whether the message was sent in a supergroup.             |
+| `is_channel`           | Whether the message was sent in a channel.                |
+| `avatar`               | File ID of the user's most recent profile photo.          |
+| `profile_photos_count` | Total number of profile photos the user has set.          |
+
+- Refactor: `User` now accepts a `Message` object instead of `chat_id` + `from_user`. All properties are derived from `_sender` (`from_user` or `chat`) and migrated to `cached_property`. Fixed broken `get_id` and `get_full_name` references.
+- Added `__repr__`.

{telekit-2.2.0a0 → telekit-2.2.0a2}/telekit/_handler.py

@@ -98,7 +98,7 @@ class Handler:
 
     def __init__(self, message: Message):
         self.message: Message = message
-        self.user = User(self.message.chat.id, self.message.from_user)
+        self.user = User(self.message)
         self.new_chain()
 
     def handle(self) -> Any:
@@ -112,7 +112,7 @@ class Handler:
         avoids the need for multiple custom entry methods 
         like `start` or `handle_start`.
         """
-        library.warning("Handler `handle` was called but not overridden; no logic executed.")
+        library.warning(f"`{type(self).__qualname__}().handle()` was called but not overridden; no logic executed.")
         return
 
     # -----------------------------------------------------

{telekit-2.2.0a0 → telekit-2.2.0a2}/telekit/_logger.py

@@ -1,7 +1,7 @@
 import logging
 import sys
 from pathlib import Path
-from typing import Union, Callable, Protocol
+from typing import Union, Callable
 
 # ------------------------------
 # Formatter
@@ -49,31 +49,32 @@ user_logger.addHandler(uch)
 def enable_user_logging(*user_ids: Union[int, str]) -> None:
     _enabled_users.update(user_ids)
 
-class UserLoggerProtocol(Protocol):
-    def info(self, msg: str, *args, **kwargs) -> None: ...
-    def warning(self, msg: str, *args, **kwargs) -> None: ...
-    def debug(self, msg: str, *args, **kwargs) -> None: ...
-    def error(self, msg: str, *args, **kwargs) -> None: ...
-    def critical(self, msg: str, *args, **kwargs) -> None: ...
-
-def _users(user_id: Union[int, str]) -> UserLoggerProtocol:
-    class UserLogger:
-        def info(self, msg, *args, **kwargs):
-            if user_id in _enabled_users:
-                user_logger.info(f"[{user_id}] {msg}", *args, stacklevel=2, **kwargs)
-        def warning(self, msg, *args, **kwargs):
-            if user_id in _enabled_users:
-                user_logger.warning(f"[{user_id}] {msg}", *args, stacklevel=2, **kwargs)
-        def debug(self, msg, *args, **kwargs):
-            if user_id in _enabled_users:
-                user_logger.debug(f"[{user_id}] {msg}", *args, stacklevel=2, **kwargs)
-        def error(self, msg, *args, **kwargs):
-            if user_id in _enabled_users:
-                user_logger.error(f"[{user_id}] {msg}", *args, stacklevel=2, **kwargs)
-        def critical(self, msg, *args, **kwargs):
-            if user_id in _enabled_users:
-                user_logger.critical(f"[{user_id}] {msg}", *args, stacklevel=2, **kwargs)
-    return UserLogger()
+class _UserLogger:
+    """Thin wrapper that prefixes every log line with the user ID."""
+
+    __slots__ = ("_user_id",)
+
+    def __init__(self, user_id: int | str | None) -> None:
+        self._user_id = user_id
+
+    def _log(self, level: int, msg: str, *args, **kwargs) -> None:
+        if self._user_id in _enabled_users:
+            user_logger.log(level, f"[{self._user_id}] {msg}", *args, stacklevel=3, **kwargs)
+
+    def debug(self, msg: str, *args, **kwargs) -> None: 
+        self._log(logging.DEBUG,    msg, *args, **kwargs)
+
+    def info(self, msg: str, *args, **kwargs) -> None: 
+        self._log(logging.INFO,     msg, *args, **kwargs)
+
+    def warning(self, msg: str, *args, **kwargs) -> None: 
+        self._log(logging.WARNING,  msg, *args, **kwargs)
+
+    def error(self, msg: str, *args, **kwargs) -> None: 
+        self._log(logging.ERROR,    msg, *args, **kwargs)
+
+    def critical(self, msg: str, *args, **kwargs) -> None: 
+        self._log(logging.CRITICAL, msg, *args, **kwargs)
 
 # ------------------------------
 # Server Logging
@@ -115,8 +116,8 @@ class LoggerWrapper:
     enable_user_logging: Callable[..., None] = enable_user_logging
     enable_file_logging: Callable[..., None] = enable_file_logging
 
-    def users(self, user_id: int | str):
-        return _users(user_id)
+    def users(self, user_id: int | str | None):
+        return _UserLogger(user_id)
 
 logger: LoggerWrapper = LoggerWrapper()
 

telekit-2.2.0a2/telekit/_user.py

@@ -0,0 +1,199 @@
+# 
+# Copyright (C) 2026 Romashka
+# 
+# This file is part of Telekit.
+# 
+# Telekit is free software: you can redistribute it and/or modify it 
+# under the terms of the GNU General Public License as published by 
+# the Free Software Foundation, either version 3 of the License, or 
+# (at your option) any later version.
+# 
+# Telekit is distributed in the hope that it will be useful, 
+# but WITHOUT ANY WARRANTY; without even the implied warranty 
+# of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See 
+# the GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License 
+# along with Telekit. If not, see <https://www.gnu.org/licenses/>.
+# 
+from functools import cached_property
+from typing import Literal
+
+import telebot
+import telebot.types
+
+from ._logger import logger
+
+__all__ = ["User"]
+
+
+class User:
+
+    bot: telebot.TeleBot
+
+    @classmethod
+    def _init(cls, bot: telebot.TeleBot) -> None:
+        cls.bot = bot
+
+    def __init__(self, message: telebot.types.Message) -> None:
+        self._message: telebot.types.Message = message
+        self._chat_id: int = message.chat.id
+        self.logger = logger.users(self._chat_id)
+
+    # ── Internal ──────────────────────────────────────────────────
+
+    @cached_property
+    def _sender(self) -> telebot.types.User | telebot.types.Chat:
+        """Resolves to `from_user` if available, otherwise falls back to `chat`."""
+        return self._message.from_user or self._message.chat
+
+    # ── Logging ───────────────────────────────────────────────────
+
+    def enable_logging(self, *user_ids: int | str) -> None:
+        """
+        Enable logging for this user or for additional user IDs.
+        If no arguments are passed, enables logging for this instance's chat ID.
+        """
+        logger.enable_user_logging(*(user_ids or (self._chat_id,)))
+
+    # ── Telegram native fields ────────────────────────────────────
+
+    @property
+    def id(self) -> int:
+        """Unique identifier of the user or chat."""
+        return self._sender.id
+
+    @property
+    def username(self) -> str | None:
+        """Telegram username without the leading `@`, or `None` if not set."""
+        return self._sender.username
+
+    @cached_property
+    def first_name(self) -> str | None:
+        """First name of the user, or the group/channel title as a fallback."""
+        if isinstance(self._sender, telebot.types.User):
+            return self._sender.first_name
+        return self._sender.first_name or self._sender.title
+
+    @property
+    def last_name(self) -> str | None:
+        """Last name of the user, or `None` for chats and users without one."""
+        return self._sender.last_name
+
+    @cached_property
+    def is_bot(self) -> bool:
+        """Whether the sender is a bot. Always `False` for chats."""
+        if isinstance(self._sender, telebot.types.User):
+            return self._sender.is_bot
+        return False
+
+    @cached_property
+    def language_code(self) -> str | None:
+        """
+        IETF language code of the user's Telegram client (e.g. `"en"`, `"uk"`).
+        Always `None` for chats.
+        """
+        if isinstance(self._sender, telebot.types.User):
+            return self._sender.language_code
+        return None
+
+    @cached_property
+    def is_premium(self) -> bool:
+        """Whether the user has an active Telegram Premium subscription.
+        Always `False` for chats and bots.
+        """
+        if isinstance(self._sender, telebot.types.User):
+            return bool(self._sender.is_premium)
+        return False
+
+    @cached_property
+    def added_to_attachment_menu(self) -> bool:
+        """Whether this bot has been added to the user's attachment menu.
+        Always `False` for chats.
+        """
+        if isinstance(self._sender, telebot.types.User):
+            return bool(self._sender.added_to_attachment_menu)
+        return False
+
+    @property
+    def chat_type(self) -> Literal["private", "group", "supergroup", "channel"]:
+        """Type of the chat the message was sent in."""
+        return self._message.chat.type  # pyright: ignore[reportReturnType]
+
+    @property
+    def bio(self) -> str | None:
+        """Bio of the user or description of the chat, as set in Telegram."""
+        return self._message.chat.bio
+
+    @property
+    def birthdate(self) -> telebot.types.Birthdate | None:
+        """Birthdate of the user, if set and visible."""
+        return self._message.chat.birthdate
+
+    @property
+    def description(self) -> str | None:
+        """Description of the group or channel. `None` for private chats."""
+        return self._message.chat.description
+
+    # ── Computed helpers ──────────────────────────────────────────
+
+    @cached_property
+    def full_name(self) -> str | None:
+        """Full name of the user (`first_name + last_name`), or the chat title.
+        Returns `None` if neither is available.
+        """
+        if isinstance(self._sender, telebot.types.User):
+            return self._sender.full_name
+        return " ".join(filter(None, [self.first_name, self.last_name])) or None
+
+    @property
+    def mention(self) -> str:
+        """
+        A `tg://user?id=` deep link that mentions the user in any context,
+        even without a username.
+        """
+        return f"tg://user?id={self.id}"
+
+    @property
+    def is_private(self) -> bool:
+        """Whether the message was sent in a private chat."""
+        return self.chat_type == "private"
+
+    @property
+    def is_group(self) -> bool:
+        """Whether the message was sent in a group chat."""
+        return self.chat_type == "group"
+
+    @property
+    def is_supergroup(self) -> bool:
+        """Whether the message was sent in a supergroup."""
+        return self.chat_type == "supergroup"
+
+    @property
+    def is_channel(self) -> bool:
+        """Whether the message was sent in a channel."""
+        return self.chat_type == "channel"
+
+    @property
+    def avatar(self) -> str | None:
+        """
+        File ID of the user's most recent profile photo, or `None` if not set.
+        Makes an API call each time — cache the result if called frequently.
+        """
+        photos = self.bot.get_user_profile_photos(self.id, limit=1)
+        if photos.total_count == 0:
+            return None
+        return photos.photos[0].file_id
+
+    @property
+    def profile_photos_count(self) -> int:
+        """
+        Total number of profile photos the user has set.
+        Makes an API call each time.
+        """
+        return self.bot.get_user_profile_photos(self.id).total_count
+
+    # ── Dunder ────────────────────────────────────────────────────
+
+    def __repr__(self) -> str:
+        return f"User(id={self.id}, username={self.username!r})"

{telekit-2.2.0a0 → telekit-2.2.0a2}/telekit/_version.py

@@ -1,5 +1,6 @@
 # ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 # PyPI package version: https://img.shields.io/pypi/v/telekit.svg
+# PyPI history: https://pypi.org/project/telekit/#history
 # ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 
-__version__ = "2.2.0a0"
+__version__ = "2.2.0a2"

{telekit-2.2.0a0 → telekit-2.2.0a2}/telekit/example/example_handlers/entry.py

@@ -63,9 +63,7 @@ class EntryHandler(telekit.Handler):
         # Priority:
         # 1. Previous response (internal database)
         # 2. Telegram username (fallback)
-        name: str | None = self._user_data.get_name(
-            default=self.user.username
-        )
+        name: str | None = self._user_data.get_name() or self.user.username
         
         if name:
             self.chain.set_entry_suggestions([name])

{telekit-2.2.0a0 → telekit-2.2.0a2}/telekit/types.py

@@ -26,11 +26,13 @@ from .utils import format_file_size
 
 from ._user import User
 from ._inline_buttons import (
+    ButtonStyle,
     InlineButton, 
     LinkButton, WebAppButton, 
     CopyTextButton, SuggestButton, 
     CallbackButton, 
-    ButtonStyle
+    AlertButton,
+    NotificationButton
 )
 
 from .styles import Styles, TextEntity, StaticTextEntity, EasyTextEntity
@@ -168,6 +170,8 @@ __all__ = [
     "CopyTextButton",
     "SuggestButton",
     "CallbackButton",
+    "AlertButton",
+    "NotificationButton",
 
     "ButtonStyle",
 

{telekit-2.2.0a0 → telekit-2.2.0a2/telekit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telekit
-Version: 2.2.0a0
+Version: 2.2.0a2
 Summary: Declarative, developer-friendly library for building Telegram bots
 Home-page: https://github.com/Romashkaa/telekit
 Author: romashka
@@ -378,11 +378,29 @@ It tries to make Telegram bot development easier.
 
 ---
 
-# Changes in version 2.2.0a0
+# Changes in version 2.2.0a2
 
 ## New Button Types
 
-| **Name** | **Description** |
-|----------|-----------------|
-| `AlertButton` | A callback button that shows a popup alert when pressed. |
-| `NotificationButton` | A callback button that shows a brief notification at the top of the chat screen. |
+| **Name**             | **Description**                                          |
+|----------------------|----------------------------------------------------------|
+| `AlertButton`        | A callback button that shows a popup alert when pressed. |
+| `NotificationButton` | A callback button that shows a notification.             |
+
+## User Improvements
+
+| **Name**               | **Description**                                           |
+| ---------------------- | --------------------------------------------------------- |
+| `bio`                  | Bio of the user or description of the chat.               |
+| `birthdate`            | Birthdate of the user, if set and visible.                |
+| `description`          | Description of the group or channel.                      |
+| `mention`              | `tg://user?id=` deep link, works even without a username. |
+| `is_private`           | Whether the message was sent in a private chat.           |
+| `is_group`             | Whether the message was sent in a group.                  |
+| `is_supergroup`        | Whether the message was sent in a supergroup.             |
+| `is_channel`           | Whether the message was sent in a channel.                |
+| `avatar`               | File ID of the user's most recent profile photo.          |
+| `profile_photos_count` | Total number of profile photos the user has set.          |
+
+- Refactor: `User` now accepts a `Message` object instead of `chat_id` + `from_user`. All properties are derived from `_sender` (`from_user` or `chat`) and migrated to `cached_property`. Fixed broken `get_id` and `get_full_name` references.
+- Added `__repr__`.

telekit-2.2.0a0/telekit/_user.py

@@ -1,138 +0,0 @@
-# 
-# Copyright (C) 2026 Romashka
-# 
-# This file is part of Telekit.
-# 
-# Telekit is free software: you can redistribute it and/or modify it 
-# under the terms of the GNU General Public License as published by 
-# the Free Software Foundation, either version 3 of the License, or 
-# (at your option) any later version.
-# 
-# Telekit is distributed in the hope that it will be useful, 
-# but WITHOUT ANY WARRANTY; without even the implied warranty 
-# of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See 
-# the GNU General Public License for more details.
-# 
-# You should have received a copy of the GNU General Public License 
-# along with Telekit. If not, see <https://www.gnu.org/licenses/>.
-# 
-
-import telebot.types
-import telebot
-
-from ._logger import logger
-
-__all__ = ["User"]
-
-
-class User:
-
-    bot: telebot.TeleBot
-    
-    @classmethod
-    def _init(cls, bot: telebot.TeleBot):
-        """
-        Initializes the bot instance for the class.
-
-        Args:
-            bot (TeleBot): The Telegram bot instance to be used for sending messages.
-        """
-        cls.bot = bot
-
-    def __init__(self, chat_id: int, from_user: telebot.types.User | None):
-        self.chat_id = chat_id
-        self.from_user = from_user
-
-        self.logger = logger.users(self.chat_id)
-
-    def enable_logging(self, *user_ids: int | str):
-        """
-        Enable logging for this user or for additional user IDs.
-
-        If no arguments are passed, enables logging for this instance's chat_id.
-        """
-        if user_ids:
-            logger.enable_user_logging(*user_ids)
-        else:
-            logger.enable_user_logging(self.chat_id)
-
-    # Chat Full Info
-
-    def get_chat_full_info(self) -> telebot.types.ChatFullInfo | None:
-        try:
-            return self.bot.get_chat(self.chat_id)
-        except:
-            return None
-        
-    @property
-    def chat_full_info(self) -> telebot.types.ChatFullInfo | None:
-        # Equivalent to `get_chat_full_info()` but the result is cached so only one API call is needed.
-        if not hasattr(self, "_chat_full_info"):
-            self._chat_full_info = self.get_chat_full_info()
-        
-        return self._chat_full_info
-
-    # Username
-
-    def get_username(self) -> str | None:
-        if chat := self.get_chat_full_info():
-            return chat.username
-    
-    @property
-    def username(self) -> str | None:
-        if not hasattr(self, "_username"):
-            self._username = self.get_username()
-        
-        return self._username
-    
-    # First Name
-
-    def get_first_name(self) -> str | None:
-        if chat := self.get_chat_full_info():
-            return chat.first_name
-    
-    @property
-    def first_name(self) -> str | None:
-        if not hasattr(self, "_first_name"):
-            self._first_name = self.get_first_name()
-        
-        return self._first_name
-    
-    # Last Name
-
-    def get_last_name(self) -> str | None:
-        if chat := self.get_chat_full_info():
-            return chat.last_name
-    
-    @property
-    def last_name(self) -> str | None:
-        if not hasattr(self, "_last_name"):
-            self._last_name = self.get_last_name()
-        
-        return self._last_name
-    
-    # Full Name
-
-    def get_full_name(self) -> str | None:
-        if chat := self.from_user: # TODO
-            return chat.full_name
-    
-    @property
-    def full_name(self) -> str | None:
-        if not hasattr(self, "_full_name"):
-            self._full_name = self.get_full_name()
-        
-        return self._full_name
-    
-    # User ID
-
-    def get_id(self) -> int | None:
-        if chat := self.from_user: # TODO
-            return chat.id # TODO
-    
-    @property
-    def id(self) -> int | None:
-        if not hasattr(self, "_id"):
-            self._id = self.get_id()
-        
-        return self._id