Session and progress tracking

Create a MadMatcherSession to turn on the live progress dashboard; every operation that follows reports to it automatically.

class madmatcher_pro.MadMatcherSession(*, dashboard=True, port=4050, open_browser=False, host='127.0.0.1')

Bases: object

Always-on progress tracking for MadMatcher operations, in the style of SparkSession.

Creating a session launches (or joins) a small web dashboard and makes the session active, so every blocking or matching operation that runs afterward shows up on it automatically – you do not pass a dashboard flag to each call.

Build one with the fluent builder, chaining any of the setters before getOrCreate():

from madmatcher_pro import MadMatcherSession

with MadMatcherSession.builder.port(4050).open_browser(True).getOrCreate() as session:
    print(session.url)   # -> http://127.0.0.1:4050
    # run blocking / matching here; each step appears on the dashboard
# leaving the ``with`` block stops the session and shuts the dashboard down

or construct it directly with the same options, e.g. MadMatcherSession(port=4050). Use it as a context manager (above) or call stop() yourself; stop restores any session it displaced and shuts the dashboard down once no other session needs it.

Parameters:

  • dashboard (bool) – Turn tracking on. Default True; False makes an inert session that launches no dashboard. The MADMATCHER_DASHBOARD=0 environment variable forces tracking off everywhere and overrides this.

  • port (int) – Port for the dashboard web server. Default 4050; if it is busy the server scans upward for the next free port.

  • open_browser (bool) – Open the dashboard in your browser when it launches. Default False.

  • host (str) – Address the dashboard binds to. Default "127.0.0.1" (reachable only from this machine). Set "0.0.0.0" to reach it from another machine – the dashboard has no built-in authentication, so restrict access at the network layer.

property url: str | None

The dashboard URL once launched, else None.

flush()

Finish the active plain op now, without stopping the session or its dashboard. A plain (lazy) op’s card is only completed when a later op supersedes it or the session stops, so the LAST op sits at “running” / 100% until then. Call this once the work is done (e.g. before a pause to view the dashboard) to flip that final card to complete. Best-effort and idempotent; the next tracked op would supersede it anyway.

Return type:

None

stop()

Deactivate this session, restoring any session it displaced. The process-wide dashboard server is shut down only when no live session remains to serve (so an inner session’s stop never tears down an outer session’s server). Idempotent.

Return type:

None

class Builder

Bases: object

Fluent builder for MadMatcherSession (à la SparkSession.builder).

Get one from MadMatcherSession.builder, chain any of dashboard(), port(), open_browser(), and host(), then call getOrCreate(). See MadMatcherSession for what each option means.

dashboard(on=True)

Set whether the session tracks on the dashboard (default True).

Parameters:

on (bool)

Return type:

Builder

port(port)

Set the dashboard port (default 4050; scans upward if busy).

Parameters:

port (int)

Return type:

Builder

open_browser(on=True)

Set whether to open the dashboard in a browser on launch (default False).

Parameters:

on (bool)

Return type:

Builder

host(host)

Set the address the dashboard binds to (default "127.0.0.1"; use "0.0.0.0" for access from another machine).

Parameters:

host (str)

Return type:

Builder

getOrCreate()

Return the active session if one exists, else create, launch and activate a new one (Spark’s getOrCreate semantics). Serialized so two racing first calls share one session.

Return type:

MadMatcherSession