oscura 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

oscura/reporting/export.py

@@ -0,0 +1,366 @@
+"""Multi-format report export for TraceKit.
+
+This module provides unified export interface for generating reports in
+multiple formats (HTML, PDF, DOCX, Markdown) from a single source.
+
+
+Example:
+    >>> from oscura.reporting.export import export_report
+    >>> export_report(report, "output", formats=["pdf", "html", "markdown"])
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from oscura.reporting.core import Report
+
+
+def export_report(
+    report: Report,
+    output_path: str | Path,
+    *,
+    formats: list[Literal["pdf", "html", "docx", "markdown"]] | None = None,
+    format_options: dict[str, Any] | None = None,
+) -> dict[str, Path]:
+    """Export report to multiple formats.
+
+    Args:
+        report: Report object to export.
+        output_path: Base output path (without extension).
+        formats: List of formats to generate (default: ["pdf", "html"]).
+        format_options: Format-specific options dictionary.
+
+    Returns:
+        Dictionary mapping format to output file path.
+
+    Raises:
+        ValueError: If unsupported format is specified.
+
+    Example:
+        >>> paths = export_report(
+        ...     report,
+        ...     "report",
+        ...     formats=["pdf", "html", "markdown"],
+        ...     format_options={
+        ...         "pdf": {"dpi": 300, "pdfa_compliance": True},
+        ...         "html": {"interactive": True, "dark_mode": True},
+        ...     }
+        ... )
+
+    References:
+        REPORT-010
+    """
+    if formats is None:
+        formats = ["pdf", "html"]
+
+    if format_options is None:
+        format_options = {}
+
+    output_path = Path(output_path)
+    generated_files = {}
+
+    for fmt in formats:
+        fmt_opts = format_options.get(fmt, {})
+
+        if fmt == "pdf":
+            file_path = _export_pdf(report, output_path, **fmt_opts)
+        elif fmt == "html":
+            file_path = _export_html(report, output_path, **fmt_opts)
+        elif fmt == "docx":
+            file_path = _export_docx(report, output_path, **fmt_opts)
+        elif fmt == "markdown":
+            file_path = _export_markdown(report, output_path, **fmt_opts)
+        else:
+            raise ValueError(f"Unsupported format: {fmt}")
+
+        generated_files[fmt] = file_path
+
+    return generated_files  # type: ignore[return-value]
+
+
+def _export_pdf(
+    report: Report,
+    output_path: Path,
+    **options: Any,
+) -> Path:
+    """Export report as PDF."""
+    from oscura.reporting.pdf import save_pdf_report
+
+    path = output_path.with_suffix(".pdf")
+    save_pdf_report(report, path, **options)
+    return path
+
+
+def _export_html(
+    report: Report,
+    output_path: Path,
+    **options: Any,
+) -> Path:
+    """Export report as HTML."""
+    from oscura.reporting.html import save_html_report
+
+    path = output_path.with_suffix(".html")
+    save_html_report(report, path, **options)
+    return path
+
+
+def _export_markdown(
+    report: Report,
+    output_path: Path,
+    **options: Any,
+) -> Path:
+    """Export report as Markdown."""
+    path = output_path.with_suffix(".md")
+    markdown_content = report.to_markdown()
+    path.write_text(markdown_content, encoding="utf-8")
+    return path
+
+
+def _export_docx(
+    report: Report,
+    output_path: Path,
+    **options: Any,
+) -> Path:
+    """Export report as DOCX.
+
+    Requires python-docx library.
+
+    Args:
+        report: Report object to export.
+        output_path: Base output path (extension will be changed to .docx).
+        **options: Format-specific options (currently unused).
+
+    Returns:
+        Path to the created DOCX file.
+
+    Raises:
+        ImportError: If python-docx library is not installed.
+
+    References:
+        REPORT-019
+    """
+    try:
+        from docx import Document  # type: ignore[import-not-found]
+        from docx.enum.text import (  # type: ignore[import-not-found]
+            WD_ALIGN_PARAGRAPH,  # type: ignore[import-not-found]
+        )
+        from docx.shared import (  # noqa: F401  # type: ignore[import-not-found]
+            Inches,
+            Pt,
+            RGBColor,
+        )
+    except ImportError:
+        raise ImportError(  # noqa: B904
+            "python-docx is required for DOCX export. Install with: pip install python-docx"
+        )
+
+    path = output_path.with_suffix(".docx")
+    doc = Document()
+
+    # Add title
+    title = doc.add_heading(report.config.title, level=0)
+    title.alignment = WD_ALIGN_PARAGRAPH.CENTER
+
+    # Add metadata
+    if report.config.author:
+        doc.add_paragraph(f"Author: {report.config.author}")
+    doc.add_paragraph(f"Date: {report.config.created.strftime('%Y-%m-%d %H:%M')}")
+    doc.add_paragraph()  # Blank line
+
+    # Add sections
+    for section in report.sections:
+        if not section.visible:
+            continue
+
+        # Section heading
+        doc.add_heading(section.title, level=section.level)
+
+        # Section content
+        if isinstance(section.content, str):
+            doc.add_paragraph(section.content)
+
+        elif isinstance(section.content, list):
+            for item in section.content:
+                if isinstance(item, dict):
+                    if item.get("type") == "table":
+                        _add_table_to_docx(doc, item)
+                    elif item.get("type") == "figure":
+                        # Placeholder for figures
+                        doc.add_paragraph(f"[Figure: {item.get('caption', 'N/A')}]")
+                else:
+                    doc.add_paragraph(str(item))
+
+        # Subsections
+        for subsec in section.subsections:
+            if not subsec.visible:
+                continue
+            doc.add_heading(subsec.title, level=subsec.level)
+            if isinstance(subsec.content, str):
+                doc.add_paragraph(subsec.content)
+
+    # Save document
+    doc.save(str(path))
+    return path
+
+
+def _add_table_to_docx(doc: Any, table_dict: dict[str, Any]) -> None:
+    """Add table to DOCX document."""
+    headers = table_dict.get("headers", [])
+    data = table_dict.get("data", [])
+
+    if not headers and not data:
+        return
+
+    # Create table
+    num_cols = len(headers) if headers else len(data[0]) if data else 0
+    num_rows = len(data) + (1 if headers else 0)
+
+    if num_rows == 0 or num_cols == 0:
+        return
+
+    table = doc.add_table(rows=num_rows, cols=num_cols)
+    table.style = "Light Grid Accent 1"
+
+    # Add headers
+    if headers:
+        header_cells = table.rows[0].cells
+        for i, header in enumerate(headers):
+            header_cells[i].text = str(header)
+            # Make header bold
+            for paragraph in header_cells[i].paragraphs:
+                for run in paragraph.runs:
+                    run.bold = True
+
+    # Add data
+    start_row = 1 if headers else 0
+    for i, row in enumerate(data):
+        row_cells = table.rows[start_row + i].cells
+        for j, cell in enumerate(row):
+            row_cells[j].text = str(cell)
+
+    # Add caption
+    if table_dict.get("caption"):
+        doc.add_paragraph(table_dict["caption"], style="Caption")
+
+
+def export_multiple_reports(
+    reports: dict[str, Report],
+    output_dir: str | Path,
+    *,
+    format: Literal["pdf", "html", "docx", "markdown"] = "pdf",
+    **options: Any,
+) -> dict[str, Path]:
+    """Export multiple reports to a directory.
+
+    Args:
+        reports: Dictionary mapping name to Report object.
+        output_dir: Output directory path.
+        format: Export format for all reports.
+        **options: Format-specific options.
+
+    Returns:
+        Dictionary mapping report name to output path.
+
+    References:
+        REPORT-010
+    """
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    generated_files = {}
+
+    for name, report in reports.items():
+        output_path = output_dir / name
+        files = export_report(
+            report, output_path, formats=[format], format_options={format: options}
+        )
+        generated_files[name] = files[format]
+
+    return generated_files
+
+
+def batch_export_formats(
+    report: Report,
+    output_dir: str | Path,
+    *,
+    formats: list[str] | None = None,
+    **options: Any,
+) -> dict[str, Path]:
+    """Export single report to multiple formats in a directory.
+
+    Args:
+        report: Report to export.
+        output_dir: Output directory.
+        formats: List of formats (default: all supported).
+        **options: Common options for all formats.
+
+    Returns:
+        Dictionary mapping format to output path.
+
+    References:
+        REPORT-010
+    """
+    if formats is None:
+        formats = ["pdf", "html", "docx", "markdown"]
+
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    base_name = report.config.title.lower().replace(" ", "_")
+    output_path = output_dir / base_name
+
+    return export_report(report, output_path, formats=formats, format_options=options)  # type: ignore[arg-type]
+
+
+def create_archive(
+    files: dict[str, Path],
+    archive_path: str | Path,
+    *,
+    format: Literal["zip", "tar", "tar.gz"] = "zip",
+) -> Path:
+    """Create archive of exported report files.
+
+    Args:
+        files: Dictionary of files to archive.
+        archive_path: Output archive path.
+        format: Archive format (zip, tar, tar.gz).
+
+    Returns:
+        Path to created archive.
+
+    Raises:
+        ValueError: If unsupported archive format is specified.
+
+    References:
+        REPORT-010
+    """
+    from pathlib import Path
+
+    archive_path = Path(archive_path)
+
+    if format == "zip":
+        import zipfile
+
+        with zipfile.ZipFile(archive_path.with_suffix(".zip"), "w") as zipf:
+            for path in files.values():
+                zipf.write(path, arcname=path.name)
+
+        return archive_path.with_suffix(".zip")
+
+    elif format in ("tar", "tar.gz"):
+        import tarfile
+
+        mode = "w:gz" if format == "tar.gz" else "w"
+        suffix = ".tar.gz" if format == "tar.gz" else ".tar"
+
+        with tarfile.open(archive_path.with_suffix(suffix), mode) as tar:  # type: ignore[call-overload]
+            for path in files.values():
+                tar.add(path, arcname=path.name)
+
+        return archive_path.with_suffix(suffix)
+
+    else:
+        raise ValueError(f"Unsupported archive format: {format}")

oscura/reporting/formatting/__init__.py

@@ -0,0 +1,129 @@
+"""Formatting utilities for reports."""
+
+from oscura.reporting.formatting.emphasis import (
+    VisualEmphasis,
+    format_callout_box,
+    format_severity,
+)
+from oscura.reporting.formatting.numbers import (
+    NumberFormatter,
+    format_percentage,
+    format_range,
+    format_value,
+    format_with_context,
+    format_with_locale,
+    format_with_units,
+)
+from oscura.reporting.formatting.standards import (
+    ColorScheme,
+    FormatStandards,
+    Severity,
+    apply_formatting_standards,
+)
+
+
+def format_margin(
+    value: float,
+    limit: float,
+    unit: str = "",
+    limit_type: str = "upper",
+) -> str:
+    """Format a margin value with pass/fail indication.
+
+    Calculates the margin between a measured value and its specification limit,
+    then categorizes it as good (>20%), ok (10-20%), marginal (0-10%), or violation.
+
+    Args:
+        value: Measured value.
+        limit: Limit value (specification).
+        unit: Unit of measurement.
+        limit_type: Type of limit ("upper" or "lower").
+
+    Returns:
+        Formatted margin string with status indication.
+
+    Examples:
+        >>> format_margin(70, 100, limit_type="upper")
+        '30.0% margin (good)'
+        >>> format_margin(95, 100, limit_type="upper")
+        '5.0% margin (marginal)'
+    """
+    # Calculate margin percentage
+    if limit != 0:
+        if limit_type == "upper":
+            margin = limit - value
+            margin_pct = (margin / limit) * 100
+            is_passing = value < limit
+        else:  # lower
+            margin = value - limit
+            margin_pct = (margin / limit) * 100
+            is_passing = value > limit
+    else:
+        margin_pct = 0
+        is_passing = False
+
+    # Determine status based on margin percentage
+    if not is_passing:
+        status = "violation"
+    elif margin_pct >= 20:
+        status = "good"
+    elif margin_pct >= 10:
+        status = "ok"
+    else:
+        status = "marginal"
+
+    return f"{abs(margin_pct):.1f}% margin ({status})"
+
+
+def format_pass_fail(passed: bool, message: str = "", with_symbol: bool = True) -> str:
+    """Format pass/fail status.
+
+    Args:
+        passed: Whether the test passed.
+        message: Optional message to append.
+        with_symbol: Whether to include Unicode symbol (checkmark/cross).
+
+    Returns:
+        Formatted pass/fail string.
+
+    Examples:
+        >>> format_pass_fail(True)
+        'PASS ✓'
+        >>> format_pass_fail(False, with_symbol=False)
+        'FAIL'
+    """
+    status = "PASS" if passed else "FAIL"
+
+    if with_symbol:
+        symbol = "\u2713" if passed else "\u2717"
+        result = f"{status} {symbol}"
+    else:
+        result = status
+
+    if message:
+        return f"{result}: {message}"
+    return result
+
+
+__all__ = [
+    "ColorScheme",
+    # Standards
+    "FormatStandards",
+    # Numbers
+    "NumberFormatter",
+    "Severity",
+    # Emphasis
+    "VisualEmphasis",
+    "apply_formatting_standards",
+    "format_callout_box",
+    # Convenience
+    "format_margin",
+    "format_pass_fail",
+    "format_percentage",
+    "format_range",
+    "format_severity",
+    "format_value",
+    "format_with_context",
+    "format_with_locale",
+    "format_with_units",
+]

oscura/reporting/formatting/emphasis.py

@@ -0,0 +1,81 @@
+"""Text emphasis formatting utilities.
+
+Simple text formatting for terminal output.
+"""
+
+from enum import Enum
+
+
+class VisualEmphasis(Enum):
+    """Visual emphasis levels."""
+
+    NONE = "none"
+    SUBTLE = "subtle"
+    MODERATE = "moderate"
+    STRONG = "strong"
+    CRITICAL = "critical"
+
+
+def bold(text: str) -> str:
+    """Make text bold (terminal)."""
+    return f"\033[1m{text}\033[0m"
+
+
+def italic(text: str) -> str:
+    """Make text italic (terminal)."""
+    return f"\033[3m{text}\033[0m"
+
+
+def underline(text: str) -> str:
+    """Underline text (terminal)."""
+    return f"\033[4m{text}\033[0m"
+
+
+def color(text: str, color_code: str) -> str:
+    """Color text (terminal)."""
+    colors = {
+        "red": "31",
+        "green": "32",
+        "yellow": "33",
+        "blue": "34",
+        "magenta": "35",
+        "cyan": "36",
+        "white": "37",
+    }
+    code = colors.get(color_code.lower(), "37")
+    return f"\033[{code}m{text}\033[0m"
+
+
+def format_severity(text: str, severity: str) -> str:
+    """Format text based on severity level."""
+    severity_colors = {
+        "critical": "red",
+        "error": "red",
+        "warning": "yellow",
+        "info": "blue",
+        "success": "green",
+    }
+    return color(text, severity_colors.get(severity.lower(), "white"))
+
+
+def format_callout_box(title: str, content: str, severity: str = "info") -> str:
+    """Format a callout box."""
+    lines = [
+        "=" * 60,
+        format_severity(f" {title.upper()} ", severity),
+        "-" * 60,
+        content,
+        "=" * 60,
+    ]
+    return "\n".join(lines)
+
+
+__all__ = [
+    "VisualEmphasis",
+    "bold",
+    "color",
+    "format_callout_box",
+    "format_severity",
+    "italic",
+    "underline",
+]