Metadata-Version: 2.4
Name: negogv-log
Version: 0.1.8
Summary: A custom Python logger configuration with colored console output.
Author-email: Daniel Viacheslavovich <daniel.tk@tuta.io>
License: MIT License
        
        Copyright (c) 2025 Daniel Weber
        
        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/negogv/negogv_logger
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# negogv-log 🪵🎨

[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Package Version](https://img.shields.io/badge/version-0.1.8-green.svg)](pyproject.toml)

> A lightweight, highly readable Python logging library featuring colorized console output, split file logging by severity, custom multiline formatting, and exception location reporting.

---

## 📖 Overview

**negogv-log** is a Python logging utility designed to simplify application logging. It provides out-of-the-box colorized console formatting using ANSI escape codes, separate log file outputs based on severity levels (`low_lvl.log` vs `high_lvl.log`), automatic multiline message indentation, and concise exception tracing with source code line locations.

Whether building CLI tools, background workers, or multi-module Python projects, **negogv-log** ensures log readability in both interactive terminals and log files.

---

## ✨ Features

- 🎨 **Colorized Console Output**: ANSI-colored console logs tailored to log severity (DEBUG, INFO, WARNING, ERROR, CRITICAL).
- 📁 **Dual-Level Split File Logging**:
    - `low_lvl.log`: Captures DEBUG and INFO level logs.
    - `high_lvl.log`: Captures WARNING, ERROR, and CRITICAL level logs.
- 📄 **Smart Multiline Formatting**: Automatically indents multiline log messages in log files for clean parsing.
- 🔍 **Source Code Origin Tracking**: Displays timestamp, level, source filename, and line numbers.
- 🚫 **Console Level Exclusion**: Exclude specific log levels from printing to console output while preserving file logging.
- 💥 **Concise Exception Tracing**: `log_exception()` helper extracts and displays exception names, source filenames, line numbers, and error messages cleanly.

---

## 🗂️ Repository Structure

``` txt
negogv_logger/
├── negogv_log/                      # Core Package Module
│   ├── __init__.py                  # Package exports (setup_logger, log_exception, formatters, filters)
│   └── logger.py                    # Main implementation of loggers, formatters, filters & color schemes
│
├── tests/                           # Test Suite Directory
│   ├── __init__.py                  # Test package initialization
│   └── test_model.py                # Unit tests for CustomFormatter and CustomFileFormatter
├── examples/                        # Minimal runnable usage examples
│
├── LICENSE                          # MIT Open Source License
├── pyproject.toml                   # Build system and PyPI package specifications
└── README.md                        # Original project documentation
```

### Module Breakdown

- **[`negogv_log/logger.py`](negogv_log/logger.py)**:
    - `colour()`: Utility function for wrapping strings in ANSI color codes.
    - `CustomFormatter`: Formatter for colored console log output.
    - `CustomFileFormatter`: Formatter handling multiline indentation for file logs.
    - `MaxLevelFilter`: Filter restricting log file entries to a maximum log level (e.g. `<= INFO`).
    - `ExcludeLevelFilter`: Filter allowing console exclusions for specified log levels.
    - `log_exception()`: Helper that sends formatted exception details through `logging`.
    - `setup_logger()`: Primary factory function initializing handlers, filters, and log file outputs.
- **[`tests/test_model.py`](file:///home/negogv/Dev/negogv_logger/tests/test_model.py)**:
    - `TestCustomFormatter`: Verifies correct log message and level formatting for console output.
    - `TestCustomFileFormatter`: Verifies newline replacement and multiline indentation handling.

---

## 🚀 Installation

Install directly via `pip` from PyPI:

```bash
pip install negogv-log
```

Or install from source repository:

```bash
git clone https://github.com/negogv/negogv_logger.git
cd negogv_logger
pip install .
```

---

## 🛠️ Usage

### Basic Example

```python
from negogv_log import setup_logger

# Initialize logger and specify directory for log files
logger = setup_logger(log_dir="logs")

logger.debug("Debugging application state")
logger.info("Service initialized successfully")
logger.warning("High memory usage detected")
logger.error("Failed to connect to database")
logger.critical("Unrecoverable error encountered!")
```

### Excluding Log Levels from Console

You can filter out specific log levels from the console output while still writing them to log files:

```python
# Exclude INFO messages from stdout
logger = setup_logger(log_dir="logs", exclude_console="INFO")

# Exclude multiple levels
logger = setup_logger(log_dir="logs", exclude_console=["DEBUG", "INFO"])
```

### Exception Logging Helper

Use `log_exception()` to log caught exceptions with file name and line number context:

```python
from negogv_log import log_exception

try:
    result = 10 / 0
except Exception as exc:
    log_exception(exc)
```

---

## 📦 Technologies

- **Language**: [Python 3.8+](https://www.python.org/)
- **Standard Library Modules**: `logging`, `sys`, `os`, `unittest`, `typing`
- **Packaging Standard**: PEP 517 / PEP 621 with `setuptools`

---

## 🔧 Configuration

The `setup_logger(log_dir, exclude_console=None)` function provides the following default behaviors:

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `log_dir` | `str` | *Required* | Path to folder where `high_lvl.log` and `low_lvl.log` are stored. |
| `exclude_console` | `Union[List[str], str]` | `None` | Log level(s) to suppress from terminal output. |

### Log Files Generated in `log_dir`

1. `low_lvl.log`: Stores `DEBUG` and `INFO` messages formatted with `CustomFileFormatter`.
2. `high_lvl.log`: Stores `WARNING`, `ERROR`, and `CRITICAL` messages formatted with `CustomFileFormatter`.

---

## ✅ Requirements

- **Python**: `>= 3.8`
- **Dependencies**: None (uses standard Python library modules only).

---

## 🧪 Testing

Run the test suite using Python's built-in `unittest` module:

```bash
python3 -m unittest discover tests
```

---

## 🤝 Contributing

Contributions are welcome!

1. Fork the repository (`https://github.com/negogv/negogv_logger`).
2. Create your feature branch (`git checkout -b feature/NewFeature`).
3. Commit your changes (`git commit -m 'Add NewFeature'`).
4. Push to the branch (`git push origin feature/NewFeature`).
5. Open a Pull Request.

---

## 📄 Documentation

- Package source code: [`negogv_log/logger.py`](file:///home/negogv/Dev/negogv_logger/negogv_log/logger.py)
- Unit tests: [`tests/test_model.py`](file:///home/negogv/Dev/negogv_logger/tests/test_model.py)

---

## ❤️ Acknowledgements

- Built and maintained by **Daniel Weber** (`daniel.tk@tuta.io`).
- Inspired by Python `logging` standard library customization techniques.

---

## 📝 Changelog

Project release history from repository commits:

- **`0.1.8`** — Reworked exception logging, handler lifecycle, validation, non-TTY output, and package documentation.
- **`0.1.7`** — Added console log level exclusion filtering (`exclude_console`).
- **`0.1.6`** — Bug fixes and stability improvements.
- **`0.1.5`** — Minor patch fixes.
- **`0.1.4`** — Package release updates and metadata refinements.
- **`0.1.2`** — Added exception logger (`log_exception`) and ANSI console color support.
- **`Initial`** — Initial package setup and split log file handlers.
