enkryptai-sdk 1.0.23__py3-none-any.whl → 1.0.25__py3-none-any.whl

enkryptai_sdk/utils/pagination.py

@@ -0,0 +1,384 @@
+"""
+Pagination utilities for Enkrypt AI SDK.
+
+This module provides helper functions for handling pagination in API requests and responses.
+"""
+
+from typing import Dict, Any, List, Optional, Union, Tuple
+from urllib.parse import urlencode, parse_qs, urlparse, urlunparse
+from ..response import PaginationInfo, PaginatedResponse
+
+
+def parse_pagination_params(
+    query_string: str = "", 
+    default_page: int = 1, 
+    default_per_page: int = 10
+) -> PaginationInfo:
+    """
+    Parse pagination parameters from a query string.
+    
+    Args:
+        query_string (str): URL query string (e.g., "page=2&per_page=20")
+        default_page (int): Default page number if not specified
+        default_per_page (int): Default items per page if not specified
+        
+    Returns:
+        PaginationInfo: Parsed pagination information
+        
+    Example:
+        >>> parse_pagination_params("page=2&per_page=20")
+        PaginationInfo(page=2, per_page=20, total_count=0)
+    """
+    if not query_string:
+        return PaginationInfo(default_page, default_per_page)
+    
+    # Parse query string
+    params = parse_qs(query_string)
+    
+    # Extract pagination parameters
+    page = params.get("page", [str(default_page)])[0]
+    per_page = params.get("per_page", [str(default_per_page)])[0]
+    
+    try:
+        page_num = int(page)
+        per_page_num = int(per_page)
+    except (ValueError, TypeError):
+        page_num = default_page
+        per_page_num = default_per_page
+    
+    # Validate and create PaginationInfo
+    return PaginationInfo(
+        page=max(1, page_num),
+        per_page=max(1, min(100, per_page_num)),
+        total_count=0
+    )
+
+
+def build_pagination_url(
+    base_url: str, 
+    page: int, 
+    per_page: int, 
+    **additional_params
+) -> str:
+    """
+    Build a URL with pagination parameters.
+    
+    Args:
+        base_url (str): Base URL without query parameters
+        page (int): Page number
+        per_page (int): Items per page
+        **additional_params: Additional query parameters
+        
+    Returns:
+        str: Complete URL with pagination parameters
+        
+    Example:
+        >>> build_pagination_url("https://api.example.com/users", 2, 20, status="active")
+        'https://api.example.com/users?page=2&per_page=20&status=active'
+    """
+    params = {
+        "page": page,
+        "per_page": per_page,
+        **additional_params
+    }
+    
+    # Filter out None values
+    params = {k: v for k, v in params.items() if v is not None}
+    
+    query_string = urlencode(params)
+    return f"{base_url}?{query_string}" if query_string else base_url
+
+
+def create_paginated_response(
+    data: List[Any],
+    total_count: int,
+    page: int = 1,
+    per_page: int = 10,
+    **additional_data
+) -> PaginatedResponse:
+    """
+    Create a paginated response object.
+    
+    Args:
+        data (List[Any]): List of items for the current page
+        total_count (int): Total number of items across all pages
+        page (int): Current page number
+        per_page (int): Items per page
+        **additional_data: Additional data to include in the response
+        
+    Returns:
+        PaginatedResponse: Paginated response object
+        
+    Example:
+        >>> users = [{"id": 1, "name": "John"}, {"id": 2, "name": "Jane"}]
+        >>> response = create_paginated_response(users, 100, 1, 10)
+        >>> response.get_page()
+        1
+        >>> response.get_total_count()
+        100
+    """
+    pagination = PaginationInfo(page, per_page, total_count)
+    return PaginatedResponse(data, pagination, **additional_data)
+
+
+def validate_pagination_params(
+    page: Union[str, int, None], 
+    per_page: Union[str, int, None]
+) -> Tuple[int, int]:
+    """
+    Validate pagination parameters and return validated values.
+    
+    Args:
+        page: Page number (can be string, int, or None)
+        per_page: Items per page (can be string, int, or None)
+        
+    Returns:
+        Tuple[int, int]: Validated (page, per_page) values
+        
+    Raises:
+        ValueError: If parameters are invalid
+        
+    Example:
+        >>> validate_pagination_params("2", "20")
+        (2, 20)
+        >>> validate_pagination_params(None, None)
+        (1, 10)
+    """
+    try:
+        page_num = int(page) if page is not None else 1
+        per_page_num = int(per_page) if per_page is not None else 10
+    except (ValueError, TypeError):
+        raise ValueError("Page and per_page must be valid integers")
+    
+    if page_num < 1:
+        raise ValueError("Page must be >= 1")
+    if per_page_num < 1 or per_page_num > 100:
+        raise ValueError("Per_page must be between 1 and 100")
+        
+    return page_num, per_page_num
+
+
+def get_pagination_metadata(
+    total_count: int, 
+    page: int, 
+    per_page: int
+) -> Dict[str, Any]:
+    """
+    Generate pagination metadata for API responses.
+    
+    Args:
+        total_count (int): Total number of items
+        page (int): Current page number
+        per_page (int): Items per page
+        
+    Returns:
+        Dict[str, Any]: Pagination metadata dictionary
+        
+    Example:
+        >>> get_pagination_metadata(100, 2, 20)
+        {
+            'page': 2,
+            'per_page': 20,
+            'total_count': 100,
+            'total_pages': 5,
+            'has_next': True,
+            'has_previous': True
+        }
+    """
+    pagination = PaginationInfo(page, per_page, total_count)
+    return pagination.to_dict()
+
+
+def calculate_page_info(
+    total_count: int, 
+    page: int, 
+    per_page: int
+) -> Dict[str, Any]:
+    """
+    Calculate detailed pagination information.
+    
+    Args:
+        total_count (int): Total number of items
+        page (int): Current page number
+        per_page (int): Items per page
+        
+    Returns:
+        Dict[str, Any]: Detailed pagination information
+        
+    Example:
+        >>> calculate_page_info(100, 2, 20)
+        {
+            'current_page': 2,
+            'per_page': 20,
+            'total_count': 100,
+            'total_pages': 5,
+            'has_next': True,
+            'has_previous': True,
+            'offset': 20,
+            'limit': 20,
+            'start_item': 21,
+            'end_item': 40
+        }
+    """
+    pagination = PaginationInfo(page, per_page, total_count)
+    
+    start_item = (page - 1) * per_page + 1
+    end_item = min(page * per_page, total_count)
+    
+    return {
+        'current_page': pagination.page,
+        'per_page': pagination.per_page,
+        'total_count': pagination.total_count,
+        'total_pages': pagination.total_pages,
+        'has_next': pagination.has_next,
+        'has_previous': pagination.has_previous,
+        'offset': pagination.offset,
+        'limit': pagination.limit,
+        'start_item': start_item if total_count > 0 else 0,
+        'end_item': end_item if total_count > 0 else 0
+    }
+
+
+def create_pagination_links(
+    base_url: str,
+    current_page: int,
+    total_pages: int,
+    per_page: int,
+    **additional_params
+) -> Dict[str, Optional[str]]:
+    """
+    Create pagination links for navigation.
+    
+    Args:
+        base_url (str): Base URL for the endpoint
+        current_page (int): Current page number
+        total_pages (int): Total number of pages
+        per_page (int): Items per page
+        **additional_params: Additional query parameters
+        
+    Returns:
+        Dict[str, Optional[str]]: Dictionary with pagination links
+        
+    Example:
+        >>> links = create_pagination_links("https://api.example.com/users", 2, 5, 20)
+        >>> links
+        {
+            'first': 'https://api.example.com/users?page=1&per_page=20',
+            'previous': 'https://api.example.com/users?page=1&per_page=20',
+            'current': 'https://api.example.com/users?page=2&per_page=20',
+            'next': 'https://api.example.com/users?page=3&per_page=20',
+            'last': 'https://api.example.com/users?page=5&per_page=20'
+        }
+    """
+    links = {}
+    
+    # First page
+    links['first'] = build_pagination_url(base_url, 1, per_page, **additional_params)
+    
+    # Previous page
+    if current_page > 1:
+        links['previous'] = build_pagination_url(base_url, current_page - 1, per_page, **additional_params)
+    else:
+        links['previous'] = None
+    
+    # Current page
+    links['current'] = build_pagination_url(base_url, current_page, per_page, **additional_params)
+    
+    # Next page
+    if current_page < total_pages:
+        links['next'] = build_pagination_url(base_url, current_page + 1, per_page, **additional_params)
+    else:
+        links['next'] = None
+    
+    # Last page
+    if total_pages > 0:
+        links['last'] = build_pagination_url(base_url, total_pages, per_page, **additional_params)
+    else:
+        links['last'] = None
+    
+    return links
+
+
+def apply_pagination_to_list(
+    data: List[Any], 
+    page: int, 
+    per_page: int
+) -> Tuple[List[Any], int]:
+    """
+    Apply pagination to a list of data.
+    
+    Args:
+        data (List[Any]): Complete list of data
+        page (int): Page number (1-based)
+        per_page (int): Items per page
+        
+    Returns:
+        Tuple[List[Any], int]: (paginated_data, total_count)
+        
+    Example:
+        >>> all_users = [{"id": i, "name": f"User{i}"} for i in range(1, 101)]
+        >>> page_data, total = apply_pagination_to_list(all_users, 2, 20)
+        >>> len(page_data)
+        20
+        >>> total
+        100
+    """
+    total_count = len(data)
+    start_index = (page - 1) * per_page
+    end_index = start_index + per_page
+    
+    paginated_data = data[start_index:end_index]
+    return paginated_data, total_count
+
+
+def format_pagination_response(
+    data: List[Any],
+    total_count: int,
+    page: int,
+    per_page: int,
+    include_links: bool = True,
+    base_url: str = "",
+    **additional_data
+) -> Dict[str, Any]:
+    """
+    Format a complete paginated response.
+    
+    Args:
+        data (List[Any]): List of items for the current page
+        total_count (int): Total number of items
+        page (int): Current page number
+        per_page (int): Items per page
+        include_links (bool): Whether to include pagination links
+        base_url (str): Base URL for generating pagination links
+        **additional_data: Additional data to include
+        
+    Returns:
+        Dict[str, Any]: Formatted paginated response
+        
+    Example:
+        >>> response = format_pagination_response(
+        ...     [{"id": 1, "name": "John"}], 
+        ...     100, 1, 10, 
+        ...     base_url="https://api.example.com/users"
+        ... )
+        >>> response.keys()
+        dict_keys(['data', 'pagination', 'links'])
+    """
+    # Create pagination metadata
+    pagination = get_pagination_metadata(total_count, page, per_page)
+    
+    # Build response
+    response = {
+        "data": data,
+        "pagination": pagination,
+        **additional_data
+    }
+    
+    # Add pagination links if requested
+    if include_links and base_url:
+        links = create_pagination_links(
+            base_url, page, pagination['total_pages'], per_page
+        )
+        response["links"] = links
+    
+    return response

{enkryptai_sdk-1.0.23.dist-info → enkryptai_sdk-1.0.25.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: enkryptai-sdk
-Version: 1.0.23
+Version: 1.0.25
 Summary: A Python SDK with guardrails and red teaming functionality for API interactions
 Home-page: https://github.com/enkryptai/enkryptai-sdk
 Author: Enkrypt AI Team

{enkryptai_sdk-1.0.23.dist-info → enkryptai_sdk-1.0.25.dist-info}/RECORD

@@ -1,4 +1,4 @@
-enkryptai_sdk/__init__.py,sha256=8H5tznmjirTVdrTmrsyU6fNVRj3-UC0nrTGkzfFp0h0,845
+enkryptai_sdk/__init__.py,sha256=uwIMVg_MDFmp7khURZt4nSOPVdZlwqK_s4pGhv8yzCw,2111
 enkryptai_sdk/ai_proxy.py,sha256=ot1lqKk2LjcvlpnFm2kSA51vFThfquVlx86BhSbAzBo,3823
 enkryptai_sdk/base.py,sha256=KonezvdjVzIr3gw75grzcCNyhzI_sHXi-Cb9tRJgSDE,3277
 enkryptai_sdk/coc.py,sha256=5rq9LhZX-uvCmX8fM6JEndIEvd8rSzsSfDFnTvSvTQE,7396
@@ -9,9 +9,9 @@ enkryptai_sdk/evals.py,sha256=BywyEgIT7xdJ58svO_sDNOMVowdB0RTGoAZPEbCnDVo,2595
 enkryptai_sdk/guardrails.py,sha256=iEngSpkzZBB3EkJGxUxUgYF0Av4N2XWMN-BlAkRDle4,19856
 enkryptai_sdk/guardrails_old.py,sha256=SgzPZkTzbAPD9XfmYNG6M1-TrzbhDHpAkI3FjnVWS_s,6434
 enkryptai_sdk/models.py,sha256=0R0I4KOq0aDNi5utabANot-E8dT9GqiSsgrcI9RULHM,8932
-enkryptai_sdk/red_team.py,sha256=w52gPteGaH6iEBThjIYxLAV1bXXTorgxST_TOnGMT88,20917
-enkryptai_sdk/response.py,sha256=43JRubzgGCpoVxYNzBZY0AlUgLbfcXD_AwD7wU3qY9o,4086
-enkryptai_sdk/dto/__init__.py,sha256=wHgIv_OCnVMJOys-vqImF59ifogDrMcgxVRmfNayVvc,2761
+enkryptai_sdk/red_team.py,sha256=BbL_GRbkU_zqJuF6tPgXHhLGhq4Ri_RQmxzyO2X8wQ0,28756
+enkryptai_sdk/response.py,sha256=2WOyejMYK7lA7I3fyebd0oYhP4js5Q1favJAV_h9pmo,13604
+enkryptai_sdk/dto/__init__.py,sha256=hBN523YIkuHCvLTrkPu9ipGwAyLDnhV9sb3rKNpRajg,3061
 enkryptai_sdk/dto/ai_proxy.py,sha256=clwMN4xdH8Zr55dnhilHbs-qaHRlCOrLPrij0Zd1Av0,11283
 enkryptai_sdk/dto/base.py,sha256=y77kQL1X7389ifSVNc0E7CUFNxACh5AM3ml9YPon1KY,2822
 enkryptai_sdk/dto/coc.py,sha256=9D5mmSdmC_guV75ml48PPLZD_zFa5FjxRwlTqHrmdak,5071
@@ -19,10 +19,12 @@ enkryptai_sdk/dto/common.py,sha256=lrWMu4FKUGCN2dbS9fT4yNtfiPm1cNN16J4eCe4_tBM,1
 enkryptai_sdk/dto/datasets.py,sha256=FiVwbEZ04jPajnlBfgw1Aj83iAhup3Ut7GOymq73OMg,5073
 enkryptai_sdk/dto/deployments.py,sha256=v--UrwkuXP4xTsPbmVruYj-g3JEQXepBRQfr-Gsv3aA,11744
 enkryptai_sdk/dto/guardrails.py,sha256=n73uPmK9fCIqqxv1rNecYUX4v5ePdIjxSBD4jIhwDe8,55966
-enkryptai_sdk/dto/models.py,sha256=AwqYMBZckJ0RdeU89I-3CYJ03c-VLdHf5zD5PSbU3JQ,14585
-enkryptai_sdk/dto/red_team.py,sha256=rV7bYVb5YSxnrhLwNiTlKWy0ZTXK4zhmPgVoLJQMMoo,28802
-enkryptai_sdk-1.0.23.dist-info/licenses/LICENSE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-enkryptai_sdk-1.0.23.dist-info/METADATA,sha256=CMSsEyEBXxGhIciL2JgGg2slVeEbxw9OeLRpVtUp1qM,1644
-enkryptai_sdk-1.0.23.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-enkryptai_sdk-1.0.23.dist-info/top_level.txt,sha256=s2X9UJJwvJamNmr6ZXWyyQe60sXtQGWFuaBYfhgHI_4,14
-enkryptai_sdk-1.0.23.dist-info/RECORD,,
+enkryptai_sdk/dto/models.py,sha256=upzoQlyA7-isf0DsuabDw1CfqzZXLOhkcj7jV5cnj4Q,16175
+enkryptai_sdk/dto/red_team.py,sha256=NwE6Ed7dpSvcx3ioin6B8iCglQWD5rtKFJwDVfKQnLM,38456
+enkryptai_sdk/utils/__init__.py,sha256=SII0dz9SesrXt2zOR1xXErPYZGj3WyC9A9Pn_eOLsOg,710
+enkryptai_sdk/utils/pagination.py,sha256=5t9qiDdxRA4uQywU4I4pp9OScqNBrEPmzKlPG-b-eVE,11149
+enkryptai_sdk-1.0.25.dist-info/licenses/LICENSE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+enkryptai_sdk-1.0.25.dist-info/METADATA,sha256=tdfbJ017FU2zkAS1nSN8-l8h2Ve1E_pk8KNxOZH1tSw,1644
+enkryptai_sdk-1.0.25.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+enkryptai_sdk-1.0.25.dist-info/top_level.txt,sha256=s2X9UJJwvJamNmr6ZXWyyQe60sXtQGWFuaBYfhgHI_4,14
+enkryptai_sdk-1.0.25.dist-info/RECORD,,