| 1 | <!-- Parent: ../AGENTS.md --> |
| 2 | <!-- Generated: 2026-03-27 | Updated: 2026-03-27 --> |
| 3 | |
| 4 | # utils |
| 5 | |
| 6 | ## Purpose |
| 7 | Shared utility modules — logging setup, URL/filename validation, date/size helpers, cookie parsing, and Douyin anti-bot signature generation (X-Bogus, A-Bogus). |
| 8 | |
| 9 | ## Key Files |
| 10 | |
| 11 | | File | Description | |
| 12 | |------|-------------| |
| 13 | | `__init__.py` | Exports `setup_logger`, `validate_url`, `sanitize_filename`, `parse_timestamp`, `format_size`, `generate_x_bogus`, `XBogus` | |
| 14 | | `logger.py` | Configures per-module loggers with Rich handler; `set_console_log_level()` for runtime control | |
| 15 | | `validators.py` | URL validation and filename sanitization (removes illegal characters) | |
| 16 | | `helpers.py` | `parse_timestamp()` for Douyin timestamps, `format_size()` for human-readable byte sizes | |
| 17 | | `cookie_utils.py` | `parse_cookie_header()` string→dict, `sanitize_cookies()` value cleaning | |
| 18 | | `xbogus.py` | X-Bogus signature generator for Douyin API request signing | |
| 19 | | `abogus.py` | A-Bogus signature generator using SM3 crypto (newer anti-bot mechanism) | |
| 20 | |
| 21 | ## For AI Agents |
| 22 | |
| 23 | ### Working In This Directory |
| 24 | - `setup_logger(name)` is called in every module — returns a named logger with Rich formatting |
| 25 | - `set_console_log_level()` is used by CLI to quiet logs during progress display |
| 26 | - Anti-bot modules (`xbogus.py`, `abogus.py`) implement Douyin's request signing — changes here require careful testing as they affect all API calls |
| 27 | - `cookie_utils.py` is shared by both `auth/` and `config/` |
| 28 | |
| 29 | ### Testing Requirements |
| 30 | - Tests: `tests/test_xbogus.py`, `tests/test_cookie_utils.py` |
| 31 | - Anti-bot signature tests should verify output format, not exact values (signatures change with input) |
| 32 | |
| 33 | ### Common Patterns |
| 34 | - Singleton-style logger per module via `setup_logger()` |
| 35 | - SM3 hashing via `gmssl` for A-Bogus signatures |
| 36 | - Cookie sanitization strips whitespace and empty values |
| 37 | |
| 38 | ## Dependencies |
| 39 | |
| 40 | ### External |
| 41 | - `rich` — log handler formatting |
| 42 | - `gmssl` — SM3/SM4 Chinese crypto standard (for `abogus.py`) |
| 43 | - `python-dateutil` — date parsing in `helpers.py` |
| 44 | |
| 45 | <!-- MANUAL: --> |
| 46 |