Metadata-Version: 2.3
Name: wyl-py-utils
Version: 0.1.0
Summary: A practical Python utility library for strings, dicts and time.
Author: wangyanli02
Author-email: wangyanli02 <wangyanli02@daojia-inc.com>
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# wyl-py-utils

一个实用的 Python 工具库，提供字符串、字典、时间相关的常用工具函数。

## 安装

```bash
pip install wyl-py-utils
# 或者用 uv
uv add wyl-py-utils
```

## 使用

```python
from wyl_py_utils import camel_to_snake, deep_merge, now_str
```

---

## 字符串工具

### `camel_to_snake` - 驼峰转下划线

```python
from wyl_py_utils import camel_to_snake

camel_to_snake("helloWorld")       # 'hello_world'
camel_to_snake("getElementById")   # 'get_element_by_id'
camel_to_snake("HTMLParser")       # 'html_parser'
```

### `snake_to_camel` - 下划线转驼峰

```python
from wyl_py_utils import snake_to_camel

snake_to_camel("hello_world")                    # 'helloWorld'
snake_to_camel("hello_world", upper_first=True)  # 'HelloWorld'（大驼峰）
snake_to_camel("get_element_by_id")              # 'getElementById'
```

### `truncate` - 截断字符串

```python
from wyl_py_utils import truncate

truncate("这是一段很长的文字需要被截断", 5)         # '这是一段很...'
truncate("Hi", 10)                                # 'Hi'（不超长则原样返回）
truncate("Hello World", 5, suffix="…")            # 'Hello…'（自定义省略符）
```

### `random_string` - 生成随机字符串

```python
from wyl_py_utils import random_string

random_string()          # 'aB3kF9xM2pQ7wR1s'（默认16位，字母+数字）
random_string(8)         # 'xK3mP9qW'（指定长度）
random_string(4, "abc")  # 'abca'（指定字符集）
```

### `mask_string` - 字符串脱敏

```python
from wyl_py_utils import mask_string

mask_string("13800138000")                     # '138****8000'
mask_string("wangyanli@example.com", 2, 4)     # 'wa*************m.com'
mask_string("6225880123456789", 4, 4)          # '6225********6789'（银行卡号）
```

---

## 字典工具

### `deep_merge` - 深度合并字典

```python
from wyl_py_utils import deep_merge

deep_merge(
    {"a": 1, "b": {"x": 1}},
    {"b": {"y": 2}, "c": 3}
)
# {'a': 1, 'b': {'x': 1, 'y': 2}, 'c': 3}
```

### `pick` - 挑选指定 key

类似 JS 的 `lodash.pick`

```python
from wyl_py_utils import pick

pick({"a": 1, "b": 2, "c": 3}, ["a", "c"])  # {'a': 1, 'c': 3}
pick({"a": 1}, ["a", "x"])                    # {'a': 1}（不存在的 key 会跳过）
```

### `omit` - 排除指定 key

类似 JS 的 `lodash.omit`

```python
from wyl_py_utils import omit

omit({"a": 1, "b": 2, "c": 3}, ["b"])  # {'a': 1, 'c': 3}
```

### `flatten_dict` - 嵌套字典展平

```python
from wyl_py_utils import flatten_dict

flatten_dict({"a": 1, "b": {"x": 2, "y": {"z": 3}}})
# {'a': 1, 'b.x': 2, 'b.y.z': 3}

flatten_dict({"a": {"b": 1}}, sep="/")  # {'a/b': 1}（自定义分隔符）
```

---

## 时间工具

### `now_str` - 获取当前时间字符串

```python
from wyl_py_utils import now_str

now_str()                          # '2026-04-24 21:00:00'
now_str("%Y/%m/%d")                # '2026/04/24'（自定义格式）
now_str("%H:%M")                   # '21:00'
```

### `timestamp_to_str` - 时间戳转字符串

自动识别秒级和毫秒级时间戳

```python
from wyl_py_utils import timestamp_to_str

timestamp_to_str(1700000000)        # '2023-11-14 22:13:20'（秒级）
timestamp_to_str(1700000000000)     # '2023-11-14 22:13:20'（毫秒级，自动识别）
timestamp_to_str(1700000000, "%Y-%m-%d")  # '2023-11-14'
```

### `str_to_timestamp` - 字符串转时间戳

```python
from wyl_py_utils import str_to_timestamp

str_to_timestamp("2023-11-14 22:13:20")  # 1700000000
```

### `time_ago` - 友好时间展示

类似微博、朋友圈的时间展示

```python
from wyl_py_utils import time_ago
from datetime import datetime, timedelta

time_ago(datetime.now())                                    # '刚刚'
time_ago(datetime.now() - timedelta(minutes=5))             # '5分钟前'
time_ago(datetime.now() - timedelta(hours=3))               # '3小时前'
time_ago(datetime.now() - timedelta(days=7))                # '7天前'
time_ago(1700000000)                                        # '2年前'（支持时间戳）
```

---

## License

MIT
