Merge remote-tracking branch 'upstream/master' into pd.array

Author: TomAugspurger

ci/code_checks.sh

@@ -175,7 +175,7 @@ if [[ -z "$CHECK" || "$CHECK" == "doctests" ]]; then
 
     MSG='Doctests frame.py' ; echo $MSG
     pytest -q --doctest-modules pandas/core/frame.py \
-        -k"-axes -combine -itertuples -join -pivot_table -quantile -query -reindex -reindex_axis -round"
+        -k"-axes -combine -itertuples -join -pivot_table -query -reindex -reindex_axis -round"
     RET=$(($RET + $?)) ; echo $MSG "DONE"
 
     MSG='Doctests series.py' ; echo $MSG

doc/source/10min.rst

@@ -1,24 +1,6 @@
 .. _10min:
 
-.. currentmodule:: pandas
-
-.. ipython:: python
-   :suppress:
-
-   import os
-   import numpy as np
-
-   import pandas as pd
-
-   np.random.seed(123456)
-   np.set_printoptions(precision=4, suppress=True)
-   pd.options.display.max_rows = 15
-
-   # portions of this were borrowed from the
-   # Pandas cheatsheet
-   # created during the PyData Workshop-Sprint 2012
-   # Hannah Chen, Henry Chow, Eric Cox, Robert Mauriello
-
+{{ header }}
 
 ********************
 10 Minutes to pandas
@@ -69,7 +51,7 @@ Creating a ``DataFrame`` by passing a dict of objects that can be converted to s
                        'F': 'foo'})
    df2
 
-The columns of the resulting ``DataFrame`` have different 
+The columns of the resulting ``DataFrame`` have different
 :ref:`dtypes <basics.dtypes>`.
 
 .. ipython:: python
@@ -83,7 +65,7 @@ will be completed:
 .. ipython::
 
    @verbatim
-   In [1]: df2.<TAB>
+   In [1]: df2.<TAB>  # noqa: E225, E999
    df2.A                  df2.bool
    df2.abs                df2.boxplot
    df2.add                df2.C
@@ -513,7 +495,7 @@ Another example that can be given is:
 Append
 ~~~~~~
 
-Append rows to a dataframe. See the :ref:`Appending <merging.concatenation>` 
+Append rows to a dataframe. See the :ref:`Appending <merging.concatenation>`
 section.
 
 .. ipython:: python
@@ -546,14 +528,14 @@ See the :ref:`Grouping section <groupby>`.
                       'D': np.random.randn(8)})
    df
 
-Grouping and then applying the :meth:`~DataFrame.sum` function to the resulting 
+Grouping and then applying the :meth:`~DataFrame.sum` function to the resulting
 groups.
 
 .. ipython:: python
 
    df.groupby('A').sum()
 
-Grouping by multiple columns forms a hierarchical index, and again we can 
+Grouping by multiple columns forms a hierarchical index, and again we can
 apply the ``sum`` function.
 
 .. ipython:: python
@@ -689,7 +671,7 @@ Convert the raw grades to a categorical data type.
     df["grade"] = df["raw_grade"].astype("category")
     df["grade"]
 
-Rename the categories to more meaningful names (assigning to 
+Rename the categories to more meaningful names (assigning to
 ``Series.cat.categories`` is inplace!).
 
 .. ipython:: python
@@ -738,7 +720,7 @@ See the :ref:`Plotting <visualization>` docs.
    @savefig series_plot_basic.png
    ts.plot()
 
-On a DataFrame, the :meth:`~DataFrame.plot` method is a convenience to plot all 
+On a DataFrame, the :meth:`~DataFrame.plot` method is a convenience to plot all
 of the columns with labels:
 
 .. ipython:: python
@@ -773,6 +755,7 @@ CSV
 .. ipython:: python
    :suppress:
 
+   import os
    os.remove('foo.csv')
 
 HDF5

doc/source/advanced.rst

@@ -1,15 +1,6 @@
 .. _advanced:
 
-.. currentmodule:: pandas
-
-.. ipython:: python
-   :suppress:
-
-   import numpy as np
-   import pandas as pd
-   np.random.seed(123456)
-   np.set_printoptions(precision=4, suppress=True)
-   pd.options.display.max_rows = 15
+{{ header }}
 
 ******************************
 MultiIndex / Advanced Indexing
@@ -62,8 +53,9 @@ The :class:`MultiIndex` object is the hierarchical analogue of the standard
 can think of ``MultiIndex`` as an array of tuples where each tuple is unique. A
 ``MultiIndex`` can be created from a list of arrays (using
 :meth:`MultiIndex.from_arrays`), an array of tuples (using
-:meth:`MultiIndex.from_tuples`), or a crossed set of iterables (using
-:meth:`MultiIndex.from_product`).  The ``Index`` constructor will attempt to return
+:meth:`MultiIndex.from_tuples`), a crossed set of iterables (using
+:meth:`MultiIndex.from_product`), or a :class:`DataFrame` (using 
+:meth:`MultiIndex.from_frame`).  The ``Index`` constructor will attempt to return
 a ``MultiIndex`` when it is passed a list of tuples.  The following examples
 demonstrate different ways to initialize MultiIndexes.
 
@@ -89,6 +81,19 @@ to use the :meth:`MultiIndex.from_product` method:
    iterables = [['bar', 'baz', 'foo', 'qux'], ['one', 'two']]
    pd.MultiIndex.from_product(iterables, names=['first', 'second'])
 
+You can also construct a ``MultiIndex`` from a ``DataFrame`` directly, using 
+the method :meth:`MultiIndex.from_frame`. This is a complementary method to
+:meth:`MultiIndex.to_frame`.
+
+.. versionadded:: 0.24.0
+
+.. ipython:: python
+
+   df = pd.DataFrame([['bar', 'one'], ['bar', 'two'],
+                      ['foo', 'one'], ['foo', 'two']],
+                     columns=['first', 'second'])
+   pd.MultiIndex.from_frame(df)
+
 As a convenience, you can pass a list of arrays directly into ``Series`` or
 ``DataFrame`` to construct a ``MultiIndex`` automatically:
 
@@ -558,7 +563,8 @@ they need to be sorted. As with any index, you can use :meth:`~DataFrame.sort_in
 
 .. ipython:: python
 
-   import random; random.shuffle(tuples)
+   import random
+   random.shuffle(tuples)
    s = pd.Series(np.random.randn(8), index=pd.MultiIndex.from_tuples(tuples))
    s
    s.sort_index()

doc/source/api.rst

@@ -1,6 +1,7 @@
-.. currentmodule:: pandas
 .. _api:
 
+{{ header }}
+
 *************
 API Reference
 *************
@@ -1776,6 +1777,7 @@ MultiIndex Constructors
    MultiIndex.from_arrays
    MultiIndex.from_tuples
    MultiIndex.from_product
+   MultiIndex.from_frame
 
 MultiIndex Attributes
 ~~~~~~~~~~~~~~~~~~~~~

doc/source/basics.rst

@@ -1,16 +1,7 @@
-.. currentmodule:: pandas
-
-.. ipython:: python
-   :suppress:
-
-   import numpy as np
-   import pandas as pd
-
-   np.set_printoptions(precision=4, suppress=True)
-   pd.options.display.max_rows = 15
-
 .. _basics:
 
+{{ header }}
+
 ==============================
  Essential Basic Functionality
 ==============================

doc/source/categorical.rst

@@ -1,16 +1,6 @@
 .. _categorical:
 
-.. currentmodule:: pandas
-
-.. ipython:: python
-   :suppress:
-
-   import numpy as np
-   import pandas as pd
-   np.random.seed(123456)
-   np.set_printoptions(precision=4, suppress=True)
-   pd.options.display.max_rows = 15
-
+{{ header }}
 
 ****************
 Categorical Data
@@ -792,7 +782,7 @@ Setting values by assigning categorical data will also check that the `categorie
     df
     try:
         df.loc["j":"k", "cats"] = pd.Categorical(["b", "b"],
-                                                  categories=["a", "b", "c"])
+                                                 categories=["a", "b", "c"])
     except ValueError as e:
         print("ValueError:", str(e))
 

doc/source/comparison_with_r.rst

@@ -1,12 +1,6 @@
-.. currentmodule:: pandas
 .. _compare_with_r:
 
-.. ipython:: python
-   :suppress:
-
-   import pandas as pd
-   import numpy as np
-   pd.options.display.max_rows = 15
+{{ header }}
 
 Comparison with R / R libraries
 *******************************

doc/source/comparison_with_sas.rst

@@ -1,6 +1,7 @@
-.. currentmodule:: pandas
 .. _compare_with_sas:
 
+{{ header }}
+
 Comparison with SAS
 ********************
 For potential users coming from `SAS <https://en.wikipedia.org/wiki/SAS_(software)>`__

doc/source/comparison_with_sql.rst

@@ -1,6 +1,7 @@
-.. currentmodule:: pandas
 .. _compare_with_sql:
 
+{{ header }}
+
 Comparison with SQL
 ********************
 Since many potential pandas users have some familiarity with

doc/source/comparison_with_stata.rst

@@ -1,6 +1,7 @@
-.. currentmodule:: pandas
 .. _compare_with_stata:
 
+{{ header }}
+
 Comparison with Stata
 *********************
 For potential users coming from `Stata <https://en.wikipedia.org/wiki/Stata>`__
@@ -675,5 +676,3 @@ If out of core processing is needed, one possibility is the
 `dask.dataframe <http://dask.pydata.org/en/latest/dataframe.html>`_
 library, which provides a subset of pandas functionality for an
 on-disk ``DataFrame``.
-
-

doc/source/computation.rst

@@ -1,21 +1,7 @@
-.. currentmodule:: pandas
-
-.. ipython:: python
-   :suppress:
-
-   import numpy as np
-   import matplotlib.pyplot as plt
-
-   import pandas as pd
-
-   np.random.seed(123456)
-   np.set_printoptions(precision=4, suppress=True)
-   pd.options.display.max_rows = 15
-
-   plt.close('all')
-
 .. _computation:
 
+{{ header }}
+
 Computational tools
 ===================
 

doc/source/conf.py

@@ -301,25 +301,25 @@
 }
 
 
-common_imports = """\
+header = """\
 .. currentmodule:: pandas
 
 .. ipython:: python
    :suppress:
 
    import numpy as np
-   from pandas import *
    import pandas as pd
+
    randn = np.random.randn
+   np.random.seed(123456)
    np.set_printoptions(precision=4, suppress=True)
-   options.display.max_rows = 15
-   from pandas.compat import StringIO
+   pd.options.display.max_rows = 15
 """
 
 
 html_context = {
     'redirects': {old: new for old, new in moved_api_pages},
-    'common_imports': common_imports,
+    'header': header
 }
 
 # If false, no module index is generated.

doc/source/contributing.rst

@@ -1,5 +1,7 @@
 .. _contributing:
 
+{{ header }}
+
 **********************
 Contributing to pandas
 **********************
@@ -672,6 +674,7 @@ Otherwise, you need to do it manually:
 
     import warnings
 
+
     def old_func():
         """Summary of the function.
 
@@ -681,6 +684,7 @@ Otherwise, you need to do it manually:
         warnings.warn('Use new_func instead.', FutureWarning, stacklevel=2)
         new_func()
 
+
     def new_func():
         pass
 
@@ -816,7 +820,6 @@ We would name this file ``test_cool_feature.py`` and put in an appropriate place
    import pytest
    import numpy as np
    import pandas as pd
-   from pandas.util import testing as tm
 
 
    @pytest.mark.parametrize('dtype', ['int8', 'int16', 'int32', 'int64'])
@@ -938,8 +941,10 @@ If your change involves checking that a warning is actually emitted, use
 
 .. code-block:: python
 
-   df = pd.DataFrame()
+   import pandas.util.testing as tm
+
 
+   df = pd.DataFrame()
    with tm.assert_produces_warning(FutureWarning):
        df.some_operation()
 

doc/source/contributing_docstring.rst

@@ -1,13 +1,11 @@
 .. _docstring:
 
+{{ header }}
+
 ======================
 pandas docstring guide
 ======================
 
-.. note::
-  `Video tutorial: Pandas docstring guide
-  <https://www.youtube.com/watch?v=EOA0lUeW4NI>`_ by Frank Akogun.
-
 About docstrings and standards
 ------------------------------