LightningWork

class lightning.app.core.LightningWork(parallel=False, cache_calls=True, raise_exception=True, host='127.0.0.1', port=None, local_build_config=None, cloud_build_config=None, cloud_compute=None, run_once=None, start_with_flow=True)[source]

Bases: object

LightningWork, or Work in short, is a building block for long-running jobs.

The LightningApp runs its LightningFlow component within an infinite loop and track the LightningWork status update.

Use LightningWork for third-party services or for launching heavy jobs such as downloading data, training or serving a model.

Each LightningWork is running in its own independent process. Works are self-isolated from the rest, e.g any state changes happening within the work will be reflected within the flow but not the other way around.

Parameters:
  • parallel (bool) – Whether to run in parallel mode or not. When False, the flow waits for the work to finish.

  • cache_calls (bool) – Whether the run method should cache its input arguments and not run again when provided with the same arguments in subsequent calls.

  • raise_exception (bool) – Whether to re-raise an exception in the flow when raised from within the work run method.

  • host (str) – Bind socket to this host

  • port (Optional[int]) – Bind socket to this port. Be default, this is None and should be called within your run method.

  • local_build_config (Optional[BuildConfig]) – The local BuildConfig isn’t used until Lightning supports DockerRuntime.

  • cloud_build_config (Optional[BuildConfig]) – The cloud BuildConfig enables user to easily configure machine before running this work.

  • run_once (Optional[bool]) – Deprecated in favor of cache_calls. This will be removed soon.

  • start_with_flow (bool) – Whether the work should be started at the same time as the root flow. Only applies to works defined in __init__.

Learn More About Lightning Work Inner Workings


_run_executor_cls[source]

alias of WorkRunExecutor

_aggregate_status_timeout(statuses)[source]

Method used to return the first request and the total count of timeout after the latest succeeded status.

Return type:

WorkStatus

static _is_state_attribute(name)[source]

Every public attribute is part of the state by default and all protected (prefixed by ‘_’) or private (prefixed by ‘__’) attributes are not.

Exceptions are listed in the _INTERNAL_STATE_VARS class variable.

Return type:

bool

apply_flow_delta(delta)[source]

Override to customize how the flow should update the work state.

Return type:

None

configure_layout()[source]

Configure the UI of this LightningWork.

You can either :rtype: Union[None, str, Frontend]

  1. Return a single Frontend object to serve a user interface for this Work.

  2. Return a string containing a URL to act as the user interface for this Work.

  3. Return None to indicate that this Work doesn’t currently have a user interface.

Example: Serve a static directory (with at least a file index.html inside).

from lightning.app.frontend import StaticWebFrontend


class Work(LightningWork):
    def configure_layout(self):
        return StaticWebFrontend("path/to/folder/to/serve")

Example: Arrange the UI of my children in tabs (default UI by Lightning).

class Work(LightningWork):
    def configure_layout(self):
        return [
            dict(name="First Tab", content=self.child0),
            dict(name="Second Tab", content=self.child1),
            dict(name="Lightning", content="https://lightning.ai"),
        ]

If you don’t implement configure_layout, Lightning will use self.url.

Note

This hook gets called at the time of app creation and then again as part of the loop. If desired, a returned URL can depend on the state. This is not the case if the work returns a Frontend. These need to be provided at the time of app creation in order for the runtime to start the server.

delete()[source]

Delete LightingWork component and shuts down hardware provisioned via CloudCompute.

Locally, the work.delete() behaves as work.stop().

Return type:

None

on_exception(exception)[source]

Override to customize how to handle exception in the run method.

Return type:

None

on_exit()[source]

Override this hook to add your logic when the work is exiting.

Note: This hook is not guaranteed to be called when running in the cloud.

Return type:

None

run(*args, **kwargs)[source]

Override to add your own logic.

Raises:

LightningPlatformException – If resource exceeds platform quotas or other constraints.

Return type:

None

start()[source]

Starts LightingWork component via CloudCompute.

Return type:

None

stop()[source]

Stops LightingWork component and shuts down hardware provisioned via CloudCompute.

This can only be called from a LightningFlow.

Return type:

None

property cache_calls: bool[source]

Returns whether the run method should cache its input arguments and not run again when provided with the same arguments in subsequent calls.

property cloud_build_config: BuildConfig[source]

Returns the cloud build config used to prepare the selected cloud hardware.

property display_name: str[source]

Returns the display name of the LightningWork in the cloud.

The display name needs to set before the run method of the work is called.

property has_failed: bool[source]

Return whether the work has failed.

property has_started: bool[source]

Return whether the work has started.

property has_stopped: bool[source]

Return whether the work has stopped.

property has_succeeded: bool[source]

Return whether the work has succeeded.

property has_timeout: bool[source]

Return whether the work has time-out.

property host: str[source]

Returns the current host of the work.

property internal_ip: str[source]

The internal ip address of this LightningWork, reachable by other Work locally and in the cloud.

By default, this attribute returns the empty string and the ip address will only be returned once the work runs. Locally, the address is 127.0.0.1 and in the cloud it will be determined by the cluster.

property is_pending: bool[source]

Return whether the work is pending.

property is_running: bool[source]

Return whether the work is running.

property lightningignore: Tuple[str, ...][source]

Programmatic equivalent of the .lightningignore file.

property name: str[source]

Returns the name of the LightningWork.

property num_successes: int[source]

Returns the number of successful runs.

property num_timeouts: int[source]

Return the number of timeout status since the lastest succeeded run.

property parallel: bool[source]

Whether to run in parallel mode or not.

When parallel is False, the flow waits for the work to finish.

property public_ip: str[source]

The public ip address of this LightningWork, reachable from the internet.

By default, this attribute returns the empty string and the ip address will only be returned once the work runs. Locally, this address is undefined (empty string) and in the cloud it will be determined by the cluster.

property state: dict[source]

Returns the current state of this LightningWork.

property status: WorkStatus[source]

Return the current status of the work.

All statuses are stored in the state.

property statuses: List[WorkStatus][source]

Return all the status of the work.

property url: str[source]

Returns the current url of the work.