profile

---

Use this shared, callable ProfileController instance to create sessions or collect across notebook cells. Import profile directly from linescope. profiler is another name for the same object: profiler is profile is True. Both names share the session started with start() and its result.

callable instance linescope.profile(**options)[source]

Create a context-managed session using explicit Config options.

Calling the controller creates a fresh Session without replacing the session retained by start(). The package's profile and profiler names refer to the same callable controller instance.

Parameters	**options Configuration fields overriding project defaults for this session. Collection begins when entering the context or calling start.
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.
Returns	Session A new session in the created state.

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 profile, profiler

>>> profiler is profile
True
>>> with profile(
...     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.