Service layer#

from DMDO.service import Client, start_service, serve, run_worker, RemoteExecutor, TaskQueue

Client#

class DMDO.service.Client(url, token=None, timeout=60.0)#

Bases: object

Connect to a DMDO service started with dmdo serve (or DMDO.service.serve()).

client = Client("http://localhost:8400", token="...")
session = client.create_session(setup_file="problem.yaml", mdo_name="wing",
                                blackboxes={"A1": "my_pkg.aero:A1"}, sweep="jacobi")
for event in session.run().events(): ...
Parameters:
  • url (str)

  • token (str | None)

  • timeout (float)

create_session(setup=None, setup_file=None, mdo_name='MDO', blackboxes=None, **options)#

Create a session from a problem definition dict (setup) or a YAML path readable by the service.

blackboxes maps names to "module:attr" import paths resolved by the service (and its workers). options: mode, sweep, executor ("inprocess", "process" or "remote"), placement ({subproblem index: worker tag}, implies executor="remote") and max_workers.

Parameters:
  • setup (Mapping[str, Any] | None)

  • setup_file (str | None)

  • mdo_name (str)

  • blackboxes (Mapping[str, str] | None)

Return type:

RemoteSession

class DMDO.service.RemoteSession(http, session_id)#

Bases: object

A session living in a DMDO service; mirrors the run/step/result part of DMDO.Session.

Parameters:
  • http (_Http)

  • session_id (str)

run(wait=False, poll=0.5)#

Start running to the end in the service; with wait block until done and return the result.

Parameters:
  • wait (bool)

  • poll (float)

Return type:

Dict[str, Any]

step()#

Run one outer iteration; the iteration record, or None when the run is over.

Return type:

Dict[str, Any] | None

events(since=0)#

Server-sent events of the run (iteration_end records, then run_end/run_failed).

Parameters:

since (int)

Return type:

Iterator[Dict[str, Any]]

exception DMDO.service.ServiceError(status, message)#

Bases: RuntimeError

The service answered with an error status.

Parameters:
  • status (int)

  • message (str)

Return type:

None

Service#

DMDO.service.serve(host='127.0.0.1', port=8400, root_dir='dmdo_service', token=None, lease_seconds=None, allow_insecure=False)#

Run the service in the foreground until interrupted.

Parameters:
  • host (str)

  • port (int)

  • root_dir (str)

  • token (str | None)

  • lease_seconds (float | None)

  • allow_insecure (bool)

Return type:

None

DMDO.service.start_service(host='127.0.0.1', port=0, root_dir='dmdo_service', token=None, lease_seconds=None, allow_insecure=False)#

Start the service in a background thread (port=0: any free port); returns a handle with url.

Parameters:
  • host (str)

  • port (int)

  • root_dir (str)

  • token (str | None)

  • lease_seconds (float | None)

  • allow_insecure (bool)

Return type:

ServiceHandle

class DMDO.service.ServiceHandle(service, server, thread)#

Bases: object

A service running in a background thread (see start_service()).

Parameters:
  • service (DMDOService)

  • server (ThreadingHTTPServer)

  • thread (Thread)

class DMDO.service.DMDOService(root_dir='dmdo_service', token=None, lease_seconds=None)#

Bases: object

Holds the sessions and the job queue; transport-independent (the HTTP handler below calls it).

Parameters:
  • root_dir (str) – each session works in <root_dir>/<session id>.

  • token (str | None) – shared secret clients and workers must send; None disables authentication.

  • lease_seconds (float | None) – re-offer a claimed job to another worker after this long without a result (None: never).

Workers and remote execution#

DMDO.service.run_worker(url, tags=(), token=None, name=None, max_jobs=None, poll_wait=20.0, stop_event=None)#

Serve jobs until stop_event is set or max_jobs jobs were run; returns the number of jobs run.

Parameters:
  • url (str)

  • tags (Iterable[str])

  • token (str | None)

  • name (str | None)

  • max_jobs (int | None)

  • poll_wait (float)

  • stop_event (Event | None)

Return type:

int

class DMDO.service.RemoteExecutor(queue, placement=None, timeout=None, max_workers=None)#

Bases: object

Executor whose tasks run on remote workers connected to a TaskQueue.

Parameters:
  • queue (TaskQueue) – the queue workers claim jobs from (the service’s queue).

  • placement (Mapping[Any, str] | None) – {subproblem index: worker tag}; tasks of other subproblems go to any worker.

  • timeout (float | None) – seconds to wait for one map call (None: no limit).

  • max_workers (int | None)

class DMDO.service.TaskQueue(lease_seconds=None)#

Bases: object

Thread-safe job queue between executors (producers) and HTTP workers (consumers).

Parameters:

lease_seconds (float | None) – a claimed job whose result has not arrived after this many seconds is offered again (a worker that died mid-job); None disables re-delivery.

wait(job_ids, timeout=None)#

Block until every job in job_ids has a result; return (ok, payload) per job, in order.

Parameters:
  • job_ids (Sequence[str])

  • timeout (float | None)

Return type:

List[Tuple[bool, bytes]]

claim(worker, tags=(), timeout=0.0)#

Take the oldest job this worker may run: untagged jobs, or jobs tagged with one of tags.

Parameters:
  • worker (str)

  • tags (Iterable[str])

  • timeout (float)

Return type:

Tuple[str, bytes] | None

complete(job_id, ok, payload)#

Store a job’s result; False if the job is unknown (cancelled, or already completed by another worker).

Parameters:
  • job_id (str)

  • ok (bool)

  • payload (bytes)

Return type:

bool

exception DMDO.service.RemoteTaskError#

Bases: RuntimeError

A worker reported an exception while running a job.