DOC: Don't show traceback for :okexcept:

- use local modified ipython_directive to add optional no_traceback
  argument to :ok_except: which prevents the (sometimes long) traceback
  from being printed (default is no argument, i.e. the traceback is
  printed) and enable the @okexcept pseudodecorator so that it can be
  applied to individual instructions instead of the whole block
- use local modified ipython_console_highlighting to enable syntax
  highlighting of exceptions without a traceback
- fix pylint warnings for ipython_directive.py and simplify
  "".join(["."] * x) to "." * x

The "# noqa: E999" after "@okexcept no_traceback" is necessary to
prevent flake8-rst from complaining about syntax errors as it
interprets the pseudodecorator as a real python decorator.

Items 1 and 2 can be reverted if github.com/ipython/ipython/pull/13751
gets merged upstream.

Author: StefRe

doc/source/conf.py

@@ -51,8 +51,8 @@
 
 extensions = [
     "contributors",  # custom pandas extension
-    "IPython.sphinxext.ipython_directive",
-    "IPython.sphinxext.ipython_console_highlighting",
+    "ipython_sphinxext.ipython_directive",
+    "ipython_sphinxext.ipython_console_highlighting",
     "matplotlib.sphinxext.plot_directive",
     "numpydoc",
     "sphinx_copybutton",

doc/source/user_guide/categorical.rst

@@ -356,20 +356,16 @@ Renaming categories is done by using the
 Categories must be unique or a ``ValueError`` is raised:
 
 .. ipython:: python
+   :okexcept: no_traceback
 
-    try:
-        s = s.cat.rename_categories([1, 1, 1])
-    except ValueError as e:
-        print("ValueError:", str(e))
+    s = s.cat.rename_categories([1, 1, 1])
 
 Categories must also not be ``NaN`` or a ``ValueError`` is raised:
 
 .. ipython:: python
+   :okexcept: no_traceback
 
-    try:
-        s = s.cat.rename_categories([1, 2, np.nan])
-    except ValueError as e:
-        print("ValueError:", str(e))
+    s = s.cat.rename_categories([1, 2, np.nan])
 
 Appending new categories
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -572,11 +568,9 @@ Equality comparisons work with any list-like object of same length and scalars:
 This doesn't work because the categories are not the same:
 
 .. ipython:: python
+   :okexcept: no_traceback
 
-    try:
-        cat > cat_base2
-    except TypeError as e:
-        print("TypeError:", str(e))
+    cat > cat_base2
 
 If you want to do a "non-equality" comparison of a categorical series with a list-like object
 which is not categorical data, you need to be explicit and convert the categorical data back to
@@ -586,10 +580,8 @@ the original values:
 
     base = np.array([1, 2, 3])
 
-    try:
-        cat > base
-    except TypeError as e:
-        print("TypeError:", str(e))
+    @okexcept no_traceback  # noqa: E999
+    cat > base
 
     np.asarray(cat) > base
 
@@ -768,21 +760,17 @@ value is included in the ``categories``:
 
     df.iloc[2:4, :] = [["b", 2], ["b", 2]]
     df
-    try:
-        df.iloc[2:4, :] = [["c", 3], ["c", 3]]
-    except TypeError as e:
-        print("TypeError:", str(e))
+    @okexcept no_traceback   # noqa: E999
+    df.iloc[2:4, :] = [["c", 3], ["c", 3]]
 
 Setting values by assigning categorical data will also check that the ``categories`` match:
 
 .. ipython:: python
 
     df.loc["j":"k", "cats"] = pd.Categorical(["a", "a"], categories=["a", "b"])
     df
-    try:
-        df.loc["j":"k", "cats"] = pd.Categorical(["b", "b"], categories=["a", "b", "c"])
-    except TypeError as e:
-        print("TypeError:", str(e))
+    @okexcept no_traceback  # noqa: E999
+    df.loc["j":"k", "cats"] = pd.Categorical(["b", "b"], categories=["a", "b", "c"])
 
 Assigning a ``Categorical`` to parts of a column of other types will use the values:
 
@@ -1067,16 +1055,12 @@ NumPy itself doesn't know about the new ``dtype``:
 
 .. ipython:: python
 
-    try:
-        np.dtype("category")
-    except TypeError as e:
-        print("TypeError:", str(e))
+    @okexcept no_traceback  # noqa: E999
+    np.dtype("category")
 
     dtype = pd.Categorical(["a"]).dtype
-    try:
-        np.dtype(dtype)
-    except TypeError as e:
-        print("TypeError:", str(e))
+    @okexcept no_traceback  # noqa: E999
+    np.dtype(dtype)
 
 Dtype comparisons work:
 
@@ -1098,11 +1082,9 @@ are not numeric data (even in the case that ``.categories`` is numeric).
 .. ipython:: python
 
     s = pd.Series(pd.Categorical([1, 2, 3, 4]))
-    try:
-        np.sum(s)
-        # same with np.log(s),...
-    except TypeError as e:
-        print("TypeError:", str(e))
+    @okexcept no_traceback  # noqa: E999
+    np.sum(s)
+    # same with np.log(s),...
 
 .. note::
     If such a function works, please file a bug at https://github.com/pandas-dev/pandas!

doc/sphinxext/ipython_sphinxext/__init__.py

@@ -0,0 +1,60 @@
+"""
+reST directive for syntax-highlighting ipython interactive sessions.
+
+"""
+
+from IPython.lib.lexers import IPyLexer
+from sphinx import highlighting
+
+
+def patch_IPythonConsoleLexer():
+    """Patch lexers.IPythonConsoleLexer.ipytb_start.
+
+    This extension uses IPyLexer to highlight the exception. An exception is
+    recognized by the traceback. The start of a traceback is found using the
+    ipytb_start regex. This regex has to be patched to also find exceptions
+    without a preceding traceback.
+    """
+    import builtins
+    import re
+
+    import IPython.lib.lexers as lexers
+
+    exceptions = [
+        name
+        for name, value in builtins.__dict__.items()
+        if isinstance(value, type)
+        and issubclass(value, Exception)
+        and not issubclass(value, Warning)
+    ]
+    lexers.IPythonConsoleLexer.ipytb_start = re.compile(
+        r"^(\^C)?(-+\n)|^(  File)(.*)(, line )(\d+\n)|^("
+        + "|".join(exceptions)
+        + r"): \S.*\n"
+    )
+
+
+patch_IPythonConsoleLexer()
+
+
+def setup(app):
+    """Setup as a sphinx extension."""
+
+    # This is only a lexer, so adding it below to pygments appears sufficient.
+    # But if somebody knows what the right API usage should be to do that via
+    # sphinx, by all means fix it here.  At least having this setup.py
+    # suppresses the sphinx warning we'd get without it.
+    metadata = {"parallel_read_safe": True, "parallel_write_safe": True}
+    return metadata
+
+
+# Register the extension as a valid pygments lexer.
+# Alternatively, we could register the lexer with pygments instead. This would
+# require using setuptools entrypoints: http://pygments.org/docs/plugins
+
+ipy2 = IPyLexer(python3=False)
+ipy3 = IPyLexer(python3=True)
+
+highlighting.lexers["ipython"] = ipy2
+highlighting.lexers["ipython2"] = ipy2
+highlighting.lexers["ipython3"] = ipy3