Exceptions

clitic defines a custom exception hierarchy for clear error handling.

Exception hierarchy for clitic package.

This module defines all custom exceptions used throughout the clitic package. All exceptions inherit from CliticError for easy catching of package-specific errors.

exception clitic.exceptions.CliticError

Bases: Exception

Base exception for all clitic errors.

All custom exceptions in the clitic package inherit from this class, allowing users to catch all package-specific errors with a single except clause.

Example

try:

# clitic operations pass

except CliticError as e:

# Handle any clitic-specific error print(f”Clitic error: {e}”)

exception clitic.exceptions.PluginError(plugin_name: str, operation: str, message: str | None = None)

Bases: CliticError

Exception for plugin-related issues.

Raised when a plugin fails to load, initialize, or execute properly.

plugin_name

The name of the plugin that encountered the error.

operation

The operation that failed (e.g., ‘load’, ‘initialize’).

Example

raise PluginError(

plugin_name=”MarkdownRenderer”, operation=”initialize”, message=”Failed to parse configuration”

)

__init__(plugin_name: str, operation: str, message: str | None = None) → None

Initialize PluginError.

Parameters:

• plugin_name – Name of the plugin that encountered the error.

• operation – The operation that failed.

• message – Optional additional context for the error.

exception clitic.exceptions.ConfigurationError(setting: str, expected: str | None = None, message: str | None = None)

Bases: CliticError

Exception for configuration-related issues.

Raised when a configuration setting is invalid, missing, or malformed.

setting

The name of the configuration setting.

expected

Optional description of expected format or values.

Example

raise ConfigurationError(

setting=”theme”, expected=”one of: ‘dark’, ‘light’, ‘custom’”, message=”Invalid theme name ‘unknown’”

)

__init__(setting: str, expected: str | None = None, message: str | None = None) → None

Initialize ConfigurationError.

Parameters:

• setting – Name of the configuration setting with the issue.

• expected – Optional description of expected format or values.

• message – Optional additional context for the error.

exception clitic.exceptions.RenderError(content_type: str, renderer: str, message: str | None = None)

Bases: CliticError

Exception for content rendering failures.

Raised when a renderer fails to process or display content.

content_type

The type of content being rendered (e.g., ‘markdown’).

renderer

The name of the renderer that failed.

Example

raise RenderError(

content_type=”markdown”, renderer=”MarkdownRenderer”, message=”Failed to parse table syntax at line 42”

)

__init__(content_type: str, renderer: str, message: str | None = None) → None

Initialize RenderError.

Parameters:

• content_type – Type of content being rendered.

• renderer – Name of the renderer that failed.

• message – Optional additional context for the error.

exception clitic.exceptions.SessionError(session_id: str | None = None, operation: str = 'unknown', message: str | None = None)

Bases: CliticError

Exception for session-related issues.

Raised when a session operation fails (start, save, resume, delete).

session_id

The session ID involved in the error (if applicable).

operation

The operation that failed (e.g., ‘start’, ‘save’, ‘resume’).

Example

raise SessionError(

session_id=”abc-123”, operation=”resume”, message=”Session file not found”

)

__init__(session_id: str | None = None, operation: str = 'unknown', message: str | None = None) → None

Initialize SessionError.

Parameters:

• session_id – Optional session ID involved in the error.

• operation – The operation that failed.

• message – Optional additional context for the error.

exception clitic.exceptions.HistoryError(operation: str = 'unknown', message: str | None = None)

Bases: CliticError

Exception for history-related issues.

Raised when a history operation fails (load, save, clear).

operation

The operation that failed (e.g., ‘load’, ‘save’, ‘clear’).

Example

raise HistoryError(

operation=”save”, message=”Failed to write history entry”

)

__init__(operation: str = 'unknown', message: str | None = None) → None

Initialize HistoryError.

Parameters:

• operation – The operation that failed.

• message – Optional additional context for the error.

Exception Hierarchy

Exception
└── CliticError (base)
    ├── PluginError
    ├── ConfigurationError
    └── RenderError

Usage Examples

Catching All clitic Errors

from clitic.exceptions import CliticError

try:
    # clitic operations
    pass
except CliticError as e:
    print(f"clitic error: {e}")

Plugin Errors

from clitic.exceptions import PluginError

try:
    plugin.initialize()
except PluginError as e:
    print(f"Plugin {e.plugin_name} failed: {e}")

Configuration Errors

from clitic.exceptions import ConfigurationError

try:
    app.configure(settings)
except ConfigurationError as e:
    print(f"Invalid setting '{e.setting}': {e}")

Render Errors

from clitic.exceptions import RenderError

try:
    renderer.render(content)
except RenderError as e:
    print(f"Failed to render {e.content_type}: {e}")

Exception Details

CliticError

Base exception for all clitic-specific errors.

PluginError

Raised when a plugin fails to load, initialize, or execute.

• plugin_name: The plugin that encountered the error

• operation: The operation that failed

ConfigurationError

Raised when a configuration setting is invalid.

• setting: The setting name

• expected: Description of expected format

RenderError

Raised when content rendering fails.

• content_type: The type of content

• renderer: The renderer that failed