"""
Exception types for PureSVG library.

This module defines the exception hierarchy for SVG parsing and rendering errors.
All exceptions inherit from SVGError base class for easy catching.
"""


class SVGError(Exception):
    """Base exception for all SVG-related errors."""

    pass


class SVGParseError(SVGError):
    """
    Exception raised when SVG parsing fails due to malformed XML or invalid structure.

    Attributes:
        message: Error description
        line: Line number where error occurred (if available)
        column: Column number where error occurred (if available)
        source: Source SVG content snippet (if available)
    """

    def __init__(
        self,
        message: str,
        line: int | None = None,
        column: int | None = None,
        source: str | None = None,
    ) -> None:
        self.message = message
        self.line = line
        self.column = column
        self.source = source

        # Build detailed error message
        error_parts = [message]
        if line is not None:
            location = f"line {line}"
            if column is not None:
                location += f", column {column}"
            error_parts.append(f"at {location}")
        if source:
            error_parts.append(f"near: {source}")

        super().__init__(" ".join(error_parts))


class UnsupportedFeatureError(SVGError):
    """
    Exception raised when encountering unsupported SVG features.

    This is raised for valid SVG features that are not yet implemented
    (e.g., gradients, filters, animations).

    Attributes:
        feature: Name of the unsupported feature
        element_id: ID of the element using the feature (if available)
        message: Optional additional context
    """

    def __init__(
        self, feature: str, element_id: str | None = None, message: str | None = None
    ) -> None:
        self.feature = feature
        self.element_id = element_id

        # Build descriptive error message
        error_parts = [f"Unsupported SVG feature: {feature}"]
        if element_id:
            error_parts.append(f"in element '{element_id}'")
        if message:
            error_parts.append(f"- {message}")

        super().__init__(" ".join(error_parts))
