paper-scoring-reporting 0.1.0__tar.gz

paper_scoring_reporting-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paper Scoring contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

paper_scoring_reporting-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: paper-scoring-reporting
+Version: 0.1.0
+Summary: Safe HTML, text, PDF, and SMTP reporting for Paper Scoring results
+Author: Paper Scoring contributors
+License-Expression: MIT
+Project-URL: Repository, https://github.com/maikeruSan/paper-scoring-reporting
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: paper-scoring-core<0.2,>=0.1
+Requires-Dist: reportlab<5,>=4.2
+Provides-Extra: test
+Requires-Dist: build<2,>=1.2; extra == "test"
+Requires-Dist: mypy<2,>=1.18; extra == "test"
+Requires-Dist: pypdf<7,>=5; extra == "test"
+Requires-Dist: pytest<10,>=9.0.3; extra == "test"
+Requires-Dist: pytest-cov<8,>=6; extra == "test"
+Requires-Dist: ruff<1,>=0.12; extra == "test"
+Requires-Dist: twine<7,>=6; extra == "test"
+Requires-Dist: types-reportlab<5,>=4.4; extra == "test"
+Provides-Extra: security
+Requires-Dist: bandit[toml]<2,>=1.8; extra == "security"
+Requires-Dist: detect-secrets<2,>=1.5; extra == "security"
+Requires-Dist: pip-audit<3,>=2.9; extra == "security"
+Dynamic: license-file
+
+# Paper Scoring Reporting
+
+`paper-scoring-reporting` turns `paper-scoring-core` score results into plain-text,
+mobile-friendly HTML, and PDF reports. SMTP delivery is a separate, explicitly
+configured step. The package never reads `.env` files or process environment
+variables.
+
+## Install
+
+```shell
+python -m pip install paper-scoring-reporting
+```
+
+## Render and deliver
+
+```python
+from datetime import date
+
+from paper_scoring_reporting import (
+    ReportMetadata,
+    SMTPSettings,
+    SMTPSender,
+    compose_report_email,
+    render_report,
+)
+
+report = render_report(
+    score_results,
+    ReportMetadata(
+        report_date=date.today(),
+        category="cs.AI",
+        scoring_version="3.0.0",
+    ),
+)
+
+settings = SMTPSettings(
+    host="smtp.example.invalid",
+    port=587,
+    sender="automation@example.invalid",
+    username="automation@example.invalid",
+    password=runtime_password,
+)
+email = compose_report_email(
+    sender=settings.sender,
+    recipients=["reviewer@example.invalid"],
+    subject="Paper scoring report",
+    report=report,
+)
+SMTPSender(settings).send(email)
+```
+
+Inject credentials at runtime from your process supervisor, secret store, CLI, or
+MCP composition root. Do not put credentials in source files or report data.
+
+## Accepted result values
+
+The renderer accepts a sequence of `paper_scoring_core.ScoreResult` objects, objects
+with a safe `model_dump()` method, dataclass instances, or mappings. Only the public
+score-report fields are selected; arbitrary object attributes and unknown mapping
+keys are ignored. Legacy title-cased mapping keys are accepted for migration.
+
+## Development
+
+```shell
+python -m pip install -e '.[test,security]'
+pytest
+ruff check .
+bandit -c pyproject.toml -r src
+pip-audit
+```
+
+CI exercises Python 3.11 through 3.13 on Ubuntu and Windows, builds wheel and sdist
+artifacts, and verifies their metadata.

paper_scoring_reporting-0.1.0/README.md

@@ -0,0 +1,73 @@
+# Paper Scoring Reporting
+
+`paper-scoring-reporting` turns `paper-scoring-core` score results into plain-text,
+mobile-friendly HTML, and PDF reports. SMTP delivery is a separate, explicitly
+configured step. The package never reads `.env` files or process environment
+variables.
+
+## Install
+
+```shell
+python -m pip install paper-scoring-reporting
+```
+
+## Render and deliver
+
+```python
+from datetime import date
+
+from paper_scoring_reporting import (
+    ReportMetadata,
+    SMTPSettings,
+    SMTPSender,
+    compose_report_email,
+    render_report,
+)
+
+report = render_report(
+    score_results,
+    ReportMetadata(
+        report_date=date.today(),
+        category="cs.AI",
+        scoring_version="3.0.0",
+    ),
+)
+
+settings = SMTPSettings(
+    host="smtp.example.invalid",
+    port=587,
+    sender="automation@example.invalid",
+    username="automation@example.invalid",
+    password=runtime_password,
+)
+email = compose_report_email(
+    sender=settings.sender,
+    recipients=["reviewer@example.invalid"],
+    subject="Paper scoring report",
+    report=report,
+)
+SMTPSender(settings).send(email)
+```
+
+Inject credentials at runtime from your process supervisor, secret store, CLI, or
+MCP composition root. Do not put credentials in source files or report data.
+
+## Accepted result values
+
+The renderer accepts a sequence of `paper_scoring_core.ScoreResult` objects, objects
+with a safe `model_dump()` method, dataclass instances, or mappings. Only the public
+score-report fields are selected; arbitrary object attributes and unknown mapping
+keys are ignored. Legacy title-cased mapping keys are accepted for migration.
+
+## Development
+
+```shell
+python -m pip install -e '.[test,security]'
+pytest
+ruff check .
+bandit -c pyproject.toml -r src
+pip-audit
+```
+
+CI exercises Python 3.11 through 3.13 on Ubuntu and Windows, builds wheel and sdist
+artifacts, and verifies their metadata.

paper_scoring_reporting-0.1.0/pyproject.toml

@@ -0,0 +1,85 @@
+[build-system]
+requires = ["setuptools==84.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "paper-scoring-reporting"
+version = "0.1.0"
+description = "Safe HTML, text, PDF, and SMTP reporting for Paper Scoring results"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Paper Scoring contributors" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Communications :: Email",
+]
+dependencies = [
+  "paper-scoring-core>=0.1,<0.2",
+  "reportlab>=4.2,<5",
+]
+
+[project.optional-dependencies]
+test = [
+  "build>=1.2,<2",
+  "mypy>=1.18,<2",
+  "pypdf>=5,<7",
+  "pytest>=9.0.3,<10",
+  "pytest-cov>=6,<8",
+  "ruff>=0.12,<1",
+  "twine>=6,<7",
+  "types-reportlab>=4.4,<5",
+]
+security = [
+  "bandit[toml]>=1.8,<2",
+  "detect-secrets>=1.5,<2",
+  "pip-audit>=2.9,<3",
+]
+
+[project.urls]
+Repository = "https://github.com/maikeruSan/paper-scoring-reporting"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+paper_scoring_reporting = ["py.typed", "templates/*.html", "templates/*.txt"]
+
+[tool.pytest.ini_options]
+addopts = "-ra --strict-markers"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+relative_files = true
+source = ["paper_scoring_reporting"]
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "S", "UP"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/paper_scoring_reporting/renderer.py" = ["E501"]
+"tests/**" = ["S101", "S106"]
+"tests/check_distribution.py" = ["S603"]
+
+[tool.bandit]
+exclude_dirs = ["tests"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src/paper_scoring_reporting"]

paper_scoring_reporting-0.1.0/setup.cfg

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

paper_scoring_reporting-0.1.0/src/paper_scoring_reporting/__init__.py

@@ -0,0 +1,33 @@
+"""Render and deliver Paper Scoring reports without import-time side effects."""
+
+from .email import compose_email, compose_report_email
+from .models import (
+    Attachment,
+    PreparedEmail,
+    RenderedReport,
+    ReportMetadata,
+    SMTPSettings,
+    TLSMode,
+)
+from .renderer import ReportRenderer, build_report, render_report
+from .smtp import SMTPDeliveryError, SMTPDeliveryResult, SMTPSender, send_email
+
+__all__ = [
+    "Attachment",
+    "PreparedEmail",
+    "RenderedReport",
+    "ReportMetadata",
+    "ReportRenderer",
+    "SMTPDeliveryError",
+    "SMTPDeliveryResult",
+    "SMTPSettings",
+    "SMTPSender",
+    "TLSMode",
+    "build_report",
+    "compose_email",
+    "compose_report_email",
+    "render_report",
+    "send_email",
+]
+
+__version__ = "0.1.0"

paper_scoring_reporting-0.1.0/src/paper_scoring_reporting/email.py

@@ -0,0 +1,78 @@
+"""Compose standards-compliant report email without opening a network connection."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from email.message import EmailMessage
+from email.policy import SMTP
+
+from .models import Attachment, PreparedEmail, RenderedReport
+from .validation import validate_email_address, validate_header, validate_mime_type
+
+
+def compose_email(
+    *,
+    sender: str,
+    recipients: Sequence[str],
+    subject: str,
+    plain_text: str,
+    html: str,
+    attachments: Sequence[Attachment] = (),
+) -> PreparedEmail:
+    """Build a validated MIME email without performing delivery."""
+
+    sender = validate_email_address(sender)
+    if isinstance(recipients, (str, bytes, bytearray)):
+        raise TypeError("recipients must be a sequence of email addresses")
+    validated_recipients = tuple(validate_email_address(item) for item in recipients)
+    if not validated_recipients:
+        raise ValueError("at least one recipient is required")
+    subject = validate_header(subject, name="subject")
+    if not isinstance(plain_text, str) or not isinstance(html, str):
+        raise TypeError("plain_text and html must be strings")
+    if isinstance(attachments, (str, bytes, bytearray)):
+        raise TypeError("attachments must be a sequence")
+
+    message = EmailMessage(policy=SMTP)
+    message["From"] = sender
+    message["To"] = ", ".join(validated_recipients)
+    message["Subject"] = subject
+    message.set_content(plain_text, subtype="plain", charset="utf-8")
+    message.add_alternative(html, subtype="html", charset="utf-8")
+    for attachment in attachments:
+        if not isinstance(attachment, Attachment):
+            raise TypeError("attachments must contain Attachment values")
+        main_type, subtype = validate_mime_type(attachment.content_type)
+        message.add_attachment(
+            attachment.content,
+            maintype=main_type,
+            subtype=subtype,
+            filename=attachment.filename,
+        )
+    return PreparedEmail(message, validated_recipients)
+
+
+def compose_report_email(
+    *,
+    sender: str,
+    recipients: Sequence[str],
+    subject: str,
+    report: RenderedReport,
+    attachments: Sequence[Attachment] = (),
+) -> PreparedEmail:
+    """Build a MIME message with text/HTML alternatives and a PDF attachment."""
+
+    if not isinstance(report, RenderedReport):
+        raise TypeError("report must be a RenderedReport")
+    all_attachments = (
+        Attachment(report.pdf_filename, report.pdf, "application/pdf"),
+        *attachments,
+    )
+    return compose_email(
+        sender=sender,
+        recipients=recipients,
+        subject=subject,
+        plain_text=report.plain_text,
+        html=report.html,
+        attachments=all_attachments,
+    )

paper_scoring_reporting-0.1.0/src/paper_scoring_reporting/models.py

@@ -0,0 +1,136 @@
+"""Public immutable value objects for reports and email delivery."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date
+from email.message import EmailMessage
+from enum import StrEnum
+
+from .validation import (
+    validate_attachment_filename,
+    validate_email_address,
+    validate_header,
+    validate_hostname,
+    validate_mime_type,
+)
+
+
+class TLSMode(StrEnum):
+    """Supported secure SMTP transports. Clear-text SMTP is intentionally absent."""
+
+    STARTTLS = "starttls"
+    IMPLICIT = "implicit"
+
+
+@dataclass(frozen=True, slots=True)
+class ReportMetadata:
+    report_date: date | str
+    category: str
+    scoring_version: str
+    title: str | None = None
+
+    def __post_init__(self) -> None:
+        value = self.report_date
+        if isinstance(value, str):
+            try:
+                value = date.fromisoformat(value)
+            except ValueError as error:
+                raise ValueError("report_date must use YYYY-MM-DD") from error
+            object.__setattr__(self, "report_date", value)
+        elif not isinstance(value, date):
+            raise TypeError("report_date must be a date or ISO date string")
+        category = validate_header(self.category, name="category").strip()
+        version = validate_header(self.scoring_version, name="scoring_version").strip()
+        if len(category) > 100 or len(version) > 100:
+            raise ValueError(
+                "category and scoring_version must be at most 100 characters"
+            )
+        object.__setattr__(self, "category", category)
+        object.__setattr__(self, "scoring_version", version)
+        if self.title is not None:
+            title = validate_header(self.title, name="title").strip()
+            if len(title) > 200:
+                raise ValueError("title must be at most 200 characters")
+            object.__setattr__(self, "title", title)
+
+    @property
+    def display_title(self) -> str:
+        return self.title or f"{self.category} 論文評分摘要"
+
+
+@dataclass(frozen=True, slots=True)
+class RenderedReport:
+    plain_text: str
+    html: str
+    pdf: bytes
+    pdf_filename: str
+
+    def __post_init__(self) -> None:
+        validate_attachment_filename(self.pdf_filename)
+        if not self.pdf.startswith(b"%PDF"):
+            raise ValueError("pdf must contain a PDF document")
+
+
+@dataclass(frozen=True, slots=True)
+class Attachment:
+    filename: str
+    content: bytes
+    content_type: str = "application/octet-stream"
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, "filename", validate_attachment_filename(self.filename)
+        )
+        if not isinstance(self.content, bytes):
+            raise TypeError("attachment content must be bytes")
+        validate_mime_type(self.content_type)
+
+
+@dataclass(frozen=True, slots=True)
+class PreparedEmail:
+    message: EmailMessage
+    envelope_recipients: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.message, EmailMessage):
+            raise TypeError("message must be an EmailMessage")
+        if not self.envelope_recipients:
+            raise ValueError("at least one recipient is required")
+        validated = tuple(
+            validate_email_address(item) for item in self.envelope_recipients
+        )
+        object.__setattr__(self, "envelope_recipients", validated)
+
+
+@dataclass(frozen=True, slots=True)
+class SMTPSettings:
+    host: str = field(repr=False)
+    port: int
+    sender: str = field(repr=False)
+    username: str | None = field(default=None, repr=False)
+    password: str | None = field(default=None, repr=False)
+    tls_mode: TLSMode = TLSMode.STARTTLS
+    timeout_seconds: float = 30.0
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "host", validate_hostname(self.host))
+        object.__setattr__(self, "sender", validate_email_address(self.sender))
+        if not isinstance(self.port, int) or isinstance(self.port, bool):
+            raise TypeError("SMTP port must be an integer")
+        if not 1 <= self.port <= 65535:
+            raise ValueError("SMTP port must be between 1 and 65535")
+        if not isinstance(self.timeout_seconds, (int, float)):
+            raise TypeError("timeout_seconds must be numeric")
+        if not 0 < float(self.timeout_seconds) <= 300:
+            raise ValueError("timeout_seconds must be between 0 and 300")
+        try:
+            tls_mode = TLSMode(self.tls_mode)
+        except (TypeError, ValueError) as error:
+            raise ValueError("unsupported TLS mode") from error
+        object.__setattr__(self, "tls_mode", tls_mode)
+        if (self.username is None) != (self.password is None):
+            raise ValueError("username and password must be supplied together")
+        if self.username is not None:
+            username = validate_header(self.username, name="SMTP username").strip()
+            object.__setattr__(self, "username", username)