local¶

The local service of a project: the service with the local backend in .simrun/.

.simrun/ of a project directory holds the store, the index, the token of the user and, while the service runs, service.json (pid, port, token, url and the environment it runs with). simrun serve --local runs the service in the foreground; ensure_local finds the running one or starts it in the background, which exits after IDLE_EXIT_S without a request and without a live run. A service in the background which runs with another environment than the command (python, simrun, task types) is restarted when it is idle. The service listens on 127.0.0.1 only, and its end cancels the runs of the local backend, so no process of a run outlives a graceful stop; a service which starts kills the processes one which died left behind (LocalBackend.kill_orphans).

LOCAL_DIR `module-attribute` ¶

LOCAL_DIR = '.simrun'

The directory of the local service in a project directory.

IDLE_EXIT_S `module-attribute` ¶

IDLE_EXIT_S = 1800

Seconds without a request and without a live run after which a service started in the background exits.

GRACEFUL_SHUTDOWN_S `module-attribute` ¶

GRACEFUL_SHUTDOWN_S = 5

Seconds the open requests, e.g. event streams, have at the end of the service.

PACKAGE_WEB `module-attribute` ¶

PACKAGE_WEB = Path(simrun.__file__).parent / 'web'

The built web app in the package, put there by the release before the wheel.

CHECKOUT `module-attribute` ¶

CHECKOUT = Path(simrun.__file__).parents[2]

The checkout of the repository simrun is imported from, if it is one.

INSTANCE_PATH `module-attribute` ¶

INSTANCE_PATH = '/local/instance'

The route which answers the instance of the local service, without a token.

STOP_PATH `module-attribute` ¶

STOP_PATH = '/local/stop'

The route which stops the local service, with the token of the user; with ?idle=1 only when no run is live and no other request is open (409 otherwise).

STOP_MARGIN_S `module-attribute` ¶

STOP_MARGIN_S = 30.0

Seconds a stop waits for the end of the service beyond the grace of the processes of its runs.

EXIT_RUNNING `module-attribute` ¶

EXIT_RUNNING = 3

The exit code of simrun serve --local when the service of the directory runs.

ServiceRunning ¶

Bases: RuntimeError

The local service of the directory runs already.

ServiceBusy ¶

Bases: RuntimeError

The local service has a live run or an open request, so it was not stopped.

LocalService `dataclass` ¶

LocalService(
    instance,
    pid,
    port,
    token,
    url,
    python="",
    version="",
    types="",
    background=False,
)

A running local service, as its service.json names it.

Attributes:

Name	Type	Description
`instance`	`str`	A random value of this start of the service, which it answers at `INSTANCE_PATH` without a token: a client checks it before it sends the token.
`pid`	`int`	The process of the service.
`port`	`int`	The port on `127.0.0.1`.
`token`	`str`	The bearer token of the user.
`url`	`str`	The URL of the API, `http://127.0.0.1:<port>`.
`python`	`str`	The interpreter of the service.
`version`	`str`	The version of simrun of the service.
`types`	`str`	The hash of the task types the service found (`environment`).
`background`	`bool`	Whether it was started in the background (`ensure_local`), which exits when idle and is restarted for another environment.

environment ¶

environment()

The environment of this process as a local service records it.

Returns:

Type	Description
`dict[str, str]`	`python` (the interpreter), `version` (of simrun) and `types`, a hash of the
`dict[str, str]`	entry points of the task types with the names and versions of their
`dict[str, str]`	distributions, so a new, removed or upgraded plugin changes it.

web_dir ¶

web_dir()

The built web app: the one in the package, else the one of a checkout.

Returns:

Type	Description
`Path \| None`	`simrun/web` of the installed package if it has an `index.html`, else
`Path \| None`	`frontend/dist` of the checkout of simrun it is imported from (a
`Path \| None`	`pyproject.toml` of the project simrun beside `frontend/`), else None.

local_dir ¶

local_dir(root)

.simrun/ of a project directory, created with a .gitignore of everything.

local_settings ¶

local_settings(root)

The settings of the local service of a project directory.

The token file is generated once with a random token of the user, a person who owns the service.

Parameters:

Name	Type	Description	Default
`root`	`Path`	The project directory.	required

Returns:

Type	Description
`ServiceSettings`	The settings: the store, the index and the tokens in `.simrun/`.

serve_local ¶

serve_local(
    root,
    port=0,
    idle_exit_s=None,
    ready=None,
    stopping=None,
)

Run the local service of a project directory until stopped.

Writes .simrun/service.json once the service listens and removes it at the end; the end cancels every run of the local backend and waits for its processes. At the start it kills the processes a service before left running when it died.

Parameters:

Name	Type	Description	Default
`root`	`Path`	The project directory.	required
`port`	`int`	The port on `127.0.0.1`, 0 for a free one.	`0`
`idle_exit_s`	`float \| None`	Exit after this many seconds without a request and without a live run; None runs until stopped. Set for a service in the background.	`None`
`ready`	`Callable[[LocalService], None] \| None`	Called with the service once it listens.	`None`
`stopping`	`Callable[[str], None] \| None`	Called with what the end of the service waits for, the open requests and the processes of the runs, when it waits for any.	`None`

Raises:

Type	Description
`ServiceRunning`	The local service of the directory runs already.
`RuntimeError`	The tokens file has no token of the user.
`OSError`	The port cannot be bound.

read_service ¶

read_service(root)

The service .simrun/service.json names.

Returns:

Type	Description
`LocalService \| None`	The service, None without a readable file or with a URL which is not the one
`LocalService \| None`	of its port on `127.0.0.1`.

stop_local ¶

stop_local(
    root,
    idle=False,
    stopping=None,
    timeout_s=GRACE_S + STOP_MARGIN_S,
)

Stop the local service of a project directory and wait for its end.

The end of the service cancels its runs, whose processes get worker.GRACE_S.

Parameters:

Name	Type	Description	Default
`root`	`Path`	The project directory.	required
`idle`	`bool`	Stop it only when no run is live and no request is open.	`False`
`stopping`	`Callable[[LocalService], None] \| None`	Called with the service once it stops, before the wait.	`None`
`timeout_s`	`float`	Seconds to wait for its end.	`GRACE_S + STOP_MARGIN_S`

Returns:

Type	Description
`LocalService \| None`	The service which was stopped, None when none runs.

Raises:

Type	Description
`ServiceBusy`	With `idle`, the service has a live run or an open request.
`RuntimeError`	The service refused to stop or did not end in time.

ensure_local ¶

ensure_local(root, timeout_s=10.0, warn=None)

The local service of a project directory, started in the background if none runs.

A service runs when the pid of service.json is alive, the server answers the instance of the file and GET /me answers. The start runs under an exclusive lock of .simrun/start.lock, so concurrent calls start one service; a start refused while an old service still ends is repeated once it has ended.

A service whose environment (python, simrun, task types) differs from the one of this process runs code this command does not: one in the background without a live run and without an open request is stopped and started again; else it is used with a warning.

Parameters:

Name	Type	Description	Default
`root`	`Path`	The project directory.	required
`timeout_s`	`float`	Seconds to wait for a started service.	`10.0`
`warn`	`Callable[[str], None] \| None`	Called with a warning for the user, by default logged.	`None`

Returns:

Type	Description
`LocalService`	The running service.

Raises:

Type	Description
`RuntimeError`	The service did not start in time or exited; the message has the end of `.simrun/service.log`.

local¶

LOCAL_DIR module-attribute ¶

IDLE_EXIT_S module-attribute ¶

GRACEFUL_SHUTDOWN_S module-attribute ¶

PACKAGE_WEB module-attribute ¶

CHECKOUT module-attribute ¶

INSTANCE_PATH module-attribute ¶

STOP_PATH module-attribute ¶

STOP_MARGIN_S module-attribute ¶

EXIT_RUNNING module-attribute ¶

ServiceRunning ¶

ServiceBusy ¶

LocalService dataclass ¶

environment ¶

web_dir ¶

local_dir ¶

local_settings ¶

serve_local ¶

read_service ¶

stop_local ¶

ensure_local ¶

LOCAL_DIR `module-attribute` ¶

IDLE_EXIT_S `module-attribute` ¶

GRACEFUL_SHUTDOWN_S `module-attribute` ¶

PACKAGE_WEB `module-attribute` ¶

CHECKOUT `module-attribute` ¶

INSTANCE_PATH `module-attribute` ¶

STOP_PATH `module-attribute` ¶

STOP_MARGIN_S `module-attribute` ¶

EXIT_RUNNING `module-attribute` ¶

LocalService `dataclass` ¶