protegrity-ai-developer-python 1.2.1__py3-none-any.whl

appython/service/request_handler.py

@@ -0,0 +1,115 @@
+"""
+This module provides the RequestHandler class, which is responsible for sending HTTP requests to a specified API
+endpoint using the `requests` library. It includes methods to send POST requests with JSON payloads and handle
+the necessary headers for authentication.
+"""
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+
+_DEFAULT_TIMEOUT = 30
+_DEFAULT_MAX_RETRIES = 3
+
+# One Session per (max_retries, backoff) combination so a connection pool can be
+# reused across calls without re-mounting adapters on every request.
+_session_cache: dict = {}
+
+
+def _get_session(max_retries: int) -> requests.Session:
+    sess = _session_cache.get(max_retries)
+    if sess is not None:
+        return sess
+    sess = requests.Session()
+    if max_retries > 0:
+        retry = Retry(
+            total=max_retries,
+            connect=max_retries,
+            read=max_retries,
+            status=max_retries,
+            status_forcelist=(429, 500, 502, 503, 504),
+            allowed_methods=frozenset(["GET", "POST", "PUT", "DELETE"]),
+            backoff_factor=0.5,  # 0.5s, 1s, 2s, 4s, ...
+            respect_retry_after_header=True,
+            raise_on_status=False,
+        )
+        adapter = HTTPAdapter(max_retries=retry)
+        sess.mount("https://", adapter)
+        sess.mount("http://", adapter)
+    _session_cache[max_retries] = sess
+    return sess
+
+
+def _resolve_resilience(config):
+    """Pull timeout (seconds) and max_retries from an SDK config dict."""
+    if not config:
+        return _DEFAULT_TIMEOUT, _DEFAULT_MAX_RETRIES
+    try:
+        timeout = int(config.get("request_timeout", _DEFAULT_TIMEOUT))
+    except (TypeError, ValueError):
+        timeout = _DEFAULT_TIMEOUT
+    try:
+        retries = int(config.get("max_retries", _DEFAULT_MAX_RETRIES))
+    except (TypeError, ValueError):
+        retries = _DEFAULT_MAX_RETRIES
+    return max(1, timeout), max(0, retries)
+
+
+class RequestHandler:
+    def send_api_request(
+        payload: dict, base_url: str, api_key: str, jwt_token: str
+    ) -> requests.Response:
+        """
+        Sends a POST request to the specified API endpoint with a JSON payload.
+        Legacy method retained for backward compatibility.
+
+        Parameters:
+            payload (dict): The JSON-serializable payload to send in the request body.
+            base_url (str): The full URL of the API endpoint to which the request is sent.
+            api_key (str): API key for x-api-key header.
+            jwt_token (str): JWT token for Authorization header.
+
+        Returns:
+            Response: The HTTP response object returned by the `requests.post` call.
+        """
+        headers = {
+            "Content-Type": "application/json",
+            "x-api-key": api_key,
+            "Authorization": jwt_token,
+        }
+        # Legacy path: apply default timeout but no retries (preserves caller
+        # behavior for the older DE auth flow).
+        response = requests.post(
+            base_url, json=payload, headers=headers, timeout=_DEFAULT_TIMEOUT
+        )
+        return response
+
+    def send_request(
+        payload: dict, url: str, auth_provider, config: dict = None
+    ) -> requests.Response:
+        """
+        Sends a POST request using the pluggable auth provider for authentication.
+
+        Parameters:
+            payload (dict): The JSON-serializable payload to send in the request body.
+            url (str): The full URL of the API endpoint.
+            auth_provider: An AuthProvider instance that signs the request.
+            config (dict, optional): SDK config dict. Honors keys:
+                - "request_timeout" (seconds, default 30) — per-attempt HTTP timeout.
+                - "max_retries" (int, default 3) — retries on connection errors and
+                  HTTP 429/5xx with exponential backoff and jitter. 0 disables retries.
+
+        Returns:
+            Response: The HTTP response object returned by the `requests.post` call.
+        """
+        timeout, max_retries = _resolve_resilience(config)
+        headers = {"Content-Type": "application/json"}
+        headers = auth_provider.authenticate_request("POST", url, headers, payload)
+        kwargs = auth_provider.get_request_kwargs()
+        session = _get_session(max_retries)
+        response = session.post(
+            url, json=payload, headers=headers, timeout=timeout, **kwargs
+        )
+        return response
+

appython/service/response_handler.py

@@ -0,0 +1,78 @@
+"""
+This module provides the ResponseHandler class, which processes HTTP responses from the API.
+"""
+
+from appython.utils.output_postprocessor import OutputProcessor
+from appython.utils.constants import (
+    RETURN_CODE as return_code,
+    LOG_RETURN_CODE_UNSUPPORTED as log_return_code
+)
+from appython.utils.exceptions import PythonSDKException
+
+
+class ResponseHandler:
+    @staticmethod
+    def process(response, return_type: dict, operation_type: str):
+        """
+        Processes the HTTP response from the API and restores the original data type(s) of the result.
+
+        This method handles both successful and error responses. For successful responses (HTTP 200),
+        it checks the return code inside the response payload and uses the OutputProcessor to convert
+        the returned data into its original type(s) based on the `return_type` metadata.
+
+        Parameters:
+            response (requests.Response): The HTTP response object returned by the API call.
+            return_type (dict): Metadata describing how to interpret the response data. Keys include:
+                - "is_bulk" (bool): Whether the response contains a list of values.
+                - "response_type" (type): The expected type of the response values.
+                - "type" (type): The container type for the result (e.g., list, tuple).
+                - "isENC" (bool): Whether the data is base64-encoded.
+                - "charset" (Charset, optional): Character encoding used for decoding bytes.
+
+        Returns:
+            The processed result, either as a single value or a collection (list or tuple),
+            along with a tuple of return codes if bulk.
+
+        Raises:
+            Exception: If the return code indicates failure, if the response is malformed,
+                        or if the data cannot be decoded or restored properly.
+        """
+        if response.status_code == 200:
+            response_json = response.json()
+            is_query_success = response_json.get("success")
+
+            if not is_query_success:
+                try:
+                    message = response.json().get("error_msg", "Unknown Error")
+                    mapped_message = PythonSDKException.map_error_message(message)
+                except Exception:
+                    mapped_message = "Failed to parse error message from response"
+                raise Exception(mapped_message)
+
+            data = response_json.get("results")
+            try:
+                result = OutputProcessor.restore_original_type(data, return_type)
+
+                if not return_type.get("is_bulk", False):
+                    return result
+                else:
+                    return_type_cls = return_type.get("type", list)
+                    if return_type_cls == tuple:
+                        return tuple(result), (return_code[operation_type],) * len(data)
+                    else:
+                        return result, (return_code[operation_type],) * len(data)
+            except Exception:
+                raise Exception(f"26, {log_return_code[26]}")  # Error in setting data
+        else:
+            is_query_success = response.json().get("success", "Unknown Error")
+            if not is_query_success:
+                try:
+                    message = response.json().get("error_msg", "Unknown Error")
+                    mapped_message = PythonSDKException.map_error_message(message)
+                except Exception:
+                    mapped_message = "Failed to parse error message from response"
+                raise Exception(mapped_message)
+            
+            message = response.json().get("message", "Could not process the request")
+            raise Exception(message)
+

appython/stats/__init__.py

@@ -0,0 +1,3 @@
+"""Usage statistics collection for migration readiness assessment."""
+
+from appython.stats.collector import UsageCollector

appython/stats/collector.py

@@ -0,0 +1,90 @@
+"""
+In-memory usage statistics collector.
+
+Accumulates operation counts during a session and flushes to disk on close.
+"""
+
+import os
+from datetime import date, datetime
+
+
+def _stats_enabled():
+    """Check if stats collection is enabled.
+
+    Stats are only collected when DEV_EDITION_* env vars are set (i.e. Developer Edition).
+    Can be explicitly overridden with PTY_STATS=true/false.
+    """
+    explicit = os.getenv("PTY_STATS")
+    if explicit is not None:
+        return explicit.lower() not in ("false", "0", "no", "off")
+    # Default: enabled only when Developer Edition env vars are present
+    return any(k.startswith("DEV_EDITION_") for k in os.environ)
+
+
+class UsageCollector:
+    """Collects usage statistics in memory during a session.
+
+    Stats are accumulated per data element and policy user, then flushed
+    to disk when flush() is called (typically on session close).
+    """
+
+    def __init__(self, user):
+        self._enabled = _stats_enabled()
+        self._user = user
+        self._data_elements = {}
+        self._session_started = date.today().isoformat()
+
+    @property
+    def enabled(self):
+        return self._enabled
+
+    def record_protect(self, data_element):
+        """Record a protect operation for a data element."""
+        if not self._enabled:
+            return
+        self._ensure_element(data_element)
+        self._data_elements[data_element]["protect_count"] += 1
+        self._data_elements[data_element]["last_used"] = date.today().isoformat()
+
+    def record_unprotect(self, data_element):
+        """Record an unprotect operation for a data element."""
+        if not self._enabled:
+            return
+        self._ensure_element(data_element)
+        self._data_elements[data_element]["unprotect_count"] += 1
+        self._data_elements[data_element]["last_used"] = date.today().isoformat()
+
+    def record_reprotect(self, source_de, target_de):
+        """Record a reprotect operation for source and target data elements."""
+        if not self._enabled:
+            return
+        self._ensure_element(source_de)
+        self._ensure_element(target_de)
+        self._data_elements[source_de]["reprotect_source_count"] += 1
+        self._data_elements[source_de]["last_used"] = date.today().isoformat()
+        self._data_elements[target_de]["reprotect_target_count"] += 1
+        self._data_elements[target_de]["last_used"] = date.today().isoformat()
+
+    def get_session_data(self):
+        """Return collected stats for this session.
+
+        Returns:
+            dict: Session stats with user, data_elements, and metadata.
+        """
+        return {
+            "user": self._user,
+            "data_elements": dict(self._data_elements),
+        }
+
+    def _ensure_element(self, data_element):
+        """Ensure a data element entry exists in the collection."""
+        if data_element not in self._data_elements:
+            today = date.today().isoformat()
+            self._data_elements[data_element] = {
+                "protect_count": 0,
+                "unprotect_count": 0,
+                "reprotect_source_count": 0,
+                "reprotect_target_count": 0,
+                "first_used": today,
+                "last_used": today,
+            }

appython/stats/writer.py

@@ -0,0 +1,185 @@
+"""
+Persistent storage for usage statistics.
+
+Reads, merges, and writes the JSON stats file with file locking
+for multi-process safety.
+"""
+
+import json
+import logging
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_SCHEMA_VERSION = "1.0"
+
+
+# Cross-platform exclusive file locking. fcntl.flock is unix-only; Windows
+# CPython (including Git Bash / MINGW which runs the Windows interpreter)
+# does not ship it. msvcrt.locking provides equivalent semantics there.
+if sys.platform == "win32":
+    import msvcrt
+
+    def _lock_exclusive(fd):
+        # msvcrt requires a nonzero byte count. Lock 1 byte from offset 0;
+        # this is sufficient as an advisory whole-file lock for our use.
+        os.lseek(fd, 0, os.SEEK_SET)
+        while True:
+            try:
+                msvcrt.locking(fd, msvcrt.LK_LOCK, 1)
+                return
+            except OSError:
+                # LK_LOCK blocks ~10s then raises; retry until acquired.
+                continue
+
+    def _unlock(fd):
+        try:
+            os.lseek(fd, 0, os.SEEK_SET)
+            msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+        except OSError:
+            pass
+else:
+    import fcntl
+
+    def _lock_exclusive(fd):
+        fcntl.flock(fd, fcntl.LOCK_EX)
+
+    def _unlock(fd):
+        fcntl.flock(fd, fcntl.LOCK_UN)
+
+
+def _stats_path():
+    """Return the path to the usage stats file."""
+    custom = os.getenv("PTY_STATS_FILE")
+    if custom:
+        return Path(custom)
+    return Path.home() / ".protegrity" / "usage_stats.json"
+
+
+def _empty_stats():
+    """Return a fresh empty stats structure."""
+    now = datetime.utcnow().isoformat(timespec="seconds") + "Z"
+    return {
+        "schema_version": _SCHEMA_VERSION,
+        "collected_since": now,
+        "last_updated": now,
+        "data_elements": {},
+        "policy_users": {},
+    }
+
+
+def _read_stats(path):
+    """Read existing stats file. Returns None if not found or invalid."""
+    if not path.is_file():
+        return None
+    try:
+        with open(path, "r") as f:
+            data = json.load(f)
+        if data.get("schema_version") == _SCHEMA_VERSION:
+            return data
+        return None
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def _merge_session(existing, session_data):
+    """Merge a session's collected stats into the existing stats structure.
+
+    Args:
+        existing: The full stats dict (will be mutated).
+        session_data: Dict from UsageCollector.get_session_data().
+    """
+    now = datetime.utcnow().isoformat(timespec="seconds") + "Z"
+    existing["last_updated"] = now
+
+    # Merge data elements
+    for de_name, de_stats in session_data.get("data_elements", {}).items():
+        if de_name not in existing["data_elements"]:
+            existing["data_elements"][de_name] = {
+                "protect_count": 0,
+                "unprotect_count": 0,
+                "reprotect_source_count": 0,
+                "reprotect_target_count": 0,
+                "first_used": de_stats["first_used"],
+                "last_used": de_stats["last_used"],
+            }
+        target = existing["data_elements"][de_name]
+        target["protect_count"] += de_stats["protect_count"]
+        target["unprotect_count"] += de_stats["unprotect_count"]
+        target["reprotect_source_count"] += de_stats["reprotect_source_count"]
+        target["reprotect_target_count"] += de_stats["reprotect_target_count"]
+        # Update last_used if session is more recent
+        if de_stats["last_used"] > target.get("last_used", ""):
+            target["last_used"] = de_stats["last_used"]
+        # Keep earliest first_used
+        if de_stats["first_used"] < target.get("first_used", "9999-12-31"):
+            target["first_used"] = de_stats["first_used"]
+
+    # Merge policy user
+    user = session_data.get("user")
+    if user:
+        today = datetime.utcnow().strftime("%Y-%m-%d")
+        if user not in existing["policy_users"]:
+            existing["policy_users"][user] = {
+                "session_count": 0,
+                "first_used": today,
+                "last_used": today,
+            }
+        existing["policy_users"][user]["session_count"] += 1
+        existing["policy_users"][user]["last_used"] = today
+
+
+def flush_stats(session_data):
+    """Flush session stats to disk with file locking.
+
+    Reads existing stats, merges in session data, writes back atomically.
+    Degrades gracefully — never raises exceptions to caller.
+
+    Args:
+        session_data: Dict from UsageCollector.get_session_data().
+    """
+    try:
+        # During interpreter shutdown, modules may be None
+        if json is None or os is None:
+            return
+
+        path = _stats_path()
+
+        # Ensure directory exists
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Open (or create) with exclusive lock
+        fd = os.open(str(path), os.O_RDWR | os.O_CREAT, 0o644)
+        try:
+            _lock_exclusive(fd)
+            # Read existing
+            with os.fdopen(os.dup(fd), "r") as f:
+                try:
+                    content = f.read()
+                    existing = json.loads(content) if content.strip() else None
+                except (json.JSONDecodeError, OSError):
+                    existing = None
+
+            if existing is None or existing.get("schema_version") != _SCHEMA_VERSION:
+                existing = _empty_stats()
+
+            # Merge
+            _merge_session(existing, session_data)
+
+            # Write back (truncate and rewrite)
+            os.lseek(fd, 0, os.SEEK_SET)
+            os.ftruncate(fd, 0)
+            data_bytes = json.dumps(existing, indent=2).encode("utf-8")
+            os.write(fd, data_bytes)
+        finally:
+            _unlock(fd)
+            os.close(fd)
+
+    except Exception as e:
+        # Graceful degradation: log warning, never impact SDK operation
+        # During interpreter shutdown, modules may already be torn down
+        if json is not None and os is not None:
+            logger.warning("Failed to write usage stats: %s", e)

appython/utils/codec_helper.py

@@ -0,0 +1,86 @@
+"""
+This module provides helper functions for encoding and decoding data, particularly focusing on
+base64 transformations and character set handling. It includes functions to convert between byte
+strings and base64-encoded strings, as well as functions to decode byte data based on specified
+character sets and operation types.
+"""
+
+import base64
+from appython.utils.constants import Charset, OP_TYPE as op_type
+
+
+def convert_b64_bytes_b64_string(data: bytes) -> str:
+    """
+    Encodes a byte string into a base64-encoded UTF-8 string.
+
+    Parameters:
+        data (bytes): The input byte data to encode.
+
+    Returns:
+        str: A base64-encoded string representation of the input bytes.
+    """
+    return base64.b64encode(data).decode("utf-8")
+
+
+def convert_bytes_b64_string(data: bytes, charset: str) -> str:
+    """
+    Encodes byte data into a base64 string and re-encodes it using the specified character set.
+
+    Parameters:
+        data (bytes): The input byte data to encode.
+        charset (str): The character set to use for encoding the base64 string.
+
+    Returns:
+        str: A base64-encoded string re-encoded using the specified charset.
+    """
+    return base64.b64encode(data).decode("ascii").encode(charset).decode(charset)
+
+
+def decode_bytes(data: bytes, charset: Charset, is_enc: bool, operation: str) -> str:
+    """
+    Decodes byte data into a string, optionally applying base64 decoding based on the operation type.
+
+    Parameters:
+        data (bytes): The byte data to decode.
+        charset (Charset): The character set to use for decoding.
+        is_enc (bool): Indicates whether the data is base64-encoded.
+        operation (str): The operation type (e.g., 'PROTECT', 'UNPROTECT', 'REPROTECT').
+
+    Returns:
+        str: The decoded string.
+
+    Raises:
+        Exception: If the operation type is unsupported.
+    """
+
+    if not is_enc:
+        return data.decode(charset.name.lower())
+    if op_type[operation] in ["UNPROTECT", "REPROTECT"]:
+        return convert_b64_bytes_b64_string(data)
+    return convert_bytes_b64_string(data, charset.name.lower())
+
+
+def encode_to_base64_string(data) -> str:
+    """
+    Converts any input data to a UTF-8 base64-encoded string.
+
+    Parameters:
+        data: The input data to encode (typically str, int, float, etc.).
+
+    Returns:
+        str: A base64-encoded UTF-8 string representation of the input.
+    """
+    return base64.b64encode(str(data).encode("utf-8")).decode("utf-8")
+
+
+def get_str_from_b64(data: str):
+    """
+    Decodes a base64-encoded UTF-8 string back to its original string form.
+
+    Parameters:
+        data (str): The base64-encoded string.
+
+    Returns:
+        str: The decoded original string.
+    """
+    return base64.b64decode(data.encode("utf-8")).decode("utf-8")