ComputeSession Functions¶
-
class
ai.backend.client.func.session.
ComputeSession
(name, owner_access_key=None)[source]¶ Provides various interactions with compute sessions in Backend.AI.
The term ‘kernel’ is now deprecated and we prefer ‘compute sessions’. However, for historical reasons and to avoid confusion with client sessions, we keep the backward compatibility with the naming of this API function class.
For multi-container sessions, all methods take effects to the master container only, except
destroy()
andrestart()
methods. So it is the user’s responsibility to distribute uploaded files to multiple containers using explicit copies or virtual folders which are commonly mounted to all containers belonging to the same compute session.-
classmethod async for ... in
paginated_list
()¶ classmethod(function) -> method
Convert a function to be a class method.
A class method receives the class as implicit first argument, just like an instance method receives the instance. To declare a class method, use this idiom:
- class C:
@classmethod def f(cls, arg1, arg2, …):
…
It can be called either on the class (e.g. C.f()) or on an instance (e.g. C().f()). The instance is ignored except for its class. If a class method is called for a derived class, the derived class object is passed as the implied first argument.
Class methods are different than C++ or Java static methods. If you want those, see the staticmethod builtin.
-
classmethod await
hello
()¶ classmethod(function) -> method
Convert a function to be a class method.
A class method receives the class as implicit first argument, just like an instance method receives the instance. To declare a class method, use this idiom:
- class C:
@classmethod def f(cls, arg1, arg2, …):
…
It can be called either on the class (e.g. C.f()) or on an instance (e.g. C().f()). The instance is ignored except for its class. If a class method is called for a derived class, the derived class object is passed as the implied first argument.
Class methods are different than C++ or Java static methods. If you want those, see the staticmethod builtin.
-
classmethod async for ... in
get_task_logs
()¶ classmethod(function) -> method
Convert a function to be a class method.
A class method receives the class as implicit first argument, just like an instance method receives the instance. To declare a class method, use this idiom:
- class C:
@classmethod def f(cls, arg1, arg2, …):
…
It can be called either on the class (e.g. C.f()) or on an instance (e.g. C().f()). The instance is ignored except for its class. If a class method is called for a derived class, the derived class object is passed as the implied first argument.
Class methods are different than C++ or Java static methods. If you want those, see the staticmethod builtin.
-
classmethod await
get_or_create
()¶ classmethod(function) -> method
Convert a function to be a class method.
A class method receives the class as implicit first argument, just like an instance method receives the instance. To declare a class method, use this idiom:
- class C:
@classmethod def f(cls, arg1, arg2, …):
…
It can be called either on the class (e.g. C.f()) or on an instance (e.g. C().f()). The instance is ignored except for its class. If a class method is called for a derived class, the derived class object is passed as the implied first argument.
Class methods are different than C++ or Java static methods. If you want those, see the staticmethod builtin.
-
classmethod await
create_from_template
()¶ classmethod(function) -> method
Convert a function to be a class method.
A class method receives the class as implicit first argument, just like an instance method receives the instance. To declare a class method, use this idiom:
- class C:
@classmethod def f(cls, arg1, arg2, …):
…
It can be called either on the class (e.g. C.f()) or on an instance (e.g. C().f()). The instance is ignored except for its class. If a class method is called for a derived class, the derived class object is passed as the implied first argument.
Class methods are different than C++ or Java static methods. If you want those, see the staticmethod builtin.
-
await
destroy
(*, forced=False)[source]¶ Destroys the compute session. Since the server literally kills the container(s), all ongoing executions are forcibly interrupted.
-
await
restart
()[source]¶ Restarts the compute session. The server force-destroys the current running container(s), but keeps their temporary scratch directories intact.
-
await
interrupt
()[source]¶ Tries to interrupt the current ongoing code execution. This may fail without any explicit errors depending on the code being executed.
-
await
complete
(code, opts=None)[source]¶ Gets the auto-completion candidates from the given code string, as if a user has pressed the tab key just after the code in IDEs.
Depending on the language of the compute session, this feature may not be supported. Unsupported sessions returns an empty list.
-
await
execute
(run_id=None, code=None, mode='query', opts=None)[source]¶ Executes a code snippet directly in the compute session or sends a set of build/clean/execute commands to the compute session.
For more details about using this API, please refer the official API documentation.
- Parameters
run_id (
Optional
[str
]) – A unique identifier for a particular run loop. In the first call, it may beNone
so that the server auto-assigns one. Subsequent calls must use the returnedrunId
value to request continuation or to send user inputs.code (
Optional
[str
]) – A code snippet as string. In the continuation requests, it must be an empty string. When sending user inputs, this is where the user input string is stored.mode (
str
) – A constant string which is one of"query"
,"batch"
,"continue"
, and"user-input"
.opts (
Optional
[dict
]) – A dict for specifying additional options. Mainly used in the batch mode to specify build/clean/execution commands. See the API object reference for details.
- Returns
-
await
upload
(files, basedir=None, show_progress=False)[source]¶ Uploads the given list of files to the compute session. You may refer them in the batch-mode execution or from the code executed in the server afterwards.
- Parameters
files (
Sequence
[Union
[str
,Path
]]) –The list of file paths in the client-side. If the paths include directories, the location of them in the compute session is calculated from the relative path to basedir and all intermediate parent directories are automatically created if not exists.
For example, if a file path is
/home/user/test/data.txt
(ortest/data.txt
) where basedir is/home/user
(or the current working directory is/home/user
), the uploaded file is located at/home/work/test/data.txt
in the compute session container.basedir (
Union
[str
,Path
,None
]) – The directory prefix where the files reside. The default value is the current working directory.show_progress (
bool
) – Displays a progress bar during uploads.
-
await
download
(files, dest='.', show_progress=False)[source]¶ Downloads the given list of files from the compute session.
- Parameters
files (
Sequence
[Union
[str
,Path
]]) – The list of file paths in the compute session. If they are relative paths, the path is calculated from/home/work
in the compute session container.dest (
Union
[str
,Path
]) – The destination directory in the client-side.show_progress (
bool
) – Displays a progress bar during downloads.
-
await
list_files
(path='.')[source]¶ Gets the list of files in the given path inside the compute session container.
-
listen_events
()[source]¶ Opens the stream of the kernel lifecycle events. Only the master kernel of each session is monitored.
- Return type
SSEContextManager
- Returns
a
StreamEvents
object.
-
stream_events
()¶ Opens the stream of the kernel lifecycle events. Only the master kernel of each session is monitored.
- Return type
SSEContextManager
- Returns
a
StreamEvents
object.
-
stream_pty
()[source]¶ Opens a pseudo-terminal of the kernel (if supported) streamed via websockets.
- Return type
- Returns
a
StreamPty
object.
-
classmethod async for ... in
-
class
ai.backend.client.func.session.
StreamPty
(session, underlying_response, **kwargs)[source]¶ A derivative class of
WebSocketResponse
which provides additional functions to control the terminal.