beans-logging 5.0.0__tar.gz → 6.0.1__tar.gz

beans_logging-6.0.1/.python-version

@@ -0,0 +1 @@
+3.10

{beans_logging-5.0.0 → beans_logging-6.0.1}/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Batkhuu Byambajav
+Copyright (c) 2025 Batkhuu Byambajav
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

beans_logging-6.0.1/PKG-INFO

@@ -0,0 +1,419 @@
+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>