Update docstring _restore_dropped_levels_multijoin

Author: harisbal

ci/code_checks.sh

@@ -44,6 +44,14 @@ if [[ -z "$CHECK" || "$CHECK" == "lint" ]]; then
     flake8 pandas/_libs --filename=*.pxi.in,*.pxd --select=E501,E302,E203,E111,E114,E221,E303,E231,E126,F403
     RET=$(($RET + $?)) ; echo $MSG "DONE"
 
+    # Check that cython casting is of the form `<type>obj` as opposed to `<type> obj`;
+    # it doesn't make a difference, but we want to be internally consistent.
+    # Note: this grep pattern is (intended to be) equivalent to the python
+    # regex r'(?<![ ->])> '
+    MSG='Linting .pyx code for spacing conventions in casting' ; echo $MSG
+    ! grep -r -E --include '*.pyx' --include '*.pxi.in' '> ' pandas/_libs | grep -v '[ ->]> '
+    RET=$(($RET + $?)) ; echo $MSG "DONE"
+
     # readability/casting: Warnings about C casting instead of C++ casting
     # runtime/int: Warnings about using C number types instead of C++ ones
     # build/include_subdir: Warnings about prefacing included header files with directory

doc/source/contributing.rst

@@ -612,6 +612,54 @@ Alternatively, you can install the ``grep`` and ``xargs`` commands via the
 `MinGW <http://www.mingw.org/>`__ toolchain, and it will allow you to run the
 commands above.
 
+.. _contributing.import-formatting:
+
+Import Formatting
+~~~~~~~~~~~~~~~~~
+*pandas* uses `isort <https://pypi.org/project/isort/>`__ to standardise import
+formatting across the codebase.
+
+A guide to import layout as per pep8 can be found `here <https://www.python.org/dev/peps/pep-0008/#imports/>`__.
+
+A summary of our current import sections ( in order ):
+
+* Future
+* Python Standard Library
+* Third Party
+* ``pandas._libs``, ``pandas.compat``, ``pandas.util._*``, ``pandas.errors`` (largely not dependent on ``pandas.core``)
+* ``pandas.core.dtypes`` (largely not dependent on the rest of ``pandas.core``)
+* Rest of ``pandas.core.*``
+* Non-core ``pandas.io``, ``pandas.plotting``, ``pandas.tseries``
+* Local application/library specific imports
+
+Imports are alphabetically sorted within these sections.
+
+
+As part of :ref:`Continuous Integration <contributing.ci>` checks we run::
+
+    isort --recursive --check-only pandas
+
+to check that imports are correctly formatted as per the `setup.cfg`.
+
+If you see output like the below in :ref:`Continuous Integration <contributing.ci>` checks:
+
+.. code-block:: shell
+
+   Check import format using isort
+   ERROR: /home/travis/build/pandas-dev/pandas/pandas/io/pytables.py Imports are incorrectly sorted
+   Check import format using isort DONE
+   The command "ci/code_checks.sh" exited with 1
+
+You should run::
+
+    isort pandas/io/pytables.py
+
+to automatically format imports correctly. This will modify your local copy of the files.
+
+The `--recursive` flag can be passed to sort all files in a directory.
+
+You can then verify the changes look ok, then git :ref:`commit <contributing.commit-code>` and :ref:`push <contributing.push-code>`.
+
 Backwards Compatibility
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1078,6 +1126,8 @@ or a new keyword argument (`example <https://github.com/pandas-dev/pandas/blob/v
 Contributing your changes to *pandas*
 =====================================
 
+.. _contributing.commit-code:
+
 Committing your code
 --------------------
 
@@ -1122,6 +1172,8 @@ Now you can commit your changes in your local repository::
 
     git commit -m
 
+.. _contributing.push-code:
+
 Pushing your changes
 --------------------
 

doc/source/whatsnew/v0.24.0.txt

@@ -1191,6 +1191,7 @@ Timezones
 - Bug in :meth:`DatetimeIndex.unique` that did not re-localize tz-aware dates correctly (:issue:`21737`)
 - Bug when indexing a :class:`Series` with a DST transition (:issue:`21846`)
 - Bug in :meth:`DataFrame.resample` and :meth:`Series.resample` where an ``AmbiguousTimeError`` or ``NonExistentTimeError`` would raise if a timezone aware timeseries ended on a DST transition (:issue:`19375`, :issue:`10117`)
+- Bug in :meth:`DataFrame.drop` and :meth:`Series.drop` when specifying a tz-aware Timestamp key to drop from a :class:`DatetimeIndex` with a DST transition (:issue:`21761`)
 
 Offsets
 ^^^^^^^

pandas/_libs/algos.pyx

@@ -32,7 +32,7 @@ import missing
 
 cdef float64_t FP_ERR = 1e-13
 
-cdef double NaN = <double> np.NaN
+cdef double NaN = <double>np.NaN
 cdef double nan = NaN
 
 cdef int64_t iNaT = get_nat()
@@ -242,7 +242,7 @@ def nancorr(ndarray[float64_t, ndim=2] mat, bint cov=0, minp=None):
         int64_t nobs = 0
         float64_t vx, vy, sumx, sumy, sumxx, sumyy, meanx, meany, divisor
 
-    N, K = (<object> mat).shape
+    N, K = (<object>mat).shape
 
     if minp is None:
         minpv = 1
@@ -307,7 +307,7 @@ def nancorr_spearman(ndarray[float64_t, ndim=2] mat, Py_ssize_t minp=1):
         int64_t nobs = 0
         float64_t vx, vy, sumx, sumxx, sumyy, mean, divisor
 
-    N, K = (<object> mat).shape
+    N, K = (<object>mat).shape
 
     result = np.empty((K, K), dtype=np.float64)
     mask = np.isfinite(mat).view(np.uint8)
@@ -531,7 +531,7 @@ def pad_2d_inplace(ndarray[algos_t, ndim=2] values,
         algos_t val
         int lim, fill_count = 0
 
-    K, N = (<object> values).shape
+    K, N = (<object>values).shape
 
     # GH#2778
     if N == 0:
@@ -730,7 +730,7 @@ def backfill_2d_inplace(ndarray[algos_t, ndim=2] values,
         algos_t val
         int lim, fill_count = 0
 
-    K, N = (<object> values).shape
+    K, N = (<object>values).shape
 
     # GH#2778
     if N == 0:

pandas/_libs/algos_common_helper.pxi.in

@@ -34,7 +34,7 @@ def diff_2d_{{name}}(ndarray[{{c_type}}, ndim=2] arr,
     cdef:
         Py_ssize_t i, j, sx, sy
 
-    sx, sy = (<object> arr).shape
+    sx, sy = (<object>arr).shape
     if arr.flags.f_contiguous:
         if axis == 0:
             if periods >= 0:
@@ -88,14 +88,14 @@ def put2d_{{name}}_{{dest_name}}(ndarray[{{c_type}}, ndim=2, cast=True] values,
 # ensure_dtype
 #----------------------------------------------------------------------
 
-cdef int PLATFORM_INT = (<ndarray> np.arange(0, dtype=np.intp)).descr.type_num
+cdef int PLATFORM_INT = (<ndarray>np.arange(0, dtype=np.intp)).descr.type_num
 
 
 def ensure_platform_int(object arr):
     # GH3033, GH1392
     # platform int is the size of the int pointer, e.g. np.intp
     if util.is_array(arr):
-        if (<ndarray> arr).descr.type_num == PLATFORM_INT:
+        if (<ndarray>arr).descr.type_num == PLATFORM_INT:
             return arr
         else:
             return arr.astype(np.intp)
@@ -105,7 +105,7 @@ def ensure_platform_int(object arr):
 
 def ensure_object(object arr):
     if util.is_array(arr):
-        if (<ndarray> arr).descr.type_num == NPY_OBJECT:
+        if (<ndarray>arr).descr.type_num == NPY_OBJECT:
             return arr
         else:
             return arr.astype(np.object_)
@@ -142,7 +142,7 @@ def get_dispatch(dtypes):
 
 def ensure_{{name}}(object arr, copy=True):
     if util.is_array(arr):
-        if (<ndarray> arr).descr.type_num == NPY_{{c_type}}:
+        if (<ndarray>arr).descr.type_num == NPY_{{c_type}}:
             return arr
         else:
             return arr.astype(np.{{dtype}}, copy=copy)

pandas/_libs/algos_rank_helper.pxi.in

@@ -263,7 +263,7 @@ def rank_2d_{{dtype}}(object in_arr, axis=0, ties_method='average',
     np.putmask(values, mask, nan_value)
     {{endif}}
 
-    n, k = (<object> values).shape
+    n, k = (<object>values).shape
     ranks = np.empty((n, k), dtype='f8')
 
     {{if dtype == 'object'}}

pandas/_libs/algos_take_helper.pxi.in

@@ -278,7 +278,7 @@ cdef _take_2d(ndarray[take_t, ndim=2] values, object idx):
         ndarray[take_t, ndim=2] result
         object val
 
-    N, K = (<object> values).shape
+    N, K = (<object>values).shape
 
     if take_t is object:
         # evaluated at compile-time

pandas/_libs/groupby.pyx

@@ -22,7 +22,7 @@ from algos import take_2d_axis1_float64_float64, groupsort_indexer, tiebreakers
 
 cdef int64_t iNaT = get_nat()
 
-cdef double NaN = <double> np.NaN
+cdef double NaN = <double>np.NaN
 cdef double nan = NaN
 
 
@@ -115,7 +115,7 @@ def group_median_float64(ndarray[float64_t, ndim=2] out,
     assert min_count == -1, "'min_count' only used in add and prod"
 
     ngroups = len(counts)
-    N, K = (<object> values).shape
+    N, K = (<object>values).shape
 
     indexer, _counts = groupsort_indexer(labels, ngroups)
     counts[:] = _counts[1:]
@@ -152,7 +152,7 @@ def group_cumprod_float64(float64_t[:, :] out,
         float64_t[:, :] accum
         int64_t lab
 
-    N, K = (<object> values).shape
+    N, K = (<object>values).shape
     accum = np.ones_like(values)
 
     with nogil:
@@ -189,7 +189,7 @@ def group_cumsum(numeric[:, :] out,
         numeric[:, :] accum
         int64_t lab
 
-    N, K = (<object> values).shape
+    N, K = (<object>values).shape
     accum = np.zeros_like(values)
 
     with nogil:
@@ -226,7 +226,7 @@ def group_shift_indexer(ndarray[int64_t] out, ndarray[int64_t] labels,
         int64_t[:] label_seen = np.zeros(ngroups, dtype=np.int64)
         int64_t[:, :] label_indexer
 
-    N, = (<object> labels).shape
+    N, = (<object>labels).shape
 
     if periods < 0:
         periods = -periods

pandas/_libs/groupby_helper.pxi.in

@@ -48,7 +48,7 @@ def group_add_{{name}}(ndarray[{{c_type}}, ndim=2] out,
     nobs = np.zeros_like(out)
     sumx = np.zeros_like(out)
 
-    N, K = (<object> values).shape
+    N, K = (<object>values).shape
 
     with nogil:
 
@@ -95,7 +95,7 @@ def group_prod_{{name}}(ndarray[{{c_type}}, ndim=2] out,
     nobs = np.zeros_like(out)
     prodx = np.ones_like(out)
 
-    N, K = (<object> values).shape
+    N, K = (<object>values).shape
 
     with nogil:
         for i in range(N):
@@ -141,7 +141,7 @@ def group_var_{{name}}(ndarray[{{c_type}}, ndim=2] out,
     nobs = np.zeros_like(out)
     mean = np.zeros_like(out)
 
-    N, K = (<object> values).shape
+    N, K = (<object>values).shape
 
     out[:, :] = 0.0
 
@@ -193,7 +193,7 @@ def group_mean_{{name}}(ndarray[{{c_type}}, ndim=2] out,
     nobs = np.zeros_like(out)
     sumx = np.zeros_like(out)
 
-    N, K = (<object> values).shape
+    N, K = (<object>values).shape
 
     with nogil:
         for i in range(N):
@@ -238,7 +238,7 @@ def group_ohlc_{{name}}(ndarray[{{c_type}}, ndim=2] out,
     if len(labels) == 0:
         return
 
-    N, K = (<object> values).shape
+    N, K = (<object>values).shape
 
     if out.shape[1] != 4:
         raise ValueError('Output array must have 4 columns')
@@ -312,14 +312,14 @@ def group_last_{{name}}(ndarray[{{c_type}}, ndim=2] out,
     if not len(values) == len(labels):
         raise AssertionError("len(index) != len(labels)")
 
-    nobs = np.zeros((<object> out).shape, dtype=np.int64)
+    nobs = np.zeros((<object>out).shape, dtype=np.int64)
     {{if name == 'object'}}
-    resx = np.empty((<object> out).shape, dtype=object)
+    resx = np.empty((<object>out).shape, dtype=object)
     {{else}}
     resx = np.empty_like(out)
     {{endif}}
 
-    N, K = (<object> values).shape
+    N, K = (<object>values).shape
 
     {{if name == "object"}}
     if True:  # make templating happy
@@ -369,14 +369,14 @@ def group_nth_{{name}}(ndarray[{{c_type}}, ndim=2] out,
     if not len(values) == len(labels):
         raise AssertionError("len(index) != len(labels)")
 
-    nobs = np.zeros((<object> out).shape, dtype=np.int64)
+    nobs = np.zeros((<object>out).shape, dtype=np.int64)
     {{if name=='object'}}
-    resx = np.empty((<object> out).shape, dtype=object)
+    resx = np.empty((<object>out).shape, dtype=object)
     {{else}}
     resx = np.empty_like(out)
     {{endif}}
 
-    N, K = (<object> values).shape
+    N, K = (<object>values).shape
 
     {{if name == "object"}}
     if True:  # make templating happy
@@ -462,7 +462,7 @@ def group_rank_{{name}}(ndarray[float64_t, ndim=2] out,
 
     tiebreak = tiebreakers[ties_method]
     keep_na = na_option == 'keep'
-    N, K = (<object> values).shape
+    N, K = (<object>values).shape
     grp_sizes = np.ones_like(out)
 
     # Copy values into new array in order to fill missing data
@@ -635,7 +635,7 @@ def group_max(ndarray[groupby_t, ndim=2] out,
         maxx.fill(-np.inf)
         nan_val = NAN
 
-    N, K = (<object> values).shape
+    N, K = (<object>values).shape
 
     with nogil:
         for i in range(N):
@@ -697,7 +697,7 @@ def group_min(ndarray[groupby_t, ndim=2] out,
         minx.fill(np.inf)
         nan_val = NAN
 
-    N, K = (<object> values).shape
+    N, K = (<object>values).shape
 
     with nogil:
         for i in range(N):
@@ -744,7 +744,7 @@ def group_cummin(ndarray[groupby_t, ndim=2] out,
         ndarray[groupby_t, ndim=2] accum
         int64_t lab
 
-    N, K = (<object> values).shape
+    N, K = (<object>values).shape
     accum = np.empty_like(values)
     if groupby_t is int64_t:
         accum.fill(_int64_max)
@@ -792,7 +792,7 @@ def group_cummax(ndarray[groupby_t, ndim=2] out,
         ndarray[groupby_t, ndim=2] accum
         int64_t lab
 
-    N, K = (<object> values).shape
+    N, K = (<object>values).shape
     accum = np.empty_like(values)
     if groupby_t is int64_t:
         accum.fill(-_int64_max)

pandas/_libs/hashtable_class_helper.pxi.in

@@ -318,7 +318,7 @@ cdef class {{name}}HashTable(HashTable):
             for i in range(n):
                 key = keys[i]
                 k = kh_put_{{dtype}}(self.table, key, &ret)
-                self.table.vals[k] = <Py_ssize_t> values[i]
+                self.table.vals[k] = <Py_ssize_t>values[i]
 
     @cython.boundscheck(False)
     def map_locations(self, ndarray[{{dtype}}_t, ndim=1] values):

pandas/_libs/join.pyx

@@ -11,7 +11,7 @@ from numpy cimport (ndarray,
 cnp.import_array()
 
 
-cdef double NaN = <double> np.NaN
+cdef double NaN = <double>np.NaN
 cdef double nan = NaN
 
 from pandas._libs.algos import groupsort_indexer, ensure_platform_int