Utilities
#########

Using Python's print function in SystemVerilog
==============================================

The usual way to write output in SystemVerilog is using ``$display`` while in Python one
would use ``print``. Since these methods use different buffers, mixing them can
lead to output order issues. To resolve this, PyStim modules can use the
:func:`pystim_pkg::print` function which writes to Python's ``sys.stdout`` for consistency.

.. code-block:: systemverilog

    py::print(py::str_("hello world")); // hello world
    py::print(py::str_("Pi value = "), py::float_(3.14159)); 
    py::print(some_prealocated_py_object); // prints the object

Evaluating Python expressions from strings and files
====================================================

PyStim provides the ``eval``, ``exec`` and ``eval_file`` functions to evaluate
Python expressions and statements. The following example illustrates how they
can be used.

.. code-block:: systemverilog

    ...

    // Evaluate in scope of main module
    py::dict global_scope = py_dict::create_empty();
    py::dict local_scope = py_dict::create_empty();

    // Evaluate an isolated expression
    int result = py::eval("2 + 10", global_scope, local_scope).cast_int();

    // Evaluate a sequence of statements
    py::exec("print('Hello')\nprint('world!');",
        global_scope);

    // Evaluate the statements in an separate Python file on disk
    py::eval_file("script.py", scope);


In PyStim, the difference between `exec`` and `eval` mirrors the difference between Python’s built-in `exec()` and `eval()` functions.

Here's a breakdown: