ProfileController

---

Create a controller when you need an independent owner for explicit profiling sessions. The shared profile and profiler entry points are instances of this class. Import ProfileController directly from linescope.

class linescope.api.ProfileController()[source]

Offer callable contexts and explicit notebook-wide start/stop ergonomics.

The package exports one shared instance as profile and profiler. These names refer to the same object and retain the same explicit session. Construct this class directly when an independent controller is needed.

Attributes

result : ProfileResult Complete normalized result of the most recent explicit session, including source snapshots, measurements, the run tree, capabilities, and diagnostics. Read-only access to the same object as session.result; finalized after stop completes.

See Also

Config

Configure a single profiling session.

ProfileResult

Combine portable source snapshots with backend-independent run data.

Session

Collect one source profiling run and render portable HTML.

Example

>>> from linescope import ProfileController

>>> controller = ProfileController()
>>> with controller(
...     backend="trace", display="none", notebooks=False, spark=False
... ) as session:
...     total = sum(range(10))

>>> (total, str(session.state), str(session.result.backend))
(45, 'stopped', 'trace')

Methods

start	Start a new session using explicit Config options.
stop	Stop the current explicit session without returning its result.
save	Save the current session without displaying it.
show	Display the current session.

method start(**options)[source]

Start a new session using explicit Config options.

Example

>>> from linescope import ProfileController

>>> controller = ProfileController()
>>> session = controller.start(
...     backend="trace", display="none", notebooks=False, spark=False
... )
>>> total = sum(range(10))
>>> controller.stop()
>>> result = controller.result
>>> (total, str(session.state), str(result.backend))
(45, 'stopped', 'trace')

Parameters	**options Configuration fields for the new session. Use display="none" to collect without displaying a report automatically at stop.
Returns	Session The running session retained by this controller.

method stop()[source]

Stop the current explicit session without returning its result.

Instrumentation is restored before any configured report display. Retrieve the completed result through profile.result or session.result. Repeated calls do nothing without displaying again.

method save(path)[source]

Save the current session without displaying it.

Parameters	path : str | Path Destination HTML filename. Missing parent directories are created. Stop collection first when saving a finalized sampling result.
Returns	Path Absolute path of the self-contained report.

method show(inline=None)[source]

Display the current session.

Reports display inside notebook cells automatically and open a browser elsewhere. Use inline to choose the destination for this report. Return None; retrieve the HTML string through session.html(). Stop collection first when displaying a finalized sampling result.

Parameters

inline : bool | None, default=None Choose the destination for this report. None detects the environment; True requires a notebook, and False opens a browser.