kstlib 0.0.1a0__py3-none-any.whl → 1.0.0__py3-none-any.whl

kstlib/utils/secure_delete.py

@@ -0,0 +1,205 @@
+"""Secure file deletion utilities."""
+
+from __future__ import annotations
+
+import os
+import platform
+import secrets
+import shutil
+import subprocess
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+DEFAULT_CHUNK_SIZE = 1024 * 1024
+
+
+class SecureDeleteMethod(str, Enum):
+    """Available strategies for securely deleting files."""
+
+    AUTO = "auto"
+    COMMAND = "command"
+    OVERWRITE = "overwrite"
+
+
+@dataclass(slots=True)
+class SecureDeleteReport:
+    """Summary result produced by :func:`secure_delete`."""
+
+    success: bool
+    method: SecureDeleteMethod
+    passes: int
+    command: Sequence[str] | None = None
+    message: str | None = None
+
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+def secure_delete(
+    target: Path | str,
+    *,
+    passes: int = 3,
+    method: SecureDeleteMethod | str = SecureDeleteMethod.AUTO,
+    chunk_size: int = DEFAULT_CHUNK_SIZE,
+    zero_last_pass: bool = True,
+) -> SecureDeleteReport:
+    """Securely remove ``target`` from disk.
+
+    Args:
+        target: File path that must be removed.
+        passes: Number of overwrite passes to perform when relying on the
+            built-in overwrite implementation. Values lower than ``1`` raise
+            ``ValueError``.
+        method: Preferred strategy. ``auto`` attempts to use a platform shred
+            command and falls back to overwriting when none is available or
+            when the command fails. ``command`` forces the usage of a system
+            command and reports an error if it is not available. ``overwrite``
+            forces the Python overwrite implementation.
+        chunk_size: Size, in bytes, of the chunks written during the overwrite
+            loop. Defaults to 1 MiB.
+        zero_last_pass: If ``True``, the final overwrite pass writes zeros
+            instead of random data.
+
+    Returns:
+        A :class:`SecureDeleteReport` describing the outcome.
+
+    Raises:
+        ValueError: If ``passes`` is lower than ``1`` or if ``target`` does not
+            reference a regular file.
+
+    Example:
+        Securely remove a cleartext file once it is no longer needed::
+
+            >>> from pathlib import Path
+            >>> from kstlib.utils.secure_delete import secure_delete, SecureDeleteMethod
+            >>> path = Path("secret.txt")
+            >>> _ = path.write_text("classified")  # doctest: +SKIP
+            >>> report = secure_delete(path, method=SecureDeleteMethod.OVERWRITE, passes=1)  # doctest: +SKIP
+            >>> report.success  # doctest: +SKIP
+            True
+    """
+    path = Path(target)
+
+    if passes < 1:
+        raise ValueError("passes must be >= 1")
+
+    if not path.exists():
+        return SecureDeleteReport(
+            success=True,
+            method=SecureDeleteMethod(method),
+            passes=passes,
+            message="Target already removed.",
+        )
+
+    if not path.is_file():
+        raise ValueError("secure_delete only supports regular files")
+
+    resolved_method = SecureDeleteMethod(method)
+
+    if resolved_method in {SecureDeleteMethod.AUTO, SecureDeleteMethod.COMMAND}:
+        command = _build_platform_command(path, passes, zero_last_pass)
+        if command is not None:
+            result = subprocess.run(
+                command,
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode == 0:
+                return SecureDeleteReport(
+                    success=True,
+                    method=SecureDeleteMethod.COMMAND,
+                    passes=passes,
+                    command=command,
+                )
+
+            if resolved_method == SecureDeleteMethod.COMMAND:
+                message = result.stderr.strip() or result.stdout.strip() or "command failed"
+                return SecureDeleteReport(
+                    success=False,
+                    method=SecureDeleteMethod.COMMAND,
+                    passes=passes,
+                    command=command,
+                    message=message,
+                )
+
+    overwrite_report = _overwrite_and_remove(path, passes, chunk_size, zero_last_pass)
+    if resolved_method == SecureDeleteMethod.COMMAND and not overwrite_report.success:
+        overwrite_report.method = SecureDeleteMethod.COMMAND
+    return overwrite_report
+
+
+def _build_platform_command(path: Path, passes: int, zero_last_pass: bool) -> list[str] | None:
+    """Return a platform-specific secure delete command when available."""
+    system = platform.system().lower()
+    shred_path = shutil.which("shred")
+    if shred_path:
+        command = [shred_path, "--force", "--remove"]
+        if passes:
+            command.append(f"--iterations={passes}")
+        if zero_last_pass:
+            command.append("--zero")
+        command.append(str(path))
+        return command
+
+    if system == "darwin":
+        srm_path = shutil.which("srm")
+        if srm_path:
+            command = [srm_path, "-f"]
+            if passes > 1:
+                command.append("-m")
+            if zero_last_pass:
+                command.append("-z")
+            command.append(str(path))
+            return command
+
+    return None
+
+
+def _overwrite_and_remove(
+    path: Path,
+    passes: int,
+    chunk_size: int,
+    zero_last_pass: bool,
+) -> SecureDeleteReport:
+    """Overwrite ``path`` with random data before unlinking it."""
+    try:
+        file_size = path.stat().st_size
+        if file_size == 0:
+            path.unlink(missing_ok=True)
+            return SecureDeleteReport(
+                success=True,
+                method=SecureDeleteMethod.OVERWRITE,
+                passes=passes,
+                message="Zero-length file removed.",
+            )
+
+        with path.open("r+b", buffering=0) as handle:
+            for index in range(passes):
+                handle.seek(0)
+                remaining = file_size
+                while remaining > 0:
+                    chunk = min(chunk_size, remaining)
+                    data = bytes(chunk) if index == passes - 1 and zero_last_pass else secrets.token_bytes(chunk)
+                    handle.write(data)
+                    remaining -= chunk
+                handle.flush()
+                os.fsync(handle.fileno())
+
+        path.unlink(missing_ok=True)
+        return SecureDeleteReport(
+            success=True,
+            method=SecureDeleteMethod.OVERWRITE,
+            passes=passes,
+            message="File overwritten and removed.",
+        )
+    except OSError as error:
+        return SecureDeleteReport(
+            success=False,
+            method=SecureDeleteMethod.OVERWRITE,
+            passes=passes,
+            message=str(error),
+        )

kstlib/utils/serialization.py

@@ -0,0 +1,247 @@
+"""Serialization utilities for JSON, YAML, and XML output.
+
+This module provides consistent serialization helpers used across kstlib,
+particularly for CLI output formatting.
+
+Example:
+    >>> from kstlib.utils.serialization import to_json, to_xml
+    >>> data = {"name": "test", "count": 42}
+    >>> print(to_json(data))
+    {
+      "name": "test",
+      "count": 42
+    }
+    >>> xml = '<?xml version="1.0"?><root><item>test</item></root>'
+    >>> print(to_xml(xml))  # doctest: +NORMALIZE_WHITESPACE
+    <?xml version="1.0" ?>
+    <root>
+      <item>test</item>
+    </root>
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+from xml.dom import minidom
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+def _default_encoder(obj: Any) -> Any:
+    """Default JSON encoder for complex types.
+
+    Handles:
+    - datetime objects (ISO format)
+    - Enum values
+    - Objects with __dict__ attribute
+    - Objects with to_dict() method
+
+    Args:
+        obj: Object to encode.
+
+    Returns:
+        JSON-serializable representation.
+
+    Raises:
+        TypeError: If object is not serializable.
+    """
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    if isinstance(obj, Enum):
+        return obj.value
+    if hasattr(obj, "to_dict"):
+        return obj.to_dict()
+    if hasattr(obj, "__dict__"):
+        return obj.__dict__
+    msg = f"Object of type {type(obj).__name__} is not JSON serializable"
+    raise TypeError(msg)
+
+
+def to_json(
+    data: Any,
+    *,
+    indent: int = 2,
+    sort_keys: bool = False,
+    default: Callable[[Any], Any] | None = None,
+) -> str:
+    r"""Serialize data to JSON string.
+
+    Args:
+        data: Data to serialize.
+        indent: Indentation level (default: 2).
+        sort_keys: Sort dictionary keys (default: False).
+        default: Custom encoder function (default: built-in handler).
+
+    Returns:
+        JSON string.
+
+    Example:
+        >>> to_json({"key": "value"})
+        '{\n  "key": "value"\n}'
+    """
+    encoder = default if default is not None else _default_encoder
+    return json.dumps(data, indent=indent, sort_keys=sort_keys, default=encoder)
+
+
+def to_xml(
+    xml_string: str,
+    *,
+    indent: str = "  ",
+) -> str:
+    """Pretty-print an XML string.
+
+    Uses xml.dom.minidom for formatting. Falls back to original string
+    if parsing fails.
+
+    Args:
+        xml_string: Raw XML string to format.
+        indent: Indentation string (default: 2 spaces).
+
+    Returns:
+        Formatted XML string with proper indentation.
+
+    Example:
+        >>> xml = '<?xml version="1.0"?><root><item>test</item></root>'
+        >>> formatted = to_xml(xml)
+        >>> '<root>' in formatted and '  <item>' in formatted
+        True
+    """
+    try:
+        # S318: Safe here - only used for display formatting, not for processing untrusted data
+        dom = minidom.parseString(xml_string.encode("utf-8"))  # noqa: S318
+        # toprettyxml adds extra blank lines, clean them up
+        pretty = dom.toprettyxml(indent=indent)
+        # Remove extra blank lines that minidom creates
+        lines = [line for line in pretty.split("\n") if line.strip()]
+        return "\n".join(lines)
+    except Exception:
+        # If parsing fails, return original string
+        return xml_string
+
+
+def is_xml_content(content: str, content_type: str | None = None) -> bool:
+    """Check if content is XML based on content-type header or content inspection.
+
+    Args:
+        content: The content string to check.
+        content_type: Optional Content-Type header value.
+
+    Returns:
+        True if content appears to be XML.
+
+    Example:
+        >>> is_xml_content('<root/>', 'application/xml')
+        True
+        >>> is_xml_content('<?xml version="1.0"?><root/>')
+        True
+        >>> is_xml_content('{"key": "value"}')
+        False
+    """
+    # Check content-type header first
+    if content_type:
+        ct_lower = content_type.lower()
+        if "xml" in ct_lower:
+            return True
+
+    # Fallback: check content starts with XML markers
+    stripped = content.strip()
+    return stripped.startswith(("<?xml", "<"))
+
+
+def to_yaml_like(data: dict[str, Any], *, indent: int = 0) -> str:
+    """Format dictionary as YAML-like readable output.
+
+    This is a simplified formatter for CLI output, not full YAML.
+    Handles nested dicts, lists, and converts timestamps to ISO format.
+
+    Args:
+        data: Dictionary to format.
+        indent: Base indentation level.
+
+    Returns:
+        YAML-like formatted string.
+
+    Example:
+        >>> print(to_yaml_like({"name": "test", "items": ["a", "b"]}))
+        name: test
+        items:
+          - a
+          - b
+    """
+    lines: list[str] = []
+    prefix = "  " * indent
+
+    for key, value in data.items():
+        if isinstance(value, dict):
+            lines.append(f"{prefix}{key}:")
+            lines.append(to_yaml_like(value, indent=indent + 1))
+        elif isinstance(value, list):
+            lines.append(f"{prefix}{key}:")
+            for item in value:
+                if isinstance(item, dict):
+                    # Nested dict in list
+                    lines.append(f"{prefix}  -")
+                    lines.append(to_yaml_like(item, indent=indent + 2))
+                else:
+                    lines.append(f"{prefix}  - {item}")
+        elif isinstance(value, datetime):
+            lines.append(f"{prefix}{key}: {value.isoformat()}")
+        elif isinstance(value, Enum):
+            lines.append(f"{prefix}{key}: {value.value}")
+        elif value is None:
+            lines.append(f"{prefix}{key}: ~")
+        elif isinstance(value, bool):
+            lines.append(f"{prefix}{key}: {str(value).lower()}")
+        else:
+            lines.append(f"{prefix}{key}: {value}")
+
+    return "\n".join(lines)
+
+
+def format_output(
+    data: Any,
+    *,
+    output_format: str = "yaml",
+) -> str:
+    """Format data for CLI output.
+
+    Args:
+        data: Data to format.
+        output_format: Output format - "json" or "yaml" (default: "yaml").
+
+    Returns:
+        Formatted string ready for display.
+
+    Raises:
+        ValueError: If output_format is not recognized.
+
+    Example:
+        >>> print(format_output({"key": "value"}, output_format="json"))
+        {
+          "key": "value"
+        }
+    """
+    fmt = output_format.lower()
+
+    if fmt == "json":
+        return to_json(data)
+    if fmt in ("yaml", "text"):
+        if isinstance(data, dict):
+            return to_yaml_like(data)
+        return str(data)
+
+    msg = f"Unknown output format: {output_format}. Use 'json' or 'yaml'."
+    raise ValueError(msg)
+
+
+__all__ = [
+    "format_output",
+    "is_xml_content",
+    "to_json",
+    "to_xml",
+    "to_yaml_like",
+]

kstlib/utils/text.py

@@ -0,0 +1,56 @@
+"""Text manipulation helpers."""
+
+from __future__ import annotations
+
+import importlib
+import re
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+else:  # pragma: no cover - runtime alias for delayed evaluation
+    Mapping = importlib.import_module("collections.abc").Mapping
+
+_PLACEHOLDER_PATTERN = re.compile(r"{{\s*(?P<key>[\w.\-]+)\s*}}")
+
+
+def replace_placeholders(template: str, values: Mapping[str, Any] | None = None, /, **kwargs: Any) -> str:
+    """Replace ``{{ placeholder }}`` tokens within *template*.
+
+    Args:
+        template: Raw template string containing placeholder patterns.
+        values: Optional mapping used to look up replacement values. When provided,
+            it is merged with the keyword arguments, giving precedence to the latter.
+        **kwargs: Additional placeholder values.
+
+    Returns:
+        Rendered template with matching placeholders substituted by their string
+        representation. Missing placeholders are left untouched to simplify
+        incremental rendering.
+
+    Examples:
+        >>> replace_placeholders("Hello {{ name }}!", name="Ada")
+        'Hello Ada!'
+
+    """
+    combined: dict[str, Any] = {}
+    if values:
+        combined.update(dict(values))
+    if kwargs:
+        combined.update(kwargs)
+
+    def _replace(match: re.Match[str]) -> str:
+        key = match.group("key")
+        if key not in combined:
+            return match.group(0)
+        value = combined[key]
+        if value is None:
+            return ""
+        if isinstance(value, str | int | float | bool):
+            return str(value)
+        return "[object]"
+
+    return _PLACEHOLDER_PATTERN.sub(_replace, template)
+
+
+__all__ = ["replace_placeholders"]

kstlib/utils/validators.py

@@ -0,0 +1,124 @@
+"""Validation utilities used across kstlib."""
+
+from __future__ import annotations
+
+import importlib
+import re
+from dataclasses import dataclass
+from email.utils import formataddr, parseaddr
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+else:  # pragma: no cover - runtime alias for delayed evaluation
+    Iterable = importlib.import_module("collections.abc").Iterable
+
+_EMAIL_PATTERN = re.compile(r"^[^\s@<>]+@[^\s@<>]+\.[^\s@<>]+$")
+
+LOCAL_PART_MAX_LENGTH = 64
+DOMAIN_MAX_LENGTH = 255
+LABEL_MAX_LENGTH = 63
+MIN_LABEL_COUNT = 2
+MIN_TLD_LENGTH = 2
+
+
+class ValidationError(ValueError):
+    """Raised when user supplied values fail validation."""
+
+
+@dataclass(frozen=True, slots=True)
+class EmailAddress:
+    """Normalized representation of an email address."""
+
+    name: str
+    address: str
+
+    @property
+    def formatted(self) -> str:
+        """Return ``"Name <email@domain>"`` if a display name is present."""
+        if not self.name:
+            return self.address
+        sanitized = self.name.replace("\r", " ").replace("\n", " ").strip()
+        if not sanitized:
+            return self.address
+        sanitized = sanitized.replace('"', "'")
+        return formataddr((sanitized, self.address))
+
+
+def parse_email_address(value: str) -> EmailAddress:
+    """Parse *value* into a validated :class:`EmailAddress`.
+
+    Args:
+        value: Raw email string, optionally containing a display name.
+
+    Returns:
+        A normalized :class:`EmailAddress` instance.
+
+    Raises:
+        ValidationError: If the string does not contain a valid address.
+
+    Examples:
+        >>> parse_email_address("Ada Lovelace <ADA@example.COM>").formatted
+        'Ada Lovelace <ada@example.com>'
+        >>> parse_email_address("foo@bar")
+        Traceback (most recent call last):
+        ...
+        kstlib.utils.validators.ValidationError: Invalid email address: 'foo@bar'
+    """
+    if not value:
+        raise ValidationError("Email address cannot be empty")
+
+    name, address = parseaddr(value)
+    address = address.strip().lower()
+
+    if name:
+        start = value.find("<")
+        end = value.rfind(">")
+        candidate = value[start + 1 : end].strip() if start != -1 and end != -1 and end > start else address
+    else:
+        candidate = value.strip()
+
+    if candidate.lower() != address:
+        raise ValidationError(f"Invalid email address: {value!r}")
+
+    if not _EMAIL_PATTERN.match(address):
+        raise ValidationError(f"Invalid email address: {value!r}")
+
+    local_part, _, domain_part = address.partition("@")
+    if len(local_part) == 0 or len(local_part) > LOCAL_PART_MAX_LENGTH:
+        raise ValidationError(f"Invalid email address: {value!r}")
+
+    if len(domain_part) == 0 or len(domain_part) > DOMAIN_MAX_LENGTH:
+        raise ValidationError(f"Invalid email address: {value!r}")
+
+    labels = domain_part.split(".")
+    if len(labels) < MIN_LABEL_COUNT or any(len(label) == 0 or len(label) > LABEL_MAX_LENGTH for label in labels):
+        raise ValidationError(f"Invalid email address: {value!r}")
+
+    if len(labels[-1]) < MIN_TLD_LENGTH:
+        raise ValidationError(f"Invalid email address: {value!r}")
+
+    name = name.strip()
+    return EmailAddress(name=name, address=address)
+
+
+def normalize_address_list(values: Iterable[str]) -> list[EmailAddress]:
+    """Validate and normalize a sequence of email addresses.
+
+    Examples:
+        >>> normalize_address_list([
+        ...     "Ada Lovelace <ada@example.com>",
+        ...     "grace@example.net",
+        ... ])  # doctest: +NORMALIZE_WHITESPACE
+        [EmailAddress(name='Ada Lovelace', address='ada@example.com'),
+         EmailAddress(name='', address='grace@example.net')]
+    """
+    return [parse_email_address(value) for value in values]
+
+
+__all__ = [
+    "EmailAddress",
+    "ValidationError",
+    "normalize_address_list",
+    "parse_email_address",
+]