Result API
You can get a list of Result object from the ResultsManager using a named-results name or a reference. What you get back is the results from each csvpath executed in a single run. Once you have the list of results there is a lot of information available to you, most of which is also available from the result files in each csvpath instance's folder.
Get a list of named-results
Listing all named-results is not the same as listing runs. Each named-result is one directory in a flat list that is equal to the list of named-paths groups that have been run at least one time. Each name on the list may have had any number of runs.
results:list[str] = CsvPaths().results_manager.list_named_results()Get the results from a single run
Each run creates a set of one or more Result objects. Each Result object represents one csvpath in the named-paths group that was run against a single file. You can get the run's Result objects with:
results:list[Result] = CsvPaths().results_manager.get_named_results("orders")The results returned are from the most recent run. Alternatively, you can get a specific run's results using a results reference:
results:list[Result] = CsvPaths().results_manager.get_named_results("$orders.results.2025-03-01_10:3")")In this case, we are pulling results for the orders run on March 1st, 2025 at or after 10:30 AM UTC. If there are multiple orders runs on March 1st, 2025 at or after 10:30 AM UTC the reference is not specific enough so the method returns None. If that were the case we would need to either use :first, :last, or an index pointer like :3, or we could use a more specific timestamp.
Get a specific csvpath instance from a run
To get a specific instance csvpath results you can use a reference like:
result = paths.results_manager.get_specific_named_result("$food#candy check.results.:0")Or like:
result = paths.results_manager.get_specific_named_result("$food.results.2025.candy check")The more common syntax is as in the latter example: $named-results-name.results.run_dir-match.instance-match where:
named-results-name is, as it sounds, any named-results name
resultsis the datatype pointing to the published results arearun_dir-match is a path or timestamp match to the run's folder. This value can have pointers. In the example we're just matching the first part of the run_dir name,
2025, and taking the first run found.instance-match is the identity of the csvpath that created the results you want, or an index pointer
Equally, but less commonly, we can use the # character to add the instance name to the named-results name. In the first example we have food#candy check, indicating the food named-results's candy check instance, and the pointer :0 indicating which run.
Access the manifest of an individual csvpath within a run
Runs have manifests containing metadata about the run. Each csvpath instance within a run has its own manifest with metadata specific to that particular csvpath within the context of the run.
result = paths.results_manager.get_named_results("$food.files.:today:last.candy check")
mani = result.manifestA few more important Result properties
result = paths.results_manager.get_named_results("$food.files.:today:last.candy check")
#
# the identity of a csvpath is set in its external comments. if no identity is set
# we address it by its index within the named-paths group
#
result.identity_or_index
result.errors
result.variables
result.metadata
result.printoutsErrors, variables, and metadata are dicts[str, Any]. Printouts are list[list[str]].
A csvpath's identity
The identity of a csvpath is used in several places. You have seen how we use the identity in references. Identity is also important in the built-in error messages that CsvPath Validation Language emits when data is invalid or there is a mistake in the csvpath statement. You set a csvpath's identity in an external comment. An external comment is one that is outside the scanning and match instructions. They look like this:
~
this is an external comment
ID: this is my identity
~
$[*][ yes() ~ this is an internal comment ~ ]You can set an identity using a comment metadata field — i.e. a word followed by a colon — where the metadata name is any of: ID, Id, id, NAME, Name, name. If no identity is found CsvPath Framework knows the csvpath by its index within its named-paths group.
Last updated