simple-resume 0.1.9__py3-none-any.whl

simple_resume/shell/runtime/lazy.py

@@ -0,0 +1,138 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+import importlib
+from functools import lru_cache
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+from simple_resume.core.models import GenerationConfig
+
+
+class _LazyRuntimeLoader:
+    """Lazy loader for runtime generation functions."""
+
+    def __init__(self) -> None:
+        self._core: ModuleType | None = None
+        self._loaded = False
+
+    def _load_core(self) -> ModuleType:
+        """Load runtime module if not already loaded."""
+        if not self._loaded:
+            self._core = importlib.import_module(".generate", package=__package__)
+            self._loaded = True
+        # _core is set when _loaded is True
+        return self._core  # type: ignore[return-value]
+
+    @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() -> _LazyRuntimeLoader:
+    """Return a shared lazy loader instance without module-level globals."""
+    return _LazyRuntimeLoader()
+
+
+def generate_pdf(
+    config: GenerationConfig,
+    **config_overrides: Any,
+) -> Any:
+    """Generate PDF resumes using a configuration object (lazy-loaded wrapper)."""
+    return _get_lazy_core().generate_pdf(config, **config_overrides)
+
+
+def generate_html(
+    config: GenerationConfig,
+    **config_overrides: Any,
+) -> Any:
+    """Generate HTML resumes using a configuration object (lazy-loaded wrapper)."""
+    return _get_lazy_core().generate_html(config, **config_overrides)
+
+
+def generate_all(
+    config: GenerationConfig,
+    **config_overrides: Any,
+) -> Any:
+    """Generate resumes in all specified formats (lazy-loaded wrapper)."""
+    return _get_lazy_core().generate_all(config, **config_overrides)
+
+
+def generate_resume(
+    config: GenerationConfig,
+    **config_overrides: Any,
+) -> Any:
+    """Generate a resume in a specific format (lazy-loaded wrapper)."""
+    return _get_lazy_core().generate_resume(config, **config_overrides)
+
+
+def generate(
+    source: str | Path,
+    options: Any | None = None,
+    **overrides: Any,
+) -> Any:
+    """Render one or more formats for the same source (lazy-loaded wrapper)."""
+    return _get_lazy_core().generate(source, options, **overrides)
+
+
+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,
+) -> Any:
+    """Render a single resume to HTML with preview defaults (lazy-loaded wrapper)."""
+    return _get_lazy_core().preview(
+        source,
+        data_dir=data_dir,
+        template=template,
+        browser=browser,
+        open_after=open_after,
+        **overrides,
+    )
+
+
+__all__ = [
+    "generate_pdf",
+    "generate_html",
+    "generate_all",
+    "generate_resume",
+    "generate",
+    "preview",
+]

simple_resume/shell/runtime/lazy_import.py

@@ -0,0 +1,173 @@
+"""Lazy loading utilities for optimizing import performance.
+
+This module provides utilities to defer heavy imports until actually needed,
+reducing initial memory footprint and improving startup performance.
+"""
+
+from __future__ import annotations
+
+import importlib
+from functools import lru_cache
+from typing import Any, Callable, TypeVar, cast
+
+T = TypeVar("T")
+
+
+class LazyModule:
+    """A module that loads on first attribute access."""
+
+    def __init__(self, module_name: str) -> None:
+        """Initialize lazy module.
+
+        Args:
+            module_name: Full module path to import when needed
+
+        """
+        self._module_name = module_name
+        self._module: Any = None
+        self._loaded = False
+
+    def _load(self) -> Any:
+        """Load the module if not already loaded."""
+        if not self._loaded:
+            self._module = importlib.import_module(self._module_name)
+            self._loaded = True
+        return self._module
+
+    def __getattr__(self, name: str) -> Any:
+        """Get attribute from the lazily loaded module."""
+        module = self._load()
+        return getattr(module, name)
+
+    def __dir__(self) -> list[str]:
+        """Return directory listing of the module when loaded."""
+        module = self._load()
+        return dir(module)
+
+
+class LazyFunction:
+    """A function that loads its implementation on first call."""
+
+    def __init__(self, module_path: str, function_name: str) -> None:
+        """Initialize lazy function.
+
+        Args:
+            module_path: Full module path containing the function
+            function_name: Name of the function to lazy-load
+
+        """
+        self._module_path = module_path
+        self._function_name = function_name
+        self._function: Callable[..., Any] | None = None
+        self._loaded = False
+
+    def _load(self) -> Callable[..., Any]:
+        """Load the function if not already loaded."""
+        if not self._loaded:
+            module = importlib.import_module(self._module_path)
+            self._function = getattr(module, self._function_name)
+            self._loaded = True
+        # After loading, _function is guaranteed to be set
+        return cast(Callable[..., Any], self._function)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Call the lazily loaded function."""
+        function = self._load()
+        return function(*args, **kwargs)
+
+
+@lru_cache(maxsize=128)
+def lazy_import(module_path: str) -> LazyModule:
+    """Create a cached lazy module instance.
+
+    Args:
+        module_path: Full module path to import lazily
+
+    Returns:
+        LazyModule instance that loads on first access
+
+    """
+    return LazyModule(module_path)
+
+
+@lru_cache(maxsize=64)
+def lazy_function(module_path: str, function_name: str) -> LazyFunction:
+    """Create a cached lazy function instance.
+
+    Args:
+        module_path: Full module path containing the function
+        function_name: Name of the function to lazy-load
+
+    Returns:
+        LazyFunction instance that loads on first call
+
+    """
+    return LazyFunction(module_path, function_name)
+
+
+# Common lazy-loaded modules
+_lazy_session = lazy_import("simple_resume.shell.session")
+_lazy_result = lazy_import("simple_resume.core.result")
+_lazy_validation = lazy_import("simple_resume.core.validation")
+
+
+# Public lazy API functions
+def lazy_create_session(*args: Any, **kwargs: Any) -> Any:
+    """Lazily loaded create_session function."""
+    return _lazy_session.create_session(*args, **kwargs)
+
+
+def lazy_ResumeSession(*args: Any, **kwargs: Any) -> Any:
+    """Lazily loaded ResumeSession class."""
+    return _lazy_session.ResumeSession(*args, **kwargs)
+
+
+def lazy_SessionConfig(*args: Any, **kwargs: Any) -> Any:
+    """Lazily loaded SessionConfig class."""
+    return _lazy_session.SessionConfig(*args, **kwargs)
+
+
+def lazy_GenerationResult(*args: Any, **kwargs: Any) -> Any:
+    """Lazily loaded GenerationResult class."""
+    return _lazy_result.GenerationResult(*args, **kwargs)
+
+
+def lazy_BatchGenerationResult(*args: Any, **kwargs: Any) -> Any:
+    """Lazily loaded BatchGenerationResult class."""
+    return _lazy_result.BatchGenerationResult(*args, **kwargs)
+
+
+def lazy_GenerationMetadata(*args: Any, **kwargs: Any) -> Any:
+    """Lazily loaded GenerationMetadata class."""
+    return _lazy_result.GenerationMetadata(*args, **kwargs)
+
+
+def lazy_validate_directory_path(*args: Any, **kwargs: Any) -> Any:
+    """Lazily loaded validate_directory_path function."""
+    return _lazy_validation.validate_directory_path(*args, **kwargs)
+
+
+def lazy_validate_format(*args: Any, **kwargs: Any) -> Any:
+    """Lazily loaded validate_format function."""
+    return _lazy_validation.validate_format(*args, **kwargs)
+
+
+def lazy_validate_template_name(*args: Any, **kwargs: Any) -> Any:
+    """Lazily loaded validate_template_name function."""
+    return _lazy_validation.validate_template_name(*args, **kwargs)
+
+
+__all__ = [
+    "LazyModule",
+    "LazyFunction",
+    "lazy_import",
+    "lazy_function",
+    "lazy_create_session",
+    "lazy_ResumeSession",
+    "lazy_SessionConfig",
+    "lazy_GenerationResult",
+    "lazy_BatchGenerationResult",
+    "lazy_validate_directory_path",
+    "lazy_validate_format",
+    "lazy_validate_template_name",
+]

simple_resume/shell/service_locator.py

@@ -0,0 +1,80 @@
+"""Service locator pattern for dependency injection.
+
+This module provides a clean way to inject shell-layer dependencies
+into core functions without using late-bound imports.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Any, Callable, TypeVar
+
+T = TypeVar("T")
+
+
+class ServiceLocator:
+    """Simple service locator for dependency injection."""
+
+    def __init__(self) -> None:
+        """Initialize the service locator."""
+        self._services: dict[str, Any] = {}
+        self._factories: dict[str, Callable[[], Any]] = {}
+
+    def register(self, name: str, service: Any) -> None:
+        """Register a service instance."""
+        self._services[name] = service
+
+    def register_factory(self, name: str, factory: Callable[[], Any]) -> None:
+        """Register a factory function for lazy service creation."""
+        self._factories[name] = factory
+
+    def get(self, name: str, service_type: type[T]) -> T:
+        """Get a service by name, ensuring it matches the expected type."""
+        if name in self._services:
+            service = self._services[name]
+            if not isinstance(service, service_type):
+                raise TypeError(f"Service {name} is not of type {service_type}")
+            return service
+
+        if name in self._factories:
+            service = self._factories[name]()
+            if not isinstance(service, service_type):
+                raise TypeError(f"Service {name} is not of type {service_type}")
+            self._services[name] = service  # Cache the instance
+            return service
+
+        raise ValueError(f"Service {name} not registered")
+
+    def has(self, name: str) -> bool:
+        """Check if a service is registered."""
+        return name in self._services or name in self._factories
+
+
+@lru_cache(maxsize=1)
+def get_service_locator() -> ServiceLocator:
+    """Get the global service locator instance without module globals."""
+    return ServiceLocator()
+
+
+def register_service(name: str, service: Any) -> None:
+    """Register a service with the global locator."""
+    get_service_locator().register(name, service)
+
+
+def register_service_factory(name: str, factory: Callable[[], Any]) -> None:
+    """Register a service factory with the global locator."""
+    get_service_locator().register_factory(name, factory)
+
+
+def get_service(name: str, service_type: type[T]) -> T:
+    """Get a service from the global locator."""
+    return get_service_locator().get(name, service_type)
+
+
+__all__ = [
+    "ServiceLocator",
+    "get_service_locator",
+    "register_service",
+    "register_service_factory",
+    "get_service",
+]

simple_resume/shell/services.py

@@ -0,0 +1,256 @@
+"""Shell layer implementations of core protocols.
+
+This module provides concrete implementations of the protocols defined
+in the core layer, enabling dependency injection without late-bound imports.
+"""
+
+from __future__ import annotations
+
+import copy
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    pass
+
+from simple_resume.core.generate.html import create_html_generator_factory
+from simple_resume.core.generate.pdf import PdfGeneratorFactory
+from simple_resume.core.markdown import render_markdown_content
+from simple_resume.core.protocols import (
+    ContentLoader,
+    EffectExecutor,
+    FileOpenerService,
+    HtmlGenerator,
+    LaTeXRenderer,
+    PaletteLoader,
+    PathResolver,
+    PdfGenerationStrategy,
+    TemplateLocator,
+)
+from simple_resume.core.resume import set_default_loaders
+from simple_resume.shell.config import TEMPLATE_LOC
+from simple_resume.shell.effect_executor import EffectExecutor as ShellEffectExecutor
+from simple_resume.shell.file_opener import open_file as shell_open_file
+from simple_resume.shell.io_utils import candidate_yaml_path, resolve_paths_for_read
+from simple_resume.shell.palettes.loader import get_palette_registry
+from simple_resume.shell.render.latex import (
+    LatexCompilationError,
+    compile_tex_to_pdf,
+    render_resume_latex_from_data,
+)
+from simple_resume.shell.render.operations import (
+    generate_html_with_jinja as shell_generate,
+)
+from simple_resume.shell.runtime.content import get_content, load_palette_from_file
+from simple_resume.shell.service_locator import register_service
+from simple_resume.shell.strategies import (
+    LatexStrategy,
+    PdfGenerationRequest,
+    WeasyPrintStrategy,
+)
+
+
+class DefaultTemplateLocator(TemplateLocator):
+    """Default template locator implementation."""
+
+    def get_template_location(self) -> Path:
+        """Get the template directory path."""
+        return TEMPLATE_LOC
+
+
+class DefaultEffectExecutor(EffectExecutor):
+    """Default effect executor implementation."""
+
+    def __init__(self) -> None:
+        """Initialize the default effect executor."""
+        self._executor = ShellEffectExecutor()
+
+    def execute(self, effect: Any) -> None:
+        """Execute a single effect."""
+        self._executor.execute(effect)
+
+    def execute_many(self, effects: list[Any]) -> None:
+        """Execute multiple effects."""
+        self._executor.execute_many(effects)
+
+
+class DefaultPathResolver(PathResolver):
+    """Default path resolver implementation."""
+
+    def candidate_yaml_path(self, name: str) -> Path:
+        """Get candidate YAML path for a name."""
+        result = candidate_yaml_path(name)
+        if result is None:
+            # Fallback to creating a Path from name
+            return Path(name)
+        return result
+
+    def resolve_paths_for_read(
+        self,
+        paths: Any,
+        overrides: dict[str, Any],
+        candidate_path: Path,
+    ) -> Any:
+        """Resolve paths for reading operations."""
+        return resolve_paths_for_read(paths, overrides, candidate_path)
+
+
+class DefaultContentLoader(ContentLoader):
+    """Default content loader implementation."""
+
+    def __init__(self) -> None:
+        """Initialize the default content loader."""
+        self._path_resolver = DefaultPathResolver()
+
+    def load(
+        self,
+        name: str,
+        paths: Any,
+        transform_markdown: bool,
+    ) -> tuple[dict[str, Any], dict[str, Any]]:
+        """Load content from a YAML file."""
+        candidate_path = self._path_resolver.candidate_yaml_path(name)
+        resolved_paths = self._path_resolver.resolve_paths_for_read(
+            paths, {}, candidate_path
+        )
+        raw_data = get_content(name, paths=resolved_paths, transform_markdown=False)
+
+        if transform_markdown:
+            processed_data = render_markdown_content(raw_data)
+        else:
+            processed_data = copy.deepcopy(raw_data)
+        return processed_data, raw_data
+
+
+class DefaultPdfGenerationStrategy(PdfGenerationStrategy):
+    """Default PDF generation strategy implementation."""
+
+    def __init__(self, mode: str = "weasyprint") -> None:
+        """Initialize the PDF generation strategy.
+
+        Args:
+            mode: PDF generation mode ('latex' or 'weasyprint')
+
+        """
+        if mode == "latex":
+            self._strategy: LatexStrategy | WeasyPrintStrategy = LatexStrategy()
+        else:
+            self._strategy = WeasyPrintStrategy()
+
+    def generate(
+        self,
+        render_plan: Any,
+        output_path: Path,
+        resume_name: str,
+        filename: str | None = None,
+    ) -> tuple[Any, int | None]:
+        """Generate a PDF file."""
+        if not isinstance(render_plan, PdfGenerationRequest):
+            raise TypeError(
+                "render_plan must be a PdfGenerationRequest; "
+                "legacy inputs are not supported"
+            )
+        request = render_plan
+        result = self._strategy.generate_pdf(request)
+        return result, None if hasattr(result, "page_count") else None
+
+
+class DefaultHtmlGenerator(HtmlGenerator):
+    """Default HTML generator implementation."""
+
+    def generate(
+        self,
+        render_plan: Any,
+        output_path: Path,
+        filename: str | None = None,
+    ) -> Any:
+        """Generate HTML content."""
+        # Use shell's render operations directly since this service is in shell layer
+        return shell_generate(render_plan, output_path, filename)
+
+
+class DefaultFileOpenerService(FileOpenerService):
+    """Default file opener service implementation."""
+
+    def open_file(self, path: Path, format_type: str | None = None) -> bool:
+        """Open a file with the system default application."""
+        return shell_open_file(path, format_type)
+
+
+class DefaultPaletteLoader(PaletteLoader):
+    """Default palette loader implementation."""
+
+    def load_palette_from_file(self, path: str | Path) -> dict[str, Any]:
+        """Load a palette from a file."""
+        return load_palette_from_file(path)
+
+
+class DefaultLaTeXRenderer(LaTeXRenderer):
+    """Default LaTeX renderer implementation."""
+
+    def get_latex_functions(self) -> tuple[Any, Any, Any]:
+        """Get LaTeX compilation functions."""
+        try:
+            return (
+                LatexCompilationError,
+                compile_tex_to_pdf,
+                render_resume_latex_from_data,
+            )
+        except ImportError:
+            return None, None, None
+
+
+def register_default_services() -> None:
+    """Register all default services with the service locator."""
+    # Create default implementations
+    content_loader = DefaultContentLoader()
+    path_resolver = DefaultPathResolver()
+    palette_loader = DefaultPaletteLoader()
+    template_locator = DefaultTemplateLocator()
+    effect_executor = DefaultEffectExecutor()
+    latex_renderer = DefaultLaTeXRenderer()
+
+    # Set default dependencies for core HTML generation
+    html_factory = create_html_generator_factory(template_locator)
+
+    # Set default dependencies for core PDF generation
+    pdf_factory = PdfGeneratorFactory(
+        effect_executor=effect_executor,
+        template_locator=template_locator,
+        latex_renderer=latex_renderer,
+    )
+
+    # Register with service locator (for legacy compatibility)
+    register_service("html_generator_factory", html_factory)
+    register_service("pdf_generator_factory", pdf_factory)
+    register_service("file_opener", DefaultFileOpenerService())
+    register_service("palette_loader", palette_loader)
+    register_service("latex_renderer", latex_renderer)
+    register_service("html_generator", DefaultHtmlGenerator())
+    register_service("pdf_generation_strategy", DefaultPdfGenerationStrategy())
+
+    # Set default loaders for core Resume class
+    set_default_loaders(
+        content_loader=content_loader,
+        palette_loader=palette_loader,
+        path_resolver=path_resolver,
+        palette_registry_provider=get_palette_registry,
+    )
+
+    # Warm the palette registry once at startup to avoid expensive discovery
+    # during latency-sensitive operations (e.g., concurrent renders in tests).
+    get_palette_registry()
+
+
+__all__ = [
+    "DefaultTemplateLocator",
+    "DefaultEffectExecutor",
+    "DefaultPathResolver",
+    "DefaultContentLoader",
+    "DefaultPdfGenerationStrategy",
+    "DefaultHtmlGenerator",
+    "DefaultFileOpenerService",
+    "DefaultPaletteLoader",
+    "DefaultLaTeXRenderer",
+    "register_default_services",
+]

simple_resume/shell/session/__init__.py

@@ -0,0 +1,6 @@
+"""Session management for simple-resume operations."""
+
+from simple_resume.shell.session.config import SessionConfig
+from simple_resume.shell.session.manage import ResumeSession, create_session
+
+__all__ = ["SessionConfig", "ResumeSession", "create_session"]

simple_resume/shell/session/config.py

@@ -0,0 +1,35 @@
+"""Session configuration for simple-resume operations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from simple_resume.core.constants import OutputFormat
+from simple_resume.core.exceptions import ConfigurationError
+from simple_resume.core.paths import Paths
+
+
+@dataclass
+class SessionConfig:
+    """Configuration for a `ResumeSession`."""
+
+    paths: Paths | None = None
+    default_template: str | None = None
+    default_palette: str | None = None
+    default_format: OutputFormat | str = OutputFormat.PDF
+    auto_open: bool = False
+    preview_mode: bool = False
+    output_dir: Path | None = None
+    # Additional session-wide settings
+    session_metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        """Normalize enum-backed fields."""
+        try:
+            self.default_format = OutputFormat.normalize(self.default_format)
+        except (ValueError, TypeError) as exc:
+            raise ConfigurationError(
+                f"Invalid default format: {self.default_format}"
+            ) from exc