"""
PlotEZ Error Handling.
Custom exceptions for plotting operations.
"""
[docs]
class PlotError(Exception):
"""
Base class for exceptions related to plotting operations.
Notes
-----
This serves as the parent class for all plotting-related errors.
Specific exceptions related to plot configuration or data issues
should inherit from this class.
"""
pass
[docs]
class OrientationError(PlotError):
"""
Raised when an invalid or unexpected orientation is used in a plot.
Notes
-----
This error occurs when the orientation parameter for a plot is set
incorrectly or does not match the expected format.
"""
pass
# ---------------------------------------------------------------------------
# Data errors
# ---------------------------------------------------------------------------
[docs]
class DataError(PlotError):
"""
Base class for data-related plotting errors.
Notes
-----
Inherit from this class for any error that stems from invalid, malformed,
or incompatible input data arrays or files.
"""
pass
[docs]
class ShapeError(DataError):
"""
Raised when an array has an unexpected or incompatible shape.
Notes
-----
Typically raised when an error array intended for asymmetric error bars
does not satisfy the required ``(2, N)`` shape contract.
"""
pass
[docs]
class EmptyDataError(DataError):
"""
Raised when required primary x or y data is empty.
Notes
-----
At least one data point must be present in the primary x and y arrays
before a plot can be constructed.
"""
pass
[docs]
class ColumnCountError(DataError):
"""
Raised when a data file does not contain exactly two columns.
Notes
-----
``plot_two_column_file`` expects files with exactly one x-column and one
y-column. Any other column count triggers this error.
"""
pass
# ---------------------------------------------------------------------------
# Configuration errors
# ---------------------------------------------------------------------------
[docs]
class ConfigurationError(PlotError):
"""
Base class for plot configuration and parameter errors.
Notes
-----
Inherit from this class for errors that arise from incorrect or
conflicting plot configuration options rather than from the data itself.
"""
pass
[docs]
class AxisLabelError(ConfigurationError):
"""
Raised when the ``axis_labels`` sequence does not contain exactly three elements.
Notes
-----
Dual-axes functions require labels for three axes: primary x, primary y,
and the secondary axis (either x or y).
"""
pass
[docs]
class TwinXDataError(ConfigurationError):
"""
Raised when ``x2_data`` is supplied for a dual-Y-axis (``use_twin_x=True``) plot.
Notes
-----
A dual-Y-axis plot shares the x-axis between both datasets; providing a
separate ``x2_data`` is therefore contradictory and not permitted.
"""
pass
[docs]
class TwinYDataError(ConfigurationError):
"""
Raised when ``y2_data`` is supplied for a dual-X-axis (``use_twin_x=False``) plot.
Notes
-----
A dual-X-axis plot shares the y-axis between both datasets; providing a
separate ``y2_data`` is therefore contradictory and not permitted.
"""
pass
# ---------------------------------------------------------------------------
# Warnings
# ---------------------------------------------------------------------------
[docs]
class LabelConflictWarning(UserWarning):
"""
Issued when ``auto_label=True`` overrides user-provided labels.
Notes
-----
When ``auto_label`` is enabled it silently replaces any explicitly supplied
axis labels, data labels, or plot titles with auto-generated defaults.
This warning is raised to make that substitution visible to the caller.
Use ``warnings.filterwarnings`` to suppress or escalate it as needed.
"""
pass