Better error message for unescaped underscores

timhoffm · timhoffm · commit a2728f1e033c · 2020-08-26T00:29:03.000+02:00
diff --git a/lib/matplotlib/tests/test_texmanager.py b/lib/matplotlib/tests/test_texmanager.py
@@ -1,3 +1,5 @@
+import pytest
+
 import matplotlib.pyplot as plt
 from matplotlib.texmanager import TexManager
 
@@ -16,3 +18,13 @@ def test_fontconfig_preamble():
     font_config2 = tm2.get_font_config()
 
     assert font_config1 != font_config2
+
+
+def test_usetex_missing_underscore():
+    """
+    Test that failed TeX rendering due to an unescaped underscore has a
+    custom error message.
+    """
+    with pytest.raises(RuntimeError, match='caused by an unescaped underscore'):
+        plt.text(0, 0, 'foo_bar', usetex=True)
+        plt.draw()  # TeX rendering is done at draw time
diff --git a/lib/matplotlib/texmanager.py b/lib/matplotlib/texmanager.py
@@ -281,14 +281,38 @@ def _run_checked_subprocess(self, command, tex, *, cwd=None):
                 'Failed to process string with tex because {} could not be '
                 'found'.format(command[0])) from exc
         except subprocess.CalledProcessError as exc:
-            raise RuntimeError(
-                '{prog} was not able to process the following string:\n'
-                '{tex!r}\n\n'
-                'Here is the full report generated by {prog}:\n'
-                '{exc}\n\n'.format(
-                    prog=command[0],
-                    tex=tex.encode('unicode_escape'),
-                    exc=exc.output.decode('utf-8'))) from exc
+            tex_log = exc.output.decode('utf-8')
+
+            # whether the exception was likely caused by an unescaped
+            # underscore. This cannot be easily determined unambiguously.
+            # By requiring `'$' not in tex` we err on the side of preventing
+            # false positives, because we only want to issue the customized
+            # error message if we are sure there's an unescaped underscore.
+            unescaped_underscore = (
+                '_' in tex and '$' not in tex and
+                re.match(r'.*Missing \$ inserted.*_\n', tex_log,
+                         flags=re.DOTALL)
+            )
+            if unescaped_underscore:
+                message = (
+                    '{prog} was not able to process the following string:\n'
+                    '{tex!r}\n\n'
+                    'This is likely caused by an unescaped underscore.\n'
+                    'You may escape the underscore or add '
+                    'r"\\usepackage{{underscore}}"\n'
+                    'to the matplotlib rcParam text.latex.preamble'.format(
+                        prog=command[0],
+                        tex=tex.encode('unicode_escape')))
+            else:
+                message = (
+                    '{prog} was not able to process the following string:\n'
+                    '{tex!r}\n\n'
+                    'Here is the full report generated by {prog}:\n'
+                    '{exc}\n\n'.format(
+                        prog=command[0],
+                        tex=tex.encode('unicode_escape'),
+                        exc=tex_log))
+            raise RuntimeError(message) from exc
         _log.debug(report)
         return report
 
