# SAGE Utils
通用工具库，为SAGE框架提供基础的配置管理、日志记录等功能。
## 功能特性
### 🔧 配置管理 (Config)
- **多格式支持**: 支持YAML、JSON、TOML等配置文件格式
- **智能路径查找**: 支持项目级、用户级、系统级配置文件自动发现
- **环境变量覆盖**: 支持通过环境变量动态覆盖配置项
- **配置验证**: 基于Pydantic的配置项验证和类型检查
- **缓存机制**: 高效的配置加载和缓存策略
### 📝 日志记录 (Logging)
- **多输出目标**: 支持控制台、文件等多种输出目标
- **彩色输出**: 支持不同日志级别的颜色区分
- **IDE友好**: 格式化输出支持IDE点击跳转
- **线程安全**: 全局调试开关的线程安全控制
- **动态配置**: 运行时动态调整日志输出配置
## 安装
```bash
pip install intellistream-sage-utils
```
## 快速开始
### 配置管理
```python
from sage.utils.config.loader import load_config
from sage.utils.config.manager import ConfigManager, BaseConfig
# 简单配置加载
config = load_config("config.yaml") # 自动查找配置文件
# 使用配置管理器
manager = ConfigManager("./config")
config = manager.load("app.yaml")
manager.save("app.yaml", {"key": "value"})
# 使用配置类
class AppConfig(BaseConfig):
app_name: str = "myapp"
debug: bool = False
port: int = 8000
config = AppConfig(app_name="sage", debug=True)
```
### 日志记录
```python
from sage.utils.logging.custom_logger import CustomLogger
# 基本用法
logger = CustomLogger([
("console", "INFO"), # 控制台输出
("app.log", "DEBUG"), # 文件输出(相对路径)
("/tmp/error.log", "ERROR") # 文件输出(绝对路径)
], name="MyApp", log_base_folder="./logs")
logger.info("应用启动")
logger.error("发生错误", exc_info=True)
# 全局调试控制
CustomLogger.disable_global_console_debug() # 关闭所有控制台调试输出
CustomLogger.enable_global_console_debug() # 启用所有控制台调试输出
```
## 模块结构
```
sage/
└── utils/
├── config/
│ ├── __init__.py
│ ├── loader.py # 配置文件加载器
│ └── manager.py # 配置管理器
└── logging/
├── custom_formatter.py # 自定义日志格式化器
└── custom_logger.py # 自定义日志记录器
```
## 配置文件查找优先级
配置加载器按以下优先级查找配置文件：
1. **显式路径**: 直接指定的配置文件路径
2. **环境变量**: `SAGE_CONFIG` 环境变量指定的路径
3. **项目级配置**: `<项目根目录>/config/config.yaml`
4. **用户级配置**: `~/.config/sage/config.yaml`
5. **系统级配置**: `/etc/sage/config.yaml` (Linux/macOS)
## 日志输出格式
日志输出采用IDE友好的两行格式：
```
2024-08-08 10:30:45 | INFO | MyApp | /path/to/file.py:123 →
应用启动成功，监听端口：8000
```
## 开发
### 安装开发依赖
```bash
pip install -e ".[dev]"
```
### 运行测试
```bash
pytest
pytest --cov=sage.utils # 带覆盖率
```
### 代码格式化
```bash
black src/ tests/
isort src/ tests/
flake8 src/ tests/
```
## 许可证
MIT License - 详见 [LICENSE](LICENSE) 文件。
Raw data
{
"_id": null,
"home_page": "https://github.com/intellistream/SAGE",
"name": "intellistream-sage-utils",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "utils, config, logging, intellistream, sage, utilities, configuration, logger",
"author": "IntelliStream Team",
"author_email": "IntelliStream Team <intellistream@outlook.com>",
"download_url": null,
"platform": null,
"description": "# SAGE Utils\n\n\u901a\u7528\u5de5\u5177\u5e93\uff0c\u4e3aSAGE\u6846\u67b6\u63d0\u4f9b\u57fa\u7840\u7684\u914d\u7f6e\u7ba1\u7406\u3001\u65e5\u5fd7\u8bb0\u5f55\u7b49\u529f\u80fd\u3002\n\n## \u529f\u80fd\u7279\u6027\n\n### \ud83d\udd27 \u914d\u7f6e\u7ba1\u7406 (Config)\n- **\u591a\u683c\u5f0f\u652f\u6301**: \u652f\u6301YAML\u3001JSON\u3001TOML\u7b49\u914d\u7f6e\u6587\u4ef6\u683c\u5f0f\n- **\u667a\u80fd\u8def\u5f84\u67e5\u627e**: \u652f\u6301\u9879\u76ee\u7ea7\u3001\u7528\u6237\u7ea7\u3001\u7cfb\u7edf\u7ea7\u914d\u7f6e\u6587\u4ef6\u81ea\u52a8\u53d1\u73b0\n- **\u73af\u5883\u53d8\u91cf\u8986\u76d6**: \u652f\u6301\u901a\u8fc7\u73af\u5883\u53d8\u91cf\u52a8\u6001\u8986\u76d6\u914d\u7f6e\u9879\n- **\u914d\u7f6e\u9a8c\u8bc1**: \u57fa\u4e8ePydantic\u7684\u914d\u7f6e\u9879\u9a8c\u8bc1\u548c\u7c7b\u578b\u68c0\u67e5\n- **\u7f13\u5b58\u673a\u5236**: \u9ad8\u6548\u7684\u914d\u7f6e\u52a0\u8f7d\u548c\u7f13\u5b58\u7b56\u7565\n\n### \ud83d\udcdd \u65e5\u5fd7\u8bb0\u5f55 (Logging)\n- **\u591a\u8f93\u51fa\u76ee\u6807**: \u652f\u6301\u63a7\u5236\u53f0\u3001\u6587\u4ef6\u7b49\u591a\u79cd\u8f93\u51fa\u76ee\u6807\n- **\u5f69\u8272\u8f93\u51fa**: \u652f\u6301\u4e0d\u540c\u65e5\u5fd7\u7ea7\u522b\u7684\u989c\u8272\u533a\u5206\n- **IDE\u53cb\u597d**: \u683c\u5f0f\u5316\u8f93\u51fa\u652f\u6301IDE\u70b9\u51fb\u8df3\u8f6c\n- **\u7ebf\u7a0b\u5b89\u5168**: \u5168\u5c40\u8c03\u8bd5\u5f00\u5173\u7684\u7ebf\u7a0b\u5b89\u5168\u63a7\u5236\n- **\u52a8\u6001\u914d\u7f6e**: \u8fd0\u884c\u65f6\u52a8\u6001\u8c03\u6574\u65e5\u5fd7\u8f93\u51fa\u914d\u7f6e\n\n## \u5b89\u88c5\n\n```bash\npip install intellistream-sage-utils\n```\n\n## \u5feb\u901f\u5f00\u59cb\n\n### \u914d\u7f6e\u7ba1\u7406\n\n```python\nfrom sage.utils.config.loader import load_config\nfrom sage.utils.config.manager import ConfigManager, BaseConfig\n\n# \u7b80\u5355\u914d\u7f6e\u52a0\u8f7d\nconfig = load_config(\"config.yaml\") # \u81ea\u52a8\u67e5\u627e\u914d\u7f6e\u6587\u4ef6\n\n# \u4f7f\u7528\u914d\u7f6e\u7ba1\u7406\u5668\nmanager = ConfigManager(\"./config\")\nconfig = manager.load(\"app.yaml\")\nmanager.save(\"app.yaml\", {\"key\": \"value\"})\n\n# \u4f7f\u7528\u914d\u7f6e\u7c7b\nclass AppConfig(BaseConfig):\n app_name: str = \"myapp\"\n debug: bool = False\n port: int = 8000\n\nconfig = AppConfig(app_name=\"sage\", debug=True)\n```\n\n### \u65e5\u5fd7\u8bb0\u5f55\n\n```python\nfrom sage.utils.logging.custom_logger import CustomLogger\n\n# \u57fa\u672c\u7528\u6cd5\nlogger = CustomLogger([\n (\"console\", \"INFO\"), # \u63a7\u5236\u53f0\u8f93\u51fa\n (\"app.log\", \"DEBUG\"), # \u6587\u4ef6\u8f93\u51fa(\u76f8\u5bf9\u8def\u5f84)\n (\"/tmp/error.log\", \"ERROR\") # \u6587\u4ef6\u8f93\u51fa(\u7edd\u5bf9\u8def\u5f84)\n], name=\"MyApp\", log_base_folder=\"./logs\")\n\nlogger.info(\"\u5e94\u7528\u542f\u52a8\")\nlogger.error(\"\u53d1\u751f\u9519\u8bef\", exc_info=True)\n\n# \u5168\u5c40\u8c03\u8bd5\u63a7\u5236\nCustomLogger.disable_global_console_debug() # \u5173\u95ed\u6240\u6709\u63a7\u5236\u53f0\u8c03\u8bd5\u8f93\u51fa\nCustomLogger.enable_global_console_debug() # \u542f\u7528\u6240\u6709\u63a7\u5236\u53f0\u8c03\u8bd5\u8f93\u51fa\n```\n\n## \u6a21\u5757\u7ed3\u6784\n\n```\nsage/\n\u2514\u2500\u2500 utils/\n \u251c\u2500\u2500 config/\n \u2502 \u251c\u2500\u2500 __init__.py\n \u2502 \u251c\u2500\u2500 loader.py # \u914d\u7f6e\u6587\u4ef6\u52a0\u8f7d\u5668\n \u2502 \u2514\u2500\u2500 manager.py # \u914d\u7f6e\u7ba1\u7406\u5668\n \u2514\u2500\u2500 logging/\n \u251c\u2500\u2500 custom_formatter.py # \u81ea\u5b9a\u4e49\u65e5\u5fd7\u683c\u5f0f\u5316\u5668\n \u2514\u2500\u2500 custom_logger.py # \u81ea\u5b9a\u4e49\u65e5\u5fd7\u8bb0\u5f55\u5668\n```\n\n## \u914d\u7f6e\u6587\u4ef6\u67e5\u627e\u4f18\u5148\u7ea7\n\n\u914d\u7f6e\u52a0\u8f7d\u5668\u6309\u4ee5\u4e0b\u4f18\u5148\u7ea7\u67e5\u627e\u914d\u7f6e\u6587\u4ef6\uff1a\n\n1. **\u663e\u5f0f\u8def\u5f84**: \u76f4\u63a5\u6307\u5b9a\u7684\u914d\u7f6e\u6587\u4ef6\u8def\u5f84\n2. **\u73af\u5883\u53d8\u91cf**: `SAGE_CONFIG` \u73af\u5883\u53d8\u91cf\u6307\u5b9a\u7684\u8def\u5f84\n3. **\u9879\u76ee\u7ea7\u914d\u7f6e**: `<\u9879\u76ee\u6839\u76ee\u5f55>/config/config.yaml`\n4. **\u7528\u6237\u7ea7\u914d\u7f6e**: `~/.config/sage/config.yaml`\n5. **\u7cfb\u7edf\u7ea7\u914d\u7f6e**: `/etc/sage/config.yaml` (Linux/macOS)\n\n## \u65e5\u5fd7\u8f93\u51fa\u683c\u5f0f\n\n\u65e5\u5fd7\u8f93\u51fa\u91c7\u7528IDE\u53cb\u597d\u7684\u4e24\u884c\u683c\u5f0f\uff1a\n\n```\n2024-08-08 10:30:45 | INFO | MyApp | /path/to/file.py:123 \u2192\n \u5e94\u7528\u542f\u52a8\u6210\u529f\uff0c\u76d1\u542c\u7aef\u53e3\uff1a8000\n```\n\n## \u5f00\u53d1\n\n### \u5b89\u88c5\u5f00\u53d1\u4f9d\u8d56\n\n```bash\npip install -e \".[dev]\"\n```\n\n### \u8fd0\u884c\u6d4b\u8bd5\n\n```bash\npytest\npytest --cov=sage.utils # \u5e26\u8986\u76d6\u7387\n```\n\n### \u4ee3\u7801\u683c\u5f0f\u5316\n\n```bash\nblack src/ tests/\nisort src/ tests/\nflake8 src/ tests/\n```\n\n## \u8bb8\u53ef\u8bc1\n\nMIT License - \u8be6\u89c1 [LICENSE](LICENSE) \u6587\u4ef6\u3002\n",
"bugtrack_url": null,
"license": null,
"summary": "SAGE Framework - \u901a\u7528\u5de5\u5177\u5e93\uff0c\u5305\u542b\u914d\u7f6e\u7ba1\u7406\u3001\u65e5\u5fd7\u8bb0\u5f55\u7b49\u57fa\u7840\u529f\u80fd",
"version": "0.1.3",
"project_urls": {
"Bug Tracker": "https://github.com/intellistream/SAGE/issues",
"Documentation": "https://intellistream.github.io/SAGE",
"Homepage": "https://github.com/intellistream/SAGE",
"Repository": "https://github.com/intellistream/SAGE"
},
"split_keywords": [
"utils",
" config",
" logging",
" intellistream",
" sage",
" utilities",
" configuration",
" logger"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1fa2feb88e85b98b2c7141e7c76c77a3694e597d3b52f8499998cfda2492146c",
"md5": "f5393929572a40abd4ce031cd8b33e24",
"sha256": "0c18dbc64320a829782b8965927c7ca7c30eaadb0675e27d6338044cc20bcf89"
},
"downloads": -1,
"filename": "intellistream_sage_utils-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f5393929572a40abd4ce031cd8b33e24",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 91673,
"upload_time": "2025-08-08T11:39:58",
"upload_time_iso_8601": "2025-08-08T11:39:58.720065Z",
"url": "https://files.pythonhosted.org/packages/1f/a2/feb88e85b98b2c7141e7c76c77a3694e597d3b52f8499998cfda2492146c/intellistream_sage_utils-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-08 11:39:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "intellistream",
"github_project": "SAGE",
"github_not_found": true,
"lcname": "intellistream-sage-utils"
}
JSON
