onelogger 0.1.3
Oneenv-based settings management and fast logging library
Requires Python: >=3.11

# OneLogger 🚀
A Simple and Efficient Logging Library

OneLogger is a lightweight logging library built to help you dynamically configure and manage log settings with ease using [oneenv](https://github.com/kitfactory/oneenv). It leverages Python's built-in logging module and (for Python versions up to 3.12) enhances performance with [picologging](https://github.com/microsoft/picologging). Perfect for development, testing, and production environments!

## Features ✨
- **Dynamic Configuration**: Easily manage logging settings using environment variables via oneenv.
- **High Performance Logging**:
  - For Python versions ≤ 3.12, OneLogger uses picologging to deliver blazing-fast logging 🚀.
  - For Python 3.13 and later, it seamlessly falls back to the standard logging module.
- **Flexible Output Options**: Configure logs to output to the console, files (with rotation), or both.
- **Custom Formatting**: Supports both plain text and JSON log formats.
- **Asynchronous Logging**: Optionally enable asynchronous logging for better performance under high load.
- **Easy Integration**: A simple API with a singleton pattern for effortless logger retrieval.

## Supported Environments 🖥️
- **Python ≥ 3.11**
  - **Python < 3.13**: Utilizes picologging for enhanced performance.
  - **Python ≥ 3.13**: Uses the standard logging module for full compatibility.

## Installation 🛠️

### For Users 👥
```bash
pip install onelogger
```

### For Developers 🛠️
1. **Clone the Repository**
   ```bash
   git clone <repository-url>
   cd onelogger
   ```

2. **Create and Activate a Virtual Environment**
   ```bash
   python -m venv .venv
   # Windows (PowerShell)
   .\.venv\Scripts\Activate.ps1
   # macOS/Linux
   source .venv/bin/activate
   ```

3. **Install Development Dependencies**
   ```bash
   pip install -e ".[dev]"
   ```

## Usage 🚀
OneLogger integrates effortlessly into your projects. For example:

```python
from onelogger import Logger

# Retrieve a configured logger instance
logger = Logger.get_logger("example_logger")

# Log messages at various levels
logger.info("This is an informational message.")
logger.error("This is an error message.")

try:
    result = 1 / 0
except Exception as e:
    logger.exception("An exception occurred during division!")
```

You can try out the example provided in the `examples` folder:
```bash
python examples/example_logger.py
```

## Configuration 📦
OneLogger uses [oneenv](https://github.com/kitfactory/oneenv) to manage environment variables with ease. The library automatically generates a `.env.example` template file with detailed descriptions for all available settings. This makes it simple to:

- View all available configuration options with descriptions
- Understand the purpose and valid values for each setting
- Create your own `.env` file by copying and modifying the template

Here's an example of the auto-generated template:

```ini
# Auto-generated by OneEnv

# Specifies the logging level used by OneLogger.
# Valid options are DEBUG, INFO, WARNING, ERROR, and CRITICAL.
# Required
LOG_LEVEL=DEBUG

# Specifies the destination for log output.
# Options: 'console' for standard output, 'file' for file logging, or 'both'.
# Required
LOG_OUTPUT=both

# Specifies the log file path when LOG_OUTPUT is set to 'file' or 'both'.
LOG_FILE_PATH=example.log

# ... (other settings with descriptions)
```

To configure OneLogger, simply:
1. Copy `.env.example` to `.env`
2. Modify the values in `.env` according to your needs
3. OneLogger will automatically load these settings when initialized

## Contributing 🤝
Contributions are welcome! Please follow best practices and add tests as necessary.

## License 📄
This project is licensed under the MIT License.

## Color Support 🎨

OneLogger supports ANSI color codes in log messages:
- Console output shows colored messages (when supported)
- File output can strip color codes (configurable via `LOG_STRIP_COLORS`)

### Windows Users
Color support is automatically enabled on Windows 10 and later. For earlier versions, you might need to use Windows Terminal or another terminal that supports ANSI colors.

### Environment Variables
- `LOG_STRIP_COLORS`: Set to "true" to remove color codes from file output (default: "false")
- `NO_COLOR`: Set to any value to disable colors completely

---

Enjoy fast and configurable logging with OneLogger! 🎉