add linters

2025-11-13 01:32:17 +03:00
parent c4bb087aaf
commit d5ff05abdb
28 changed files with 2070 additions and 331 deletions
--- a/cv/services/dowload/base.py
+++ b/cv/services/dowload/base.py
@@ -1,13 +1,30 @@
+"""Базовые протоколы и сериализаторы для рендереров резюме.
+
+Содержит `ProfileSerializer` для подготовки данных профиля к выводу
+и протокол `Renderer` с контрактом метода `render`.
+"""
+
 from __future__ import annotations

 from io import BytesIO
-from typing import Any, Dict, Protocol
+from typing import Any, Protocol


 class ProfileSerializer:
-    """Сериализатор данных профиля для рендереров."""
+    """Сериализатор данных профиля для рендереров.

-    def serialize(self, profile) -> Dict[str, Any]:
+    Готовит словарь с данными, необходимыми для HTML/PDF/DOCX рендеринга.
+    """
+
+    def serialize(self, profile: Any) -> dict[str, Any]:
+        """Собрать слепок профиля для рендеринга.
+
+        Args:
+            profile: Экземпляр модели профиля.
+
+        Returns:
+            dict[str, Any]: Сериализованные поля профиля, контактов, опыта и навыков.
+        """
        return {
            "full_name": profile.full_name,
            "role": getattr(profile, "role", ""),
@@ -25,6 +42,8 @@ class ProfileSerializer:


 class Renderer(Protocol):
-    def render(self, profile) -> BytesIO: ...
-
+    """Протокол рендерера документов с методом `render`."""

+    def render(self, profile: Any) -> BytesIO:
+        """Сгенерировать бинарный документ по профилю."""
+        ...
--- a/cv/services/dowload/docx.py
+++ b/cv/services/dowload/docx.py
@@ -1,21 +1,43 @@
+"""Рендеринг резюме в формат DOCX.
+
+Класс `DocxRenderer` формирует документ с заголовками, контактами, опытом
+и навыками на основе сериализованных данных профиля.
+"""
+
 from __future__ import annotations

+import logging
+from collections.abc import Sequence
 from io import BytesIO
+from typing import Any

-from docx import Document   
-from docx.shared import Pt, RGBColor
+from docx import Document as new_document
+from docx.document import Document as DocxDocument
 from docx.oxml import OxmlElement
 from docx.oxml.ns import qn
+from docx.shared import Pt, RGBColor

-from cv.services.dowload.pdf import ProfileSerializer
+from cv.services.dowload.base import ProfileSerializer
+from resume.utils.logging import configure_root_logger
+
+_root = logging.getLogger()
+if not _root.handlers:
+    configure_root_logger()
+logger = logging.getLogger(__name__)


 class DocxRenderer:
-    def __init__(self, ):
+    """Создает DOCX-документ на основе данных профиля."""
+
+    def __init__(
+        self,
+    ) -> None:
+        """Инициализирует сериализатор документов DOCX."""
        self.serializer = ProfileSerializer()

    @staticmethod
-    def _add_divider(document: Document) -> None:
+    def _add_divider(document: DocxDocument) -> None:
+        """Добавить горизонтальный разделитель как границу параграфа."""
        p = document.add_paragraph()
        fmt = p.paragraph_format
        fmt.space_before = Pt(6)
@@ -32,38 +54,45 @@ class DocxRenderer:
        pPr.append(pBdr)

    @staticmethod
-    def _month_year(dt) -> str:
+    def _month_year(dt: Any) -> str:
+        """Вернуть строку месяца и года на русском для даты."""
        ru_months = {
-            1: "январь", 2: "февраль", 3: "март", 4: "апрель",
-            5: "май", 6: "июнь", 7: "июль", 8: "август",
-            9: "сентябрь", 10: "октябрь", 11: "ноябрь", 12: "декабрь",
+            1: "январь",
+            2: "февраль",
+            3: "март",
+            4: "апрель",
+            5: "май",
+            6: "июнь",
+            7: "июль",
+            8: "август",
+            9: "сентябрь",
+            10: "октябрь",
+            11: "ноябрь",
+            12: "декабрь",
        }
        return f"{ru_months.get(dt.month, dt.strftime('%B')).capitalize()} {dt.year}"

-    def render(self, profile) -> BytesIO:
-        data = self.serializer.serialize(profile)
-        buf = BytesIO()
-        doc = Document()
-        # Заголовок
+    def _append_header(self, doc: DocxDocument, data: dict[str, Any]) -> None:
+        """Добавить заголовок и краткие сведения."""
        doc.core_properties.title = data["full_name"]
-        if data["role"]:
+        if data.get("role"):
            doc.core_properties.subject = data["role"]
        doc.add_heading(data["full_name"], level=0)
-        if data["role"]:
+        if data.get("role"):
            doc.add_paragraph(data["role"])
-        if data["summary"]:
+        if data.get("summary"):
            doc.add_paragraph(data["summary"])
        meta_parts: list[str] = []
-        if data["location"]:
+        if data.get("location"):
            meta_parts.append(data["location"])
-        if data["languages"]:
+        if data.get("languages"):
            meta_parts.append("Языки: " + ", ".join(data["languages"]))
        if meta_parts:
            doc.add_paragraph(" • ".join(meta_parts))

-        # Контакты
+    def _append_contacts(self, doc: DocxDocument, contacts: dict[str, Any]) -> None:
+        """Добавить секцию контактов."""
        doc.add_heading("Контакты", level=1)
-        contacts = data["contacts"]
        if contacts.get("email"):
            doc.add_paragraph(f"Email: {contacts['email']}")
        if contacts.get("phone"):
@@ -71,12 +100,17 @@ class DocxRenderer:
        if contacts.get("telegram"):
            doc.add_paragraph(f"Telegram: {contacts['telegram']}")

-        # Опыт
+    def _append_experience(self, doc: DocxDocument, experience: Sequence[Any] | None) -> None:
+        """Добавить опыт работы."""
        doc.add_heading("Опыт работы", level=1)
-        for i, e in enumerate(data["experience"]):
+        for i, e in enumerate(experience or []):
            if i:
                self._add_divider(doc)
-            period = f"{self._month_year(e.start_date)} — {(self._month_year(e.end_date) if e.end_date else 'настоящее время')}"
+            start = self._month_year(e.start_date) if getattr(e, "start_date", None) else ""
+            end = (
+                self._month_year(e.end_date) if getattr(e, "end_date", None) else "настоящее время"
+            )
+            period = f"{start} — {end}"
            p_company = doc.add_paragraph()
            run_company = p_company.add_run(e.company)
            run_company.bold = True
@@ -87,19 +121,42 @@ class DocxRenderer:
                r.font.color.rgb = RGBColor(0x99, 0xA2, 0xB2)
            if e.summary:
                doc.add_paragraph(e.summary)
-            for a in (e.achievements or []):
+            for a in e.achievements or []:
                if a:
                    doc.add_paragraph(a, style="List Bullet")
            if e.tech:
                doc.add_paragraph("Технологии: " + ", ".join([t for t in e.tech if t]))

-        # Навыки
+    def _append_skills(self, doc: DocxDocument, skills: Sequence[Any] | None) -> None:
+        """Добавить навыки."""
        doc.add_heading("Навыки", level=1)
-        for g in data["skills_map"]:
+        for g in skills or []:
            if g.items:
                doc.add_paragraph(f"{g.group}: " + ", ".join([i for i in g.items if i]))

+    def render(self, profile: Any) -> BytesIO:
+        """Сформировать DOCX документ по профилю.
+
+        Args:
+            profile: Объект профиля.
+
+        Returns:
+            BytesIO: Буфер с содержимым DOCX.
+        """
+        logger.info("Старт рендеринга DOCX для профиля")
+        data = self.serializer.serialize(profile)
+        buf = BytesIO()
+        doc: DocxDocument = new_document()
+        # Заголовок
+        self._append_header(doc, data)
+        # Контакты
+        self._append_contacts(doc, data.get("contacts", {}))
+        # Опыт
+        self._append_experience(doc, data.get("experience"))
+        # Навыки
+        self._append_skills(doc, data.get("skills_map"))
+
        doc.save(buf)
        buf.seek(0)
+        logger.info("DOCX сгенерирован: %s байт", buf.getbuffer().nbytes)
        return buf
-
--- a/cv/services/dowload/pdf.py
+++ b/cv/services/dowload/pdf.py
@@ -1,107 +1,199 @@
+"""Рендеринг резюме в PDF на базе WeasyPrint.
+
+Модуль предоставляет класс `PdfRenderer` для генерации минималистичного HTML
+и конвертации его в PDF. Включает базовый печатный CSS и сериализацию профиля.
+"""
+
 from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
 from io import BytesIO
+from typing import Any
+
 from weasyprint import HTML

+from cv.models import Profile
 from cv.services.dowload.base import ProfileSerializer
+from resume.utils.logging import configure_root_logger
+
+# Инициализация логирования с RichHandler (формат и уровень по правилам проекта)
+_root = logging.getLogger()
+if not _root.handlers:
+    configure_root_logger()
+logger = logging.getLogger(__name__)


 class PdfRenderer:
-    """Формирует HTML на лету (без шаблона) и конвертирует в PDF."""
+    """Формирует HTML на лету (без шаблона) и конвертирует в PDF.

-    def __init__(self):
-        # template не используется, оставлен для совместимости интерфейса
+    Методы класса генерируют минимальный печатный HTML и превращают его
+    в PDF с помощью WeasyPrint.
+    """
+
+    def __init__(self) -> None:
+        """Инициализирует сериализатор и части HTML."""
        self.serializer = ProfileSerializer()
+        self.parts: list[str] = []

-    def render(self, profile) -> BytesIO:
-        data = self.serializer.serialize(profile)
-        # Минимальный, печатный HTML с безопасными стилями
-        parts = []
-        parts.append("<!DOCTYPE html><html lang='ru'><head><meta charset='utf-8'>")
-        parts.append(f"<title>{data['full_name']} — Резюме (PDF)</title>")
-        parts.append("""
-        <style>
-          @page { size: A4; margin: 18mm 16mm; }
-          body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Arial, sans-serif; color: #111; }
-          h1 { margin: 0 0 6mm 0; font-size: 20pt; }
-          h2 { margin: 8mm 0 3mm 0; font-size: 13pt; border-bottom: 1px solid #ccc; padding-bottom: 2mm; }
-          p { margin: 0 0 3mm 0; line-height: 1.4; }
-          .meta { color: #555; }
-          .tag { display: inline-block; border: 1px solid #ddd; padding: 2px 6px; border-radius: 10px; font-size: 9pt; color: #444; margin-right: 4px; }
-          .item { margin: 0 0 5mm 0; }
-          .item-title { font-weight: 700; }
-          .item-period { color: #666; }
-          ul { margin: 2mm 0 2mm 6mm; }
-        </style>
-        </head><body>
-        """)
-        # Header
-        parts.append(f"<h1>{data['full_name']}</h1>")
-        if data["role"]:
-            parts.append(f"<p class='meta'><strong>{data['role']}</strong></p>")
-        if data["summary"]:
-            parts.append(f"<p>{data['summary']}</p>")
-        meta_tags = []
-        if data["location"]:
+    def _build_print_css(self) -> str:
+        """Вернуть минимальный CSS для печатного PDF.
+
+        Returns:
+            str: Строка CSS-правил, совместимых с WeasyPrint.
+        """
+        css_rules = """
+        @page { size: A4; margin: 18mm 16mm; }
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI",
+                        Roboto, Arial, sans-serif;
+            color: #111;
+        }
+        h1 {
+            margin: 0 0 6mm 0;
+            font-size: 20pt;
+        }
+        h2 {
+            margin: 8mm 0 3mm 0;
+            font-size: 13pt;
+            border-bottom: 1px solid #ccc;
+            padding-bottom: 2mm;
+        }
+        p {
+            margin: 0 0 3mm 0;
+            line-height: 1.4;
+        }
+        .meta { color: #555; }
+        .tag {
+            display: inline-block;
+            border: 1px solid #ddd;
+            padding: 2px 6px;
+            border-radius: 10px;
+            font-size: 9pt;
+            color: #444;
+            margin-right: 4px;
+        }
+        .item { margin: 0 0 5mm 0; }
+        .item-title { font-weight: 700; }
+        .item-period { color: #666; }
+        ul { margin: 2mm 0 2mm 6mm; }
+        """.strip()
+
+        return css_rules
+
+    def _append_head(self, full_name: str) -> None:
+        """Добавить секцию head с CSS.
+
+        Args:
+            full_name (str): Полное имя для тега <title>.
+        """
+        self.parts.append("<!DOCTYPE html><html lang='ru'><head><meta charset='utf-8'>")
+        self.parts.append(f"<title>{full_name} — Резюме (PDF)</title>")
+        self.parts.append("<style>")
+        self.parts.append(self._build_print_css())
+        self.parts.append("</style></head><body>")
+
+    def _append_header_section(self, data: dict[str, Any]) -> None:
+        """Добавить шапку с именем, ролью, summary и метками."""
+        self.parts.append(f"<h1>{data['full_name']}</h1>")
+        if data.get("role"):
+            self.parts.append(f"<p class='meta'><strong>{data['role']}</strong></p>")
+        if data.get("summary"):
+            self.parts.append(f"<p>{data['summary']}</p>")
+        meta_tags: list[str] = []
+        if data.get("location"):
            meta_tags.append(f"<span class='tag'>{data['location']}</span>")
-        if data["languages"]:
+        if data.get("languages"):
            meta_tags.append(f"<span class='tag'>Языки: {', '.join(data['languages'])}</span>")
        if meta_tags:
-            parts.append(f"<p class='meta'>{' '.join(meta_tags)}</p>")
+            self.parts.append(f"<p class='meta'>{' '.join(meta_tags)}</p>")

-        # Contacts
-        contacts = data["contacts"]
-        parts.append("<h2>Контакты</h2><p>")
+    def _append_contacts_section(self, contacts: dict[str, Any]) -> None:
+        """Добавить секцию контактов."""
+        self.parts.append("<h2>Контакты</h2><p>")
        if contacts.get("email"):
-            parts.append(f"<strong>Email:</strong> {contacts['email']}<br>")
+            self.parts.append(f"<strong>Email:</strong> {contacts['email']}<br>")
        if contacts.get("phone"):
-            parts.append(f"<strong>Телефон:</strong> {contacts['phone']}<br>")
+            self.parts.append(f"<strong>Телефон:</strong> {contacts['phone']}<br>")
        if contacts.get("telegram"):
-            parts.append(f"<strong>Telegram:</strong> {contacts['telegram']}")
-        parts.append("</p>")
+            self.parts.append(f"<strong>Telegram:</strong> {contacts['telegram']}")
+        self.parts.append("</p>")

-        # Experience
-        parts.append("<h2>Опыт работы</h2>")
-        exp = data["experience"]
-        if exp:
-            for e in exp:
-                parts.append("<div class='item'>")
-                parts.append(f"<div class='item-title'>{e.company}</div>")
+    def _append_experience_section(self, experience: Sequence[Any] | None) -> None:
+        """Добавить секцию опыта работы."""
+        self.parts.append("<h2>Опыт работы</h2>")
+        if experience:
+            for e in experience:
+                self.parts.append("<div class='item'>")
+                self.parts.append(f"<div class='item-title'>{e.company}</div>")
                period = ""
-                if getattr(e, 'start_date', None):
+                if getattr(e, "start_date", None):
                    period += e.start_date.strftime("%B %Y")
                period += " — "
-                period += e.end_date.strftime("%B %Y") if getattr(e, 'end_date', None) else "настоящее время"
-                parts.append(f"<div class='item-period'>{period}</div>")
+                period += (
+                    e.end_date.strftime("%B %Y")
+                    if getattr(e, "end_date", None)
+                    else "настоящее время"
+                )
+                self.parts.append(f"<div class='item-period'>{period}</div>")
                if e.summary:
-                    parts.append(f"<p>{e.summary}</p>")
+                    self.parts.append(f"<p>{e.summary}</p>")
                if e.achievements:
-                    parts.append("<ul>")
+                    self.parts.append("<ul>")
                    for a in e.achievements:
                        if a:
-                            parts.append(f"<li>{a}</li>")
-                    parts.append("</ul>")
+                            self.parts.append(f"<li>{a}</li>")
+                    self.parts.append("</ul>")
                if e.tech:
-                    parts.append(f"<p class='meta'>Технологии: {', '.join(e.tech)}</p>")
-                parts.append("</div>")
+                    self.parts.append(f"<p class='meta'>Технологии: {', '.join(e.tech)}</p>")
+                self.parts.append("</div>")
        else:
-            parts.append("<p class='meta'>Нет записей.</p>")
+            self.parts.append("<p class='meta'>Нет записей.</p>")

-        # Skills
-        parts.append("<h2>Навыки</h2>")
-        skills = data["skills_map"]
+    def _append_skills_section(self, skills: Sequence[Any] | None) -> None:
+        """Добавить секцию навыков."""
+        self.parts.append("<h2>Навыки</h2>")
        if skills:
            for g in skills:
                if g.items:
-                    parts.append(f"<p><strong>{g.group}:</strong> {', '.join([i for i in g.items if i])}</p>")
+                    self.parts.append(
+                        f"<p><strong>{g.group}:</strong> {', '.join([i for i in g.items if i])}</p>"
+                    )
        else:
-            parts.append("<p class='meta'>Нет данных.</p>")
+            self.parts.append("<p class='meta'>Нет данных.</p>")

-        parts.append("</body></html>")
+    def render(self, profile: Profile) -> BytesIO:
+        """Формирует HTML на лету (без шаблона) и конвертирует в PDF.

-        html = "".join(parts)
+        Args:
+            profile (Profile): Профиль для сериализации.
+
+        Returns:
+            BytesIO: PDF-файл.
+        """
+        logger.info("Старт рендеринга PDF для профиля")
+        data = self.serializer.serialize(profile)
+        if not data or "full_name" not in data or not data["full_name"]:
+            logger.error("Отсутствует обязательное поле full_name после сериализации")
+            raise ValueError("Невозможно сформировать PDF: отсутствует full_name")
+
+        logger.info("Сериализация профиля завершена, подготовка HTML")
+        # Head + Header
+        self._append_head(data["full_name"])
+        self._append_header_section(data)
+        # Contacts
+        self._append_contacts_section(data["contacts"])
+        # Experience
+        self._append_experience_section(data["experience"])
+        # Skills
+        self._append_skills_section(data["skills_map"])
+
+        self.parts.append("</body></html>")
+
+        logger.info("HTML подготовлен, генерация PDF через WeasyPrint")
+        html = "".join(self.parts)
        pdf = HTML(string=html).write_pdf()
        out = BytesIO(pdf)
        out.seek(0)
+        logger.info("PDF сгенерирован: %s байт", len(pdf))
        return out
-
-