pynq.utils Module

The pynq.utils module contains functions and classes that are used for delivery and testing of PYNQ and packages that depend on PYNQ. For delivery it includes the setuptools function for managing the download of bitstreams from link files at install time and the enumeration and copying of notebooks. For testing it provides a function for evaluating a notebook and getting the results.

exception pynq.utils.DownloadedFileChecksumError

This exception is raised when a downloaded file has an incorrect checksum.

class pynq.utils.NotebookResult(nb)

Class representing the result of executing a notebook

Contains members with the form _[0-9]* with the output object for each cell or None if the cell did not return an object.

The raw outputs are available in the outputs attribute. See the Jupyter documentation for details on the format of the dictionary

exception pynq.utils.OverlayNotFoundError

This exception is raised when an overlay for the target device could not be located.

class pynq.utils.ReprDict(*args, rootname='root', expanded=False, **kwargs)

Subclass of the built-in dict that will display using the Jupyterlab JSON repr.

The class is recursive in that any entries that are also dictionaries will be converted to ReprDict objects when returned.

class pynq.utils.build_py(dist, **kw)

Overload the standard setuptools ‘build_py’ command to also call the command ‘download_overlays’.

run()

Build modules, packages, and copy data files to build directory

pynq.utils.deliver_notebooks(device_name, src_path, dst_path, name, folder=False, overlays_res_lookup=True)

Deliver notebooks to target destination path.

If a overlay_res.ext.link file or a overlay_res.ext.d folders is found, then overlay_res.ext (where .ext represents a generic file extension) is considered to be a file that need to be resolved dynamically, based on device_name. The following resolution strategy is applied when inspecting src_path:

1. If an overlay_res.ext file is found, prioritize that file and do not perform any resolution.
2. In case step 1 fails, if a overlay_res.ext.d folder is found, try to retrieve the right overlau_res.ext file from there. The files in this folder are expected to contain the device name as a string, before the file extension .ext. Format should be overlay_res.device_name.ext.
3. In case step 2 fails, if there is an overlay_res.ext.link file, attempt to download the correct file from the provided url, assumed that a valid entry for device_name is available in the .link json file.
4. If all steps fail, notebooks that are in the same folder as overlay_res.ext are not delivered, and the user is warned.

For simplicity, it is assumed that .link files and .d folders are located next to the notebooks that use the associated resource. Folders that does not contain notebooks will not be inspected.

In case no .link or overlay_res.d files are found, notebooks are simply copied as is, no resolution is performed. It is assumed that for this scenario, overlays are delivered somewhere else.

Parameters:

• device_name (str) – The target device name to use when doing resolution of .link files and .d folders. If an overlay_res.ext file is also found, no resolution will be done and device_name will be ignored, as it is assumed that the overlay_res.ext file is prioritized and no automatic resolution is expected
• src_path (str) – The source path to copy from
• dst_path (str) – The destination path to copy to
• name (str) – The name of the notebooks module
• folder (bool) – Indicates whether to use name as target folder to copy notebooks, inside dst_path. Notebooks will be copied directly in dst_path if False.
• overlays_res_lookup (bool) – Dynamic resolution of .link files and .d folders is disabled if `False.

pynq.utils.download_overlays(path, download_all=False, fail_at_lookup=False, fail_at_device_detection=False, cleanup=False)

Download overlays for detected devices in destination path.

Resolve overlay_res.ext files from overlay_res.ext.link json files. Downloaded overlay_res.ext files are put in a overlay_res.ext.d directory, with the device name added to their filename, as overlay_res.device_name.ext. If the detected device is only one and is an edge device, target file is resolved directly to overlay_res.ext. If target overlay_res.ext already exists, resolution is skipped.

Parameters:

• path (str) – The path to inspect for overlays installation
• download_all (bool) – Causes all overlays to be downloaded from .link files, regardless of the detected devices.
• fail_at_lookup (bool) – Determines whether the function should raise an exception in case overlay lookup fails.
• fail_at_device_detection (bool) – Determines whether the function should raise an exception in case no device is detected.
• cleanup (bool) – Dictates whether .link files need to be deleted after resolution. If True, all .link files are removed as last step.

pynq.utils.get_logger(level=20, force_lvl=False)

Returns an instance of the pynq.utils logger.

Parameters:

• level (str or int) – String or integer constant representing the logging level following Python’s logging standard levels. By default, the level is not updated if the current level is higher, unless force_lvl is set to True.
• force_lvl (bool) – If True, sets the logging level to level in any case.

pynq.utils.run_notebook(notebook, root_path='.', timeout=30, prerun=None)

Run a notebook in Jupyter

This function will copy all of the files in root_path to a temporary directory, run the notebook and then return a NotebookResult object containing the outputs for each cell.

The notebook is run in a separate process and only objects that are serializable will be returned in their entirety, otherwise the string representation will be returned instead.

Parameters:

• notebook (str) – The notebook to run relative to root_path
• root_path (str) – The root notebook folder (default “.”)
• timeout (int) – Length of time to run the notebook in seconds (default 30)
• prerun (function) – Function to run prior to starting the notebook, takes the temporary copy of root_path as a parameter