Metadata-Version: 2.4
Name: fsvlog
Version: 0.3.2
Summary: Advanced logging library with colored output, file rotation, and flexible configuration
Author-email: Fsainv028 <fsainv028@gmail.com>
Project-URL: Homepage, https://github.com/Fsainv028/FSVLog
Project-URL: Repository, https://github.com/Fsainv028/FSVLog.git
Project-URL: Release Notes, https://github.com/Fsainv028/FSVLog/releases
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Logging
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Dynamic: license-file

# FSVLog - Advanced Python Logging Library
> A powerful and flexible logging library with colored console output, file rotation, JSON support, metrics, and global exception handling.

---
[![PyPI version](https://badge.fury.io/py/fsvlog.svg)](https://badge.fury.io/py/fsvlog)
[![Python versions](https://img.shields.io/pypi/pyversions/fsvlog.svg)](https://pypi.org/project/fsvlog/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)


## Features
- 🎨 Colored output with RGB color support for console logging
- 📁 File logging with automatic rotation and cleanup
- 🔄 Flexible modes - File-only, console-only, or both
- 📏 Size-based rotation to prevent log files from growing too large
- 🗑️ Automatic cleanup to keep only the newest log files
- ✨ Custom formatting with flexible log message templates
- 📊 Metrics tracking to count logs by level
- 🛡️ Global exception handling to catch and log unhandled exceptions
- 📋 JSON format support for machine-readable logs
- 🔗 Context binding to add persistent context to log entries
- 🎯 Multiple log levels: DEBUG, INFO, WARNING, ERROR, FATAL
- ⚡ Zero dependencies - pure Python, no external packages


## Installation
```bash
pip install fsvlog
```
---
## Quick Start
```python
from fsvlog import FSVLog

# Create logger with default settings
logger = FSVLog()

# Log messages with different levels
logger.debug("Debug message")
logger.info("Info message")
logger.warning("Warning message")
logger.error("Error message")
logger.fatal("Fatal message")
```
## Advanced Usage
### Basic Configuration
```python
logger = FSVLog(
    log_folder_path="logs",      # Log directory (default: "Logs")
    max_logs=10,                 # Max log files to keep (default: 10)
    max_file_size_mb=100,        # Max file size before rotation (default: 100MB)
    log_level="INFO",            # Minimum log level (default: "DEBUG")
    file_only=False,             # Log only to file (default: False)
    console_only=False,          # Log only to console (default: False)
    use_json=False,              # Use JSON format (default: False)
    enable_metrics=False,        # Enable metrics tracking (default: False)
    enable_global_exception_logging=True,  # Catch unhandled exceptions
    exception_format="compact"   # "full", "compact", or "minimal"
)
```
### Custom Formatting
```python
# Custom log format
logger = FSVLog(
    log_format="{timestamp} [{level}] [{filename}:{lineno}] {message}",
    time_format="%Y-%m-%d %H:%M:%S"
)

logger.info("Custom format example")
# Output: 2026-07-29 14:30:00 [INFO] [app.py:42] Custom format example
```
### Context Binding
```python
# Bind context to all subsequent logs
logger = FSVLog()
user_logger = logger.bind(user_id=123, session="abc123")
user_logger.info("User logged in")
# Output includes user_id and session

# Type-specific logging
auth_logger = logger.type("AUTH")
auth_logger.info("Authentication successful")
# Output: [AUTH] Authentication successful
```
### JSON Logging
```python
# Enable JSON format for structured logging
logger = FSVLog(use_json=True)
logger.info("Structured log", extra={"user": "john", "action": "login"})
# Output: {"timestamp": "2026-07-29T14:30:00.123Z", "level": "INFO", "message": "Structured log", "user": "john", "action": "login"}
```
### Metrics
```python
# Enable metrics tracking
logger = FSVLog(enable_metrics=True)
logger.info("Message 1")
logger.error("Error 1")
logger.info("Message 2")

metrics = logger.get_metrics()
print(metrics)  # {'INFO': 2, 'ERROR': 1}

logger.reset_metrics()
```
### Exception Handling
```python
logger = FSVLog(exception_format="compact")

try:
    result = 1 / 0
except Exception:
    logger.exception("Division by zero occurred")
    # Output: Division by zero occurred: ZeroDivisionError: division by zero [app.py:42]
```
### Global Exception Logging
```python
# All unhandled exceptions will be automatically logged
logger = FSVLog(enable_global_exception_logging=True)

# This will be caught and logged
def buggy_function():
    raise RuntimeError("Something went wrong!")

buggy_function()  # Automatically logged as FATAL
```
### Custom Colors
```python
# Use predefined colors
logger.info("Success!", color=Colors.GREEN)
logger.error("Danger!", color=Colors.RED)

# Custom RGB colors
logger.custom("Custom colored message", "CUSTOM", (255, 165, 0))  # Orange
```
### Log Levels
| Level | Method | Color | Use Case |
|----------|----------|----------|----------|
| DEBUG | .debug() | Cyan | Detailed debugging info |
| INFO | .info() | Green | General information |
| WARNING | .warning() | Yellow | Warning messages |
| ERROR | .error() | Red | Error conditions |
| FATAL | .fatal() | Magenta | Critical errors |

---
## API Reference
### Class: FSVLog
Parameters:

- log_folder_path (str): Path to log directory. Default: "Logs"
- max_logs (int): Maximum number of log files to keep. Default: 10
- max_file_size_mb (int): Maximum file size in MB before rotation. Default: 100
- log_format (str): Custom log format template. Default: "{timestamp} [{level}] {message}"
- time_format (str): Time format string. Default: "%Y-%m-%dT%H:%M:%S.%f"
- filename_time_format (str): Filename time format. Default: "%Y%m%d_%H%M%S_%f"
- file_only (bool): Log only to file. Default: False
- console_only (bool): Log only to console. Default: False
- use_json (bool): Use JSON format. Default: False
- log_level (str): Minimum log level. Default: "DEBUG"
- enable_metrics (bool): Enable metrics tracking. Default: False
- enable_global_exception_logging (bool): Catch unhandled exceptions. Default: True
- exception_format (str): Exception format: "full", "compact", or "minimal". Default: "compact"

Available format keys:

    {timestamp} - Current timestamp
    {level} - Log level
    {message} - Log message
    {filename} - Source file name
    {lineno} - Line number
    {funcname} - Function name
    {type} - Custom log type
    {context} - Bound context (JSON)

Methods:

    debug(msg, extra=None) - Log debug message
    info(msg, extra=None) - Log info message
    warning(msg, extra=None) - Log warning message
    error(msg, extra=None) - Log error message
    fatal(msg, extra=None) - Log fatal message
    exception(msg, extra=None) - Log exception with traceback
    custom(msg, level, color=None, extra=None) - Log with custom level and color
    bind(**kwargs) - Create logger with bound context
    type(log_type) - Create logger with specific log type
    set_log_level(level) - Change minimum log level
    set_log_format(format) - Change log format
    set_time_format(format) - Change time format
    get_current_log_file() - Get current log file path
    get_metrics() - Get metrics dictionary
    reset_metrics() - Reset metrics
    close() - Close log file
    enable_global_exception_logging() - Enable global exception handler
    set_exception_format(format) - Set exception format

### Helper Function: create_logger()
```python
from fsvlog import create_logger

logger = create_logger("logs", max_logs=5, log_level="INFO")
```
## Examples
### Web Application Logging
```python
from fsvlog import FSVLog

logger = FSVLog(log_folder_path="web_logs", enable_metrics=True)

# Bind request context
req_logger = logger.bind(request_id="req-123", user="alice")
req_logger.info("Request received")
req_logger.error("Database connection failed")

# Type-based logging
access_logger = logger.type("ACCESS")
access_logger.info("GET /api/users 200")
```
### Microservice Logging
```python
logger = FSVLog(
    log_folder_path="/var/log/myapp",
    use_json=True,
    enable_global_exception_logging=True,
    exception_format="full"
)

# Add service context
svc_logger = logger.bind(service="auth-service", version="1.2.3")
svc_logger.info("Service started")
```
### Development Debugging
```python
import time
from fsvlog import FSVLog

logger = FSVLog(
    console_only=True,  # Console only for development
    log_level="DEBUG",
    log_format="{timestamp} [{level}] [{funcname}()] {message}"
)

def process_data():
    logger.debug("Processing data...")
    # ... processing
    logger.info("Data processed successfully")

process_data()
```
---
# License
**MIT License - see LICENSE file for details**

---
# Contributing
**Contributions are welcome! Please feel free to submit a Pull Request.**

---
## Support
- **GitHub**: [Fsainv028/FSVLog](https://github.com/Fsainv028/FSVLog)
- **Issues**: [Report a bug](https://github.com/Fsainv028/FSVLog/issues)
- **Email**: fsainv028@gmail.com

---
Made with ❤️ by Fsainv028
