"""
LucidLink Python Library - Exception Classes
This module defines custom exception classes for LucidLink-specific errors
(client 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
.. deprecated::
Used by the deprecated :class:`Daemon` class. New code should use
:class:`Client` and catch :class:`ClientError`.
"""
pass
[docs]
class ClientError(LucidLinkError):
"""
Raised when :class:`Client` lifecycle operations fail.
Examples: client initialization failed, runtime startup failed, teardown
error. Authentication failures use :class:`AuthenticationError` instead.
"""
pass
[docs]
class FilespaceError(LucidLinkError):
"""
Raised when filespace operations fail.
Examples: filespace not linked, filespace connection failed, invalid filespace ID
"""
pass
[docs]
class FilespaceAlreadyLinkedError(FilespaceError):
"""
Raised when linking a filespace that is already linked under a different
identifier (e.g. linked by id earlier, now requested by name).
``link_filespace()`` catches this internally to return the existing live
``Filespace`` — its idempotency contract — so callers rarely see it. It
surfaces only if the existing link can no longer be resolved.
The runtime classifies this case by exception type (the
``AlreadyLinkedException`` FFI category) and carries the canonical id as a
structured field, surfaced here as the ``filespace_id`` attribute — it is
never parsed out of the human message. A reworded message therefore changes
nothing, and the error can never be mistaken for an unrelated failure such
as a network drop.
"""
def __init__(self, *args, filespace_id: str = ""):
super().__init__(*args)
self.filespace_id = filespace_id
[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.