# logging

Python API: `luxonis_ml.utils.logging`

## 函数

### deprecated

```python
def deprecated(*args: str, suggest: dict[str, str] | None = None, additional_message: str | None = None, altogether: bool = False) -> Callable[[Callable], Callable]:
```

将函数或其参数标记为已弃用。

> **示例**
> ```python
decorator = deprecated(
    "old_arg",
    "another_old_arg",
    suggest={"old_arg": "new_arg"},
    additional_message="不鼓励使用 'old_arg'。",
)

def my_func(old_arg, another_old_arg, new_arg=None):
    pass

my_func = decorator(my_func)
my_func("foo")

# DeprecationWarning: 函数 `my_func` 中的参数 'old_arg' 已弃用，
# 并将在未来版本中移除。
# 请改用 'new_arg'。
# 不鼓励使用 'old_arg'。
```

参数

 * `*args` (`str`): 已弃用参数的名称。
 * `suggest` (`dict[str, str] | None`): 建议的替换参数。
 * `additional_message` (`str | None`): 要附加到警告消息的额外消息。
 * `altogether` (`bool`): 如果为 True，则将整个函数标记为已弃用。

返回

 * `Callable[[Callable], Callable]`: 发出弃用警告的装饰器。

### log_once

```python
def log_once(logger: Callable[[str], None], message: str):
```

仅记录一次消息。

参数

 * `logger` (`Callable[[str], None]`): 要使用的记录器。
 * `message` (`str`): 要记录的消息。

### setup_logging

```python
def setup_logging(*, level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] | None = None, file: PathType | None = None,
use_rich: bool = True, pretty_validation_errors: bool = True, **kwargs):
```

使用 loguru 和 rich 设置全局日志记录。

参数

 * `level` (`Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] | None`): 日志级别。如果未设置，则从环境变量 `LOG_LEVEL` 读取。
 * `file` (`PathType | None`): 日志文件路径。如果提供，日志将保存到此文件。
 * `use_rich` (`bool`): 如果为 True，则使用 rich 进行日志记录。
 * `pretty_validation_errors` (`bool`): 如果为 True，则在未捕获的 pydantic 验证错误后打印可读摘要。
 * `**kwargs`: 传递给 `RichHandler` 的其他关键字参数。

引发

 * `ValueError`: 如果日志级别无效。
