simple-resume 0.1.9__py3-none-any.whl

simple_resume/core/palettes/generators.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""Provide procedural palette generators."""
+
+from __future__ import annotations
+
+import colorsys
+import hashlib
+import math
+
+# Default deterministic seed for consistent color palette generation
+# Format: YYYYMMDD (November 1, 2025) - ensures reproducible palettes across runs
+DEFAULT_SEED = 20251101
+
+
+class DeterministicRNG:
+    """Define a deterministic random number generator using hash-based seeding."""
+
+    def __init__(self, seed: int):
+        """Initialize the deterministic RNG with a seed.
+
+        Args:
+            seed: The seed for the random number generator.
+
+        """
+        self.seed = seed
+        self.state = seed
+
+    def random(self) -> float:
+        """Generate a deterministic random float between 0 and 1."""
+        self.state += 1
+        hash_input = f"{self.seed}-{self.state}".encode()
+        # 64-bit digest keeps deterministic behavior without wasting work
+        hash_bytes = hashlib.blake2s(hash_input, digest_size=8).digest()
+        hash_int = int.from_bytes(hash_bytes, "big")
+        return hash_int / (2**64 - 1)
+
+    def uniform(self, a: float, b: float) -> float:
+        """Generate a deterministic random float between a and b."""
+        return a + self.random() * (b - a)
+
+
+def _clamp(value: float, low: float, high: float) -> float:
+    """Restrict a value to the [low, high] interval."""
+    return max(low, min(value, high))
+
+
+def _wrap_hue(value: float) -> float:
+    """Wrap a hue value into [0, 360) degrees."""
+    return value % 360.0
+
+
+def _generate_hues(
+    *,
+    start: float,
+    end: float,
+    count: int,
+    rng: DeterministicRNG,
+) -> list[float]:
+    """Return evenly distributed hues between start and end (inclusive)."""
+    start = _wrap_hue(start)
+    end = _wrap_hue(end)
+
+    if count == 1:
+        return [start]
+
+    span = (end - start) % 360.0
+    if math.isclose(span, 0.0):
+        span = 360.0
+
+    step = span / (count - 1)
+    return [
+        _wrap_hue(start + index * step + rng.uniform(-step * 0.05, step * 0.05))
+        for index in range(count)
+    ]
+
+
+def _generate_luminance_values(
+    *,
+    start: float,
+    end: float,
+    count: int,
+) -> list[float]:
+    """Return interpolated luminance values."""
+    if count == 1:
+        return [_clamp(start, 0.0, 1.0)]
+    step = (end - start) / (count - 1)
+    return [_clamp(start + index * step, 0.0, 1.0) for index in range(count)]
+
+
+def _hsl_to_hex(hue: float, saturation: float, luminance: float) -> str:
+    """Convert HSL values to a hex string."""
+    r, g, b = colorsys.hls_to_rgb(hue / 360.0, luminance, saturation)
+    r_hex = f"{int(_clamp(r, 0.0, 1.0) * 255 + 0.5):02X}"
+    g_hex = f"{int(_clamp(g, 0.0, 1.0) * 255 + 0.5):02X}"
+    b_hex = f"{int(_clamp(b, 0.0, 1.0) * 255 + 0.5):02X}"
+    return f"#{r_hex}{g_hex}{b_hex}"
+
+
+def generate_hcl_palette(
+    size: int,
+    *,
+    seed: int | None = None,
+    hue_range: tuple[float, float] = (0.0, 360.0),
+    chroma: float = 0.12,
+    luminance_range: tuple[float, float] = (0.35, 0.85),
+) -> list[str]:
+    """Generate a deterministic palette in an HCL-inspired fashion.
+
+    Args:
+        size: Number of swatches to produce.
+        seed: Optional deterministic seed. Defaults to a project seed.
+        hue_range: Inclusive range of hue values (degrees).
+        chroma: Saturation component (0-1, approximated using HSL saturation).
+        luminance_range: Inclusive range of luminance/lightness values.
+
+    Returns:
+        List of hex color strings.
+
+    """
+    if size <= 0:
+        raise ValueError("size must be a positive integer")
+
+    rng = DeterministicRNG(seed if seed is not None else DEFAULT_SEED)
+    hue_start, hue_end = hue_range
+    lum_start, lum_end = luminance_range
+
+    hues = _generate_hues(start=hue_start, end=hue_end, count=size, rng=rng)
+    luminances = _generate_luminance_values(start=lum_start, end=lum_end, count=size)
+
+    saturation = _clamp(chroma, 0.0, 1.0)
+    colors: list[str] = []
+    for hue, luminance in zip(hues, luminances):
+        colors.append(_hsl_to_hex(hue, saturation, _clamp(luminance, 0.0, 1.0)))
+    return colors
+
+
+__all__ = ["generate_hcl_palette"]

simple_resume/core/palettes/registry.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Provide a palette registry that aggregates multiple providers."""
+
+from __future__ import annotations
+
+import json
+from typing import Callable
+
+from simple_resume.core.palettes.common import Palette
+
+
+class PaletteRegistry:
+    """Define an in-memory registry of named palettes."""
+
+    def __init__(self) -> None:
+        """Initialize an empty palette registry."""
+        self._palettes: dict[str, Palette] = {}
+
+    def register(self, palette: Palette) -> None:
+        """Register or overwrite a palette."""
+        key = palette.name.lower()
+        self._palettes[key] = palette
+
+    def get(self, name: str) -> Palette:
+        """Return a palette by name."""
+        key = name.lower()
+        try:
+            return self._palettes[key]
+        except KeyError as exc:
+            raise KeyError(f"Palette not found: {name}") from exc
+
+    def list(self) -> list[Palette]:
+        """Return all registered palettes sorted by name."""
+        return [self._palettes[key] for key in sorted(self._palettes)]
+
+    def to_json(self) -> str:
+        """Serialize the registry to JSON."""
+        return json.dumps([palette.to_dict() for palette in self.list()], indent=2)
+
+
+_CACHE_ENV = "SIMPLE_RESUME_PALETTE_CACHE"
+
+
+def build_palette_registry(
+    *,
+    default_loader: Callable[[], list[Palette]] | None = None,
+    palettable_loader: Callable[[], list[Palette]] | None = None,
+) -> PaletteRegistry:
+    """Build a palette registry with custom loader functions.
+
+    Args:
+        default_loader: Function to load default palettes
+        palettable_loader: Function to load palettable palettes
+
+    Returns:
+        PaletteRegistry populated with palettes from the specified loaders
+
+    """
+    registry = PaletteRegistry()
+
+    if default_loader:
+        for palette in default_loader():
+            registry.register(palette)
+
+    if palettable_loader:
+        for palette in palettable_loader():
+            registry.register(palette)
+
+    return registry
+
+
+__all__ = [
+    "Palette",
+    "PaletteRegistry",
+    "build_palette_registry",
+]

simple_resume/core/palettes/resolution.py

@@ -0,0 +1,123 @@
+"""Pure palette resolution logic without network I/O.
+
+This module contains pure functions that resolve palette configurations
+into either colors or fetch requests, without performing any I/O operations.
+"""
+
+from typing import Any
+
+from simple_resume.core.constants.colors import CONFIG_COLOR_FIELDS
+from simple_resume.core.palettes.common import PaletteSource
+from simple_resume.core.palettes.exceptions import (
+    PaletteError,
+    PaletteGenerationError,
+    PaletteLookupError,
+)
+from simple_resume.core.palettes.fetch_types import (
+    PaletteFetchRequest,
+    PaletteResolution,
+)
+from simple_resume.core.palettes.generators import generate_hcl_palette
+from simple_resume.core.palettes.registry import PaletteRegistry
+
+
+def resolve_palette_config(
+    block: dict[str, Any], *, registry: PaletteRegistry
+) -> PaletteResolution:
+    """Pure palette resolution - returns colors OR fetch request.
+
+    This function performs pure logic to determine what colors are needed
+    and how to obtain them. It never performs I/O operations.
+
+    Args:
+        block: Palette configuration block from resume config.
+        registry: Palette registry to look up named palettes (injected dependency).
+
+    Returns:
+        PaletteResolution with either colors (for local sources) or
+        a fetch request (for remote sources).
+
+    Raises:
+        PaletteError: If palette configuration is invalid.
+
+    """
+    try:
+        source = PaletteSource.normalize(block.get("source"), param_name="palette")
+    except (TypeError, ValueError) as exc:
+        raise PaletteError(
+            f"Unsupported palette source: {block.get('source')}"
+        ) from exc
+
+    if source is PaletteSource.REGISTRY:
+        """Pure lookup from local registry (no I/O)."""
+        name = block.get("name")
+        if not name:
+            raise PaletteLookupError("registry source requires 'name'")
+
+        palette = registry.get(str(name))
+
+        colors = list(palette.swatches)
+        metadata = {
+            "source": source.value,
+            "name": palette.name,
+            "size": len(palette.swatches),
+            "attribution": palette.metadata,
+        }
+
+        return PaletteResolution(colors=colors, metadata=metadata)
+
+    elif source is PaletteSource.GENERATOR:
+        """Pure generation - no I/O."""
+
+        size = int(block.get("size", len(CONFIG_COLOR_FIELDS)))
+        seed = block.get("seed")
+        hue_range = tuple(block.get("hue_range", (0, 360)))
+        luminance_range = tuple(block.get("luminance_range", (0.35, 0.85)))
+        chroma = float(block.get("chroma", 0.12))
+
+        REQUIRED_RANGE_LENGTH = 2
+        if (
+            len(hue_range) != REQUIRED_RANGE_LENGTH
+            or len(luminance_range) != REQUIRED_RANGE_LENGTH
+        ):
+            raise PaletteGenerationError(
+                "hue_range and luminance_range must have two values"
+            )
+
+        colors = generate_hcl_palette(
+            size,
+            seed=int(seed) if seed is not None else None,
+            hue_range=(float(hue_range[0]), float(hue_range[1])),
+            chroma=chroma,
+            luminance_range=(float(luminance_range[0]), float(luminance_range[1])),
+        )
+
+        metadata = {
+            "source": source.value,
+            "size": len(colors),
+            "seed": int(seed) if seed is not None else None,
+            "hue_range": [float(hue_range[0]), float(hue_range[1])],
+            "luminance_range": [float(luminance_range[0]), float(luminance_range[1])],
+            "chroma": chroma,
+        }
+
+        return PaletteResolution(colors=colors, metadata=metadata)
+
+    elif source is PaletteSource.REMOTE:
+        """Return request for shell to execute - no network I/O here."""
+        fetch_request = PaletteFetchRequest(
+            source=source.value,
+            keywords=block.get("keywords"),
+            num_results=int(block.get("num_results", 1)),
+            order_by=str(block.get("order_by", "score")),
+        )
+
+        return PaletteResolution(fetch_request=fetch_request)
+
+    else:
+        raise PaletteError(f"Unsupported palette source: {source.value}")
+
+
+__all__ = [
+    "resolve_palette_config",
+]

simple_resume/core/palettes/sources.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""Provide palette sources: bundled datasets, palettable integration, remote APIs."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from importlib import import_module
+from pathlib import Path
+from typing import Any
+
+from simple_resume.core.palettes.common import Palette
+
+logger = logging.getLogger(__name__)
+
+# NOTE: Network-related functions (_validate_url, _create_safe_request) and
+# ColourLoversClient have been moved to shell/palettes/remote.py
+
+DEFAULT_DATA_FILENAME = "default_palettes.json"
+PALETTABLE_CACHE = "palettable_registry.json"
+PALETTE_MODULE_CATEGORY_INDEX = 2
+MIN_MODULE_NAME_PARTS = 2
+
+
+@dataclass(frozen=True)
+class PalettableRecord:
+    """Define metadata describing a palette provided by `palettable`."""
+
+    name: str
+    module: str
+    attribute: str
+    category: str
+    palette_type: str
+    size: int
+
+    def to_dict(self) -> dict[str, object]:
+        """Convert a record to dictionary representation."""
+        return {
+            "name": self.name,
+            "module": self.module,
+            "attribute": self.attribute,
+            "category": self.category,
+            "palette_type": self.palette_type,
+            "size": self.size,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, object]) -> PalettableRecord:
+        """Create a record from a dictionary."""
+        return cls(
+            name=str(data["name"]),
+            module=str(data["module"]),
+            attribute=str(data["attribute"]),
+            category=str(data["category"]),
+            palette_type=str(data["palette_type"]),
+            size=int(data["size"])
+            if isinstance(data["size"], (int, float, str))
+            else 0,
+        )
+
+
+def _data_dir() -> Path:
+    """Return the data directory."""
+    return Path(__file__).resolve().parent / "data"
+
+
+def _default_file() -> Path:
+    """Return the default palette file path (no I/O)."""
+    return _data_dir() / "default_palettes.json"
+
+
+def parse_palette_data(payload: list[dict[str, Any]]) -> list[Palette]:
+    """Parse palette JSON data into Palette objects (pure function).
+
+    Args:
+        payload: List of palette dictionaries with 'name', 'colors', etc.
+
+    Returns:
+        List of Palette objects.
+
+    """
+    palettes: list[Palette] = []
+    for entry in payload:
+        palettes.append(
+            Palette(
+                name=entry["name"],
+                swatches=tuple(entry["colors"]),
+                source=entry.get("source", "default"),
+                metadata=entry.get("metadata", {}),
+            )
+        )
+    return palettes
+
+
+def load_palettable_palette(record: PalettableRecord) -> Palette | None:
+    """Resolve a `palettable` palette into our `Palette` type.
+
+    This remains in the core layer because it transforms library objects
+    into pure data structures; dynamic import is the only side effect.
+    """
+    try:
+        module = import_module(record.module)
+        palette_obj = getattr(module, record.attribute)
+        raw_colors = getattr(palette_obj, "hex_colors", None) or getattr(
+            palette_obj, "colors", []
+        )
+        colors = tuple(
+            str(color if str(color).startswith("#") else f"#{color}")
+            for color in raw_colors
+        )
+        if not colors:
+            return None
+        metadata = {
+            "category": record.category,
+            "palette_type": record.palette_type,
+            "size": record.size,
+        }
+        return Palette(
+            name=record.name,
+            swatches=colors,
+            source="palettable",
+            metadata=metadata,
+        )
+    except Exception as exc:  # noqa: BLE001
+        logger.debug(
+            "Unable to load palettable palette %s.%s: %s",
+            record.module,
+            record.attribute,
+            exc,
+        )
+        return None
+
+
+def _cache_path(filename: str) -> Path:
+    """Return the cache file path.
+
+    NOTE: Assumes cache directory already exists. Directory creation
+    should be handled by the shell layer before calling core functions.
+    """
+    return Path.home() / ".cache" / "simple_resume" / filename
+
+
+def parse_palettable_cache(payload: list[dict[str, Any]]) -> list[PalettableRecord]:
+    """Parse palettable cache JSON into records (pure function)."""
+    return [PalettableRecord.from_dict(item) for item in payload]
+
+
+def serialize_palettable_records(
+    records: Iterable[PalettableRecord],
+) -> list[dict[str, Any]]:
+    """Serialize palettable records to JSON-serializable dicts (pure function)."""
+    return [record.to_dict() for record in records]
+
+
+__all__ = [
+    "PalettableRecord",
+    "parse_palette_data",
+    "parse_palettable_cache",
+    "serialize_palettable_records",
+    "load_palettable_palette",
+]

simple_resume/core/paths.py

@@ -0,0 +1,21 @@
+"""Core filesystem path dataclasses used across the project."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Paths:
+    """Resolved filesystem locations for resume data and assets."""
+
+    data: Path
+    input: Path
+    output: Path
+    content: Path
+    templates: Path
+    static: Path
+
+
+__all__ = ["Paths"]

simple_resume/core/protocols.py

@@ -0,0 +1,134 @@
+"""Protocol definitions for shell layer dependencies.
+
+These protocols define the interfaces that shell layer implementations
+must provide to the core layer, enabling dependency injection without
+late-bound imports.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class TemplateLocator(Protocol):
+    """Protocol for locating template directories."""
+
+    def get_template_location(self) -> Path:
+        """Get the template directory path."""
+        ...
+
+
+@runtime_checkable
+class EffectExecutor(Protocol):
+    """Protocol for executing effects."""
+
+    def execute(self, effect: Any) -> Any:
+        """Execute a single effect and return its result (type varies)."""
+        ...
+
+    def execute_many(self, effects: list[Any]) -> None:
+        """Execute multiple effects."""
+        ...
+
+
+@runtime_checkable
+class ContentLoader(Protocol):
+    """Protocol for loading resume content."""
+
+    def load(
+        self,
+        name: str,
+        paths: Any,
+        transform_markdown: bool,
+    ) -> tuple[dict[str, Any], dict[str, Any]]:
+        """Load content from a YAML file."""
+        ...
+
+
+@runtime_checkable
+class PdfGenerationStrategy(Protocol):
+    """Protocol for PDF generation strategies."""
+
+    def generate(
+        self,
+        render_plan: Any,
+        output_path: Path,
+        resume_name: str,
+        filename: str | None = None,
+    ) -> tuple[Any, int | None]:
+        """Generate a PDF file."""
+        ...
+
+
+@runtime_checkable
+class HtmlGenerator(Protocol):
+    """Protocol for HTML generation."""
+
+    def generate(
+        self,
+        render_plan: Any,
+        output_path: Path,
+        filename: str | None = None,
+    ) -> Any:
+        """Generate HTML content."""
+        ...
+
+
+@runtime_checkable
+class FileOpenerService(Protocol):
+    """Protocol for opening files."""
+
+    def open_file(self, path: Path, format_type: str | None = None) -> bool:
+        """Open a file with the system default application."""
+        ...
+
+
+@runtime_checkable
+class PaletteLoader(Protocol):
+    """Protocol for loading color palettes."""
+
+    def load_palette_from_file(self, path: str | Path) -> dict[str, Any]:
+        """Load a palette from a file."""
+        ...
+
+
+@runtime_checkable
+class PathResolver(Protocol):
+    """Protocol for resolving file paths."""
+
+    def candidate_yaml_path(self, name: str) -> Path:
+        """Get candidate YAML path for a name."""
+        ...
+
+    def resolve_paths_for_read(
+        self,
+        paths: Any,
+        overrides: dict[str, Any],
+        candidate_path: Path,
+    ) -> Any:
+        """Resolve paths for reading operations."""
+        ...
+
+
+@runtime_checkable
+class LaTeXRenderer(Protocol):
+    """Protocol for LaTeX rendering."""
+
+    def get_latex_functions(self) -> tuple[Any, Any, Any]:
+        """Get LaTeX compilation functions."""
+        ...
+
+
+__all__ = [
+    "TemplateLocator",
+    "EffectExecutor",
+    "ContentLoader",
+    "PdfGenerationStrategy",
+    "HtmlGenerator",
+    "FileOpenerService",
+    "PaletteLoader",
+    "PathResolver",
+    "LaTeXRenderer",
+]

simple_resume/core/render/__init__.py

@@ -0,0 +1,37 @@
+"""Core rendering functionality for resumes.
+
+This module provides pure functions for template rendering and coordination
+between different rendering backends without any I/O side effects.
+"""
+
+from __future__ import annotations
+
+from simple_resume.core.render.manage import (
+    get_template_environment,
+    prepare_html_generation_request,
+    prepare_pdf_generation_request,
+    validate_render_plan,
+)
+from simple_resume.core.render.plan import (
+    RenderPlanConfig,
+    build_render_plan,
+    normalize_with_palette_fallback,
+    prepare_render_data,
+    transform_for_mode,
+    validate_resume_config,
+    validate_resume_config_or_raise,
+)
+
+__all__ = [
+    "get_template_environment",
+    "prepare_html_generation_request",
+    "prepare_pdf_generation_request",
+    "validate_render_plan",
+    "build_render_plan",
+    "normalize_with_palette_fallback",
+    "prepare_render_data",
+    "RenderPlanConfig",
+    "transform_for_mode",
+    "validate_resume_config",
+    "validate_resume_config_or_raise",
+]