sync-cv-formatter 1.2.0__tar.gz

sync_cv_formatter-1.2.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: sync_cv_formatter
+Version: 1.2.0
+Summary: CV/resume HTML and PDF rendering with hiring-manager-focused templates
+Author: SyncQues
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SyncQues/CV-Formatter
+Project-URL: Repository, https://github.com/SyncQues/CV-Formatter
+Project-URL: Issues, https://github.com/SyncQues/CV-Formatter/issues
+Keywords: resume,cv,pdf,html,jinja2
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: pydantic>=2.12.3
+
+# CV Formatter
+
+Public Python package for resume/CV HTML and PDF rendering — single source of truth for SyncQues resume templates, schemas, and rendering.
+
+**Repository:** https://github.com/SyncQues/CV-Formatter  
+**PyPI:** https://pypi.org/project/sync_cv_formatter/
+
+## Install
+
+```bash
+pip install sync_cv_formatter
+# or
+uv add sync_cv_formatter
+```
+
+## Consumers
+
+- `SyncQues-Backend` — recompile and live preview
+- `SyncQues-Resume` — initial resume generation
+
+## Usage
+
+```python
+from sync_cv_formatter import ResumeDocument, populate_html_template, render_html_to_pdf
+
+document = ResumeDocument.model_validate(content_json)
+html = populate_html_template(document, template_id="modern")
+pdf_bytes = render_html_to_pdf(html)
+```
+
+## Templates
+
+| ID | Style |
+|----|-------|
+| `professional` | Centered serif, traditional |
+| `executive` | Experience-first, navy serif/sans |
+| `modern` | Inter sans-serif, teal accent |
+| `classic` | Times New Roman, ATS-maximum |
+| `compact` | Dense one-page, IBM Plex |
+
+Legacy `creative` maps to `modern`.
+
+## Local development
+
+```bash
+uv sync --dev
+uv run pytest
+```
+
+Editable install from a checkout:
+
+```bash
+uv add --editable ../CV-Formatter
+```
+
+## Release process
+
+1. Change templates/code in this repo
+2. Bump `version` in `pyproject.toml`
+3. Run `uv run pytest`
+4. Commit, tag (`git tag v1.2.1`), push tag
+5. GitHub Actions publishes to PyPI (or `uv build && uv publish`)
+6. Bump pin in Backend + Resume `pyproject.toml` and `uv lock`
+
+## Versioning
+
+- **MAJOR** — breaking `content_json` schema changes
+- **MINOR** — template/CSS changes or new optional fields
+- **PATCH** — bug fixes

sync_cv_formatter-1.2.0/README.md

@@ -0,0 +1,69 @@
+# CV Formatter
+
+Public Python package for resume/CV HTML and PDF rendering — single source of truth for SyncQues resume templates, schemas, and rendering.
+
+**Repository:** https://github.com/SyncQues/CV-Formatter  
+**PyPI:** https://pypi.org/project/sync_cv_formatter/
+
+## Install
+
+```bash
+pip install sync_cv_formatter
+# or
+uv add sync_cv_formatter
+```
+
+## Consumers
+
+- `SyncQues-Backend` — recompile and live preview
+- `SyncQues-Resume` — initial resume generation
+
+## Usage
+
+```python
+from sync_cv_formatter import ResumeDocument, populate_html_template, render_html_to_pdf
+
+document = ResumeDocument.model_validate(content_json)
+html = populate_html_template(document, template_id="modern")
+pdf_bytes = render_html_to_pdf(html)
+```
+
+## Templates
+
+| ID | Style |
+|----|-------|
+| `professional` | Centered serif, traditional |
+| `executive` | Experience-first, navy serif/sans |
+| `modern` | Inter sans-serif, teal accent |
+| `classic` | Times New Roman, ATS-maximum |
+| `compact` | Dense one-page, IBM Plex |
+
+Legacy `creative` maps to `modern`.
+
+## Local development
+
+```bash
+uv sync --dev
+uv run pytest
+```
+
+Editable install from a checkout:
+
+```bash
+uv add --editable ../CV-Formatter
+```
+
+## Release process
+
+1. Change templates/code in this repo
+2. Bump `version` in `pyproject.toml`
+3. Run `uv run pytest`
+4. Commit, tag (`git tag v1.2.1`), push tag
+5. GitHub Actions publishes to PyPI (or `uv build && uv publish`)
+6. Bump pin in Backend + Resume `pyproject.toml` and `uv lock`
+
+## Versioning
+
+- **MAJOR** — breaking `content_json` schema changes
+- **MINOR** — template/CSS changes or new optional fields
+- **PATCH** — bug fixes

sync_cv_formatter-1.2.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "sync_cv_formatter"
+version = "1.2.0"
+description = "CV/resume HTML and PDF rendering with hiring-manager-focused templates"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "SyncQues" }]
+keywords = ["resume", "cv", "pdf", "html", "jinja2"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Text Processing :: Markup :: HTML",
+]
+dependencies = [
+    "jinja2>=3.1.6",
+    "pydantic>=2.12.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/SyncQues/CV-Formatter"
+Repository = "https://github.com/SyncQues/CV-Formatter"
+Issues = "https://github.com/SyncQues/CV-Formatter/issues"
+
+[dependency-groups]
+dev = [
+    "build>=1.2",
+    "pytest>=8.3",
+    "twine>=6.1",
+]
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+sync_cv_formatter = ["templates/html/**/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

sync_cv_formatter-1.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sync_cv_formatter-1.2.0/src/sync_cv_formatter/__init__.py

@@ -0,0 +1,13 @@
+from sync_cv_formatter.renderers.html_renderer import (
+    populate_html_template,
+    save_html_file,
+)
+from sync_cv_formatter.renderers.pdf_renderer import render_html_to_pdf
+from sync_cv_formatter.schemas.resume_document import ResumeDocument
+
+__all__ = [
+    "ResumeDocument",
+    "populate_html_template",
+    "render_html_to_pdf",
+    "save_html_file",
+]

sync_cv_formatter-1.2.0/src/sync_cv_formatter/renderers/__init__.py

@@ -0,0 +1,4 @@
+from sync_cv_formatter.renderers.html_renderer import populate_html_template, save_html_file
+from sync_cv_formatter.renderers.pdf_renderer import render_html_to_pdf
+
+__all__ = ["populate_html_template", "render_html_to_pdf", "save_html_file"]

sync_cv_formatter-1.2.0/src/sync_cv_formatter/renderers/html_renderer.py

@@ -0,0 +1,211 @@
+from datetime import datetime
+from pathlib import Path
+from urllib.parse import urlparse
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+from sync_cv_formatter.schemas.resume_document import ResumeDocument, ResumeTemplateId
+
+_PKG_DIR = Path(__file__).resolve().parent.parent
+HTML_TEMPLATES_DIR = _PKG_DIR / "templates" / "html"
+
+_MONTHS = (
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+)
+
+
+def _format_resume_date(value: str | None) -> str:
+    if not value:
+        return "Present"
+
+    normalized = str(value).strip()
+    if normalized.lower() == "present":
+        return "Present"
+
+    try:
+        parsed = datetime.fromisoformat(normalized.replace("Z", "+00:00"))
+        return f"{_MONTHS[parsed.month - 1]} {parsed.year}"
+    except ValueError:
+        pass
+
+    if len(normalized) >= 7 and normalized[4] == "-":
+        try:
+            year = int(normalized[:4])
+            month = int(normalized[5:7])
+            if 1 <= month <= 12:
+                return f"{_MONTHS[month - 1]} {year}"
+        except ValueError:
+            pass
+
+    return normalized
+
+
+def _format_external_url(url: str | None) -> str:
+    if not url:
+        return ""
+    normalized = str(url).strip()
+    return normalized if normalized.startswith("http") else f"https://{normalized}"
+
+
+def _resume_link_domain(url: str | None) -> str | None:
+    href = _format_external_url(url)
+    if not href:
+        return None
+    try:
+        hostname = urlparse(href).hostname or ""
+        return hostname.removeprefix("www.") or None
+    except ValueError:
+        return None
+
+
+def _resume_favicon_url(url: str | None) -> str:
+    domain = _resume_link_domain(url)
+    if not domain:
+        return ""
+    return f"https://www.google.com/s2/favicons?domain={domain}&sz=32"
+
+
+_PLATFORM_LABELS = {
+    "linkedin": "LinkedIn",
+    "github": "GitHub",
+    "gitlab": "GitLab",
+    "twitter": "Twitter",
+    "x": "X",
+    "youtube": "YouTube",
+    "instagram": "Instagram",
+    "facebook": "Facebook",
+    "portfolio": "Portfolio",
+    "website": "Website",
+    "syncques": "SyncQues",
+    "leetcode": "LeetCode",
+    "stackoverflow": "Stack Overflow",
+    "medium": "Medium",
+    "behance": "Behance",
+    "dribbble": "Dribbble",
+    "credential": "View Credential",
+    "live": "Live",
+}
+
+_DOMAIN_LABEL_PATTERNS: list[tuple[str, str]] = [
+    ("linkedin.com", "LinkedIn"),
+    ("github.com", "GitHub"),
+    ("gitlab.com", "GitLab"),
+    ("twitter.com", "X"),
+    ("x.com", "X"),
+    ("youtube.com", "YouTube"),
+    ("youtu.be", "YouTube"),
+    ("instagram.com", "Instagram"),
+    ("facebook.com", "Facebook"),
+    ("fb.com", "Facebook"),
+    ("syncques.com", "SyncQues"),
+    ("leetcode.com", "LeetCode"),
+    ("stackoverflow.com", "Stack Overflow"),
+    ("medium.com", "Medium"),
+    ("behance.net", "Behance"),
+    ("dribbble.com", "Dribbble"),
+    ("credly.com", "Credly"),
+]
+
+
+def _resume_link_label(
+    platform_or_kind: str, url: str | None = None, fallback: str | None = None
+) -> str:
+    platform_key = platform_or_kind.lower().replace(" ", "_")
+    if platform_key in _PLATFORM_LABELS:
+        return _PLATFORM_LABELS[platform_key]
+
+    href = _format_external_url(url)
+    if href:
+        lower_href = href.lower()
+        for domain, label in _DOMAIN_LABEL_PATTERNS:
+            if domain in lower_href:
+                return label
+
+        domain = _resume_link_domain(href)
+        if domain:
+            base = domain.split(".")[0]
+            return base[:1].upper() + base[1:]
+
+    if fallback:
+        return fallback
+
+    return platform_or_kind.replace("_", " ").title()
+
+
+TEMPLATE_DIRS: dict[ResumeTemplateId, str] = {
+    "professional": "professional",
+    "executive": "executive",
+    "modern": "modern",
+    "classic": "classic",
+    "compact": "compact",
+}
+
+_LEGACY_TEMPLATE_ALIASES: dict[str, ResumeTemplateId] = {
+    "creative": "modern",
+}
+
+
+def _get_template_env(template_id: ResumeTemplateId) -> Environment:
+    template_dir = HTML_TEMPLATES_DIR / TEMPLATE_DIRS[template_id]
+    env = Environment(
+        loader=FileSystemLoader(
+            [str(template_dir), str(HTML_TEMPLATES_DIR)],
+        ),
+        autoescape=select_autoescape(["html", "xml"]),
+    )
+    env.filters["format_resume_date"] = _format_resume_date
+    env.filters["format_external_url"] = _format_external_url
+    env.filters["resume_favicon_url"] = _resume_favicon_url
+    env.globals["resume_link_label"] = _resume_link_label
+    return env
+
+
+def _load_css(template_id: ResumeTemplateId) -> str:
+    css_path = HTML_TEMPLATES_DIR / TEMPLATE_DIRS[template_id] / "styles.css"
+    return css_path.read_text(encoding="utf-8")
+
+
+def _resolve_template_id(
+    template_id: str | ResumeTemplateId | None,
+    *,
+    fallback: ResumeTemplateId = "professional",
+) -> ResumeTemplateId:
+    normalized = str(template_id or fallback).strip().lower()
+    if normalized in _LEGACY_TEMPLATE_ALIASES:
+        return _LEGACY_TEMPLATE_ALIASES[normalized]
+    if normalized in TEMPLATE_DIRS:
+        return normalized  # type: ignore[return-value]
+    return fallback
+
+
+def populate_html_template(
+    document: ResumeDocument,
+    template_id: ResumeTemplateId | None = None,
+    *,
+    interactive: bool = False,
+) -> str:
+    selected_template = _resolve_template_id(template_id or document.template_id)
+    env = _get_template_env(selected_template)
+    template = env.get_template("template.html.j2")
+    return template.render(
+        document=document,
+        css_content=_load_css(selected_template),
+        interactive=interactive,
+    )
+
+
+def save_html_file(content: str, output_path: str) -> str:
+    html_path = output_path.replace(".pdf", ".html")
+    Path(html_path).write_text(content, encoding="utf-8")
+    return html_path

sync_cv_formatter-1.2.0/src/sync_cv_formatter/renderers/pdf_renderer.py

@@ -0,0 +1,42 @@
+from pathlib import Path
+
+
+def render_html_to_pdf(html_file: str, output_dir: str | None = None) -> tuple[bool, str]:
+    html_path = Path(html_file)
+
+    if not html_path.exists():
+        return False, f"HTML file not found: {html_file}"
+
+    if output_dir is None:
+        output_dir = html_path.parent
+
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    pdf_path = output_dir / html_path.with_suffix(".pdf").name
+
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError:
+        return False, "Playwright is not installed. Run: playwright install chromium"
+
+    try:
+        file_url = html_path.resolve().as_uri()
+        with sync_playwright() as playwright:
+            browser = playwright.chromium.launch(headless=True)
+            page = browser.new_page()
+            page.goto(file_url, wait_until="networkidle")
+            page.pdf(
+                path=str(pdf_path),
+                format="A4",
+                print_background=True,
+                prefer_css_page_size=True,
+                margin={"top": "0", "right": "0", "bottom": "0", "left": "0"},
+            )
+            browser.close()
+
+        if pdf_path.exists():
+            return True, f"PDF created successfully: {pdf_path}"
+
+        return False, "PDF file was not created by Playwright"
+    except Exception as exc:
+        return False, f"HTML to PDF rendering failed: {exc}"

sync_cv_formatter-1.2.0/src/sync_cv_formatter/schemas/__init__.py

@@ -0,0 +1,27 @@
+from sync_cv_formatter.schemas.resume_document import (
+    AchievementItem,
+    BasicsSection,
+    EducationItem,
+    ExperienceItem,
+    ProjectItem,
+    ResumeDocument,
+    ResumeDocumentMetadata,
+    ResumeSections,
+    ResumeTemplateId,
+    ResumeTypeValue,
+    SkillsSection,
+)
+
+__all__ = [
+    "AchievementItem",
+    "BasicsSection",
+    "EducationItem",
+    "ExperienceItem",
+    "ProjectItem",
+    "ResumeDocument",
+    "ResumeDocumentMetadata",
+    "ResumeSections",
+    "ResumeTemplateId",
+    "ResumeTypeValue",
+    "SkillsSection",
+]

sync_cv_formatter-1.2.0/src/sync_cv_formatter/schemas/resume_document.py

@@ -0,0 +1,100 @@
+from datetime import datetime, timezone
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+ResumeTemplateId = Literal["professional", "executive", "modern", "classic", "compact"]
+ResumeTypeValue = Literal["standard", "ats_optimized"]
+
+
+class BasicsSection(BaseModel):
+    full_name: str = ""
+    email: str = ""
+    phone: str | None = None
+    location: str | None = None
+    summary: str | None = None
+    syncques_url: str | None = None
+    social_links: dict[str, str] = Field(default_factory=dict)
+
+
+class SkillsSection(BaseModel):
+    flat: list[str] = Field(default_factory=list)
+    categorized: dict[str, list[str]] = Field(default_factory=dict)
+
+
+class ExperienceItem(BaseModel):
+    title: str = ""
+    company: str = ""
+    location: str | None = None
+    start_date: str | None = None
+    end_date: str | None = "Present"
+    description: str = ""
+
+
+class EducationItem(BaseModel):
+    institution: str = ""
+    degree: str = ""
+    field_of_study: str | None = None
+    location: str | None = None
+    start_date: str | None = None
+    end_date: str | None = "Present"
+    gpa: str | None = None
+    description: str | None = None
+
+
+class ProjectItem(BaseModel):
+    title: str = ""
+    description: str = ""
+    technologies: list[str] = Field(default_factory=list)
+    project_url: str | None = None
+    repository_url: str | None = None
+    start_date: str | None = None
+    end_date: str | None = None
+
+
+class AchievementItem(BaseModel):
+    title: str = ""
+    organization: str | None = None
+    description: str | None = None
+    date_earned: str | None = None
+    credential_url: str | None = None
+
+
+class ResumeSections(BaseModel):
+    skills: SkillsSection = Field(default_factory=SkillsSection)
+    experience: list[ExperienceItem] = Field(default_factory=list)
+    education: list[EducationItem] = Field(default_factory=list)
+    projects: list[ProjectItem] = Field(default_factory=list)
+    achievements: list[AchievementItem] = Field(default_factory=list)
+
+
+class ResumeDocumentMetadata(BaseModel):
+    generated_at: str
+    resume_type: ResumeTypeValue = "standard"
+    job_title: str | None = None
+    job_description: str | None = None
+    last_edited_at: str | None = None
+    content_version: int = 1
+
+
+class ResumeDocument(BaseModel):
+    schema_version: str = "1.0"
+    template_id: ResumeTemplateId = "professional"
+    basics: BasicsSection = Field(default_factory=BasicsSection)
+    sections: ResumeSections = Field(default_factory=ResumeSections)
+    metadata: ResumeDocumentMetadata
+
+    @classmethod
+    def default_metadata(
+        cls,
+        resume_type: ResumeTypeValue = "standard",
+        job_title: str | None = None,
+        job_description: str | None = None,
+    ) -> ResumeDocumentMetadata:
+        return ResumeDocumentMetadata(
+            generated_at=datetime.now(timezone.utc).isoformat(),
+            resume_type=resume_type,
+            job_title=job_title,
+            job_description=job_description,
+            content_version=1,
+        )

sync_cv_formatter-1.2.0/src/sync_cv_formatter/templates/html/_base_head.html.j2

@@ -0,0 +1,10 @@
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>{{ document.basics.full_name }} — Resume</title>
+<style>{{ css_content }}</style>
+{% if interactive %}
+<style>
+  [data-resume-section] { cursor: pointer; border-radius: 2px; }
+  [data-resume-section]:hover { background: rgba(0, 51, 153, 0.05); }
+</style>
+{% endif %}

sync_cv_formatter-1.2.0/src/sync_cv_formatter/templates/html/_macros.html.j2

@@ -0,0 +1,43 @@
+{% macro resume_contact(document) %}
+  {% set ns = namespace(first=true) %}
+  {% if document.basics.email %}
+    {% if not ns.first %}<span class="contact-sep">·</span>{% endif %}
+    <a href="mailto:{{ document.basics.email }}">{{ document.basics.email }}</a>
+    {% set ns.first = false %}
+  {% endif %}
+  {% if document.basics.phone %}
+    {% if not ns.first %}<span class="contact-sep">·</span>{% endif %}
+    <a href="tel:{{ document.basics.phone }}">{{ document.basics.phone }}</a>
+    {% set ns.first = false %}
+  {% endif %}
+  {% if document.basics.location %}
+    {% if not ns.first %}<span class="contact-sep">·</span>{% endif %}
+    <span>{{ document.basics.location }}</span>
+    {% set ns.first = false %}
+  {% endif %}
+  {% if document.basics.syncques_url %}
+    {% if not ns.first %}<span class="contact-sep">·</span>{% endif %}
+    {{ external_link('syncques', document.basics.syncques_url) }}
+    {% set ns.first = false %}
+  {% endif %}
+  {% for platform, url in document.basics.social_links.items() %}
+    {% if url %}
+      {% if not ns.first %}<span class="contact-sep">·</span>{% endif %}
+      {{ external_link(platform, url) }}
+      {% set ns.first = false %}
+    {% endif %}
+  {% endfor %}
+{% endmacro %}
+
+{% macro external_link(platform, url, fallback='') %}
+  {% set href = url | format_external_url %}
+  {% if href %}
+    <a href="{{ href }}" class="resume-external-link">
+      {% set favicon = url | resume_favicon_url %}
+      {% if favicon %}
+        <img src="{{ favicon }}" alt="" class="resume-link-icon" width="12" height="12" />
+      {% endif %}
+      <span>{{ resume_link_label(platform, url, fallback) }}</span>
+    </a>
+  {% endif %}
+{% endmacro %}