simple-resume 0.1.9__py3-none-any.whl

simple_resume/shell/generate/lazy.py

@@ -0,0 +1,284 @@
+"""Lazy-loaded generation functions for optimal import performance.
+
+This module provides thin wrappers around the core generation functions
+with lazy loading to reduce startup memory footprint.
+
+.. versionadded:: 0.1.0
+"""
+
+from __future__ import annotations
+
+import importlib
+from functools import lru_cache
+from pathlib import Path
+from types import ModuleType
+from typing import TYPE_CHECKING, Any, cast
+
+from simple_resume.core.models import GenerationConfig
+
+if TYPE_CHECKING:
+    from simple_resume.core.result import BatchGenerationResult, GenerationResult
+    from simple_resume.shell.generate.core import GenerateOptions
+
+
+class _LazyCoreLoader:
+    """Lazy loader for core generation functions."""
+
+    def __init__(self) -> None:
+        self._core: ModuleType | None = None
+        self._loaded = False
+
+    def _load_core(self) -> ModuleType:
+        """Load core module if not already loaded."""
+        if not self._loaded:
+            self._core = importlib.import_module(".core", package=__package__)
+            self._loaded = True
+        if self._core is None:  # pragma: no cover
+            raise RuntimeError("Failed to load core module")
+        return self._core
+
+    @property
+    def generate_pdf(self) -> Any:
+        """Get generate_pdf function from core module."""
+        return self._load_core().generate_pdf
+
+    @property
+    def generate_html(self) -> Any:
+        """Get generate_html function from core module."""
+        return self._load_core().generate_html
+
+    @property
+    def generate_all(self) -> Any:
+        """Get generate_all function from core module."""
+        return self._load_core().generate_all
+
+    @property
+    def generate_resume(self) -> Any:
+        """Get generate_resume function from core module."""
+        return self._load_core().generate_resume
+
+    @property
+    def generate(self) -> Any:
+        """Get generate function from core module."""
+        return self._load_core().generate
+
+    @property
+    def preview(self) -> Any:
+        """Get preview function from core module."""
+        return self._load_core().preview
+
+
+@lru_cache(maxsize=1)
+def _get_lazy_core_loader() -> _LazyCoreLoader:
+    """Provide a lazily created singleton loader without module globals."""
+    return _LazyCoreLoader()
+
+
+def generate_pdf(
+    config: GenerationConfig,
+    **config_overrides: Any,
+) -> BatchGenerationResult:
+    """Generate PDF resumes using a configuration object.
+
+    Args:
+        config: Generation configuration specifying sources, formats, and options.
+        **config_overrides: Additional configuration overrides.
+
+    Returns:
+        BatchGenerationResult containing generated PDF files and metadata.
+
+    Example:
+        >>> from simple_resume import generate_pdf
+        >>> from simple_resume.core.models import GenerationConfig
+        >>> config = GenerationConfig(sources=["resume.yaml"], formats=["pdf"])
+        >>> result = generate_pdf(config)
+        >>> print(result.successful)
+
+    .. versionadded:: 0.1.0
+
+    """
+    lazy_core = _get_lazy_core_loader()
+    result: BatchGenerationResult = cast(
+        "BatchGenerationResult", lazy_core.generate_pdf(config, **config_overrides)
+    )
+    return result
+
+
+def generate_html(
+    config: GenerationConfig,
+    **config_overrides: Any,
+) -> BatchGenerationResult:
+    """Generate HTML resumes using a configuration object.
+
+    Args:
+        config: Generation configuration specifying sources, formats, and options.
+        **config_overrides: Additional configuration overrides.
+
+    Returns:
+        BatchGenerationResult containing generated HTML files and metadata.
+
+    Example:
+        >>> from simple_resume import generate_html
+        >>> from simple_resume.core.models import GenerationConfig
+        >>> config = GenerationConfig(sources=["resume.yaml"], formats=["html"])
+        >>> result = generate_html(config)
+
+    .. versionadded:: 0.1.0
+
+    """
+    lazy_core = _get_lazy_core_loader()
+    result: BatchGenerationResult = cast(
+        "BatchGenerationResult", lazy_core.generate_html(config, **config_overrides)
+    )
+    return result
+
+
+def generate_all(
+    config: GenerationConfig,
+    **config_overrides: Any,
+) -> BatchGenerationResult:
+    """Generate resumes in all specified formats.
+
+    Args:
+        config: Generation configuration specifying sources, formats, and options.
+        **config_overrides: Additional configuration overrides.
+
+    Returns:
+        BatchGenerationResult containing all generated files and metadata.
+
+    Example:
+        >>> from simple_resume import generate_all
+        >>> from simple_resume.core.models import GenerationConfig
+        >>> config = GenerationConfig(sources=["resume.yaml"], formats=["pdf", "html"])
+        >>> result = generate_all(config)
+
+    .. versionadded:: 0.1.0
+
+    """
+    lazy_core = _get_lazy_core_loader()
+    result: BatchGenerationResult = cast(
+        "BatchGenerationResult", lazy_core.generate_all(config, **config_overrides)
+    )
+    return result
+
+
+def generate_resume(
+    config: GenerationConfig,
+    **config_overrides: Any,
+) -> GenerationResult:
+    """Generate a single resume in a specific format.
+
+    Args:
+        config: Generation configuration specifying source and format.
+        **config_overrides: Additional configuration overrides.
+
+    Returns:
+        GenerationResult for the generated resume.
+
+    Example:
+        >>> from simple_resume import generate_resume
+        >>> from simple_resume.core.models import GenerationConfig
+        >>> config = GenerationConfig(sources=["resume.yaml"], formats=["pdf"])
+        >>> result = generate_resume(config)
+
+    .. versionadded:: 0.1.0
+
+    """
+    lazy_core = _get_lazy_core_loader()
+    result: GenerationResult = cast(
+        "GenerationResult", lazy_core.generate_resume(config, **config_overrides)
+    )
+    return result
+
+
+def generate(
+    source: str | Path,
+    options: GenerateOptions | None = None,
+    **overrides: Any,
+) -> dict[str, GenerationResult | BatchGenerationResult]:
+    """Render one or more formats for the same source.
+
+    This is the primary entry point for generating resumes. It accepts a
+    source file path and optional configuration.
+
+    Args:
+        source: Path to the resume YAML file.
+        options: Optional GenerateOptions with formats and settings.
+        **overrides: Additional configuration overrides.
+
+    Returns:
+        Dictionary mapping format names to GenerationResult or BatchGenerationResult.
+
+    Example:
+        >>> from simple_resume import generate
+        >>> result = generate("resume.yaml")
+        >>> for fmt, r in result.items():
+        ...     print(f"Generated {fmt}: {r}")
+
+    .. versionadded:: 0.1.0
+
+    """
+    lazy_core = _get_lazy_core_loader()
+    result: dict[str, GenerationResult | BatchGenerationResult] = cast(
+        "dict[str, GenerationResult | BatchGenerationResult]",
+        lazy_core.generate(source, options, **overrides),
+    )
+    return result
+
+
+def preview(
+    source: str | Path,
+    *,
+    data_dir: str | Path | None = None,
+    template: str | None = None,
+    browser: str | None = None,
+    open_after: bool = True,
+    **overrides: Any,
+) -> GenerationResult | BatchGenerationResult:
+    """Render a single resume to HTML and open in browser.
+
+    This convenience function generates an HTML preview and optionally
+    opens it in the default web browser.
+
+    Args:
+        source: Path to the resume YAML file.
+        data_dir: Optional data directory override.
+        template: Optional template name override.
+        browser: Optional browser command (e.g., "firefox", "chrome").
+        open_after: Whether to open the file after generation (default: True).
+        **overrides: Additional configuration overrides.
+
+    Returns:
+        GenerationResult for the generated HTML preview.
+
+    Example:
+        >>> from simple_resume import preview
+        >>> result = preview("resume.yaml")  # Opens in browser
+        >>> result = preview("resume.yaml", open_after=False)  # Just generate
+
+    .. versionadded:: 0.1.0
+
+    """
+    lazy_core = _get_lazy_core_loader()
+    result: GenerationResult | BatchGenerationResult = cast(
+        "GenerationResult | BatchGenerationResult",
+        lazy_core.preview(
+            source,
+            data_dir=data_dir,
+            template=template,
+            browser=browser,
+            open_after=open_after,
+            **overrides,
+        ),
+    )
+    return result
+
+
+__all__ = [
+    "generate_pdf",
+    "generate_html",
+    "generate_all",
+    "generate_resume",
+    "generate",
+    "preview",
+]

simple_resume/shell/io_utils.py

@@ -0,0 +1,199 @@
+"""Consolidated path and file handling utilities.
+
+This module provides centralized path handling following the Path-first principle:
+- Accept str | Path at API boundaries for flexibility
+- Normalize to Path immediately after receiving input
+- Use Path objects internally throughout the codebase
+- Convert to str only when required by external APIs
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from oyaml import safe_load
+
+from simple_resume.core.paths import Paths
+from simple_resume.shell.config import FILE_DEFAULT, resolve_paths
+
+
+def candidate_yaml_path(name: str | os.PathLike[str]) -> Path | None:
+    """Return a Path if ``name`` resembles a supported resume file, else ``None``.
+
+    Notes:
+        We treat ``.json`` specially: a bare "resume.json" is often meant as a resume
+        *name* (looked up under the data-dir input folder). To avoid surprising
+        "file not found" errors, we only treat ``.json`` as a direct path when it
+        looks like a real path (has directory components or is absolute).
+
+    """
+    if isinstance(name, (str, os.PathLike)):
+        maybe_path = Path(name)
+        suffix = maybe_path.suffix.lower()
+        if suffix in {".yaml", ".yml"}:
+            return maybe_path
+        if suffix == ".json":
+            if maybe_path.is_absolute() or len(maybe_path.parts) > 1:
+                return maybe_path
+    return None
+
+
+def resolve_paths_for_read(
+    supplied_paths: Paths | None,
+    overrides: dict[str, Any],
+    candidate: Path | None,
+) -> Paths:
+    """Resolve path configuration for read operations."""
+    if supplied_paths is not None:
+        return supplied_paths
+
+    if overrides:
+        return resolve_paths(**overrides)
+
+    if candidate is not None:
+        if candidate.parent.name == "input":
+            base_dir = candidate.parent.parent
+        else:
+            base_dir = candidate.parent
+
+        base_paths = resolve_paths(data_dir=base_dir)
+        return Paths(
+            data=base_paths.data,
+            input=candidate.parent,
+            output=base_paths.output,
+            content=base_paths.content,
+            templates=base_paths.templates,
+            static=base_paths.static,
+        )
+
+    return resolve_paths(**overrides)
+
+
+def normalize_resume_name(name: str | os.PathLike[str]) -> str:
+    """Normalize resume identifiers by stripping extensions and defaults.
+
+    Args:
+        name: Resume identifier (filename, stem, or path)
+
+    Returns:
+        Normalized resume name without extension
+
+    """
+    if not name:
+        return FILE_DEFAULT
+    if isinstance(name, (str, os.PathLike)):
+        candidate = Path(name)
+        suffix = candidate.suffix.lower()
+        if suffix in {".yaml", ".yml", ".json"}:
+            return candidate.stem
+        return candidate.name or str(name)
+    return str(name)
+
+
+def find_resume_file(
+    resume_name: str, input_path: Path, *, include_uppercase: bool = True
+) -> Path:
+    """Find a resume file in the input directory by name.
+
+    Args:
+        resume_name: Name of the resume (without extension)
+        input_path: Directory to search for resume files
+        include_uppercase: Whether to search for uppercase extensions
+
+    Returns:
+        Path to the found resume file
+
+    """
+    candidates: list[Path] = []
+    extensions = ["yaml", "yml", "json"]
+
+    # Search for files with both lowercase and uppercase extensions
+    for ext in extensions:
+        candidates.extend(input_path.glob(f"{resume_name}.{ext}"))
+        if include_uppercase:
+            candidates.extend(input_path.glob(f"{resume_name}.{ext.upper()}"))
+
+    if candidates:
+        return candidates[0]
+
+    # Fallback to default yaml file
+    return input_path / f"{resume_name}.yaml"
+
+
+def read_yaml_file(path: str | Path) -> dict[str, Any]:
+    """Read and parse a YAML file.
+
+    Args:
+        path: Path to the YAML file
+
+    Returns:
+        Parsed YAML content as dictionary
+
+    Raises:
+        ValueError: If YAML content is not a dictionary
+        FileNotFoundError: If file doesn't exist
+
+    """
+    path_obj = Path(path)
+    if not path_obj.exists():
+        raise FileNotFoundError(f"YAML file not found: {path}")
+
+    with open(path_obj, encoding="utf-8") as file:
+        content = safe_load(file)
+
+    if content is None:
+        return {}
+
+    if not isinstance(content, dict):
+        raise ValueError(
+            f"YAML file must contain a dictionary at the root level, "
+            f"but found {type(content).__name__}: {path_obj}"
+        )
+
+    return content
+
+
+def ensure_directory_exists(path: Path) -> Path:
+    """Ensure a directory exists, creating it if necessary.
+
+    Args:
+        path: Directory path to ensure exists
+
+    Returns:
+        The same path for convenience
+
+    """
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def resolve_output_path(base_dir: Path, filename: str, extension: str = ".pdf") -> Path:
+    """Resolve an output file path with proper extension.
+
+    Args:
+        base_dir: Base output directory
+        filename: Base filename (without extension)
+        extension: Desired file extension
+
+    Returns:
+        Resolved output file path
+
+    """
+    if not filename.endswith(extension):
+        filename = f"{filename}{extension}"
+
+    ensure_directory_exists(base_dir)
+    return base_dir / filename
+
+
+__all__ = [
+    "candidate_yaml_path",
+    "resolve_paths_for_read",
+    "normalize_resume_name",
+    "find_resume_file",
+    "read_yaml_file",
+    "ensure_directory_exists",
+    "resolve_output_path",
+]

simple_resume/shell/palettes/__init__.py

@@ -0,0 +1 @@
+"""Palette-related functionality for the shell layer."""

simple_resume/shell/palettes/fetch.py

@@ -0,0 +1,63 @@
+"""Shell layer palette fetching with network I/O.
+
+This module executes the network operations described by PaletteFetchRequest
+objects created by the pure core logic. This isolates all network I/O
+to the shell layer.
+"""
+
+from typing import Any
+
+from simple_resume.core.palettes import PaletteFetchRequest
+from simple_resume.core.palettes.exceptions import PaletteLookupError
+from simple_resume.shell.palettes.remote import ColourLoversClient
+
+
+def execute_palette_fetch(
+    request: PaletteFetchRequest,
+) -> tuple[list[str], dict[str, Any]]:
+    """Shell operation - performs network I/O to fetch palette.
+
+    This function executes the network operation described by the request
+    and returns the actual color data.
+
+    Args:
+        request: Palette fetch request describing the network operation
+
+    Returns:
+        Tuple of (colors, metadata) from the remote source
+
+    Raises:
+        PaletteLookupError: If palette fetch fails or returns no results
+
+    """
+    if request.source not in {"colourlovers", "remote"}:
+        raise PaletteLookupError(f"Unsupported remote source: {request.source}")
+
+    client = ColourLoversClient()
+    # Convert list of keywords to comma-separated string for the API
+    keywords_str = ",".join(request.keywords) if request.keywords else None
+    palettes = client.fetch(
+        keywords=keywords_str,
+        num_results=request.num_results,
+        order_by=request.order_by,
+    )
+
+    if not palettes:
+        raise PaletteLookupError(f"No palettes found for keywords: {request.keywords}")
+
+    palette = palettes[0]
+    colors = list(palette.swatches)
+
+    metadata = {
+        "source": request.source,
+        "name": palette.name,
+        "attribution": palette.metadata,
+        "size": len(colors),
+    }
+
+    return colors, metadata
+
+
+__all__ = [
+    "execute_palette_fetch",
+]