https://github.com/bybatkhuu/module-python-logging
'beans-logging' is a python package for simple logger and easily managing logs.
https://github.com/bybatkhuu/module-python-logging
custom-logging log-files logger logging loguru module package pre-defined-configs python
Last synced: 21 days ago
JSON representation
'beans-logging' is a python package for simple logger and easily managing logs.
- Host: GitHub
- URL: https://github.com/bybatkhuu/module-python-logging
- Owner: bybatkhuu
- License: mit
- Created: 2023-09-05T03:36:40.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2026-05-05T13:52:22.000Z (about 2 months ago)
- Last Synced: 2026-05-05T15:40:33.946Z (about 2 months ago)
- Topics: custom-logging, log-files, logger, logging, loguru, module, package, pre-defined-configs, python
- Language: Python
- Homepage: http://pylogging-docs.bybatkhuu.dev/
- Size: 2.79 MB
- Stars: 2
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Python Logging (beans-logging)
[](https://choosealicense.com/licenses/mit)
[](https://github.com/bybatkhuu/module-python-logging/actions/workflows/2.build-publish.yml)
[](https://github.com/bybatkhuu/module-python-logging/releases)
[](https://pypi.org/project/beans-logging)
[](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 -
- 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 virtual 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)
### 2. 📦 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
git clone https://github.com/bybatkhuu/module-python-logging.git && \
cd ./module-python-logging
# 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`**](./examples/simple/configs/logger.yml):
```yaml
logger:
app_name: my-app
level:
base: TRACE
handlers:
file_handler:
enabled: true
err_file_handler:
enabled: true
json_handler:
enabled: true
err_json_handler:
enabled: true
```
[**`main.py`**](./examples/simple/main.py):
```python
#!/usr/bin/env 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:
logger.exception("Show me, what value is wrong:")
```
Run the [**`examples/simple`**](./examples/simple):
```sh
cd ./examples/simple
python ./main.py
```
**Output**:
```txt
[2025-11-01 00:00:00.735 +09:00 | TRACE | beans_logging._intercept:96]: Intercepted modules: ['potato_util._base', 'potato_util.io', 'concurrent', 'concurrent.futures', 'asyncio', 'potato_util.io._sync', 'potato_util']; Muted modules: [];
[2025-11-01 00:00:00.736 +09:00 | TRACE | __main__:6]: Tracing...
[2025-11-01 00:00:00.736 +09:00 | DEBUG | __main__:7]: Debugging...
[2025-11-01 00:00:00.736 +09:00 | INFO | __main__:8]: Logging info.
[2025-11-01 00:00:00.736 +09:00 | OK | __main__:9]: Success.
[2025-11-01 00:00:00.736 +09:00 | WARN | __main__:10]: Warning something.
[2025-11-01 00:00:00.736 +09:00 | ERROR | __main__:11]: Error occured.
[2025-11-01 00:00:00.736 +09:00 | CRIT | __main__:12]: CRITICAL ERROR.
[2025-11-01 00:00:00.736 +09:00 | ERROR | __main__:24]: division by zero
[2025-11-01 00:00:00.737 +09:00 | ERROR | __main__:31]: Show me, what value is wrong:
Traceback (most recent call last):
> File "/home/user/workspaces/projects/my/module-python-logging/examples/simple/./main.py", line 29, in
nested(0)
└
File "/home/user/workspaces/projects/my/module-python-logging/examples/simple/./main.py", line 22, in nested
divide(5, c)
│ └ 0
└
File "/home/user/workspaces/projects/my/module-python-logging/examples/simple/./main.py", line 16, in divide
_result = a / b
│ └ 0
└ 5
ZeroDivisionError: division by zero
```
👍
---
## ⚙️ Configuration
[**`templates/configs/logger.yml`**](./templates/configs/logger.yml):
```yaml
logger:
# app_name: app
level:
base: INFO
err: WARNING
format_str: "[{time:YYYY-MM-DD HH:mm:ss.SSS Z} | {extra[level_short]:<5} | {name}:{line}]: {message}"
file:
logs_dir: "./logs"
rotate_size: 10000000
rotate_time: "00:00:00"
retention: 90
encoding: utf8
use_custom_serialize: false
intercept:
enabled: true
only_base: false
ignore_modules: []
include_modules: []
mute_modules: []
handlers:
std_handler:
enabled: true
h_type: STD
format: "[{time:YYYY-MM-DD HH:mm:ss.SSS Z} | {extra[level_short]:<5} | {name}:{line}]: {message}"
colorize: true
file_handler:
enabled: false
h_type: FILE
sink: "{app_name}.all.log"
err_file_handler:
enabled: false
h_type: FILE
sink: "{app_name}.err.log"
error: true
json_handler:
enabled: false
h_type: FILE
sink: "json/{app_name}.all.json.log"
serialize: true
err_json_handler:
enabled: false
h_type: FILE
sink: "json/{app_name}.err.json.log"
serialize: true
error: true
extra:
```
### 🌎 Environment Variables
[**`.env.example`**](./.env.example):
```sh
# ENV=LOCAL
# DEBUG=false
# TZ=UTC
```
---
## 🧪 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 --livereload
# 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
-
-
-
-
-