Metadata-Version: 2.4
Name: FncLogger
Version: 1.0.0
Summary: Простой и мощный логгер для Python с цветным выводом
Home-page: https://github.com/yourusername/fnclogger
Author: Your Name
Author-email: plv88 <devplv88@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Piliaev Andrei
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/plv88/FncLogger
Project-URL: Repository, https://github.com/plv88/FncLogger
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Logging
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: rich
Requires-Dist: rich>=10.0.0; extra == "rich"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 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 сообщества**
