simple-resume 0.1.9__py3-none-any.whl

simple_resume/core/validation.py

@@ -0,0 +1,321 @@
+"""Provide validation functions for resume inputs and files."""
+
+import re
+from pathlib import Path
+from typing import Any
+
+from simple_resume.core.constants import (
+    MAX_FILE_SIZE_MB,
+    SUPPORTED_FORMATS,
+    OutputFormat,
+)
+from simple_resume.core.constants.files import SUPPORTED_YAML_EXTENSIONS
+from simple_resume.core.exceptions import (
+    ConfigurationError,
+    FileSystemError,
+    ValidationError,
+)
+
+EMAIL_REGEX = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+DATE_REGEX = re.compile(r"^\d{4}(-\d{2})?$")
+
+
+def validate_format(
+    format_str: str | OutputFormat, param_name: str = "format"
+) -> OutputFormat:
+    """Validate and normalize a format string.
+
+    Args:
+        format_str: The format string or enum to validate.
+        param_name: The parameter name for error messages.
+
+    Returns:
+        An `OutputFormat` enum value.
+
+    Raises:
+        ValidationError: If the format is not supported.
+
+    """
+    if not format_str:
+        raise ValidationError(f"{param_name} cannot be empty")
+
+    normalized = (
+        format_str.value
+        if isinstance(format_str, OutputFormat)
+        else format_str.lower().strip()
+    )
+
+    if not OutputFormat.is_valid(normalized):
+        raise ValidationError(
+            f"Unsupported {param_name}: '{format_str}'. "
+            f"Supported formats: {', '.join(SUPPORTED_FORMATS)}"
+        )
+
+    return OutputFormat(normalized)
+
+
+def validate_file_path(
+    file_path: str | Path,
+    *,
+    must_exist: bool = True,
+    must_be_file: bool = True,
+    allowed_extensions: tuple[str, ...] | None = None,
+) -> Path:
+    """Validate a file path.
+
+    Args:
+        file_path: The path to validate.
+        must_exist: If `True`, the path must exist.
+        must_be_file: If `True`, the path must be a file.
+        allowed_extensions: If provided, the file must have one of these extensions.
+
+    Returns:
+        A validated `Path` object.
+
+    Raises:
+        FileSystemError: If path validation fails.
+
+    """
+    if not file_path:
+        raise FileSystemError("File path cannot be empty")
+
+    path = Path(file_path) if isinstance(file_path, str) else file_path
+
+    # Resolve to absolute path if not already absolute.
+    if not path.is_absolute():
+        path = path.resolve()
+
+    if must_exist and not path.exists():
+        raise FileSystemError(f"Path does not exist: {path}")
+
+    if must_be_file and must_exist and not path.is_file():
+        raise FileSystemError(f"Path is not a file: {path}")
+
+    if allowed_extensions and path.suffix.lower() not in allowed_extensions:
+        raise FileSystemError(
+            f"Invalid file extension '{path.suffix}'. "
+            f"Allowed: {', '.join(allowed_extensions)}"
+        )
+
+    # Check file size if file exists.
+    if must_exist and path.is_file():
+        size_mb = path.stat().st_size / (1024 * 1024)
+        if size_mb > MAX_FILE_SIZE_MB:
+            raise FileSystemError(
+                f"File too large: {size_mb:.1f}MB (max: {MAX_FILE_SIZE_MB}MB)"
+            )
+
+    return path
+
+
+def validate_directory_path(
+    dir_path: str | Path, *, must_exist: bool = False, create_if_missing: bool = False
+) -> Path:
+    """Validate a directory path.
+
+    Args:
+        dir_path: The directory path to validate.
+        must_exist: If `True`, the directory must exist.
+        create_if_missing: If `True`, create the directory if it doesn't exist.
+
+    Returns:
+        A validated `Path` object.
+
+    Raises:
+        FileSystemError: If path validation fails.
+
+    """
+    if not dir_path:
+        raise FileSystemError("Directory path cannot be empty")
+
+    path = Path(dir_path) if isinstance(dir_path, str) else dir_path
+
+    if not path.is_absolute():
+        path = path.resolve()
+
+    if must_exist and not path.exists():
+        raise FileSystemError(f"Directory does not exist: {path}")
+
+    if path.exists() and not path.is_dir():
+        raise FileSystemError(f"Path is not a directory: {path}")
+
+    if create_if_missing and not path.exists():
+        # NOTE: Directory creation has been moved to shell layer.
+        # Core validation should not perform I/O operations.
+        # Callers should create directories in the shell layer if needed.
+        raise FileSystemError(
+            f"Directory does not exist and create_if_missing is not supported "
+            f"in core validation: {path}. Create the directory in the shell layer."
+        )
+
+    return path
+
+
+def validate_template_name(template: str) -> str:
+    """Validate a template name.
+
+    Args:
+        template: The template name to validate.
+
+    Returns:
+        The validated template name.
+
+    Raises:
+        ConfigurationError: If the template name is invalid.
+
+    """
+    if not template:
+        raise ConfigurationError("Template name cannot be empty")
+
+    template = template.strip()
+
+    # Allow custom templates; ensure reasonable string format.
+    if not template.replace("_", "").replace("-", "").isalnum():
+        message = (
+            f"Invalid template name: '{template}'. "
+            "Template names should contain only alphanumeric characters, "
+            "hyphens, and underscores."
+        )
+        raise ConfigurationError(message)
+
+    return template
+
+
+def validate_yaml_file(file_path: str | Path) -> Path:
+    """Validate a YAML resume file.
+
+    Args:
+        file_path: The path to the YAML file.
+
+    Returns:
+        A validated `Path` object.
+
+    Raises:
+        FileSystemError: If file validation fails.
+
+    """
+    return validate_file_path(
+        file_path,
+        must_exist=True,
+        must_be_file=True,
+        allowed_extensions=tuple(SUPPORTED_YAML_EXTENSIONS),
+    )
+
+
+def validate_resume_data(data: dict[str, Any]) -> None:
+    """Validate the basic structure of the resume data.
+
+    Args:
+        data: A resume data dictionary.
+
+    Raises:
+        ValidationError: If the data structure is invalid.
+
+    """
+    if not isinstance(data, dict):
+        raise ValidationError("Resume data must be a dictionary")
+
+    if not data:
+        raise ValidationError("Resume data cannot be empty")
+
+    # Check required fields.
+    if "full_name" not in data:
+        raise ValidationError("Resume data must include 'full_name'")
+
+    if not data.get("full_name"):
+        raise ValidationError("'full_name' cannot be empty")
+
+    _validate_required_email(data)
+
+    # Check config if present.
+    if "config" in data:
+        if not isinstance(data["config"], dict):
+            raise ValidationError("'config' must be a dictionary")
+
+    _validate_date_fields(data)
+
+
+def validate_output_path(output_path: str | Path, format_type: str) -> Path:
+    """Validate the output file path for a generated resume.
+
+    Args:
+        output_path: The output file path.
+        format_type: The output format (e.g., "pdf", "html").
+
+    Returns:
+        A validated `Path` object.
+
+    Raises:
+        FileSystemError: If path validation fails.
+
+    """
+    path = Path(output_path) if isinstance(output_path, str) else output_path
+
+    # Validate parent directory.
+    if path.parent and path.parent != Path("."):
+        validate_directory_path(path.parent, must_exist=False, create_if_missing=False)
+
+    # Check file extension matches format.
+    expected_ext = f".{format_type.lower()}"
+    if path.suffix.lower() != expected_ext:
+        message = (
+            f"Output path extension '{path.suffix}' doesn't match format "
+            f"'{format_type}'. Expected: {expected_ext}"
+        )
+        raise FileSystemError(message)
+
+    return path
+
+
+def _validate_required_email(data: dict[str, Any]) -> None:
+    """Validate the required email field."""
+    email = data.get("email")
+    if email is None:
+        raise ValidationError("Resume data must include 'email'")
+
+    if not isinstance(email, str) or not EMAIL_REGEX.match(email.strip()):
+        raise ValidationError(
+            "Invalid email format. Expected something like user@example.com"
+        )
+
+
+def _is_date_key(key: str) -> bool:
+    """Check if a key is a date field."""
+    key_lower = key.lower()
+    return key_lower == "date" or key_lower.endswith("_date")
+
+
+def _validate_date_value(field: str, value: Any) -> None:
+    """Validate a date field's value.
+
+    Args:
+        field: The name of the field being validated.
+        value: The value of the date field.
+
+    Raises:
+        ValidationError: If the date format is invalid.
+
+    """
+    if value is None or value == "":
+        return
+    if not isinstance(value, str) or not DATE_REGEX.match(value.strip()):
+        raise ValidationError(
+            f"Invalid date format for '{field}'. Use 'YYYY' or 'YYYY-MM'."
+        )
+
+
+def _validate_date_fields(node: Any) -> None:
+    """Recursively validate date fields within a dictionary or list.
+
+    Args:
+        node: The dictionary or list node to traverse and validate.
+
+    """
+    if isinstance(node, dict):
+        for key, value in node.items():
+            if isinstance(key, str) and _is_date_key(key):
+                _validate_date_value(key, value)
+            _validate_date_fields(value)
+    elif isinstance(node, list):
+        for item in node:
+            _validate_date_fields(item)

simple_resume/shell/__init__.py

@@ -0,0 +1,3 @@
+"""Shell layer for resume generation - orchestrates I/O and external dependencies."""
+
+__all__: list[str] = []

simple_resume/shell/assets/static/css/README.md

@@ -0,0 +1,213 @@
+# CSS Architecture for Simple Resume
+
+This directory contains the external CSS files for the resume templates.
+
+## File Structure
+
+```text
+static/css/
+├── README.md      # This file
+├── fonts.css      # @font-face declarations for Avenir fonts
+├── common.css     # Shared styles for PDF and web preview
+├── print.css      # PDF-specific styles and WeasyPrint workarounds
+└── preview.css    # Web browser preview enhancements
+```
+
+## CSS Files
+
+### fonts.css
+
+Font-face declarations for the Avenir font family. Uses relative paths
+to load fonts from `../fonts/`.
+
+### common.css
+
+All shared layout and component styles. Uses CSS custom properties
+(variables) for theme customization. These variables must be injected
+via an inline `<style>` block in the template.
+
+### print.css
+
+PDF/print-specific styles including `@page` rules and WeasyPrint
+workarounds. Applied only for PDF generation.
+
+### preview.css
+
+Web browser enhancements for the preview mode. Adds shadows, smooth
+scrolling, and responsive adjustments.
+
+## CSS Custom Properties
+
+The template must inject CSS custom properties for theme values.
+Required properties:
+
+```css
+:root {
+  /* Colors */
+  --sidebar-color: #2c3e50;
+  --sidebar-text-color: #ffffff;
+  --theme-color: #3498db;
+  --date2-color: #7f8c8d;
+  --bar-background-color: #bdc3c7;
+  --frame-color: #f5f5f5;
+  --heading-icon-color: #ffffff;
+  --section-icon-color: #2c3e50;
+  --section-header-color: #2c3e50;
+
+  /* Dimensions (use mm for print compatibility) */
+  --page-width: 210mm;
+  --page-height: 297mm;
+  --sidebar-width: 60mm;
+  --body-width: 150mm;
+  --padding: 5mm;
+
+  /* Layout spacing */
+  --sidebar-padding-top: 5mm;
+  --sidebar-padding-bottom: 5mm;
+  --sidebar-padding-left: 5mm;
+  --sidebar-padding-right: 5mm;
+  --pitch-padding-top: 10mm;
+  --pitch-padding-bottom: 5mm;
+  --pitch-padding-left: 5mm;
+  --h2-padding-left-full: 25mm;
+  --h2-width: 140mm;
+  --h3-padding-top: 3mm;
+  --date-container-width: 25mm;
+  --description-container-padding-left: 5mm;
+  --skill-container-padding-top: 2mm;
+  --profile-image-padding-bottom: 5mm;
+  --profile-width: 50mm;
+  --frame-padding: 10mm;
+
+  /* Section icon styling */
+  --section-icon-circle-size: 10mm;
+  --section-icon-circle-x-offset: 0mm;
+  --section-icon-design-size: 5mm;
+  --section-icon-design-x-offset: 0;
+  --section-icon-design-y-offset: 0;
+  --section-heading-text-margin: 5mm;
+  --section-heading-marker-margin-left: -10mm;
+  --section-heading-marker-line-height: 15mm;
+}
+```
+
+## Usage in Templates
+
+### Loading CSS Files
+
+From templates in `templates/html/`:
+
+```html
+<head>
+  <!-- Load external CSS -->
+  <link rel="stylesheet" href="../static/css/fonts.css">
+  <link rel="stylesheet" href="../static/css/common.css">
+
+  <!-- Print styles (for PDF) -->
+  <link rel="stylesheet" href="../static/css/print.css">
+
+  <!-- Preview styles (browser only) -->
+  {% if preview %}
+  <link rel="stylesheet" href="../static/css/preview.css">
+  {% endif %}
+
+  <!-- Inject CSS custom properties from YAML config -->
+  <style>
+    :root {
+      --sidebar-color: {{ resume_config["sidebar_color"] }};
+      --theme-color: {{ resume_config["theme_color"] }};
+      /* ... other properties ... */
+    }
+  </style>
+</head>
+```
+
+### Path Resolution
+
+CSS files use relative paths. From `static/css/`:
+
+- Fonts: `../fonts/AvenirLTStd-Light.otf`
+- Images: `../images/...`
+
+Templates link to CSS from `templates/html/`:
+
+- CSS: `../static/css/common.css`
+
+WeasyPrint's `base_url` is set to the templates directory, so all
+relative paths resolve from there.
+
+## Migration Status
+
+### Phase 1: External CSS with Fallback (Complete)
+
+- [x] CSS files created and documented
+- [x] CSS custom properties defined
+- [x] Templates updated to use external CSS (`<link>` tags added)
+- [x] Font paths fixed in templates (`../static/fonts/`)
+- [x] All 1014 tests passing
+- [x] Font embedding verified (Avenir fonts in PDFs)
+
+### Phase 2: Visual Regression Testing (Complete)
+
+- [x] All 8 sample PDFs generated successfully
+- [x] Fonts properly embedded in all PDFs (verified with `pdffonts`):
+  - Avenir-35-Light
+  - Avenir-45
+  - Avenir-55-Medium
+  - Avenir-65-Bold
+  - Avenir-35-Light-Oblique
+- [x] Layout renders correctly across all samples
+- [x] Dark sidebar theme verified
+- [x] Multipage layouts verified
+- [x] Palette variations verified
+
+### Phase 3: Remove Inline Styles (Complete)
+
+- [x] Remove inline fallback styles from `resume_base.html`
+- [x] Remove inline fallback font styles from `cover.html`
+- [x] Final visual regression testing (all 8 PDFs generated, fonts verified)
+- [x] All 1014 tests passing
+- [x] Documentation updated
+
+**Note:** `cover.html` retains cover-specific inline styles that use `resume_config`
+variables (e.g., `cover_padding_top`). These are not duplicates of external CSS
+but template-specific styles that require Jinja variable injection.
+
+## Testing
+
+After making changes:
+
+1. Generate PDF: `uv run simple-resume generate --format pdf`
+2. Compare output visually with previous version
+3. Check fonts are embedded: `pdffonts output.pdf`
+4. Run test suite: `uv run pytest`
+
+## WeasyPrint Notes
+
+WeasyPrint has some CSS limitations:
+
+- `calc()` with CSS variables may not work in all contexts
+- Some flexbox edge cases render differently
+- Font loading requires proper path resolution via `base_url`
+
+The styles in this directory have been tested with WeasyPrint.
+
+## Theme Presets
+
+For ready-to-use theme configurations, see the **[Theme Gallery](../themes/README.md)**:
+
+| Theme | Description |
+|-------|-------------|
+| `modern.yaml` | Clean, contemporary design |
+| `classic.yaml` | Traditional professional look |
+| `bold.yaml` | High-contrast, vibrant colors |
+| `minimal.yaml` | Light and airy |
+| `executive.yaml` | Sophisticated dark with gold |
+
+Each theme provides a complete `config:` block you can copy into your resume YAML.
+
+## Related Documentation
+
+- [Theme Gallery](../themes/README.md) - Pre-built themes and customization guide
+- [Path Handling Guide](../../../../wiki/Path-Handling-Guide.md)
+- [PDF Renderer Evaluation](../../../../wiki/PDF-Renderer-Evaluation.md)