Add HAS_PYGMENTS lazy tester (#9944)

* Add `HAS_PYGMENTS` lazy tester

This somehow slipped through my nets when I added all the lazy testers.
We hope to drop support for the custom Pygments lexers in the future,
but in the mean time, this is the correct way to test for things, and
having an extra lazy tester doesn't hurt us.

* Remove unused import

qiskit/circuit/quantumcircuit.py

@@ -15,7 +15,6 @@
 """Quantum circuit object."""
 
 from __future__ import annotations
-import sys
 import collections.abc
 import copy
 import itertools
@@ -38,16 +37,18 @@
     Iterable,
     Any,
     DefaultDict,
+    Literal,
     overload,
 )
 import numpy as np
-from qiskit.exceptions import QiskitError, MissingOptionalLibraryError
+from qiskit.exceptions import QiskitError
 from qiskit.utils.multiprocessing import is_main_process
 from qiskit.circuit.instruction import Instruction
 from qiskit.circuit.gate import Gate
 from qiskit.circuit.parameter import Parameter
 from qiskit.qasm.exceptions import QasmError
 from qiskit.circuit.exceptions import CircuitError
+from qiskit.utils import optionals as _optionals
 from .parameterexpression import ParameterExpression, ParameterValueType
 from .quantumregister import QuantumRegister, Qubit, AncillaRegister, AncillaQubit
 from .classicalregister import ClassicalRegister, Clbit
@@ -62,21 +63,6 @@
 from .measure import Measure
 from .reset import Reset
 
-try:
-    import pygments
-    from pygments.formatters import Terminal256Formatter  # pylint: disable=no-name-in-module
-    from qiskit.qasm.pygments import OpenQASMLexer  # pylint: disable=ungrouped-imports
-    from qiskit.qasm.pygments import QasmTerminalStyle  # pylint: disable=ungrouped-imports
-
-    HAS_PYGMENTS = True
-except Exception:  # pylint: disable=broad-except
-    HAS_PYGMENTS = False
-
-if sys.version_info >= (3, 8):
-    from typing import Literal
-else:
-    from typing_extensions import Literal
-
 if typing.TYPE_CHECKING:
     import qiskit  # pylint: disable=cyclic-import
     from qiskit.transpiler.layout import TranspileLayout  # pylint: disable=cyclic-import
@@ -1768,12 +1754,15 @@ def qasm(
                 file.write(out)
 
         if formatted:
-            if not HAS_PYGMENTS:
-                raise MissingOptionalLibraryError(
-                    libname="pygments>2.4",
-                    name="formatted QASM output",
-                    pip_install="pip install pygments",
-                )
+            _optionals.HAS_PYGMENTS.require_now("formatted OpenQASM 2 output")
+
+            import pygments
+            from pygments.formatters import (  # pylint: disable=no-name-in-module
+                Terminal256Formatter,
+            )
+            from qiskit.qasm.pygments import OpenQASMLexer
+            from qiskit.qasm.pygments import QasmTerminalStyle
+
             code = pygments.highlight(
                 out, OpenQASMLexer(), Terminal256Formatter(style=QasmTerminalStyle)
             )

qiskit/qasm/__init__.py

@@ -42,18 +42,16 @@
 
 from numpy import pi
 
+from qiskit.utils.optionals import HAS_PYGMENTS
+
 from .qasm import Qasm
 from .exceptions import QasmError
 
-try:
-    import pygments
 
-    HAS_PYGMENTS = True
-except ImportError:
-    HAS_PYGMENTS = False
+def __getattr__(name):
+    if name in ("OpenQASMLexer", "QasmHTMLStyle", "QasmTerminalStyle"):
+        import qiskit.qasm.pygments
+
+        return getattr(qiskit.qasm.pygments, name)
 
-if HAS_PYGMENTS:
-    try:
-        from .pygments import OpenQASMLexer, QasmHTMLStyle, QasmTerminalStyle
-    except Exception:  # pylint: disable=broad-except
-        HAS_PYGMENTS = False
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

qiskit/qasm/pygments/__init__.py

@@ -24,15 +24,11 @@
    QasmTerminalStyle
    QasmHTMLStyle
 """
-try:
-    import pygments
-
-    HAS_PYGMENTS = True
-except ImportError:
-    HAS_PYGMENTS = False
-
-if HAS_PYGMENTS:
-    try:
-        from .lexer import OpenQASMLexer, QasmTerminalStyle, QasmHTMLStyle
-    except Exception:  # pylint: disable=broad-except
-        HAS_PYGMENTS = False
+
+# pylint: disable=wrong-import-position
+
+from qiskit.utils.optionals import HAS_PYGMENTS
+
+HAS_PYGMENTS.require_now("built-in OpenQASM 2 syntax highlighting")
+
+from .lexer import OpenQASMLexer, QasmTerminalStyle, QasmHTMLStyle

qiskit/qasm/pygments/lexer.py

@@ -12,16 +12,9 @@
 """Pygments tools for Qasm.
 """
 
-from qiskit.exceptions import MissingOptionalLibraryError
-
-try:
-    from pygments.lexer import RegexLexer
-    from pygments.token import Comment, String, Keyword, Name, Number, Text
-    from pygments.style import Style
-except ImportError as ex:
-    raise MissingOptionalLibraryError(
-        "pygments>2.4", "qiskit.qasm.pygments", "pip install pygments"
-    ) from ex
+from pygments.lexer import RegexLexer
+from pygments.token import Comment, String, Keyword, Name, Number, Text
+from pygments.style import Style
 
 
 class QasmTerminalStyle(Style):

qiskit/tools/jupyter/library.py

@@ -17,19 +17,9 @@
 import ipywidgets as wid
 from IPython.display import display
 from qiskit import QuantumCircuit
-from qiskit.exceptions import MissingOptionalLibraryError
 from qiskit.utils import optionals as _optionals
 from qiskit.utils.deprecation import deprecate_func
 
-try:
-    import pygments
-    from pygments.formatters import HtmlFormatter
-    from qiskit.qasm.pygments import QasmHTMLStyle, OpenQASMLexer
-
-    HAS_PYGMENTS = True
-except Exception:  # pylint: disable=broad-except
-    HAS_PYGMENTS = False
-
 
 @_optionals.HAS_MATPLOTLIB.require_in_call
 def _generate_circuit_library_visualization(circuit: QuantumCircuit):
@@ -139,6 +129,7 @@ def properties_widget(circuit: QuantumCircuit) -> wid.VBox:
     return properties
 
 
+@_optionals.HAS_PYGMENTS.require_in_call
 @deprecate_func(
     since="0.25.0",
     additional_msg="This is unused by Qiskit, and no replacement will be publicly provided.",
@@ -151,16 +142,11 @@ def qasm_widget(circuit: QuantumCircuit) -> wid.VBox:
 
     Returns:
         Output widget.
-
-    Raises:
-        MissingOptionalLibraryError: If pygments is not installed
     """
-    if not HAS_PYGMENTS:
-        raise MissingOptionalLibraryError(
-            libname="pygments>2.4",
-            name="qasm_widget",
-            pip_install="pip install pygments",
-        )
+    import pygments
+    from pygments.formatters import HtmlFormatter
+    from qiskit.qasm.pygments import QasmHTMLStyle, OpenQASMLexer
+
     qasm_code = circuit.qasm()
     code = pygments.highlight(qasm_code, OpenQASMLexer(), HtmlFormatter())
 

qiskit/utils/optionals.py

@@ -113,6 +113,11 @@
       - For some graph visualisations, Qiskit uses `pydot <https://github.com/pydot/pydot>`__ as an
         interface to GraphViz (see :data:`HAS_GRAPHVIZ`).
 
+    * - .. py:data:: HAS_PYGMENTS
+      - Pygments is a code highlighter and formatter used by many environments that involve rich
+        display of code blocks, including Sphinx and Jupyter.  Qiskit uses this when producing rich
+        output for these environments.
+
     * - .. py:data:: HAS_PYLATEX
       - Various LaTeX-based visualizations, especially the circuit drawers, need access to the
         `pylatexenc <https://github.com/phfaist/pylatexenc>`__ project to work correctly.
@@ -261,6 +266,7 @@
 HAS_NLOPT = _LazyImportTester("nlopt", name="NLopt Optimizer", install="pip install nlopt")
 HAS_PIL = _LazyImportTester("PIL.Image", name="pillow", install="pip install pillow")
 HAS_PYDOT = _LazyImportTester("pydot", install="pip install pydot")
+HAS_PYGMENTS = _LazyImportTester("pygments", install="pip install pygments")
 HAS_PYLATEX = _LazyImportTester(
     {
         "pylatexenc.latex2text": ("LatexNodes2Text",),

releasenotes/notes/has-pygments-tester-3fb9f9c34907d45d.yaml

@@ -0,0 +1,5 @@
+---
+features:
+  - |
+    A new lazy import tester, :data:`.HAS_PYGMENTS`, is available for testing for the presence of
+    `the Pygments syntax highlighting library <https://pygments.org/>`__.

tools/find_optional_imports.py

@@ -25,6 +25,7 @@ def _main():
         "networkx",
         "sympy",
         "pydot",
+        "pygments",
         "ipywidgets",
         "scipy.stats",
         "matplotlib",