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.
@@ -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.
@@ -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
+ | ![Search screen](docs/tui_search.svg) | ![Versions screen](docs/tui_versions.svg) | ![Download dialog](docs/tui_download.svg) |
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
+ | ![Search screen](docs/tui_search.svg) | ![Versions screen](docs/tui_versions.svg) | ![Download dialog](docs/tui_download.svg) |
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.