# FancyLogger

![Python](https://img.shields.io/badge/python-3.7+-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
![PyPI](https://img.shields.io/pypi/v/fancy-logger.svg)

Улучшенный логгер для Python приложений с поддержкой цветного вывода, JSON форматирования и гибкой конфигурацией.

## 🚀 Основные возможности

- ✅ **Цветной вывод в консоль** с поддержкой Rich (опционально)
- ✅ **Несколько режимов работы**: консоль, файл, или оба
- ✅ **JSON логирование** для структурированных данных
- ✅ **Ротация файлов** по размеру и времени
- ✅ **Thread-safe** операции
- ✅ **Раздельные уровни** для консоли и файла
- ✅ **Контекстные данные** в логах
- ✅ **Простая конфигурация** через словари
- ✅ **Минимальные зависимости** (Rich опционально)

## 📦 Установка

### Базовая установка
```bash
pip install fancy-logger
```

### С поддержкой Rich (рекомендуется)
```bash
pip install fancy-logger[rich]
```

### Для разработки
```bash
pip install fancy-logger[dev]
```

## 🎯 Быстрый старт

### Базовое использование

```python
from fancy_logger import get_logger

# Создание логгера
logger = get_logger("my_app")

# Основные методы
logger.info("Приложение запущено")
logger.warning("Предупреждение")
logger.error("Произошла ошибка")

# Цветные методы
logger.success("Операция завершена успешно!")
logger.highlight("Важная информация")
logger.alert("Требуется внимание")
logger.fail("Критическая ошибка")
```

### Конфигурация режимов

```python
from fancy_logger import FancyLogger, LogMode, LogLevel

# Только в консоль
console_logger = FancyLogger(
    name="console_app",
    mode=LogMode.CONSOLE_ONLY,
    level=LogLevel.DEBUG
)

# Только в файл
file_logger = FancyLogger(
    name="file_app", 
    mode=LogMode.FILE_ONLY,
    log_dir="./logs"
)

# В консоль и файл с разными уровнями
mixed_logger = FancyLogger(
    name="mixed_app",
    mode=LogMode.BOTH,
    console_level=LogLevel.INFO,
    file_level=LogLevel.WARNING
)
```

### JSON логирование

```python
from fancy_logger import FancyLogger, OutputFormat

# JSON в файл, обычный текст в консоль
logger = FancyLogger(
    name="api_server",
    file_format=OutputFormat.JSON,
    console_format=OutputFormat.TEXT
)

# Логирование с контекстными данными
logger.info("Пользователь авторизован", extra={
    "user_id": 12345,
    "email": "user@example.com", 
    "ip": "192.168.1.1",
    "action": "login"
})
```

### Конфигурация из словаря

```python
config = {
    'name': 'web_app',
    'mode': 'both',
    'level': 20,  # INFO
    'console_level': 20,  # INFO
    'file_level': 30,     # WARNING
    'log_dir': './logs',
    'file_format': 'json',
    'console_format': 'text',
    'use_rich': True,
    'max_file_size': 5 * 1024 * 1024,  # 5MB
    'backup_count': 3
}

logger = FancyLogger.configure_from_dict(config)
```

## 📋 Примеры использования

### Веб-приложение

```python
from fancy_logger import FancyLogger, LogMode, OutputFormat

# Настройка логгера для веб-приложения
app_logger = FancyLogger(
    name="webapp",
    mode=LogMode.BOTH,
    console_level=LogLevel.INFO,
    file_level=LogLevel.WARNING,
    file_format=OutputFormat.JSON,
    log_dir="./logs",
    max_file_size=10 * 1024 * 1024,  # 10MB
    backup_count=5
)

def handle_request(user_id, endpoint):
    app_logger.info("Обработка запроса", extra={
        "user_id": user_id,
        "endpoint": endpoint,
        "timestamp": datetime.now().isoformat()
    })
    
    try:
        # Обработка запроса
        result = process_request(endpoint)
        app_logger.success(f"Запрос обработан: {endpoint}")
        return result
    except Exception as e:
        app_logger.fail(f"Ошибка обработки: {e}", exc_info=True)
        raise
```

### Микросервис с разными компонентами

```python
# Основной логгер приложения
main_logger = get_logger("service")

# Специализированные логгеры
db_logger = FancyLogger("service.database", mode=LogMode.FILE_ONLY)
api_logger = FancyLogger("service.api", console_level=LogLevel.DEBUG)
auth_logger = FancyLogger("service.auth", file_format=OutputFormat.JSON)

# Использование
def authenticate_user(token):
    auth_logger.info("Проверка токена", extra={"token_hash": hash(token)})
    
    if not validate_token(token):
        auth_logger.alert("Недействительный токен")
        return False
        
    auth_logger.success("Пользователь авторизован")
    return True

def database_query(query):
    db_logger.debug(f"Выполнение запроса: {query}")
    
    try:
        result = execute_query(query)
        db_logger.info(f"Запрос выполнен, строк: {len(result)}")
        return result
    except Exception as e:
        db_logger.error(f"Ошибка БД: {e}", exc_info=True)
        raise
```

### Обработка исключений

```python
logger = get_logger("error_handler")

def safe_operation():
    try:
        risky_operation()
        logger.success("Операция выполнена успешно")
    except ValueError as e:
        logger.alert(f"Некорректные данные: {e}")
        return None
    except ConnectionError as e:
        logger.fail(f"Ошибка соединения: {e}", exc_info=True)
        raise
    except Exception as e:
        logger.critical(f"Неожиданная ошибка: {e}", exc_info=True)
        raise
```

## 🔧 API Reference

### Основные классы

#### `FancyLogger`

Основной класс логгера.

**Параметры конструктора:**
- `name: str` - имя логгера
- `mode: LogMode` - режим работы (CONSOLE_ONLY, FILE_ONLY, BOTH)
- `level: LogLevel` - базовый уровень логирования
- `console_level: LogLevel` - уровень для консоли
- `file_level: LogLevel` - уровень для файла
- `log_dir: str | Path` - директория для логов
- `file_format: OutputFormat` - формат файловых логов
- `console_format: OutputFormat` - формат консольных логов
- `use_rich: bool` - использовать Rich для цветного вывода
- `max_file_size: int` - максимальный размер файла (байты)
- `backup_count: int` - количество backup файлов
- `custom_format: str` - кастомный формат сообщений

#### Методы логирования

```python
# Стандартные методы
logger.debug(message, extra=None, **kwargs)
logger.info(message, extra=None, **kwargs)
logger.warning(message, extra=None, **kwargs)
logger.error(message, extra=None, exc_info=False, **kwargs)
logger.critical(message, extra=None, exc_info=True, **kwargs)

# Цветные методы
logger.success(message, extra=None, **kwargs)  # Зеленый с ✓
logger.highlight(message, extra=None, **kwargs)  # Синий с →
logger.alert(message, extra=None, **kwargs)    # Желтый с ⚠
logger.fail(message, extra=None, **kwargs)     # Красный с ✗
```

### Enum классы

```python
class LogLevel(Enum):
    DEBUG = logging.DEBUG
    INFO = logging.INFO
    WARNING = logging.WARNING
    ERROR = logging.ERROR
    CRITICAL = logging.CRITICAL

class LogMode(Enum):
    CONSOLE_ONLY = "console"
    FILE_ONLY = "file"
    BOTH = "both"

class OutputFormat(Enum):
    TEXT = "text"
    JSON = "json"
```

### Вспомогательные функции

```python
# Быстрое создание логгера
get_logger(name: str, **kwargs) -> FancyLogger

# Базовая настройка
setup_basic_logger(name: str, level: str) -> FancyLogger
```

## 🧪 Тестирование

```bash
# Запуск всех тестов
pytest

# С покрытием кода
pytest --cov=fancy_logger

# Только быстрые тесты
pytest -m "not slow"
```

## 🛣️ Roadmap

- [ ] Поддержка асинхронного логирования
- [ ] Интеграция с популярными фреймворками (FastAPI, Django)
- [ ] Отправка логов в внешние системы (Elasticsearch, Sentry)
- [ ] Веб-интерфейс для просмотра логов
- [ ] Метрики и мониторинг

## 🤝 Участие в разработке

1. Fork репозитория
2. Создайте feature branch (`git checkout -b feature/amazing-feature`)
3. Commit изменения (`git commit -m 'Add amazing feature'`)
4. Push в branch (`git push origin feature/amazing-feature`)
5. Создайте Pull Request

### Требования к коду

- Код должен проходить `black`, `flake8` и `mypy`
- Все новые функции должны быть покрыты тестами
- Документация должна быть обновлена

## 📝 Changelog

### v1.0.0
- Первый релиз
- Базовая функциональность логирования
- Поддержка Rich и JSON форматирования
- Thread-safe операции
- Конфигурация через словари

## 📄 Лицензия

Этот проект распространяется под лицензией MIT. Подробности в файле [LICENSE](LICENSE).

## 🙏 Благодарности

- [Rich](https://github.com/Textualize/rich) - за отличную библиотеку для цветного вывода
- Python Logging - за базовую функциональность логирования
- Сообщество Python за вдохновение и обратную связь

---

**Создано с ❤️ для Python сообщества**