pararamio-aio 3.0.0__py3-none-any.whl

pararamio_aio/_core/utils/http_client.py

@@ -0,0 +1,199 @@
+"""Common HTTP client utilities for sync and async implementations."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, ClassVar
+from urllib.parse import urljoin
+
+from ..constants import BASE_API_URL, VERSION, XSRF_HEADER_NAME
+
+__all__ = (
+    'HTTPClientConfig',
+    'RateLimitHandler',
+    'build_url',
+    'prepare_headers',
+    'should_retry_request',
+)
+
+
+class HTTPClientConfig:
+    """Common HTTP client configuration."""
+
+    DEFAULT_HEADERS: ClassVar[dict[str, str]] = {
+        'Content-type': 'application/json',
+        'Accept': 'application/json',
+        'User-agent': f'pararamio lib version {VERSION}',
+    }
+
+    # Retry configuration
+    MAX_RETRIES = 3
+    RETRY_DELAY = 1.0  # seconds
+    RETRY_BACKOFF = 2.0  # exponential backoff multiplier
+
+    # Rate limit configuration
+    RATE_LIMIT_RETRY_AFTER_DEFAULT = 60  # seconds
+    RATE_LIMIT_MAX_RETRIES = 3
+
+    # Status codes that trigger retry
+    RETRY_STATUS_CODES: ClassVar[set[int]] = {429, 502, 503, 504}
+
+    # Status codes that are considered successful
+    SUCCESS_STATUS_CODES: ClassVar[set[int]] = {200, 201, 204}
+
+
+class RateLimitHandler:
+    """Handle rate limiting (429) responses."""
+
+    def __init__(self):
+        self.last_rate_limit_time: float | None = None
+        self.retry_after: int | None = None
+
+    def handle_rate_limit(self, headers: dict[str, str]) -> int:
+        """Handle rate limit response and return retry delay.
+
+        Args:
+            headers: Response headers
+
+        Returns:
+            Seconds to wait before retry
+        """
+        self.last_rate_limit_time = time.time()
+
+        # Check for Retry-After header
+        retry_after = headers.get('Retry-After')
+        if retry_after:
+            try:
+                # Try to parse as integer (seconds)
+                self.retry_after = int(retry_after)
+            except ValueError:
+                # Might be a date, use default
+                self.retry_after = HTTPClientConfig.RATE_LIMIT_RETRY_AFTER_DEFAULT
+        else:
+            self.retry_after = HTTPClientConfig.RATE_LIMIT_RETRY_AFTER_DEFAULT
+
+        return self.retry_after
+
+    def should_wait(self) -> tuple[bool, int]:
+        """Check if we should wait due to rate limiting.
+
+        Returns:
+            Tuple of (should_wait, seconds_to_wait)
+        """
+        if self.last_rate_limit_time and self.retry_after:
+            elapsed = time.time() - self.last_rate_limit_time
+            remaining = self.retry_after - elapsed
+
+            if remaining > 0:
+                return True, int(remaining)
+
+        return False, 0
+
+    def clear(self):
+        """Clear rate limit state."""
+        self.last_rate_limit_time = None
+        self.retry_after = None
+
+
+def prepare_headers(
+    custom_headers: dict[str, str] | None = None,
+    xsrf_token: str | None = None,
+) -> dict[str, str]:
+    """Prepare request headers.
+
+    Args:
+        custom_headers: Custom headers to add
+        xsrf_token: XSRF token to include
+
+    Returns:
+        Combined headers dict
+    """
+    headers = HTTPClientConfig.DEFAULT_HEADERS.copy()
+
+    if xsrf_token:
+        headers[XSRF_HEADER_NAME] = xsrf_token
+
+    if custom_headers:
+        headers.update(custom_headers)
+
+    return headers
+
+
+def build_url(endpoint: str, base_url: str | None = None) -> str:
+    """Build full URL from endpoint.
+
+    Args:
+        endpoint: API endpoint path
+        base_url: Base URL (defaults to BASE_API_URL)
+
+    Returns:
+        Full URL
+    """
+    if endpoint.startswith('http'):
+        return endpoint
+
+    base = base_url or BASE_API_URL
+    return urljoin(base, endpoint)
+
+
+def should_retry_request(
+    status_code: int,
+    attempt: int,
+    error: Exception | None = None,
+) -> tuple[bool, float]:
+    """Determine if request should be retried.
+
+    Args:
+        status_code: HTTP status code
+        attempt: Current attempt number (1-based)
+        error: Optional exception that occurred
+
+    Returns:
+        Tuple of (should_retry, delay_seconds)
+    """
+    if attempt >= HTTPClientConfig.MAX_RETRIES:
+        return False, 0
+
+    # Check if status code is retryable
+    if status_code in HTTPClientConfig.RETRY_STATUS_CODES:
+        # Special handling for rate limit
+        if status_code == 429:
+            # Rate limit delay is handled separately
+            return True, 0
+
+        # Calculate exponential backoff
+        delay = HTTPClientConfig.RETRY_DELAY * (HTTPClientConfig.RETRY_BACKOFF ** (attempt - 1))
+        return True, delay
+
+    # Check for network errors
+    if error and isinstance(error, (ConnectionError, TimeoutError)):
+        delay = HTTPClientConfig.RETRY_DELAY * (HTTPClientConfig.RETRY_BACKOFF ** (attempt - 1))
+        return True, delay
+
+    return False, 0
+
+
+class RequestResult:
+    """Result of an HTTP request."""
+
+    def __init__(
+        self,
+        success: bool,
+        status_code: int,
+        data: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        error: str | None = None,
+    ):
+        self.success = success
+        self.status_code = status_code
+        self.data = data or {}
+        self.headers = headers or {}
+        self.error = error
+
+    def is_rate_limited(self) -> bool:
+        """Check if response indicates rate limiting."""
+        return self.status_code == 429
+
+    def is_success(self) -> bool:
+        """Check if response is successful."""
+        return self.status_code in HTTPClientConfig.SUCCESS_STATUS_CODES

pararamio_aio/_core/utils/requests.py

@@ -0,0 +1,424 @@
+from __future__ import annotations
+
+import codecs
+import json
+import logging
+import mimetypes
+from io import BytesIO
+from json import JSONDecodeError
+from pathlib import Path
+from typing import TYPE_CHECKING, BinaryIO
+from urllib.error import HTTPError
+from urllib.parse import quote
+from urllib.request import HTTPCookieProcessor, Request, build_opener
+
+from pararamio_aio._core.constants import BASE_API_URL, FILE_UPLOAD_URL, UPLOAD_TIMEOUT, VERSION
+from pararamio_aio._core.constants import REQUEST_TIMEOUT as TIMEOUT
+from pararamio_aio._core.exceptions import PararamioHTTPRequestException
+
+if TYPE_CHECKING:
+    from http.client import HTTPResponse
+
+    from pararamio_aio._core._types import CookieJarT, HeaderLikeT
+
+__all__ = (
+    'api_request',
+    'bot_request',
+    'delete_file',
+    'download_file',
+    'raw_api_request',
+    'upload_file',
+    'xupload_file',
+)
+log = logging.getLogger('pararamio')
+UA_HEADER = f'pararamio lib version {VERSION}'
+DEFAULT_HEADERS = {
+    'Content-type': 'application/json',
+    'Accept': 'application/json',
+    'User-agent': UA_HEADER,
+}
+writer = codecs.lookup('utf-8')[3]
+
+
+def multipart_encode(
+    fd: BinaryIO,
+    fields: list[tuple[str, str | None | int]] | None = None,
+    boundary: str | None = None,
+    form_field_name: str = 'data',
+    filename: str | None = None,
+    content_type: str | None = None,
+) -> bytes:
+    """
+    Encodes a file and additional fields into a multipart/form-data payload.
+
+    Args:
+        fd: A file-like object opened in binary mode that is to be included in the payload.
+        fields: An optional list of tuples representing additional form fields,
+                with each tuple containing a field name and its value.
+        boundary: An optional string used to separate parts of the multipart message.
+                  If not provided, a default boundary ('FORM-BOUNDARY') is used.
+        form_field_name: The name of the form field for the file being uploaded. Defaults to 'data'.
+        filename: An optional string representing the filename for the file being uploaded.
+                  If not provided, the name is derived from the file-like object.
+        content_type: An optional string representing the content type of the file being uploaded.
+                      If not provided, the content type will be guessed from the filename.
+
+    Returns:
+        A bytes' object representing the encoded multipart/form-data payload.
+    """
+    if fields is None:
+        fields = []
+    if boundary is None:
+        boundary = 'FORM-BOUNDARY'
+    body = BytesIO()
+
+    def write(text: str):
+        nonlocal body
+        writer(body).write(text)
+
+    if fields:
+        for key, value in fields:
+            if value is None:
+                continue
+            write(f'--{boundary}\r\n')
+            write(f'Content-Disposition: form-data; name="{key}"')
+            write(f'\r\n\r\n{value}\r\n')
+    if not filename:
+        filename = Path(fd.name).name
+    if not content_type:
+        content_type = mimetypes.guess_type(filename)[0] or 'application/octet-stream'
+    fd.seek(0)
+    write(f'--{boundary}\r\n')
+    write(f'Content-Disposition: form-data; name="{form_field_name}"; filename="{filename}"\r\n')
+    write(f'Content-Type: {content_type}\r\n\r\n')
+    body.write(fd.read())
+    write(f'\r\n--{boundary}--\r\n\r\n')
+    return body.getvalue()
+
+
+def bot_request(
+    url: str,
+    key: str,
+    method: str = 'GET',
+    data: dict | None = None,
+    headers: dict | None = None,
+    timeout: int = TIMEOUT,
+):
+    """
+
+    Sends a request to a bot API endpoint with the specified parameters.
+
+    Parameters:
+    url (str): The endpoint URL of the bot API.
+    key (str): The API token for authentication.
+    method (str): The HTTP method to use for the request. Defaults to 'GET'.
+    data (Optional[dict]): The data payload for the request. Defaults to None.
+    headers (Optional[dict]): Additional headers to include in the request. Defaults to None.
+    timeout (int): The timeout setting for the request. Defaults to TIMEOUT.
+
+    Returns:
+    Response object from the API request.
+    """
+    _headers = {'X-APIToken': key, **DEFAULT_HEADERS}
+    if headers:
+        _headers = {**_headers, **headers}
+    return api_request(url=url, method=method, data=data, headers=_headers, timeout=timeout)
+
+
+def _base_request(
+    url: str,
+    method: str = 'GET',
+    data: bytes | None = None,
+    headers: dict | None = None,
+    cookie_jar: CookieJarT | None = None,
+    timeout: int = TIMEOUT,
+) -> HTTPResponse:
+    """
+    Sends an HTTP request and returns an HTTPResponse object.
+
+    Parameters:
+        url (str): The URL endpoint to which the request is sent.
+        method (str): The HTTP method to use for the request (default is 'GET').
+        data (Optional[bytes]): The payload to include in the request body (default is None).
+        headers (Optional[dict]): A dictionary of headers to include in the request
+                                  (default is None).
+        cookie_jar (Optional[CookieJarT]): A cookie jar to manage cookies for the request
+                                           (default is None).
+        timeout (int): The timeout for the request in seconds (TIMEOUT defines default).
+
+    Returns:
+        HTTPResponse: The response object containing the server's response to the HTTP request.
+
+    Raises:
+        PararamioHTTPRequestException: An exception is raised if there is
+                                       an issue with the HTTP request.
+    """
+    _url = f'{BASE_API_URL}{url}'
+    _headers = DEFAULT_HEADERS
+    if headers:
+        _headers = {**_headers, **headers}
+    opener = build_opener(*[HTTPCookieProcessor(cookie_jar)] if cookie_jar is not None else [])
+    _data = None
+    if data:
+        _data = data
+    rq = Request(_url, _data, method=method, headers=_headers)
+    log.debug('%s - %s - %s - %s - %s', _url, method, data, headers, cookie_jar)
+    try:
+        return opener.open(rq, timeout=timeout)
+    except HTTPError as e:
+        log.exception('%s - %s', _url, method)
+        # noinspection PyUnresolvedReferences
+        raise PararamioHTTPRequestException(e.filename, e.code, e.msg, e.hdrs, e.fp) from e
+
+
+def _base_file_request(
+    url: str,
+    method='GET',
+    data: bytes | None = None,
+    headers: HeaderLikeT | None = None,
+    cookie_jar: CookieJarT | None = None,  # type: ignore
+    timeout: int = TIMEOUT,
+) -> BytesIO:
+    """
+    Performs a file request to the specified URL with the given parameters.
+
+    Arguments:
+        url (str): The URL endpoint to send the request to.
+        method (str, optional): The HTTP method to use for the request (default is 'GET').
+        data (Optional[bytes], optional): The data to send in the request body (default is None).
+        headers (Optional[HeaderLikeT], optional): The headers to include in the request
+                                                   (default is None).
+        cookie_jar (Optional[CookieJarT], optional): The cookie jar to use for managing cookies
+                                                     (default is None).
+        timeout (int, optional): The timeout duration for the request (default value is TIMEOUT).
+
+    Returns:
+        BytesIO: The response object from the file request.
+
+    Raises:
+        PararamioHTTPRequestException: If the request fails with an HTTP error code.
+    """
+    _url = f'{FILE_UPLOAD_URL}{url}'
+    opener = build_opener(HTTPCookieProcessor(cookie_jar))
+    if not headers:
+        headers = {}
+    rq = Request(_url, data, method=method, headers=headers)
+    log.debug('%s - %s - %s - %s - %s', url, method, data, headers, cookie_jar)
+    try:
+        resp = opener.open(rq, timeout=timeout)
+        if 200 >= resp.getcode() < 300:
+            return resp
+        raise PararamioHTTPRequestException(
+            _url, resp.getcode(), 'Unknown error', resp.getheaders(), resp.fp
+        )
+    except HTTPError as e:
+        log.exception('%s - %s', _url, method)
+        # noinspection PyUnresolvedReferences
+        raise PararamioHTTPRequestException(e.filename, e.code, e.msg, e.hdrs, e.fp) from e
+
+
+def upload_file(
+    fp: BinaryIO,
+    perm: str,
+    filename: str | None = None,
+    file_type=None,
+    headers: HeaderLikeT | None = None,
+    cookie_jar: CookieJarT | None = None,
+    timeout: int = UPLOAD_TIMEOUT,
+):
+    """
+    Upload a file to a pararam server with specified permissions and optional parameters.
+
+    Args:
+        fp (BinaryIO): A file-like object to be uploaded.
+        perm (str): The permission level for the uploaded file.
+        filename (Optional[str], optional): Optional filename used during upload. Defaults to None.
+        file_type (optional): Optional MIME type of the file. Defaults to None.
+        headers (Optional[HeaderLikeT], optional): Optional headers to include in the request.
+        Defaults to None.
+        cookie_jar (Optional[CookieJarT], optional): Optional cookie jar for maintaining session.
+        Defaults to None.
+        timeout (int, optional): Timeout duration for the upload request.
+        Defaults to UPLOAD_TIMEOUT.
+
+    Returns:
+        dict: A dictionary containing the server's response to the file upload.
+
+    The function constructs a multipart form data request with the file contents,
+    sends the POST request to the server,
+    and returns the parsed JSON response from the server.
+    """
+    url = f'/upload/{perm}'
+    boundary = 'FORM-BOUNDARY'
+    _headers = {
+        'User-agent': UA_HEADER,
+        **(headers or {}),
+        'Accept': 'application/json',
+        'Content-Type': f'multipart/form-data; boundary={boundary}',
+    }
+    data = multipart_encode(
+        fp,
+        boundary=boundary,
+        form_field_name='file',
+        filename=filename,
+        content_type=file_type,
+    )
+    resp = _base_file_request(
+        url,
+        method='POST',
+        data=data,
+        headers=_headers,
+        cookie_jar=cookie_jar,
+        timeout=timeout,
+    )
+    return json.loads(resp.read())
+
+
+def xupload_file(
+    fp: BinaryIO,
+    fields: list[tuple[str, str | None | int]],
+    filename: str | None = None,
+    content_type: str | None = None,
+    headers: HeaderLikeT | None = None,
+    cookie_jar: CookieJarT | None = None,
+    timeout: int = UPLOAD_TIMEOUT,
+) -> dict:
+    """
+
+    Uploads a file to a predefined URL using a multipart/form-data request.
+
+    Arguments:
+    - fp: A binary file-like object to upload.
+    - fields: A list of tuples where each tuple contains a field name, z
+     and a value which can be
+    a string, None, or an integer.
+    - filename: Optional; The name of the file being uploaded.
+                If not provided, it defaults to None.
+    - content_type: Optional; The MIME type of the file being uploaded.
+                    If not provided, it defaults to None.
+    - headers: Optional; Additional headers to include in the upload request.
+               If not provided, defaults to None.
+    - cookie_jar: Optional; A collection of cookies to include in the upload request.
+                  If not provided, defaults to None.
+    - timeout: Optional; The timeout in seconds for the request.
+               Defaults to UPLOAD_TIMEOUT.
+
+    Returns:
+    - A dictionary parsed from the JSON response of the upload request.
+
+    """
+    url = '/upload'
+    boundary = 'FORM-BOUNDARY'
+    _headers = {
+        'User-agent': UA_HEADER,
+        **(headers or {}),
+        'Accept': 'application/json',
+        'Content-Type': f'multipart/form-data; boundary={boundary}',
+    }
+    data = multipart_encode(
+        fp,
+        fields,
+        filename=filename,
+        content_type=content_type,
+        boundary=boundary,
+    )
+    resp = _base_file_request(
+        url,
+        method='POST',
+        data=data,
+        headers=_headers,
+        cookie_jar=cookie_jar,
+        timeout=timeout,
+    )
+    return json.loads(resp.read())
+
+
+def delete_file(
+    guid: str,
+    headers: HeaderLikeT | None = None,
+    cookie_jar: CookieJarT | None = None,
+    timeout: int = TIMEOUT,
+) -> dict:
+    url = f'/delete/{guid}'
+    resp = _base_file_request(
+        url, method='DELETE', headers=headers, cookie_jar=cookie_jar, timeout=timeout
+    )
+    return json.loads(resp.read())
+
+
+def download_file(
+    guid: str,
+    filename: str,
+    headers: HeaderLikeT | None = None,
+    cookie_jar: CookieJarT | None = None,
+    timeout: int = TIMEOUT,
+) -> BytesIO:
+    url = f'/download/{guid}/{quote(filename)}'
+    return file_request(url, method='GET', headers=headers, cookie_jar=cookie_jar, timeout=timeout)
+
+
+def file_request(
+    url: str,
+    method='GET',
+    data: bytes | None = None,
+    headers: HeaderLikeT | None = None,
+    cookie_jar: CookieJarT | None = None,
+    timeout: int = TIMEOUT,
+) -> BytesIO:
+    _headers = DEFAULT_HEADERS
+    if headers:
+        _headers = {**_headers, **headers}
+    return _base_file_request(
+        url,
+        method=method,
+        data=data,
+        headers=_headers,
+        cookie_jar=cookie_jar,
+        timeout=timeout,
+    )
+
+
+def raw_api_request(
+    url: str,
+    method: str = 'GET',
+    data: bytes | None = None,
+    headers: HeaderLikeT | None = None,
+    cookie_jar: CookieJarT | None = None,
+    timeout: int = TIMEOUT,
+) -> tuple[dict, list]:
+    resp = _base_request(url, method, data, headers, cookie_jar, timeout)
+    if 200 >= resp.getcode() < 300:
+        contents = resp.read()
+        return json.loads(contents), resp.getheaders()
+    return {}, []
+
+
+def api_request(
+    url: str,
+    method: str = 'GET',
+    data: dict | None = None,
+    headers: HeaderLikeT | None = None,
+    cookie_jar: CookieJarT | None = None,
+    timeout: int = TIMEOUT,
+) -> dict:
+    _data = None
+    if data is not None:
+        _data = str.encode(json.dumps(data), 'utf-8')
+    resp = _base_request(url, method, _data, headers, cookie_jar, timeout)
+    resp_code = resp.getcode()
+    if resp_code == 204:
+        return {}
+    if 200 <= resp_code < 500:
+        content = resp.read()
+        try:
+            return json.loads(content)
+        except JSONDecodeError as e:
+            log.exception('%s - %s', url, method)
+            raise PararamioHTTPRequestException(
+                url,
+                resp.getcode(),
+                'JSONDecodeError',
+                resp.getheaders(),
+                BytesIO(content),
+            ) from e
+    return {}

pararamio_aio/_core/validators.py

@@ -0,0 +1,78 @@
+"""Common validators for pararamio models."""
+
+from .exceptions import PararamioValidationException
+
+__all__ = [
+    'validate_filename',
+    'validate_ids_list',
+    'validate_post_load_range',
+]
+
+
+def validate_post_load_range(start_post_no: int, end_post_no: int) -> None:
+    """
+    Validate post loading range parameters.
+
+    Args:
+        start_post_no: Starting post number
+        end_post_no: Ending post number
+
+    Raises:
+        PararamioValidationException: If range is invalid
+    """
+    if (start_post_no < 0 <= end_post_no) or (start_post_no >= 0 > end_post_no):
+        msg = 'start_post_no and end_post_no can only be negative or positive at the same time'
+        raise PararamioValidationException(msg)
+    if 0 > start_post_no > end_post_no:
+        msg = 'range start_post_no must be greater then end_post_no'
+        raise PararamioValidationException(msg)
+    if 0 <= start_post_no > end_post_no:
+        msg = 'range start_post_no must be smaller then end_post_no'
+        raise PararamioValidationException(msg)
+
+
+def validate_filename(filename: str) -> None:
+    """
+    Validate filename for file uploads.
+
+    Args:
+        filename: Name of the file
+
+    Raises:
+        PararamioValidationException: If filename is invalid
+    """
+    if not filename or not filename.strip():
+        msg = 'Filename cannot be empty'
+        raise PararamioValidationException(msg)
+
+    # Add more filename validation as needed
+    forbidden_chars = ['<', '>', ':', '"', '|', '?', '*']
+    for char in forbidden_chars:
+        if char in filename:
+            msg = f'Filename cannot contain character: {char}'
+            raise PararamioValidationException(msg)
+
+
+def validate_ids_list(ids: list, max_count: int = 100) -> None:
+    """
+    Validate list of IDs.
+
+    Args:
+        ids: List of IDs to validate
+        max_count: Maximum allowed count
+
+    Raises:
+        PararamioValidationException: If IDs list is invalid
+    """
+    if not ids:
+        msg = 'IDs list cannot be empty'
+        raise PararamioValidationException(msg)
+
+    if len(ids) > max_count:
+        msg = f'Too many IDs, maximum {max_count} allowed'
+        raise PararamioValidationException(msg)
+
+    for id_val in ids:
+        if not isinstance(id_val, int) or id_val <= 0:
+            msg = f'Invalid ID: {id_val}. IDs must be positive integers'
+            raise PararamioValidationException(msg)