Add Python objects: instances of Python classes owned by VHDL

README.md

@@ -19,7 +19,9 @@ the selected simulator by a foreign language interface the package builds itself
 called through VHPIDIRECT (NVC, GHDL) or the FLI (Questa/ModelSim), or a VHPI application built with
 the simulator's own compiler driver (Riviera-PRO/Active-HDL). Values cross the interface with their
 VHDL types: `integer`, `real`, `string`, `boolean`, `std_ulogic`, `unsigned`/`signed`, the vector
-types, and `integer_array_t` as a NumPy array.
+types, and `integer_array_t` as a NumPy array. A `python_object_t` is an instance of a Python class
+owned by VHDL, for example the backend of a verification component, with a namespace of its own for
+every instance.
 
 ## Installation
 

docs/file_paths.rst

@@ -36,12 +36,9 @@ How a file name is resolved
        ``pathlib.Path`` and so on
      - The current working directory of Python, which is the working
        directory of the simulator. See the warning below.
-   * - Python module imported by name, ``import model``
-     - ``sys.path``, which holds the directory of the run script first, like
-       ``python run.py`` does, the directories of ``PYTHONPATH`` (the
-       simulator inherits the environment of VUnit, so a ``PYTHONPATH`` set
-       in the run script before ``vu.main()`` is seen), and, while
-       ``exec_file`` executes a file, the directory of that file.
+   * - Python module imported by name, ``import model``, and the class of a
+       :ref:`Python object <python_bridge:objects>`
+     - ``sys.path``: see :ref:`python_bridge:finding_code` below.
 
 .. warning::
 
@@ -53,6 +50,34 @@ How a file name is resolved
    ``Path(__file__).parent`` in the model, or pass an absolute name from VHDL,
    built with ``base_path`` or ``tb_path``.
 
+.. _python_bridge:finding_code:
+
+Python modules
+~~~~~~~~~~~~~~
+
+The interpreter in the simulator imports modules the way Python started on the
+run script does. Without any setup it finds:
+
+* modules in the directory of the run script, the first entry of ``sys.path``.
+  This is also how ``import_run_script`` imports the run script;
+* the packages of the Python environment VUnit runs in, for example an active
+  virtual environment, including packages installed with ``pip install -e``;
+* while ``exec_file`` executes a file, the modules next to that file.
+
+Python code anywhere else is found once its directory is on ``PYTHONPATH``,
+set in the run script before ``vu.main()``: the simulations inherit the
+environment of VUnit (see the recipes below). A verification component used by
+many testbenches can so keep its model in a directory of its own and name its
+class, for example ``"my_vc_model.Model"`` for a :ref:`Python object
+<python_bridge:objects>`. Installing the model as a package, for example with
+``pip install -e``, has the same effect without changing the run script.
+
+There is one ``sys.path`` and one ``sys.modules`` per simulation, shared by all
+:ref:`sessions <python_bridge:sessions>`. Two modules with the same name are
+therefore the same module, so a package is best named after the component it
+belongs to, and state kept at module level is shared by everything that
+imports the module.
+
 Recipes
 ~~~~~~~
 

docs/index.rst

@@ -38,6 +38,8 @@ Key features
   ``boolean``, ``std_ulogic``, ``unsigned``/``signed``, the vector types, and ``integer_array_t``
   as a NumPy array.
 * :doc:`Sessions <sessions>` give models and component instances Python namespaces of their own.
+* :doc:`Python objects <python_objects>` are instances of Python classes owned by VHDL, for example
+  the backends of verification components.
 * :doc:`Python files and modules <python_files>`, including the run script itself, are executed or
   imported from VHDL, with :doc:`file paths <file_paths>` that work for testbenches and
   verification components alike.
@@ -111,6 +113,7 @@ become available through ``python_context``:
    types
    errors
    sessions
+   python_objects
    python_files
    file_paths
 
@@ -121,6 +124,7 @@ become available through ``python_context``:
    api/python_context
    api/python_ffi_pkg
    api/python_pkg
+   api/python_object_pkg
 
 .. toctree::
    :caption: Simulators

docs/other_simulators.rst

@@ -35,8 +35,9 @@ arguments, a 20 register status dump, wide
 ``call``, Python files executed with ``exec_file`` or imported with
 ``import_module_from_file``, two models loaded into a session each, and a
 Python model failing with the logger of the default session mocked. Its last
-test case drives ``python_model``, a verification component whose behaviour is
-the Python function in ``python_model.py`` rather than VHDL. The component finds
-that file by joining its name to ``base_path``, the directory of the run script, which
+test cases drive ``python_model``, a verification component whose behaviour is
+the Python function in ``python_model.py`` rather than VHDL, and ``filter_vc``,
+whose instances have Python objects as backends. ``python_model`` finds its file
+by joining its name to ``base_path``, the directory of the run script, which
 ``run.py`` sets as the base directory, while the testbench gives the files it
 loads itself relative to its own directory. See :ref:`python_bridge:file_paths`.