oscura 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

oscura/reporting/standards.py

@@ -87,9 +87,22 @@ class FormatStandards:
         References:
             REPORT-001: Professional Formatting Standards
         """
+        root_vars = self._generate_css_variables()
+        base_styles = self._generate_css_base_styles()
+        component_styles = self._generate_css_component_styles()
+        print_styles = self._generate_css_print_styles()
+
         return f"""
 /* Oscura Professional Report Styles - REPORT-001 */
-:root {{
+{root_vars}
+{base_styles}
+{component_styles}
+{print_styles}
+"""
+
+    def _generate_css_variables(self) -> str:
+        """Generate CSS custom properties."""
+        return f""":root {{
     --heading-font: {self.heading_font};
     --body-font: {self.body_font};
     --code-font: {self.code_font};
@@ -109,158 +122,186 @@ class FormatStandards:
     --color-critical-bg: #ffebee;
     --color-warning-bg: #fff3e0;
     --color-info-bg: #e3f2fd;
-}}
+}}"""
 
-body {{
+    def _generate_css_base_styles(self) -> str:
+        """Generate base body and typography CSS."""
+        return """
+body {
     font-family: var(--body-font);
     font-size: var(--body-size);
     line-height: var(--line-spacing);
     margin: var(--margin);
     max-width: 8.5in;
     color: #333;
-}}
+}
 
-h1, h2, h3, h4 {{
+h1, h2, h3, h4 {
     font-family: var(--heading-font);
     line-height: 1.2;
     margin-top: 1.5em;
     margin-bottom: 0.5em;
-}}
+}
 
-h1 {{ font-size: var(--h1-size); }}
-h2 {{ font-size: var(--h2-size); }}
-h3 {{ font-size: var(--h3-size); }}
+h1 { font-size: var(--h1-size); }
+h2 { font-size: var(--h2-size); }
+h3 { font-size: var(--h3-size); }
 
-.report-title {{
+.report-title {
     font-size: var(--title-size);
     text-align: center;
     margin-bottom: 2em;
-}}
+}
 
-code, pre {{
+code, pre {
     font-family: var(--code-font);
     font-size: 0.9em;
     background-color: #f5f5f5;
     padding: 2px 4px;
     border-radius: 3px;
-}}
+}"""
+
+    def _generate_css_component_styles(self) -> str:
+        """Generate component CSS (tables, severity, etc)."""
+        tables = self._generate_css_tables()
+        indicators = self._generate_css_indicators()
+        callouts = self._generate_css_callouts()
+        summary = self._generate_css_executive_summary()
+        watermark = self._generate_css_watermark()
 
+        return f"{tables}\n{indicators}\n{callouts}\n{summary}\n{watermark}"
+
+    def _generate_css_tables(self) -> str:
+        """Generate table CSS."""
+        return """
 /* Table styles */
-table {{
+table {
     border-collapse: collapse;
     width: 100%;
     margin: 1em 0;
-}}
+}
 
-th, td {{
+th, td {
     border: 1px solid #ddd;
     padding: 8px;
     text-align: left;
-}}
+}
 
-th {{
+th {
     background-color: #f2f2f2;
     font-weight: bold;
-}}
+}
 
-tr:nth-child(even) {{
+tr:nth-child(even) {
     background-color: #f9f9f9;
-}}
+}"""
 
+    def _generate_css_indicators(self) -> str:
+        """Generate pass/fail and severity indicator CSS."""
+        return """
 /* Pass/Fail indicators (REPORT-002) */
-.pass {{
+.pass {
     color: var(--color-pass);
-}}
+}
 
-.fail {{
+.fail {
     color: var(--color-fail);
-}}
+}
 
-.warning {{
+.warning {
     color: var(--color-warning);
-}}
+}
 
 /* Severity indicators (REPORT-002) */
-.severity-critical {{
+.severity-critical {
     background-color: var(--color-critical-bg);
     border-left: 4px solid var(--color-fail);
     padding: 10px;
     margin: 10px 0;
-}}
+}
 
-.severity-warning {{
+.severity-warning {
     background-color: var(--color-warning-bg);
     border-left: 4px solid var(--color-warning);
     padding: 10px;
     margin: 10px 0;
-}}
+}
 
-.severity-info {{
+.severity-info {
     background-color: var(--color-info-bg);
     border-left: 4px solid var(--color-info);
     padding: 10px;
     margin: 10px 0;
-}}
+}"""
 
+    def _generate_css_callouts(self) -> str:
+        """Generate callout box CSS."""
+        return """
 /* Callout box (REPORT-002) */
-.callout {{
+.callout {
     border: 1px solid #ddd;
     border-radius: 4px;
     padding: 15px;
     margin: 15px 0;
     background-color: #fafafa;
-}}
+}
 
-.callout.key-finding {{
+.callout.key-finding {
     border-color: var(--color-info);
     background-color: var(--color-info-bg);
-}}
+}
 
 /* Highlighting for out-of-spec values */
-.out-of-spec {{
+.out-of-spec {
     background-color: rgba(255, 235, 59, 0.15);
     padding: 2px 4px;
     border-radius: 2px;
-}}
+}"""
 
+    def _generate_css_executive_summary(self) -> str:
+        """Generate executive summary CSS."""
+        return """
 /* Executive summary styles (REPORT-004) */
-.executive-summary {{
+.executive-summary {
     background-color: #f5f5f5;
     padding: 20px;
     margin: 20px 0;
     border-radius: 4px;
-}}
+}
 
-.executive-summary h2 {{
+.executive-summary h2 {
     margin-top: 0;
-}}
+}
 
-.key-findings {{
+.key-findings {
     list-style-type: none;
     padding-left: 0;
-}}
+}
 
-.key-findings li {{
+.key-findings li {
     padding: 5px 0;
     padding-left: 25px;
     position: relative;
-}}
+}
 
-.key-findings li::before {{
+.key-findings li::before {
     content: "";
     position: absolute;
     left: 0;
     top: 8px;
     width: 16px;
     height: 16px;
-}}
+}
 
-.key-findings li.critical::before {{
+.key-findings li.critical::before {
     content: "!";
     color: var(--color-fail);
     font-weight: bold;
-}}
+}"""
 
+    def _generate_css_watermark(self) -> str:
+        """Generate watermark CSS."""
+        return f"""
 /* Watermark */
 .watermark {{
     position: fixed;
@@ -271,21 +312,23 @@ tr:nth-child(even) {{
     color: rgba(0, 0, 0, {self.watermark_opacity});
     pointer-events: none;
     z-index: 1000;
-}}
+}}"""
 
+    def _generate_css_print_styles(self) -> str:
+        """Generate print media query CSS."""
+        return """
 /* Print styles */
-@media print {{
-    body {{
+@media print {
+    body {
         margin: 0;
-    }}
-    .page-break {{
+    }
+    .page-break {
         page-break-before: always;
-    }}
-    .no-print {{
+    }
+    .no-print {
         display: none;
-    }}
-}}
-"""
+    }
+}"""
 
 
 @dataclass

oscura/reporting/summary_generator.py

@@ -215,57 +215,16 @@ def _format_frequency(freq_hz: float) -> str:
         return f"{freq_hz:.1f} Hz"
 
 
-def generate_summary(
+def _build_findings(
+    signal_type: str,
+    type_confidence: float,
+    quality_level: str,
+    quality_issues: list[str],
     trace: WaveformTrace,
-    *,
-    context: dict[str, Any] | None = None,
-    detail_level: str = "summary",
-    max_words: int = 200,
-    include_sections: list[str] | None = None,
-) -> Summary:
-    """Generate natural language summary of signal analysis.
-
-    Creates a plain-English description of the signal and analysis results,
-    avoiding technical jargon and explaining findings in accessible terms.
-
-    Args:
-        trace: Waveform to summarize.
-        context: Optional analysis context (characterization, anomalies, etc.).
-        detail_level: Summary detail level ("summary", "intermediate", "expert").
-        max_words: Maximum word count for summary text.
-        include_sections: Sections to include (default: all).
-
-    Returns:
-        Summary object with natural language description.
-
-    Example:
-        >>> trace = load("uart_signal.wfm")
-        >>> summary = generate_summary(trace)
-        >>> print(summary.text)
-        This is a digital signal with two voltage levels...
-
-    References:
-        DISC-003: Natural Language Summaries
-    """
-    context = context or {}
-    include_sections = include_sections or ["overview", "findings", "recommendations"]
-
-    # Characterize signal type
-    signal_type, type_confidence = _characterize_signal_type(trace)
-
-    # Assess quality
-    quality_level, quality_issues = _assess_quality(trace)
-
-    # Build overview
-    sample_rate = trace.metadata.sample_rate
-    duration_ms = len(trace.data) / sample_rate * 1000
-
-    overview = f"This is a {signal_type} signal captured at {_format_frequency(sample_rate)} sample rate for {duration_ms:.1f} milliseconds."
-
-    # Build findings
+) -> list[Finding]:
+    """Build findings list from analysis results."""
     findings = []
 
-    # Signal type finding
     findings.append(
         Finding(
             title="Signal Type",
@@ -275,7 +234,6 @@ def generate_summary(
         )
     )
 
-    # Quality finding
     quality_desc = f"Signal quality is {quality_level}"
     if quality_issues:
         quality_desc += f" with {len(quality_issues)} issue(s) noted"
@@ -289,7 +247,6 @@ def generate_summary(
         )
     )
 
-    # Voltage levels
     v_min = float(np.min(trace.data))
     v_max = float(np.max(trace.data))
     v_range = v_max - v_min
@@ -303,7 +260,11 @@ def generate_summary(
         )
     )
 
-    # Build recommendations
+    return findings
+
+
+def _build_recommendations(signal_type: str, quality_issues: list[str]) -> list[str]:
+    """Build recommendations from analysis results."""
     recommendations = []
 
     if "very short" in str(quality_issues).lower():
@@ -322,14 +283,24 @@ def generate_summary(
     elif signal_type in ["analog", "periodic analog"] and not recommendations:
         recommendations.append("Consider spectral analysis to identify frequency components")
 
-    # Build complete summary text
+    return recommendations
+
+
+def _build_summary_text(
+    overview: str,
+    findings: list[Finding],
+    recommendations: list[str],
+    include_sections: list[str],
+    max_words: int,
+) -> str:
+    """Build complete summary text from components."""
     summary_parts = []
 
     if "overview" in include_sections:
         summary_parts.append(overview)
 
     if "findings" in include_sections and findings:
-        key_findings = findings[:3]  # Top 3 findings
+        key_findings = findings[:3]
         findings_text = " ".join(
             [f"{finding.title}: {finding.description}." for finding in key_findings]
         )
@@ -341,13 +312,62 @@ def generate_summary(
 
     full_text = " ".join(summary_parts)
 
-    # Truncate to max_words if needed
     words = full_text.split()
     if len(words) > max_words:
         words = words[:max_words]
         full_text = " ".join(words) + "..."
 
-    # Calculate statistics
+    return full_text
+
+
+def generate_summary(
+    trace: WaveformTrace,
+    *,
+    context: dict[str, Any] | None = None,
+    detail_level: str = "summary",
+    max_words: int = 200,
+    include_sections: list[str] | None = None,
+) -> Summary:
+    """Generate natural language summary of signal analysis.
+
+    Creates a plain-English description of the signal and analysis results,
+    avoiding technical jargon and explaining findings in accessible terms.
+
+    Args:
+        trace: Waveform to summarize.
+        context: Optional analysis context (characterization, anomalies, etc.).
+        detail_level: Summary detail level ("summary", "intermediate", "expert").
+        max_words: Maximum word count for summary text.
+        include_sections: Sections to include (default: all).
+
+    Returns:
+        Summary object with natural language description.
+
+    Example:
+        >>> trace = load("uart_signal.wfm")
+        >>> summary = generate_summary(trace)
+        >>> print(summary.text)
+        This is a digital signal with two voltage levels...
+
+    References:
+        DISC-003: Natural Language Summaries
+    """
+    context = context or {}
+    include_sections = include_sections or ["overview", "findings", "recommendations"]
+
+    signal_type, type_confidence = _characterize_signal_type(trace)
+    quality_level, quality_issues = _assess_quality(trace)
+
+    sample_rate = trace.metadata.sample_rate
+    duration_ms = len(trace.data) / sample_rate * 1000
+    overview = f"This is a {signal_type} signal captured at {_format_frequency(sample_rate)} sample rate for {duration_ms:.1f} milliseconds."
+
+    findings = _build_findings(signal_type, type_confidence, quality_level, quality_issues, trace)
+    recommendations = _build_recommendations(signal_type, quality_issues)
+
+    full_text = _build_summary_text(
+        overview, findings, recommendations, include_sections, max_words
+    )
     word_count = len(full_text.split())
     grade_level = _estimate_grade_level(full_text)
 

oscura/reporting/tables.py

@@ -21,6 +21,138 @@ if TYPE_CHECKING:
     from numpy.typing import NDArray
 
 
+def _build_table_headers(show_spec: bool, show_margin: bool, show_status: bool) -> list[str]:
+    """Build table headers based on display options.
+
+    Args:
+        show_spec: Include specification column.
+        show_margin: Include margin column.
+        show_status: Include status column.
+
+    Returns:
+        List of header strings.
+    """
+    headers = ["Parameter", "Value"]
+    if show_spec:
+        headers.append("Specification")
+    if show_margin:
+        headers.append("Margin")
+    if show_status:
+        headers.append("Status")
+    return headers
+
+
+def _format_value_cell(value: Any, unit: str, formatter: NumberFormatter) -> str:
+    """Format measurement value cell.
+
+    Args:
+        value: Measurement value.
+        unit: Unit string.
+        formatter: Number formatter instance.
+
+    Returns:
+        Formatted value string.
+    """
+    if value is None:
+        return "N/A"
+    return formatter.format(value, unit)
+
+
+def _format_spec_cell(spec: Any, spec_type: str, unit: str, formatter: NumberFormatter) -> str:
+    """Format specification cell with comparison operator.
+
+    Args:
+        spec: Specification value.
+        spec_type: Spec type ("max", "min", or "exact").
+        unit: Unit string.
+        formatter: Number formatter instance.
+
+    Returns:
+        Formatted specification string.
+    """
+    if spec is None:
+        return "-"
+
+    prefix = "<" if spec_type == "max" else ">" if spec_type == "min" else "="
+    return f"{prefix}{formatter.format(spec, unit)}"
+
+
+def _calculate_margin(value: float, spec: float, spec_type: str) -> str:
+    """Calculate margin percentage between value and spec.
+
+    Args:
+        value: Measured value.
+        spec: Specification limit.
+        spec_type: Specification type ("max" or "min").
+
+    Returns:
+        Formatted margin percentage string.
+    """
+    if spec == 0:
+        return "-"
+
+    if spec_type == "max":
+        margin = (spec - value) / spec * 100
+    else:
+        margin = (value - spec) / spec * 100
+
+    return f"{margin:.1f}%"
+
+
+def _build_measurement_row(
+    name: str,
+    meas: dict[str, Any],
+    formatter: NumberFormatter,
+    show_spec: bool,
+    show_margin: bool,
+    show_status: bool,
+) -> list[str]:
+    """Build single measurement table row.
+
+    Args:
+        name: Measurement parameter name.
+        meas: Measurement data dictionary.
+        formatter: Number formatter instance.
+        show_spec: Include specification column.
+        show_margin: Include margin column.
+        show_status: Include status column.
+
+    Returns:
+        List of cell values for table row.
+    """
+    row = [name]
+    value = meas.get("value")
+    unit = meas.get("unit", "")
+
+    # Value column
+    row.append(_format_value_cell(value, unit, formatter))
+
+    # Specification column
+    if show_spec:
+        spec = meas.get("spec")
+        spec_type = meas.get("spec_type", "max")
+        row.append(_format_spec_cell(spec, spec_type, unit, formatter))
+
+    # Margin column
+    if show_margin:
+        spec = meas.get("spec")
+        if value is not None and spec is not None:
+            spec_type = meas.get("spec_type", "max")
+            row.append(_calculate_margin(value, spec, spec_type))
+        else:
+            row.append("-")
+
+    # Status column
+    if show_status:
+        passed = meas.get("passed", True)
+        if value is None:
+            row.append("N/A")
+        else:
+            row.append("✓ PASS" if passed else "✗ FAIL")
+
+    return row
+
+
 def create_measurement_table(
     measurements: dict[str, Any],
     *,
@@ -56,62 +188,14 @@ def create_measurement_table(
     References:
         REPORT-004, REPORT-006
     """
-    # Build table headers
-    headers = ["Parameter", "Value"]
-    if show_spec:
-        headers.append("Specification")
-    if show_margin:
-        headers.append("Margin")
-    if show_status:
-        headers.append("Status")
-
-    # Build table rows
-    rows = []
+    headers = _build_table_headers(show_spec, show_margin, show_status)
     formatter = NumberFormatter(sig_figs=3)
 
-    for name, meas in measurements.items():
-        row = [name]
-
-        # Value
-        value = meas.get("value")
-        unit = meas.get("unit", "")
-        if value is not None:
-            row.append(formatter.format(value, unit))
-        else:
-            row.append("N/A")
-
-        # Specification
-        if show_spec:
-            spec = meas.get("spec")
-            spec_type = meas.get("spec_type", "max")
-            if spec is not None:
-                prefix = "<" if spec_type == "max" else ">" if spec_type == "min" else "="
-                row.append(f"{prefix}{formatter.format(spec, unit)}")
-            else:
-                row.append("-")
-
-        # Margin
-        if show_margin:
-            spec = meas.get("spec")
-            if value is not None and spec is not None and spec != 0:
-                spec_type = meas.get("spec_type", "max")
-                if spec_type == "max":
-                    margin = (spec - value) / spec * 100
-                else:
-                    margin = (value - spec) / spec * 100
-                row.append(f"{margin:.1f}%")
-            else:
-                row.append("-")
-
-        # Status
-        if show_status:
-            passed = meas.get("passed", True)
-            if value is None:
-                row.append("N/A")
-            else:
-                row.append("✓ PASS" if passed else "✗ FAIL")
-
-        rows.append(row)
+    # Build rows
+    rows = [
+        _build_measurement_row(name, meas, formatter, show_spec, show_margin, show_status)
+        for name, meas in measurements.items()
+    ]
 
     # Sort if requested
     if sort_by and sort_by in headers: