Error Reference¶

Exception hierarchy¶

Exception
└── DepKeeperError                  message + structured `details`
    ├── ParseError                  line_number, line_content, file_path
    ├── ConfigError                 config_path, option
    ├── FileOperationError          file_path, operation, original_error
    └── NetworkError                url, status_code, response_body
        └── PyPIError               package_name

Every depkeeper exception carries a details mapping that is appended to str(exc) as key=value pairs:

[ERROR] Unknown configuration keys: check_conflict (config_path=/path/depkeeper.toml)

PyPIError subclasses NetworkError, so a single except NetworkError handler covers 404s, timeouts, 429 exhaustion and 5xx. Long response bodies are truncated to 200 characters before being recorded.

All exception classes use __slots__ and are importable from depkeeper.exceptions.

ParseError¶

Raised by the parser. Attributes: line_number, line_content, file_path.

Surfaced by the CLI as Failed to parse <file>: <detail> with exit code 1.

ConfigError¶

Raised during configuration discovery, decoding, parsing and validation. Attributes: config_path, option.

Exit code 1. Raised before any command runs.

FileOperationError¶

Raised by the filesystem layer. Attributes: file_path, operation (read / write / backup / restore / validate), original_error.

NetworkError and PyPIError¶

How network failures are absorbed¶

Network errors for an individual package rarely reach the user as an error:

The consequence: a run completes and reports, even with total network failure. Every package simply becomes an [ERROR] row.

Command-level errors¶

Raised as plain DepKeeperError by the command layer.

Warnings (not errors)¶

These are printed to stderr and do not change the exit code.

Handling errors programmatically¶

from depkeeper.exceptions import (
    DepKeeperError, ParseError, ConfigError, FileOperationError, NetworkError, PyPIError,
)

try:
    requirements = parser.parse_file("requirements.txt")
except ParseError as exc:
    print(f"{exc.file_path}:{exc.line_number}: {exc.message}")
    print(f"  {exc.line_content}")
except FileOperationError as exc:
    print(f"{exc.operation} failed on {exc.file_path}: {exc.original_error}")
except DepKeeperError as exc:
    print(exc.message, dict(exc.details))

try:
    data = await store.get_package_data("requests")
except PyPIError as exc:          # 404 / unexpected status
    print(exc.package_name, exc.status_code)
except NetworkError as exc:       # timeout, 429 exhaustion, 5xx
    print(exc.url, exc.status_code)

Catch NetworkError rather than PyPIError unless you specifically need the package-name attribute — the broader class is what the rest of the codebase catches.