RsLogMod 1.3.0
A versatile logging module for Python projects
License: MIT
Requires Python: >=3.6
Keywords: logging, log rotation, python logging, programmable customization

# RsLogMod


*RsLogMod* is a flexible and powerful Python logging module designed to manage log files with features such as log rotation, customizable paths, and various log levels. It is easy to use yet offers extensive customization options.



## Table of Contents

- [Installation](#installation)
- [Getting Started](#getting-started)
- [Default Behavior](#default-behavior)
- [Log Levels & Prefixes](#log-levels--prefixes)
- [Customization](#customization)
  - [Set Log Folder Path](#set-log-folder-path)
  - [Set Archive Folder Path](#set-archive-folder-path)
  - [Set Maximum Log Size](#set-maximum-log-size)
  - [Enable or Disable Log Rotation](#enable-or-disable-log-rotation)
  - [Enable or Disable Verbose Mode](#enable-or-disable-verbose-mode)
  - [Display Configuration](#display-configuration)
- [Configuration](#configuration)
- [Changelog](#changelog)
- [License](#license)

## Installation

Install RsLogMod using `pip`:

```bash
pip install rslogmod
```

Then import the module:

```python
from RsLogMod import rlog, RsConfig
```

## Getting Started

Here’s a simple example:

```python
from RsLogMod import rlog, RsConfig

# Set log folder path (only needed once, saved in config)
RsConfig.set_log_folder_path('path/to/log/folder')

# Log a message
rlog(log_file_name='my_log', log_level=1, log_entry='This is a log entry.')
```

### Explanation
- **`log_file_name`**: Name of the log file (e.g., `my_log`).
- **`log_level`**: Log level (`1` for INFO, `2` for ERROR, etc.).
- **`log_entry`**: The message to log.
- **`verbose`**: Optionally set `verbose=True` to print the message to the terminal as well.

## Default Behavior

1. **Log Rotation**: Enabled by default (log files rotate when they reach the set max size).
2. **Log to File and Terminal**: Logs are written to the file, and verbose mode controls whether they are printed to the terminal.
3. **Config Persistence**: Once paths are set, they are stored in a config file for future sessions.

## Log Levels & Prefixes

RsLogMod supports the following log levels, each with its own prefix:

- **0**: `[DEBUG]` - Detailed debug information.
- **1**: `[INFO]` - General program execution info.
- **2**: `[ERROR]` - Errors encountered during execution.
- **3**: `[CRITICAL]` - Critical issues that need attention.
- **4**: `[SEC-ALERT]` - Security-related alerts.
- **5**: `[SEC-BREACH]` - Security breaches or serious issues.

## Customization

### Set Log Folder Path

```python
RsConfig.set_log_folder_path('/path/to/logs')
```

### Set Archive Folder Path

```python
RsConfig.set_archive_path('/path/to/archive')
```

### Set Maximum Log Size

```python
RsConfig.set_log_file_max_size(50)  # Max size is set in MB
```

### Enable or Disable Log Rotation

```python
RsConfig.enable_log_rotation(True)  # Enable or disable log rotation
```

### Enable or Disable Verbose Mode

Verbose mode controls whether logs are printed to the terminal. It can be controlled globally via the config or for each individual `rlog()` call.

#### Global Verbose Mode

Enable verbose globally, applying to all future log entries unless overridden:

```python
RsConfig.enable_verbose(True)  # Enable terminal printing for all logs
```

#### Per-Entry Verbose Mode

Control verbosity per log entry by using the `verbose` parameter in `rlog()`:

```python
rlog(log_file_name='my_log', log_level=1, log_entry='This will print to terminal', verbose=True)
```

### Verbose Mode Behavior

- If `verbose` is passed in `rlog()`, it overrides the global config.
- If not passed (`None`), it falls back to the config file setting.
- If both are unset (`None`), logs will only be written to the file.

#### Example Configuration:

```json
{
    "log_rotation": true,
    "verbose": null,
    "max_size_in_mega_bytes": 50,
    "log_folder": "path/to/logs",
    "archive_folder": "path/to/archive"
}
```

- **`"verbose": true`**: Logs print to terminal and file.
- **`"verbose": false`**: Logs are only written to the file.
- **`"verbose": null`**: Behavior is controlled by the individual `rlog()` calls.

### Display Configuration

```python
RsConfig.display()  # Display the current configuration in JSON format
```

## Configuration

RsLogMod stores its settings in a `configs.json` file:

```json
{
  "log_rotation": true,
  "verbose": null,
  "max_size_in_mega_bytes": 50,
  "log_folder": "/path/to/logs",
  "archive_folder": "/path/to/logs/archived"
}
```

- **`log_rotation`**: Enables or disables log rotation.
- **`verbose`**: Controls whether logs are printed to the terminal.
- **`log_folder`**: Directory where logs are saved.
- **`archive_folder`**: Directory where archived logs are stored.


## Changelog

### \[Jun 21, 2025] — v1.2.0

* **Class Rename:** The `Configure` class has been renamed to `RsConfig` for improved clarity and consistency.
* **Backward Compatibility:** The `Configure` class remains fully functional in this version for compatibility.
* **Important:** `Configure` **will be removed in version 2.0.0**.
* **Upgrade Notice:** Update your code to use `RsConfig` before upgrading to version 2.0.0 to avoid breakage.
* **Internal:** All references and docs updated to use `RsConfig`.

## License

This project is licensed under the [MIT License](https://github.com/D-3-X/Rodent-REPO/blob/main/licenses/MIT_License.txt). See the LICENSE file for details.