testflows.machine 0.1.2__tar.gz → 0.1.3__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.

Potentially problematic release.


This version of testflows.machine might be problematic. Click here for more details.

Files changed (25) hide show
  1. {testflows_machine-0.1.2/testflows.machine.egg-info → testflows_machine-0.1.3}/PKG-INFO +1 -1
  2. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/__init__.py +3 -1
  3. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/_requires.py +11 -1
  4. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/_service.py +18 -2
  5. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/_version.py +1 -1
  6. testflows_machine-0.1.3/testflows/machine/v1/_warn.py +38 -0
  7. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/client.py +160 -7
  8. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/errors.py +4 -3
  9. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/sessions.py +128 -4
  10. {testflows_machine-0.1.2 → testflows_machine-0.1.3/testflows.machine.egg-info}/PKG-INFO +1 -1
  11. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows.machine.egg-info/SOURCES.txt +1 -0
  12. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/LICENSE +0 -0
  13. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/NOTICE +0 -0
  14. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/README.md +0 -0
  15. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/pyproject.toml +0 -0
  16. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/setup.cfg +0 -0
  17. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/_args.py +0 -0
  18. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/_when.py +0 -0
  19. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/disks.py +0 -0
  20. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/login.py +0 -0
  21. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/ping.py +0 -0
  22. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/results.py +0 -0
  23. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows/machine/v1/runs.py +0 -0
  24. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows.machine.egg-info/dependency_links.txt +0 -0
  25. {testflows_machine-0.1.2 → testflows_machine-0.1.3}/testflows.machine.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: testflows.machine
3
- Version: 0.1.2
3
+ Version: 0.1.3
4
4
  Summary: Python SDK for TestFlows™ Machine, the deterministic execution environment
5
5
  Author-email: "Katteli Inc." <info@testflows.com>
6
6
  License-Expression: Apache-2.0
@@ -153,7 +153,7 @@ from .runs import (
153
153
  Task,
154
154
  Vtime,
155
155
  )
156
- from .sessions import Session, Sessions
156
+ from .sessions import Session, SessionClosing, SessionMovedBack, Sessions
157
157
 
158
158
  __all__ = [
159
159
  "AlreadyExists",
@@ -255,6 +255,8 @@ __all__ = [
255
255
  "Runs",
256
256
  "ServiceUnavailable",
257
257
  "Session",
258
+ "SessionClosing",
259
+ "SessionMovedBack",
258
260
  "Sessions",
259
261
  "State",
260
262
  "Storage",
@@ -32,6 +32,9 @@ import testflows.machine
32
32
 
33
33
  #: The core interface versions this SDK works with.
34
34
  CORE_API_VERSIONS = range(1, 2)
35
+ #: The least revision of that interface this SDK needs. A core from before
36
+ #: revisions has none and counts as 1.
37
+ CORE_API_REVISION = 2
35
38
 
36
39
  #: The name the core is loaded under, and the file it ships as.
37
40
  CORE_MODULE = "testflows.machine._core"
@@ -93,7 +96,8 @@ def _core() -> ModuleType:
93
96
  )
94
97
 
95
98
 
96
- _found = getattr(_core(), "API_VERSION", None)
99
+ _loaded = _core()
100
+ _found = getattr(_loaded, "API_VERSION", None)
97
101
  if _found not in CORE_API_VERSIONS:
98
102
  raise ImportError(
99
103
  f"The TestFlows™ Machine SDK Core has interface version {_found};"
@@ -101,3 +105,9 @@ if _found not in CORE_API_VERSIONS:
101
105
  f" {CORE_API_VERSIONS.stop - 1}."
102
106
  f" Update it with the TestFlows™ Machine client {_INSTALLER}"
103
107
  )
108
+ _revision = getattr(_loaded, "API_REVISION", 1)
109
+ if _revision < CORE_API_REVISION:
110
+ raise ImportError(
111
+ "The TestFlows™ Machine SDK Core is older than this SDK."
112
+ f" Update it with the TestFlows™ Machine client {_INSTALLER}"
113
+ )
@@ -16,6 +16,7 @@
16
16
  from __future__ import annotations
17
17
 
18
18
  import contextlib
19
+ import logging
19
20
  from pathlib import Path
20
21
  from typing import Any, Callable, Generator, Optional
21
22
 
@@ -27,6 +28,10 @@ from testflows.machine._core import tunnel
27
28
 
28
29
  from .errors import NotFound, ServiceUnavailable, _translated
29
30
 
31
+ #: Where the SDK says what a call waits on, such as a session moving to
32
+ #: another host. At INFO: the call goes on by itself.
33
+ _log = logging.getLogger("testflows.machine")
34
+
30
35
 
31
36
  class _Service:
32
37
  """One session's service: where its socket is and how disks are named.
@@ -43,11 +48,15 @@ class _Service:
43
48
  disks: Optional[Callable[[], list[dict[str, Any]]]],
44
49
  label: str,
45
50
  renew: Optional[Callable[[], None]] = None,
51
+ follow: Optional[Callable[[], Optional[Path]]] = None,
46
52
  ) -> None:
47
53
  self.socket = socket
48
54
  self.disks = disks
49
55
  self.label = label
50
56
  self.renew = renew
57
+ #: Follows the session when it moved, `sessions migrate`, and gives the
58
+ #: socket of where it went: a call that meets the move goes on there.
59
+ self.follow = follow
51
60
 
52
61
  @contextlib.contextmanager
53
62
  def client(self) -> Generator[ipc.Client, None, None]:
@@ -58,7 +67,9 @@ class _Service:
58
67
  raise ServiceUnavailable(f"The {self.label} is not running.")
59
68
  if self.renew is not None:
60
69
  self.renew()
61
- client = ipc.Client(socket_path=self.socket)
70
+ client = ipc.Client(
71
+ socket_path=self.socket, follow=self.follow, notice=_log.info
72
+ )
62
73
  try:
63
74
  client.connect()
64
75
  except OSError as exc:
@@ -86,7 +97,11 @@ def local() -> _Service:
86
97
 
87
98
 
88
99
  def of_session(
89
- client: api.client.Client, creds: dict[str, Any], session_id: str, name: str
100
+ client: api.client.Client,
101
+ creds: dict[str, Any],
102
+ session_id: str,
103
+ name: str,
104
+ follow: Optional[Callable[[], Optional[Path]]] = None,
90
105
  ) -> _Service:
91
106
  """A cloud session's service, through this machine's tunnel to it.
92
107
 
@@ -106,4 +121,5 @@ def of_session(
106
121
  lambda: api.auth.authed(creds, client.disk_list),
107
122
  f"service of session {name}",
108
123
  renew,
124
+ follow,
109
125
  )
@@ -13,4 +13,4 @@
13
13
  # limitations under the License.
14
14
  """The SDK's version."""
15
15
 
16
- __version__ = "0.1.2"
16
+ __version__ = "0.1.3"
@@ -0,0 +1,38 @@
1
+ # Copyright 2026 Katteli Inc.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ """Warnings attributed to the program's own call."""
15
+
16
+ from __future__ import annotations
17
+
18
+ import contextlib
19
+ import os
20
+ import sys
21
+ import types
22
+ import warnings
23
+ from typing import Optional
24
+
25
+ #: Frames a warning is never attributed to: the SDK's own, and contextlib's,
26
+ #: which a `with` on the SDK's connections passes through.
27
+ _SKIPPED = (os.path.dirname(__file__) + os.sep, contextlib.__file__)
28
+
29
+
30
+ def warn(message: str, category: type[Warning]) -> None:
31
+ """Warn at the first frame outside the SDK: the program's call, however
32
+ many of the SDK's own calls lie between."""
33
+ level = 1
34
+ frame: Optional[types.FrameType] = sys._getframe(1)
35
+ while frame is not None and frame.f_code.co_filename.startswith(_SKIPPED):
36
+ frame = frame.f_back
37
+ level += 1
38
+ warnings.warn(message, category, stacklevel=level + 1)
@@ -24,9 +24,11 @@ from __future__ import annotations
24
24
  import builtins
25
25
  import contextlib
26
26
  import dataclasses
27
+ from datetime import datetime, timezone
27
28
  import time
28
29
  import os
29
- from typing import Any, Generator, Literal, Optional, Sequence, overload
30
+ from pathlib import Path
31
+ from typing import Any, Callable, Generator, Literal, Optional, Sequence, overload
30
32
 
31
33
  from testflows.machine._core import api
32
34
  from testflows.machine._core import branches as _branches
@@ -38,19 +40,21 @@ from testflows.machine._core import parsers as _parsers
38
40
  from testflows.machine._core import ping as _ping
39
41
  from testflows.machine._core import storage_ops as _storage_ops
40
42
  from testflows.machine._core import run_source as _run_source
43
+ from testflows.machine._core import sessions as _sessions
41
44
  from testflows.machine._core import sorting as _sorting
42
45
  from testflows.machine._core import wait as _wait
43
46
  from testflows.machine._core import wire as _wire
44
47
 
45
48
  from . import _args
46
49
  from . import _service
50
+ from . import _warn
47
51
  from . import _when
48
52
  from . import results
49
53
  from .errors import ApiError, InvalidArgument, ServiceUnavailable, _translated
50
54
  from .disks import Disk, Disks
51
55
  from .ping import Ping, _public
52
56
  from .runs import Run
53
- from .sessions import Session, Sessions
57
+ from .sessions import Session, SessionClosing, Sessions
54
58
 
55
59
  #: Set to 1, a client given no session works with the service on this
56
60
  #: machine.
@@ -62,6 +66,25 @@ _MEM_MODES = ("auto", "map", "lazy")
62
66
  _CONSOLES = ("serial", "virtio")
63
67
  _FRAMEBUFFERS = ("vnc", "gtk", "sdl", "none")
64
68
 
69
+ #: A notice's deadline as the client keys it, and as `Session.closing_at`
70
+ #: holds it when the service cannot be read: ISO 8601 in UTC.
71
+ _NOTICE_TIME = "%Y-%m-%dT%H:%M:%S"
72
+
73
+
74
+ def _deadline(value: str) -> datetime:
75
+ """A deadline as the service or the record writes it, in UTC. One with no
76
+ offset is UTC already."""
77
+ at = datetime.fromisoformat(value)
78
+ if at.tzinfo is None:
79
+ return at.replace(tzinfo=timezone.utc)
80
+ return at.astimezone(timezone.utc)
81
+
82
+
83
+ def _deadline_key(at: datetime) -> str:
84
+ """How the client remembers a deadline it told."""
85
+ return at.astimezone(timezone.utc).strftime(_NOTICE_TIME)
86
+
87
+
65
88
  #: `runs --parents`: where a run reads its data parents from.
66
89
  _PARENTS = ("local", "remote")
67
90
 
@@ -104,11 +127,31 @@ class Client:
104
127
  ... run.run(until="/app:exit")
105
128
  ... run.checkpoint("done")
106
129
 
130
+ A session can be scheduled to stop for maintenance of its host. The
131
+ client reads the notice at the start of a call into the session, at most
132
+ once every ten minutes from the service, and tells the program once for
133
+ each notice: through `on_session_closing` when it is given, or with a
134
+ `SessionClosing` warning. The session's `closing_at` and
135
+ `closing_reason` say when and why. Use `Session.migrate` before then to
136
+ keep its machines running. A call that is already running when the
137
+ deadline passes is not told.
138
+
139
+ Example:
140
+ >>> def closing(session):
141
+ ... session.migrate()
142
+ >>> client = machine.Client(on_session_closing=closing)
143
+
107
144
  Args:
108
145
  session (str, optional): The current session, by name, id or unique
109
146
  id prefix, as `-s` names it.
110
147
  api_url (str, optional): The service's URL, as `--api-url` gives it;
111
148
  defaults to TESTFLOWS_MACHINE_API_URL, else the public service.
149
+ on_session_closing (callable, optional): Called with the `Session`
150
+ once for each maintenance notice, before the call that found it
151
+ goes on. A call it makes goes on in the session it leaves
152
+ current, so a callback that migrates moves the call with it. An
153
+ exception it raises is raised from that call, and the notice is
154
+ not told again.
112
155
  """
113
156
 
114
157
  def __init__(
@@ -116,6 +159,7 @@ class Client:
116
159
  *,
117
160
  session: Optional[str] = None,
118
161
  api_url: Optional[str] = None,
162
+ on_session_closing: Optional[Callable[[Session], None]] = None,
119
163
  ) -> None:
120
164
  local = os.environ.get(_LOCAL_ENV) == "1"
121
165
  if local and session is not None:
@@ -126,9 +170,17 @@ class Client:
126
170
  self._local = local
127
171
  self._session_ref = session
128
172
  self._session: Optional[Session] = None
173
+ #: The session each moved one went to, `sessions migrate`, so every
174
+ #: Session object of a moved session names where it went.
175
+ self._moved_ids: dict[str, str] = {}
129
176
  self._api_url = api_url
130
177
  self._api: Optional[tuple[api.client.Client, dict[str, Any]]] = None
131
178
  self._services: dict[str, _service._Service] = {}
179
+ self._on_session_closing = on_session_closing
180
+ #: The deadlines each session's notice was told for, so a notice is
181
+ #: told once, and again only when it changes. Both the record's and
182
+ #: the session's as read again, which can differ while the record lags.
183
+ self._closing_told: dict[str, set[str]] = {}
132
184
 
133
185
  @classmethod
134
186
  def _signed_in(
@@ -867,6 +919,14 @@ class Client:
867
919
  self._session_ref = session.id
868
920
  self._session = session
869
921
 
922
+ def _moved(self, old_id: str, session: Session) -> None:
923
+ """`old_id` moved to `session`: every Session object of `old_id` names it
924
+ now, and the client uses it in its place when it was current."""
925
+ self._moved_ids[old_id] = session.id
926
+ self._services.pop(old_id, None)
927
+ if self._session is not None and self._session.id == session.id:
928
+ self._use(session)
929
+
870
930
  def _forget(self, session_id: str) -> None:
871
931
  """Drop `session_id` as current, when it is: it was deleted."""
872
932
  self._services.pop(session_id, None)
@@ -893,16 +953,109 @@ class Client:
893
953
  )
894
954
  if session.id not in self._services:
895
955
  client, creds = self._account()
896
- self._services[session.id] = _service.of_session(
897
- client, creds, session.id, session.name
956
+ session_id = session.id
957
+ self._services[session_id] = _service.of_session(
958
+ client,
959
+ creds,
960
+ session_id,
961
+ session.name,
962
+ follow=lambda: self._follow_from(session_id),
898
963
  )
899
964
  return self._services[session.id]
900
965
 
901
966
  @contextlib.contextmanager
902
967
  def _connection(self) -> Generator[_ipc.Client, None, None]:
903
- """A connection to the current session's service."""
904
- with self._service().client() as client:
905
- yield client
968
+ """A connection to the current session's service.
969
+
970
+ A call that fails because the session moved, `sessions migrate`, makes
971
+ the client follow it: the next call goes to where the session went. The
972
+ failed call is raised as it failed, since it may have done its work.
973
+
974
+ A session's maintenance notice is told first, so a callback that
975
+ migrates sends the call to the new session."""
976
+ if not self._local:
977
+ self._tell_closing()
978
+ try:
979
+ with self._service().client() as client:
980
+ yield client
981
+ except Exception as err:
982
+ if not self._local and _sessions.moved_away(err):
983
+ self._follow()
984
+ raise
985
+
986
+ def _tell_closing(self) -> None:
987
+ """Tell the program of the current session's maintenance notice, once
988
+ for each deadline: `on_session_closing`, or a `SessionClosing`
989
+ warning. Marked told before the callback runs, so the calls it makes
990
+ do not tell it again."""
991
+ session = self.session
992
+ if session is None:
993
+ return
994
+ notice = _sessions.notice(session.id, self._account)
995
+ if notice is None:
996
+ if self._closing_told.pop(session.id, None):
997
+ session._closing(None, None)
998
+ return
999
+ by = _deadline_key(notice.by)
1000
+ told = self._closing_told.setdefault(session.id, set())
1001
+ if by in told:
1002
+ return
1003
+ told.add(by)
1004
+ if not self._closing_still(session, by, notice.reason):
1005
+ return
1006
+ deadline = _deadline(str(session.closing_at))
1007
+ told.add(_deadline_key(deadline))
1008
+ if self._on_session_closing is not None:
1009
+ self._on_session_closing(session)
1010
+ return
1011
+ reason = session.closing_reason or notice.reason
1012
+ _warn.warn(
1013
+ f"Session {session.name} stops at {deadline:%Y-%m-%d %H:%M} UTC"
1014
+ f" because of {reason}. Move it before then with Session.migrate.",
1015
+ SessionClosing,
1016
+ )
1017
+
1018
+ def _closing_still(self, session: Session, by: str, reason: str) -> bool:
1019
+ """Read `session` again before a notice is told: the notice is read
1020
+ from a record up to ten minutes old, and a session that moved or ended
1021
+ since keeps its notice, which nothing can act on. When the service
1022
+ does not answer, the notice is told as recorded: a notice never fails
1023
+ the call it rides on."""
1024
+ try:
1025
+ session.refresh()
1026
+ except Exception:
1027
+ session._closing(by, reason)
1028
+ return True
1029
+ live = session.state in _sessions.NOTICE_STATES
1030
+ moved = bool(session._row.get("successor_id"))
1031
+ return live and not moved and session.closing_at is not None
1032
+
1033
+ def _follow(self) -> None:
1034
+ """Use the session the current one moved to, when it moved."""
1035
+ if self._session is not None:
1036
+ self._follow_from(self._session.id)
1037
+
1038
+ def _follow_from(self, old_id: str) -> Optional[Path]:
1039
+ """Follow session `old_id` to where it moved, and give its socket; None
1040
+ when it did not move. Bound to each session's service, so a session that
1041
+ is not the current one follows its own move, not the current one's."""
1042
+ client, creds = self._account()
1043
+ try:
1044
+ info = _sessions.follow(client, creds, old_id)
1045
+ except Exception: # the error that led here is the one to report
1046
+ return None
1047
+ if info is None:
1048
+ return None
1049
+ moved = Session(self, info)
1050
+ self._moved(old_id, moved)
1051
+ return api.store.session_socket(moved.id)
1052
+
1053
+ def _now_id(self, session_id: str) -> str:
1054
+ """The id a session has now: the session it moved to, after every move this
1055
+ client followed."""
1056
+ while session_id in self._moved_ids:
1057
+ session_id = self._moved_ids[session_id]
1058
+ return session_id
906
1059
 
907
1060
  @contextlib.contextmanager
908
1061
  def _catalog(self) -> Generator[_run_source.RunSource, None, None]:
@@ -115,9 +115,10 @@ class Conflict(Error):
115
115
 
116
116
 
117
117
  class Diverged(Error):
118
- """A recorded run could not be followed: `Run.play` stopped where the
119
- machine no longer matched the recording. `Run.replay` reports a
120
- divergence in its result instead."""
118
+ """A machine's state did not match what was recorded. `Run.play` stopped
119
+ where the machine no longer matched the recording, or `Session.migrate`
120
+ started a machine in another state than it stopped in. `Run.replay`
121
+ reports a divergence in its result instead."""
121
122
 
122
123
 
123
124
  class Timeout(Error, TimeoutError):
@@ -19,9 +19,11 @@ import builtins
19
19
  from typing import TYPE_CHECKING, Any, Generator, Literal, Optional, overload
20
20
 
21
21
  from testflows.machine._core import api
22
+ from testflows.machine._core import migration as _migration
22
23
  from testflows.machine._core import sessions as _sessions
23
24
 
24
25
  from . import _args
26
+ from . import _warn
25
27
  from .errors import ApiError, InvalidArgument, NotFound, _translated
26
28
 
27
29
  if TYPE_CHECKING:
@@ -49,6 +51,18 @@ FIELDS: tuple[str, ...] = (
49
51
  )
50
52
 
51
53
 
54
+ class SessionClosing(UserWarning):
55
+ """A session is scheduled to stop for maintenance of its host. The
56
+ client gives it once for each notice, at the program's next call into the
57
+ session, when the program set no `on_session_closing`. Use
58
+ `warnings.simplefilter("error", SessionClosing)` to raise it instead."""
59
+
60
+
61
+ class SessionMovedBack(UserWarning):
62
+ """A run that `migrate` started at its last checkpoint, not where it was,
63
+ because the session's host was lost before the move stopped it."""
64
+
65
+
52
66
  class Session:
53
67
  """One session: a machine the account rents, with its own CPUs,
54
68
  memory and storage, where runs execute.
@@ -75,8 +89,9 @@ class Session:
75
89
 
76
90
  @property
77
91
  def id(self) -> str:
78
- """str: The session's id, which never changes."""
79
- return str(self._row["session_id"])
92
+ """str: The session's id. A session moved with `migrate` has a new id,
93
+ which this follows, whichever client or object moved it."""
94
+ return self._client._now_id(str(self._row["session_id"]))
80
95
 
81
96
  @property
82
97
  def name(self) -> str:
@@ -142,6 +157,24 @@ class Session:
142
157
  """str: When the session stopped, ISO 8601; None while it runs."""
143
158
  return _str_or_none(self._row.get("stopped_at"))
144
159
 
160
+ @property
161
+ def closing_at(self) -> Optional[str]:
162
+ """str: When the session stops for maintenance of its host, ISO 8601;
163
+ None when none is scheduled. Use `migrate` before then to keep its
164
+ machines running in a new session. Read again with `refresh`."""
165
+ return _str_or_none(self._row.get("closing_at"))
166
+
167
+ @property
168
+ def closing_reason(self) -> Optional[str]:
169
+ """str: Why the session stops at `closing_at`, such as a kernel
170
+ update; None when none is scheduled."""
171
+ return _str_or_none(self._row.get("closing_reason"))
172
+
173
+ def _closing(self, by: Optional[str], reason: Optional[str]) -> None:
174
+ """Set the notice the client read, without asking the API again."""
175
+ self._row["closing_at"] = by
176
+ self._row["closing_reason"] = reason
177
+
145
178
  def refresh(self) -> "Session":
146
179
  """Read the session again, so its attributes are current.
147
180
 
@@ -241,6 +274,60 @@ class Session:
241
274
  self._row = _sessions.keep(client, creds, self.id, minutes)
242
275
  return self
243
276
 
277
+ def migrate(self) -> "Session":
278
+ """Move the session to a new session with its runs, as `machine
279
+ sessions migrate` does.
280
+
281
+ A session of the same class and size is created. Each running machine
282
+ is stopped, which checkpoints it, and started in the new session at
283
+ that checkpoint, in the same state. The new session takes the name,
284
+ and the old one is deleted. A command running on a machine ends, as
285
+ `stop` ends it.
286
+
287
+ A move that fails is put back: every machine it stopped starts again
288
+ in the session, and the new session is deleted. When the session ends
289
+ during the move, the move finishes in the new session instead.
290
+
291
+ A machine the move had not stopped when the session's host was lost
292
+ starts at its last checkpoint, not where it was. Each one is reported
293
+ with a `SessionMovedBack` warning that names the run.
294
+
295
+ This object becomes the new session. When it was the client's current
296
+ session, the client uses the new one.
297
+
298
+ Example:
299
+ >>> session = client.sessions.show("ci-1")
300
+ >>> session.migrate().name
301
+ 'ci-1'
302
+
303
+ Returns:
304
+ Session: This session, moved.
305
+
306
+ Raises:
307
+ NoCapacity: No other host has room for the session now.
308
+ NotRunning: The session is not running.
309
+ Diverged: A machine started in another state in the new session.
310
+ The sessions are kept as they are, and the message says how
311
+ to go on.
312
+ Conflict: The move was refused, or failed and was put back. The
313
+ message says why.
314
+ ApiError: The service could not carry out the move.
315
+ """
316
+ client, creds = self._client._account()
317
+ old_id = self.id
318
+ with _translated():
319
+ planned = _migration.plan(client, creds, old_id)
320
+ moved = _migration.migrate(client, creds, planned)
321
+ self._row = moved.session
322
+ self._client._moved(old_id, self)
323
+ for machine in moved.went_back:
324
+ _warn.warn(
325
+ f"{machine.name} ({machine.run_id}) started at its last checkpoint."
326
+ " The session's host was lost before the move stopped it.",
327
+ SessionMovedBack,
328
+ )
329
+ return self
330
+
244
331
  def delete(self, *, wait: bool = True, timeout: Optional[float] = None) -> None:
245
332
  """Delete the session, as `machine sessions delete` does.
246
333
 
@@ -471,7 +558,9 @@ class Sessions:
471
558
  tests it and reconnects through a fresh tunnel when it does not
472
559
  answer. Otherwise it connects, waiting while the session is still
473
560
  provisioning. Only this client changes: the CLI's current session is
474
- left as it is.
561
+ left as it is. A session that moved, `migrate` here or on another
562
+ computer, is followed: the session it moved to becomes current, and
563
+ every Session object of the one it left names it.
475
564
 
476
565
  Example:
477
566
  >>> session = client.sessions.use("ci-1")
@@ -498,13 +587,48 @@ class Sessions:
498
587
  failed.
499
588
  ServiceUnavailable: The session does not respond.
500
589
  """
501
- known = self.show(session)
590
+ known = self._moved_to(self.show(session))
502
591
  with _translated():
503
592
  if api.store.session_connected(known.id) and _sessions.recheck(known.id):
504
593
  self._client._use(known)
505
594
  return known
506
595
  return self.connect(known, wait=wait, timeout=timeout)
507
596
 
597
+ def _moved_to(self, session: Session) -> Session:
598
+ """The session `session` moved to, after every move; itself when it did
599
+ not move."""
600
+ if not session._row.get("successor_id"):
601
+ return session
602
+ client, creds = self._client._account()
603
+ with _translated():
604
+ row = _sessions.follow(client, creds, session.id)
605
+ if row is None:
606
+ return session
607
+ moved = Session(self._client, row)
608
+ self._client._moved(session.id, moved)
609
+ return moved
610
+
611
+ def migrate(self, session: "Session | str | None" = None) -> Session:
612
+ """Move a session to a new session with its runs, as `machine sessions
613
+ migrate` does. See `Session.migrate`.
614
+
615
+ Args:
616
+ session (Session or str, optional): The session; defaults to the
617
+ only one.
618
+
619
+ Returns:
620
+ Session: The session, moved.
621
+
622
+ Raises:
623
+ NotFound: No session matches.
624
+ NoCapacity: No other host has room for the session now.
625
+ NotRunning: The session is not running.
626
+ Diverged: A machine started in another state. See `Session.migrate`.
627
+ Conflict: The move was refused, or failed and was put back.
628
+ """
629
+ target = session if isinstance(session, Session) else self.show(session)
630
+ return target.migrate()
631
+
508
632
  def show(self, session: "Session | str | None" = None) -> Session:
509
633
  """Read a session, as `machine sessions show` does.
510
634
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: testflows.machine
3
- Version: 0.1.2
3
+ Version: 0.1.3
4
4
  Summary: Python SDK for TestFlows™ Machine, the deterministic execution environment
5
5
  Author-email: "Katteli Inc." <info@testflows.com>
6
6
  License-Expression: Apache-2.0
@@ -11,6 +11,7 @@ testflows/machine/v1/_args.py
11
11
  testflows/machine/v1/_requires.py
12
12
  testflows/machine/v1/_service.py
13
13
  testflows/machine/v1/_version.py
14
+ testflows/machine/v1/_warn.py
14
15
  testflows/machine/v1/_when.py
15
16
  testflows/machine/v1/client.py
16
17
  testflows/machine/v1/disks.py