exedev 0.2.0__tar.gz → 0.3.1__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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: exedev
3
- Version: 0.2.0
3
+ Version: 0.3.1
4
4
  Summary: Official Python SDK for the exe.dev HTTPS API
5
5
  Project-URL: Homepage, https://exe.dev
6
6
  Project-URL: Documentation, https://exe.dev/docs/https-api
@@ -40,7 +40,9 @@ with exe.new(image="ubuntu:24.04") as vm: # deleted at the end of the block
40
40
  `new()` returns once the VM runs commands, so the first `run()` needs no
41
41
  retry loop, and if it fails or is interrupted on the way, it deletes the VM
42
42
  rather than leak it. Create a token with `ssh exe.dev ssh-key generate-api-key`; its
43
- permissions decide which methods work.
43
+ permissions decide which methods work. For automation, prefer a key scoped to
44
+ a tag (`--tag=ci`): it manages only the VMs with that tag, and VMs it creates
45
+ get the tag.
44
46
 
45
47
  The same API is available for asyncio:
46
48
 
@@ -164,7 +166,9 @@ seconds (60, or 600 for setup), `VMReadyError` is raised.
164
166
 
165
167
  If waiting fails, or is interrupted by an exception, a `KeyboardInterrupt`,
166
168
  or cancellation, `new()` deletes the VM before raising. Pass
167
- `keep_on_failure=True` to keep it for debugging, as `err.vm`.
169
+ `keep_on_failure=True` to keep it for debugging, as `err.vm`. Interrupted
170
+ while the server is still creating the VM, `new()` (and `vm.copy()`) waits
171
+ for it, deletes it, and then raises; a second interrupt gives up on it.
168
172
 
169
173
  A VM from `new()` or `vm.copy()` is a context manager that deletes it at the
170
174
  end of the block (`async with exe.new() as vm:` in async code). Otherwise,
@@ -178,9 +182,9 @@ for vm in exe.vms(): # or exe.vms("web-*")
178
182
 
179
183
  vm = exe.vm("build") # NotFoundError if there is none
180
184
 
181
- copy = vm.copy("build-2", cpu=8) # a new VM with a copy of the disk (syncs it first)
185
+ copy = vm.copy("build-2", cpu=8) # a new VM with a copy of the disk
182
186
  vm.restart() # waits for SSH again, like new()
183
- vm.pause(); vm.resume()
187
+ vm.pause(); vm.resume() # a paused VM can be copied too
184
188
  vm.rename("builder") # vm.name, ssh_dest, and https_url follow
185
189
  vm.tag("ci", "linux"); vm.untag("linux")
186
190
  vm.set_comment("nightly builds")
@@ -196,6 +200,11 @@ A VM's attributes (`status`, `ssh_dest`, `https_url`, `tags`, `comment`,
196
200
  `region`, `created_at`) are a snapshot: the SDK's own operations keep them
197
201
  current, and `refresh()` fetches the rest.
198
202
 
203
+ `copy()`, `pause()`, and `restart()` (and `resize(restart=True)`) first flush
204
+ the VM's recent writes to its disk, so that copies and the restarted VM have
205
+ them. Pass `flush=False` to skip that. It is best effort: it needs a token that
206
+ may run `ssh`.
207
+
199
208
  `vm.delete()` raises `NotFoundError` for a VM that is gone, while
200
209
  `exe.delete()` reports each VM's fate in its result, since some may be
201
210
  deleted and others not.
@@ -220,7 +229,7 @@ arguments (`--copy-tags=false` is `copy_tags=False`).
220
229
  ```python
221
230
  exe.whoami()
222
231
  exe.ssh_key.list()
223
- exe.ssh_key.generate_api_key(label="ci", vm="build", exp="30d")
232
+ exe.ssh_key.generate_api_key(label="ci", tag="ci", exp="30d")["token"]
224
233
  exe.integrations.add("http-proxy", name="api", target="https://api.example.com", headers=["X-Key:secret"])
225
234
  exe.integrations.attach("api", "tag:ci")
226
235
  exe.team() # a group that is also a command is callable
@@ -23,7 +23,9 @@ with exe.new(image="ubuntu:24.04") as vm: # deleted at the end of the block
23
23
  `new()` returns once the VM runs commands, so the first `run()` needs no
24
24
  retry loop, and if it fails or is interrupted on the way, it deletes the VM
25
25
  rather than leak it. Create a token with `ssh exe.dev ssh-key generate-api-key`; its
26
- permissions decide which methods work.
26
+ permissions decide which methods work. For automation, prefer a key scoped to
27
+ a tag (`--tag=ci`): it manages only the VMs with that tag, and VMs it creates
28
+ get the tag.
27
29
 
28
30
  The same API is available for asyncio:
29
31
 
@@ -147,7 +149,9 @@ seconds (60, or 600 for setup), `VMReadyError` is raised.
147
149
 
148
150
  If waiting fails, or is interrupted by an exception, a `KeyboardInterrupt`,
149
151
  or cancellation, `new()` deletes the VM before raising. Pass
150
- `keep_on_failure=True` to keep it for debugging, as `err.vm`.
152
+ `keep_on_failure=True` to keep it for debugging, as `err.vm`. Interrupted
153
+ while the server is still creating the VM, `new()` (and `vm.copy()`) waits
154
+ for it, deletes it, and then raises; a second interrupt gives up on it.
151
155
 
152
156
  A VM from `new()` or `vm.copy()` is a context manager that deletes it at the
153
157
  end of the block (`async with exe.new() as vm:` in async code). Otherwise,
@@ -161,9 +165,9 @@ for vm in exe.vms(): # or exe.vms("web-*")
161
165
 
162
166
  vm = exe.vm("build") # NotFoundError if there is none
163
167
 
164
- copy = vm.copy("build-2", cpu=8) # a new VM with a copy of the disk (syncs it first)
168
+ copy = vm.copy("build-2", cpu=8) # a new VM with a copy of the disk
165
169
  vm.restart() # waits for SSH again, like new()
166
- vm.pause(); vm.resume()
170
+ vm.pause(); vm.resume() # a paused VM can be copied too
167
171
  vm.rename("builder") # vm.name, ssh_dest, and https_url follow
168
172
  vm.tag("ci", "linux"); vm.untag("linux")
169
173
  vm.set_comment("nightly builds")
@@ -179,6 +183,11 @@ A VM's attributes (`status`, `ssh_dest`, `https_url`, `tags`, `comment`,
179
183
  `region`, `created_at`) are a snapshot: the SDK's own operations keep them
180
184
  current, and `refresh()` fetches the rest.
181
185
 
186
+ `copy()`, `pause()`, and `restart()` (and `resize(restart=True)`) first flush
187
+ the VM's recent writes to its disk, so that copies and the restarted VM have
188
+ them. Pass `flush=False` to skip that. It is best effort: it needs a token that
189
+ may run `ssh`.
190
+
182
191
  `vm.delete()` raises `NotFoundError` for a VM that is gone, while
183
192
  `exe.delete()` reports each VM's fate in its result, since some may be
184
193
  deleted and others not.
@@ -203,7 +212,7 @@ arguments (`--copy-tags=false` is `copy_tags=False`).
203
212
  ```python
204
213
  exe.whoami()
205
214
  exe.ssh_key.list()
206
- exe.ssh_key.generate_api_key(label="ci", vm="build", exp="30d")
215
+ exe.ssh_key.generate_api_key(label="ci", tag="ci", exp="30d")["token"]
207
216
  exe.integrations.add("http-proxy", name="api", target="https://api.example.com", headers=["X-Key:secret"])
208
217
  exe.integrations.attach("api", "tag:ci")
209
218
  exe.team() # a group that is also a command is callable
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "exedev"
3
- version = "0.2.0"
3
+ version = "0.3.1"
4
4
  description = "Official Python SDK for the exe.dev HTTPS API"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -11,6 +11,8 @@
11
11
  AsyncClient is the same API for asyncio.
12
12
  """
13
13
 
14
+ from importlib.metadata import PackageNotFoundError, version
15
+
14
16
  from ._async import AsyncClient, AsyncProcess, AsyncVM
15
17
  from ._errors import (
16
18
  APIError,
@@ -33,6 +35,12 @@ from ._errors import (
33
35
  from ._sync import VM, Client, Process
34
36
  from ._wire import CommandResult, Logs
35
37
 
38
+ try:
39
+ __version__ = version("exedev")
40
+ except PackageNotFoundError: # Not installed, as in a source checkout.
41
+ __version__ = "0+unknown"
42
+ del PackageNotFoundError, version
43
+
36
44
  __all__ = [
37
45
  "APIError",
38
46
  "AsyncClient",
@@ -48,6 +48,7 @@ from ._errors import (
48
48
  from ._wire import (
49
49
  DEFAULT_BASE_URL,
50
50
  DOWNLOAD_SCRIPT,
51
+ FLUSH_SCRIPT,
51
52
  HEADERS,
52
53
  IS_DIRECTORY,
53
54
  KILL_SCRIPT,
@@ -146,6 +147,23 @@ class _AsyncTransport:
146
147
  await asyncio.sleep(retry_delay(response, attempt))
147
148
  attempt += 1
148
149
 
150
+ async def create(self, path: Literal["new", "cp"], args: Sequence[Arg], flags: Sequence[Flag]) -> VMInfo:
151
+ """Run new or cp: the VM it created. Interrupted (by cancellation, or
152
+ KeyboardInterrupt) before the response, it waits for the response
153
+ anyway, deletes the VM, and re-raises: no one else would know of it.
154
+ Interrupted again, it gives up."""
155
+ request = asyncio.ensure_future(self.call(path, args, flags, json=True))
156
+ try:
157
+ result = await asyncio.shield(request)
158
+ except Exception:
159
+ raise
160
+ except BaseException:
161
+ with contextlib.suppress(Exception):
162
+ info = vm_info(await request, path)
163
+ await self.documents("rm", [info.name])
164
+ raise
165
+ return vm_info(result, path)
166
+
149
167
  async def documents(
150
168
  self, path: str, args: Sequence[Arg] = (), flags: Sequence[Flag] = ()
151
169
  ) -> tuple[int, str, list[Any] | None]:
@@ -303,7 +321,7 @@ class AsyncVM:
303
321
 
304
322
  @property
305
323
  def created_at(self) -> datetime | None:
306
- """When the VM was created; None until listed (see refresh())."""
324
+ """When the VM was created; None if the server did not say (see refresh())."""
307
325
  return self._info.created_at
308
326
 
309
327
  @property
@@ -678,7 +696,7 @@ class AsyncVM:
678
696
  async def _flush(self) -> None:
679
697
  """Flush the VM's recent writes to its disk, if it is running. Best effort."""
680
698
  with contextlib.suppress(ExeError):
681
- await self._t.ssh(self.name, "sync", capture=False, timeout=60)
699
+ await self._t.ssh(self.name, sh(FLUSH_SCRIPT), capture=False, timeout=60)
682
700
 
683
701
  async def delete(self) -> None:
684
702
  """Delete the VM. A VM that does not exist raises NotFoundError.
@@ -692,7 +710,13 @@ class AsyncVM:
692
710
  if summary["failed"] or len(summary["deleted"]) != 1:
693
711
  raise api_error("rm", 404 if summary.get("not_found") else 422, body)
694
712
 
695
- async def restart(self, *, wait_until: WaitUntil = "ssh", timeout: float | None = None) -> t.RestartResponse:
713
+ async def restart(
714
+ self,
715
+ *,
716
+ flush: bool = True,
717
+ wait_until: WaitUntil = "ssh",
718
+ timeout: float | None = None,
719
+ ) -> t.RestartResponse:
696
720
  """Restart a VM.
697
721
 
698
722
  CLI: ``restart <vmname>``
@@ -700,6 +724,9 @@ class AsyncVM:
700
724
  Tag-scoped API keys may run this command.
701
725
 
702
726
  Args:
727
+ flush: first flush the VM's recent writes to its disk (best effort: it needs
728
+ ssh permission, and a running VM), so that it still has them after the
729
+ restart.
703
730
  wait_until: "ssh" (the default) returns once the VM runs commands; "setup"
704
731
  also waits for its setup script to finish, and succeed; "created"
705
732
  returns at once. Waiting needs ssh permission, and raises VMReadyError
@@ -707,17 +734,26 @@ class AsyncVM:
707
734
  timeout: seconds to wait for readiness; by default 60, or 600 for "setup".
708
735
  """
709
736
  check_ready(wait_until, timeout)
737
+ if flush:
738
+ await self._flush()
710
739
  result: t.RestartResponse = await self._t.call("restart", [self.name], json=True)
711
740
  await self._ready(wait_until, timeout)
712
741
  return result
713
742
 
714
- async def pause(self) -> t.PauseResponse:
743
+ async def pause(self, *, flush: bool = True) -> t.PauseResponse:
715
744
  """Pause a VM (snapshot RAM to disk, free its CPU and memory).
716
745
 
717
746
  CLI: ``pause <vmname>``
718
747
 
719
748
  Tag-scoped API keys may run this command.
749
+
750
+ Args:
751
+ flush: first flush the VM's recent writes to its disk (best effort: it needs
752
+ ssh permission, and a running VM), so that copies of the paused VM have
753
+ them.
720
754
  """
755
+ if flush:
756
+ await self._flush()
721
757
  result: t.PauseResponse = await self._t.call("pause", [self.name], json=True)
722
758
  self._absorb(result)
723
759
  return result
@@ -790,6 +826,7 @@ class AsyncVM:
790
826
  copy_tags: bool = True,
791
827
  cpu: int | None = None,
792
828
  disk: int | str | None = None,
829
+ egress: str | None = None,
793
830
  memory: int | str | None = None,
794
831
  pool: str | None = None,
795
832
  standalone: bool = False,
@@ -808,12 +845,13 @@ class AsyncVM:
808
845
  copy_tags: copy tags from source VM (use ``copy_tags=False`` to disable)
809
846
  cpu: number of CPUs
810
847
  disk: disk size (e.g., 20, 20GB, 50G)
848
+ egress: egress policy: integrations or all (default source policy)
811
849
  memory: memory allocation (e.g., 4, 4GB, 8G)
812
850
  pool: create the copy in one of your team's pools (see ``exe.pool.list()``)
813
851
  standalone: create the copy as a standalone VM with its own reserved
814
852
  capacity (requires a plan with standalone VMs and team approval)
815
- flush: first flush the VM's recent writes to its disk, so that the copy has
816
- them. Best effort: it needs ssh permission, and a running VM.
853
+ flush: first flush the VM's recent writes to its disk (best effort: it needs
854
+ ssh permission, and a running VM), so that the copy has them.
817
855
  wait_until: "ssh" (the default) returns once the VM runs commands; "setup"
818
856
  also waits for its setup script to finish, and succeed; "created"
819
857
  returns at once. Waiting needs ssh permission, and raises VMReadyError
@@ -826,20 +864,20 @@ class AsyncVM:
826
864
  check_ready(wait_until, timeout)
827
865
  if flush:
828
866
  await self._flush()
829
- result = await self._t.call(
867
+ result = await self._t.create(
830
868
  "cp",
831
869
  [self.name, name],
832
870
  [
833
871
  ("copy-tags", "bool", None if copy_tags else False),
834
872
  ("cpu", "number", cpu),
835
873
  ("disk", "string", disk),
874
+ ("egress", "string", egress),
836
875
  ("memory", "string", memory),
837
876
  ("pool", "string", pool),
838
877
  ("standalone", "bool", standalone or None),
839
878
  ],
840
- json=True,
841
879
  )
842
- vm = AsyncVM(self._t, vm_info(result, "cp"), owned=True)
880
+ vm = AsyncVM(self._t, result, owned=True)
843
881
  return await vm._created(wait_until, timeout, keep_on_failure)
844
882
 
845
883
  async def resize(
@@ -940,7 +978,8 @@ class AsyncProcess:
940
978
 
941
979
  @property
942
980
  def pid(self) -> int:
943
- """Its process ID on the VM, which is also its process group's."""
981
+ """Its process ID on the VM, which is also its process group's; 0 if
982
+ that is unknown, as it can be for a lost process."""
944
983
  return self._state.pid
945
984
 
946
985
  @property
@@ -1131,6 +1170,7 @@ class AsyncClient:
1131
1170
  comment: str | None = None,
1132
1171
  cpu: int | None = None,
1133
1172
  disk: int | str | None = None,
1173
+ egress: str | None = None,
1134
1174
  env: Mapping[str, str] | None = None,
1135
1175
  image: str | None = None,
1136
1176
  integrations: Sequence[str] | None = None,
@@ -1156,6 +1196,7 @@ class AsyncClient:
1156
1196
  comment: short note about the VM (max 200 bytes)
1157
1197
  cpu: number of CPUs (default 2; run 'billing plan' for plan limits)
1158
1198
  disk: disk size (e.g., 20, 20GB, 50G)
1199
+ egress: egress policy: integrations or all (default all)
1159
1200
  env: environment variable in KEY=VALUE format (can be specified multiple
1160
1201
  times)
1161
1202
  image: container image (server default: exeuntu)
@@ -1185,13 +1226,14 @@ class AsyncClient:
1185
1226
  is interrupted.
1186
1227
  """
1187
1228
  check_ready(wait_until, timeout)
1188
- result = await self._t.call(
1229
+ result = await self._t.create(
1189
1230
  "new",
1190
1231
  [],
1191
1232
  [
1192
1233
  ("comment", "string", comment),
1193
1234
  ("cpu", "number", cpu),
1194
1235
  ("disk", "string", disk),
1236
+ ("egress", "string", egress),
1195
1237
  ("env", "repeated", env_flags(env)),
1196
1238
  ("image", "string", image),
1197
1239
  ("integration", "repeated", integrations),
@@ -1206,11 +1248,19 @@ class AsyncClient:
1206
1248
  ("tag", "repeated", tags),
1207
1249
  ("no-email", "bool", None if email else True),
1208
1250
  ],
1209
- json=True,
1210
1251
  )
1211
- vm = AsyncVM(self._t, vm_info(result, "new"), owned=True)
1252
+ vm = AsyncVM(self._t, result, owned=True)
1212
1253
  return await vm._created(wait_until, timeout, keep_on_failure)
1213
1254
 
1255
+ async def egress(self, vmname: str, value: Literal["integrations", "all"] | None = None) -> Any:
1256
+ """Show or set a VM's egress policy.
1257
+
1258
+ CLI: ``egress <vmname> [integrations|all]``
1259
+
1260
+ Tag-scoped API keys may run this command.
1261
+ """
1262
+ return await self._t.call("egress", [vmname, value])
1263
+
1214
1264
  async def whoami(self) -> t.WhoamiResponse:
1215
1265
  """Show user information (email, keys, etc).
1216
1266
 
@@ -1271,17 +1321,35 @@ class _AsyncSshKey:
1271
1321
  """
1272
1322
  return await self._t.call("ssh-key list", [])
1273
1323
 
1274
- async def add(self, public_key: str, *, tag: str | None = None) -> Any:
1324
+ async def add(
1325
+ self,
1326
+ public_key: str,
1327
+ *,
1328
+ ssh_user: str | None = None,
1329
+ tag: str | None = None,
1330
+ vm: str | None = None,
1331
+ ) -> Any:
1275
1332
  """Add a new SSH key to your account.
1276
1333
 
1277
- CLI: ``ssh-key add [--tag=TAG] <public-key>``
1334
+ CLI: ``ssh-key add [--tag=TAG | --vm=VM [--ssh-user=USER]] <public-key>``
1278
1335
 
1279
1336
  Tag-scoped API keys may run this command.
1280
1337
 
1281
1338
  Args:
1339
+ ssh_user: with ``vm``, the Unix user to log in to the VM as (default: the
1340
+ VM's default user)
1282
1341
  tag: scope key to VMs with this tag
1342
+ vm: scope key to a VM
1283
1343
  """
1284
- return await self._t.call("ssh-key add", [public_key], [("tag", "string", tag)])
1344
+ return await self._t.call(
1345
+ "ssh-key add",
1346
+ [public_key],
1347
+ [
1348
+ ("ssh-user", "string", ssh_user),
1349
+ ("tag", "string", tag),
1350
+ ("vm", "string", vm),
1351
+ ],
1352
+ )
1285
1353
 
1286
1354
  async def remove(self, key: str) -> Any:
1287
1355
  """Remove an SSH key from your account.
@@ -1307,11 +1375,12 @@ class _AsyncSshKey:
1307
1375
  cmds: str | None = None,
1308
1376
  exp: str | None = None,
1309
1377
  label: str | None = None,
1378
+ tag: str | None = None,
1310
1379
  vm: str | None = None,
1311
1380
  ) -> Any:
1312
1381
  """Generate an API key for the exe.dev HTTPS API or for a specific VM.
1313
1382
 
1314
- CLI: ``ssh-key generate-api-key [--label=NAME] [--vm=VMNAME] [--cmds=CMD1,CMD2] [--exp=30d]``
1383
+ CLI: ``ssh-key generate-api-key [--label=NAME] [--vm=VMNAME | --tag=TAG] [--cmds=CMD1,CMD2] [--exp=30d]``
1315
1384
 
1316
1385
  Tag-scoped API keys may run this command.
1317
1386
 
@@ -1319,6 +1388,7 @@ class _AsyncSshKey:
1319
1388
  cmds: comma-separated list of allowed commands (empty = defaults)
1320
1389
  exp: expiry duration (e.g. 30d, 1y) or 'never'
1321
1390
  label: label for this token's SSH key
1391
+ tag: scope key to VMs with this tag
1322
1392
  vm: scope key to a VM (authenticates to its HTTPS endpoints instead of
1323
1393
  exe.dev commands)
1324
1394
  """
@@ -1329,6 +1399,7 @@ class _AsyncSshKey:
1329
1399
  ("cmds", "string", cmds),
1330
1400
  ("exp", "string", exp),
1331
1401
  ("label", "string", label),
1402
+ ("tag", "string", tag),
1332
1403
  ("vm", "string", vm),
1333
1404
  ],
1334
1405
  )
@@ -1341,17 +1412,25 @@ class _AsyncIntegrations:
1341
1412
  self._t = t
1342
1413
  self.setup = _AsyncIntegrationsSetup(self._t)
1343
1414
 
1344
- async def list(self, *, usage: bool = False) -> Any:
1415
+ async def list(self, *, available: bool = False, usage: bool = False) -> Any:
1345
1416
  """List your integrations.
1346
1417
 
1347
- CLI: ``integrations list [--json [--usage]]``
1418
+ CLI: ``integrations list [--json [--usage]] | integrations list --available [--json]``
1348
1419
 
1349
1420
  Tag-scoped API keys may run this command.
1350
1421
 
1351
1422
  Args:
1423
+ available: list available integrations
1352
1424
  usage: include per-VM usage (lastUsedAt, usedByVMs); JSON only
1353
1425
  """
1354
- return await self._t.call("integrations list", [], [("usage", "bool", usage or None)])
1426
+ return await self._t.call(
1427
+ "integrations list",
1428
+ [],
1429
+ [
1430
+ ("available", "bool", available or None),
1431
+ ("usage", "bool", usage or None),
1432
+ ],
1433
+ )
1355
1434
 
1356
1435
  async def add(
1357
1436
  self,