Metadata-Version: 2.4
Name: python-library-patch-jack
Version: 0.1.1
Requires-Python: >=3.10
Requires-Dist: aiohttp<4,>=3.9
Requires-Dist: msgpack<2,>=1
Requires-Dist: pydantic<3,>=2
Provides-Extra: integration
Requires-Dist: python-library-patch-bay==0.1.8; extra == 'integration'
Provides-Extra: rich
Requires-Dist: rich>=13; extra == 'rich'
Description-Content-Type: text/markdown

# patch_jack

> **一句话**：你在本机开个端口等人连；外面的交换程序按自己的配置主动连上来。连上之后怎么转发、走哪条线，都由交换程序决定，本库帮你处理「监听、收发、编解码」这些脏活。

## 适合你吗

1. 你的进程只想**在本机被动监听**，不想写「主动去连中央」的客户端。  
2. 可能有多路交换程序（或多实例）要**同时**连到同一个业务进程。  
3. 你想直接发 **Python 对象**（字典、数据类、带校验的模型），不想手搓二进制协议。

三条里命中任意一条，就值得往下看。

---

## 常用词对照

| 文档里常说 | 你可以理解成 |
|-----------|----------------|
| 监听地址 | 你绑定的 `IP:端口`，一般要抄到交换程序的配置里 |
| 发一条 | 发给**当前所有**已连上的交换程序，内容同一份 |

---

## 设计特性

### 你只管开端口，谁来连由交换程序决定

1. 你在代码里指定本机要绑的 **主机** 和 **端口**（端口也可以写 `0`，让系统随便挑一个空的）。  
2. 交换程序读自己的表，**主动连**你这个地址。  
3. 你**不用**在业务里记「中央在哪」——对方会来找你。

### 好几台交换程序可以同时连你

- 不会因为「已经有一台连上了」就把后来的拒掉。  
- 每台连接单独维护；发数据时可以**一起**通知当前所有连接。

### 发一次，所有连着的人都收到同一份

你发一条业务消息时：

1. 内容会**原样**发给当前所有连接。  
2. 大家拿到的是**同一份**字节和**同一个**序号，方便各台交换程序各自做路由、对账。

### 你平时还是写 Python 对象，不用自己拼二进制

| 你手里是 | 库会帮你 |
|----------|-----------|
| 字典、`Mapping` | 按约定压成线上字节 |
| 带校验的模型、数据类 | 同样压成线上字节 |
| 收进来的字节 | 解回 Python，再进你的回调 |

### 回调可以写类型，对不上就不瞎调

- 处理函数**第一个参数**可以写类型注解。  
- 对得上的才调用；对不上会**打日志**，不会悄悄把错数据塞进你的函数。

### 想打日志可以挂几个小钩子

适合记日志、做调试的同步回调包括（名字不必背，知道「有这回事」即可）：

1. 监听起来了 / 有人连上或断开  
2. 收到对端转过来的数据 / 发不出去  
3. 对面报错 / 收到「已收到」的确认  

> 钩子别太耗时；重活请自己 `create_task` 或丢线程池。

### 想看得顺眼可以装彩色日志（不装也行）

- **装了**常见彩色终端库：事件可以打成**一行**、带颜色。  
- **没装**：退回标准 `logging`，不会因为少依赖就崩。

### 端口写 0 也行，起来后再问「我实际监听的是哪」

```text
端口写 0  →  启动完成  →  取 listen_address 字符串
         →  复制到交换程序配置里的 address
```

本机「全零监听」时，也会给你一个**适合写进本机配置**的地址形式（含 IPv6 时的括号习惯）。

### 命令行跑着时，Ctrl+C 能正常收尾

库带一个「**等到用户想退出**再继续」的辅助协程，适合示例和小脚本：收到中断或退出意图后，可以统一关掉监听和连接，不至于一团糟。
