API

Run pyperformance and pyperf benchmarks and store results in SQL.

run(runner_arguments, *, db=(), target=(), config=None, name=None)

Run benchmarks and write the result to every selected database.

Targets and the run name template are checked before any benchmark starts; the length of the final name and a : that comes from the result are checked only after the benchmarks, and that error keeps the result file in its result_path attribute. A failed write does not raise: report.write.succeeded is False and the result file stays on disk.

Parameters:

Name	Type	Description	Default
runner_arguments	Sequence[str]	Arguments of pyperformance run, or a pyperf script path followed by its arguments.	required
db	Sequence[str]	SQLAlchemy URLs of target databases, like --db.	()
target	Sequence[str]	Target names from takt.toml, like --target.	()
config	str | PathLike[str] | None	Path to takt.toml instead of ./takt.toml.	None
name	str | None	Run name or name template, like --name.	None

Returns:

Type	Description
ImportReport	The import report of the produced result file.

Raises:

Type	Description
UsageError	If the configuration, targets or run name are invalid, -o/--output has no value, the folder of the result file is missing or not writable, or a string is passed instead of a sequence of strings.
ExecutionError	If the benchmarks fail or the result file cannot be read.
KeyboardInterrupt	On Ctrl+C; if the benchmarks had already written a new result file, or takt was writing the result to the databases, its __cause__ has that file in the result_path attribute, and during the write also the run name in name.

import_results(path, *, db=(), target=(), config=None, name=None)

Write a ready pyperf or pyperformance result to every database.

A failed write does not raise: report.write.succeeded is False.

Parameters:

Name	Type	Description	Default
path	str | PathLike[str]	Result file, .json or .json.gz; it becomes the Path in report.result_path unchanged.	required
db	Sequence[str]	SQLAlchemy URLs of target databases, like --db.	()
target	Sequence[str]	Target names from takt.toml, like --target.	()
config	str | PathLike[str] | None	Path to takt.toml instead of ./takt.toml.	None
name	str | None	Run name or name template, like --name.	None

Returns:

Type	Description
ImportReport	The import report of the result file.

Raises:

Type	Description
UsageError	If the configuration, targets or run name are invalid, or a string is passed instead of a sequence of strings.
ExecutionError	If the result file cannot be read.
KeyboardInterrupt	On Ctrl+C; during the database write its __cause__ has the result file in the result_path attribute and the run name in name.

compare(operands, *, db=(), target=(), config=None)

Compare two or more results against the first one.

Stored runs are read from the first configured target; when every operand is a file, db, target, config, TAKT_DB and takt.toml are not read at all.

Parameters:

Name	Type	Description	Default
operands	Sequence[str | PathLike[str]]	Result files, run names, name:N, name:prefix or hash prefixes; the first one is the base, and a path-like operand is a file whose label is its string form.	required
db	Sequence[str]	SQLAlchemy URLs of target databases, like --db.	()
target	Sequence[str]	Target names from takt.toml, like --target.	()
config	str | PathLike[str] | None	Path to takt.toml instead of ./takt.toml.	None

Returns:

Type	Description
CompareTable	The compare table.

Raises:

Type	Description
UsageError	If fewer than two operands are given, a stored run is requested without a target or with an invalid configuration, or a string is passed instead of a sequence of strings.
ExecutionError	If an operand is not found or ambiguous, a result file cannot be read, the database cannot be connected to or read, has no takt results or is a missing SQLite file, or the suites share no benchmark.