nvflare.fuel.flare_api.api_spec module¶
- class MonitorReturnCode(value)[source]¶
Bases:
int
,Enum
An enumeration.
- ENDED_BY_CB = 2¶
- JOB_FINISHED = 0¶
- TIMEOUT = 1¶
- class SessionSpec[source]¶
Bases:
ABC
- abstract abort_job(job_id: str)[source]¶
Abort the specified job
- Parameters:
job_id – job to be aborted
Returns: None
If the job is already done, no effect; If job is not started yet, it will be cancelled and won’t be scheduled. If the job is being executed, it will be aborted
- abstract cat_target(target: str, options: str | None = None, file: str | None = None) str [source]¶
Run the “cat” command on the specified target and return result
- Parameters:
target – the target (server or a client name) the command will run
options – options of the “cat” command
file – the file that the “cat” command will run against
Returns: result of “cat” command
- abstract clone_job(job_id: str) str [source]¶
Create a new job by cloning a specified job
- Parameters:
job_id – job to be cloned
Returns: ID of the new job
- abstract delete_job(job_id: str)[source]¶
Delete the specified job completely from the system
- Parameters:
job_id – job to be deleted
Returns: None
If the job is being executed, the job will be stopped first. Everything of the job will be deleted from the job store, as well as workspaces on the FL server and clients.
- abstract download_job_result(job_id: str) str [source]¶
Download result of the job
- Parameters:
job_id – ID of the job
Returns: folder path to the location of the job result
If the job size is smaller than the maximum size set on the server, the job will download to the download_dir set in Session through the admin config, and the path to the downloaded result will be returned. If the size of the job is larger than the maximum size, the location to download the job will be returned.
- abstract get_active_sp() dict [source]¶
Get the current active service provider (SP).
Returns: a dict that describes the current active SP. If no SP is available currently, the ‘name’ attribute of the result is empty.
- abstract get_available_apps_to_upload()[source]¶
Get defined FLARE app folders from the upload folder on the machine the FLARE API is running
Returns: a list of app folders
- abstract get_client_job_status(client_names: List[str] | None = None) List[dict] [source]¶
Get job status info of specified FL clients
- Parameters:
client_names – names of the clients to get status info
Returns: A list of jobs running on the clients. Each job is described by a dict of: id, app name and status. If there are multiple jobs running on one client, the list contains one entry for each job for that client. If no FL clients are connected or the server failed to communicate to them, this method returns None.
- abstract get_connected_client_list() List[ClientInfo] [source]¶
Get the list of connected clients
Returns: a list of ClientInfo objects
- abstract get_job_meta(job_id: str) dict [source]¶
Get the meta info of the specified job
- Parameters:
job_id – ID of the job
Returns: a dict of job metadata
- abstract get_system_info() SystemInfo [source]¶
Get general info of the FLARE system
- abstract get_working_directory(target: str) str [source]¶
Get the working directory of the specified target
- Parameters:
target – the target (server of a client name)
Returns: current working directory of the specified target
- abstract grep_target(target: str, options: str | None = None, pattern: str | None = None, file: str | None = None) str [source]¶
Run the “grep” command on the specified target and return result
- Parameters:
target – the target (server or a client name) the command will run
options – options of the “grep” command
pattern – the grep pattern
file – the file that the “grep” command will run against
Returns: result of “grep” command
- abstract head_target(target: str, options: str | None = None, file: str | None = None) str [source]¶
Run the “head” command on the specified target and return result
- Parameters:
target – the target (server or a client name) the command will run
options – options of the “head” command
file – the file that the “head” command will run against
Returns: result of “head” command
- abstract head_target_log(target: str, options: str | None = None) str [source]¶
Run the “head log.txt” command on the specified target and return result
- Parameters:
target – the target (server or a client name) the command will run
options – options of the “head” command
Returns: result of “head” command
- abstract list_jobs(detailed: bool = False, all: bool = False) List[dict] [source]¶
Get the job info from the server
- Parameters:
detailed – True to get the detailed information for each job, False by default
all – True to get jobs submitted by all users (default is to only list jobs submitted by the same user)
Returns: a list of job metadata
- abstract list_sp() dict [source]¶
List available service providers
Returns: a dict that contains information about the primary SP and others
- abstract ls_target(target: str, options: str | None = None, path: str | None = None) str [source]¶
Run the “ls” command on the specified target and return result
- Parameters:
target – the target (server or a client name) the command will run
options – options of the “ls” command
path – the optional file path
Returns: result of “ls” command
- abstract monitor_job(job_id: str, timeout: int = 0, poll_interval: float = 2.0, cb=None, *cb_args, **cb_kwargs) MonitorReturnCode [source]¶
- Monitor the job progress until one of the conditions occurs:
job is done
timeout
the status_cb returns False
- Parameters:
job_id – the job to be monitored
timeout – how long to monitor. If 0, never time out.
poll_interval – how often to poll job status
cb – if provided, callback to be called after each poll
Returns: a MonitorReturnCode
Every time the cb is called, it must return a bool indicating whether the monitor should continue. If False, this method ends.
- abstract promote_sp(sp_end_point: str)[source]¶
Promote the specified endpoint to become the active SP.
- Parameters:
sp_end_point – the endpoint of the SP. It’s string in this format: <url>:<server_port>:<admin_port>
Returns: None
- abstract reset_errors(job_id: str)[source]¶
Clear errors for all system targets for the specified job
- Parameters:
job_id – ID of the job
Returns: None
- abstract restart(target_type: str, client_names: List[str] | None = None) dict [source]¶
Restart specified system target(s)
- Parameters:
target_type – what system target (server, client, or all) to restart
client_names – clients to be restarted if target_type is client. If not specified, all clients.
Returns: a dict that contains detailed info about the restart request: status - the overall status of the result. server_status - whether the server is restarted successfully - only if target_type is “all” or “server”. client_status - a dict (keyed on client name) that specifies status of each client - only if target_type is “all” or “client”.
- abstract set_timeout(value: float)[source]¶
Set a session-specific command timeout. This is the amount of time the server will wait for responses after sending commands to FL clients.
Note that this value is only effective for the current API session.
- Parameters:
value – a positive float number
Returns: None
- abstract show_errors(job_id: str, target_type: str, targets: List[str] | None = None) dict [source]¶
Show processing errors of specified job on specified targets
- Parameters:
job_id – ID of the job
target_type – type of target (server or client)
targets – list of client names if target type is “client”. All clients if not specified.
Returns: a dict that contains job errors (if any) on specified targets. The key of the dict is target name. The value is a dict of errors reported by different system components (ServerRunner or ClientRunner).
- abstract show_stats(job_id: str, target_type: str, targets: List[str] | None = None) dict [source]¶
Show processing stats of specified job on specified targets
- Parameters:
job_id – ID of the job
target_type – type of target (server or client)
targets – list of client names if target type is “client”. All clients if not specified.
Returns: a dict that contains job stats on specified targets. The key of the dict is target name. The value is a dict of stats reported by different system components (ServerRunner or ClientRunner).
- abstract shutdown(target_type: TargetType, client_names: List[str] | None = None)[source]¶
Shut down specified system target(s)
- Parameters:
target_type – what system target (server, client, or all) to shut down
client_names – clients to be shut down if target_type is client. If not specified, all clients.
Returns: None
- abstract shutdown_system()[source]¶
Shut down the whole NVFLARE system including the overseer, FL server(s), and all FL clients.
Returns: None
Note: the user must be a Project Admin to use this method; otherwise the NOT_AUTHORIZED exception will raise.
- abstract submit_job(job_definition_path: str) str [source]¶
Submit a predefined job to the NVFLARE system
- Parameters:
job_definition_path – path to the folder that defines a NVFLARE job
Returns: the job id if accepted by the system
If the submission fails, exception will be raised:
- abstract tail_target(target: str, options: str | None = None, file: str | None = None) str [source]¶
Run the “tail” command on the specified target and return result
- Parameters:
target – the target (server or a client name) the command will run
options – options of the “tail” command
file – the file that the “tail” command will run against
Returns: result of “tail” command
- abstract tail_target_log(target: str, options: str | None = None) str [source]¶
Run the “tail log.txt” command on the specified target and return result
- Parameters:
target – the target (server or a client name) the command will run
options – options of the “tail” command
Returns: result of “tail” command
- class SystemInfo(server_info: ServerInfo, client_info: List[ClientInfo], job_info: List[JobInfo])[source]¶
Bases:
object
- job_monitor_cb_signature(session: SessionSpec, job_id: str, job_mea: dict, *args, **kwargs) bool [source]¶
- Parameters:
session – the session
job_id – ID of the job being monitored
job_mea – meta info of the job
*args
**kwargs
Returns: