Metadata-Version: 2.1
Name: py-abu
Version: 1.4.0
Summary: A small personal Python utility toolkit for automation scripts
Author-email: Chris <10512@qq.com>
License: MIT
Project-URL: Homepage, https://github.com/ChrisYP/abu
Project-URL: Repository, https://github.com/ChrisYP/abu
Project-URL: Issues, https://github.com/ChrisYP/abu/issues
Keywords: abu,utility,toolkit,crypto,notify
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typing-extensions (>=4.6.0)
Provides-Extra: all
Requires-Dist: cryptography (>=41.0.0) ; extra == 'all'
Requires-Dist: curl-cffi (>=0.5.0) ; extra == 'all'
Requires-Dist: msoffcrypto-tool (>=5.0.0) ; extra == 'all'
Requires-Dist: openpyxl (>=3.1.0) ; extra == 'all'
Requires-Dist: pandas (>=2.0.0) ; extra == 'all'
Requires-Dist: pyperclip (>=1.8.0) ; extra == 'all'
Provides-Extra: clipboard
Requires-Dist: pyperclip (>=1.8.0) ; extra == 'clipboard'
Provides-Extra: crypto
Requires-Dist: cryptography (>=41.0.0) ; extra == 'crypto'
Provides-Extra: dev
Requires-Dist: build (>=1.2.0) ; extra == 'dev'
Requires-Dist: mypy (<1.15,>=1.8.0) ; extra == 'dev'
Requires-Dist: pytest (>=7.4.0) ; extra == 'dev'
Requires-Dist: pytest-cov (>=4.1.0) ; extra == 'dev'
Requires-Dist: ruff (>=0.6.0) ; extra == 'dev'
Requires-Dist: twine (>=5.0.0) ; extra == 'dev'
Provides-Extra: excel
Requires-Dist: msoffcrypto-tool (>=5.0.0) ; extra == 'excel'
Requires-Dist: openpyxl (>=3.1.0) ; extra == 'excel'
Requires-Dist: pandas (>=2.0.0) ; extra == 'excel'
Provides-Extra: notify
Requires-Dist: curl-cffi (>=0.5.0) ; extra == 'notify'

# py-abu

`py-abu` is a small Python utility toolkit for personal automation scripts. It keeps common helpers in one package: text extraction, hashing and AES encryption, TOTP codes, notifications, clipboard utilities, timers, and password-protected Excel reads.

The project is intentionally lightweight. APIs are kept flat so scripts can continue to use simple imports such as `from abu import text_mid`.

## Installation

```bash
pip install py-abu
```

The lightweight base install contains text and TOTP helpers. Install only the
feature groups a script needs:

```bash
pip install "py-abu[crypto,notify]"
pip install "py-abu[excel]"
pip install "py-abu[all]"
```

Available extras are `clipboard`, `crypto`, `excel`, `notify`, and `all`.
Python 3.8+ is supported.

## Quick Start

```python
from abu import VariantAES, get_2fa, text_mid, text_random_str

token = text_mid("token=abc123;", "token=", ";")
name = text_random_str(8)
code = get_2fa("JBSWY3DPEHPK3PXP")

crypto = VariantAES("password")
encrypted = crypto.encrypt("hello")
plain_text = crypto.decrypt(encrypted)
```

## What Is Included

| Area | Helpers |
| --- | --- |
| Text | `text_mid`, `text_mid_batch`, `text_random_str` |
| Crypto | `crypto_md5`, `crypto_sha1`, `crypto_sha256`, `crypto_sha512`, `crypto_hmac_md5`, `VariantAES` |
| 2FA | `get_2fa` |
| Notifications | `send_msg_to_telegram`, `send_msg_to_bark`, `QQ` |
| Excel | `open_excel_with_columns`, `open_excel_single_text` |
| Utilities | `json_to_object`, `flatten_list`, `set_timeout`, clipboard helpers, cookie-to-Chrome helper |

## Examples

### Text Extraction

```python
from abu import text_mid, text_mid_batch

html = "<a>one</a><a>two</a>"

first = text_mid(html, "<a>", "</a>")
all_items = text_mid_batch(html, "<a>", "</a>")
```

### Hashing

```python
from abu import crypto_md5, crypto_sha256, crypto_hmac_md5

crypto_md5("hello")
crypto_sha256("hello")
crypto_hmac_md5("secret", "hello")
```

### AES Encryption

```python
from abu import VariantAES

aes = VariantAES("my-password")
cipher_text = aes.encrypt("private text")
plain_text = aes.decrypt(cipher_text)
```

`VariantAES.encrypt()` returns a versioned AES-GCM hex payload. `decrypt()`
detects modified data and raises `DecryptionError`; legacy CBC payloads from
py-abu 1.3.x remain decryptable.

### Telegram, Bark, And QQ

```python
from abu import QQ, send_msg_to_bark, send_msg_to_telegram

send_msg_to_bark("https://api.day.app/YOUR_KEY", title="Done", body="Task finished")
send_msg_to_telegram("BOT_TOKEN", 123456789, "Task finished")

qq = QQ("http://127.0.0.1:3000", bearer_token="ONEBOT_TOKEN")
qq.send_msg_group_at(123456789, "Task finished", at=[10001, 10002])
```

### Password-Protected Excel

```python
from abu import open_excel_single_text, read_excel_pairs

pairs = read_excel_pairs("secret.xlsx", "password", address_col=0, key_col=1)
first_row = open_excel_single_text("secret.xlsx", "password", lines=2)
```

`read_excel_pairs()` returns structured `ExcelPair(address, key)` values.
`open_excel_with_columns()` remains available for legacy `address----key`
strings. Excel failures now raise `ExcelError` subclasses instead of returning
`None`.

## Compatibility Notes

- Retry-decorated functions re-raise their final exception by default. Pass
  `suppress=True` to retain the old `None` result.
- HTTP notification helpers enforce a timeout and TLS verification.
- `text_mid()` and `text_mid_batch()` reject empty markers.
- `QQ` keeps the historical default bearer token, `"Chris"`.

## Development

```bash
python -m pip install -e ".[all,dev]"
python -m compileall abu
pytest
ruff check abu tests
mypy abu
python -m build
twine check dist/*
```

## License

MIT
