src.common package

Submodules

src.common.base_log module

class src.common.base_log.Log(filename=None, cmdlevel='DEBUG', filelevel='INFO', backup_count=7, limit='20 MB', when=None, colorful=True, compression=None, is_backtrace=True)[源代码]

基类：object

DLT645 库日志封装。

默认不输出任何日志（不挂载 handler）；通过模块级函数 configure_logging() 启用并配置日志。

注意：为保证默认静默，本类在首次创建时会移除 loguru 的默认 stderr handler（ID 0）。若宿主应用依赖 loguru 默认 handler，请在导入本库后自行添加所需的 handler。

set_config(filename=None, cmdlevel='DEBUG', filelevel='INFO', backup_count=7, limit='20 MB', when=None, colorful=True, compression=None)[源代码]

动态修改本实例的日志配置（作为全局未配置时的默认值）。

仅当全局日志已启用时立即生效；否则下次启用时生效。

static set_logger(**kwargs)[源代码]

For backward compatibility.

返回类型:: bool

enable_log()[源代码]

启用本库日志输出（全局开关）。

兼容接口，等价于 :func:`configure_logging`(enabled=True)。

返回类型:: None

disable_log()[源代码]

关闭本库日志输出（全局开关）。

兼容接口，等价于 :func:`configure_logging`(enabled=False)。

返回类型:: None

set_log_level(level, is_console=True, is_file=True)[源代码]

设置日志级别（全局生效）。

参数:

level (str) -- 日志级别（DEBUG/INFO/WARNING/ERROR/CRITICAL）。
is_console (bool) -- 是否应用到控制台输出。
is_file (bool) -- 是否应用到文件输出。

返回:

级别有效返回 True，无效返回 False。

返回类型:

bool

debug(*args, **kwargs)[源代码]

info(*args, **kwargs)[源代码]

warning(*args, **kwargs)[源代码]

error(*args, **kwargs)[源代码]

critical(*args, **kwargs)[源代码]

exception(*args, **kwargs)[源代码]

src.common.base_log.configure_logging(enabled=True, cmdlevel=None, filelevel=None, filename=<object object>, backup_count=None, limit=None, when=None, colorful=None, compression=None, is_backtrace=None)[源代码]

配置 dlt645 库的日志输出。

库默认**不输出任何日志**；调用本函数启用日志或调整日志配置。

参数:

enabled (bool) -- True 启用日志输出，False 关闭（移除所有日志 handler）。
cmdlevel (Optional[str]) -- 控制台日志级别（如 "DEBUG"/"INFO"/"WARNING"/"ERROR"）。 None 表示回退到各模块默认级别。
filelevel (Optional[str]) -- 文件日志级别。None 表示回退到各模块默认级别。
filename (Union[str, None, object]) -- 统一日志文件路径；指定后所有模块日志输出到该文件。传 None 恢复"各模块各自文件"；不传（默认）保持当前配置。
backup_count (Optional[int]) -- 日志文件保留数量（天）。
limit (Union[int, str, None]) -- 单文件大小限制（如 "10 MB"）。
when (Optional[str]) -- 按时间轮转（如 "midnight"、"D"、"H"）。
colorful (Optional[bool]) -- 控制台输出是否带颜色。
compression (Optional[str]) -- 轮转文件压缩格式（如 "zip"）。
is_backtrace (Optional[bool]) -- 是否显示调用位置（文件:函数:行号）。

返回类型:

None

示例:

from dlt645 import configure_logging

# 启用日志，控制台 INFO、文件 DEBUG
configure_logging(cmdlevel="INFO", filelevel="DEBUG")

# 所有日志统一写入指定文件
configure_logging(filename="logs/meter.log")

# 恢复各模块各自文件
configure_logging(filename=None)

# 关闭日志
configure_logging(enabled=False)

src.common.base_log.enable_logging(**kwargs)[源代码]

启用 dlt645 库日志输出（可传 configure_logging() 的参数）。

返回类型:: None

src.common.base_log.disable_logging()[源代码]

关闭 dlt645 库日志输出。

返回类型:: None

src.common.env module

src.common.transform module

数据转换工具模块。

本模块提供了 DLT645 协议所需的各种数据转换功能，包括： - 字节数组与整数/浮点数之间的转换 - BCD 码与数值/字符串之间的转换 - 日期时间与 BCD 码之间的转换 - 十六进制格式化等辅助功能

src.common.transform.pad_with_zeros(length)[源代码]

根据指定长度生成补零字符串。

参数:: length (int) -- 需要生成的零的个数。
返回:: 由指定数量零组成的字符串。
返回类型:: str

src.common.transform.bytes_to_int(byte_array)[源代码]

将字节数组转换为无符号整数。

使用小端序进行转换，如果字节数组长度不足4字节，会在右侧补零至4字节。

参数:: byte_array (bytearray) -- 待转换的字节数组。
返回:: 转换后的无符号整数。
返回类型:: int

src.common.transform.bytes_to_float(byte_array)[源代码]

将字节数组转换为浮点数。

使用小端序进行转换，如果字节数组长度不足4字节，会在右侧补零至4字节。

参数:: byte_array (bytearray) -- 待转换的字节数组。
返回:: 转换后的浮点数。
返回类型:: float

src.common.transform.bytes_to_spaced_hex(data)[源代码]

将字节数组转换为空格分隔的十六进制字符串。

每两个十六进制字符用空格分隔，便于阅读和调试。例如: bytearray([0x68, 0xAA]) -> "68 aa"

参数:: data (bytearray) -- 待转换的字节数组。
返回:: 空格分隔的十六进制字符串。
返回类型:: str

src.common.transform.bcd_to_string(bcd, endian='big')[源代码]

将 BCD 码字节数组转换为数字字符串。

BCD（Binary-Coded Decimal）码是一种用4位二进制数表示十进制数字的编码方式。每个字节包含两个 BCD 数字（高4位和低4位）。

参数:

bcd (bytearray) -- BCD 码字节数组。
endian (str) -- 字节序，"big" 为大端序，"little" 为小端序，默认为 "big"。

返回:

解码后的数字字符串。

返回类型:

str

src.common.transform.parse_format(format_str)[源代码]

解析数据格式字符串，返回小数位数和总位数。

格式字符串示例： - "XXXXXX.XX" -> (2, 8) 表示8位数字，2位小数 - "XXXX.XX" -> (2, 6) 表示6位数字，2位小数 - "XXXXXXXX" -> (0, 8) 表示8位整数，无小数

参数:: format_str (str) -- 格式字符串。
返回:: 元组 (小数位数, 总位数)。
返回类型:: tuple[int, int]
抛出:: ValueError -- 当格式字符串无效时抛出。

src.common.transform.round_float(value, decimal_places)[源代码]

将浮点数四舍五入到指定的小数位数。

参数:

value (float) -- 待四舍五入的浮点数。
decimal_places (int) -- 保留的小数位数。

返回:

四舍五入后的浮点数。

返回类型:

float

src.common.transform.format_float(value, decimal_places, total_digits)[源代码]

格式化浮点数为固定长度字符串（补零对齐）。

参数:

value (float) -- 待格式化的浮点数。
decimal_places (int) -- 小数位数。
total_digits (int) -- 总字符长度（包括小数点）。

返回:

格式化后的字符串。

返回类型:

str

src.common.transform.string_to_bcd(digits, endian='big')[源代码]

将数字字符串转换为 BCD 码字节数组。

如果数字字符串长度为奇数，会在前面补零使其变为偶数长度。

参数:

digits (str) -- 数字字符串（只包含 0-9）。
endian (str) -- 字节序，"big" 为大端序，"little" 为小端序，默认为 "big"。

返回:

BCD 码字节数组。

返回类型:

bytearray

src.common.transform.bcd_to_value(bcd, format_str, endian='big')[源代码]

将 BCD 码字节数组转换为数值。

根据格式字符串决定返回类型： - 如果格式字符串不包含小数点，返回数字字符串 - 如果格式字符串包含小数点，返回浮点数

参数:

bcd (bytearray) -- BCD 码字节数组。
format_str (str) -- 数据格式字符串（如 "XXXXXX.XX"）。
endian (str) -- 字节序，"big" 或 "little"，默认为 "big"。

返回:

解析后的数值（字符串或浮点数）。

返回类型:

Union[str, float]

src.common.transform.float_to_bcd(value, format_str, endian='big')[源代码]

将浮点数转换为 BCD 码字节数组。

支持正负数转换，负数会在最高位设置符号位（0x80）。

参数:

value (float) -- 待转换的浮点数。
format_str (str) -- 数据格式字符串（如 "XXXXXX.XX"）。
endian (str) -- 字节序，"big" 或 "little"，默认为 "big"。

返回:

BCD 码字节数组。

返回类型:

bytearray

src.common.transform.bcd_to_float(bcd, format_str, endian='big')[源代码]

将 BCD 码字节数组转换为浮点数。

支持带符号位的 BCD 码转换，最高位为 0x80 时表示负数。

参数:

bcd (Union[bytearray, bytes]) -- BCD 码字节数组。
format_str (str) -- 数据格式字符串（如 "XXXXXX.XX"）。
endian (str) -- 字节序，"big" 或 "little"，默认为 "big"。

返回:

解析后的浮点数。

返回类型:

float

src.common.transform.datetime_to_bcd(t)[源代码]

将 datetime 对象转换为 BCD 码字节数组（小端序）。

输出格式为：分时日月年（小端序），共5字节。年份只取后两位（如 2025 -> 25）。

参数:: t (datetime) -- datetime 对象。
返回:: BCD 码字节数组，长度为5字节。
返回类型:: bytearray

src.common.transform.bcd_to_byte(b)[源代码]

将单个 BCD 码字节转换为对应的十进制整数。

例如：0x25 -> 25

参数:: b (int) -- BCD 码字节（0x00-0x99）。
返回:: 对应的十进制整数（0-99）。
返回类型:: int

src.common.transform.bcd_to_time(bcd)[源代码]

将 BCD 码字节数组转换为 datetime 对象。

输入格式为：年月日时分（大端序），共5字节。年份假设为21世纪（如 25 -> 2025）。

参数:: bcd (Union[bytearray, bytes]) -- BCD 码字节数组，长度至少为5字节。
返回:: 解析后的 datetime 对象。
返回类型:: datetime
抛出:: ValueError -- 当 BCD 码长度不足5字节时抛出。

src.common.transform.uint8_to_bcd(n)[源代码]

将 0-99 范围内的整数转换为 BCD 码。

例如：25 -> 0x25

参数:: n (int) -- 0-99 范围内的整数。
返回:: 对应的 BCD 码值。
返回类型:: int
抛出:: ValueError -- 当输入不在 0-99 范围内时抛出。

src.common.transform.reverse_bytes(data)[源代码]

反转字节数组的顺序。

用于大小端序之间的转换。

参数:: data (Union[bytearray, bytes]) -- 待反转的字节数组。
返回:: 反转后的字节数组。
返回类型:: bytearray

src.common package

Submodules

src.common.base_log module

src.common.env module

src.common.transform module

Module contents