"""
LucidLink Python Library - Exception Classes
This module defines custom exception classes for LucidLink-specific errors
(daemon lifecycle, filespace operations, authentication, configuration).
Filesystem operations raise **standard Python exceptions** for seamless
interoperability with existing Python code:
- ``FileNotFoundError`` -- file or directory does not exist
- ``FileExistsError`` -- file or directory already exists
- ``NotADirectoryError`` -- expected a directory
- ``IsADirectoryError`` -- expected a file, got a directory
- ``PermissionError`` -- insufficient permissions or wrong credentials
- ``ValueError`` -- invalid path or argument
- ``TimeoutError`` -- operation timed out
- ``ConnectionError`` -- network/transport failure
- ``OSError`` -- general system-level error
This means standard ``try/except`` patterns work as expected::
try:
data = filespace.fs.read_file("/missing.txt")
except FileNotFoundError:
print("File does not exist")
except PermissionError:
print("No read access")
"""
[docs]
class LucidLinkError(Exception):
"""
Base class for all LucidLink-specific exceptions.
This is a base exception that can be caught to handle any LucidLink error.
Most specific errors inherit from Python builtins for better compatibility.
"""
pass
[docs]
class DaemonError(LucidLinkError):
"""
Raised when daemon operations fail.
Examples: daemon already running, daemon not started, daemon initialization failed
"""
pass
[docs]
class FilespaceError(LucidLinkError):
"""
Raised when filespace operations fail.
Examples: filespace not linked, filespace connection failed, invalid filespace ID
"""
pass
[docs]
class AuthenticationError(LucidLinkError):
"""
Raised when authentication fails.
Note: Most authentication errors are mapped to Python's PermissionError.
This is for authentication-specific context where needed.
"""
pass
[docs]
class ConfigurationError(LucidLinkError, ValueError):
"""
Raised when configuration is invalid.
Inherits from both LucidLinkError and ValueError for compatibility.
"""
pass
# Note: The C++ exception translator maps most exceptions to Python builtins:
#
# File operations:
# - FileExistsException → FileExistsError (builtin)
# - NotDirException → NotADirectoryError (builtin)
# - IsDirException → IsADirectoryError (builtin)
# - FileReadOnlyException → PermissionError (builtin)
# - InvalidPathException → ValueError (builtin)
#
# Authentication:
# - WrongCredentialsException → PermissionError (builtin)
# - AuthorizationException → PermissionError (builtin)
#
# Network/I/O:
# - TimeoutException → TimeoutError (builtin)
# - IoException → IOError (builtin)
# - TransportException → ConnectionError (builtin)
#
# Generic:
# - NotImplementedException → NotImplementedError (builtin)
# - SystemException → OSError (builtin)
# - InvalidArgumentException → ValueError (builtin)
# - Most others → RuntimeError (builtin)
#
# This approach provides better Python interoperability - catching OSError
# will catch filesystem errors, catching PermissionError will catch auth errors, etc.