simple-resume 0.1.9__py3-none-any.whl

simple_resume/core/latex/conversion.py

@@ -0,0 +1,227 @@
+"""Markdown to LaTeX conversion functions (pure, deterministic)."""
+
+from __future__ import annotations
+
+import itertools
+import re
+from typing import Any, Literal
+
+from simple_resume.core.latex.escaping import escape_latex, escape_url
+from simple_resume.core.latex.types import Block
+
+
+class _InlineConverter:
+    """Convert limited Markdown inline formatting to LaTeX.
+
+    This class is pure and deterministic - it uses internal state only for
+    placeholder generation during conversion, which is deterministic based
+    on the order of replacements.
+    """
+
+    def __init__(self) -> None:
+        self._placeholders: dict[str, str] = {}
+        self._counter = itertools.count()
+
+    def convert(self, text: str) -> str:
+        """Return a string that is safe for LaTeX.
+
+        Args:
+            text: Markdown-formatted text.
+
+        Returns:
+            LaTeX-formatted text with escaping applied.
+
+        """
+        working = text
+        working = re.sub(r"`([^`]+)`", self._code_replacement, working)
+        working = re.sub(
+            r"\[([^\]]+)\]\(([^)]+)\)",
+            self._link_replacement,
+            working,
+        )
+        working = re.sub(r"\*\*(.+?)\*\*", self._bold_replacement, working)
+        working = re.sub(r"__(.+?)__", self._bold_replacement, working)
+        working = re.sub(
+            r"(?<!\*)\*(?!\*)(.+?)(?<!\*)\*(?!\*)",
+            self._italic_replacement,
+            working,
+        )
+        working = re.sub(r"_(.+?)_", self._italic_replacement, working)
+
+        escaped = escape_latex(working)
+        for key, value in self._placeholders.items():
+            escaped = escaped.replace(key, value)
+        return escaped
+
+    def _placeholder(self, value: str) -> str:
+        token = f"LATEXPH{next(self._counter)}"
+        self._placeholders[token] = value
+        return token
+
+    def _code_replacement(self, match: re.Match[str]) -> str:
+        content = escape_latex(match.group(1))
+        return self._placeholder(rf"\texttt{{{content}}}")
+
+    def _link_replacement(self, match: re.Match[str]) -> str:
+        label = convert_inline(match.group(1))
+        url = escape_url(match.group(2))
+        return self._placeholder(rf"\href{{{url}}}{{{label}}}")
+
+    def _bold_replacement(self, match: re.Match[str]) -> str:
+        content = convert_inline(match.group(1))
+        return self._placeholder(rf"\textbf{{{content}}}")
+
+    def _italic_replacement(self, match: re.Match[str]) -> str:
+        content = convert_inline(match.group(1))
+        return self._placeholder(rf"\textit{{{content}}}")
+
+
+def convert_inline(text: str) -> str:
+    r"""Convert simple Markdown inline formatting to LaTeX.
+
+    This is a pure function that transforms Markdown syntax to LaTeX.
+
+    Supported Markdown:
+    - **bold** or __bold__ → \textbf{bold}
+    - *italic* or _italic_ → \textit{italic}
+    - `code` → \texttt{code}
+    - [text](url) → \href{url}{text}
+
+    Args:
+        text: Markdown-formatted text.
+
+    Returns:
+        LaTeX-formatted text.
+
+    Examples:
+        >>> convert_inline("This is **bold** text")
+        'This is \\textbf{bold} text'
+        >>> convert_inline("[GitHub](https://github.com)")
+        '\\href{https://github.com}{GitHub}'
+
+    """
+    converter = _InlineConverter()
+    return converter.convert(text)
+
+
+def normalize_iterable(value: Any) -> list[str]:
+    """Return a list of strings, regardless of the input type.
+
+    This is a pure function that coerces various types to a list of strings
+    with Markdown-to-LaTeX conversion applied.
+
+    Args:
+        value: Input value (None, str, list, tuple, set, or dict).
+
+    Returns:
+        List of LaTeX-formatted strings.
+
+    Examples:
+        >>> normalize_iterable(["Python", "JavaScript"])
+        ['Python', 'JavaScript']
+        >>> normalize_iterable({"Python": "Expert", "Go": "Intermediate"})
+        ['Python (Expert)', 'Go (Intermediate)']
+        >>> normalize_iterable(None)
+        []
+
+    """
+    if value is None:
+        return []
+    if isinstance(value, dict):
+        items = []
+        for key, val in value.items():
+            item = f"{key} ({val})"
+            items.append(convert_inline(str(item)))
+        return items
+    if isinstance(value, (list, tuple, set)):
+        return [convert_inline(str(item)) for item in value]
+    return [convert_inline(str(value))]
+
+
+def collect_blocks(description: str | None) -> list[Block]:
+    r"""Parse Markdown text into structured blocks for LaTeX rendering.
+
+    This is a pure function that transforms Markdown text into a list of
+    block structures (paragraphs and lists) suitable for LaTeX rendering.
+
+    Supported Markdown:
+    - Paragraphs separated by blank lines
+    - Bullet lists (-, *, +)
+    - Numbered lists (1., 2., etc.)
+    - Multi-line list items (indented continuation)
+
+    Args:
+        description: Markdown-formatted text (may be None).
+
+    Returns:
+        List of Block structures (ParagraphBlock or ListBlock).
+
+    Examples:
+        >>> blocks = collect_blocks("Paragraph.\\n\\n- Item 1\\n- Item 2")
+        >>> len(blocks)
+        2
+        >>> blocks[0]['kind']
+        'paragraph'
+        >>> blocks[1]['kind']
+        'itemize'
+
+    """
+    if not description:
+        return []
+
+    lines = description.strip("\n").splitlines()
+    blocks: list[Block] = []
+    current_items: list[str] = []
+    ordered = False
+
+    def flush_items() -> None:
+        nonlocal current_items, ordered
+        if current_items:
+            converted = [convert_inline(item) for item in current_items]
+            kind: Literal["itemize", "enumerate"] = (
+                "enumerate" if ordered else "itemize"
+            )
+            blocks.append({"kind": kind, "items": converted})
+            current_items = []
+            ordered = False
+
+    for line in lines:
+        stripped = line.rstrip()
+        if not stripped:
+            flush_items()
+            continue
+
+        bullet_match = re.match(r"^[-*+]\s+(.*)", stripped)
+        ordered_match = re.match(r"^\d+\.\s+(.*)", stripped)
+
+        if bullet_match:
+            if current_items and ordered:
+                flush_items()
+            ordered = False
+            current_items.append(bullet_match.group(1).strip())
+            continue
+
+        if ordered_match:
+            if current_items and not ordered:
+                flush_items()
+            ordered = True
+            current_items.append(ordered_match.group(1).strip())
+            continue
+
+        if stripped.startswith(" ") and current_items:
+            current_items[-1] = f"{current_items[-1]} {stripped.strip()}"
+            continue
+
+        flush_items()
+        paragraph_text = convert_inline(stripped)
+        blocks.append({"kind": "paragraph", "text": paragraph_text})
+
+    flush_items()
+    return blocks
+
+
+__all__ = [
+    "collect_blocks",
+    "convert_inline",
+    "normalize_iterable",
+]

simple_resume/core/latex/escaping.py

@@ -0,0 +1,68 @@
+"""LaTeX escaping functions (pure, no side effects)."""
+
+from __future__ import annotations
+
+LATEX_SPECIAL_CHARS = {
+    "\\": r"\textbackslash{}",
+    "&": r"\&",
+    "%": r"\%",
+    "$": r"\$",
+    "#": r"\#",
+    "_": r"\_",
+    "{": r"\{",
+    "}": r"\}",
+    "~": r"\textasciitilde{}",
+    "^": r"\textasciicircum{}",
+}
+
+
+def escape_latex(text: str) -> str:
+    r"""Escape LaTeX special characters.
+
+    This is a pure function that transforms a string by escaping characters
+    that have special meaning in LaTeX.
+
+    Args:
+        text: The input string to escape.
+
+    Returns:
+        The escaped string safe for use in LaTeX documents.
+
+    Examples:
+        >>> escape_latex("Price: $50 & up")
+        'Price: \\$50 \\& up'
+        >>> escape_latex("file_name")
+        'file\\_name'
+
+    """
+    return "".join(LATEX_SPECIAL_CHARS.get(char, char) for char in text)
+
+
+def escape_url(url: str) -> str:
+    r"""Escape characters in URLs that break LaTeX hyperlinks.
+
+    This is a pure function that escapes only the subset of characters
+    that cause issues in LaTeX URLs (fewer than general LaTeX escaping).
+
+    Args:
+        url: The URL to escape.
+
+    Returns:
+        The escaped URL safe for use in LaTeX \\href commands.
+
+    Examples:
+        >>> escape_url("https://example.com?q=test&foo=bar")
+        'https://example.com?q=test\\&foo=bar'
+        >>> escape_url("https://example.com/page#section")
+        'https://example.com/page\\#section'
+
+    """
+    replacements = {"%": r"\%", "#": r"\#", "&": r"\&", "_": r"\_"}
+    return "".join(replacements.get(char, char) for char in url)
+
+
+__all__ = [
+    "LATEX_SPECIAL_CHARS",
+    "escape_latex",
+    "escape_url",
+]

simple_resume/core/latex/fonts.py

@@ -0,0 +1,93 @@
+"""LaTeX font support functions (pure, no side effects)."""
+
+from __future__ import annotations
+
+import textwrap
+
+
+def fontawesome_support_block(fontawesome_dir: str | None) -> str:
+    r"""Return a LaTeX block that defines the contact icons.
+
+    This is a pure function that generates LaTeX code for FontAwesome
+    icon support. It uses either fontspec (with font files) or fallback
+    text-based icons.
+
+    Args:
+        fontawesome_dir: Path to fontawesome fonts directory, or None for fallback.
+
+    Returns:
+        LaTeX code block defining icon commands.
+
+    Examples:
+        >>> block = fontawesome_support_block(None)
+        >>> r"\\IfFileExists{fontawesome.sty}" in block
+        True
+        >>> block = fontawesome_support_block("/fonts/")
+        >>> r"\\usepackage{fontspec}" in block
+        True
+
+    """
+    fallback = textwrap.dedent(
+        r"""
+        \IfFileExists{fontawesome.sty}{%
+          \usepackage{fontawesome}%
+          \providecommand{\faLocation}{\faMapMarker}%
+        }{
+          \newcommand{\faPhone}{\textbf{P}}
+          \newcommand{\faEnvelope}{\textbf{@}}
+          \newcommand{\faLinkedin}{\textbf{in}}
+          \newcommand{\faGlobe}{\textbf{W}}
+          \newcommand{\faGithub}{\textbf{GH}}
+          \newcommand{\faLocation}{\textbf{A}}
+        }
+        """
+    ).strip()
+
+    if not fontawesome_dir:
+        return fallback
+
+    fontspec_block = textwrap.dedent(
+        rf"""
+        \usepackage{{fontspec}}
+        \newfontfamily\FAFreeSolid[
+            Path={fontawesome_dir},
+            Scale=0.72,
+        ]{{Font Awesome 6 Free-Solid-900.otf}}
+        \newfontfamily\FAFreeBrands[
+            Path={fontawesome_dir},
+            Scale=0.72,
+        ]{{Font Awesome 6 Brands-Regular-400.otf}}
+        \newcommand{{\faPhone}}{{%
+          {{\FAFreeSolid\symbol{{"F095}}}}%
+        }}
+        \newcommand{{\faEnvelope}}{{%
+          {{\FAFreeSolid\symbol{{"F0E0}}}}%
+        }}
+        \newcommand{{\faLinkedin}}{{%
+          {{\FAFreeBrands\symbol{{"F08C}}}}%
+        }}
+        \newcommand{{\faGlobe}}{{%
+          {{\FAFreeSolid\symbol{{"F0AC}}}}%
+        }}
+        \newcommand{{\faGithub}}{{%
+          {{\FAFreeBrands\symbol{{"F09B}}}}%
+        }}
+        \newcommand{{\faLocation}}{{%
+          {{\FAFreeSolid\symbol{{"F3C5}}}}%
+        }}
+        """
+    ).strip()
+
+    lines: list[str] = [r"\usepackage{iftex}", r"\ifPDFTeX"]
+    fallback_lines = fallback.splitlines()
+    lines.extend(f"  {line}" if line else "" for line in fallback_lines)
+    lines.append(r"\else")
+    fontspec_lines = fontspec_block.splitlines()
+    lines.extend(f"  {line}" if line else "" for line in fontspec_lines)
+    lines.append(r"\fi")
+    return "\n".join(lines)
+
+
+__all__ = [
+    "fontawesome_support_block",
+]

simple_resume/core/latex/formatting.py

@@ -0,0 +1,81 @@
+"""LaTeX formatting functions for dates and links (pure, no side effects)."""
+
+from __future__ import annotations
+
+from simple_resume.core.latex.conversion import convert_inline
+from simple_resume.core.latex.escaping import escape_url
+
+
+def format_date(start: str | None, end: str | None) -> str | None:
+    """Format start and end dates for LaTeX rendering.
+
+    This is a pure function that formats date ranges according to resume
+    conventions.
+
+    Args:
+        start: Start date string (may be None or empty).
+        end: End date string (may be None or empty).
+
+    Returns:
+        Formatted date range string, or None if both inputs are empty.
+
+    Examples:
+        >>> format_date("2020", "2023")
+        '2020 -- 2023'
+        >>> format_date("2023", "2023")
+        '2023'
+        >>> format_date("2020", "Present")
+        '2020 -- Present'
+        >>> format_date(None, None)
+        None
+
+    """
+    start_clean = start.strip() if isinstance(start, str) else ""
+    end_clean = end.strip() if isinstance(end, str) else ""
+
+    if start_clean and end_clean:
+        if start_clean == end_clean:
+            return convert_inline(start_clean)
+        return convert_inline(f"{start_clean} -- {end_clean}")
+    if end_clean:
+        return convert_inline(end_clean)
+    if start_clean:
+        return convert_inline(start_clean)
+    return None
+
+
+def linkify(text: str | None, link: str | None) -> str | None:
+    r"""Convert text to a hyperlink if a URL is provided.
+
+    This is a pure function that creates LaTeX \\href commands when
+    a link is provided, or returns the text as-is if no link.
+
+    Args:
+        text: The text to display (may be None).
+        link: The URL to link to (may be None or empty).
+
+    Returns:
+        LaTeX hyperlink command if link is provided, plain text otherwise,
+        or None if text is empty.
+
+    Examples:
+        >>> linkify("Company", "https://example.com")
+        '\\href{https://example.com}{Company}'
+        >>> linkify("Company", None)
+        'Company'
+        >>> linkify(None, "https://example.com")
+        None
+
+    """
+    if not text:
+        return None
+    rendered = convert_inline(text)
+    if link:
+        return rf"\href{{{escape_url(link)}}}{{{rendered}}}"
+    return rendered
+
+
+__all__ = [
+    "format_date",
+    "linkify",
+]

simple_resume/core/latex/sections.py

@@ -0,0 +1,218 @@
+"""LaTeX section preparation functions (pure, no side effects)."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from simple_resume.core.latex.conversion import collect_blocks, convert_inline
+from simple_resume.core.latex.escaping import escape_latex, escape_url
+from simple_resume.core.latex.formatting import format_date, linkify
+from simple_resume.core.latex.types import LatexEntry, LatexSection
+from simple_resume.core.skills import format_skill_groups
+
+
+def build_contact_lines(data: dict[str, Any]) -> list[str]:
+    """Build contact information lines from resume data.
+
+    This is a pure function that transforms resume data into LaTeX-formatted
+    contact lines with FontAwesome icons.
+
+    Args:
+        data: Resume data dictionary containing contact fields.
+
+    Returns:
+        List of LaTeX-formatted contact lines.
+
+    Examples:
+        >>> data = {"email": "user@example.com", "phone": "555-1234"}
+        >>> lines = build_contact_lines(data)
+        >>> len(lines)
+        2
+
+    """
+    lines: list[str] = []
+
+    def _icon_prefix(icon: str) -> str:
+        return rf"\{icon}\enspace "
+
+    # Address handling
+    address = data.get("address")
+    if isinstance(address, Iterable) and not isinstance(address, (str, bytes)):
+        joined = ", ".join(str(part) for part in address if part)
+    elif address:
+        joined = str(address)
+    else:
+        joined = ""
+
+    if joined:
+        lines.append(f"{_icon_prefix('faLocation')}{convert_inline(joined)}")
+
+    # Phone
+    phone = data.get("phone")
+    if phone:
+        lines.append(f"{_icon_prefix('faPhone')}{escape_latex(str(phone))}")
+
+    # Email
+    email = data.get("email")
+    if email:
+        lines.append(
+            rf"{_icon_prefix('faEnvelope')}\href{{mailto:{escape_url(email)}}}{{\nolinkurl{{{escape_latex(email)}}}}}"
+        )
+
+    # GitHub
+    github_added = False
+    github = data.get("github")
+    if github:
+        gh_value = str(github)
+        gh_url = (
+            gh_value
+            if gh_value.startswith("http")
+            else f"https://github.com/{gh_value.lstrip('/')}"
+        )
+        lines.append(
+            rf"{_icon_prefix('faGithub')}\href{{{escape_url(gh_url)}}}{{\nolinkurl{{{escape_latex(gh_value)}}}}}"
+        )
+        github_added = True
+
+    # Web
+    web = data.get("web")
+    if web:
+        web_value = str(web)
+        icon = "faGithub" if "github.com" in web_value.lower() else "faGlobe"
+        if icon == "faGithub" and github_added:
+            pass  # Skip duplicate GitHub entry
+        else:
+            lines.append(
+                rf"{_icon_prefix(icon)}\href{{{escape_url(web_value)}}}{{\nolinkurl{{{escape_latex(web_value)}}}}}"
+            )
+
+    # LinkedIn
+    linkedin = data.get("linkedin")
+    if linkedin:
+        url = linkedin
+        if not url.startswith("http"):
+            url = f"https://www.linkedin.com/{linkedin.lstrip('/')}"
+        lines.append(
+            rf"{_icon_prefix('faLinkedin')}\href{{{escape_url(url)}}}{{\nolinkurl{{{escape_latex(linkedin)}}}}}"
+        )
+
+    return lines
+
+
+def prepare_sections(data: dict[str, Any]) -> list[LatexSection]:
+    """Prepare resume body sections from data.
+
+    This is a pure function that transforms resume data into structured
+    LatexSection objects ready for template rendering.
+
+    Args:
+        data: Resume data dictionary with 'body' key containing sections.
+
+    Returns:
+        List of LatexSection objects.
+
+    Examples:
+        >>> data = {
+        ...     "body": {
+        ...         "Experience": [
+        ...             {"title": "Software Engineer", "company": "Tech Corp"}
+        ...         ]
+        ...     }
+        ... }
+        >>> sections = prepare_sections(data)
+        >>> len(sections)
+        1
+
+    """
+    sections: list[LatexSection] = []
+    body = data.get("body")
+    if not isinstance(body, dict):
+        return sections
+
+    for section_name, entries in body.items():
+        if not isinstance(entries, list):
+            continue
+
+        rendered_title = convert_inline(str(section_name))
+        rendered_entries: list[LatexEntry] = []
+
+        for entry in entries:
+            if not isinstance(entry, dict):
+                continue
+
+            title = linkify(entry.get("title"), entry.get("title_link"))
+            subtitle = linkify(entry.get("company"), entry.get("company_link"))
+            date_range = format_date(entry.get("start"), entry.get("end"))
+            blocks = collect_blocks(entry.get("description"))
+
+            rendered_entries.append(
+                LatexEntry(
+                    title=title or "",
+                    subtitle=subtitle,
+                    date_range=date_range,
+                    blocks=blocks,
+                )
+            )
+
+        if rendered_entries:
+            sections.append(
+                LatexSection(title=rendered_title, entries=rendered_entries)
+            )
+
+    return sections
+
+
+def prepare_skill_sections(data: dict[str, Any]) -> list[dict[str, Any]]:
+    """Prepare skill sections from resume data.
+
+    This is a pure function that transforms skill data into a list of
+    skill group dictionaries ready for LaTeX rendering.
+
+    Args:
+        data: Resume data containing skill fields (expertise, programming, etc.).
+
+    Returns:
+        List of skill section dictionaries with title and items.
+
+    Examples:
+        >>> data = {"expertise": ["Python", "JavaScript"]}
+        >>> sections = prepare_skill_sections(data)
+        >>> sections[0]["title"]
+        'Expertise'
+
+    """
+    titles = data.get("titles", {})
+    skill_sections: list[dict[str, Any]] = []
+
+    def append_groups(raw_value: Any, default_title: str) -> None:
+        for group in format_skill_groups(raw_value):
+            raw_items = group["items"]
+            if not isinstance(raw_items, (list, tuple, set)):
+                continue
+            items = [convert_inline(str(item)) for item in raw_items if item]
+            if not items:
+                continue
+            title = group["title"] or default_title
+            skill_sections.append(
+                {
+                    "title": convert_inline(str(title)),
+                    "items": items,
+                }
+            )
+
+    append_groups(data.get("expertise"), titles.get("expertise", "Expertise"))
+    append_groups(data.get("programming"), titles.get("programming", "Programming"))
+    append_groups(data.get("keyskills"), titles.get("keyskills", "Key Skills"))
+    append_groups(
+        data.get("certification"), titles.get("certification", "Certifications")
+    )
+
+    return skill_sections
+
+
+__all__ = [
+    "build_contact_lines",
+    "prepare_sections",
+    "prepare_skill_sections",
+]