pswitch 0.1.5__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. pswitch-0.1.5/.gitignore +9 -0
  2. pswitch-0.1.5/LICENSE +21 -0
  3. pswitch-0.1.5/PKG-INFO +184 -0
  4. pswitch-0.1.5/README.md +162 -0
  5. pswitch-0.1.5/pyproject.toml +44 -0
  6. pswitch-0.1.5/src/pswitch/__init__.py +3 -0
  7. pswitch-0.1.5/src/pswitch/__main__.py +6 -0
  8. pswitch-0.1.5/src/pswitch/cli.py +650 -0
  9. pswitch-0.1.5/src/pswitch/config.py +98 -0
  10. pswitch-0.1.5/src/pswitch/direct.py +299 -0
  11. pswitch-0.1.5/src/pswitch/launchd.py +69 -0
  12. pswitch-0.1.5/src/pswitch/proxy.py +397 -0
  13. pswitch-0.1.5/src/pswitch/stream.py +40 -0
pswitch-0.1.5/.gitignore ADDED
@@ -0,0 +1,9 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .ruff_cache/
4
+ .pytest_cache/
5
+ .venv/
6
+ build/
7
+ dist/
8
+ *.egg-info/
9
+ .DS_Store
pswitch-0.1.5/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Walter LIU
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
pswitch-0.1.5/PKG-INFO ADDED
@@ -0,0 +1,184 @@
1
+ Metadata-Version: 2.5
2
+ Name: pswitch
3
+ Version: 0.1.5
4
+ Summary: 一个本地端口，多个上游代理，随时切换
5
+ Project-URL: Homepage, https://github.com/WalterYOO/pswitch
6
+ Project-URL: Repository, https://github.com/WalterYOO/pswitch
7
+ Project-URL: Issues, https://github.com/WalterYOO/pswitch/issues
8
+ Author: Walter LIU
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: http-proxy,macos,port,proxy,socks5,switch
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: MacOS
16
+ Classifier: Operating System :: POSIX
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Topic :: Internet :: Proxy Servers
19
+ Classifier: Topic :: System :: Networking
20
+ Requires-Python: >=3.9
21
+ Description-Content-Type: text/markdown
22
+
23
+ # pswitch
24
+
25
+ 把多个上游代理聚合到一个固定本地端口（默认 `127.0.0.1:17000`）。
26
+ 客户端只认这个端口，切换上游只需一条命令，不再改环境变量。
27
+
28
+ ```
29
+ ┌──────────────────────┐
30
+ curl/git/npm ───▶│ 127.0.0.1:17000 │
31
+ 浏览器/GUI ───▶│ pswitch (TCP 转发) │───▶ upstream A
32
+ │ │───▶ upstream B
33
+ └──────────────────────┘───▶ upstream C
34
+ ```
35
+
36
+ ## 安装
37
+
38
+ ```bash
39
+ uv tool install pswitch
40
+ # 或者
41
+ pip install pswitch
42
+ ```
43
+
44
+ 升级：
45
+
46
+ ```bash
47
+ uv tool upgrade pswitch
48
+ # 或者
49
+ pip install -U pswitch
50
+ ```
51
+
52
+ 从源码安装（开发用）：
53
+
54
+ ```bash
55
+ git clone https://github.com/WalterYOO/pswitch.git
56
+ uv tool install ./pswitch
57
+ ```
58
+
59
+ 安装后可执行文件位于 `~/.local/bin/pswitch`，确认该目录在 `PATH` 中：
60
+
61
+ ```bash
62
+ command -v pswitch
63
+ ```
64
+
65
+ ## 首次运行
66
+
67
+ 代码里**不内置任何上游**。第一次执行任意命令时会自动创建配置文件，
68
+ 其中 `upstreams` 为空：
69
+
70
+ ```bash
71
+ pswitch status
72
+ # 已创建配置文件: ~/.config/proxy_switch/config.json（还没有上游，用 pswitch add 添加）
73
+ ```
74
+
75
+ 添加上游后才能启动：
76
+
77
+ ```bash
78
+ pswitch add local 127.0.0.1:17890
79
+ pswitch add office 192.168.212.21:17090
80
+ pswitch start
81
+ ```
82
+
83
+ **没有配置任何上游时，`pswitch start` 和 `pswitch install` 会拒绝执行并返回退出码 1。**
84
+
85
+ ## 日常使用
86
+
87
+ ```bash
88
+ pswitch status # 当前走哪个、各上游实时探活
89
+ pswitch use office # 固定走某一个
90
+ pswitch use auto # 自动：按优先级顺序选第一个真正能通的（推荐）
91
+ pswitch use direct # 全部直连：不经过任何上游
92
+ pswitch priority # 查看优先级顺序
93
+ pswitch priority office 1 # 把 office 提到最高优先级
94
+ pswitch list # 列出全部上游
95
+ pswitch test # 经本地端口发真实请求验证
96
+ pswitch env # 打印代理环境变量
97
+ pswitch disable office # 临时不用它（如内网代理在当前网络不可达），配置保留
98
+ pswitch enable office # 恢复
99
+ pswitch version # 查看当前版本号
100
+ ```
101
+
102
+ ## 命令
103
+
104
+ | 命令 | 作用 |
105
+ | --- | --- |
106
+ | `start` / `stop` / `restart` | 管理守护进程 |
107
+ | `status` | 进程、监听、当前上游、各上游实时探活结果 |
108
+ | `use <名字\|auto\|direct>` | 切换出口（auto = 自动选择；direct = 不经上游直接连目标） |
109
+ | `list` / `add <名> <host:port>` / `remove <名>` | 管理上游列表 |
110
+ | `enable <名>` / `disable <名>` | 临时启用/禁用某个上游：配置保留，禁用后不参与 `use`、auto 选路和故障转移 |
111
+ | `priority [<名> [位置]]` | 查看优先级顺序；给出名字和位置则把该上游移到该位置（1 = 最高） |
112
+ | `env` | 打印代理环境变量 |
113
+ | `test` | 经本地端口请求 gstatic 的 204 接口 |
114
+ | `logs [-n 行数]` | 查看日志（`~/.config/proxy_switch/pswitch.log`） |
115
+ | `install` / `uninstall` | 安装/卸载 launchd 开机自启 |
116
+ | `system on\|off\|status` | 把 macOS 系统代理指向/取消指向本地端口 |
117
+ | `version`（或 `-V` / `--version`） | 查看版本号 |
118
+
119
+ ## 配置文件
120
+
121
+ `~/.config/proxy_switch/config.json`（`PSWITCH_HOME` 可覆盖目录）：
122
+
123
+ ```json
124
+ {
125
+ "listen": "127.0.0.1:17000",
126
+ "mode": "auto",
127
+ "active": null,
128
+ "health_check_interval": 10,
129
+ "connect_timeout": 3,
130
+ "failover": true,
131
+ "probe_url": "http://connectivitycheck.gstatic.com/generate_204",
132
+ "probe_timeout": 3,
133
+ "upstreams": []
134
+ }
135
+ ```
136
+
137
+ - 直接编辑也没关系，守护进程会检测到文件变化并自动重载。
138
+ - 改 `listen` 需要 `pswitch restart` 才生效。
139
+ - `mode: auto` 时按 `upstreams` 顺序取第一个探活通过的；`mode: manual` 时固定 `active`。
140
+ - `mode: direct` 时完全不使用上游：pswitch 自己解析 HTTP CONNECT / 普通 HTTP / SOCKS5，
141
+ 直接连接目标。此时没有配置上游也能 `pswitch start`，`use direct` 与 `use auto|名字`
142
+ 可随时互切，客户端的环境变量和系统代理指向都不用改。
143
+ - **`upstreams` 的数组顺序就是优先级**：先比探活等级（HTTP 通 > 只通 TCP），同级按顺序取第一个，
144
+ 不看延迟。`pswitch add` 追加到末尾（最低），`pswitch priority <名> <位置>` 调整，
145
+ `list` / `priority` 里的编号就是选路顺序。
146
+ - 每个上游可带 `"enabled": false`（`pswitch disable <名>` 会写入）。禁用的上游保留在配置里，
147
+ 但探活、auto 选路、故障转移都会跳过它；如果 `mode: manual` 的 `active` 正好被禁用，
148
+ 选路会当作没命中，退回 auto 顺序。`pswitch enable <名>` 即可恢复。
149
+ - 全部上游都被禁用时，`pswitch start` 会拒绝启动，系统代理也不会被打开。
150
+ - 探活地址可以换成内网地址，避免依赖外网：例如
151
+ `"probe_url": "http://your-intranet/health"`（要求返回 200/204）。
152
+
153
+ ## 与 shell 环境变量的关系
154
+
155
+ 如果环境变量由 `zsh-osx-autoproxy` 之类的插件从 **macOS 系统代理设置**导出，
156
+ 让系统代理指向本地端口即可，新终端会自动跟随：
157
+
158
+ ```bash
159
+ pswitch install # 开机自启，挂了自动拉起
160
+ pswitch system on # 系统代理 -> 127.0.0.1:17000
161
+ ```
162
+
163
+ GUI 应用也一起生效。恢复直连或换回原来的代理：`pswitch system off`。
164
+
165
+ 如果只想影响命令行，把 `pswitch env` 的输出追加到 `~/.zshrc` 末尾
166
+ （放在 oh-my-zsh 加载之后，才能覆盖插件设置）。
167
+
168
+ ## 工作方式
169
+
170
+ - 在 TCP 层透明转发，同一个本地端口既能当 HTTP 代理，也能当 SOCKS5 代理。
171
+ - 每 `health_check_interval` 秒对每个上游做一次真实 HTTP 探活；只通 TCP 但转发失败
172
+ （例如返回 502）的上游会被标记为 `TCP only`，自动选路时排在后面。
173
+ - 当前上游临时连不上时，单条连接会自动借用其它可用上游。
174
+ - direct 模式下 pswitch 自己充当代理：支持 HTTP CONNECT、普通 HTTP（首个请求改写为
175
+ origin-form 并强制 `Connection: close`）和无认证 SOCKS5 CONNECT；BIND / UDP ASSOCIATE
176
+ 和 SOCKS4 不支持，会明确拒绝。
177
+
178
+ ## 注意事项
179
+
180
+ - 系统代理指向本地端口后，`pswitch` 停掉就等于断网。建议先 `install` 再 `system on`。
181
+ - 手动 `use <名字>` 的语义是“钉死”；要自动避开坏上游就用 `use auto`。
182
+ - `no_proxy` 里保留 `127.0.0.1,localhost`，否则访问本地服务可能被绕一圈。
183
+ - 从源码目录执行 `python -m pswitch` 时，注意不要与旧版的 `pswitch.py` 同名冲突；
184
+ 正常使用安装后的 `pswitch` 命令即可。
pswitch-0.1.5/README.md ADDED
@@ -0,0 +1,162 @@
1
+ # pswitch
2
+
3
+ 把多个上游代理聚合到一个固定本地端口（默认 `127.0.0.1:17000`）。
4
+ 客户端只认这个端口，切换上游只需一条命令，不再改环境变量。
5
+
6
+ ```
7
+ ┌──────────────────────┐
8
+ curl/git/npm ───▶│ 127.0.0.1:17000 │
9
+ 浏览器/GUI ───▶│ pswitch (TCP 转发) │───▶ upstream A
10
+ │ │───▶ upstream B
11
+ └──────────────────────┘───▶ upstream C
12
+ ```
13
+
14
+ ## 安装
15
+
16
+ ```bash
17
+ uv tool install pswitch
18
+ # 或者
19
+ pip install pswitch
20
+ ```
21
+
22
+ 升级：
23
+
24
+ ```bash
25
+ uv tool upgrade pswitch
26
+ # 或者
27
+ pip install -U pswitch
28
+ ```
29
+
30
+ 从源码安装（开发用）：
31
+
32
+ ```bash
33
+ git clone https://github.com/WalterYOO/pswitch.git
34
+ uv tool install ./pswitch
35
+ ```
36
+
37
+ 安装后可执行文件位于 `~/.local/bin/pswitch`，确认该目录在 `PATH` 中：
38
+
39
+ ```bash
40
+ command -v pswitch
41
+ ```
42
+
43
+ ## 首次运行
44
+
45
+ 代码里**不内置任何上游**。第一次执行任意命令时会自动创建配置文件，
46
+ 其中 `upstreams` 为空：
47
+
48
+ ```bash
49
+ pswitch status
50
+ # 已创建配置文件: ~/.config/proxy_switch/config.json（还没有上游，用 pswitch add 添加）
51
+ ```
52
+
53
+ 添加上游后才能启动：
54
+
55
+ ```bash
56
+ pswitch add local 127.0.0.1:17890
57
+ pswitch add office 192.168.212.21:17090
58
+ pswitch start
59
+ ```
60
+
61
+ **没有配置任何上游时，`pswitch start` 和 `pswitch install` 会拒绝执行并返回退出码 1。**
62
+
63
+ ## 日常使用
64
+
65
+ ```bash
66
+ pswitch status # 当前走哪个、各上游实时探活
67
+ pswitch use office # 固定走某一个
68
+ pswitch use auto # 自动：按优先级顺序选第一个真正能通的（推荐）
69
+ pswitch use direct # 全部直连：不经过任何上游
70
+ pswitch priority # 查看优先级顺序
71
+ pswitch priority office 1 # 把 office 提到最高优先级
72
+ pswitch list # 列出全部上游
73
+ pswitch test # 经本地端口发真实请求验证
74
+ pswitch env # 打印代理环境变量
75
+ pswitch disable office # 临时不用它（如内网代理在当前网络不可达），配置保留
76
+ pswitch enable office # 恢复
77
+ pswitch version # 查看当前版本号
78
+ ```
79
+
80
+ ## 命令
81
+
82
+ | 命令 | 作用 |
83
+ | --- | --- |
84
+ | `start` / `stop` / `restart` | 管理守护进程 |
85
+ | `status` | 进程、监听、当前上游、各上游实时探活结果 |
86
+ | `use <名字\|auto\|direct>` | 切换出口（auto = 自动选择；direct = 不经上游直接连目标） |
87
+ | `list` / `add <名> <host:port>` / `remove <名>` | 管理上游列表 |
88
+ | `enable <名>` / `disable <名>` | 临时启用/禁用某个上游：配置保留，禁用后不参与 `use`、auto 选路和故障转移 |
89
+ | `priority [<名> [位置]]` | 查看优先级顺序；给出名字和位置则把该上游移到该位置（1 = 最高） |
90
+ | `env` | 打印代理环境变量 |
91
+ | `test` | 经本地端口请求 gstatic 的 204 接口 |
92
+ | `logs [-n 行数]` | 查看日志（`~/.config/proxy_switch/pswitch.log`） |
93
+ | `install` / `uninstall` | 安装/卸载 launchd 开机自启 |
94
+ | `system on\|off\|status` | 把 macOS 系统代理指向/取消指向本地端口 |
95
+ | `version`（或 `-V` / `--version`） | 查看版本号 |
96
+
97
+ ## 配置文件
98
+
99
+ `~/.config/proxy_switch/config.json`（`PSWITCH_HOME` 可覆盖目录）：
100
+
101
+ ```json
102
+ {
103
+ "listen": "127.0.0.1:17000",
104
+ "mode": "auto",
105
+ "active": null,
106
+ "health_check_interval": 10,
107
+ "connect_timeout": 3,
108
+ "failover": true,
109
+ "probe_url": "http://connectivitycheck.gstatic.com/generate_204",
110
+ "probe_timeout": 3,
111
+ "upstreams": []
112
+ }
113
+ ```
114
+
115
+ - 直接编辑也没关系，守护进程会检测到文件变化并自动重载。
116
+ - 改 `listen` 需要 `pswitch restart` 才生效。
117
+ - `mode: auto` 时按 `upstreams` 顺序取第一个探活通过的；`mode: manual` 时固定 `active`。
118
+ - `mode: direct` 时完全不使用上游：pswitch 自己解析 HTTP CONNECT / 普通 HTTP / SOCKS5，
119
+ 直接连接目标。此时没有配置上游也能 `pswitch start`，`use direct` 与 `use auto|名字`
120
+ 可随时互切，客户端的环境变量和系统代理指向都不用改。
121
+ - **`upstreams` 的数组顺序就是优先级**：先比探活等级（HTTP 通 > 只通 TCP），同级按顺序取第一个，
122
+ 不看延迟。`pswitch add` 追加到末尾（最低），`pswitch priority <名> <位置>` 调整，
123
+ `list` / `priority` 里的编号就是选路顺序。
124
+ - 每个上游可带 `"enabled": false`（`pswitch disable <名>` 会写入）。禁用的上游保留在配置里，
125
+ 但探活、auto 选路、故障转移都会跳过它；如果 `mode: manual` 的 `active` 正好被禁用，
126
+ 选路会当作没命中，退回 auto 顺序。`pswitch enable <名>` 即可恢复。
127
+ - 全部上游都被禁用时，`pswitch start` 会拒绝启动，系统代理也不会被打开。
128
+ - 探活地址可以换成内网地址，避免依赖外网：例如
129
+ `"probe_url": "http://your-intranet/health"`（要求返回 200/204）。
130
+
131
+ ## 与 shell 环境变量的关系
132
+
133
+ 如果环境变量由 `zsh-osx-autoproxy` 之类的插件从 **macOS 系统代理设置**导出，
134
+ 让系统代理指向本地端口即可，新终端会自动跟随：
135
+
136
+ ```bash
137
+ pswitch install # 开机自启，挂了自动拉起
138
+ pswitch system on # 系统代理 -> 127.0.0.1:17000
139
+ ```
140
+
141
+ GUI 应用也一起生效。恢复直连或换回原来的代理：`pswitch system off`。
142
+
143
+ 如果只想影响命令行，把 `pswitch env` 的输出追加到 `~/.zshrc` 末尾
144
+ （放在 oh-my-zsh 加载之后，才能覆盖插件设置）。
145
+
146
+ ## 工作方式
147
+
148
+ - 在 TCP 层透明转发，同一个本地端口既能当 HTTP 代理，也能当 SOCKS5 代理。
149
+ - 每 `health_check_interval` 秒对每个上游做一次真实 HTTP 探活；只通 TCP 但转发失败
150
+ （例如返回 502）的上游会被标记为 `TCP only`，自动选路时排在后面。
151
+ - 当前上游临时连不上时，单条连接会自动借用其它可用上游。
152
+ - direct 模式下 pswitch 自己充当代理：支持 HTTP CONNECT、普通 HTTP（首个请求改写为
153
+ origin-form 并强制 `Connection: close`）和无认证 SOCKS5 CONNECT；BIND / UDP ASSOCIATE
154
+ 和 SOCKS4 不支持，会明确拒绝。
155
+
156
+ ## 注意事项
157
+
158
+ - 系统代理指向本地端口后，`pswitch` 停掉就等于断网。建议先 `install` 再 `system on`。
159
+ - 手动 `use <名字>` 的语义是“钉死”；要自动避开坏上游就用 `use auto`。
160
+ - `no_proxy` 里保留 `127.0.0.1,localhost`，否则访问本地服务可能被绕一圈。
161
+ - 从源码目录执行 `python -m pswitch` 时，注意不要与旧版的 `pswitch.py` 同名冲突；
162
+ 正常使用安装后的 `pswitch` 命令即可。
pswitch-0.1.5/pyproject.toml ADDED
@@ -0,0 +1,44 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "pswitch"
7
+ version = "0.1.5"
8
+ description = "一个本地端口，多个上游代理，随时切换"
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{ name = "Walter LIU" }]
14
+ keywords = ["proxy", "http-proxy", "socks5", "port", "switch", "macos"]
15
+ classifiers = [
16
+ "Development Status :: 4 - Beta",
17
+ "Environment :: Console",
18
+ "Intended Audience :: Developers",
19
+ "Operating System :: MacOS",
20
+ "Operating System :: POSIX",
21
+ "Programming Language :: Python :: 3 :: Only",
22
+ "Topic :: Internet :: Proxy Servers",
23
+ "Topic :: System :: Networking",
24
+ ]
25
+ dependencies = []
26
+
27
+ [project.urls]
28
+ Homepage = "https://github.com/WalterYOO/pswitch"
29
+ Repository = "https://github.com/WalterYOO/pswitch"
30
+ Issues = "https://github.com/WalterYOO/pswitch/issues"
31
+
32
+ [project.scripts]
33
+ pswitch = "pswitch.cli:main"
34
+
35
+ [tool.hatch.build.targets.wheel]
36
+ packages = ["src/pswitch"]
37
+
38
+ [tool.hatch.build.targets.sdist]
39
+ include = [
40
+ "src/pswitch",
41
+ "README.md",
42
+ "LICENSE",
43
+ "pyproject.toml",
44
+ ]
pswitch-0.1.5/src/pswitch/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """pswitch — 一个本地端口，多个上游代理，随时切换。"""
2
+
3
+ __version__ = "0.1.5"
pswitch-0.1.5/src/pswitch/__main__.py ADDED
@@ -0,0 +1,6 @@
1
+ import sys
2
+
3
+ from .cli import main
4
+
5
+ if __name__ == "__main__":
6
+ sys.exit(main())