You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
54 lines
2.0 KiB
54 lines
2.0 KiB
name: error_handling
|
|
|
|
rules:
|
|
- Use explicit exceptions for domain/error classification (e.g., ProviderError, ValueError).
|
|
- Prefer logging.exception when catching an exception where stack trace is useful.
|
|
- Avoid broad except: clauses that swallow exceptions; if broad except is used for "best-effort" fallback, log at warning and include original exception context.
|
|
- For public library-like functions, prefer raising typed exceptions instead of returning magic values ([], False) — only return safe defaults where documented.
|
|
|
|
examples:
|
|
- path: ai_provider.py
|
|
excerpt: |
|
|
```python
|
|
except requests.ConnectionError as exc:
|
|
if attempt == retries:
|
|
raise ProviderError(
|
|
f"Connection error when calling provider: {exc}"
|
|
) from exc
|
|
...
|
|
```
|
|
note: mapping network error to ProviderError with re-raise chaining
|
|
|
|
- path: pipeline/ai_provider_wrapper.py
|
|
excerpt: |
|
|
```python
|
|
except Exception:
|
|
_logger.exception("Failed to append audit event for embedding failure")
|
|
results[j] = None
|
|
```
|
|
note: logs and assigns None for failure; fallback behavior documented earlier in wrapper rule
|
|
|
|
- path: similarity/compute.py
|
|
excerpt: |
|
|
```python
|
|
try:
|
|
import duckdb
|
|
except Exception:
|
|
logger.exception("duckdb import failed; cannot load vectors")
|
|
return 0
|
|
```
|
|
note: defensive import handling and early return on failure
|
|
|
|
anti_patterns:
|
|
- Bad: Broad except without logging and without re-raising (silently hides bugs)
|
|
remediation: Narrow exception types or at minimum log.exception() and re-raise or convert to a domain error if truly handled.
|
|
example: |
|
|
```python
|
|
try:
|
|
do_work()
|
|
except Exception:
|
|
return []
|
|
# BAD: hides the root cause and returns an ambiguous default
|
|
```
|
|
- Bad: Mixing print() and logging for errors
|
|
remediation: Replace print() calls with logger.* calls; use structured logging configuration.
|
|
|