rayohx-cli 0.1.0__py3-none-any.whl

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,190 @@
1
+ """How a download runs and ends: pausing with a key, stopping on Ctrl-C, and the result."""
2
+
3
+ import signal
4
+ import sys
5
+ from collections.abc import Callable, Generator
6
+ from contextlib import contextmanager
7
+ from types import FrameType
8
+
9
+ import typer
10
+ from rayohx import Downloader, DownloadResult, result_to_dict
11
+ from rayohx.errors import RayoHXError
12
+
13
+ from rayohx_cli import format as fmt
14
+ from rayohx_cli import output
15
+ from rayohx_cli.cli.common import EXIT_CANCELLED, EXIT_FAILED
16
+
17
+
18
+ @contextmanager
19
+ def graceful_interrupt(downloader: Downloader) -> Generator[None]:
20
+ """The first Ctrl-C stops the download cleanly; a second one quits at once."""
21
+ presses = 0
22
+
23
+ def handler(signum: int, frame: FrameType | None) -> None:
24
+ nonlocal presses
25
+ presses += 1
26
+ if presses == 1:
27
+ downloader.cancel()
28
+ output.message("Stopping... press Ctrl-C again to quit at once.")
29
+ else:
30
+ raise KeyboardInterrupt
31
+
32
+ def toggle_pause(signum: int, frame: FrameType | None) -> None:
33
+ if downloader.is_paused:
34
+ downloader.resume()
35
+ output.message("Resumed.")
36
+ else:
37
+ downloader.pause()
38
+ output.message("Paused. Send the same signal again to continue.")
39
+
40
+ try:
41
+ previous = signal.signal(signal.SIGINT, handler)
42
+ except ValueError: # not the main thread: signals cannot be handled here
43
+ yield
44
+ return
45
+ # SIGUSR1 pauses and continues where the system has it (not on Windows).
46
+ pause_signal = getattr(signal, "SIGUSR1", None)
47
+ previous_pause = signal.signal(pause_signal, toggle_pause) if pause_signal else None
48
+ try:
49
+ yield
50
+ finally:
51
+ signal.signal(signal.SIGINT, previous)
52
+ if pause_signal is not None and previous_pause is not None:
53
+ signal.signal(pause_signal, previous_pause)
54
+
55
+
56
+ PAUSE_KEYS = frozenset("pP ")
57
+ POLL_SECONDS = 0.1
58
+
59
+
60
+ @contextmanager
61
+ def _key_source() -> Generator[Callable[[float], str | None] | None]:
62
+ """Yield a function that waits up to a timeout for one key press, or None with no keyboard."""
63
+ try:
64
+ interactive = sys.stdin is not None and sys.stdin.isatty()
65
+ except (OSError, ValueError):
66
+ interactive = False
67
+ if not interactive:
68
+ yield None
69
+ return
70
+ if sys.platform == "win32":
71
+ import msvcrt
72
+ import time
73
+
74
+ def poll_windows(timeout: float) -> str | None:
75
+ deadline = time.monotonic() + timeout
76
+ while True:
77
+ if msvcrt.kbhit():
78
+ key = msvcrt.getwch()
79
+ if key in ("\x00", "\xe0"): # the first half of an arrow or function key
80
+ msvcrt.getwch()
81
+ return None
82
+ return key
83
+ if time.monotonic() >= deadline:
84
+ return None
85
+ time.sleep(0.02)
86
+
87
+ yield poll_windows
88
+ return
89
+ import select
90
+ import termios
91
+ import tty
92
+
93
+ fd = sys.stdin.fileno()
94
+ try:
95
+ saved = termios.tcgetattr(fd)
96
+ tty.setcbreak(fd)
97
+ except termios.error:
98
+ yield None
99
+ return
100
+
101
+ def poll_unix(timeout: float) -> str | None:
102
+ ready, _, _ = select.select([fd], [], [], timeout)
103
+ return sys.stdin.read(1) if ready else None
104
+
105
+ try:
106
+ yield poll_unix
107
+ finally:
108
+ termios.tcsetattr(fd, termios.TCSADRAIN, saved)
109
+
110
+
111
+ @contextmanager
112
+ def pause_toggle(
113
+ downloader: Downloader,
114
+ *,
115
+ source: Callable[[float], str | None] | None = None,
116
+ ) -> Generator[None]:
117
+ """While the download runs, the P key (or the space bar) pauses it and resumes it again.
118
+
119
+ Does nothing when there is no keyboard to read, such as when input is piped. ``source`` is
120
+ for tests: a function that waits up to a timeout for one key and returns it.
121
+ """
122
+ import threading
123
+
124
+ with _key_source() as found:
125
+ poll = source or found
126
+ if poll is None:
127
+ yield
128
+ return
129
+ stop = threading.Event()
130
+
131
+ def watch() -> None:
132
+ paused = False
133
+ while not stop.is_set():
134
+ key = poll(POLL_SECONDS)
135
+ if key is None or key not in PAUSE_KEYS:
136
+ continue
137
+ paused = not paused
138
+ if paused:
139
+ downloader.pause()
140
+ output.message("Paused. Press P to resume.", style="yellow")
141
+ else:
142
+ downloader.resume()
143
+ output.message("Resumed.")
144
+
145
+ output.message("Press P to pause or resume, Ctrl-C to stop.")
146
+ thread = threading.Thread(target=watch, name="rayohx-keys", daemon=True)
147
+ thread.start()
148
+ try:
149
+ yield
150
+ finally:
151
+ stop.set()
152
+ thread.join(1)
153
+
154
+
155
+ def finish(
156
+ result: DownloadResult,
157
+ downloader: Downloader,
158
+ *,
159
+ json_output: bool,
160
+ documents: list[dict[str, object]] | None = None,
161
+ ) -> None:
162
+ """Report how the download ended and set the exit code.
163
+
164
+ With ``documents`` (several downloads), the JSON result is added to it instead of printed,
165
+ so the caller can print one array at the end.
166
+ """
167
+ if json_output and documents is not None:
168
+ documents.append(result_to_dict(result))
169
+ elif json_output:
170
+ output.print_json(result_to_dict(result))
171
+ if result.success and result.output is not None:
172
+ if not json_output:
173
+ output.data(str(result.output.path))
174
+ output.message(
175
+ f"Saved {result.output.path.name} ({fmt.size(result.output.size_bytes)}) "
176
+ f"in {fmt.duration(result.elapsed_seconds)}",
177
+ style="green",
178
+ )
179
+ return
180
+ if result.cancelled:
181
+ output.message("Cancelled.", style="yellow")
182
+ raise typer.Exit(EXIT_CANCELLED)
183
+ exc = downloader.exception
184
+ if isinstance(exc, RayoHXError):
185
+ output.error_from(exc)
186
+ elif exc is not None:
187
+ raise exc # unexpected: reported once, by run()
188
+ else:
189
+ output.error(result.error or "The download failed.")
190
+ raise typer.Exit(EXIT_FAILED)
rayohx_cli/cli/root.py ADDED
@@ -0,0 +1,105 @@
1
+ """The root command: the program's name, help, and the options every command takes."""
2
+
3
+ import logging
4
+ from collections.abc import Mapping
5
+ from pathlib import Path
6
+ from typing import Annotated
7
+
8
+ import click
9
+ import typer
10
+ from rayohx import __version__
11
+ from rayohx.errors import ConfigurationError
12
+
13
+ from rayohx_cli import output
14
+ from rayohx_cli.cli.common import usage_error
15
+ from rayohx_cli.settings import find_config, load_config
16
+
17
+ app = typer.Typer(
18
+ name="rayohx",
19
+ help=(
20
+ "Download HLS (.m3u8) streams: pick the quality, audio and subtitles, and save "
21
+ "one file. Use [bold]rayohx info URL[/bold] to look first, "
22
+ "[bold]rayohx download URL[/bold] to save."
23
+ ),
24
+ no_args_is_help=True,
25
+ rich_markup_mode="rich",
26
+ # run() reports errors briefly; Typer's own traceback would show local variables.
27
+ pretty_exceptions_enable=False,
28
+ )
29
+
30
+
31
+ def _show_version(value: bool) -> None:
32
+ if value:
33
+ output.console.print(f"rayohx {__version__}")
34
+ raise typer.Exit
35
+
36
+
37
+ @app.callback()
38
+ def main(
39
+ ctx: typer.Context,
40
+ version: Annotated[
41
+ bool,
42
+ typer.Option(
43
+ "--version",
44
+ "-V",
45
+ callback=_show_version,
46
+ is_eager=True,
47
+ help="Show the version and exit.",
48
+ ),
49
+ ] = False,
50
+ verbose: Annotated[
51
+ bool,
52
+ typer.Option("--verbose", "-v", envvar="RAYOHX_VERBOSE", help="Show extra detail."),
53
+ ] = False,
54
+ quiet: Annotated[
55
+ bool,
56
+ typer.Option(
57
+ "--quiet", "-q", envvar="RAYOHX_QUIET", help="Show only errors (and the result)."
58
+ ),
59
+ ] = False,
60
+ no_color: Annotated[
61
+ bool,
62
+ typer.Option("--no-color", envvar="RAYOHX_NO_COLOR", help="Disable colored output."),
63
+ ] = False,
64
+ log_file: Annotated[
65
+ Path | None,
66
+ typer.Option(
67
+ "--log-file",
68
+ envvar="RAYOHX_LOG_FILE",
69
+ help="Also write a detailed log to this file (secrets are removed).",
70
+ ),
71
+ ] = None,
72
+ config: Annotated[
73
+ Path | None,
74
+ typer.Option(
75
+ "--config",
76
+ envvar="RAYOHX_CONFIG",
77
+ help="A settings file (TOML) with defaults for the options.",
78
+ ),
79
+ ] = None,
80
+ no_config: Annotated[bool, typer.Option("--no-config", help="Ignore settings files.")] = False,
81
+ ) -> None:
82
+ """Options that apply to every command."""
83
+ if verbose and quiet:
84
+ raise typer.BadParameter("--verbose and --quiet cannot be used together.")
85
+ if config is not None and no_config:
86
+ raise typer.BadParameter("--config and --no-config cannot be used together.")
87
+ output.configure(no_color=no_color, verbose=verbose, quiet=quiet)
88
+ level = logging.DEBUG if verbose else logging.ERROR if quiet else logging.WARNING
89
+ output.configure_logging(level, verbose=verbose, log_file=log_file)
90
+ if no_config:
91
+ return
92
+ try:
93
+ path = find_config(config)
94
+ if path is None:
95
+ return
96
+ commands: Mapping[str, click.Command] = getattr(typer.main.get_command(app), "commands", {})
97
+ known = {opt.name for command in commands.values() for opt in command.params if opt.name}
98
+ loaded = load_config(path, known)
99
+ except ConfigurationError as exc:
100
+ usage_error(exc)
101
+ ctx.default_map = {
102
+ name: {k: v for k, v in loaded.items() if k in {o.name for o in command.params}}
103
+ for name, command in commands.items()
104
+ }
105
+ logging.getLogger("rayohx.cli").debug("Using settings from %s", path)
rayohx_cli/events.py ADDED
@@ -0,0 +1,40 @@
1
+ """Following a download as machine-readable events (``--events``)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from typing import TYPE_CHECKING, Any
7
+
8
+ from rayohx_cli import output
9
+
10
+ if TYPE_CHECKING:
11
+ from rayohx.events import DownloadEvent
12
+
13
+
14
+ def event_to_dict(event: DownloadEvent) -> dict[str, Any]:
15
+ """A JSON-ready view of one event. Messages and data are already free of secrets."""
16
+ document: dict[str, Any] = {
17
+ "type": event.type.value,
18
+ "download_id": event.download_id,
19
+ "state": event.state.value,
20
+ "timestamp": round(event.timestamp, 3),
21
+ }
22
+ if event.segment_index is not None:
23
+ document["segment_index"] = event.segment_index
24
+ if event.message:
25
+ document["message"] = event.message
26
+ if event.data:
27
+ document["data"] = dict(event.data)
28
+ if event.progress is not None:
29
+ from rayohx import progress_to_dict
30
+
31
+ document["progress"] = progress_to_dict(event.progress)
32
+ return document
33
+
34
+
35
+ class EventStream:
36
+ """Writes each event as one JSON line on stderr, so stdout still holds only the result."""
37
+
38
+ def __call__(self, event: DownloadEvent) -> None:
39
+ line = json.dumps(event_to_dict(event), ensure_ascii=False, default=str)
40
+ output.err_console.print(line, markup=False, highlight=False, soft_wrap=True)
rayohx_cli/format.py ADDED
@@ -0,0 +1,34 @@
1
+ """Turning numbers into short text for people."""
2
+
3
+ from rayohx.errors import format_bytes
4
+
5
+
6
+ def size(count: int | float) -> str:
7
+ """Bytes as ``1.5 MiB``."""
8
+ return format_bytes(int(count))
9
+
10
+
11
+ def rate(bytes_per_second: float) -> str:
12
+ """A speed as ``4.2 MiB/s``."""
13
+ return f"{format_bytes(int(bytes_per_second))}/s"
14
+
15
+
16
+ def bitrate(bits_per_second: int) -> str:
17
+ """A stream's bit rate as ``2.8 Mbit/s``."""
18
+ if bits_per_second >= 1_000_000:
19
+ return f"{bits_per_second / 1_000_000:.1f} Mbit/s"
20
+ return f"{round(bits_per_second / 1000)} kbit/s"
21
+
22
+
23
+ def duration(seconds: float | None) -> str:
24
+ """A time span as ``45s``, ``3:07`` or ``1:02:03``; ``--`` when it is not known."""
25
+ if seconds is None:
26
+ return "--"
27
+ total = max(0, round(seconds))
28
+ hours, remainder = divmod(total, 3600)
29
+ minutes, secs = divmod(remainder, 60)
30
+ if hours:
31
+ return f"{hours}:{minutes:02d}:{secs:02d}"
32
+ if minutes:
33
+ return f"{minutes}:{secs:02d}"
34
+ return f"{secs}s"
rayohx_cli/output.py ADDED
@@ -0,0 +1,119 @@
1
+ """Rich consoles shared by every command, so all output is written the same way.
2
+
3
+ Data goes to ``console`` (stdout) and diagnostics go to ``err_console`` (stderr), so a command's
4
+ result can be piped or captured while its messages still reach the person. Rich honors the
5
+ ``NO_COLOR`` environment variable and disables color when output is piped. Nothing prints with
6
+ ``print``.
7
+ """
8
+
9
+ import json
10
+ import logging
11
+ from dataclasses import dataclass
12
+ from pathlib import Path
13
+ from typing import Any
14
+
15
+ from rayohx import configure_logging as configure_library_logging
16
+ from rayohx.errors import RayoHXError
17
+ from rayohx.logs import RedactionFilter
18
+ from rich.console import Console
19
+ from rich.text import Text
20
+
21
+ console = Console()
22
+ err_console = Console(stderr=True)
23
+
24
+
25
+ @dataclass
26
+ class Settings:
27
+ """Global output options, set once by the Typer callback."""
28
+
29
+ verbose: bool = False
30
+ quiet: bool = False
31
+
32
+
33
+ settings = Settings()
34
+
35
+
36
+ def configure(*, no_color: bool, verbose: bool, quiet: bool = False) -> None:
37
+ """Apply global output options."""
38
+ settings.verbose = verbose
39
+ settings.quiet = quiet
40
+ for target in (console, err_console):
41
+ target.no_color = no_color or target.no_color
42
+
43
+
44
+ def error(message: str, hint: str | None = None) -> None:
45
+ """Print an error message (and what to try) to stderr."""
46
+ err_console.print(Text(f"Error: {message}", style="bold red"))
47
+ if hint:
48
+ err_console.print(Text(hint, style="dim"))
49
+
50
+
51
+ def error_from(exc: RayoHXError) -> None:
52
+ """Print a library error with its hint."""
53
+ error(exc.message, exc.hint)
54
+
55
+
56
+ def message(text: str, *, style: str | None = None) -> None:
57
+ """Print a status message to stderr, unless ``--quiet``."""
58
+ if not settings.quiet:
59
+ err_console.print(Text(text, style=style or ""))
60
+
61
+
62
+ def data(text: str) -> None:
63
+ """Print one line of result data to stdout exactly as given (no wrapping, no markup)."""
64
+ console.print(Text(text), soft_wrap=True, highlight=False)
65
+
66
+
67
+ def print_json(value: Any) -> None:
68
+ """Print ``value`` as JSON to stdout. Plain text, so it is the same on every terminal."""
69
+ text = json.dumps(value, indent=2, ensure_ascii=False)
70
+ console.print(text, soft_wrap=True, markup=False, highlight=False)
71
+
72
+
73
+ def print_exception(exc: Exception) -> None:
74
+ """Report an unexpected error: a short message, plus a traceback only with ``--verbose``.
75
+
76
+ Local variables are never shown, since they can contain secrets.
77
+ """
78
+ error(f"{type(exc).__name__}: {exc}" if str(exc) else type(exc).__name__)
79
+ if settings.verbose:
80
+ err_console.print_exception(show_locals=False)
81
+ else:
82
+ err_console.print(Text("Run with --verbose for details.", style="dim"))
83
+
84
+
85
+ class _ConsoleHandler(logging.Handler):
86
+ """Writes log records through the error console, so they do not tear a progress bar."""
87
+
88
+ def __init__(self, level: int) -> None:
89
+ super().__init__(level)
90
+
91
+ def emit(self, record: logging.LogRecord) -> None:
92
+ text = self.format(record)
93
+ style = "yellow" if record.levelno >= logging.WARNING else "dim"
94
+ if record.levelno >= logging.ERROR:
95
+ style = "red"
96
+ err_console.print(Text(text, style=style), soft_wrap=True)
97
+
98
+
99
+ _handler: _ConsoleHandler | None = None
100
+
101
+
102
+ def configure_logging(level: int, *, verbose: bool, log_file: Path | None = None) -> None:
103
+ """Show the library's log records on stderr at ``level``, replacing any set up before.
104
+
105
+ With ``log_file`` everything (down to debug) is also written there, with secrets removed.
106
+ """
107
+ global _handler
108
+ logger = logging.getLogger("rayohx")
109
+ if _handler is not None:
110
+ logger.removeHandler(_handler)
111
+ # The library sets up (or, without a file, clears) its own file handler.
112
+ configure_library_logging(logging.DEBUG, console=False, log_file=log_file)
113
+ _handler = _ConsoleHandler(level)
114
+ _handler.setFormatter(
115
+ logging.Formatter("%(asctime)s %(name)s: %(message)s" if verbose else "%(message)s")
116
+ )
117
+ _handler.addFilter(RedactionFilter())
118
+ logger.addHandler(_handler)
119
+ logger.setLevel(logging.DEBUG if log_file else level)
@@ -0,0 +1,147 @@
1
+ """The command line's options, defined once and shared by every command that takes them.
2
+
3
+ Every option that takes one value can also be set with a ``RAYOHX_<NAME>`` environment variable
4
+ (``RAYOHX_QUALITY``, ``RAYOHX_PROXY``) or in the settings file; the command line wins over both.
5
+ """
6
+
7
+ from rayohx_cli.params.display import (
8
+ Events,
9
+ JsonOutput,
10
+ ProgressMode,
11
+ )
12
+ from rayohx_cli.params.engine import (
13
+ AllowFileKeys,
14
+ BufferSize,
15
+ Concurrency,
16
+ KeepState,
17
+ MaxTempSize,
18
+ ReserveSpace,
19
+ Resume,
20
+ SpaceCheck,
21
+ Storage,
22
+ Workspace,
23
+ )
24
+ from rayohx_cli.params.network import (
25
+ Backoff,
26
+ BaseUrl,
27
+ CaBundle,
28
+ ClientCert,
29
+ ClientKey,
30
+ ClientKeyPassword,
31
+ ConnectTimeout,
32
+ Cookie,
33
+ CookieFile,
34
+ CredentialHost,
35
+ EnvProxy,
36
+ Header,
37
+ Insecure,
38
+ MaxRedirects,
39
+ Origin,
40
+ Proxy,
41
+ ProxyPassword,
42
+ ProxyUsername,
43
+ RateLimit,
44
+ ReadTimeout,
45
+ Referer,
46
+ Retries,
47
+ Timeout,
48
+ UserAgent,
49
+ )
50
+ from rayohx_cli.params.output import (
51
+ Directory,
52
+ Ffmpeg,
53
+ Format,
54
+ OutputPath,
55
+ Overwrite,
56
+ RemuxBackendOption,
57
+ Validate,
58
+ )
59
+ from rayohx_cli.params.selection import (
60
+ Audio,
61
+ AudioName,
62
+ Bandwidth,
63
+ Codec,
64
+ InputFile,
65
+ MaxBitrate,
66
+ MaxFrameRate,
67
+ MaxResolution,
68
+ PlaylistFile,
69
+ Quality,
70
+ Resolution,
71
+ StopOnError,
72
+ SubtitleName,
73
+ Subtitles,
74
+ Url,
75
+ Urls,
76
+ Variant,
77
+ VariantName,
78
+ VideoOnly,
79
+ VideoRange,
80
+ )
81
+
82
+ __all__ = [
83
+ "AllowFileKeys",
84
+ "Audio",
85
+ "AudioName",
86
+ "Backoff",
87
+ "Bandwidth",
88
+ "BaseUrl",
89
+ "BufferSize",
90
+ "CaBundle",
91
+ "ClientCert",
92
+ "ClientKey",
93
+ "ClientKeyPassword",
94
+ "Codec",
95
+ "Concurrency",
96
+ "ConnectTimeout",
97
+ "Cookie",
98
+ "CookieFile",
99
+ "CredentialHost",
100
+ "Directory",
101
+ "EnvProxy",
102
+ "Events",
103
+ "Ffmpeg",
104
+ "Format",
105
+ "Header",
106
+ "InputFile",
107
+ "Insecure",
108
+ "JsonOutput",
109
+ "KeepState",
110
+ "MaxBitrate",
111
+ "MaxFrameRate",
112
+ "MaxRedirects",
113
+ "MaxResolution",
114
+ "MaxTempSize",
115
+ "Origin",
116
+ "OutputPath",
117
+ "Overwrite",
118
+ "PlaylistFile",
119
+ "ProgressMode",
120
+ "Proxy",
121
+ "ProxyPassword",
122
+ "ProxyUsername",
123
+ "Quality",
124
+ "RateLimit",
125
+ "ReadTimeout",
126
+ "Referer",
127
+ "RemuxBackendOption",
128
+ "ReserveSpace",
129
+ "Resolution",
130
+ "Resume",
131
+ "Retries",
132
+ "SpaceCheck",
133
+ "StopOnError",
134
+ "Storage",
135
+ "SubtitleName",
136
+ "Subtitles",
137
+ "Timeout",
138
+ "Url",
139
+ "Urls",
140
+ "UserAgent",
141
+ "Validate",
142
+ "Variant",
143
+ "VariantName",
144
+ "VideoOnly",
145
+ "VideoRange",
146
+ "Workspace",
147
+ ]
@@ -0,0 +1,35 @@
1
+ """Display options."""
2
+
3
+ from typing import Annotated
4
+
5
+ import typer
6
+
7
+ from rayohx_cli.params.panels import DISPLAY
8
+
9
+ Events = Annotated[
10
+ bool,
11
+ typer.Option(
12
+ "--events/--no-events",
13
+ envvar="RAYOHX_EVENTS",
14
+ help="Write every download event as one JSON line on stderr, for other programs. "
15
+ "Replaces the progress display.",
16
+ rich_help_panel=DISPLAY,
17
+ ),
18
+ ]
19
+ JsonOutput = Annotated[
20
+ bool,
21
+ typer.Option(
22
+ "--json",
23
+ help="Print the result as JSON on stdout, for other programs.",
24
+ rich_help_panel=DISPLAY,
25
+ ),
26
+ ]
27
+ ProgressMode = Annotated[
28
+ str,
29
+ typer.Option(
30
+ "--progress",
31
+ envvar="RAYOHX_PROGRESS",
32
+ help="How to show progress: auto (a bar on a terminal, lines otherwise), bar, plain, none.",
33
+ rich_help_panel=DISPLAY,
34
+ ),
35
+ ]