processbehavior 0.2.0__py3-none-any.whl

processbehavior/exceptions.py

@@ -0,0 +1,216 @@
+"""
+Custom exceptions for processbehavior.
+
+This module provides a lightweight exception hierarchy for better error handling UX.
+Users can catch errors by category and get self-diagnostic error messages.
+
+Exception Hierarchy
+-------------------
+ProcessBehaviorError (base)
+└── ValidationError - Invalid input data, parameters, or configuration
+    ├── ColumnNotFoundError - Required column missing from DataFrame
+    ├── FactorNotFoundError - Invalid factor/variable name specified
+    ├── CalibrationNotSupportedError - Calibration not available on this chart path
+    └── ChartNotAvailableError - Chart type invalid or unavailable for this SDS
+
+Warnings
+--------
+ProcessBehaviorWarning (UserWarning) - Something was changed or assumed on the
+user's behalf (e.g. garbage tokens converted to NA during cleaning). Filterable
+with ``warnings.simplefilter('ignore', ProcessBehaviorWarning)``.
+
+Examples
+--------
+Catch by category:
+
+>>> try:
+...     result = study.execute(chart='Xbar')
+... except ChartNotAvailableError as e:
+...     print(f"Try one of: {study.valid_charts}")
+... except ValidationError as e:
+...     print(f"Check your data: {e}")
+
+Catch all library errors:
+
+>>> try:
+...     result = study.execute()
+... except ProcessBehaviorError as e:
+...     print(f"Analysis failed: {e}")
+"""
+
+from __future__ import annotations
+
+
+class ProcessBehaviorError(Exception):
+    """
+    Base exception for all processbehavior errors.
+
+    Catch this to handle any error from the library in a single except block.
+    """
+
+    pass
+
+
+class ValidationError(ProcessBehaviorError, ValueError):
+    """
+    Invalid input data, parameters, or configuration.
+
+    Raised when user input fails validation before analysis runs.
+    Check error message for specific issue and suggested fix.
+
+    Also subclasses the built-in ``ValueError`` so that callers (and the
+    library's own legacy code being migrated off raw ``ValueError``) that
+    ``except ValueError`` continue to work — the raw-``ValueError``→
+    ``ValidationError`` migration is therefore non-breaking.
+
+    Common causes:
+    - Invalid column names in formulate()
+    - Incompatible parameter combinations
+    - Data structure doesn't match requirements
+    """
+
+    pass
+
+
+class ColumnNotFoundError(ValidationError):
+    """
+    Required column missing from DataFrame.
+
+    Raised when a specified column (response, factor, time) doesn't exist
+    in the input DataFrame.
+
+    Attributes
+    ----------
+    column : str | None
+        The column name that was not found
+    available : list[str] | None
+        List of available column names
+
+    Suggested actions:
+    - Check `pb.cols` for available columns with auto-completion
+    - Verify column names match exactly (case-sensitive)
+    - Check `df.columns` to see all available columns
+    """
+
+    def __init__(self, message: str, column: str | None = None, available: list[str] | None = None):
+        super().__init__(message)
+        self.column = column
+        self.available = available
+
+
+class FactorNotFoundError(ValidationError):
+    """
+    Invalid factor/variable name specified.
+
+    Raised when a factor or variable name doesn't match any known factors
+    in the study. Common causes include typos and case mismatches.
+
+    Attributes
+    ----------
+    factor : str | None
+        The factor name that was not found
+    suggestion : str | None
+        A suggested correction (e.g., case-corrected name)
+    available : list[str] | None
+        List of valid factor/variable names
+
+    Suggested actions:
+    - Check spelling and case (names are case-sensitive)
+    - Use `study.factors` to see available factor names
+    """
+
+    def __init__(
+        self, message: str, factor: str | None = None, suggestion: str | None = None, available: list[str] | None = None
+    ):
+        super().__init__(message)
+        self.factor = factor
+        self.suggestion = suggestion
+        self.available = available
+
+
+class CalibrationNotSupportedError(ValidationError):
+    """A calibration was supplied on a chart path that cannot apply it.
+
+    Calibration is applied on global and grouped (single-chart) Xbar/S/X/mR paths.
+    Stratified paths (one chart per stratum) and phased X/mR are a documented
+    follow-up, so a calibration passed to one of those is refused rather than
+    silently ignored.
+
+    Ask *before* executing with :meth:`Study.supports_calibration`, which answers
+    the same question without raising — preferable to catching this, and far
+    preferable to re-deriving the rule client-side.
+
+    Subclasses :class:`ValidationError`, so existing ``except ValidationError``
+    handlers are unaffected.
+
+    Attributes
+    ----------
+    context : str | None
+        The unsupported path, e.g. ``'stratified Xbar'`` or ``'phased X/mR'``.
+
+    Examples
+    --------
+    >>> if study.supports_calibration(chart='X', by=['Machine']):
+    ...     result = study.execute(chart='X', by=['Machine'], calibration=cal)
+    ... else:
+    ...     result = study.execute(chart='X', by=['Machine'])
+    """
+
+    def __init__(self, message: str, context: str | None = None):
+        super().__init__(message)
+        self.context = context
+
+
+class ChartNotAvailableError(ValidationError):
+    """
+    Chart type invalid or unavailable for this SDS/data structure.
+
+    Raised when requesting a chart that cannot be produced given the
+    current data structure and Sampling Design State (SDS).
+
+    Attributes
+    ----------
+    chart : str | None
+        The chart type that was requested
+    available : list[str] | None
+        List of available chart types
+
+    Suggested actions:
+    - Check `study.valid_charts` for available chart types
+    - Use `study.why_not(chart_type)` for explanation
+    - Use `study.support` DataFrame for full availability matrix
+    """
+
+    def __init__(self, message: str, chart: str | None = None, available: list[str] | None = None):
+        super().__init__(message)
+        self.chart = chart
+        self.available = available
+
+
+class ProcessBehaviorWarning(UserWarning):
+    """
+    Something was changed or assumed on your behalf.
+
+    Raised (as a warning, not an exception) when the library alters input
+    rather than rejecting it — most often during the automatic cleaning that
+    converts garbage tokens to NA when a DataFrame is loaded.
+
+    These were previously emitted through ``logging``, which the library never
+    configures a handler for, so they were invisible in most sessions and
+    could not be filtered programmatically. As warnings they show up by
+    default and obey the standard filters.
+
+    Examples
+    --------
+    Silence them:
+
+    >>> import warnings
+    >>> warnings.simplefilter('ignore', ProcessBehaviorWarning)
+
+    Turn them into errors (useful in a validated pipeline where silent
+    coercion is unacceptable):
+
+    >>> warnings.simplefilter('error', ProcessBehaviorWarning)
+    """
+
+    pass

processbehavior/exporters/__init__.py

@@ -0,0 +1,5 @@
+"""Exporters for analysis results."""
+
+from .excel_exporter import ExcelExporter
+
+__all__ = ['ExcelExporter']