pararamio-aio 2.1.1__py3-none-any.whl

pararamio_aio/_core/utils/authentication.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+import binascii
+import json
+import logging
+import time
+from typing import TYPE_CHECKING, Any
+from urllib.error import HTTPError
+
+from pararamio_aio._core import exceptions as ex
+from pararamio_aio._core.constants import XSRF_HEADER_NAME
+from pararamio_aio._core.exceptions import RateLimitException
+from pararamio_aio._core.utils.http_client import RateLimitHandler
+
+from .auth_flow import generate_otp
+from .requests import api_request, raw_api_request
+
+if TYPE_CHECKING:
+    from http.cookiejar import CookieJar
+
+    from pararamio_aio._core._types import HeaderLikeT, SecondStepFnT
+
+__all__ = (
+    'authenticate',
+    'do_second_step',
+    'do_second_step_with_code',
+    'get_xsrf_token',
+)
+
+XSFR_URL = INIT_URL = '/auth/init'
+LOGIN_URL = '/auth/login/password'
+TWO_STEP_URL = '/auth/totp'
+AUTH_URL = '/auth/next'
+log = logging.getLogger('pararamio')
+
+
+def get_xsrf_token(cookie_jar: CookieJar) -> str:
+    _, headers = raw_api_request(XSFR_URL, cookie_jar=cookie_jar)
+    for key, value in headers:
+        if key.lower() == 'x-xsrftoken':
+            return value
+    msg = f'XSFR Header was not found in {XSFR_URL} url'
+    raise ex.PararamioXSFRRequestError(msg)
+
+
+def do_init(cookie_jar: CookieJar, headers: dict) -> tuple[bool, dict]:
+    try:
+        return True, api_request(
+            INIT_URL,
+            method='GET',
+            headers=headers,
+            cookie_jar=cookie_jar,
+        )
+    except HTTPError as e:
+        if e.code < 500:
+            return False, json.loads(e.read())
+        raise
+
+
+def do_login(login: str, password: str, cookie_jar: CookieJar, headers: dict) -> tuple[bool, dict]:
+    try:
+        return True, api_request(
+            LOGIN_URL,
+            method='POST',
+            data={'email': login, 'password': password},
+            headers=headers,
+            cookie_jar=cookie_jar,
+        )
+    except HTTPError as e:
+        if e.code < 500:
+            return False, json.loads(e.read())
+        raise
+
+
+def do_taking_secret(cookie_jar: CookieJar, headers: dict) -> tuple[bool, dict]:
+    try:
+        return True, api_request(
+            AUTH_URL,
+            method='GET',
+            headers=headers,
+            cookie_jar=cookie_jar,
+        )
+    except HTTPError as e:
+        if e.code < 500:
+            return False, json.loads(e.read())
+        raise
+
+
+def do_second_step(cookie_jar: CookieJar, headers: dict, key: str) -> tuple[bool, dict[str, str]]:
+    """
+    do second step pararam login with TFA key or raise Exception
+    :param cookie_jar: cookie container
+    :param headers: headers to send
+    :param key: key to generate one time code
+    :return: True if login success
+    """
+    if not key:
+        msg = 'key can not be empty'
+        raise ex.PararamioSecondFactorAuthenticationException(msg)
+    try:
+        key = generate_otp(key)
+    except binascii.Error as e:
+        msg = 'Invalid second step key'
+        raise ex.PararamioSecondFactorAuthenticationException(msg) from e
+    try:
+        resp = api_request(
+            TWO_STEP_URL,
+            method='POST',
+            data={'code': key},
+            headers=headers,
+            cookie_jar=cookie_jar,
+        )
+    except HTTPError as e:
+        if e.code < 500:
+            return False, json.loads(e.read())
+        raise
+    return True, resp
+
+
+def do_second_step_with_code(
+    cookie_jar: CookieJar, headers: dict[str, str], code: str
+) -> tuple[bool, dict[str, str]]:
+    """
+    do second step pararam login with TFA code or raise Exception
+    :param cookie_jar: cookie container
+    :param headers: headers to send
+    :param code: 6 digits code
+    :return:  True if login success
+    """
+    if not code:
+        msg = 'code can not be empty'
+        raise ex.PararamioSecondFactorAuthenticationException(msg)
+    if len(code) != 6:
+        msg = 'code must be 6 digits len'
+        raise ex.PararamioSecondFactorAuthenticationException(msg)
+    try:
+        resp = api_request(
+            TWO_STEP_URL,
+            method='POST',
+            data={'code': code},
+            headers=headers,
+            cookie_jar=cookie_jar,
+        )
+    except HTTPError as e:
+        if e.code < 500:
+            return False, json.loads(e.read())
+        raise
+    return True, resp
+
+
+def _handle_rate_limit(wait_auth_limit: bool) -> None:
+    """Handle rate limiting before authentication."""
+    rate_limit_handler = RateLimitHandler()
+    should_wait, wait_seconds = rate_limit_handler.should_wait()
+    if should_wait:
+        if wait_auth_limit:
+            time.sleep(wait_seconds)
+        else:
+            msg = f'Rate limit exceeded. Retry after {wait_seconds} seconds'
+            raise RateLimitException(msg, retry_after=wait_seconds)
+
+
+def _handle_captcha(
+    login: str, password: str, cookie_jar: CookieJar, headers: dict[str, Any], resp: dict[str, Any]
+) -> tuple[bool, tuple[bool, dict[str, Any]]]:
+    """Handle captcha requirement during authentication.
+
+    Returns:
+        Tuple of (was_captcha_required, (success, response))
+    """
+    if resp.get('codes', {}).get('non_field', '') != 'captcha_required':
+        return False, (False, resp)
+
+    try:
+        from pararamio_aio._core.utils.captcha import (  # pylint: disable=import-outside-toplevel
+            show_captcha,
+        )
+
+        success = show_captcha(f'login:{login}', headers, cookie_jar)
+        if not success:
+            msg = 'Captcha required'
+            raise ex.PararamioCaptchaAuthenticationException(msg)
+        return True, do_login(login, password, cookie_jar, headers)
+    except ImportError as e:
+        msg = 'Captcha required, but exception when show it'
+        raise ex.PararamioCaptchaAuthenticationException(msg) from e
+
+
+def authenticate(
+    login: str,
+    password: str,
+    cookie_jar: CookieJar,
+    headers: HeaderLikeT | None = None,
+    second_step_fn: SecondStepFnT | None = do_second_step,
+    second_step_arg: str | None = None,
+    wait_auth_limit: bool = False,
+) -> tuple[bool, dict[str, Any], str]:
+    # Handle rate limiting
+    _handle_rate_limit(wait_auth_limit)
+
+    if not headers or XSRF_HEADER_NAME not in headers:
+        if headers is None:
+            headers = {}
+        headers[XSRF_HEADER_NAME] = get_xsrf_token(cookie_jar)
+
+    success, resp = do_login(login, password, cookie_jar, headers)
+
+    # Handle captcha if required
+    captcha_handled, captcha_result = _handle_captcha(login, password, cookie_jar, headers, resp)
+    if captcha_handled:
+        success, resp = captcha_result
+
+    if not success and resp.get('error', 'xsrf'):
+        log.debug('invalid xsrf trying to get new one')
+        headers[XSRF_HEADER_NAME] = get_xsrf_token(cookie_jar)
+        success, resp = do_login(login, password, cookie_jar, headers)
+
+    if not success:
+        log.error('authentication failed: %s', resp.get('error', ''))
+        msg = 'Login, password authentication failed'
+        raise ex.PararamioPasswordAuthenticationException(msg)
+
+    if second_step_fn is not None and second_step_arg:
+        success, resp = second_step_fn(cookie_jar, headers, second_step_arg)
+        if not success:
+            msg = 'Second factor authentication failed'
+            raise ex.PararamioSecondFactorAuthenticationException(msg)
+
+    success, resp = do_taking_secret(cookie_jar, headers)
+    if not success:
+        msg = 'Taking secret failed'
+        raise ex.PararamioAuthenticationException(msg)
+
+    success, resp = do_init(cookie_jar, headers)
+    return True, {'user_id': resp.get('user_id')}, headers[XSRF_HEADER_NAME]

pararamio_aio/_core/utils/captcha.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import base64
+from typing import TYPE_CHECKING
+from urllib.error import HTTPError
+from urllib.parse import urlencode
+
+from ..constants import REQUEST_TIMEOUT as TIMEOUT
+from .requests import _base_request, api_request
+
+if TYPE_CHECKING:
+    from http.cookiejar import CookieJar
+
+__all__ = ['get_captcha_img', 'verify_captcha']
+
+
+def get_captcha_img(
+    id_: str,
+    headers: dict | None = None,
+    cookie_jar: CookieJar | None = None,
+    timeout: int = TIMEOUT,
+) -> bytes:  # returns tk.PhotoImage
+    """
+    Fetch and return a captcha image as bytes from the server based on the provided id.
+    The function retries the request a predetermined number of times if met with HTTPError,
+    and encodes the resulting image data in base64 format before returning it.
+
+    Parameters:
+        id_ (str): The unique identifier for the captcha to be retrieved.
+        headers (dict | None, optional): Additional headers to include in the request.
+        cookie_jar (CookieJar | None, optional): Cookie storage for handling session cookies.
+        timeout (int, optional): Duration (in seconds) before the request times out.
+
+    Returns:
+        bytes: The base64-encoded bytes of the captcha image.
+    """
+    args = urlencode({'id': id_})
+    url = f'/auth/captcha?{args}'
+    tc = 3
+    data = None
+    while True:
+        try:
+            data = _base_request(
+                url, headers=headers, cookie_jar=cookie_jar, timeout=timeout
+            ).read()
+            break
+        except HTTPError:
+            if not tc:
+                raise
+            tc -= 1
+            continue
+    return base64.b64encode(data)
+
+
+def verify_captcha(
+    code: str,
+    headers: dict | None = None,
+    cookie_jar: CookieJar | None = None,
+    timeout: int = TIMEOUT,
+) -> bool:
+    """
+    Verify CAPTCHA with the server.
+
+    This function sends a POST request to the '/auth/captcha' endpoint to
+    verify a given CAPTCHA code. It allows passing optional headers, a
+    cookie jar, and a timeout value for the request. The function returns
+    a boolean indicating whether the CAPTCHA verification was successful.
+
+    Parameters:
+        code: str
+            The CAPTCHA code to be verified.
+        headers: dict | None
+            Optional HTTP headers to be included in the request.
+        cookie_jar: CookieJar | None
+            Optional cookie jar to manage cookies during the request.
+        timeout: int
+            The timeout for the request in seconds.
+
+    Returns:
+        bool
+            True if the CAPTCHA verification was successful, False otherwise.
+    """
+    url = '/auth/captcha'
+    resp = api_request(
+        url,
+        'POST',
+        data={'code': code},
+        headers=headers,
+        cookie_jar=cookie_jar,
+        timeout=timeout,
+    )
+    return str.lower(resp.get('status', '')) == 'ok'

pararamio_aio/_core/utils/helpers.py

@@ -0,0 +1,336 @@
+from __future__ import annotations
+
+import hashlib
+import math
+import uuid
+from datetime import datetime, timezone
+from html import unescape
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    TypeVar,
+    cast,
+)
+
+from ..constants import DATETIME_FORMAT
+from ..exceptions import PararamioValidationException, PararamModelNotLoaded
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Sequence
+    from datetime import timedelta
+
+    from pararamio_aio._core._types import FormatterT
+
+__all__ = (
+    'check_login_opts',
+    'encode_chat_id',
+    'encode_digit',
+    'format_datetime',
+    'format_or_none',
+    'get_empty_vars',
+    'get_formatted_attr_or_load',
+    'get_utc',
+    'join_ids',
+    'lazy_loader',
+    'parse_datetime',
+    'parse_iso_datetime',
+    'unescape_dict',
+)
+
+
+def check_login_opts(login: str | None, password: str | None) -> bool:
+    """
+    Check if both login and password options are provided and not empty.
+
+    Parameters:
+    login (Optional[str]): The login string to check.
+    password (Optional[str]): The password string to check.
+
+    Returns:
+    bool: True if both login and password are provided and not empty, False otherwise.
+    """
+    return all(map(bool, [login, password]))
+
+
+def get_empty_vars(**kwargs: Any):
+    """
+    Identifies and returns a comma-separated string of keys from the keyword
+    arguments where the corresponding values are empty.
+
+    Parameters:
+        **kwargs (Any): Arbitrary keyword arguments with values to be checked.
+
+    Returns:
+        str: A comma-separated string of keys with empty values.
+    """
+    return ', '.join([k for k, v in kwargs.items() if not v])
+
+
+def encode_digit(digit: int, res: str = '') -> str:
+    """
+    Encodes a given integer into a custom base-64-like string.
+
+    Parameters:
+    digit (int): The integer to be encoded.
+    res (str): The resulting encoded string, used internally for recursion.
+
+    Returns:
+    str: The encoded string representation of the given integer.
+    """
+    if not isinstance(digit, int):
+        digit = int(digit)
+    # noinspection SpellCheckingInspection
+    code_string = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_.'
+    result = math.floor(digit / len(code_string))
+    res = code_string[int(digit % len(code_string))] + res
+    return encode_digit(result, res) if result > 0 else res
+
+
+def encode_chat_id(chat_id: int, posts_count: int, last_read_post_no: int) -> str:
+    """
+    Encodes the given chat details into a single string.
+
+    This function takes a chat ID, the count of posts in the chat, and the number
+    of the last read post, and combines them into a single string separated by hyphens.
+
+    Parameters:
+    chat_id (int): The unique identifier for the chat.
+    posts_count (int): The total number of posts in the chat.
+    last_read_post_no (int): The number of the last post read by the user.
+
+    Returns:
+    str: A single string containing the encoded chat details separated by hyphens.
+    """
+    return '-'.join(map(str, [chat_id, posts_count, last_read_post_no]))
+
+
+def encode_chats_ids(chats_ids: list[tuple[int, int, int]]) -> str:
+    """
+    Encodes a list of chat IDs into a single string representation.
+
+    This function takes a list of chat ID tuples and converts each tuple into an encoded string
+    using the encode_chat_id function.
+    The encoded strings are then joined together by a '/' delimiter.
+
+    Parameters:
+        chats_ids (List[Tuple[int, int, int]]): A list of tuples, where each tuple contains
+        three integers representing a chat ID.
+
+    Returns:
+        str: A single string containing all encoded chat IDs joined by '/'.
+    """
+    return '/'.join(encode_chat_id(*chat_id) for chat_id in chats_ids)
+
+
+def lazy_loader(
+    cls: Any,
+    items: Sequence,
+    load_fn: Callable[[Any, list], list],
+    per_load: int = 50,
+) -> Iterable:
+    """
+    A generator function that loads items lazily in batches from a provided sequence.
+
+    Parameters:
+    cls (Any): The class or instance context used by the load function.
+    items (Sequence): The collection of items to be loaded.
+    load_fn (Callable[[Any, List], List]): The function responsible for loading a batch of items.
+        It must accept the class or instance (cls) and a subset of items,
+        and return a list of loaded items.
+    per_load (int): The number of items to load in each batch. Default is 50.
+
+    Returns:
+    Iterable: An iterator yielding items, loaded in batches.
+    """
+    load_counter = 0
+    loaded_items: list[Any] = []
+    counter = 0
+
+    def load_items():
+        return load_fn(cls, items[(per_load * load_counter) : (per_load * load_counter) + per_load])
+
+    for _ in items:
+        if not loaded_items:
+            loaded_items = load_items()
+        if counter >= per_load:
+            counter = 0
+            load_counter += 1
+            loaded_items = load_items()
+        yield loaded_items[counter]
+        counter += 1
+
+
+def join_ids(items: Sequence[Any]) -> str:
+    """
+    Converts a list of items into a single comma-separated string.
+
+    Args:
+        items (List[Any]): A list containing elements of any type to be joined.
+
+    Returns:
+        str: A comma-separated string representation of the elements in the list.
+    """
+    return ','.join(map(str, items))
+
+
+def get_utc(date: datetime) -> datetime:
+    """
+    Converts an offset-aware datetime object to its UTC equivalent.
+
+    Parameters:
+    date (datetime): The"""
+    if date.tzinfo is None:
+        msg = 'is not offset-aware datetime'
+        raise PararamioValidationException(msg)
+    return cast('datetime', date - cast('timedelta', date.utcoffset()))
+
+
+def parse_datetime(
+    data: dict[str, Any],
+    key: str,
+    format_: str = DATETIME_FORMAT,
+) -> datetime | None:
+    """
+    Parse a datetime object from a dictionary.
+
+    Parameters:
+    data (Dict[str, Any]): The dictionary containing the datetime string to parse.
+    key (str): The key in the dictionary where the datetime string is stored.
+    format_ (str): The format in which the datetime string is stored.
+
+    Returns:
+    Optional[datetime]: The parsed datetime object with UTC timezone, or None
+                        if the key is not found.
+    """
+    if key not in data:
+        return None
+    return datetime.strptime(data[key], format_).replace(tzinfo=timezone.utc)
+
+
+def parse_iso_datetime(data: dict[str, Any], key: str) -> datetime | None:
+    """
+    Parses an ISO 8601 formatted datetime string from a dictionary by a given key.
+
+    Parameters:
+    data (Dict[str, Any]): The dictionary containing the datetime string.
+    key (str): The key used to extract the datetime string from the dictionary.
+
+    Returns:
+    Optional[datetime]: A datetime object if parsing is successful, otherwise None.
+    """
+    try:
+        return parse_datetime(data, key, '%Y-%m-%dT%H:%M:%S.%fZ')
+    except ValueError:
+        return parse_datetime(data, key, '%Y-%m-%dT%H:%M:%SZ')
+
+
+def format_datetime(date: datetime) -> str:
+    """
+    Formats the given datetime object to a string in UTC using a predefined format.
+
+    Arguments:
+        date (datetime): The datetime object to format.
+
+    Returns:
+        str: The formatted datetime string.
+    """
+    return get_utc(date).strftime(DATETIME_FORMAT)
+
+
+def rand_id():
+    """
+
+    Generates a pseudo-random identifier.
+
+    This function generates a pseudo-random identifier by using the UUID
+    and MD5 hashing algorithm. The UUID is first converted to its hexadecimal
+    representation and encoded into bytes.
+    An MD5 hash is then computed from these bytes.
+    The
+    resulting hash is converted to an integer,
+    scaled by a factor of 10^-21, and finally returned as a string.
+
+    Returns:
+        str: The generated pseudo-random identifier
+    """
+    _hash = hashlib.md5(bytes(uuid.uuid4().hex, 'utf8'))
+    return str(int(int(_hash.hexdigest(), 16) * 10**-21))
+
+
+T = TypeVar('T', bound=dict)
+
+
+def unescape_dict(d: T, keys: list[str]) -> T:
+    """
+    Unescapes the values of specified keys in a dictionary.
+
+    This function takes a dictionary and a list of keys,
+    and returns a new dictionary where the values of the specified keys have been unescaped.
+    All other keys and values remain unchanged.
+
+    Args:
+        d (T): The dictionary whose values are to be unescaped.
+        keys (List[str]): A list of keys for which the values should be unescaped.
+
+    Returns:
+        T: A new dictionary with the values of specified keys unescaped.
+    """
+    return cast('T', {k: unescape(v) if k in keys else v for k, v in d.items()})
+
+
+def format_or_none(key: str, data: dict[str, Any], formatter: FormatterT | None) -> Any:
+    """
+    Formats the value associated with the given key if a formatter is provided;
+    otherwise, returns the unformatted value.
+
+    Parameters:
+    key (str): The key for which the value should be retrieved and optionally formatted.
+    data (Dict[str, Any]): The dictionary containing the data.
+    formatter (Optional[FormatterT]): An optional formatter dictionary where keys are the same as
+                                      in data and values are formatting functions.
+
+    Returns:
+    Any: The formatted value associated with the key if a formatter exists for it
+    otherwise, the unformatted value.
+    """
+    if formatter is not None and key in formatter:
+        return formatter[key](data, key)
+    return data[key]
+
+
+def get_formatted_attr_or_load(
+    obj: object,
+    key: str,
+    formatter: FormatterT | None = None,
+    load_fn: Callable[[], Any] | None = None,
+) -> Any:
+    """
+    Fetches a formatted attribute from an object's `_data` attribute if it exists,
+    using an optional formatter function. If the attribute does not exist and a
+    `load_fn` function is provided, the function will be called to load the data,
+    and the attribute will be fetched again.
+
+    Args:
+        obj (object): The object containing the `_data` attribute.
+        key (str): The key to look up in the `_data` attribute.
+        formatter (Optional[FormatterT], optional): An optional formatter function to
+            format the retrieved attribute. Defaults to None.
+        load_fn (Optional[Callable[[], Any]], optional): An optional function to call
+            if the key does not exist in the `_data` attribute. Defaults to None.
+
+    Returns:
+        Any: The formatted attribute if found and formatted, else raises PararamModelNotLoaded.
+
+    Raises:
+        PararamModelNotLoaded: If the key does not exist in the `_data` attribute and no
+            `load_fn` is provided.
+    """
+    try:
+        return format_or_none(key, getattr(obj, '_data', {}), formatter)
+    except KeyError as e:
+        if load_fn is not None:
+            load_fn()
+            return format_or_none(key, getattr(obj, '_data', {}), formatter)
+        msg = f"Attribute '{key}' has not been loaded yet"
+        raise PararamModelNotLoaded(msg) from e