Results API

class adaptystanalyser.results.Analysable(name: str, modules: list[Module], entity=None)

Bases: object

A class describing an element of a system graph that one or more modules can be attached to for analysis.

property entity

Return the entity to which the component belongs.

get_module(name: str) → Module

Return a Module object attached to the component by name. If it doesn’t exist, None is returned.

Parameters:

name (str) – Module name.

get_modules_iterable()

Return an iterable of modules attached to the component.

property name

Return the name of the component.

class adaptystanalyser.results.Edge(start, end, name: str, modules: list[Module] = [])

Bases: Analysable

A class describing a directed connection between two nodes in a system graph.

property end

Return the Node object at which the edge ends.

get_export_name()

Return the graph-unique export name of the edge.

property start

Return the Node object at which the edge starts.

class adaptystanalyser.results.Entity(name: str)

Bases: object

A class describing an entity in a system graph.

add_node(node: Node)

Add a node to the entity.

Parameters:

node (Node) – Node to add.

Raises:

ValueError – When a node with the same name already exists.

get_exit_code() → int

Return the exit code of the entity.

get_hex_colour()

Return the colour assigned to the entity in hexadecimal form.

get_node(name: str) → Node

Return a node in the entity by name.

Parameters:

name (str) – Name of the node.

get_nodes_iterable()

Return an iterable of nodes in the entity.

property name

Return the name of the entity.

remove_node(name: str) → bool

Remove a node from the entity by name. The return value is a boolean indicating whether the node has been removed.

Parameters:

name (str) – Name of the node to remove.

set_exit_code(exit_code: int)

Set the exit code of the entity.

Parameters:

exit_code (int) – Entity exit code.

class adaptystanalyser.results.Identifier(result: Path)

Bases: object

A class representing a performance analysis session identifier/metadata.

property day

Return the day on which the performance analysis session started.

get_detailed_path(entity=None, analysable=None, module=None)

Get a path to a specific component of the performance analysis session.

Parameters:

• entity – Entity object or entity name.

• analysable – Analysable object or name of an analysable.

• module – Module object or module name.

property hour

Return the hour at which the performance analysis session started.

property label

Return the label of the performance analysis session.

property minute

Return the minute at which the performance analysis session started.

property month

Return the month in which the performance analysis session started.

property path

Return the resolved path to the performance analysis session.

property second

Return the second at which the performance analysis session started.

property value

Return the name of the performance analysis session directory.

property year

Return the year in which the performance analysis session started.

class adaptystanalyser.results.Module

Bases: ABC

An abstract base class for an Adaptyst Analyser module.

get_analysable()

Return the Analysable object to which the module belongs. If it isn’t set, None is returned.

abstractmethod get_name()

Return the name of the module.

get_session()

Return the Session object to which the module belongs. If it isn’t set, None is returned.

get_version_used() → list[int]

Return the version code of the module that produced the results. If it’s not set, None is returned.

See https://adaptyst.web.cern.ch/docs/adaptyst/module-development for details of module versioning on the Adaptyst and Adaptyst Analyser side.

is_loaded()

Return whether the module data have been loaded.

load()

Load module data if it has not been loaded yet.

Raises:

RuntimeError – When no Analysable or Session object has been assigned to the module.

needs_loading()

Decorate a method to call Module.load() before executing the method.

Parameters:

method (callable) – Module method to decorate.

abstractmethod process_post_request(data)

Process a POST request addressed to the module. The return value must be either a (<response data>, <HTTP status code>) tuple or just response data (the 200 HTTP status code is assumed then).

Parameters:

data – Data supplied in the POST request in form of a dictionary storing form fields (e.g. field xyz=abc is stored as data['xyz'] = 'abc'.

set_analysable(analysable)

Set an Analysable object to which the module belongs.

Parameters:

analysable (Analysable) – Owning Analysable object.

set_session(session)

Set a Session object to which the module belongs.

Parameters:

session (Session) – Owning Session object.

set_version_used(ver_code: list[int])

Set the version code of the module that produced the results.

See https://adaptyst.web.cern.ch/docs/adaptyst/module-development for details of module versioning on the Adaptyst and Adaptyst Analyser side.

Parameters:

ver_code (list[int]) – Module version code.

class adaptystanalyser.results.Node(name: str, entity, modules: list[Module] = [])

Bases: Analysable

A class describing a system graph node.

add_out_edge(edge: Edge)

Add an outgoing edge to the node.

Parameters:

edge (Edge) – Edge to add.

Raises:

ValueError – When an edge with the same name already exists.

get_export_name()

Return the graph-unique export name of the node.

get_out_edge(name: str) → Edge

Return an outgoing edge by name. If it doesn’t exist, None is returned.

Parameters:

name (str) – Name of the edge.

get_out_edges_iterable()

Return an iterable of outgoing edges.

remove_out_edge(name: str) → bool

Remove an outgoing edge from the node by name. The return value is a boolean indicating whether the edge has been removed.

Parameters:

name (str) – Name of the edge to remove.

class adaptystanalyser.results.Session(identifier: Identifier | Path | str)

Bases: object

A class describing a specific performance analysis session.

get_all_sessions() → list

Get the identifiers of all performance analysis sessions stored in a given directory. The return value is a list of Identifier objects.

Parameters:

path_str (str) – String path to a directory.

get_entities_iterable()

Return an iterable of entities in the performance analysis session.

get_entity(name: str) → Entity

Return an entity in the performance analysis session by name. If it doesn’t exist, None is returned.

Parameters:

name (str) – Name of the entity.

get_system_graph_json(json_type: str = 'sigma.js')

Return the performance analysis system graph as JSON data.

Parameters:

json_type (str) – Requested graph JSON format. Only “sigma.js” is supported at the moment.

Raises:

ValueError – When the requested JSON format is unsupported.

get_url(compact: bool = False, hide_header: bool = False, hide_footer: bool = False)

Get the URL suffix used to open the performance analysis session in an Adaptyst Analyser web server.

Parameters:

• compact (bool) – Whether to use the compact mode.

• hide_header (bool) – Whether to hide the header in compact mode.

• hide_footer (bool) – Whether to hide the footer in compact mode.

property identifier

Return the identifier of the performance analysis session.

process_post_request(data, entity, analysable, module)

Process a POST request addressed to a module in the session and return the response produced by the module.

Parameters:

• data – Data supplied in the POST request in form of a dictionary storing form fields (e.g. field xyz=abc is stored as data['xyz'] = 'abc').

• entity (str) – Name of the target entity.

• analysable (str) – Name of the target analysable.

• module (str) – Name of the target module.

Raises:

• NotImplementedError – When the request targets no entity.

• FileNotFoundError – When the target entity, analysable, or module does not exist.

class adaptystanalyser.results.Window

Bases: ABC

An abstract class for a window/tab shown at a website from an Adaptyst Analyser web server.

abstractmethod get_analysable() → Analysable

Return the Analysable object associated with the window.

get_arrgmt_json(session: Session = None, return_session_storage_paths: bool = False)

Return the JSON data describing a window arrangement that can be saved by calling adaptystanalyser.arrangements.Context.save(). This is a low-level method, you can also use Window.save_arrgmt().

Optionally, if return_session_storage_paths is set to True, a set of parent paths of sessions used by the window(s) is also returned (the return value is a (<data>, <paths>) tuple then).

Parameters:

• windows – Window or list of windows to serialise. If you provide a single window, a single window arrangement is generated (the dependencies of the provided window are obtained and added automatically). Otherwise, a window arrangement is produced, where you must take care of including all dependencies of all windows there.

• session (Session) – Session associated with the arrangement. It can be None.

• return_session_storage_paths (bool) – Whether to also return the parent paths of sessions used by the windows.

Raises:

ValueError – When no session can be determined for a window arrangement or one or more window dependencies are missing.

get_arrgmt_url(compact: bool = True, hide_header: bool = True, hide_footer: bool = True)

Get the URL suffix used to open a saved window arrangement in an Adaptyst Analyser web server.

Parameters:

• identifier (int) – Identifier of the saved arrangement.

• compact (bool) – Whether to use the compact mode.

• hide_header (bool) – Whether to hide the header in compact mode.

• hide_footer (bool) – Whether to hide the footer in compact mode.

abstractmethod get_constr_args() → list

Return the arguments required to construct the window.

get_custom_title()

Return the custom title of the window. If it’s not set, None is returned.

abstractmethod get_data()

Return the data stored by the window.

abstractmethod get_dependencies() → list

Return the Window objects on which this window depends.

get_id()

Return the unique identifier of the window.

An identifier is generated from the session and window type if one has not been assigned.

abstractmethod get_init_data()

Return the initialisation data required by the window.

abstractmethod get_module() → Module

Return the Module object associated with the window.

abstractmethod get_session() → Session

Return the performance analysis session associated with the window.

abstractmethod get_type() → str

Return the type identifier of the window. On the client side in JavaScript, this must match the return value of getType() in the corresponding module class and be recognised by getWindowClass().

is_collapsed()

Return whether the window is collapsed.

save_arrgmt(name: str = None, session: Session = None, db_url: str = None, db_pass: str = None)

Save an arrangement in the database.

If no name is supplied, a tuple (<arrangement identifier>, <arrangement update token>, <random human-friendly arrangement name>) is returned. Otherwise, the return value is a tuple (<arrangement identifier>, <arrangement update token>).

Parameters:

• windows – Window or list of windows to save. If you provide a single window, a single window arrangement is generated (the dependencies of the provided window are obtained and added automatically). Otherwise, a window arrangement is produced, where you must take care of including all dependencies of all windows there.

• name (str) – Name to assign to the arrangement. It can be None, then a random human-friendly name is generated.

• session (Session) – Session associated with the arrangement.

• db_url (str) – Database URL to use. Use the SQLAlchemy syntax. It can be None, a default SQLite database is used then.

• db_pass (str) – Database password to use. It can be None.

Raises:

NotImplementedError – When the windows refer to sessions stored in more than one parent directory.

set_collapsed(collapsed: bool)

Set whether the window is collapsed.

Parameters:

collapsed (bool) – Whether the window is collapsed.

set_custom_title(title: str)

Set a custom title for the window.

Parameters:

title (str) – Title to assign to the window.

set_id(identifier)

Set the unique identifier of the window.

Parameters:

identifier – Identifier to assign to the window.

Raises:

ValueError – When the identifier is assigned to another Window instance.

set_x(x: float)

Set the horizontal position of the window in pixels.

Parameters:

x (float) – Horizontal position.

set_y(y: float)

Set the vertical position of the window in pixels.

Parameters:

y (float) – Vertical position.

to_dict(x=None, y=None, collapsed=None)

Return a dictionary representation of the window.

x- and y-coordinate arguments are used only when the corresponding values have not been assigned to the window elsewhere. On the other hand, if an explicit “collapsed” argument is set, it always overrides whatever collapsed state has been assigned before.

Parameters:

• x – Fallback horizontal position of the window in pixels.

• y – Fallback vertical position of the window in pixels.

• collapsed (bool) – Explicit collapsed state of the window overriding whatever has been set before.