Metadata-Version: 2.4
Name: beans_logging
Version: 6.0.1
Summary: 'beans-logging' is a python package for simple logger and easily managing logging.
Author-email: Batkhuu Byambajav <batkhuu10@gmail.com>
Project-URL: Homepage, https://github.com/bybatkhuu/module-python-logging
Project-URL: Documentation, https://pylogging-docs.bybatkhuu.dev
Project-URL: Repository, https://github.com/bybatkhuu/module-python-logging.git
Project-URL: Issues, https://github.com/bybatkhuu/module-python-logging/issues
Project-URL: Changelog, https://github.com/bybatkhuu/module-python-logging/blob/main/CHANGELOG.md
Keywords: beans_logging,loguru,logging,logger,logs,python-logging,custom-logging
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <4.0,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: PyYAML<7.0,>=6.0.2
Requires-Dist: pydantic[timezone]!=2.1.0,<3.0.0,>=2.0.3
Requires-Dist: loguru<1.0.0,>=0.7.3
Provides-Extra: fastapi
Requires-Dist: beans-logging-fastapi<2.0.0,>=1.0.0; extra == "fastapi"
Provides-Extra: test
Requires-Dist: pytest<9.0.0,>=8.0.2; extra == "test"
Requires-Dist: pytest-cov<8.0.0,>=5.0.0; extra == "test"
Requires-Dist: pytest-xdist<4.0.0,>=3.6.1; extra == "test"
Requires-Dist: pytest-benchmark<6.0.0,>=5.0.1; extra == "test"
Provides-Extra: build
Requires-Dist: setuptools<81.0.0,>=70.3.0; extra == "build"
Requires-Dist: wheel<1.0.0,>=0.43.0; extra == "build"
Requires-Dist: build<2.0.0,>=1.1.1; extra == "build"
Requires-Dist: twine<7.0.0,>=6.0.1; extra == "build"
Provides-Extra: docs
Requires-Dist: pylint<4.0.0,>=3.0.4; extra == "docs"
Requires-Dist: mkdocs-material<10.0.0,>=9.5.50; extra == "docs"
Requires-Dist: mkdocs-awesome-nav<4.0.0,>=3.0.0; extra == "docs"
Requires-Dist: mkdocstrings[python]<1.0.0,>=0.24.3; extra == "docs"
Requires-Dist: mike<3.0.0,>=2.1.3; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest<9.0.0,>=8.0.2; extra == "dev"
Requires-Dist: pytest-cov<8.0.0,>=5.0.0; extra == "dev"
Requires-Dist: pytest-xdist<4.0.0,>=3.6.1; extra == "dev"
Requires-Dist: pytest-benchmark<6.0.0,>=5.0.1; extra == "dev"
Requires-Dist: setuptools<81.0.0,>=70.3.0; extra == "dev"
Requires-Dist: wheel<1.0.0,>=0.43.0; extra == "dev"
Requires-Dist: build<2.0.0,>=1.1.1; extra == "dev"
Requires-Dist: twine<7.0.0,>=6.0.1; extra == "dev"
Requires-Dist: pylint<4.0.0,>=3.0.4; extra == "dev"
Requires-Dist: mkdocs-material<10.0.0,>=9.5.50; extra == "dev"
Requires-Dist: mkdocs-awesome-nav<4.0.0,>=3.0.0; extra == "dev"
Requires-Dist: mkdocstrings[python]<1.0.0,>=0.24.3; extra == "dev"
Requires-Dist: mike<3.0.0,>=2.1.3; extra == "dev"
Requires-Dist: pyright<2.0.0,>=1.1.392; extra == "dev"
Requires-Dist: pre-commit<5.0.0,>=4.0.1; extra == "dev"
Dynamic: license-file

# Python Logging (beans-logging)

[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit)
[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/bybatkhuu/module-python-logging/2.build-publish.yml?logo=GitHub)](https://github.com/bybatkhuu/module-python-logging/actions/workflows/2.build-publish.yml)
[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/bybatkhuu/module-python-logging?logo=GitHub&color=blue)](https://github.com/bybatkhuu/module-python-logging/releases)
[![PyPI](https://img.shields.io/pypi/v/beans-logging?logo=PyPi)](https://pypi.org/project/beans-logging)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/beans-logging?logo=Python)](https://docs.conda.io/en/latest/miniconda.html)

`beans-logging` is a python package for simple logger and easily managing logs.

It is a `Loguru` based custom logging package for python projects.

## ✨ Features

- Main **logger** based on **Loguru** logging - <https://pypi.org/project/loguru>
- Logging to **log files** (all, error, json)
- **Pre-defined** logging configs and handlers
- **Colorful** logging
- Auto **intercepting** and **muting** modules
- Load config from **YAML** or **JSON** file
- Custom options as a **config**
- Custom logging **formats**
- **Multiprocess** compatibility (Linux, macOS - 'fork')
- Add custom **handlers**
- **Base** logging module

---

## 🛠 Installation

### 1. 🚧 Prerequisites

- Install **Python (>= v3.10)** and **pip (>= 23)**:
    - **[RECOMMENDED] [Miniconda (v3)](https://www.anaconda.com/docs/getting-started/miniconda/install)**
    - *[arm64/aarch64] [Miniforge (v3)](https://github.com/conda-forge/miniforge)*
    - *[Python virutal environment] [venv](https://docs.python.org/3/library/venv.html)*

[OPTIONAL] For **DEVELOPMENT** environment:

- Install [**git**](https://git-scm.com/downloads)
- Setup an [**SSH key**](https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh) ([video tutorial](https://www.youtube.com/watch?v=snCP3c7wXw0))

### 2. 📥 Download or clone the repository

[TIP] Skip this step, if you're going to install the package directly from **PyPi** or **GitHub** repository.

**2.1.** Prepare projects directory (if not exists):

```sh
# Create projects directory:
mkdir -pv ~/workspaces/projects

# Enter into projects directory:
cd ~/workspaces/projects
```

**2.2.** Follow one of the below options **[A]**, **[B]** or **[C]**:

**OPTION A.** Clone the repository:

```sh
git clone https://github.com/bybatkhuu/module-python-logging.git && \
    cd module-python-logging
```

**OPTION B.** Clone the repository (for **DEVELOPMENT**: git + ssh key):

```sh
git clone git@github.com:bybatkhuu/module-python-logging.git && \
    cd module-python-logging
```

**OPTION C.** Download source code:

1. Download archived **zip** file from [**releases**](https://github.com/bybatkhuu/module-python-logging/releases).
2. Extract it into the projects directory.

### 3. 📦 Install the package

[NOTE] Choose one of the following methods to install the package **[A ~ F]**:

**OPTION A.** [**RECOMMENDED**] Install from **PyPi**:

```sh
pip install -U beans-logging
```

**OPTION B.** Install latest version directly from **GitHub** repository:

```sh
pip install git+https://github.com/bybatkhuu/module-python-logging.git
```

**OPTION C.** Install from the downloaded **source code**:

```sh
# Install directly from the source code:
pip install .

# Or install with editable mode:
pip install -e .
```

**OPTION D.** Install for **DEVELOPMENT** environment:

```sh
pip install -e .[dev]

# Install pre-commit hooks:
pre-commit install
```

**OPTION E.** Install from **pre-built release** files:

1. Download **`.whl`** or **`.tar.gz`** file from [**releases**](https://github.com/bybatkhuu/module-python-logging/releases)
2. Install with pip:

```sh
# Install from .whl file:
pip install ./beans_logging-[VERSION]-py3-none-any.whl

# Or install from .tar.gz file:
pip install ./beans_logging-[VERSION].tar.gz
```

**OPTION F.** Copy the **module** into the project directory (for **testing**):

```sh
# Install python dependencies:
pip install -r ./requirements.txt

# Copy the module source code into the project:
cp -r ./src/beans_logging [PROJECT_DIR]
# For example:
cp -r ./src/beans_logging /some/path/project/
```

## 🚸 Usage/Examples

To use `beans_logging`, import the `logger` instance from the `beans_logging.auto` package:

```python
from beans_logging.auto import logger
```

You can call logging methods directly from the `logger` instance:

```python
logger.info("Logging info.")
```

### **Simple**

[**`configs/logger.yml`**](https://github.com/bybatkhuu/module-python-logging/blob/main/examples/simple/configs/logger.yml):

```yml
logger:
  app_name: "my-app"
  level: "TRACE"
  file:
    log_handlers:
      enabled: true
    json_handlers:
      enabled: true
```

[**`main.py`**](https://github.com/bybatkhuu/module-python-logging/blob/main/examples/simple/main.py):

```python
from beans_logging.auto import logger


logger.trace("Tracing...")
logger.debug("Debugging...")
logger.info("Logging info.")
logger.success("Success.")
logger.warning("Warning something.")
logger.error("Error occured.")
logger.critical("CRITICAL ERROR.")

def divide(a, b):
    _result = a / b
    return _result

def nested(c):
    try:
        divide(5, c)
    except ZeroDivisionError as err:
        logger.error(err)
        raise

try:
    nested(0)
except Exception as err:
    logger.exception("Show me, what value is wrong:")
```

Run the [**`examples/simple`**](https://github.com/bybatkhuu/module-python-logging/tree/main/examples/simple):

```sh
cd ./examples/simple

python ./main.py
```

**Output**:

```txt
[2023-09-01 00:00:00.000 +09:00 | TRACE | beans_logging._base:478]: Intercepted modules: ['concurrent', 'concurrent.futures', 'asyncio']; Muted modules: [];
[2023-09-01 00:00:00.000 +09:00 | TRACE | __main__:7]: Tracing...
[2023-09-01 00:00:00.000 +09:00 | DEBUG | __main__:8]: Debugging...
[2023-09-01 00:00:00.000 +09:00 | INFO  | __main__:9]: Logging info.
[2023-09-01 00:00:00.000 +09:00 | OK    | __main__:10]: Success.
[2023-09-01 00:00:00.000 +09:00 | WARN  | __main__:11]: Warning something.
[2023-09-01 00:00:00.000 +09:00 | ERROR | __main__:12]: Error occured.
[2023-09-01 00:00:00.000 +09:00 | CRIT  | __main__:13]: CRITICAL ERROR.
[2023-09-01 00:00:00.000 +09:00 | ERROR | __main__:25]: division by zero
[2023-09-01 00:00:00.000 +09:00 | ERROR | __main__:32]: Show me, what value is wrong:
Traceback (most recent call last):

> File "/home/user/workspaces/projects/beans_logging/examples/simple/./main.py", line 30, in <module>
    nested(0)
    └ <function nested at 0x10802a4c0>

  File "/home/user/workspaces/projects/beans_logging/examples/simple/./main.py", line 23, in nested
    divide(5, c)
    │         └ 0
    └ <function divide at 0x1052f31f0>

  File "/home/user/workspaces/projects/beans_logging/examples/simple/./main.py", line 17, in divide
    _result = a / b
              │   └ 0
              └ 5

ZeroDivisionError: division by zero
```

👍

---

## ⚙️ Configuration

[**`templates/configs/config.yml`**](./templates/configs/config.yml):

```yaml
logger:
  # app_name: "app"
  level: "INFO"
  use_diagnose: false
  stream:
    use_color: true
    use_icon: false
    format_str: "[<c>{time:YYYY-MM-DD HH:mm:ss.SSS Z}</c> | <level>{level_short:<5}</level> | <w>{name}:{line}</w>]: <level>{message}</level>"
    std_handler:
      enabled: true
  file:
    logs_dir: "./logs"
    rotate_size: 10000000 # 10MB
    rotate_time: "00:00:00"
    backup_count: 90
    log_handlers:
      enabled: false
      format_str: "[{time:YYYY-MM-DD HH:mm:ss.SSS Z} | {level_short:<5} | {name}:{line}]: {message}"
      log_path: "{app_name}.std.all.log"
      err_path: "{app_name}.std.err.log"
    json_handlers:
      enabled: false
      use_custom: false
      log_path: "{app_name}.json.all.log"
      err_path: "{app_name}.json.err.log"
  intercept:
    auto_load:
      enabled: true
      only_base: false
      ignore_modules: []
    include_modules: []
    mute_modules: []
  extra:
```

### 🌎 Environment Variables

[**`.env.example`**](./.env.example):

```sh
# ENV=LOCAL
# DEBUG=false
# TZ=UTC

# BEANS_LOGGING_DISABLE_DEFAULT=false
# BEANS_LOGGING_CONFIG_PATH="./configs/logger.yml"
# BEANS_LOGGING_LOGS_DIR="./logs"
```

---

## 🧪 Running Tests

To run tests, run the following command:

```sh
# Install python test dependencies:
pip install .[test]

# Run tests:
python -m pytest -sv -o log_cli=true
# Or use the test script:
./scripts/test.sh -l -v -c
```

## 🏗️ Build Package

To build the python package, run the following command:

```sh
# Install python build dependencies:
pip install -r ./requirements/requirements.build.txt

# Build python package:
python -m build
# Or use the build script:
./scripts/build.sh
```

## 📝 Generate Docs

To build the documentation, run the following command:

```sh
# Install python documentation dependencies:
pip install -r ./requirements/requirements.docs.txt

# Serve documentation locally (for development):
mkdocs serve -a 0.0.0.0:8000
# Or use the docs script:
./scripts/docs.sh

# Or build documentation:
mkdocs build
# Or use the docs script:
./scripts/docs.sh -b
```

## 📚 Documentation

- [Docs](./docs)

---

## 📑 References

- <https://github.com/Delgan/loguru>
- <https://loguru.readthedocs.io/en/stable/api/logger.html>
- <https://loguru.readthedocs.io/en/stable/resources/recipes.html>
- <https://docs.python.org/3/library/logging.html>
- <https://github.com/bybatkhuu/module-fastapi-logging>
