pysubzone 0.1.0__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.
- pysubzone-0.1.0/LICENSE +21 -0
- pysubzone-0.1.0/PKG-INFO +370 -0
- pysubzone-0.1.0/README.md +314 -0
- pysubzone-0.1.0/pyproject.toml +69 -0
- pysubzone-0.1.0/setup.cfg +4 -0
- pysubzone-0.1.0/src/pysubzone/__init__.py +53 -0
- pysubzone-0.1.0/src/pysubzone/__main__.py +6 -0
- pysubzone-0.1.0/src/pysubzone/cli.py +624 -0
- pysubzone-0.1.0/src/pysubzone/client.py +509 -0
- pysubzone-0.1.0/src/pysubzone/exceptions.py +36 -0
- pysubzone-0.1.0/src/pysubzone/languages.py +192 -0
- pysubzone-0.1.0/src/pysubzone/matcher.py +103 -0
- pysubzone-0.1.0/src/pysubzone/models.py +182 -0
- pysubzone-0.1.0/src/pysubzone/parsing.py +355 -0
- pysubzone-0.1.0/src/pysubzone/scoring.py +189 -0
- pysubzone-0.1.0/src/pysubzone/tui.py +326 -0
- pysubzone-0.1.0/src/pysubzone.egg-info/PKG-INFO +370 -0
- pysubzone-0.1.0/src/pysubzone.egg-info/SOURCES.txt +21 -0
- pysubzone-0.1.0/src/pysubzone.egg-info/dependency_links.txt +1 -0
- pysubzone-0.1.0/src/pysubzone.egg-info/entry_points.txt +2 -0
- pysubzone-0.1.0/src/pysubzone.egg-info/requires.txt +9 -0
- pysubzone-0.1.0/src/pysubzone.egg-info/top_level.txt +1 -0
- pysubzone-0.1.0/tests/test_offline.py +207 -0
pysubzone-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 PySubZone developers
|
|
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.
|
pysubzone-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,370 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pysubzone
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Python API, CLI and TUI to search and download subtitles from subzone.ir (Subf2m subtitle database)
|
|
5
|
+
Author: PySubZone developers
|
|
6
|
+
License: MIT License
|
|
7
|
+
|
|
8
|
+
Copyright (c) 2026 PySubZone developers
|
|
9
|
+
|
|
10
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
11
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
12
|
+
in the Software without restriction, including without limitation the rights
|
|
13
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
14
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
15
|
+
furnished to do so, subject to the following conditions:
|
|
16
|
+
|
|
17
|
+
The above copyright notice and this permission notice shall be included in all
|
|
18
|
+
copies or substantial portions of the Software.
|
|
19
|
+
|
|
20
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
21
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
22
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
23
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
24
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
25
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
26
|
+
SOFTWARE.
|
|
27
|
+
|
|
28
|
+
Project-URL: Homepage, https://github.com/mackeos/PySubZone
|
|
29
|
+
Project-URL: Repository, https://github.com/mackeos/PySubZone
|
|
30
|
+
Project-URL: Issues, https://github.com/mackeos/PySubZone/issues
|
|
31
|
+
Keywords: subzone,subzone.ir,subf2m,subtitles,subtitle-downloader,subtitle-scraper,srt,farsi,persian,cli,tui,textual
|
|
32
|
+
Classifier: Development Status :: 4 - Beta
|
|
33
|
+
Classifier: Environment :: Console
|
|
34
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
35
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
36
|
+
Classifier: Operating System :: OS Independent
|
|
37
|
+
Classifier: Programming Language :: Python :: 3
|
|
38
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
39
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
40
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
41
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
42
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
43
|
+
Classifier: Topic :: Multimedia :: Video
|
|
44
|
+
Requires-Python: >=3.9
|
|
45
|
+
Description-Content-Type: text/markdown
|
|
46
|
+
License-File: LICENSE
|
|
47
|
+
Requires-Dist: requests>=2.25
|
|
48
|
+
Requires-Dist: beautifulsoup4>=4.9
|
|
49
|
+
Requires-Dist: lxml>=4.6
|
|
50
|
+
Requires-Dist: typer>=0.9
|
|
51
|
+
Requires-Dist: rich>=13.0
|
|
52
|
+
Requires-Dist: textual>=0.60
|
|
53
|
+
Provides-Extra: dev
|
|
54
|
+
Requires-Dist: pytest>=7.0; extra == "dev"
|
|
55
|
+
Dynamic: license-file
|
|
56
|
+
|
|
57
|
+
# PySubZone
|
|
58
|
+
|
|
59
|
+
<p align="center">
|
|
60
|
+
<strong>Find the right subtitle. Download it. Get back to watching.</strong>
|
|
61
|
+
</p>
|
|
62
|
+
|
|
63
|
+
<p align="center">
|
|
64
|
+
<a href="https://pypi.org/project/pysubzone/"><img src="https://img.shields.io/pypi/v/pysubzone?label=PyPI&color=blue" alt="PyPI version"></a>
|
|
65
|
+
<a href="https://pypi.org/project/pysubzone/"><img src="https://img.shields.io/pypi/pyversions/pysubzone" alt="Python versions"></a>
|
|
66
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license"></a>
|
|
67
|
+
</p>
|
|
68
|
+
|
|
69
|
+
**PySubZone** is a Python library, command-line tool, and interactive terminal app for searching and downloading subtitles from [SubZone](https://subzone.ir/), the Subf2m subtitle database.
|
|
70
|
+
|
|
71
|
+
Whether you need one subtitle or want to match subtitles for an entire video collection, PySubZone gives you a straightforward way to find the version that fits.
|
|
72
|
+
|
|
73
|
+
Inspired by [PyAddic7](https://github.com/mackeos/PyAddic7), which works with addic7ed.com.
|
|
74
|
+
|
|
75
|
+
## What can it do?
|
|
76
|
+
|
|
77
|
+
- **Search titles** — find movies and TV shows.
|
|
78
|
+
- **Browse subtitle versions** — see the uploads available for a title, with language filtering.
|
|
79
|
+
- **Download subtitles** — download a specific upload by reference or URL, or grab the newest uploads from a title page.
|
|
80
|
+
- **Match video files automatically** — search for suitable subtitles based on release names, including episode number, resolution, source, and release group.
|
|
81
|
+
- **Use it your way** — choose the Python API, the command-line interface, or the interactive terminal UI.
|
|
82
|
+
|
|
83
|
+
The CLI is built with [Typer](https://typer.tiangolo.com/) and Rich, while the interactive TUI is powered by [Textual](https://github.com/Textualize/textual).
|
|
84
|
+
|
|
85
|
+
> **A note on responsible use:** PySubZone accesses a public website for personal use. Please keep request rates reasonable and respect the source website's terms. Do not redistribute downloaded subtitles.
|
|
86
|
+
|
|
87
|
+
## Packages
|
|
88
|
+
|
|
89
|
+
| Package | Purpose | PyPI |
|
|
90
|
+
|---|---|---|
|
|
91
|
+
| **PySubZone** (`pysubzone`) | Main Python API, CLI, and TUI package | [pypi.org/project/pysubzone](https://pypi.org/project/pysubzone/) |
|
|
92
|
+
| **PySubF2M** (`pysubf2m`) | Compatibility package | coming soon |
|
|
93
|
+
|
|
94
|
+
## Installation
|
|
95
|
+
|
|
96
|
+
Python **3.9 or newer** is required.
|
|
97
|
+
|
|
98
|
+
Install the main package with pip:
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
pip install pysubzone
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Or use [pipx](https://pipx.pypa.io/) to install the command-line application in an isolated environment:
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
pipx install pysubzone
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
A compatibility package, **PySubF2M** (`pysubf2m`), is planned as a separate release.
|
|
111
|
+
|
|
112
|
+
After installing PySubZone, the `subz` command is available. You can also run it with:
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
python -m pysubzone
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
## Quick start
|
|
119
|
+
|
|
120
|
+
Search for a title, inspect its subtitle versions, and download one:
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
# Search for a movie or show
|
|
124
|
+
subz search "dexter resurrection"
|
|
125
|
+
|
|
126
|
+
# Show the available Farsi subtitle versions
|
|
127
|
+
subz versions dexter-resurrection-season-2 -l fa
|
|
128
|
+
|
|
129
|
+
# Download a specific version
|
|
130
|
+
subz download dexter-resurrection-season-2/farsi_persian/3770171
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## Command-line reference
|
|
134
|
+
|
|
135
|
+
```text
|
|
136
|
+
subz search QUERY [-l LANG] [--json] Search titles
|
|
137
|
+
subz versions TITLE [-l LANG] [--json] List subtitle uploads
|
|
138
|
+
subz download REF [-o DIR] [--zip] [--json] Download by reference, URL, or slug
|
|
139
|
+
subz url URL [-l LANG] [-n N] [--zip] Download from a SubZone URL
|
|
140
|
+
subz filename FILE [-l LANG] [--no-download] Find the best subtitle for one video
|
|
141
|
+
subz auto PATH [-l LANG] [--dry-run] [--zip] Match videos in a folder
|
|
142
|
+
subz popular [--mode popular|latest] Browse popular or latest uploads
|
|
143
|
+
[-t all|film|series|music] [-p PAGE]
|
|
144
|
+
subz tui Open the interactive interface
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Global options:
|
|
148
|
+
|
|
149
|
+
- `--base-url` — use a different base URL.
|
|
150
|
+
- `--user-agent` — set the HTTP user agent.
|
|
151
|
+
- `--timeout` — configure the request timeout.
|
|
152
|
+
- `--retries` — configure retry attempts.
|
|
153
|
+
- `-v`, `--verbose` — enable verbose output.
|
|
154
|
+
|
|
155
|
+
Every data command supports `--json` for scripting and automation.
|
|
156
|
+
|
|
157
|
+
Exit codes follow the PyAddic7 contract:
|
|
158
|
+
|
|
159
|
+
| Code | Meaning |
|
|
160
|
+
|---:|---|
|
|
161
|
+
| `0` | Success |
|
|
162
|
+
| `1` | Nothing found |
|
|
163
|
+
| `2` | Error |
|
|
164
|
+
|
|
165
|
+
### Search and browse
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
# Search for a title
|
|
169
|
+
subz search "dexter resurrection"
|
|
170
|
+
|
|
171
|
+
# Search for titles with Farsi subtitles
|
|
172
|
+
subz search odyssey -l fa
|
|
173
|
+
|
|
174
|
+
# List Farsi subtitle versions for a title
|
|
175
|
+
subz versions dexter-resurrection-season-2 -l fa
|
|
176
|
+
|
|
177
|
+
# Browse popular movie uploads
|
|
178
|
+
subz popular -t film
|
|
179
|
+
|
|
180
|
+
# Browse the latest series uploads, page 2
|
|
181
|
+
subz popular --mode latest -t series -p 2
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
### Download subtitles
|
|
185
|
+
|
|
186
|
+
A **reference** identifies one subtitle upload and follows this format:
|
|
187
|
+
|
|
188
|
+
```text
|
|
189
|
+
<slug>/<lang>/<id>
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
You can copy a reference from a version listing.
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
# Download using a reference
|
|
196
|
+
subz download dexter-resurrection-season-2/farsi_persian/3770171
|
|
197
|
+
|
|
198
|
+
# Download using the full subtitle URL
|
|
199
|
+
subz download https://subzone.ir/subtitles/dexter-resurrection-season-2/farsi_persian/3770171
|
|
200
|
+
|
|
201
|
+
# Grab the two newest Farsi uploads from a title URL
|
|
202
|
+
subz url https://subzone.ir/subtitles/the-odyssey-2026 -l fa -n 2
|
|
203
|
+
|
|
204
|
+
# Grab all available uploads from that title URL
|
|
205
|
+
subz url https://subzone.ir/subtitles/the-odyssey-2026 -l fa -n 0
|
|
206
|
+
|
|
207
|
+
# Download by title slug
|
|
208
|
+
subz download the-odyssey-2026 -l en --zip --out ./downloads
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
By default, downloaded archives are **extracted** and subtitle files receive a language suffix, such as `Movie.fa.srt` (or retain the release name when the archive includes one).
|
|
212
|
+
|
|
213
|
+
Useful output options:
|
|
214
|
+
|
|
215
|
+
- `--zip` — keep the original archive instead of extracting it.
|
|
216
|
+
- `--no-suffix` — do not append a language suffix.
|
|
217
|
+
- `--lang-suffix XX` — choose a custom language suffix.
|
|
218
|
+
- `-o DIR` / `--out DIR` — choose the output directory.
|
|
219
|
+
|
|
220
|
+
### Automatically match a video collection
|
|
221
|
+
|
|
222
|
+
PySubZone can inspect video release names, search the site, score available subtitle versions, and download the best match.
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
# Find a subtitle for one video
|
|
226
|
+
subz filename "Dexter.Resurrection.S02E01.1080p.AMZN.WEB-DL-NTb.mkv"
|
|
227
|
+
|
|
228
|
+
# Preview matches in a folder without downloading
|
|
229
|
+
subz auto /media/shows -l fa --dry-run
|
|
230
|
+
|
|
231
|
+
# Download and extract subtitles beside the videos
|
|
232
|
+
subz auto /media/shows -l fa
|
|
233
|
+
|
|
234
|
+
# Save all subtitles into a separate folder
|
|
235
|
+
subz auto /media/shows -l fa -o ./subs
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
For each video, the release name is parsed for details such as the title, season and episode, resolution, source, and release group. Subtitle versions with conflicting episode numbers are rejected, exact release matches are preferred, and season packs can be used as fallbacks.
|
|
239
|
+
|
|
240
|
+
A failed match does not stop the whole collection: unsuccessful files are included in the final summary.
|
|
241
|
+
|
|
242
|
+
## Interactive terminal interface
|
|
243
|
+
|
|
244
|
+
Prefer an interactive experience? Run:
|
|
245
|
+
|
|
246
|
+
```bash
|
|
247
|
+
subz tui
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
The TUI guides you through the process:
|
|
251
|
+
|
|
252
|
+
1. Enter a search query to see matching titles.
|
|
253
|
+
2. Select a title to browse its uploaded subtitle versions.
|
|
254
|
+
3. Filter versions by language.
|
|
255
|
+
4. Select a version to open the download dialog.
|
|
256
|
+
5. Choose a destination and whether to extract subtitles or keep the ZIP archive.
|
|
257
|
+
|
|
258
|
+
The download dialog includes a live progress bar.
|
|
259
|
+
|
|
260
|
+
**Keyboard shortcuts**
|
|
261
|
+
|
|
262
|
+
| Key | Action |
|
|
263
|
+
|---|---|
|
|
264
|
+
| `Esc` | Go back or close the current view |
|
|
265
|
+
| `r` | Refresh subtitle versions |
|
|
266
|
+
| `Ctrl+Q` | Quit |
|
|
267
|
+
|
|
268
|
+
### TUI screenshots
|
|
269
|
+
|
|
270
|
+
| Search | Subtitle versions | Download |
|
|
271
|
+
|---|---|---|
|
|
272
|
+
|  |  |  |
|
|
273
|
+
|
|
274
|
+
## Python API
|
|
275
|
+
|
|
276
|
+
You can use PySubZone directly from your own Python projects:
|
|
277
|
+
|
|
278
|
+
```python
|
|
279
|
+
from pysubzone import SubZoneClient
|
|
280
|
+
|
|
281
|
+
client = SubZoneClient(timeout=20)
|
|
282
|
+
|
|
283
|
+
# Search for titles
|
|
284
|
+
results = client.search("dexter resurrection")
|
|
285
|
+
|
|
286
|
+
# Find a title and list its Farsi subtitle versions
|
|
287
|
+
title = client.search_exact("Dexter Resurrection")
|
|
288
|
+
versions = client.title_versions(title.slug, "farsi_persian")
|
|
289
|
+
|
|
290
|
+
# Download the first version and extract it into ./subs
|
|
291
|
+
result = client.download(
|
|
292
|
+
versions[0],
|
|
293
|
+
dest_dir="subs",
|
|
294
|
+
save_mode="extract",
|
|
295
|
+
)
|
|
296
|
+
print(result.srt_paths)
|
|
297
|
+
|
|
298
|
+
# Find the best subtitle for a video release name
|
|
299
|
+
best_title, version, score = client.best_for_file(
|
|
300
|
+
"Breaking.Bad.S05E14.720p.BluRay.x264-DEMAND"
|
|
301
|
+
)
|
|
302
|
+
|
|
303
|
+
# Download the match and associate it with the video filename
|
|
304
|
+
client.download(
|
|
305
|
+
version,
|
|
306
|
+
dest_dir=".",
|
|
307
|
+
save_mode="extract",
|
|
308
|
+
target_video="Breaking.Bad.S05E14.mkv",
|
|
309
|
+
)
|
|
310
|
+
|
|
311
|
+
# Download from a SubZone title URL
|
|
312
|
+
client.download_url(
|
|
313
|
+
"/subtitles/the-odyssey-2026",
|
|
314
|
+
lang="fa",
|
|
315
|
+
limit=1,
|
|
316
|
+
dest_dir="subs",
|
|
317
|
+
)
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
All client exceptions derive from `pysubzone.SubZoneError`. Specific errors include `NetworkError`, `TitleNotFoundError`, `NoSubtitleFoundError`, and `DownloadError`.
|
|
321
|
+
|
|
322
|
+
## How it works
|
|
323
|
+
|
|
324
|
+
The project is organized into a few focused modules:
|
|
325
|
+
|
|
326
|
+
```text
|
|
327
|
+
src/pysubzone/
|
|
328
|
+
client.py HTTP client, retries, signed-CDN downloads, ZIP verification
|
|
329
|
+
parsing.py Search, title, version, and browse-page parsers
|
|
330
|
+
models.py Data models with as_dict() support for JSON output
|
|
331
|
+
languages.py Language slugs and aliases (fa, en, tr, ...)
|
|
332
|
+
matcher.py Release-name parsing and video-folder scanning
|
|
333
|
+
scoring.py Subtitle-version scoring for auto-match
|
|
334
|
+
cli.py Typer command-line interface
|
|
335
|
+
tui.py Textual terminal interface
|
|
336
|
+
tests/ Offline tests using saved HTML fixtures
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
### Website endpoints and client methods
|
|
340
|
+
|
|
341
|
+
| SubZone route | PySubZone method |
|
|
342
|
+
|---|---|
|
|
343
|
+
| `/subtitles/searchbytitle?query=...` | `search()`, `search_exact()` |
|
|
344
|
+
| `/subtitles/<slug>` (optionally `/<lang>`) | `title()`, `title_versions()` |
|
|
345
|
+
| `/subtitles/<slug>/<lang>/<id>` | `get_version()` |
|
|
346
|
+
| `/subtitles/<slug>/<lang>/<id>/download` | `download()` |
|
|
347
|
+
| `/browse/popular|latest/...` | `browse()` |
|
|
348
|
+
|
|
349
|
+
Downloads follow a redirect to a signed CDN URL. Before saving a download, PySubZone verifies the ZIP file signature. This helps detect stale uploads that return an S3 `NoSuchKey` XML response with HTTP 200; these are reported as `DownloadError` with a hint to try another version.
|
|
350
|
+
|
|
351
|
+
## Development
|
|
352
|
+
|
|
353
|
+
Clone the repository, install the project in editable mode with development dependencies, and run the test suite:
|
|
354
|
+
|
|
355
|
+
```bash
|
|
356
|
+
pip install -e ".[dev]"
|
|
357
|
+
pytest
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
The test suite is designed to run **offline**. It uses saved HTML fixtures and synthetic release names, so tests do not need to access SubZone.
|
|
361
|
+
|
|
362
|
+
## Support the project
|
|
363
|
+
|
|
364
|
+
If PySubZone saves you time or makes subtitle management easier, consider supporting its continued development. Donations are entirely optional — using the project, reporting bugs, sharing feedback, and contributing code are all valuable ways to help.
|
|
365
|
+
|
|
366
|
+
See **[DONATE.md](DONATE.md)** for cryptocurrency donation options.
|
|
367
|
+
|
|
368
|
+
## License
|
|
369
|
+
|
|
370
|
+
PySubZone is released under the **MIT License**. See [LICENSE](LICENSE) for the full license text.
|
|
@@ -0,0 +1,314 @@
|
|
|
1
|
+
# PySubZone
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<strong>Find the right subtitle. Download it. Get back to watching.</strong>
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<a href="https://pypi.org/project/pysubzone/"><img src="https://img.shields.io/pypi/v/pysubzone?label=PyPI&color=blue" alt="PyPI version"></a>
|
|
9
|
+
<a href="https://pypi.org/project/pysubzone/"><img src="https://img.shields.io/pypi/pyversions/pysubzone" alt="Python versions"></a>
|
|
10
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license"></a>
|
|
11
|
+
</p>
|
|
12
|
+
|
|
13
|
+
**PySubZone** is a Python library, command-line tool, and interactive terminal app for searching and downloading subtitles from [SubZone](https://subzone.ir/), the Subf2m subtitle database.
|
|
14
|
+
|
|
15
|
+
Whether you need one subtitle or want to match subtitles for an entire video collection, PySubZone gives you a straightforward way to find the version that fits.
|
|
16
|
+
|
|
17
|
+
Inspired by [PyAddic7](https://github.com/mackeos/PyAddic7), which works with addic7ed.com.
|
|
18
|
+
|
|
19
|
+
## What can it do?
|
|
20
|
+
|
|
21
|
+
- **Search titles** — find movies and TV shows.
|
|
22
|
+
- **Browse subtitle versions** — see the uploads available for a title, with language filtering.
|
|
23
|
+
- **Download subtitles** — download a specific upload by reference or URL, or grab the newest uploads from a title page.
|
|
24
|
+
- **Match video files automatically** — search for suitable subtitles based on release names, including episode number, resolution, source, and release group.
|
|
25
|
+
- **Use it your way** — choose the Python API, the command-line interface, or the interactive terminal UI.
|
|
26
|
+
|
|
27
|
+
The CLI is built with [Typer](https://typer.tiangolo.com/) and Rich, while the interactive TUI is powered by [Textual](https://github.com/Textualize/textual).
|
|
28
|
+
|
|
29
|
+
> **A note on responsible use:** PySubZone accesses a public website for personal use. Please keep request rates reasonable and respect the source website's terms. Do not redistribute downloaded subtitles.
|
|
30
|
+
|
|
31
|
+
## Packages
|
|
32
|
+
|
|
33
|
+
| Package | Purpose | PyPI |
|
|
34
|
+
|---|---|---|
|
|
35
|
+
| **PySubZone** (`pysubzone`) | Main Python API, CLI, and TUI package | [pypi.org/project/pysubzone](https://pypi.org/project/pysubzone/) |
|
|
36
|
+
| **PySubF2M** (`pysubf2m`) | Compatibility package | coming soon |
|
|
37
|
+
|
|
38
|
+
## Installation
|
|
39
|
+
|
|
40
|
+
Python **3.9 or newer** is required.
|
|
41
|
+
|
|
42
|
+
Install the main package with pip:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
pip install pysubzone
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Or use [pipx](https://pipx.pypa.io/) to install the command-line application in an isolated environment:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
pipx install pysubzone
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
A compatibility package, **PySubF2M** (`pysubf2m`), is planned as a separate release.
|
|
55
|
+
|
|
56
|
+
After installing PySubZone, the `subz` command is available. You can also run it with:
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
python -m pysubzone
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Quick start
|
|
63
|
+
|
|
64
|
+
Search for a title, inspect its subtitle versions, and download one:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
# Search for a movie or show
|
|
68
|
+
subz search "dexter resurrection"
|
|
69
|
+
|
|
70
|
+
# Show the available Farsi subtitle versions
|
|
71
|
+
subz versions dexter-resurrection-season-2 -l fa
|
|
72
|
+
|
|
73
|
+
# Download a specific version
|
|
74
|
+
subz download dexter-resurrection-season-2/farsi_persian/3770171
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Command-line reference
|
|
78
|
+
|
|
79
|
+
```text
|
|
80
|
+
subz search QUERY [-l LANG] [--json] Search titles
|
|
81
|
+
subz versions TITLE [-l LANG] [--json] List subtitle uploads
|
|
82
|
+
subz download REF [-o DIR] [--zip] [--json] Download by reference, URL, or slug
|
|
83
|
+
subz url URL [-l LANG] [-n N] [--zip] Download from a SubZone URL
|
|
84
|
+
subz filename FILE [-l LANG] [--no-download] Find the best subtitle for one video
|
|
85
|
+
subz auto PATH [-l LANG] [--dry-run] [--zip] Match videos in a folder
|
|
86
|
+
subz popular [--mode popular|latest] Browse popular or latest uploads
|
|
87
|
+
[-t all|film|series|music] [-p PAGE]
|
|
88
|
+
subz tui Open the interactive interface
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Global options:
|
|
92
|
+
|
|
93
|
+
- `--base-url` — use a different base URL.
|
|
94
|
+
- `--user-agent` — set the HTTP user agent.
|
|
95
|
+
- `--timeout` — configure the request timeout.
|
|
96
|
+
- `--retries` — configure retry attempts.
|
|
97
|
+
- `-v`, `--verbose` — enable verbose output.
|
|
98
|
+
|
|
99
|
+
Every data command supports `--json` for scripting and automation.
|
|
100
|
+
|
|
101
|
+
Exit codes follow the PyAddic7 contract:
|
|
102
|
+
|
|
103
|
+
| Code | Meaning |
|
|
104
|
+
|---:|---|
|
|
105
|
+
| `0` | Success |
|
|
106
|
+
| `1` | Nothing found |
|
|
107
|
+
| `2` | Error |
|
|
108
|
+
|
|
109
|
+
### Search and browse
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
# Search for a title
|
|
113
|
+
subz search "dexter resurrection"
|
|
114
|
+
|
|
115
|
+
# Search for titles with Farsi subtitles
|
|
116
|
+
subz search odyssey -l fa
|
|
117
|
+
|
|
118
|
+
# List Farsi subtitle versions for a title
|
|
119
|
+
subz versions dexter-resurrection-season-2 -l fa
|
|
120
|
+
|
|
121
|
+
# Browse popular movie uploads
|
|
122
|
+
subz popular -t film
|
|
123
|
+
|
|
124
|
+
# Browse the latest series uploads, page 2
|
|
125
|
+
subz popular --mode latest -t series -p 2
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### Download subtitles
|
|
129
|
+
|
|
130
|
+
A **reference** identifies one subtitle upload and follows this format:
|
|
131
|
+
|
|
132
|
+
```text
|
|
133
|
+
<slug>/<lang>/<id>
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
You can copy a reference from a version listing.
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
# Download using a reference
|
|
140
|
+
subz download dexter-resurrection-season-2/farsi_persian/3770171
|
|
141
|
+
|
|
142
|
+
# Download using the full subtitle URL
|
|
143
|
+
subz download https://subzone.ir/subtitles/dexter-resurrection-season-2/farsi_persian/3770171
|
|
144
|
+
|
|
145
|
+
# Grab the two newest Farsi uploads from a title URL
|
|
146
|
+
subz url https://subzone.ir/subtitles/the-odyssey-2026 -l fa -n 2
|
|
147
|
+
|
|
148
|
+
# Grab all available uploads from that title URL
|
|
149
|
+
subz url https://subzone.ir/subtitles/the-odyssey-2026 -l fa -n 0
|
|
150
|
+
|
|
151
|
+
# Download by title slug
|
|
152
|
+
subz download the-odyssey-2026 -l en --zip --out ./downloads
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
By default, downloaded archives are **extracted** and subtitle files receive a language suffix, such as `Movie.fa.srt` (or retain the release name when the archive includes one).
|
|
156
|
+
|
|
157
|
+
Useful output options:
|
|
158
|
+
|
|
159
|
+
- `--zip` — keep the original archive instead of extracting it.
|
|
160
|
+
- `--no-suffix` — do not append a language suffix.
|
|
161
|
+
- `--lang-suffix XX` — choose a custom language suffix.
|
|
162
|
+
- `-o DIR` / `--out DIR` — choose the output directory.
|
|
163
|
+
|
|
164
|
+
### Automatically match a video collection
|
|
165
|
+
|
|
166
|
+
PySubZone can inspect video release names, search the site, score available subtitle versions, and download the best match.
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
# Find a subtitle for one video
|
|
170
|
+
subz filename "Dexter.Resurrection.S02E01.1080p.AMZN.WEB-DL-NTb.mkv"
|
|
171
|
+
|
|
172
|
+
# Preview matches in a folder without downloading
|
|
173
|
+
subz auto /media/shows -l fa --dry-run
|
|
174
|
+
|
|
175
|
+
# Download and extract subtitles beside the videos
|
|
176
|
+
subz auto /media/shows -l fa
|
|
177
|
+
|
|
178
|
+
# Save all subtitles into a separate folder
|
|
179
|
+
subz auto /media/shows -l fa -o ./subs
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
For each video, the release name is parsed for details such as the title, season and episode, resolution, source, and release group. Subtitle versions with conflicting episode numbers are rejected, exact release matches are preferred, and season packs can be used as fallbacks.
|
|
183
|
+
|
|
184
|
+
A failed match does not stop the whole collection: unsuccessful files are included in the final summary.
|
|
185
|
+
|
|
186
|
+
## Interactive terminal interface
|
|
187
|
+
|
|
188
|
+
Prefer an interactive experience? Run:
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
subz tui
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
The TUI guides you through the process:
|
|
195
|
+
|
|
196
|
+
1. Enter a search query to see matching titles.
|
|
197
|
+
2. Select a title to browse its uploaded subtitle versions.
|
|
198
|
+
3. Filter versions by language.
|
|
199
|
+
4. Select a version to open the download dialog.
|
|
200
|
+
5. Choose a destination and whether to extract subtitles or keep the ZIP archive.
|
|
201
|
+
|
|
202
|
+
The download dialog includes a live progress bar.
|
|
203
|
+
|
|
204
|
+
**Keyboard shortcuts**
|
|
205
|
+
|
|
206
|
+
| Key | Action |
|
|
207
|
+
|---|---|
|
|
208
|
+
| `Esc` | Go back or close the current view |
|
|
209
|
+
| `r` | Refresh subtitle versions |
|
|
210
|
+
| `Ctrl+Q` | Quit |
|
|
211
|
+
|
|
212
|
+
### TUI screenshots
|
|
213
|
+
|
|
214
|
+
| Search | Subtitle versions | Download |
|
|
215
|
+
|---|---|---|
|
|
216
|
+
|  |  |  |
|
|
217
|
+
|
|
218
|
+
## Python API
|
|
219
|
+
|
|
220
|
+
You can use PySubZone directly from your own Python projects:
|
|
221
|
+
|
|
222
|
+
```python
|
|
223
|
+
from pysubzone import SubZoneClient
|
|
224
|
+
|
|
225
|
+
client = SubZoneClient(timeout=20)
|
|
226
|
+
|
|
227
|
+
# Search for titles
|
|
228
|
+
results = client.search("dexter resurrection")
|
|
229
|
+
|
|
230
|
+
# Find a title and list its Farsi subtitle versions
|
|
231
|
+
title = client.search_exact("Dexter Resurrection")
|
|
232
|
+
versions = client.title_versions(title.slug, "farsi_persian")
|
|
233
|
+
|
|
234
|
+
# Download the first version and extract it into ./subs
|
|
235
|
+
result = client.download(
|
|
236
|
+
versions[0],
|
|
237
|
+
dest_dir="subs",
|
|
238
|
+
save_mode="extract",
|
|
239
|
+
)
|
|
240
|
+
print(result.srt_paths)
|
|
241
|
+
|
|
242
|
+
# Find the best subtitle for a video release name
|
|
243
|
+
best_title, version, score = client.best_for_file(
|
|
244
|
+
"Breaking.Bad.S05E14.720p.BluRay.x264-DEMAND"
|
|
245
|
+
)
|
|
246
|
+
|
|
247
|
+
# Download the match and associate it with the video filename
|
|
248
|
+
client.download(
|
|
249
|
+
version,
|
|
250
|
+
dest_dir=".",
|
|
251
|
+
save_mode="extract",
|
|
252
|
+
target_video="Breaking.Bad.S05E14.mkv",
|
|
253
|
+
)
|
|
254
|
+
|
|
255
|
+
# Download from a SubZone title URL
|
|
256
|
+
client.download_url(
|
|
257
|
+
"/subtitles/the-odyssey-2026",
|
|
258
|
+
lang="fa",
|
|
259
|
+
limit=1,
|
|
260
|
+
dest_dir="subs",
|
|
261
|
+
)
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
All client exceptions derive from `pysubzone.SubZoneError`. Specific errors include `NetworkError`, `TitleNotFoundError`, `NoSubtitleFoundError`, and `DownloadError`.
|
|
265
|
+
|
|
266
|
+
## How it works
|
|
267
|
+
|
|
268
|
+
The project is organized into a few focused modules:
|
|
269
|
+
|
|
270
|
+
```text
|
|
271
|
+
src/pysubzone/
|
|
272
|
+
client.py HTTP client, retries, signed-CDN downloads, ZIP verification
|
|
273
|
+
parsing.py Search, title, version, and browse-page parsers
|
|
274
|
+
models.py Data models with as_dict() support for JSON output
|
|
275
|
+
languages.py Language slugs and aliases (fa, en, tr, ...)
|
|
276
|
+
matcher.py Release-name parsing and video-folder scanning
|
|
277
|
+
scoring.py Subtitle-version scoring for auto-match
|
|
278
|
+
cli.py Typer command-line interface
|
|
279
|
+
tui.py Textual terminal interface
|
|
280
|
+
tests/ Offline tests using saved HTML fixtures
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
### Website endpoints and client methods
|
|
284
|
+
|
|
285
|
+
| SubZone route | PySubZone method |
|
|
286
|
+
|---|---|
|
|
287
|
+
| `/subtitles/searchbytitle?query=...` | `search()`, `search_exact()` |
|
|
288
|
+
| `/subtitles/<slug>` (optionally `/<lang>`) | `title()`, `title_versions()` |
|
|
289
|
+
| `/subtitles/<slug>/<lang>/<id>` | `get_version()` |
|
|
290
|
+
| `/subtitles/<slug>/<lang>/<id>/download` | `download()` |
|
|
291
|
+
| `/browse/popular|latest/...` | `browse()` |
|
|
292
|
+
|
|
293
|
+
Downloads follow a redirect to a signed CDN URL. Before saving a download, PySubZone verifies the ZIP file signature. This helps detect stale uploads that return an S3 `NoSuchKey` XML response with HTTP 200; these are reported as `DownloadError` with a hint to try another version.
|
|
294
|
+
|
|
295
|
+
## Development
|
|
296
|
+
|
|
297
|
+
Clone the repository, install the project in editable mode with development dependencies, and run the test suite:
|
|
298
|
+
|
|
299
|
+
```bash
|
|
300
|
+
pip install -e ".[dev]"
|
|
301
|
+
pytest
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
The test suite is designed to run **offline**. It uses saved HTML fixtures and synthetic release names, so tests do not need to access SubZone.
|
|
305
|
+
|
|
306
|
+
## Support the project
|
|
307
|
+
|
|
308
|
+
If PySubZone saves you time or makes subtitle management easier, consider supporting its continued development. Donations are entirely optional — using the project, reporting bugs, sharing feedback, and contributing code are all valuable ways to help.
|
|
309
|
+
|
|
310
|
+
See **[DONATE.md](DONATE.md)** for cryptocurrency donation options.
|
|
311
|
+
|
|
312
|
+
## License
|
|
313
|
+
|
|
314
|
+
PySubZone is released under the **MIT License**. See [LICENSE](LICENSE) for the full license text.
|