vunit-python-bridge 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

vunit_python_bridge/__init__.py

@@ -25,10 +25,21 @@ Modules:
 * foreign_application: builds the VHPI application.
 * simulator_hooks: makes NVC and GHDL find the library.
 * runtime: runs inside the simulator's embedded interpreter.
+* file_base: the base directory of ``base_path``, ``set_relative_file_base``.
+
+``set_relative_file_base(directory)``, called in the run script before ``add_package``, sets the
+directory that ``base_path`` of ``python_pkg`` returns, for VHDL to join file names to. The
+environment variable ``VUNIT_PYTHON_BRIDGE_FILE_BASE`` sets it too, and takes precedence.
 """
 
 from pathlib import Path
 
+from .file_base import add_file_base_package
+
+# Public: run scripts use them
+from .file_base import FILE_BASE_VARIABLE as FILE_BASE_VARIABLE
+from .file_base import set_relative_file_base as set_relative_file_base
+
 VHDL_PATH = Path(__file__).parent.resolve() / "hdl" / "src"
 
 # The foreign language interface implementing the package for a simulator. VUnit says which
@@ -73,6 +84,8 @@ def setup(context):
             f"it has no foreign language interface for {simulator_name}"
         )
 
+    add_file_base_package(context)
+
     if interface == "VHPI":
         # Riviera-PRO/Active-HDL, the simulators served by the VHPI application
         context.add_source_files(context.library.name, [VHDL_PATH / "python_pkg_vhpi.vhd"])

vunit_python_bridge/bridge.py

@@ -16,10 +16,12 @@ from pathlib import Path
 from typing import List, NamedTuple, Optional
 
 from .native_library import (
+    LIBRARY_DIR_VARIABLE,
     PACKAGE_PATH,
     PythonBridgeError,
     check_python_build,
     check_windows_64bit_simulator,
+    library_directory,
     prepare_library,
     windows_python_dll,
 )
@@ -51,6 +53,7 @@ class PythonBridge(NamedTuple):
     """
 
     library_file: Path
+    config_file: Path
     vhdl_files: List[Path]
 
 
@@ -88,9 +91,12 @@ def setup(
         )
 
     root = Path(output_path) / "python_bridge"
-    library_file = prepare_library(root, Path(simulator_prefix) if is_fli else None)
+    library_file = _prepare_library(Path(simulator_prefix) if is_fli else None)
     run_script_dir = str(Path.cwd() if run_script_path is None else Path(run_script_path).resolve().parent)
-    _write_if_changed(library_file.parent / CONFIG_FILE_NAME, _config_text(run_script_dir))
+    # The configuration belongs to the project, the library may be shared. The simulator
+    # hooks tell the library where the configuration is.
+    config_file = root / CONFIG_FILE_NAME
+    _write_if_changed(config_file, _config_text(run_script_dir))
 
     # The foreign attribute string of an entry point: the name of its wrapper in native/fli.c
     # and the library, by absolute path since Questa accepts it, for the FLI; the VHPIDIRECT
@@ -105,6 +111,7 @@ def setup(
 
     return PythonBridge(
         library_file,
+        config_file,
         [
             bridge_package,
             VHDL_SOURCE_PATH / "python_ffi_pkg_bridge.vhd",
@@ -112,6 +119,22 @@ def setup(
     )
 
 
+def _prepare_library(fli_prefix: Optional[Path]) -> Path:
+    """
+    Prepare the library in the library directory, failing with a pointer to the variable
+    selecting another one when it cannot be written, e.g. a read-only home directory.
+    """
+    directory = library_directory()
+    try:
+        return prepare_library(directory, fli_prefix)
+    except OSError as exc:
+        source = f"set by {LIBRARY_DIR_VARIABLE}" if os.environ.get(LIBRARY_DIR_VARIABLE) else "the default"
+        raise PythonBridgeError(
+            f"Cannot build the Python bridge library in {directory!s} ({source}): {exc}. "
+            f"Set {LIBRARY_DIR_VARIABLE} to a writable directory."
+        ) from exc
+
+
 def _vhpidirect_token(simulator_name, simulator_backend: Optional[str], library_file: Path) -> str:
     """
     The library token of the VHPIDIRECT attributes: the file name the simulator dlopen()s,

vunit_python_bridge/file_base.py

@@ -0,0 +1,128 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this file,
+# You can obtain one at http://mozilla.org/MPL/2.0/.
+#
+# Copyright (c) 2014-2026, Lars Asplund lars.anders.asplund@gmail.com
+
+"""
+The base directory that ``base_path`` of ``python_pkg`` returns: set by ``set_relative_file_base``
+in the run script or by the environment variable ``VUNIT_PYTHON_BRIDGE_FILE_BASE``, and given to
+VHDL in a generated package.
+"""
+
+import logging
+import os
+from pathlib import Path
+
+from .bridge import _write_if_changed
+
+# Name of the generated VHDL package holding the base directory, used by python_pkg (base_path)
+FILE_BASE_PACKAGE = "python_file_base_pkg"
+
+# The environment variable setting the directory of base_path when the run script cannot. It takes
+# precedence over set_relative_file_base so that whoever runs a shared run script can override it.
+FILE_BASE_VARIABLE = "VUNIT_PYTHON_BRIDGE_FILE_BASE"
+
+LOGGER = logging.getLogger(__name__)
+
+# The directory set by set_relative_file_base, None when unset, and whether setup has run, after
+# which the directory is in the generated package and can no longer be changed
+_relative_file_base = None
+_setup_done = False
+
+
+def set_relative_file_base(directory):
+    """
+    Set the directory that ``base_path`` of ``python_pkg`` returns, for VHDL to join file names to.
+
+    Call it in the run script before ``vu.add_package("vunit-python-bridge", ...)``. A relative
+    directory is taken from the current working directory at the time of the call.
+
+    :param directory: An existing directory, a ``str`` or a ``Path``.
+    """
+    global _relative_file_base  # pylint: disable=global-statement
+
+    if _setup_done:
+        raise RuntimeError(
+            'set_relative_file_base() must be called before vu.add_package("vunit-python-bridge", ...), '
+            "the package has already been set up"
+        )
+    path = Path(directory).resolve()
+    if not path.is_dir():
+        raise ValueError(f"The relative file base {str(directory)!r} is not an existing directory")
+    _relative_file_base = path
+
+
+def _vhdl_string_literal(text):
+    """
+    A VHDL expression of type string for the UTF-8 bytes of a text, in ASCII: printable characters
+    in a literal with its quotes doubled, other bytes as character'val(n).
+    """
+    parts = []
+    literal = ""
+    for byte in text.encode("utf-8"):
+        if 0x20 <= byte <= 0x7E:
+            literal += '""' if byte == ord('"') else chr(byte)
+        else:
+            if literal:
+                parts.append(f'"{literal}"')
+                literal = ""
+            parts.append(f"character'val({byte})")
+    if literal or not parts:
+        parts.append(f'"{literal}"')
+    if not parts[0].startswith('"'):
+        # A string expression rather than a lone character
+        parts.insert(0, '""')
+    return " & ".join(parts)
+
+
+def _file_base_package_text(directory):
+    """
+    Content of the generated python_file_base_pkg.vhd.
+    """
+    value = "" if directory is None else directory.as_posix()
+    return f"""\
+-- Generated by vunit_python_bridge.setup. Do not edit.
+--
+-- The directory set by the environment variable {FILE_BASE_VARIABLE} or by
+-- vunit_python_bridge.set_relative_file_base() in the run script, empty when neither is set.
+-- base_path of python_pkg returns it.
+package {FILE_BASE_PACKAGE} is
+  constant p_relative_file_base : string := {_vhdl_string_literal(value)};
+end package;
+"""
+
+
+def _file_base():
+    """
+    The directory of base_path: that of the environment variable if it is set and not empty,
+    otherwise that of set_relative_file_base, None when neither is set.
+    """
+    value = os.environ.get(FILE_BASE_VARIABLE, "")
+    if value == "":
+        return _relative_file_base
+
+    directory = Path(value).resolve()
+    if not directory.is_dir():
+        raise ValueError(f"The environment variable {FILE_BASE_VARIABLE}={value!r} is not an existing directory")
+    if _relative_file_base is not None and _relative_file_base != directory:
+        LOGGER.warning(
+            "The environment variable %s=%s takes precedence over set_relative_file_base(%r)",
+            FILE_BASE_VARIABLE,
+            value,
+            str(_relative_file_base),
+        )
+    return directory
+
+
+def add_file_base_package(context):
+    """
+    Generate python_file_base_pkg and add it to the library of the package.
+    """
+    global _setup_done  # pylint: disable=global-statement
+
+    path = Path(context.output_path) / "python_bridge" / "vhdl" / f"{FILE_BASE_PACKAGE}.vhd"
+    _write_if_changed(path, _file_base_package_text(_file_base()))
+    context.add_source_files(context.library.name, [path])
+    _setup_done = True
+

vunit_python_bridge/hdl/src/python_ffi_pkg_bridge.vhd

@@ -26,6 +26,8 @@ use vunit_lib.id_pkg.all;
 use vunit_lib.integer_array_pkg.all;
 use vunit_lib.integer_vector_ptr_pkg.all;
 use vunit_lib.logger_pkg.all;
+use vunit_lib.run_pkg.get_phase;
+use vunit_lib.run_types_pkg.all;
 use work.python_bridge_pkg.all;
 
 package python_ffi_pkg is
@@ -121,6 +123,7 @@ package python_ffi_pkg is
   constant p_kind_integer_array : integer := 8;
   constant p_kind_integer_vector : integer := 9;
   constant p_kind_real_vector : integer := 10;
+  constant p_kind_dict : integer := 11;
 
   -- Names of the operations, used in the error messages
   impure function p_exec_operation(session : python_session_t := default_session) return string;
@@ -412,6 +415,14 @@ package body python_ffi_pkg is
     variable offset, n : natural := 0;
     variable staged_id : integer;
   begin
+    if get_phase < test_runner_setup then
+      failure(
+        python_logger,
+        operation & " failed:" & LF &
+        "An integer_array_t argument cannot be made before test_runner_setup."
+      );
+      return -1;
+    end if;
     if not p_succeeded(
       vpy_push_array(len, width(arr), height(arr), depth(arr), bit_width(arr), boolean'pos(is_signed(arr))),
       operation

vunit_python_bridge/hdl/src/python_pkg.vhd

@@ -7,12 +7,16 @@
 -- Copyright (c) 2014-2026, Lars Asplund lars.anders.asplund@gmail.com
 
 use work.python_ffi_pkg.all;
+use work.python_file_base_pkg.all;
 library vunit_lib;
 use vunit_lib.path.all;
 use vunit_lib.run_pkg.all;
 use vunit_lib.runner_pkg.all;
 use vunit_lib.integer_vector_ptr_pkg.all;
 use vunit_lib.string_ops.all;
+use vunit_lib.dict_pkg.all;
+use vunit_lib.dict_2008p_pkg.all;
+use vunit_lib.data_types_private_pkg.all;
 
 use std.textio.all;
 
@@ -28,6 +32,9 @@ use vunit_lib.logger_pkg.all;
 ------------------------------------------------------------------------------
 
 package python_pkg is
+  -- Import a Python file as a module. A relative path is relative to the
+  -- directory of the testbench file, tb_path, so test_runner_setup must have
+  -- been called. An absolute path is used as it is given.
   procedure import_module_from_file(
     module_path, as_module_name : string; session : python_session_t := default_session
   );
@@ -78,6 +85,12 @@ package python_pkg is
   --
   -- H and L are read as 1 and 0. Any other metavalue is an error.
   --
+  -- A dict_t value becomes a Python dict, {"key": value, ...}, whose values
+  -- are written the same way: integer, real, string, boolean, std_ulogic,
+  -- integer_vector, real_vector, integer_vector_ptr_t, integer_array_t and
+  -- dict_t values. Any other value type is an error. An integer_array_t value
+  -- is transferred as described below.
+  --
   -- An integer_array_t value is transferred to Python by the Python bridge,
   -- which is only available for NVC, GHDL and Questa, and is referred to by
   -- the expression, which means that it can be used in several calls.
@@ -93,6 +106,8 @@ package python_pkg is
   impure function kwarg_signed(kw : string; value : signed) return arg_t;
   impure function arg(value : integer_array_t) return arg_t;
   impure function kwarg(kw : string; value : integer_array_t) return arg_t;
+  impure function arg(value : dict_t) return arg_t;
+  impure function kwarg(kw : string; value : dict_t) return arg_t;
 
   -- The Python expression calling identifier with the given arguments, for
   -- example to embed a call in a larger exec or eval string:
@@ -164,6 +179,11 @@ package python_pkg is
   -----------------------------------------------------------------------------
   -- Results of eval: boolean, std_ulogic, vectors and arrays
   -----------------------------------------------------------------------------
+  -- The result of eval_dict and call_dict is a new dict_t that the caller owns
+  -- and deallocates. Its values are integer, real, string, boolean,
+  -- integer_vector_ptr_t (a list of int), integer_array_t (a NumPy array, with
+  -- the word size of an eval_integer_array result) and dict_t (a nested dict).
+  --
   -- std_ulogic_vector and integer_array_t results are only available under
   -- their explicit names, not as eval overloads, which keeps
   -- check_equal(eval("17"), 17) and length(eval("[1, 2]")) unambiguous.
@@ -187,6 +207,11 @@ package python_pkg is
     expr : string; session : python_session_t := default_session
   ) return integer_array_t;
 
+  impure function eval_dict(
+    expr : string; session : python_session_t := default_session
+  ) return dict_t;
+  alias eval is eval_dict[string, python_session_t return dict_t];
+
   procedure eval_std_ulogic_vector(
     expr : string; result : out std_ulogic_vector; session : python_session_t := default_session
   );
@@ -247,6 +272,13 @@ package python_pkg is
   alias call is call_integer_array[
     string, arg_t, arg_t, arg_t, arg_t, arg_t, arg_t, arg_t, arg_t, arg_t, arg_t, python_session_t return integer_array_t];
 
+  impure function call_dict(
+    identifier : string; arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10 : arg_t := null_arg;
+    session : python_session_t := default_session
+  ) return dict_t;
+  alias call is call_dict[
+    string, arg_t, arg_t, arg_t, arg_t, arg_t, arg_t, arg_t, arg_t, arg_t, arg_t, python_session_t return dict_t];
+
   procedure call_std_ulogic_vector(
     identifier : string; result : out std_ulogic_vector;
     arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10 : arg_t := null_arg;
@@ -271,24 +303,36 @@ package python_pkg is
   -- is given. The file is executed with __file__ set and its own directory on
   -- sys.path so that it can import its siblings.
   procedure exec_file(file_name : string; session : python_session_t := default_session);
+
+  -- The absolute base directory, set by vunit_python_bridge.set_relative_file_base()
+  -- or VUNIT_PYTHON_BRIDGE_FILE_BASE. Without one, a failure is reported on
+  -- python_logger and "" is returned.
+  impure function base_path return string;
 end package;
 
 package body python_pkg is
+  impure function p_file_path(file_name, operation : string; session : python_session_t) return string;
+
   -- @formatter:off
   procedure import_module_from_file(
     module_path, as_module_name : string; session : python_session_t := default_session
   ) is
     constant spec_name : string := "__" & as_module_name & "_spec";
+    constant path : string := p_file_path(
+      module_path, "import_module_from_file(""" & module_path & """, """ & as_module_name & """)", session
+    );
     constant code : string :=
     "from importlib.util import spec_from_file_location, module_from_spec" & LF &
     "from pathlib import Path" & LF &
     "import sys" & LF &
-    spec_name & " = spec_from_file_location('" & as_module_name & "', str(Path('" & module_path & "')))" & LF &
+    spec_name & " = spec_from_file_location('" & as_module_name & "', str(Path('" & path & "')))" & LF &
     as_module_name & " = module_from_spec(" & spec_name & ")" & LF &
     "sys.modules['" & as_module_name & "'] = " & as_module_name & LF &
      spec_name & ".loader.exec_module(" & as_module_name & ")";
   begin
-    exec(code, session);
+    if path /= "" then
+      exec(code, session);
+    end if;
   end;
   -- @formatter:on
 
@@ -408,6 +452,31 @@ package body python_pkg is
     return result;
   end;
 
+  -- The Python source text of a message, escaped for a double quoted Python
+  -- string. Quote, backslash and control characters are escaped; bytes >= 128
+  -- are kept so that Python decodes UTF-8 text.
+  function p_quoted(message : string) return string is
+    variable result : line;
+  begin
+    swrite(result, """");
+    for idx in message'range loop
+      case message(idx) is
+        when '"' | '\' => swrite(result, "\" & message(idx));
+        when LF => swrite(result, "\n");
+        when CR => swrite(result, "\r");
+        when others =>
+          if character'pos(message(idx)) < 32 or message(idx) = DEL then
+            swrite(result, "\x" & to_hstring(to_unsigned(character'pos(message(idx)), 8)));
+          else
+            swrite(result, string'(1 => message(idx)));
+          end if;
+      end case;
+    end loop;
+    swrite(result, """");
+
+    return result.all;
+  end;
+
   function arg(value : integer) return arg_t is
   begin
     return (p_positional_arg, to_string(value));
@@ -420,12 +489,12 @@ package body python_pkg is
 
   function arg(value : string) return arg_t is
   begin
-    return (p_positional_arg, '"' & value & '"');
+    return (p_positional_arg, p_quoted(value));
   end;
 
   function kwarg(kw : string; value : string) return arg_t is
   begin
-    return (kw, '"' & value & '"');
+    return (kw, p_quoted(value));
   end;
 
   function arg(value : integer_vector) return arg_t is
@@ -466,26 +535,6 @@ package body python_pkg is
     end if;
   end;
 
-  -- The Python source text of a message, escaped for a double quoted Python
-  -- string. A quote, a backslash and a line break are the characters that
-  -- cannot be written as they are.
-  function p_quoted(message : string) return string is
-    variable result : line;
-  begin
-    swrite(result, """");
-    for idx in message'range loop
-      case message(idx) is
-        when '"' | '\' => swrite(result, "\" & message(idx));
-        when LF => swrite(result, "\n");
-        when CR => swrite(result, "\r");
-        when others => swrite(result, string'(1 => message(idx)));
-      end case;
-    end loop;
-    swrite(result, """");
-
-    return result.all;
-  end;
-
   -- Report a value that could not be converted and give it a Python source
   -- text raising the same message, so that the call the argument is used in
   -- fails the same way rather than being made without the argument.
@@ -601,6 +650,45 @@ package body python_pkg is
     return "__vunit__.staged(" & integer'image(staged_id) & ")";
   end;
 
+  impure function p_arg_value(value : dict_t; operation : string) return string;
+
+  -- The Python source text of the value stored for a key of a dict
+  impure function p_dict_item(value : dict_t; key, operation : string) return string is
+  begin
+    case get_value_type(value, key) is
+      when vhdl_integer => return to_string(get_integer(value, key));
+      when vhdl_real => return to_string(get_real(value, key), "%.16e");
+      when vhdl_string => return p_quoted(get_string(value, key));
+      when vhdl_boolean => return arg(get_boolean(value, key)).value;
+      when ieee_std_ulogic => return p_arg_value(get_std_ulogic(value, key), operation);
+      when vhdl_integer_vector => return to_py_list_str(get_integer_vector(value, key));
+      when vhdl_real_vector => return to_py_list_str(get_real_vector(value, key));
+      when vunit_integer_vector_ptr_t => return p_arg_value(get_integer_vector_ptr_t_ref(value, key));
+      when vunit_integer_array_t => return p_arg_value(get_integer_array_t_ref(value, key), operation);
+      when vunit_dict_t => return p_arg_value(get_dict_t_ref(value, key), operation);
+      when others =>
+        return p_failed_value(
+          operation & " cannot convert the " & to_string(get_value_type(value, key)) &
+          " value of the dict key """ & key & """"
+        );
+    end case;
+  end;
+
+  impure function p_arg_value(value : dict_t; operation : string) return string is
+    variable result : line;
+  begin
+    swrite(result, "{");
+    for idx in 0 to num_keys(value) - 1 loop
+      if idx > 0 then
+        swrite(result, ", ");
+      end if;
+      swrite(result, p_quoted(get_key(value, idx)) & ": " & p_dict_item(value, get_key(value, idx), operation));
+    end loop;
+    swrite(result, "}");
+
+    return result.all;
+  end;
+
   function arg(value : real_vector) return arg_t is
   begin
     return (p_positional_arg, p_arg_value(value));
@@ -661,6 +749,16 @@ package body python_pkg is
     return (kw, p_arg_value(value, "kwarg"));
   end;
 
+  impure function arg(value : dict_t) return arg_t is
+  begin
+    return (p_positional_arg, p_arg_value(value, "arg"));
+  end;
+
+  impure function kwarg(kw : string; value : dict_t) return arg_t is
+  begin
+    return (kw, p_arg_value(value, "kwarg"));
+  end;
+
   -----------------------------------------------------------------------------
   -- Argument groups
   -----------------------------------------------------------------------------
@@ -875,6 +973,51 @@ package body python_pkg is
     return result;
   end;
 
+  -- The dict_t of a dict result. Python keeps the converted entries of the dict
+  -- under the handle, see dict_kinds, dict_key and dict_item of runtime.py, and
+  -- VHDL fetches them one at a time with the eval of the type of each value.
+  impure function p_to_dict(handle : integer; session : python_session_t) return dict_t;
+
+  procedure p_add_dict_item(dict : dict_t; handle, index, kind : integer; session : python_session_t) is
+    constant entry : string := "(" & integer'image(handle) & ", " & integer'image(index) & ")";
+    constant key : string := eval_string("__vunit__.dict_key" & entry, session);
+    constant item : string := "__vunit__.dict_item" & entry;
+    variable ptr : integer_vector_ptr_t;
+    variable arr : integer_array_t;
+    variable nested : dict_t;
+  begin
+    case kind is
+      when p_kind_integer => set_integer(dict, key, eval_integer(item, session));
+      when p_kind_real => set_real(dict, key, eval_real(item, session));
+      when p_kind_boolean => set_boolean(dict, key, eval_boolean(item, session));
+      when p_kind_string => set_string(dict, key, eval_string(item, session));
+      when p_kind_integer_vector =>
+        ptr := eval_integer_vector_ptr(item, session);
+        set_integer_vector_ptr_t_ref(dict, key, ptr);
+      when p_kind_integer_array =>
+        arr := eval_integer_array(item, session);
+        set_integer_array_t_ref(dict, key, arr);
+      when others =>
+        -- A nested dict, whose result is its handle
+        if p_eval(item, p_kind_dict, -1, p_eval_operation(item, session), session) then
+          nested := p_to_dict(p_result_integer, session);
+          set_dict_t_ref(dict, key, nested);
+        end if;
+    end case;
+  end;
+
+  impure function p_to_dict(handle : integer; session : python_session_t) return dict_t is
+    constant kinds : integer_vector := eval_integer_vector(
+      "__vunit__.dict_kinds(" & integer'image(handle) & ")", session
+    );
+    constant result : dict_t := new_dict;
+  begin
+    for idx in kinds'range loop
+      p_add_dict_item(result, handle, idx - kinds'low, kinds(idx), session);
+    end loop;
+    return result;
+  end;
+
   -----------------------------------------------------------------------------
   -- exec
   -----------------------------------------------------------------------------
@@ -893,20 +1036,51 @@ package body python_pkg is
     return false;
   end;
 
-  -- The file name of exec_file, a relative one taken from the directory of the
-  -- testbench file like the file names of the other VUnit subprograms
-  impure function p_file_path(file_name : string) return string is
+  -- The file name of exec_file and import_module_from_file, a relative one taken
+  -- from the directory of the testbench file like the file names of the other
+  -- VUnit subprograms
+  impure function p_file_path(file_name, operation : string; session : python_session_t) return string is
+    constant tb_dir : string := tb_path(get_cfg(runner_state));
   begin
-    if p_is_absolute(file_name) then
+    if file_name = "" then
+      failure(get_logger(get_id(session)), operation & " failed:" & LF & "Empty file name.");
+      return "";
+    elsif p_is_absolute(file_name) then
       return file_name;
+    elsif tb_dir = "" then
+      -- Without a testbench path the file would silently be taken from the working directory
+      failure(
+        get_logger(get_id(session)),
+        operation & " failed:" & LF &
+        "A relative file name needs the testbench path set by test_runner_setup. " &
+        "Call it after test_runner_setup, give an absolute path, " &
+        "or join it to base_path with a base directory set in the run script."
+      );
+      return "";
     end if;
-    return join(tb_path(get_cfg(runner_state)), file_name);
+    return join(tb_dir, file_name);
+  end;
+
+  impure function base_path return string is
+  begin
+    if p_relative_file_base = "" then
+      failure(
+        python_logger,
+        "base_path failed: no base directory is set. " &
+        "Call vunit_python_bridge.set_relative_file_base() in the run script before add_package, " &
+        "or set the environment variable VUNIT_PYTHON_BRIDGE_FILE_BASE."
+      );
+    end if;
+    return p_relative_file_base;
   end;
 
   procedure exec_file(file_name : string; session : python_session_t := default_session) is
+    constant path : string := p_file_path(file_name, p_exec_file_operation(file_name, session), session);
     variable ok : boolean;
   begin
-    ok := p_exec_file(p_file_path(file_name), session);
+    if path /= "" then
+      ok := p_exec_file(path, session);
+    end if;
   end;
 
   -----------------------------------------------------------------------------
@@ -952,6 +1126,16 @@ package body python_pkg is
     return null_integer_array;
   end;
 
+  impure function eval_dict(
+    expr : string; session : python_session_t := default_session
+  ) return dict_t is
+  begin
+    if p_eval(expr, p_kind_dict, -1, p_eval_operation(expr, session), session) then
+      return p_to_dict(p_result_integer, session);
+    end if;
+    return new_dict;
+  end;
+
   procedure eval_std_ulogic_vector(
     expr : string; result : out std_ulogic_vector; session : python_session_t := default_session
   ) is
@@ -1052,6 +1236,16 @@ package body python_pkg is
     );
   end;
 
+  impure function call_dict(
+    identifier : string; arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10 : arg_t := null_arg;
+    session : python_session_t := default_session
+  ) return dict_t is
+  begin
+    return eval_dict(
+      to_call_str(identifier, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10), session
+    );
+  end;
+
   procedure call_std_ulogic_vector(
     identifier : string; result : out std_ulogic_vector;
     arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10 : arg_t := null_arg;