Coverage for src/prosemark/exceptions.py: 100%
18 statements
« prev ^ index » next coverage.py v7.8.0, created at 2025-09-24 18:08 +0000
1"""Custom exceptions for prosemark.
3This module defines all domain-specific exceptions used throughout the prosemark
4application. All exceptions inherit from ProsemarkError and follow these conventions:
5- No custom __init__ methods
6- Extra context passed as additional arguments
7- No variable interpolation in error messages
8"""
11class ProsemarkError(Exception):
12 """Base exception for all prosemark errors.
14 All domain exceptions should inherit from this class to provide
15 a consistent exception hierarchy for error handling.
16 """
19class BinderIntegrityError(ProsemarkError):
20 """Error raised when binder tree integrity is violated.
22 This exception indicates violations of tree invariants such as:
23 - Duplicate nodes in the tree
24 - Invalid parent-child relationships
25 - Circular references
26 - Orphaned nodes
28 Args:
29 message: A descriptive error message without variable interpolation
30 *context: Additional context such as node IDs, file paths, etc.
32 """
35class NodeIdentityError(ProsemarkError):
36 """Error raised when node identity validation fails.
38 This exception indicates issues with NodeID format or uniqueness:
39 - Invalid UUID format
40 - Non-UUIDv7 identifiers
41 - Identity conflicts between nodes
43 Args:
44 message: A descriptive error message without variable interpolation
45 *context: Additional context such as the invalid ID value
47 """
50class BinderNotFoundError(ProsemarkError):
51 """Error raised when the binder file is missing.
53 This exception indicates that the expected _binder.md file
54 cannot be found in the specified location.
56 Args:
57 message: A descriptive error message without variable interpolation
58 *context: Additional context such as the expected file path
60 """
63class NodeNotFoundError(ProsemarkError):
64 """Error raised when a referenced node doesn't exist.
66 This exception indicates that a node referenced by ID or path
67 cannot be found in the binder tree or filesystem.
69 Args:
70 message: A descriptive error message without variable interpolation
71 *context: Additional context such as the missing node ID
73 """
76class BinderFormatError(ProsemarkError):
77 """Error raised when binder file format is invalid.
79 This exception indicates that the _binder.md file has malformed
80 managed blocks or invalid structure.
82 Args:
83 message: A descriptive error message without variable interpolation
84 *context: Additional context such as file content or line numbers
86 """
89class FileSystemError(ProsemarkError):
90 """Error raised for file system operation failures.
92 This exception wraps various filesystem-related errors such as:
93 - Permission denied errors
94 - I/O errors
95 - Path not found errors
96 - Disk space errors
98 Args:
99 message: A descriptive error message without variable interpolation
100 *context: Additional context such as file paths and operation type
102 """
105class ProsemarkFileExistsError(ProsemarkError):
106 """Error raised when attempting to create a file that already exists.
108 This exception indicates that a file creation operation was attempted
109 on a path where a file already exists, and the operation does not
110 permit overwriting existing files.
112 Args:
113 message: A descriptive error message without variable interpolation
114 *context: Additional context such as the existing file path
116 """
119class EditorLaunchError(ProsemarkError):
120 """Error raised when external editor cannot be launched.
122 This exception indicates failures in launching external editors such as:
123 - Editor executable not found
124 - Editor launch command failed
125 - Editor configuration issues
126 - System-specific launch failures
128 Args:
129 message: A descriptive error message without variable interpolation
130 *context: Additional context such as editor name, command, error details
132 """
135class PlaceholderNotFoundError(ProsemarkError):
136 """Error raised when a placeholder cannot be found by display title.
138 This exception indicates that a binder placeholder with the specified
139 display title does not exist in the binder structure. Used primarily
140 by MaterializeNode when attempting to materialize a non-existent placeholder.
142 Args:
143 message: A descriptive error message without variable interpolation
144 *context: Additional context such as the display title searched for
146 """
149class AlreadyMaterializedError(ProsemarkError):
150 """Error raised when attempting to materialize an already materialized item.
152 This exception indicates that a binder item already has a NodeId assigned
153 and cannot be materialized again. Used by MaterializeNode to prevent
154 double-materialization of existing nodes.
156 Args:
157 message: A descriptive error message without variable interpolation
158 *context: Additional context such as the existing NodeId
160 """
163class EditorNotFoundError(ProsemarkError):
164 """Error raised when external editor executable cannot be found.
166 This exception indicates that the configured editor is not available
167 in the system PATH or at the specified location.
169 Args:
170 message: A descriptive error message without variable interpolation
171 *context: Additional context such as editor name or path
173 """
176class FreeformContentValidationError(ProsemarkError):
177 """Error raised when freeform content validation fails.
179 This exception indicates issues with freeform content such as:
180 - Invalid filename format
181 - Mismatched timestamps or UUIDs
182 - Invalid UUIDv7 format
184 Args:
185 message: A descriptive error message without variable interpolation
186 *context: Additional context such as filename or validation details
188 """
191class NodeValidationError(ProsemarkError):
192 """Error raised when node validation fails.
194 This exception indicates issues with node data such as:
195 - Invalid timestamps
196 - Missing required fields
197 - Data consistency problems
199 Args:
200 message: A descriptive error message without variable interpolation
201 *context: Additional context such as node data or validation details
203 """
206class NodeAlreadyExistsError(ProsemarkError):
207 """Error raised when attempting to create a node that already exists.
209 This exception indicates that node files already exist for the
210 specified NodeId and cannot be recreated.
212 Args:
213 message: A descriptive error message without variable interpolation
214 *context: Additional context such as NodeId and file paths
216 """
219class FrontmatterFormatError(ProsemarkError):
220 """Error raised when YAML frontmatter is malformed.
222 This exception indicates that the YAML frontmatter in a node file
223 cannot be parsed or contains invalid data.
225 Args:
226 message: A descriptive error message without variable interpolation
227 *context: Additional context such as file path or YAML content
229 """
232class InvalidPartError(ProsemarkError):
233 """Error raised when an invalid content part is specified.
235 This exception indicates that an unsupported part was requested
236 for node editing (valid parts: draft, notes, synopsis).
238 Args:
239 message: A descriptive error message without variable interpolation
240 *context: Additional context such as the invalid part name
242 """
245class EditorError(ProsemarkError):
246 """Error raised when editor operation fails.
248 This exception indicates general editor-related failures that
249 don't fit into more specific error categories.
251 Args:
252 message: A descriptive error message without variable interpolation
253 *context: Additional context such as editor details or error info
255 """