|
5 | 5 | This is an experimental API and subject to breaking changes
|
6 | 6 | without warning.
|
7 | 7 | """
|
8 |
| -import textwrap |
9 |
| - |
10 | 8 | import numpy as np
|
11 | 9 |
|
12 | 10 | from pandas.errors import AbstractMethodError
|
13 | 11 | from pandas.compat.numpy import function as nv
|
14 |
| -from pandas.util._decorators import Appender, Substitution |
15 | 12 |
|
16 | 13 | _not_implemented_message = "{} does not implement {}."
|
17 | 14 |
|
18 | 15 |
|
19 |
| -_take_docstring = textwrap.dedent("""\ |
20 |
| -Take elements from an array. |
21 |
| -
|
22 |
| -Parameters |
23 |
| ----------- |
24 |
| -%(arr)s\ |
25 |
| -indexer : sequence of integers |
26 |
| - Indices to be taken. See Notes for how negative indicies |
27 |
| - are handled. |
28 |
| -fill_value : any, optional |
29 |
| - Fill value to use for NA-indicies. This has a few behaviors. |
30 |
| -
|
31 |
| - * fill_value is not specified : triggers NumPy's semantics |
32 |
| - where negative values in `indexer` mean slices from the end. |
33 |
| - * fill_value is NA : Fill positions where `indexer` is ``-1`` |
34 |
| - with ``self.dtype.na_value``. Anything considered NA by |
35 |
| - :func:`pandas.isna` will result in ``self.dtype.na_value`` |
36 |
| - being used to fill. |
37 |
| - * fill_value is not NA : Fill positions where `indexer` is ``-1`` |
38 |
| - with `fill_value`. |
39 |
| -
|
40 |
| -Returns |
41 |
| -------- |
42 |
| -ExtensionArray |
43 |
| -
|
44 |
| -Raises |
45 |
| ------- |
46 |
| -IndexError |
47 |
| - When the indexer is out of bounds for the array. |
48 |
| -ValueError |
49 |
| - When the indexer contains negative values other than ``-1`` |
50 |
| - and `fill_value` is specified. |
51 |
| -
|
52 |
| -Notes |
53 |
| ------ |
54 |
| -The meaning of negative values in `indexer` depends on the |
55 |
| -`fill_value` argument. By default, we follow the behavior |
56 |
| -:meth:`numpy.take` of where negative indices indicate slices |
57 |
| -from the end. |
58 |
| -
|
59 |
| -When `fill_value` is specified, we follow pandas semantics of ``-1`` |
60 |
| -indicating a missing value. In this case, positions where `indexer` |
61 |
| -is ``-1`` will be filled with `fill_value` or the default NA value |
62 |
| -for this type. |
63 |
| -
|
64 |
| -ExtensionArray.take is called by ``Series.__getitem__``, ``.loc``, |
65 |
| -``iloc``, when the indexer is a sequence of values. Additionally, |
66 |
| -it's called by :meth:`Series.reindex` with a `fill_value`. |
67 |
| -
|
68 |
| -See Also |
69 |
| --------- |
70 |
| -numpy.take""") |
71 |
| - |
72 |
| - |
73 | 16 | class ExtensionArray(object):
|
74 | 17 | """Abstract base class for custom 1-D array types.
|
75 | 18 |
|
@@ -532,15 +475,66 @@ def _values_for_take(self):
|
532 | 475 | """
|
533 | 476 | return self.astype(object)
|
534 | 477 |
|
535 |
| - @Substitution(arr='') |
536 |
| - @Appender(_take_docstring) |
537 | 478 | def take(self, indexer, fill_value=None, allow_fill=None):
|
538 |
| - # type: (Sequence[int], Optional[Any]) -> ExtensionArray |
539 |
| - # assert fill_value is not np.nan |
| 479 | + # type: (Sequence[int], Optional[Any], Optional[bool]) -> ExtensionArray |
| 480 | + """Take elements from an array. |
| 481 | +
|
| 482 | + Parameters |
| 483 | + ---------- |
| 484 | + indexer : sequence of integers |
| 485 | + Indices to be taken. See Notes for how negative indicies |
| 486 | + are handled. |
| 487 | + fill_value : any, optional |
| 488 | + Fill value to use for NA-indicies. This has a few behaviors. |
| 489 | +
|
| 490 | + * fill_value is not specified : triggers NumPy's semantics |
| 491 | + where negative values in `indexer` mean slices from the end. |
| 492 | + * fill_value is NA : Fill positions where `indexer` is ``-1`` |
| 493 | + with ``self.dtype.na_value``. Anything considered NA by |
| 494 | + :func:`pandas.isna` will result in ``self.dtype.na_value`` |
| 495 | + being used to fill. |
| 496 | + * fill_value is not NA : Fill positions where `indexer` is ``-1`` |
| 497 | + with `fill_value`. |
| 498 | +
|
| 499 | + Returns |
| 500 | + ------- |
| 501 | + ExtensionArray |
| 502 | +
|
| 503 | + Raises |
| 504 | + ------ |
| 505 | + IndexError |
| 506 | + When the indexer is out of bounds for the array. |
| 507 | + ValueError |
| 508 | + When the indexer contains negative values other than ``-1`` |
| 509 | + and `fill_value` is specified. |
| 510 | +
|
| 511 | + Notes |
| 512 | + ----- |
| 513 | + The meaning of negative values in `indexer` depends on the |
| 514 | + `fill_value` argument. By default, we follow the behavior |
| 515 | + :meth:`numpy.take` of where negative indices indicate slices |
| 516 | + from the end. |
| 517 | +
|
| 518 | + When `fill_value` is specified, we follow pandas semantics of ``-1`` |
| 519 | + indicating a missing value. In this case, positions where `indexer` |
| 520 | + is ``-1`` will be filled with `fill_value` or the default NA value |
| 521 | + for this type. |
| 522 | +
|
| 523 | + ExtensionArray.take is called by ``Series.__getitem__``, ``.loc``, |
| 524 | + ``iloc``, when the indexer is a sequence of values. Additionally, |
| 525 | + it's called by :meth:`Series.reindex` with a `fill_value`. |
| 526 | +
|
| 527 | + See Also |
| 528 | + -------- |
| 529 | + numpy.take |
| 530 | + """ |
540 | 531 | from pandas.core.algorithms import take
|
541 | 532 |
|
542 | 533 | data = self._values_for_take()
|
543 |
| - result = take(data, indexer, fill_value=fill_value) |
| 534 | + if allow_fill and fill_value is None: |
| 535 | + fill_value = self.dtype.na_value |
| 536 | + |
| 537 | + result = take(data, indexer, fill_value=fill_value, allow_fill=allow_fill) |
544 | 538 | return self._from_sequence(result)
|
545 | 539 |
|
546 | 540 | def copy(self, deep=False):
|
@@ -605,4 +599,3 @@ def _ndarray_values(self):
|
605 | 599 | used for interacting with our indexers.
|
606 | 600 | """
|
607 | 601 | return np.array(self)
|
608 |
| - |
0 commit comments