1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
//! `cli_main`: the command line, reached from `python/matra/cli.py`.
//!
//! A launcher only. It collects arguments, calls [`crate::cli::run`], and
//! hands the bytes back to Python's own streams, so one program answers
//! to the Rust binary and to the Python entry point alike.
use *;
/// Run the matra command line and return its exit code.
///
/// `argv` is the argument vector *without* the program name, which
/// `cli::run` supplies itself so `--help` reads the same from this
/// launcher and from the Rust binary.
///
/// The command renders into byte buffers, which are then written to
/// Python's own `sys.stdout` and `sys.stderr` and flushed. Handing
/// `cli::run` the real file descriptors would interleave badly with
/// anything Python has already buffered on the same stream; going
/// through `sys` keeps one writer per stream.
///
/// A failure writing those buffers out is swallowed rather than
/// raised. It is a broken pipe in practice (`matra ... | head`), and
/// the Rust launcher treats that as success too; there is nowhere
/// left to report it to in any case.
///
/// The arguments arrive as arbitrary Python objects and go through
/// `os.fsencode`, not through `String`. A `sys.argv` entry is not
/// guaranteed to be text: on unix a path is bytes, and Python decodes
/// an undecodable one with surrogate escapes rather than failing.
/// Extracting a `String` would reject exactly those arguments, so a
/// file the Rust binary opens without comment would be unreachable
/// through this launcher. `os.fsencode` reverses the escape and hands
/// back the original bytes, which become an `OsString` unchanged. A
/// conversion failure is raised rather than swallowed: an argument
/// that is not a string, bytes, or a path is a caller's error, and
/// silently dropping it would run a different command than the one
/// that was asked for.
// pyo3 macro requirement, same as _core below.
/// A [`std::io::Write`] that forwards each write straight to a `sys`
/// stream instead of accumulating it.
///
/// The GIL is held for the whole of `cli_main`, so calling back into
/// Python here is the same access the surrounding function already
/// has.
/// The bytes `os.fsencode` produced, as an `OsString`.
///
/// On unix an `OsString` is bytes and the filesystem is bytes, so
/// this is exact: the argument reaches `cli::run` as the same bytes
/// `std::env::args_os` would have delivered to the Rust binary.
/// Elsewhere there is no lossless byte route into an `OsString`, so
/// an argument that is not valid UTF-8 loses the offending bytes to
/// the replacement character rather than reaching the command line
/// intact. Naming the limit here is the honest version of it.
/// Say on `sys.stderr` that a model is about to download, in the two
/// lines the command line writes ([`crate::cli::notice_text`]).
///
/// A first `matra.Engine()` waits seconds on a 16 MB fetch, and the first
/// `Model2Vec.potion_base_8m()` on 30.9 MB; before this, both waits were
/// silent. Model libraries in Python announce a download on stderr the
/// same way, and a caller who wants quiet redirects the stream. A notice
/// that cannot be written is not worth failing the constructor over.
pub
/// Write one rendered buffer to the named `sys` stream and flush it.