[uvm_report, logging] Add opt-in SV-UVM-style reporting over Python logging (pyuvm#396)

Author: ysekhar

README.md

@@ -24,7 +24,7 @@ You can read the API documentation for **pyuvm** on [ReadTheDocs](https://pyuvm.
 |Section|Name|Description|
 |-------|----|-----------|
 |5|Base Classes|Basic classes such as `uvm_void` and `uvm_object`|
-|6|Reporting Classes|**pyuvm** uses the **logging** package to implement reporting, but integrates it within some of the UVM reporting functionality.|
+|6|Reporting Classes|**pyuvm** uses the **logging** package as the reporting backend and provides optional SV-UVM-style reporting APIs, verbosity filtering, report IDs, severity counts, and summaries.|
 |8|Factory Classes|**pyuvm** implements all the UVM factory functionality without using the macros needed in SystemVerilog.  The factory supports any class extended from `uvm_void`.|
 |9|Phasing|IEEE 1800.2 describes basic phasing that everyone uses and a complicated custom phasing system that almost nobody uses.  **pyuvm** only implmenents the phasing that everyone uses, but you can extend phasing using Python OOP techniques.|
 |12|UVM TLM Interfaces|**pyuvm** fully implements the UVM *Transaction Level Modeling* (TLM) system. |
@@ -173,7 +173,7 @@ You'll see the following in the test:
 
 * The `ConfigDB()` singleton acts the same way as the `uvm_config_db` interface in the SystemVerilog UVM. **pyuvm** refactored away the `uvm_resource_db` as there are no issues with classes to manage.
 
-* **pyuvm** leverages the Python logging system and does not implement the UVM reporting system. Every descendent of `uvm_report_object` has a `logger` data member.
+* **pyuvm**'s default reporting use model leverages the Python logging system. Every `uvm_object` instance, including descendant instances, has a logger available through `self.logger`. The optional SV-UVM-style reporting path is described below.
 
 * Sequences work as they do in the SystemVerilog UVM.
 
@@ -278,7 +278,7 @@ The scoreboard receives commands from the command monitor and results from the r
 * The scoreboard exposes the FIFO exports by copying them into class data members.  As we see in the environment above, this allows us to connect the exports without reaching into the `Scoreboard's` inner workings.
 * We connect the exports in the `connect_phase()`
 * The `check_phase()` runs after the `run_phase()`.  At this point the scoreboard has all operations and results. It loops through the operations and predicts the result, then it compares the predicted and actual result.
-* Notice that we do not use UVM reporting. Instead we us the Python `logging` module. Every `uvm_report_object` and its children has its own logger stored in `self.logger.`
+* This example uses the Python `logging` module directly. Every `uvm_object` instance, including descendant instances, has a logger available through `self.logger`. Tests that need UVM-style report IDs and verbosity filtering can use `self.uvm_report` instead.
 
 ```python
 class Scoreboard(uvm_component):
@@ -457,6 +457,70 @@ class AluSeqItem(uvm_sequence_item):
 
 ```
 
+## SV-UVM-style reporting
+
+Existing pyuvm testbenches can continue to use Python logging directly:
+
+```python
+self.logger.info("Covered all operations")
+self.logger.error("Functional coverage error")
+```
+
+For testbenches that need UVM-style report IDs, UVM verbosity filtering, severity counts, report summaries, or report catching, pyuvm also provides an opt-in SV-UVM-style reporting path. Python logging remains the backend; the UVM-style layer decides whether a report is enabled, assigns UVM severity and report ID metadata, and then emits through logging.
+
+Enable the shared SV-UVM-style reporting mode before creating UVM objects or components:
+
+```bash
+PYUVM_ENABLE_SV_UVM_STYLE_REPORTING=1
+```
+
+You can also enable it from Python before constructing the testbench:
+
+```python
+from pyuvm import set_sv_uvm_style_reporting_enabled
+
+set_sv_uvm_style_reporting_enabled(True)
+```
+
+The enable flag changes the logging topology so `uvm_object` loggers propagate to the shared `uvm` logger. In this mode, `uvm_report_object` does not install a default stream handler on every report object. If you also want centralized counts, summaries, and report catching, create the report server early in the test:
+
+```python
+from pyuvm import UVM_LOW, uvm_report_server
+
+report_server = uvm_report_server.create(verbosity=UVM_LOW)
+```
+
+Then write reports through `self.uvm_report`:
+
+```python
+from pyuvm import UVM_HIGH, UVM_LOW, uvm_component
+
+
+class Scoreboard(uvm_component):
+    def check_phase(self):
+        self.uvm_report.info("SCOREBOARD", "checking final results", UVM_LOW)
+
+        if self.mismatch_seen:
+            self.uvm_report.error("SCOREBOARD", "result mismatch detected")
+        else:
+            self.uvm_report.info("SCOREBOARD", "all results matched", UVM_HIGH)
+```
+
+UVM verbosity is handled separately from Python logging levels. A UVM info report passes when its message verbosity is less than or equal to the configured verbosity. Warning, error, and fatal reports are severity reports and are not suppressed by info verbosity. Python logging levels still carry severity to the backend formatter and handlers.
+
+At the end of a test, the report server can emit a summary and check failure policy:
+
+```python
+import logging
+from pyuvm import uvm_report_server
+
+report_server = uvm_report_server.get()
+report_server.log_summary(logging.getLogger("uvm"))
+report_server.assert_no_failures("end of test")
+```
+
+Output formatting still uses Python logging formatters. pyuvm's `PyuvmFormatter` remains the customization point for teams that want a different log layout while keeping the UVM-style report metadata and filtering behavior.
+
 
 # Contributing
 

docs/docsources/SV_UVM_Style_Reporting.rst

@@ -0,0 +1,141 @@
+SV-UVM-Style Reporting
+======================
+
+pyuvm uses Python logging as its reporting backend. Existing testbenches can
+continue to use ``self.logger.info()``, ``self.logger.warning()``, and
+``self.logger.error()`` directly.
+
+For testbenches that need UVM-style report IDs, UVM verbosity filtering,
+severity counts, report summaries, or report catching, pyuvm also provides an
+opt-in SV-UVM-style reporting path. The UVM-style layer performs the UVM
+reporting decisions and then emits through Python logging.
+
+Enabling SV-UVM-Style Reporting
+-------------------------------
+
+Enable the shared reporting mode before creating UVM objects or components:
+
+.. code-block:: bash
+
+   PYUVM_ENABLE_SV_UVM_STYLE_REPORTING=1 make sim
+
+You can also enable it from Python before constructing the testbench:
+
+.. code-block:: python
+
+   from pyuvm import set_sv_uvm_style_reporting_enabled
+
+   set_sv_uvm_style_reporting_enabled(True)
+
+When this mode is enabled, ``uvm_object`` loggers propagate to the shared
+``uvm`` logger. In this mode, ``uvm_report_object`` does not install a default
+stream handler on every report object. This preserves Python logging as the
+transport while giving the testbench a shared path for report rendering.
+
+To collect severity counts, use report summaries, or install report catcher
+rules, create the report server early in the test:
+
+.. code-block:: python
+
+   from pyuvm import UVM_LOW, uvm_report_server
+
+   report_server = uvm_report_server.create(verbosity=UVM_LOW)
+
+Writing Reports
+---------------
+
+Every ``uvm_object`` has a ``uvm_report`` property. Use it when you want
+UVM-style report IDs and UVM verbosity semantics:
+
+.. code-block:: python
+
+   from pyuvm import UVM_HIGH, UVM_LOW, uvm_component
+
+
+   class Scoreboard(uvm_component):
+       def check_phase(self):
+           self.uvm_report.info("SCOREBOARD", "checking final results", UVM_LOW)
+
+           if self.mismatch_seen:
+               self.uvm_report.error("SCOREBOARD", "result mismatch detected")
+           else:
+               self.uvm_report.info("SCOREBOARD", "all results matched", UVM_HIGH)
+
+The available report methods are:
+
+* ``self.uvm_report.info(report_id, message, verbosity)``
+* ``self.uvm_report.warning(report_id, message)``
+* ``self.uvm_report.error(report_id, message)``
+* ``self.uvm_report.fatal(report_id, message)``
+
+UVM Verbosity
+-------------
+
+UVM verbosity is not mapped onto Python logging levels. It is evaluated before
+the logging call using UVM semantics: an info report passes when its message
+verbosity is less than or equal to the configured verbosity.
+
+.. code-block:: python
+
+   from pyuvm import UVM_HIGH, UVM_LOW, uvm_report_server
+
+   uvm_report_server.create(verbosity=UVM_LOW)
+
+   self.uvm_report.info("LOW_ID", "visible", UVM_LOW)
+   self.uvm_report.info("HIGH_ID", "suppressed", UVM_HIGH)
+
+Warning, error, and fatal reports are severity reports. They are not suppressed
+by info verbosity. Python logging levels still carry severity to the backend
+formatter and handlers.
+
+Report Summary and Failure Policy
+---------------------------------
+
+The report server tracks UVM severity counts. At the end of a test, emit a
+summary and assert the failure policy:
+
+.. code-block:: python
+
+   import logging
+   from pyuvm import uvm_report_server
+
+   report_server = uvm_report_server.get()
+   report_server.log_summary(logging.getLogger("uvm"))
+   report_server.assert_no_failures("end of test")
+
+By default, warnings do not fail the test, while errors and fatals do. The
+policy can be changed when the report server is created:
+
+.. code-block:: python
+
+   from pyuvm import uvm_report_policy, uvm_report_server
+
+   policy = uvm_report_policy(fail_on_warning=True, max_quit_count=5)
+   uvm_report_server.create(policy=policy)
+
+Report Catching
+---------------
+
+The report server supports simple severity rewrites by report ID and message
+regular expression:
+
+.. code-block:: python
+
+   from pyuvm import UVM_WARNING, uvm_report_server
+
+   report_server = uvm_report_server.get()
+   report_server.add_change_sev("KNOWN_ISSUE", "temporary", UVM_WARNING)
+
+   self.uvm_report.error("KNOWN_ISSUE", "temporary mismatch")
+
+Formatter Relationship
+----------------------
+
+SV-UVM-style reporting does not replace Python logging. It provides UVM-shaped
+report metadata and filtering before the message reaches logging. The rendered
+timestamp, hierarchy, filename, line number, and final text layout still come
+from the active Python logging formatter.
+
+pyuvm's ``PyuvmFormatter`` remains the customization point for teams that want
+a different log layout while keeping the UVM-style report metadata, verbosity
+filtering, counts, summaries, and catcher behavior.

docs/docsources/UVM_and_Python.rst

@@ -141,4 +141,29 @@ There are no field macros and thus no need to implement this class.
 Reporting Classes
 ^^^^^^^^^^^^^^^^^
 
-We use Python logging instead of the UVM reporting system.
+pyuvm uses Python logging as the reporting backend. Existing tests can keep
+using ``self.logger`` directly, and every ``uvm_object`` instance, including
+descendant instances, has a logger available through ``self.logger``.
+
+pyuvm also provides an opt-in SV-UVM-style reporting path for tests that need
+report IDs, UVM verbosity filtering, severity counts, summaries, and report
+catching. Enable it before constructing the testbench:
+
+.. code-block:: python
+
+   from pyuvm import set_sv_uvm_style_reporting_enabled
+
+   set_sv_uvm_style_reporting_enabled(True)
+
+or from the shell:
+
+.. code-block:: bash
+
+   PYUVM_ENABLE_SV_UVM_STYLE_REPORTING=1 make sim
+
+UVM verbosity is handled separately from Python logging levels. Info reports
+pass when the report verbosity is less than or equal to the configured UVM
+verbosity. Python logging levels continue to represent severity for the backend
+formatter and handlers.
+
+See :doc:`SV_UVM_Style_Reporting` for examples.

docs/index.rst

@@ -6,4 +6,5 @@ pyuvm
 
    docsources/README.md
    docsources/UVM_and_Python
+   docsources/SV_UVM_Style_Reporting
    apidocs/index

pyproject.toml

@@ -97,6 +97,11 @@ known-third-party = [
 [tool.ruff.lint.per-file-ignores]
 "pyuvm/__init__.py" = [
     "F401",
+    "I001",
+]
+"pyuvm/uvm_reporting/__init__.py" = [
+    "E402",
+    "I001",
 ]
 
 [tool.codespell]

pyuvm/__init__.py

@@ -109,6 +109,35 @@
 
 # Section 6
 from pyuvm._s06_reporting_classes import uvm_report_object
+from pyuvm.uvm_reporting.uvm_report_catcher import (
+    uvm_report_action_e,
+    uvm_report_catcher,
+    uvm_report_message,
+)
+from pyuvm.uvm_reporting.uvm_report_server import (
+    uvm_report_policy,
+    uvm_report_server,
+    uvm_report_stats,
+)
+from pyuvm.uvm_reporting import (
+    get_sv_uvm_style_reporting_enabled,
+    set_sv_uvm_style_reporting_enabled,
+)
+from pyuvm.uvm_reporting.uvm_verbosity import (
+    UVM_DEBUG,
+    UVM_ERROR,
+    UVM_FATAL,
+    UVM_FULL,
+    UVM_HIGH,
+    UVM_INFO,
+    UVM_LOW,
+    UVM_MEDIUM,
+    UVM_NONE,
+    UVM_WARNING,
+    parse_uvm_verbosity,
+    resolve_uvm_verbosity,
+    uvm_reporter,
+)
 
 # Section 8
 from pyuvm._s08_factory_classes import uvm_factory
@@ -342,7 +371,28 @@
     "uvm_policy",
     "uvm_transaction",
     # Section 6 - Reporting classes
+    "UVM_DEBUG",
+    "UVM_ERROR",
+    "UVM_FATAL",
+    "UVM_FULL",
+    "UVM_HIGH",
+    "UVM_INFO",
+    "UVM_LOW",
+    "UVM_MEDIUM",
+    "UVM_NONE",
+    "UVM_WARNING",
+    "parse_uvm_verbosity",
+    "resolve_uvm_verbosity",
+    "get_sv_uvm_style_reporting_enabled",
+    "set_sv_uvm_style_reporting_enabled",
+    "uvm_report_action_e",
+    "uvm_report_catcher",
+    "uvm_report_message",
     "uvm_report_object",
+    "uvm_report_policy",
+    "uvm_report_server",
+    "uvm_report_stats",
+    "uvm_reporter",
     # Section 8 - Factory classes
     "uvm_factory",
     # Section 9 - Phasing classes
@@ -458,7 +508,8 @@
 # Set the __module__ attribute for all re-exported names.
 # This is necessary for the documentation generation tools to link objects correctly.
 for _name in __all__:
-    # Skip non-classes and non-functions.
-    if _name in {"__version__", "FIFO_DEBUG", "PYUVM_DEBUG", "uvm_common_phases"}:
-        continue
-    globals()[_name].__module__ = __name__
+    _obj = globals()[_name]
+    # Constants and collection exports do not have __module__; re-home only
+    # exported objects that expose it for autodoc links.
+    if hasattr(_obj, "__module__"):
+        _obj.__module__ = __name__