pixec-burrow 0.1.0.dev202611130309__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 (43) hide show
  1. pixec_burrow-0.1.0.dev202611130309/.gitignore +4 -0
  2. pixec_burrow-0.1.0.dev202611130309/LICENSE +21 -0
  3. pixec_burrow-0.1.0.dev202611130309/PKG-INFO +66 -0
  4. pixec_burrow-0.1.0.dev202611130309/README.md +42 -0
  5. pixec_burrow-0.1.0.dev202611130309/pyproject.toml +44 -0
  6. pixec_burrow-0.1.0.dev202611130309/src/burrow/__init__.py +124 -0
  7. pixec_burrow-0.1.0.dev202611130309/src/burrow/_fileio.py +273 -0
  8. pixec_burrow-0.1.0.dev202611130309/src/burrow/_os.py +478 -0
  9. pixec_burrow-0.1.0.dev202611130309/src/burrow/_pathlib.py +158 -0
  10. pixec_burrow-0.1.0.dev202611130309/src/burrow/_pb/__init__.py +1 -0
  11. pixec_burrow-0.1.0.dev202611130309/src/burrow/_pb/api_pb2.py +361 -0
  12. pixec_burrow-0.1.0.dev202611130309/src/burrow/_pb/api_pb2_grpc.py +3313 -0
  13. pixec_burrow-0.1.0.dev202611130309/src/burrow/_pb/common_pb2.py +178 -0
  14. pixec_burrow-0.1.0.dev202611130309/src/burrow/_pb/common_pb2_grpc.py +24 -0
  15. pixec_burrow-0.1.0.dev202611130309/src/burrow/_policy.py +563 -0
  16. pixec_burrow-0.1.0.dev202611130309/src/burrow/_shutil.py +280 -0
  17. pixec_burrow-0.1.0.dev202611130309/src/burrow/_subprocess.py +627 -0
  18. pixec_burrow-0.1.0.dev202611130309/src/burrow/_transport.py +308 -0
  19. pixec_burrow-0.1.0.dev202611130309/src/burrow/_wire.py +67 -0
  20. pixec_burrow-0.1.0.dev202611130309/src/burrow/client.py +636 -0
  21. pixec_burrow-0.1.0.dev202611130309/src/burrow/errors.py +64 -0
  22. pixec_burrow-0.1.0.dev202611130309/src/burrow/ip.py +137 -0
  23. pixec_burrow-0.1.0.dev202611130309/src/burrow/proto/api.proto +1475 -0
  24. pixec_burrow-0.1.0.dev202611130309/src/burrow/proto/common.proto +1018 -0
  25. pixec_burrow-0.1.0.dev202611130309/src/burrow/py.typed +0 -0
  26. pixec_burrow-0.1.0.dev202611130309/src/burrow/sandbox.py +1321 -0
  27. pixec_burrow-0.1.0.dev202611130309/src/burrow/snapshot.py +118 -0
  28. pixec_burrow-0.1.0.dev202611130309/src/burrow/template.py +327 -0
  29. pixec_burrow-0.1.0.dev202611130309/src/burrow/terminal.py +174 -0
  30. pixec_burrow-0.1.0.dev202611130309/src/burrow/types.py +668 -0
  31. pixec_burrow-0.1.0.dev202611130309/src/burrow/volume.py +130 -0
  32. pixec_burrow-0.1.0.dev202611130309/tests/conftest.py +343 -0
  33. pixec_burrow-0.1.0.dev202611130309/tests/test_events.py +167 -0
  34. pixec_burrow-0.1.0.dev202611130309/tests/test_files.py +449 -0
  35. pixec_burrow-0.1.0.dev202611130309/tests/test_ip.py +108 -0
  36. pixec_burrow-0.1.0.dev202611130309/tests/test_kernel.py +80 -0
  37. pixec_burrow-0.1.0.dev202611130309/tests/test_limits.py +99 -0
  38. pixec_burrow-0.1.0.dev202611130309/tests/test_nodes.py +67 -0
  39. pixec_burrow-0.1.0.dev202611130309/tests/test_policy.py +300 -0
  40. pixec_burrow-0.1.0.dev202611130309/tests/test_resources.py +203 -0
  41. pixec_burrow-0.1.0.dev202611130309/tests/test_static.py +64 -0
  42. pixec_burrow-0.1.0.dev202611130309/tests/test_subprocess.py +203 -0
  43. pixec_burrow-0.1.0.dev202611130309/tests/test_transport.py +60 -0
@@ -0,0 +1,4 @@
1
+ __pycache__/
2
+ .pytest_cache/
3
+ dist/
4
+ *.egg-info/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Pixec Technologies
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,66 @@
1
+ Metadata-Version: 2.4
2
+ Name: pixec-burrow
3
+ Version: 0.1.0.dev202611130309
4
+ Summary: Python client for Burrow, self-hosted microVM sandboxes for running untrusted code
5
+ Project-URL: Homepage, https://burrow.pixec.net
6
+ Project-URL: Documentation, https://burrow.pixec.net/sdk/python/overview
7
+ Author-email: Pixec Technologies <oss+burrow@pixec.net>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: agents,cloud-hypervisor,firecracker,microvm,sandbox
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Topic :: Software Development :: Libraries
16
+ Classifier: Typing :: Typed
17
+ Requires-Python: >=3.9
18
+ Requires-Dist: grpcio>=1.80
19
+ Requires-Dist: protobuf>=6.31
20
+ Provides-Extra: dev
21
+ Requires-Dist: grpcio-tools==1.80.0; extra == 'dev'
22
+ Requires-Dist: pytest>=7; extra == 'dev'
23
+ Description-Content-Type: text/markdown
24
+
25
+ # pixec-burrow
26
+
27
+ Development build of commit 869d05b.
28
+
29
+ The Python SDK for [Burrow](https://burrow.pixec.net): microVM sandboxes for untrusted code, run on your own hardware.
30
+
31
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
32
+ [![PyPI](https://img.shields.io/pypi/v/pixec-burrow?label=pypi)](https://pypi.org/project/pixec-burrow/)
33
+
34
+ ## Install
35
+
36
+ ```sh
37
+ pip install pixec-burrow
38
+ ```
39
+
40
+ Python 3.9 or newer.
41
+
42
+ ```python
43
+ from burrow import Sandbox
44
+
45
+ with Sandbox.create(template="python").deleting() as sandbox:
46
+ result = sandbox.subprocess.run(["echo", "hello"], capture_output=True, text=True)
47
+ print(result.stdout) # "hello\n"
48
+ ```
49
+
50
+ ## Sponsors
51
+
52
+ Thanks to the following sponsors for helping fund Burrow's development.
53
+ To become a sponsor, write to `oss+burrow[at]pixec.net`.
54
+
55
+ | Company | About |
56
+ | --- | --- |
57
+ | [BoxCompute](https://boxcompute.ai) | BoxCompute provides cloud computers for AI agents. Each agent gets its own Linux virtual machine that keeps running after you close the browser; connect tools such as Claude Code, Codex or Cursor, or describe a task to BoxCompute's built-in agent, which sets up the software, runs your app, and gives you a live preview link. |
58
+ | [berrybyte](https://berrybyte.net) | berrybyte hosts game servers for players and their friends. It runs more than twenty games, including Minecraft, Hytale, Rust, Palworld and Valheim, with one-click modpack installs, a browser dashboard, automatic off-site backups and DDoS protection, in US East, US West and EU Central. It also offers dedicated servers. |
59
+
60
+ ## Documentation
61
+
62
+ The documentation is available at [burrow.pixec.net](https://burrow.pixec.net/sdk/python/overview).
63
+
64
+ ## License
65
+
66
+ The Python SDK is licensed under the MIT License, in [LICENSE](LICENSE). Burrow itself is licensed under the GNU Affero General Public License, version 3.
@@ -0,0 +1,42 @@
1
+ # pixec-burrow
2
+
3
+ Development build of commit 869d05b.
4
+
5
+ The Python SDK for [Burrow](https://burrow.pixec.net): microVM sandboxes for untrusted code, run on your own hardware.
6
+
7
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
8
+ [![PyPI](https://img.shields.io/pypi/v/pixec-burrow?label=pypi)](https://pypi.org/project/pixec-burrow/)
9
+
10
+ ## Install
11
+
12
+ ```sh
13
+ pip install pixec-burrow
14
+ ```
15
+
16
+ Python 3.9 or newer.
17
+
18
+ ```python
19
+ from burrow import Sandbox
20
+
21
+ with Sandbox.create(template="python").deleting() as sandbox:
22
+ result = sandbox.subprocess.run(["echo", "hello"], capture_output=True, text=True)
23
+ print(result.stdout) # "hello\n"
24
+ ```
25
+
26
+ ## Sponsors
27
+
28
+ Thanks to the following sponsors for helping fund Burrow's development.
29
+ To become a sponsor, write to `oss+burrow[at]pixec.net`.
30
+
31
+ | Company | About |
32
+ | --- | --- |
33
+ | [BoxCompute](https://boxcompute.ai) | BoxCompute provides cloud computers for AI agents. Each agent gets its own Linux virtual machine that keeps running after you close the browser; connect tools such as Claude Code, Codex or Cursor, or describe a task to BoxCompute's built-in agent, which sets up the software, runs your app, and gives you a live preview link. |
34
+ | [berrybyte](https://berrybyte.net) | berrybyte hosts game servers for players and their friends. It runs more than twenty games, including Minecraft, Hytale, Rust, Palworld and Valheim, with one-click modpack installs, a browser dashboard, automatic off-site backups and DDoS protection, in US East, US West and EU Central. It also offers dedicated servers. |
35
+
36
+ ## Documentation
37
+
38
+ The documentation is available at [burrow.pixec.net](https://burrow.pixec.net/sdk/python/overview).
39
+
40
+ ## License
41
+
42
+ The Python SDK is licensed under the MIT License, in [LICENSE](LICENSE). Burrow itself is licensed under the GNU Affero General Public License, version 3.
@@ -0,0 +1,44 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.27"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "pixec-burrow"
7
+ version = "0.1.0.dev202611130309"
8
+ description = "Python client for Burrow, self-hosted microVM sandboxes for running untrusted code"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ requires-python = ">=3.9"
13
+ authors = [{ name = "Pixec Technologies", email = "oss+burrow@pixec.net" }]
14
+ keywords = ["sandbox", "microvm", "firecracker", "cloud-hypervisor", "agents"]
15
+ classifiers = [
16
+ "Development Status :: 4 - Beta",
17
+ "Intended Audience :: Developers",
18
+ "Operating System :: OS Independent",
19
+ "Programming Language :: Python :: 3",
20
+ "Topic :: Software Development :: Libraries",
21
+ "Typing :: Typed",
22
+ ]
23
+ # Floors match what the committed `_pb` modules were generated against:
24
+ # api_pb2_grpc.py refuses grpcio older than 1.80, and api_pb2.py validates
25
+ # the protobuf runtime at 6.31.1. Older wheels fail at import, not at use.
26
+ dependencies = ["grpcio>=1.80", "protobuf>=6.31"]
27
+
28
+ [project.optional-dependencies]
29
+ # Pinned to the release that produced the committed `_pb`, so a regenerate
30
+ # does not silently move the runtime floors above.
31
+ dev = ["grpcio-tools==1.80.0", "pytest>=7"]
32
+
33
+ [project.urls]
34
+ Homepage = "https://burrow.pixec.net"
35
+ Documentation = "https://burrow.pixec.net/sdk/python/overview"
36
+
37
+ [tool.hatch.build.targets.sdist]
38
+ include = ["src", "tests", "README.md", "LICENSE"]
39
+
40
+ [tool.hatch.build.targets.wheel]
41
+ packages = ["src/burrow"]
42
+
43
+ [tool.pytest.ini_options]
44
+ testpaths = ["tests"]
@@ -0,0 +1,124 @@
1
+ """Python SDK for burrow: Firecracker microVM sandboxes for untrusted code."""
2
+
3
+ from subprocess import CompletedProcess
4
+
5
+ from ._fileio import FileIO
6
+ from ._os import DirEntry
7
+ from ._pathlib import SandboxPath
8
+ from ._subprocess import Popen
9
+ from .client import Burrow
10
+ from .errors import BurrowError
11
+ from .ip import Ips
12
+ from .sandbox import Sandbox, Watcher
13
+ from .snapshot import Snapshot
14
+ from .template import BuildLogEvent, Template, TemplateBuilder, default_build_logger
15
+ from .terminal import Terminal
16
+ from .types import (
17
+ AuditEvent,
18
+ BuiltTemplate,
19
+ CommandInfo,
20
+ DeletedGroup,
21
+ DeletedUser,
22
+ DiskCapacity,
23
+ DrainResult,
24
+ ExecPolicy,
25
+ FsPolicy,
26
+ GuestGroup,
27
+ GuestUser,
28
+ Health,
29
+ IngressRule,
30
+ IpPool,
31
+ KernelCapabilities,
32
+ KernelInfo,
33
+ LifecycleEvent,
34
+ LifetimePolicy,
35
+ LimitsOutcome,
36
+ NetworkMembership,
37
+ NetworkPolicy,
38
+ NodeInfo,
39
+ PortMapping,
40
+ PortRule,
41
+ PrunedCommands,
42
+ PublicIp,
43
+ RequestRule,
44
+ ResourceOutcome,
45
+ ResourcePolicy,
46
+ ResourcesUpdate,
47
+ SandboxInfo,
48
+ SandboxPolicy,
49
+ SecretInfo,
50
+ Session,
51
+ Share,
52
+ SnapshotPolicy,
53
+ TemplateInfo,
54
+ Usage,
55
+ UsageInterval,
56
+ UsageReport,
57
+ UsageSum,
58
+ VolumeMount,
59
+ WatchEvent,
60
+ )
61
+ from .volume import Volume
62
+
63
+ __all__ = [
64
+ "AuditEvent",
65
+ "BuildLogEvent",
66
+ "BuiltTemplate",
67
+ "Burrow",
68
+ "BurrowError",
69
+ "CommandInfo",
70
+ "CompletedProcess",
71
+ "DeletedGroup",
72
+ "DeletedUser",
73
+ "DirEntry",
74
+ "DiskCapacity",
75
+ "DrainResult",
76
+ "ExecPolicy",
77
+ "FileIO",
78
+ "FsPolicy",
79
+ "GuestGroup",
80
+ "GuestUser",
81
+ "Health",
82
+ "IngressRule",
83
+ "IpPool",
84
+ "KernelCapabilities",
85
+ "KernelInfo",
86
+ "Ips",
87
+ "LifecycleEvent",
88
+ "LifetimePolicy",
89
+ "LimitsOutcome",
90
+ "NetworkMembership",
91
+ "NetworkPolicy",
92
+ "NodeInfo",
93
+ "Popen",
94
+ "PortMapping",
95
+ "PortRule",
96
+ "PrunedCommands",
97
+ "PublicIp",
98
+ "RequestRule",
99
+ "ResourceOutcome",
100
+ "ResourcePolicy",
101
+ "ResourcesUpdate",
102
+ "Sandbox",
103
+ "SandboxInfo",
104
+ "SandboxPath",
105
+ "SandboxPolicy",
106
+ "SecretInfo",
107
+ "Session",
108
+ "Share",
109
+ "Snapshot",
110
+ "SnapshotPolicy",
111
+ "Template",
112
+ "TemplateBuilder",
113
+ "TemplateInfo",
114
+ "Terminal",
115
+ "Usage",
116
+ "UsageInterval",
117
+ "UsageReport",
118
+ "UsageSum",
119
+ "Volume",
120
+ "VolumeMount",
121
+ "WatchEvent",
122
+ "Watcher",
123
+ "default_build_logger",
124
+ ]
@@ -0,0 +1,273 @@
1
+ """`sandbox.open`: builtin `open()` over the `Fs` handle calls.
2
+
3
+ Built the way CPython builds `open()`: a raw file over the handle, wrapped in
4
+ the stdlib's own buffered and text layers. Readline, iteration, newline
5
+ translation, seeking a text file and the errors for a misused mode are then the
6
+ stdlib's code rather than a copy of it.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import errno
12
+ import io
13
+ import os
14
+ import warnings
15
+ from typing import TYPE_CHECKING, Any, Optional
16
+
17
+ from ._os import fspath, to_stat_result
18
+ from ._pb import api_pb2
19
+ from ._transport import MAX_FILE_CHUNK
20
+
21
+ if TYPE_CHECKING:
22
+ from .sandbox import Sandbox
23
+
24
+ # open(2) flags in their Linux values, which is what the guest is. This
25
+ # machine's `os.O_*` are not: O_CREAT is 0o1000 on macOS.
26
+ O_RDONLY = 0
27
+ O_WRONLY = 1
28
+ O_RDWR = 2
29
+ O_CREAT = 0o100
30
+ O_EXCL = 0o200
31
+ O_TRUNC = 0o1000
32
+ O_APPEND = 0o2000
33
+
34
+
35
+ # What `buffering=-1` gives a file. CPython takes the file's st_blksize, a few
36
+ # KiB; here every refill is a round trip to the guest, so fewer of them is
37
+ # worth more than the memory.
38
+ _BUFFER_SIZE = 1024 * 1024
39
+
40
+
41
+ class FileIO(io.RawIOBase):
42
+ """The raw file under what `sandbox.open` returns, as `io.FileIO` is under
43
+ what `open` does.
44
+
45
+ The position is kept here rather than in the guest: every read and write
46
+ names where it goes, since there is no seek call to move the guest's.
47
+ """
48
+
49
+ def __init__(
50
+ self,
51
+ sandbox: "Sandbox",
52
+ name: Any,
53
+ mode: str,
54
+ handle: int,
55
+ readable: bool,
56
+ writable: bool,
57
+ appending: bool,
58
+ ):
59
+ super().__init__()
60
+ self._sandbox = sandbox
61
+ self.name = name
62
+ self.mode = mode
63
+ self._handle = handle
64
+ self._readable = readable
65
+ self._writable = writable
66
+ self._appending = appending
67
+ # None once an append has moved it to wherever the end now is, which
68
+ # only the guest knows. Read back the next time it is needed.
69
+ self._pos: Optional[int] = None if appending else 0
70
+
71
+ def _check_closed(self) -> None:
72
+ if self.closed:
73
+ raise ValueError("I/O operation on closed file")
74
+
75
+ def readable(self) -> bool:
76
+ self._check_closed()
77
+ return self._readable
78
+
79
+ def writable(self) -> bool:
80
+ self._check_closed()
81
+ return self._writable
82
+
83
+ def seekable(self) -> bool:
84
+ self._check_closed()
85
+ return True
86
+
87
+ def fileno(self) -> int:
88
+ # No number would be honest: a handle is not a descriptor on this
89
+ # machine, and code that passed one to a local syscall (os.fstat to
90
+ # size a request body, say) would act on whatever file has that
91
+ # number here. BytesIO refuses the same way.
92
+ raise io.UnsupportedOperation("fileno: a sandbox file has no local descriptor")
93
+
94
+ def _fstat(self) -> os.stat_result:
95
+ res = self._sandbox._fs(fstat=api_pb2.FsHandle(handle=self._handle))
96
+ return to_stat_result(res.stat)
97
+
98
+ def _read(self, length: int) -> bytes:
99
+ self._check_closed()
100
+ if not self._readable:
101
+ raise io.UnsupportedOperation("File not open for reading")
102
+ res = self._sandbox._fs(
103
+ read=api_pb2.FsRead(handle=self._handle, position=self.tell(), length=length)
104
+ )
105
+ self._pos += len(res.data)
106
+ return res.data
107
+
108
+ def readinto(self, buffer: Any) -> int:
109
+ with memoryview(buffer) as view, view.cast("B") as target:
110
+ data = self._read(min(len(target), MAX_FILE_CHUNK))
111
+ target[: len(data)] = data
112
+ return len(data)
113
+
114
+ def readall(self) -> bytes:
115
+ parts = []
116
+ while True:
117
+ data = self._read(MAX_FILE_CHUNK)
118
+ if not data:
119
+ return b"".join(parts)
120
+ parts.append(data)
121
+
122
+ def write(self, b: Any) -> int:
123
+ self._check_closed()
124
+ if not self._writable:
125
+ raise io.UnsupportedOperation("File not open for writing")
126
+ with memoryview(b) as view, view.cast("B") as source:
127
+ data = source[:MAX_FILE_CHUNK].tobytes()
128
+ res = self._sandbox._fs(
129
+ write=api_pb2.FsWrite(
130
+ handle=self._handle,
131
+ # O_APPEND puts every write at the end whatever it names.
132
+ position=-1 if self._appending else self.tell(),
133
+ data=data,
134
+ )
135
+ )
136
+ if self._appending:
137
+ self._pos = None
138
+ else:
139
+ self._pos += res.written
140
+ return res.written
141
+
142
+ def seek(self, offset: int, whence: int = os.SEEK_SET) -> int:
143
+ self._check_closed()
144
+ if whence == os.SEEK_SET:
145
+ base = 0
146
+ elif whence == os.SEEK_CUR:
147
+ base = self.tell()
148
+ elif whence == os.SEEK_END:
149
+ base = self._fstat().st_size
150
+ else:
151
+ raise ValueError(f"invalid whence ({whence}, should be 0, 1 or 2)")
152
+ if base + offset < 0:
153
+ raise OSError(errno.EINVAL, os.strerror(errno.EINVAL))
154
+ self._pos = base + offset
155
+ return self._pos
156
+
157
+ def tell(self) -> int:
158
+ self._check_closed()
159
+ if self._pos is None:
160
+ self._pos = self._fstat().st_size
161
+ return self._pos
162
+
163
+ def truncate(self, size: Optional[int] = None) -> int:
164
+ self._check_closed()
165
+ if not self._writable:
166
+ raise io.UnsupportedOperation("File not open for writing")
167
+ if size is None:
168
+ size = self.tell()
169
+ self._sandbox._fs(ftruncate=api_pb2.FsFtruncate(handle=self._handle, length=size))
170
+ return size
171
+
172
+ def close(self) -> None:
173
+ if self.closed:
174
+ return
175
+ try:
176
+ self._sandbox._fs(close=api_pb2.FsHandle(handle=self._handle))
177
+ finally:
178
+ super().close()
179
+
180
+
181
+ def open_file(
182
+ sandbox: "Sandbox",
183
+ file: Any,
184
+ mode: str = "r",
185
+ buffering: int = -1,
186
+ encoding: Optional[str] = None,
187
+ errors: Optional[str] = None,
188
+ newline: Optional[str] = None,
189
+ ) -> Any:
190
+ """`open()`, for a file in the sandbox. The checks and their messages are
191
+ CPython's, in its order."""
192
+ if not isinstance(mode, str):
193
+ raise TypeError(f"open() argument 'mode' must be str, not {type(mode).__name__}")
194
+ path = fspath(file)
195
+ modes = set(mode)
196
+ if modes - set("axrwb+t") or len(mode) > len(modes):
197
+ raise ValueError(f"invalid mode: {mode!r}")
198
+ creating = "x" in modes
199
+ reading = "r" in modes
200
+ writing = "w" in modes
201
+ appending = "a" in modes
202
+ updating = "+" in modes
203
+ text = "t" in modes
204
+ binary = "b" in modes
205
+ if text and binary:
206
+ raise ValueError("can't have text and binary mode at once")
207
+ if creating + reading + writing + appending > 1:
208
+ raise ValueError("must have exactly one of create/read/write/append mode")
209
+ if not (creating or reading or writing or appending):
210
+ raise ValueError(
211
+ "Must have exactly one of create/read/write/append mode and at most one plus"
212
+ )
213
+ if binary and encoding is not None:
214
+ raise ValueError("binary mode doesn't take an encoding argument")
215
+ if binary and errors is not None:
216
+ raise ValueError("binary mode doesn't take an errors argument")
217
+ if binary and newline is not None:
218
+ raise ValueError("binary mode doesn't take a newline argument")
219
+ if binary and buffering == 1:
220
+ warnings.warn(
221
+ "line buffering (buffering=1) isn't supported in binary mode, "
222
+ "the default buffer size will be used",
223
+ RuntimeWarning,
224
+ 2,
225
+ )
226
+ # Refused before the file is opened, unlike CPython, which opens it first
227
+ # and so truncates a file it then refuses to write.
228
+ if buffering == 0 and not binary:
229
+ raise ValueError("can't have unbuffered text I/O")
230
+
231
+ if reading:
232
+ flags, raw_mode = O_RDONLY, "rb+" if updating else "rb"
233
+ elif writing:
234
+ flags, raw_mode = O_WRONLY | O_CREAT | O_TRUNC, "rb+" if updating else "wb"
235
+ elif creating:
236
+ flags, raw_mode = O_WRONLY | O_CREAT | O_EXCL, "xb+" if updating else "xb"
237
+ else:
238
+ flags, raw_mode = O_WRONLY | O_CREAT | O_APPEND, "ab+" if updating else "ab"
239
+ if updating:
240
+ flags = flags & ~O_WRONLY | O_RDWR
241
+
242
+ handle = sandbox._fs(open=api_pb2.FsOpen(path=path, flags=flags, mode=0o666)).handle
243
+ raw = FileIO(
244
+ sandbox,
245
+ os.fspath(file),
246
+ raw_mode,
247
+ handle,
248
+ readable=reading or updating,
249
+ writable=not reading or updating,
250
+ appending=appending,
251
+ )
252
+ try:
253
+ line_buffering = buffering == 1
254
+ if buffering == 1 or buffering < 0:
255
+ buffering = _BUFFER_SIZE
256
+ if buffering == 0:
257
+ return raw
258
+ if updating:
259
+ buffer: Any = io.BufferedRandom(raw, buffering)
260
+ elif reading:
261
+ buffer = io.BufferedReader(raw, buffering)
262
+ else:
263
+ buffer = io.BufferedWriter(raw, buffering)
264
+ if binary:
265
+ return buffer
266
+ # UTF-8 rather than this machine's locale encoding: the file is the
267
+ # guest's, and what this machine's locale says about it is nothing.
268
+ wrapper = io.TextIOWrapper(buffer, encoding or "utf-8", errors, newline, line_buffering)
269
+ wrapper.mode = mode
270
+ return wrapper
271
+ except BaseException:
272
+ raw.close()
273
+ raise