Metadata-Version: 2.4
Name: fnclogger
Version: 1.0.7
Summary: Простой и мощный логгер для Python с цветным выводом
Home-page: https://github.com/plv88/fnclogger
Author: plv88
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: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=10.0.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.10; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: mypy>=0.800; extra == "dev"
Requires-Dist: build>=0.7.0; extra == "dev"
Requires-Dist: twine>=3.4.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# FncLogger

![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/fnclogger.svg)

Простой и мощный логгер для Python с красивым цветным выводом и гибкой конфигурацией.

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

```bash
pip install fnclogger
```

**Rich входит в комплект!** Никаких дополнительных зависимостей - сразу получаете красивый цветной вывод. ✨

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

```python
from fnclogger import get_logger

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

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

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

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

## ⚙️ Конфигурация

### Режимы работы

```python
from fnclogger import FncLogger, LogMode

# Только в консоль (с красивым форматированием)
console_logger = FncLogger(
    name="console_app",
    mode=LogMode.CONSOLE_ONLY
)

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

# В консоль и файл одновременно (по умолчанию)
both_logger = FncLogger(
    name="full_app",
    mode=LogMode.BOTH
)
```

### Уровни логирования

```python
from fnclogger import LogLevel

# Разные уровни для консоли и файла
mixed_logger = FncLogger(
    name="mixed_app",
    console_level=LogLevel.INFO,    # В консоль только INFO и выше
    file_level=LogLevel.WARNING     # В файл только WARNING и выше
)
```

### JSON форматирование

```python
from fnclogger import OutputFormat

# JSON в файле, красивый текст в консоли
json_logger = FncLogger(
    name="api_server",
    file_format=OutputFormat.JSON,
    console_format=OutputFormat.TEXT
)

json_logger.info("API запрос", extra={
    "method": "GET",
    "url": "/api/users",
    "status": 200,
    "response_time": 0.15
})
```

### Отключение Rich (если нужно)

```python
# Если по какой-то причине нужно отключить Rich
plain_logger = FncLogger(
    name="plain_app",
    use_rich=False  # Использует простые ANSI цвета
)
```

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

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

```python
from fnclogger import FncLogger, LogMode, OutputFormat, LogLevel

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

def process_request(user_id, endpoint):
    app_logger.info("Начало обработки запроса", extra={
        "user_id": user_id,
        "endpoint": endpoint
    })
    
    try:
        # Ваша бизнес-логика здесь
        result = handle_business_logic(endpoint)
        app_logger.success(f"Запрос успешно обработан: {endpoint}")
        return result
    except Exception as e:
        app_logger.fail(f"Ошибка обработки запроса: {e}", exc_info=True)
        raise
```

### Обработка ошибок

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

def safe_operation():
    try:
        # Потенциально опасная операция
        result = risky_function()
        logger.success("Операция выполнена успешно")
        return result
    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
```

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

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

# Специализированные логгеры для разных компонентов
db_logger = FncLogger("service.database", mode=LogMode.FILE_ONLY)
api_logger = FncLogger("service.api", console_level=LogLevel.DEBUG)

def database_operation(query):
    db_logger.debug(f"Выполнение SQL: {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

def api_endpoint(request):
    api_logger.info("Получен API запрос", extra={
        "method": request.method,
        "path": request.path,
        "user_agent": request.headers.get("User-Agent")
    })
    # Обработка запроса...
```

## 🔧 API Reference

### Основные классы и функции

```python
# Быстрое создание логгера (с Rich по умолчанию)
get_logger(name: str, **kwargs) -> FncLogger

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

# Создание настраиваемого логгера
FncLogger(
    name: str,
    mode: LogMode = LogMode.BOTH,
    level: LogLevel = LogLevel.INFO,
    console_level: Optional[LogLevel] = None,
    file_level: Optional[LogLevel] = None,
    log_dir: Optional[str] = None,
    file_format: OutputFormat = OutputFormat.TEXT,
    console_format: OutputFormat = OutputFormat.TEXT,
    use_rich: bool = True,  # Rich включен по умолчанию
    max_file_size: int = 10 * 1024 * 1024,  # 10MB
    backup_count: int = 5
)
```

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

```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"
```

## 🎨 Особенности

### ✨ Rich из коробки
- Красивый цветной вывод без дополнительных установок
- Форматированные трейсбеки для ошибок
- Стильные иконки и цвета для разных типов сообщений

### 📁 Автоматическая ротация файлов
- Файлы логов автоматически ротируются при достижении максимального размера
- По умолчанию: 10MB на файл, 5 backup файлов

### 🔒 Thread-Safe
- Безопасное использование в многопоточных приложениях
- Синглтон паттерн с блокировками

### 🔧 Гибкое форматирование
- Разные форматы для консоли и файла
- JSON для структурированных логов
- Поддержка дополнительных данных через `extra`

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

После установки можете протестировать:

```python
from fnclogger import get_logger

logger = get_logger("test")
logger.success("FncLogger установлен и работает!")
logger.highlight("Rich включен по умолчанию - красиво!")
logger.info("Все системы в норме", extra={"status": "ok"})
```

Или запустите пример:

```bash
# Если клонировали репозиторий
python examples/basic_example.py
```

## 📁 Структура логов

По умолчанию логи сохраняются в папку `logs/` в текущей директории:

```
logs/
├── my_app.log        # Основные логи
├── my_app.log.1      # Backup 1
├── my_app.log.2      # Backup 2
└── ...
```

Формат логов в файле:
```
[2025-05-30 14:30:25] [INFO    ] [my_app] Приложение запущено
[2025-05-30 14:30:26] [WARNING ] [my_app] ⚠ Требуется внимание
[2025-05-30 14:30:27] [ERROR   ] [my_app] ✗ Произошла ошибка
```

JSON формат:
```json
{
  "timestamp": "2025-05-30T14:30:25.123456",
  "level": "INFO",
  "logger": "my_app",
  "message": "Пользователь вошел",
  "module": "main",
  "function": "login",
  "line": 42,
  "user_id": 123,
  "action": "login"
}
```

## 🚀 Что нового в v1.0.1

- ✅ **Rich включен по умолчанию** - красивый вывод сразу после установки
- ✅ **Упрощенная установка** - одна команда `pip install fnclogger`
- ✅ **Улучшенная документация** - больше примеров и пояснений

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

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

Для разработки:
```bash
pip install fnclogger[dev]
```

## 📝 Changelog

### v1.0.1
- Rich теперь основная зависимость (устанавливается автоматически)
- Упрощена установка и использование
- Обновлена документация

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

## 📄 Лицензия

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

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

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

---

**Красивое логирование из коробки** 🪵✨🎨
