pararamio-aio 2.1.1__py3-none-any.whl

pararamio_aio/__init__.py

@@ -0,0 +1,78 @@
+"""Async Python client library for pararam.io platform."""
+
+from pararamio_aio._core.constants import VERSION
+
+from ._types import (
+    BotProfileT,
+    PostMetaFileT,
+    PostMetaUserT,
+    ProfileTypeT,
+    QuoteRangeT,
+    TextParsedT,
+)
+from .client import AsyncPararamio
+from .cookie_manager import (
+    AsyncCookieManager,
+    AsyncFileCookieManager,
+    AsyncInMemoryCookieManager,
+    AsyncRedisCookieManager,
+)
+from .exceptions import (
+    PararamioAuthenticationException,
+    PararamioException,
+    PararamioHTTPRequestException,
+    PararamioValidationException,
+)
+from .models import (
+    Activity,
+    ActivityAction,
+    AsyncPararamioBot,
+    Attachment,
+    Chat,
+    DeferredPost,
+    File,
+    Group,
+    Poll,
+    PollOption,
+    Post,
+    Team,
+    TeamMember,
+    TeamMemberStatus,
+    User,
+    UserSearchResult,
+)
+
+__version__ = VERSION
+__all__ = (
+    "Activity",
+    "ActivityAction",
+    "Attachment",
+    "AsyncCookieManager",
+    "AsyncFileCookieManager",
+    "AsyncInMemoryCookieManager",
+    "AsyncPararamio",
+    "AsyncPararamioBot",
+    "AsyncRedisCookieManager",
+    "BotProfileT",
+    "Chat",
+    "DeferredPost",
+    "File",
+    "Group",
+    "PararamioException",
+    "PararamioAuthenticationException",
+    "PararamioHTTPRequestException",
+    "PararamioValidationException",
+    "Poll",
+    "PollOption",
+    "Post",
+    "PostMetaFileT",
+    "PostMetaUserT",
+    "ProfileTypeT",
+    "QuoteRangeT",
+    "Team",
+    "TeamMember",
+    "TeamMemberStatus",
+    "TextParsedT",
+    "User",
+    "UserSearchResult",
+)

pararamio_aio/_core/__init__.py

@@ -0,0 +1,125 @@
+"""Core components for pararamio packages."""
+
+from ._types import *
+from .base import *
+from .client_protocol import *
+from .constants import *
+from .constants.endpoints import *
+from .cookie_decorator import CookieManagerMixin, auth_required, with_auth_retry
+from .cookie_manager import (
+    AsyncCookieManager,
+    AsyncFileCookieManager,
+    AsyncInMemoryCookieManager,
+    AsyncRedisCookieManager,
+    CookieManager,
+    FileCookieManager,
+    InMemoryCookieManager,
+    RedisCookieManager,
+)
+from .endpoints import *
+from .exceptions import *
+from .exceptions.auth import *
+from .models import *
+from .utils.auth_flow import AuthenticationFlow, AuthenticationResult, generate_otp
+from .utils.http_client import (
+    HTTPClientConfig,
+    RateLimitHandler,
+    RequestResult,
+    build_url,
+    prepare_headers,
+    should_retry_request,
+)
+from .validators import *
+
+# Version
+__version__ = VERSION
+
+__all__ = [
+    'AUTH_ENDPOINTS',
+    'AUTH_INIT_URL',
+    'AUTH_LOGIN_URL',
+    'AUTH_NEXT_URL',
+    'AUTH_TOTP_URL',
+    'CHAT_ENDPOINTS',
+    'FILE_ENDPOINTS',
+    'POSTS_LIMIT',
+    'POST_ENDPOINTS',
+    # Endpoints
+    'USER_ENDPOINTS',
+    # Constants
+    'XSRF_HEADER_NAME',
+    'AsyncClientProtocol',
+    'AsyncCookieManager',
+    'AsyncFileCookieManager',
+    'AsyncInMemoryCookieManager',
+    'AsyncRedisCookieManager',
+    # Authentication exceptions
+    'AuthenticationException',
+    'AuthenticationFlow',
+    'AuthenticationResult',
+    'BaseClientObject',
+    'BaseEvent',
+    'BaseLoadedAttrMetaClass',
+    'BaseLoadedAttrPararamObject',
+    # Base classes
+    'BasePararamObject',
+    'CaptchaRequiredException',
+    # Client protocols
+    'ClientProtocol',
+    'CookieJarT',
+    # Cookie management
+    'CookieManager',
+    'CookieManagerMixin',
+    # Core models
+    'CoreBaseModel',
+    'CoreChat',
+    'CoreClientObject',
+    'CorePost',
+    'CoreUser',
+    'FileCookieManager',
+    'FormatterT',
+    # HTTP client utilities
+    'HTTPClientConfig',
+    'HeaderLikeT',
+    'InMemoryCookieManager',
+    'InvalidCredentialsException',
+    'MetaReplyT',
+    'PararamNotFound',
+    # Exceptions
+    'PararamioException',
+    'PararamioHTTPRequestException',
+    'PararamioLimitExceededException',
+    'PararamioMethodNotAllowed',
+    'PararamioRequestException',
+    'PararamioValidationException',
+    'PostMention',
+    'PostMetaFileT',
+    'PostMetaT',
+    'PostMetaThreadT',
+    'PostMetaUserT',
+    # Types
+    'ProfileTypeT',
+    'QuoteRangeT',
+    'RateLimitException',
+    'RateLimitHandler',
+    'RedisCookieManager',
+    'RequestResult',
+    'SecondStepFnT',
+    'SessionExpiredException',
+    'TextParsedT',
+    'TwoFactorFailedException',
+    'TwoFactorRequiredException',
+    'UserInfoParsedItem',
+    'XSRFTokenException',
+    'auth_required',
+    'build_url',
+    # Authentication utilities
+    'generate_otp',
+    'prepare_headers',
+    'should_retry_request',
+    'validate_filename',
+    'validate_ids_list',
+    # Validators
+    'validate_post_load_range',
+    'with_auth_retry',
+]

pararamio_aio/_core/_types.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from http.cookiejar import CookieJar
+from typing import Any, Callable, TypedDict, TypeVar, Union
+
+try:
+    from typing import Literal, NotRequired
+except ImportError:
+    from typing_extensions import Literal, NotRequired
+
+
+class ProfileTypeT(TypedDict):
+    unique_name: str
+    id: int
+    info: str | None
+    find_strict: bool
+    name: str
+    is_google: bool
+    two_step_enabled: bool
+    has_password: bool
+    phoneconfirmed: bool
+    email: str
+    phonenumber: NotRequired[str | None]
+
+
+# noinspection PyUnresolvedReferences
+class TextParsedT(TypedDict):
+    type: str
+    value: str
+    name: NotRequired[str]
+    id: NotRequired[int]
+
+
+# noinspection PyUnresolvedReferences
+class PostMetaUserT(TypedDict):
+    id: int
+    name: str
+    unique_name: str
+    is_bot: NotRequired[bool]
+
+
+class BotProfileT(TypedDict):
+    id: int
+    active: bool
+    deleted: bool
+    email: str | None
+    find_strict: bool
+    has_password: bool
+    info: str | None
+    info_parsed: list
+    info_chat: int
+    is_bot: bool
+    is_google: bool
+    name: str
+    name_trans: str
+    unique_name: str
+    organizations: list
+    phoneconfirmed: bool
+    phonenumber: str | None
+    time_created: str
+    time_updated: str
+    two_step_enabled: bool
+
+
+class PostMetaFileT(TypedDict):
+    name: str
+    guid: str
+    size: int
+    mime_type: str
+    origin: tuple[int, int]
+
+
+class MetaReplyT(TypedDict):
+    text: str
+    user_id: int
+    user_name: str
+    in_thread_no: int
+
+
+class PostMetaThreadT(TypedDict):
+    title: str
+
+
+class PostMetaT(TypedDict):
+    user: PostMetaUserT
+    thread: PostMetaThreadT
+    file: PostMetaFileT
+    reply: MetaReplyT
+    attachments: list[str]
+
+
+class PostMention(TypedDict):
+    id: int
+    name: str
+    value: str
+
+
+class BaseEvent(TypedDict):
+    type: Literal[
+        'GROUP_LEAVED',
+        'GROUP_DELETED',
+        'ORG_MEMBERS',
+        'GROUP_CREATED',
+        'GROUP_UPDATED',
+        'ENTER_TO_THREAD',
+        'CALL',
+        'POST_PINNED',
+        'NEW_THREAD',
+        'EDIT_THREAD',
+        'ENTER_TO_THREAD',
+        'CHAT_TITLE',
+    ]
+    data: dict[str, Any]
+
+
+FormatterT = dict[str, Callable[[dict[str, Any], str], Any]]
+CookieJarT = TypeVar('CookieJarT', bound=CookieJar)
+QuoteRangeT = dict[str, Union[str, int]]
+HeaderLikeT = dict[str, str]
+SecondStepFnT = Callable[[CookieJar, dict[str, str], str], tuple[bool, dict[str, str]]]

pararamio_aio/_core/base.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import contextlib
+from typing import TYPE_CHECKING, Any, Callable
+
+from .utils.helpers import get_formatted_attr_or_load
+
+if TYPE_CHECKING:
+    from ._types import FormatterT
+    from .client_protocol import AsyncClientProtocol, ClientProtocol
+__all__ = (
+    'BaseClientObject',
+    'BaseLoadedAttrMetaClass',
+    'BaseLoadedAttrPararamObject',
+    'BasePararamObject',
+)
+
+DEFAULT_ATTRIBUTES = {
+    '_attr_formatters': {},
+    'load': lambda _: None,
+    '_load_on_key_error': False,
+}
+
+
+# noinspection PyIncorrectDocstring
+def get_loaded_formatted_attr(self, key: str) -> Any:
+    """
+    Fetches a formatted attribute from the object's internal storage.
+
+    If the attribute is not already loaded and '_load_on_key_error' is True,
+    the method attempts to load the attribute first.
+
+    Parameters:
+        key (str): The key corresponding to the desired attribute.
+
+    Returns:
+        Any: The formatted attribute value.
+    """
+    if key in DEFAULT_ATTRIBUTES:
+        return DEFAULT_ATTRIBUTES[key]
+    return get_formatted_attr_or_load(
+        self,
+        key,
+        getattr(self, '_attr_formatters', None),  # pylint: disable=protected-access
+        self.load if self._load_on_key_error else None,  # pylint: disable=protected-access
+    )
+
+
+# noinspection PyIncorrectDocstring
+def get_formatted_attr(self, key: str) -> Any:
+    """
+
+    Retrieves the formatted attribute value for the specified key.
+
+    Parameters:
+        key (str): The attribute key whose formatted value is to be retrieved.
+
+    Returns:
+        Any: The formatted attribute value associated with the given key,
+             or the original attribute value if no formatter is enabled.
+    """
+    if key in DEFAULT_ATTRIBUTES:
+        return DEFAULT_ATTRIBUTES[key]
+    return get_formatted_attr_or_load(self, key, getattr(self, '_attr_formatters', None))
+
+
+def get_formatted_attr_fn(
+    cls: BaseLoadedAttrMetaClass,
+    can_be_loaded: bool = False,
+) -> Any:
+    """
+
+    Determines the appropriate function to get an attribute from a class,
+    potentially loading it if required.
+
+    Returns a function that either retrieves a formatted attribute or
+    loads it if 'load' and '_load_on_key_error' attributes are present in the class.
+
+    Returns:
+        get_formatted_attr_or_load: If the class has both
+                                    'load' and '_load_on_key_error' attributes.
+        get_formatted_attr: Otherwise.
+    """
+    _get_formatted_attr_fn = getattr(cls, '_get_formatted_attr', None)
+    if _get_formatted_attr_fn:
+        return _get_formatted_attr_fn
+    if can_be_loaded:
+        return get_loaded_formatted_attr
+    return get_formatted_attr
+
+
+class BaseLoadedAttrMetaClass(type):
+    """Metaclass for classes that have loaded attributes.
+    Adds a custom __getattr__ method to the class to fetch or load formatted attributes.
+
+    this monkeypatching needs to be done to linter-check
+    class attributes so that undeclared attributes throw an error
+    """
+
+    def __new__(mcs, name, bases, dct):  # pylint: disable=bad-mcs-classmethod-argument
+        """
+
+        Creates a new instance of the class, sets up custom attribute access.
+
+        Parameters:
+          mcs: The class being instantiated.
+          name: The name of the class.
+          bases: The base classes.
+          dct: The class attributes.
+
+        Returns:
+          The new class instance with a custom __getattr__ method.
+        """
+        new_cls = super().__new__(mcs, name, bases, dct)
+        with contextlib.suppress(NameError):
+            new_cls.__getattr__ = get_formatted_attr_fn(
+                new_cls, BaseLoadedAttrPararamObject in bases
+            )
+        return new_cls
+
+
+class BasePararamObject(metaclass=BaseLoadedAttrMetaClass):
+    _data: dict[str, Any]
+    _attr_formatters: FormatterT
+    _get_formatted_attr: Callable[[str], Any]
+
+
+class BaseLoadedAttrPararamObject(BasePararamObject):
+    _load_on_key_error: bool
+
+    def load(self) -> Any:
+        """
+        Load the object from the server.
+        """
+        raise NotImplementedError
+
+
+class BaseClientObject:
+    _client: ClientProtocol | AsyncClientProtocol
+
+    @property
+    def client(self) -> ClientProtocol | AsyncClientProtocol:
+        return self._client

pararamio_aio/_core/client_protocol.py

@@ -0,0 +1,90 @@
+"""Abstract client protocol for both sync and async implementations."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, BinaryIO
+
+__all__ = ['AsyncClientProtocol', 'ClientProtocol']
+
+
+class ClientProtocol(ABC):
+    """Abstract base class defining the interface for both sync and async clients."""
+
+    @abstractmethod
+    def api_get(self, url: str, **kwargs: Any) -> dict[str, Any]:
+        """Make a GET request to the API."""
+
+    @abstractmethod
+    def api_post(
+        self, url: str, data: dict[str, Any] | None = None, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Make a POST request to the API."""
+
+    @abstractmethod
+    def api_put(
+        self, url: str, data: dict[str, Any] | None = None, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Make a PUT request to the API."""
+
+    @abstractmethod
+    def api_delete(
+        self, url: str, data: dict[str, Any] | None = None, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Make a DELETE request to the API."""
+
+    @abstractmethod
+    def upload_file(
+        self,
+        file: BinaryIO | bytes,
+        chat_id: int,
+        filename: str | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Upload a file."""
+
+    @property
+    @abstractmethod
+    def authenticated(self) -> bool:
+        """Check if client is authenticated."""
+
+
+class AsyncClientProtocol(ABC):
+    """Abstract base class for async client implementations."""
+
+    @abstractmethod
+    async def api_get(self, url: str, **kwargs: Any) -> dict[str, Any]:
+        """Make an async GET request to the API."""
+
+    @abstractmethod
+    async def api_post(
+        self, url: str, data: dict[str, Any] | None = None, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Make an async POST request to the API."""
+
+    @abstractmethod
+    async def api_put(
+        self, url: str, data: dict[str, Any] | None = None, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Make an async PUT request to the API."""
+
+    @abstractmethod
+    async def api_delete(
+        self, url: str, data: dict[str, Any] | None = None, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Make an async DELETE request to the API."""
+
+    @abstractmethod
+    async def upload_file(
+        self,
+        file: BinaryIO | bytes,
+        chat_id: int,
+        filename: str | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Upload a file asynchronously."""
+
+    @property
+    @abstractmethod
+    def authenticated(self) -> bool:
+        """Check if client is authenticated."""

pararamio_aio/_core/constants/__init__.py

@@ -0,0 +1,7 @@
+"""Constants module."""
+
+# Export from base constants
+from .base import *
+
+# Export from endpoints
+from .endpoints import *

pararamio_aio/_core/constants/base.py

@@ -0,0 +1,9 @@
+VERSION = '2.1.1'
+BASE_API_URL = 'https://api.pararam.io'
+FILE_UPLOAD_URL = 'https://file.pararam.io'
+DEFAULT_CONNECTION_NAME = '_default'
+DATETIME_FORMAT = '%Y-%m-%dT%H:%M:%S.%fZ'
+XSRF_HEADER_NAME: str = 'X-Xsrftoken'
+UPLOAD_TIMEOUT = 600
+REQUEST_TIMEOUT = 30
+POSTS_LIMIT = 100

pararamio_aio/_core/constants/endpoints.py

@@ -0,0 +1,84 @@
+"""API endpoint constants."""
+
+__all__ = (
+    # Auth endpoints
+    'AUTH_INIT_URL',
+    'AUTH_LOGIN_URL',
+    'AUTH_NEXT_URL',
+    'AUTH_TOTP_URL',
+    'CHAT_BY_ID_URL',
+    # Chat endpoints
+    'CHAT_ENDPOINTS',
+    'CHAT_LIST_URL',
+    'CHAT_POSTS_URL',
+    'CHAT_SEND_URL',
+    'FILE_DELETE_URL',
+    'FILE_DOWNLOAD_URL',
+    # File endpoints
+    'FILE_UPLOAD_URL',
+    'GROUP_BY_ID_URL',
+    'GROUP_JOIN_URL',
+    'GROUP_LEAVE_URL',
+    # Group endpoints
+    'GROUP_LIST_URL',
+    'POST_BY_ID_URL',
+    'POST_CREATE_URL',
+    'POST_DELETE_URL',
+    # Post endpoints
+    'POST_ENDPOINTS',
+    'POST_UPDATE_URL',
+    'USER_BY_ID_URL',
+    # User endpoints
+    'USER_PROFILE_URL',
+    'USER_SEARCH_URL',
+)
+
+# Authentication endpoints
+AUTH_INIT_URL = '/auth/init'
+AUTH_LOGIN_URL = '/auth/login/password'
+AUTH_TOTP_URL = '/auth/totp'
+AUTH_NEXT_URL = '/auth/next'
+
+# User endpoints
+USER_PROFILE_URL = '/user/profile'
+USER_SEARCH_URL = '/user/search'
+USER_BY_ID_URL = '/user/{user_id}'
+
+# Chat endpoints
+CHAT_LIST_URL = '/chat/list'
+CHAT_BY_ID_URL = '/chat/{chat_id}'
+CHAT_POSTS_URL = '/chat/{chat_id}/posts'
+CHAT_SEND_URL = '/chat/{chat_id}/send'
+
+# Grouped chat endpoints for convenience
+CHAT_ENDPOINTS = {
+    'list': CHAT_LIST_URL,
+    'by_id': CHAT_BY_ID_URL,
+    'posts': CHAT_POSTS_URL,
+    'send': CHAT_SEND_URL,
+}
+
+# Post endpoints
+POST_BY_ID_URL = '/post/{post_id}'
+POST_CREATE_URL = '/post/create'
+POST_UPDATE_URL = '/post/{post_id}/update'
+POST_DELETE_URL = '/post/{post_id}/delete'
+
+# Grouped post endpoints for convenience
+POST_ENDPOINTS = {
+    'by_id': POST_BY_ID_URL,
+    'create': POST_CREATE_URL,
+    'update': POST_UPDATE_URL,
+    'delete': POST_DELETE_URL,
+}
+
+# Group endpoints
+GROUP_LIST_URL = '/group/list'
+GROUP_BY_ID_URL = '/group/{group_id}'
+GROUP_JOIN_URL = '/group/{group_id}/join'
+GROUP_LEAVE_URL = '/group/{group_id}/leave'
+
+# File endpoints
+FILE_UPLOAD_URL = '/upload/{perm}'
+FILE_DOWNLOAD_URL = '/download/{guid}/{filename}'
+FILE_DELETE_URL = '/delete/{guid}'