Metadata-Version: 2.4
Name: kingkybel-pyerror
Version: 0.1.1
Summary: Robust error handling and exception management for Python
Author-email: Dieter J Kybelksties <github@kybelksties.com>
License-Expression: GPL-2.0-only
Project-URL: Homepage, https://github.com/kingkybel/PyError
Keywords: python,error-handling,exceptions,logging,error-management
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/markdown
Requires-Dist: kingkybel-pyfundamentals
Requires-Dist: kingkybel-pyflashlogger

# PyError

![PyError banner](assets/banners/pyerror-banner.svg)

A robust error handling and exception management library for Python. PyError provides utilities for logging and raising exceptions with flexible exception types, error codes, and custom parameters.

## Features

- **Flexible Exception Handling**: Support for custom exceptions with configurable error codes and additional parameters.
- **Logging Integration**: Integrated logging via `flashlogger` for fatal, critical, and error levels.
- **Positional and Keyword Arguments**: Support for passing additional arguments (`*args`) and keyword arguments (`**kwargs`) to exceptions.
- **Multiple Exception Types**: Functions for fatal, critical, and error scenarios with consistent interfaces.
- **Easy Extension**: Extensible design allowing custom exception classes with complex initialization logic.

## Installation

Install from PyPI:

```bash
pip install PyError
```

Or clone the repository and install locally:

```bash
git clone https://github.com/kingkybel/PyError.git
cd PyError
pip install .
```

## Usage

### Fatal Errors

```python
from error import fatal

# Raise a fatal error with default SystemExit
fatal("Critical system failure")

# Raise a fatal error with custom error code
fatal("Database connection failed", error_code=2)

# Raise a custom exception
class DatabaseError(Exception):
    def __init__(self, code, *args, **kwargs):
        self.code = code
        super().__init__(*args, **kwargs)

fatal("Connection timeout", exception=DatabaseError, error_code=42)
```

### Critical Errors

```python
from error import critical

# Raise a critical error
critical("Authentication failed")

# With custom exception
critical("Invalid configuration", exception=ConfigError, error_code=10)
```

### Standard Errors

```python
from error import error

# Raise an error
error("File not found")

# With additional parameters
error("Operation failed", exception=OperationError, error_code=1)
```

## Advanced Usage

### Custom Exceptions with Extra Parameters

```python
from error import fatal

class AppError(Exception):
    def __init__(self, code, *args, **kwargs):
        self.code = code
        self.context = kwargs.get('context')
        self.timestamp = kwargs.get('timestamp')

# Pass extra keyword arguments
fatal("App failed", AppError, 5, context="user_login", timestamp="2026-05-04")
```

## Testing

Run the test suite:

```bash
python -m unittest PyError.test.test_error
```

Or with verbose output:

```bash
python -m unittest PyError.test.test_error -v
```

## Requirements

- `kingkybel-pyfundamentals`
- `kingkybel-pyflashlogger`

## License

See LICENSE file for details.

## Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.
