Merge pull request #10727 from jorisvandenbossche/sphinx-traceback

DOC: limit error traceback to one line for expected exceptions (GH10715)

Author: jorisvandenbossche

doc/source/advanced.rst

@@ -661,18 +661,14 @@ values NOT in the categories, similarly to how you can reindex ANY pandas index.
    Reshaping and Comparision operations on a ``CategoricalIndex`` must have the same categories
    or a ``TypeError`` will be raised.
 
-   .. code-block:: python
-
-      In [9]: df3 = pd.DataFrame({'A' : np.arange(6),
-                                  'B' : pd.Series(list('aabbca')).astype('category')})
-
-      In [11]: df3 = df3.set_index('B')
-
-      In [11]: df3.index
-      Out[11]: CategoricalIndex([u'a', u'a', u'b', u'b', u'c', u'a'], categories=[u'a', u'b', u'c'], ordered=False, name=u'B', dtype='category')
+   .. ipython:: python
+      :okexcept:
 
-      In [12]: pd.concat([df2, df3]
-      TypeError: categories must match existing categories when appending
+      df3 = pd.DataFrame({'A' : np.arange(6),
+                          'B' : pd.Series(list('aabbca')).astype('category')})
+      df3 = df3.set_index('B')
+      df3.index
+      pd.concat([df2, df3]
 
 .. _indexing.float64index:
 
@@ -738,20 +734,18 @@ In float indexes, slicing using floats is allowed
 
 In non-float indexes, slicing using floats will raise a ``TypeError``
 
-.. code-block:: python
-
-   In [1]: pd.Series(range(5))[3.5]
-   TypeError: the label [3.5] is not a proper indexer for this index type (Int64Index)
+.. ipython:: python
+   :okexcept:
 
-   In [1]: pd.Series(range(5))[3.5:4.5]
-   TypeError: the slice start [3.5] is not a proper indexer for this index type (Int64Index)
+   pd.Series(range(5))[3.5]
+   pd.Series(range(5))[3.5:4.5]
 
 Using a scalar float indexer will be deprecated in a future version, but is allowed for now.
 
-.. code-block:: python
+.. ipython:: python
+   :okwarning:
 
-   In [3]: pd.Series(range(5))[3.0]
-   Out[3]: 3
+   pd.Series(range(5))[3.0]
 
 Here is a typical use-case for using this type of indexing. Imagine that you have a somewhat
 irregular timedelta-like indexing scheme, but the data is recorded as floats. This could for

doc/source/basics.rst

@@ -352,13 +352,11 @@ objects of the same length:
 Trying to compare ``Index`` or ``Series`` objects of different lengths will
 raise a ValueError:
 
-.. code-block:: python
-
-    In [55]: pd.Series(['foo', 'bar', 'baz']) == pd.Series(['foo', 'bar'])
-    ValueError: Series lengths must match to compare
+.. ipython:: python
+    :okexcept:
 
-    In [56]: pd.Series(['foo', 'bar', 'baz']) == pd.Series(['foo'])
-    ValueError: Series lengths must match to compare
+    pd.Series(['foo', 'bar', 'baz']) == pd.Series(['foo', 'bar'])
+    pd.Series(['foo', 'bar', 'baz']) == pd.Series(['foo'])
 
 Note that this is different from the numpy behavior where a comparison can
 be broadcast:

doc/source/dsintro.rst

@@ -143,10 +143,10 @@ label:
 
 If a label is not contained, an exception is raised:
 
-.. code-block:: python
+.. ipython:: python
+    :okexcept:
 
-    >>> s['f']
-    KeyError: 'f'
+    s['f']
 
 Using the ``get`` method, a missing label will return None or specified default:
 

doc/source/indexing.rst

@@ -293,10 +293,10 @@ Selection By Label
      dfl = pd.DataFrame(np.random.randn(5,4), columns=list('ABCD'), index=pd.date_range('20130101',periods=5))
      dfl
 
-  .. code-block:: python
+  .. ipython:: python
+     :okexcept:
 
-     In [4]: dfl.loc[2:3]
-     TypeError: cannot do slice indexing on <class 'pandas.tseries.index.DatetimeIndex'> with these indexers [2] of <type 'int'>
+     dfl.loc[2:3]
 
   String likes in slicing *can* be convertible to the type of the index and lead to natural slicing.
 
@@ -475,13 +475,11 @@ A single indexer that is out of bounds will raise an ``IndexError``.
 A list of indexers where any element is out of bounds will raise an
 ``IndexError``
 
-.. code-block:: python
+.. ipython:: python
+   :okexcept:
 
    dfl.iloc[[4,5,6]]
-   IndexError: positional indexers are out-of-bounds
-
    dfl.iloc[:,4]
-   IndexError: single positional indexer is out-of-bounds
 
 .. _indexing.basics.partial_setting:
 

doc/source/options.rst

@@ -57,11 +57,7 @@ The following will **not work** because it matches multiple option names, e.g.
 .. ipython:: python
    :okexcept:
 
-   try:
-       pd.get_option("column")
-   except KeyError as e:
-       print(e)
-
+   pd.get_option("column")
 
 **Note:** Using this form of shorthand may cause your code to break if new options with similar names are added in future versions.
 

doc/source/timeseries.rst

@@ -205,9 +205,9 @@ Invalid Data
 Pass ``errors='coerce'`` to convert invalid data to ``NaT`` (not a time):
 
 .. ipython:: python
-   :okexcept:
 
    # this is the default, raise when unparseable
+   @okexcept
    to_datetime(['2009/07/31', 'asd'], errors='raise')
 
    # return the original input when unparseable
@@ -656,7 +656,7 @@ apply the offset to each element.
    rng + DateOffset(months=2)
    s + DateOffset(months=2)
    s - DateOffset(months=2)
-   
+
 If the offset class maps directly to a ``Timedelta`` (``Day``, ``Hour``,
 ``Minute``, ``Second``, ``Micro``, ``Milli``, ``Nano``) it can be
 used exactly like a ``Timedelta`` - see the
@@ -670,7 +670,7 @@ used exactly like a ``Timedelta`` - see the
    td + Minute(15)
 
 Note that some offsets (such as ``BQuarterEnd``) do not have a
-vectorized implementation.  They can still be used but may 
+vectorized implementation.  They can still be used but may
 calculate signficantly slower and will raise a ``PerformanceWarning``
 
 .. ipython:: python
@@ -1702,13 +1702,13 @@ the top example will fail as it contains ambiguous times and the bottom will
 infer the right offset.
 
 .. ipython:: python
-   :okexcept:
 
    rng_hourly = DatetimeIndex(['11/06/2011 00:00', '11/06/2011 01:00',
                                '11/06/2011 01:00', '11/06/2011 02:00',
                                '11/06/2011 03:00'])
 
    # This will fail as there are ambiguous times
+   @okexcept
    rng_hourly.tz_localize('US/Eastern')
    rng_hourly_eastern = rng_hourly.tz_localize('US/Eastern', ambiguous='infer')
    rng_hourly_eastern.tolist()

doc/sphinxext/ipython_sphinxext/ipython_directive.py

@@ -461,10 +461,6 @@ def process_input(self, data, input_prompt, lineno):
 
         self.cout.seek(0)
         output = self.cout.read()
-        if not is_suppress and not is_semicolon:
-            ret.append(output)
-        elif is_semicolon: # get spacing right
-            ret.append('')
 
         # context information
         filename = self.state.document.current_source
@@ -494,6 +490,16 @@ def process_input(self, data, input_prompt, lineno):
                 sys.stdout.write(s)
                 sys.stdout.write('<<<' + ('-' * 73) + '\n')
 
+        # if :okexcept: has been specified, display shorter traceback
+        if is_okexcept and "Traceback" in output:
+            traceback = output.split('\n\n')
+            output = traceback[-1]
+
+        if not is_suppress and not is_semicolon:
+            ret.append(output)
+        elif is_semicolon: # get spacing right
+            ret.append('')
+
         self.cout.truncate(0)
         return (ret, input_lines, output, is_doctest, decorator, image_file,
                     image_directive)