LogFly 2.5__tar.gz → 2.6.0__tar.gz

logfly-2.6.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: logfly
+Version: 2.6.0
+Summary: A simple log tool by python
+Home-page: https://about.guki.me
+Author: Yuan Sui
+Author-email: orisui@icloud.com
+Project-URL: Github, https://github.com/tinqlo/logfly
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: colorama
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# logfly
+
+一个给 Python 入门项目用的轻量日志工具：一行调用，同时写终端和文件，按天归档。
+
+- 版本：2.6.0
+- Python：>= 3.7
+- 依赖：`colorama`（可选安装，装上后老式 Windows 控制台也能显示颜色）
+
+## 安装
+
+```bash
+pip install -e .
+
+# 需要跑测试时
+pip install -e ".[dev]"
+```
+
+## 快速开始
+
+最简写法，和 2.x 完全一致：
+
+```python
+import logfly
+
+logfly.write_log('app', 'fileCLI', 'info', '程序启动')
+```
+
+同一类日志反复写时，把配置绑一次：
+
+```python
+log = logfly.get_logger(folder_name='myapp')   # 默认同时写终端和文件
+
+log.info('程序启动')
+log.warning('磁盘快满了')
+log.error('请求失败')
+log.success('检查全部通过')
+```
+
+## 日志写在哪
+
+`position` 决定日志出现在哪：
+
+| 取值 | 终端 | 文件 |
+| --- | :---: | :---: |
+| `'CLI'` | 有 | 无 |
+| `'file'` | 无 | 有 |
+| `'fileCLI'` | 有 | 有 |
+
+文件路径：
+
+```
+./logs/<folder_name>/<YYYY-MM-DD>/<name>-<YYYY-MM-DD>.log
+```
+
+`hidden='yes'` 时再存一份到用户主目录：
+
+```
+~/.1o9f1y/<folder_name>/<YYYY-MM-DD>/<name>-<YYYY-MM-DD>.log
+```
+
+## write_log 参数
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `name` | 必填 | 日志文件名，日期和 `.log` 自动拼接 |
+| `position` | 必填 | `'CLI'` / `'file'` / `'fileCLI'` |
+| `level` | 必填 | 自定义级别，写入时转大写并加方括号 |
+| `message` | 必填 | 日志正文 |
+| `mode` | `'add'` | `'add'` 按天追加；`'new'` 每次调用生成新文件（文件名带 `YYYYMMDDHHMMSS`） |
+| `folder_name` | `'default-log'` | `logs` 下的子目录名 |
+| `hidden` | `'no'` | `'yes'` 时在主目录再存一份副本 |
+| `color` | `'yes'` | 终端输出是否带颜色 |
+| `str_message` | `'yes'` | 是否先对 `message` 调用 `str()`；设为 `'no'` 时 `message` 必须是 `str` |
+| `base_dir` | `None` | 日志根目录，默认 `./logs` |
+
+几个补充：
+
+- 所有 `'yes'` / `'no'` 开关也接受 `True` / `False`；`position` 和 `mode` 不区分大小写。
+- 返回写入的日志文件路径；只写终端时返回 `None`。
+- 参数不合法抛 `logfly.ParameterError`（`ValueError` 子类），不再静默返回 `None`。
+
+## 日志格式
+
+文件里每行长这样：
+
+```
+2023-08-07 18:30:05 [INFO] message
+```
+
+终端输出会多带一个文件名：
+
+```
+app 2023-08-07 18:30:05 [INFO] message
+```
+
+文件行尾用 CRLF，和 2.x 生成的日志保持一致，旧日志的解析脚本不用改。
+
+## 其他工具函数
+
+| 函数 | 作用 |
+| --- | --- |
+| `create_or_check_file('file' 或 'path', name, warning='yes')` | 文件/目录不存在就创建；原本已存在时按 `warning` 提示 |
+| `create_log_folder(folder_name, hidden='no', base_dir=None)` | 建好当天要用的日志目录，返回路径 |
+| `mv_file(src, dst, folder_name='mv_file')` | 移动文件并记一条日志 |
+| `run_cmd(cmd, timeout=None, check=False, base_dir=None)` | 执行命令，逐行打印并记录，返回完整标准输出 |
+| `get_time(flag)` | 取 `'datetime'` / `'date'` / `'times'` / `'datetimefile'` / `'timestamp'` |
+| `timestamp_to_datetime(ts)` | 时间戳（秒级或毫秒级）转 `YYYY-MM-DD HH:MM:SS` |
+| `datetime_to_timestamp(s)` | `YYYY-MM-DD HH:MM:SS` 或 `datetime` 对象转时间戳 |
+| `time_transfer(ts, flag)` | 上面两个的 2.x 兼容写法 |
+
+## 2.6 的改动
+
+- **出错抛异常**：参数不合法抛 `ParameterError`，不再打印一行后返回 `None`。旧名 `ParameterERROR` 仍可用。
+- **新增 `base_dir`**：日志目录可配置，测试因此不依赖当前工作目录。
+- **`run_cmd` 返回完整输出**：原来只 `readline()` 一次就返回，多行输出会丢；解码顺序也从 GBK 优先改成 UTF-8 优先，修掉中文乱码。
+- **`create_or_check_file`**：创建成功后不再误报 `already exists`。
+- **`mv_file`**：移动成功记 `info`，原来错记为 `error`。
+- **并发安全**：多线程写同一个文件不会出现半行交错。
+- **路径校验**：`name` / `folder_name` 拒绝 `/`、`\`、`..`，日志不会写到目录外。
+
+刻意保留的行为：`mode='new'` 每次调用覆盖同名文件；隐藏副本始终追加。
+
+## 项目结构
+
+```
+src/logfly/
+├── __init__.py   公开接口（只做导出）
+├── errors.py     ParameterError
+├── options.py    'yes'/'no' 与固定取值的校验
+├── clock.py      时间格式化与时间戳换算
+├── sinks.py      把一行日志写到终端或文件
+├── logger.py     路径解析 + 写入编排（核心）
+└── tools.py      建文件/目录、移动文件、执行命令
+tests/
+└── test_logfly.py
+```
+
+## 运行测试
+
+```bash
+pytest
+```
+
+## 许可证
+
+MIT

logfly-2.6.0/README.md

@@ -0,0 +1,146 @@
+# logfly
+
+一个给 Python 入门项目用的轻量日志工具：一行调用，同时写终端和文件，按天归档。
+
+- 版本：2.6.0
+- Python：>= 3.7
+- 依赖：`colorama`（可选安装，装上后老式 Windows 控制台也能显示颜色）
+
+## 安装
+
+```bash
+pip install -e .
+
+# 需要跑测试时
+pip install -e ".[dev]"
+```
+
+## 快速开始
+
+最简写法，和 2.x 完全一致：
+
+```python
+import logfly
+
+logfly.write_log('app', 'fileCLI', 'info', '程序启动')
+```
+
+同一类日志反复写时，把配置绑一次：
+
+```python
+log = logfly.get_logger(folder_name='myapp')   # 默认同时写终端和文件
+
+log.info('程序启动')
+log.warning('磁盘快满了')
+log.error('请求失败')
+log.success('检查全部通过')
+```
+
+## 日志写在哪
+
+`position` 决定日志出现在哪：
+
+| 取值 | 终端 | 文件 |
+| --- | :---: | :---: |
+| `'CLI'` | 有 | 无 |
+| `'file'` | 无 | 有 |
+| `'fileCLI'` | 有 | 有 |
+
+文件路径：
+
+```
+./logs/<folder_name>/<YYYY-MM-DD>/<name>-<YYYY-MM-DD>.log
+```
+
+`hidden='yes'` 时再存一份到用户主目录：
+
+```
+~/.1o9f1y/<folder_name>/<YYYY-MM-DD>/<name>-<YYYY-MM-DD>.log
+```
+
+## write_log 参数
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `name` | 必填 | 日志文件名，日期和 `.log` 自动拼接 |
+| `position` | 必填 | `'CLI'` / `'file'` / `'fileCLI'` |
+| `level` | 必填 | 自定义级别，写入时转大写并加方括号 |
+| `message` | 必填 | 日志正文 |
+| `mode` | `'add'` | `'add'` 按天追加；`'new'` 每次调用生成新文件（文件名带 `YYYYMMDDHHMMSS`） |
+| `folder_name` | `'default-log'` | `logs` 下的子目录名 |
+| `hidden` | `'no'` | `'yes'` 时在主目录再存一份副本 |
+| `color` | `'yes'` | 终端输出是否带颜色 |
+| `str_message` | `'yes'` | 是否先对 `message` 调用 `str()`；设为 `'no'` 时 `message` 必须是 `str` |
+| `base_dir` | `None` | 日志根目录，默认 `./logs` |
+
+几个补充：
+
+- 所有 `'yes'` / `'no'` 开关也接受 `True` / `False`；`position` 和 `mode` 不区分大小写。
+- 返回写入的日志文件路径；只写终端时返回 `None`。
+- 参数不合法抛 `logfly.ParameterError`（`ValueError` 子类），不再静默返回 `None`。
+
+## 日志格式
+
+文件里每行长这样：
+
+```
+2023-08-07 18:30:05 [INFO] message
+```
+
+终端输出会多带一个文件名：
+
+```
+app 2023-08-07 18:30:05 [INFO] message
+```
+
+文件行尾用 CRLF，和 2.x 生成的日志保持一致，旧日志的解析脚本不用改。
+
+## 其他工具函数
+
+| 函数 | 作用 |
+| --- | --- |
+| `create_or_check_file('file' 或 'path', name, warning='yes')` | 文件/目录不存在就创建；原本已存在时按 `warning` 提示 |
+| `create_log_folder(folder_name, hidden='no', base_dir=None)` | 建好当天要用的日志目录，返回路径 |
+| `mv_file(src, dst, folder_name='mv_file')` | 移动文件并记一条日志 |
+| `run_cmd(cmd, timeout=None, check=False, base_dir=None)` | 执行命令，逐行打印并记录，返回完整标准输出 |
+| `get_time(flag)` | 取 `'datetime'` / `'date'` / `'times'` / `'datetimefile'` / `'timestamp'` |
+| `timestamp_to_datetime(ts)` | 时间戳（秒级或毫秒级）转 `YYYY-MM-DD HH:MM:SS` |
+| `datetime_to_timestamp(s)` | `YYYY-MM-DD HH:MM:SS` 或 `datetime` 对象转时间戳 |
+| `time_transfer(ts, flag)` | 上面两个的 2.x 兼容写法 |
+
+## 2.6 的改动
+
+- **出错抛异常**：参数不合法抛 `ParameterError`，不再打印一行后返回 `None`。旧名 `ParameterERROR` 仍可用。
+- **新增 `base_dir`**：日志目录可配置，测试因此不依赖当前工作目录。
+- **`run_cmd` 返回完整输出**：原来只 `readline()` 一次就返回，多行输出会丢；解码顺序也从 GBK 优先改成 UTF-8 优先，修掉中文乱码。
+- **`create_or_check_file`**：创建成功后不再误报 `already exists`。
+- **`mv_file`**：移动成功记 `info`，原来错记为 `error`。
+- **并发安全**：多线程写同一个文件不会出现半行交错。
+- **路径校验**：`name` / `folder_name` 拒绝 `/`、`\`、`..`，日志不会写到目录外。
+
+刻意保留的行为：`mode='new'` 每次调用覆盖同名文件；隐藏副本始终追加。
+
+## 项目结构
+
+```
+src/logfly/
+├── __init__.py   公开接口（只做导出）
+├── errors.py     ParameterError
+├── options.py    'yes'/'no' 与固定取值的校验
+├── clock.py      时间格式化与时间戳换算
+├── sinks.py      把一行日志写到终端或文件
+├── logger.py     路径解析 + 写入编排（核心）
+└── tools.py      建文件/目录、移动文件、执行命令
+tests/
+└── test_logfly.py
+```
+
+## 运行测试
+
+```bash
+pytest
+```
+
+## 许可证
+
+MIT

logfly-2.6.0/pyproject.toml

@@ -0,0 +1,10 @@
+[build-system]
+requires = [
+    "setuptools>=42",
+    "wheel"
+]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+# 让在仓库根目录直接运行 `pytest` 时只收集 tests/ 下的测试
+testpaths = ["tests"]

{logfly-2.5 → logfly-2.6.0}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setuptools.setup(
     name="logfly",
-    version="2.5",
+    version="2.6.0",
     author="Yuan Sui",
     author_email="orisui@icloud.com",
     description="A simple log tool by python",
@@ -22,6 +22,7 @@ setuptools.setup(
     ],
     package_dir={"": "src"},
     packages=setuptools.find_packages(where="src"),
-    python_requires=">=3.6",
-    install_requires=['colorama']
+    python_requires=">=3.7",
+    install_requires=['colorama'],
+    extras_require={"dev": ["pytest"]},
 )

logfly-2.6.0/src/logfly/__init__.py

@@ -0,0 +1,89 @@
+#####################
+# Author: Yuki Sui
+# Date: 2023-8-7
+#####################
+"""logfly —— 给 Python 入门项目用的简易日志工具。
+
+模块分工::
+
+    logfly.errors    异常类型
+    logfly.options   'yes'/'no' 与固定取值的校验
+    logfly.clock     时间格式化与时间戳换算
+    logfly.sinks     把一行日志写到终端或文件
+    logfly.logger    路径解析 + 写入编排（核心）
+    logfly.tools     建文件/目录、移动文件、执行命令
+
+2.x 的调用方式全部保留::
+
+    import logfly
+    logfly.write_log('name', 'fileCLI', 'info', 'hello')
+
+新增的写法（推荐）::
+
+    log = logfly.get_logger(folder_name='myapp')
+    log.info('程序启动')
+"""
+
+from .clock import (
+    format_compact,
+    format_date,
+    format_datetime,
+    format_time,
+    get_time,
+    time_transfer,
+    timestamp_to_datetime,
+    datetime_to_timestamp,
+)
+from .errors import ParameterERROR, ParameterError
+from .logger import (
+    DEFAULT_FOLDER,
+    DEFAULT_LOG_DIR,
+    HIDDEN_DIR,
+    LOG_FILE_STEM,
+    Logger,
+    create_log_folder,
+    get_logger,
+    hidden_root,
+    log_root,
+    write_log,
+)
+from .sinks import HAS_COLORAMA
+from .tools import create_or_check_file, error, mv_file, run_cmd
+
+__version__ = '2.6.0'
+#: 2.x 的旧变量名，表示 colorama 是否可用。
+__colorama_init__ = HAS_COLORAMA
+
+__all__ = [
+    # 主接口
+    'write_log',
+    'get_logger',
+    'Logger',
+    # 工具
+    'create_or_check_file',
+    'create_log_folder',
+    'mv_file',
+    'run_cmd',
+    'error',
+    # 时间
+    'get_time',
+    'time_transfer',
+    'format_datetime',
+    'format_date',
+    'format_time',
+    'format_compact',
+    'timestamp_to_datetime',
+    'datetime_to_timestamp',
+    # 路径
+    'log_root',
+    'hidden_root',
+    # 常量与异常
+    'DEFAULT_FOLDER',
+    'DEFAULT_LOG_DIR',
+    'HIDDEN_DIR',
+    'LOG_FILE_STEM',
+    'ParameterError',
+    'ParameterERROR',
+    'HAS_COLORAMA',
+    '__version__',
+]

logfly-2.6.0/src/logfly/clock.py

@@ -0,0 +1,120 @@
+"""时间格式化与时间戳换算。
+
+2.x 用一条 ``flag`` 字符串在 ``get_time`` / ``time_transfer`` 里分支，
+拼错时同样静默返回 ``None``（于是 ``'\\\\.1o9f1y\\\\' + None`` 才炸）。
+这里改成分工明确的小函数，非法输入立刻抛异常；
+``get_time`` / ``time_transfer`` 作为兼容包装保留下来。
+"""
+
+import time
+
+from .errors import ParameterError
+
+#: 写进日志文件的时间格式，例如 ``2023-08-07 18:30:05``。
+DATETIME_FORMAT = '%Y-%m-%d %H:%M:%S'
+#: 日期目录名，例如 ``2023-08-07``。
+DATE_FORMAT = '%Y-%m-%d'
+#: 只到秒的时间，例如 ``18:30:05``。
+TIME_FORMAT = '%H:%M:%S'
+#: ``mode='new'`` 时用的紧凑时间，例如 ``20230807183005``。
+COMPACT_FORMAT = '%Y%m%d%H%M%S'
+
+#: 时间戳超过这个量级就当作毫秒。
+#: 2.x 用 ``len(str(ts)) == 13`` 判断，2033 年之后 10 位秒级时间戳会变成
+#: 11 位，那种长度判断就失效了；按数值判断不会过时。
+_MILLISECOND_THRESHOLD = 1e11
+
+
+def format_datetime(when=None):
+    """返回 ``YYYY-MM-DD HH:MM:SS``。``when`` 为空表示当前时间。"""
+    return time.strftime(DATETIME_FORMAT, time.localtime(when))
+
+
+def format_date(when=None):
+    """返回 ``YYYY-MM-DD``，用于日志目录名。"""
+    return time.strftime(DATE_FORMAT, time.localtime(when))
+
+
+def format_time(when=None):
+    """返回 ``HH:MM:SS``。"""
+    return time.strftime(TIME_FORMAT, time.localtime(when))
+
+
+def format_compact(when=None):
+    """返回 ``YYYYMMDDHHMMSS``，用于 ``mode='new'`` 的文件名。"""
+    return time.strftime(COMPACT_FORMAT, time.localtime(when))
+
+
+def timestamp():
+    """返回当前 Unix 时间戳（浮点秒）。"""
+    return time.time()
+
+
+def _to_seconds(value):
+    """把秒级或毫秒级时间戳统一成秒。"""
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        raise ParameterError(
+            '参数 time_stamp 必须是数字（秒级或毫秒级时间戳），收到 {0!r}'.format(value)
+        )
+    if abs(number) >= _MILLISECOND_THRESHOLD:
+        number /= 1000.0
+    return number
+
+
+def timestamp_to_datetime(value):
+    """秒级 / 毫秒级时间戳 -> ``YYYY-MM-DD HH:MM:SS``。"""
+    return time.strftime(DATETIME_FORMAT, time.localtime(_to_seconds(value)))
+
+
+def datetime_to_timestamp(value):
+    """``YYYY-MM-DD HH:MM:SS`` -> 秒级时间戳。
+
+    也接受 :class:`datetime.datetime` 对象，省得调用方自己转字符串。
+    """
+    if hasattr(value, 'timetuple'):  # datetime / date 对象
+        return time.mktime(value.timetuple())
+    if isinstance(value, str):
+        try:
+            return time.mktime(time.strptime(value, DATETIME_FORMAT))
+        except ValueError:
+            raise ParameterError(
+                '参数 time_stamp 必须形如 "2023-08-07 18:30:05"，收到 {0!r}'.format(value)
+            )
+    raise ParameterError(
+        '参数 time_stamp 必须是 "YYYY-MM-DD HH:MM:SS" 字符串或 datetime，收到 {0!r}'.format(value)
+    )
+
+
+def get_time(flag):
+    """2.x 兼容接口：按 ``flag`` 取不同粒度的时间。
+
+    支持 ``'datetime'`` / ``'date'`` / ``'times'`` / ``'datetimefile'`` /
+    ``'timestamp'``。新代码建议直接调用上面那些具体函数。
+    """
+    if flag == 'datetime':
+        return format_datetime()
+    if flag == 'date':
+        return format_date()
+    if flag == 'times':
+        return format_time()
+    if flag == 'datetimefile':
+        return format_compact()
+    if flag == 'timestamp':
+        return timestamp()
+    raise ParameterError(
+        '参数 flag 必须是 "datetime" / "date" / "times" / "datetimefile" / "timestamp" 之一，'
+        '收到 {0!r}'.format(flag)
+    )
+
+
+def time_transfer(time_stamp, flag='timestamp2datetime'):
+    """2.x 兼容接口：时间戳与日期时间字符串互转。"""
+    if flag == 'timestamp2datetime':
+        return timestamp_to_datetime(time_stamp)
+    if flag == 'datetime2timestamp':
+        return datetime_to_timestamp(time_stamp)
+    raise ParameterError(
+        '参数 flag 必须是 "timestamp2datetime" 或 "datetime2timestamp"，收到 {0!r}'.format(flag)
+    )

logfly-2.6.0/src/logfly/errors.py

@@ -0,0 +1,22 @@
+"""logfly 用到的异常类型。
+
+单独一个模块，是为了让 options / clock / logger 这些模块都能引用它，
+又不会互相 import 成环。
+"""
+
+
+class ParameterError(ValueError):
+    """参数不合法时抛出。
+
+    继承 ``ValueError`` 有两个好处：
+
+    * 想精确处理时用 ``except ParameterError``；
+    * 想粗略兜住时 ``except ValueError`` 也能捕获，和 Python 内建习惯一致。
+
+    2.x 里参数错了只是打印一行错误然后返回 ``None``，调用方无法判断成败。
+    现在统一抛异常，让错误在调用处立刻暴露。
+    """
+
+
+#: 2.x 的旧名字（全大写），保留一个别名，老代码 ``except logfly.ParameterERROR`` 仍然有效。
+ParameterERROR = ParameterError