Coverage for /var/srv/projects/api.amasfac.comuna18.com/tmp/venv/lib/python3.9/site-packages/pandas/core/arrays/base.py: 29%

1""" 

2An interface for extending pandas with custom arrays. 

3 

4.. warning:: 

5 

6 This is an experimental API and subject to breaking changes 

7 without warning. 

8""" 

9from __future__ import annotations 

10 

11import inspect 

12import operator 

13from typing import ( 

14 TYPE_CHECKING, 

15 Any, 

16 Callable, 

17 ClassVar, 

18 Iterator, 

19 Literal, 

20 Sequence, 

21 TypeVar, 

22 cast, 

23 overload, 

24) 

25import warnings 

26 

27import numpy as np 

28 

29from pandas._libs import lib 

30from pandas._typing import ( 

31 ArrayLike, 

32 AstypeArg, 

33 Dtype, 

34 FillnaOptions, 

35 PositionalIndexer, 

36 ScalarIndexer, 

37 SequenceIndexer, 

38 Shape, 

39 TakeIndexer, 

40 npt, 

41) 

42from pandas.compat import set_function_name 

43from pandas.compat.numpy import function as nv 

44from pandas.errors import AbstractMethodError 

45from pandas.util._decorators import ( 

46 Appender, 

47 Substitution, 

48 cache_readonly, 

49 deprecate_nonkeyword_arguments, 

50) 

51from pandas.util._exceptions import find_stack_level 

52from pandas.util._validators import ( 

53 validate_bool_kwarg, 

54 validate_fillna_kwargs, 

55 validate_insert_loc, 

56) 

57 

58from pandas.core.dtypes.cast import maybe_cast_to_extension_array 

59from pandas.core.dtypes.common import ( 

60 is_dtype_equal, 

61 is_list_like, 

62 is_scalar, 

63 pandas_dtype, 

64) 

65from pandas.core.dtypes.dtypes import ExtensionDtype 

66from pandas.core.dtypes.generic import ( 

67 ABCDataFrame, 

68 ABCIndex, 

69 ABCSeries, 

70) 

71from pandas.core.dtypes.missing import isna 

72 

73from pandas.core import ( 

74 arraylike, 

75 missing, 

76 roperator, 

77) 

78from pandas.core.algorithms import ( 

79 factorize_array, 

80 isin, 

81 mode, 

82 rank, 

83 resolve_na_sentinel, 

84 unique, 

85) 

86from pandas.core.array_algos.quantile import quantile_with_mask 

87from pandas.core.sorting import ( 

88 nargminmax, 

89 nargsort, 

90) 

91 

92if TYPE_CHECKING: 92 ↛ 94line 92 didn't jump to line 94, because the condition on line 92 was never true

93 

94 class ExtensionArraySupportsAnyAll("ExtensionArray"): 

95 def any(self, *, skipna: bool = True) -> bool: 

96 pass 

97 

98 def all(self, *, skipna: bool = True) -> bool: 

99 pass 

100 

101 from pandas._typing import ( 

102 NumpySorter, 

103 NumpyValueArrayLike, 

104 ) 

105 

106 

107_extension_array_shared_docs: dict[str, str] = {} 

108 

109ExtensionArrayT = TypeVar("ExtensionArrayT", bound="ExtensionArray") 

110 

111 

112class ExtensionArray: 

113 """ 

114 Abstract base class for custom 1-D array types. 

115 

116 pandas will recognize instances of this class as proper arrays 

117 with a custom type and will not attempt to coerce them to objects. They 

118 may be stored directly inside a :class:`DataFrame` or :class:`Series`. 

119 

120 Attributes 

121 ---------- 

122 dtype 

123 nbytes 

124 ndim 

125 shape 

126 

127 Methods 

128 ------- 

129 argsort 

130 astype 

131 copy 

132 dropna 

133 factorize 

134 fillna 

135 equals 

136 insert 

137 isin 

138 isna 

139 ravel 

140 repeat 

141 searchsorted 

142 shift 

143 take 

144 tolist 

145 unique 

146 view 

147 _concat_same_type 

148 _formatter 

149 _from_factorized 

150 _from_sequence 

151 _from_sequence_of_strings 

152 _reduce 

153 _values_for_argsort 

154 _values_for_factorize 

155 

156 Notes 

157 ----- 

158 The interface includes the following abstract methods that must be 

159 implemented by subclasses: 

160 

161 * _from_sequence 

162 * _from_factorized 

163 * __getitem__ 

164 * __len__ 

165 * __eq__ 

166 * dtype 

167 * nbytes 

168 * isna 

169 * take 

170 * copy 

171 * _concat_same_type 

172 

173 A default repr displaying the type, (truncated) data, length, 

174 and dtype is provided. It can be customized or replaced by 

175 by overriding: 

176 

177 * __repr__ : A default repr for the ExtensionArray. 

178 * _formatter : Print scalars inside a Series or DataFrame. 

179 

180 Some methods require casting the ExtensionArray to an ndarray of Python 

181 objects with ``self.astype(object)``, which may be expensive. When 

182 performance is a concern, we highly recommend overriding the following 

183 methods: 

184 

185 * fillna 

186 * dropna 

187 * unique 

188 * factorize / _values_for_factorize 

189 * argsort, argmax, argmin / _values_for_argsort 

190 * searchsorted 

191 

192 The remaining methods implemented on this class should be performant, 

193 as they only compose abstract methods. Still, a more efficient 

194 implementation may be available, and these methods can be overridden. 

195 

196 One can implement methods to handle array reductions. 

197 

198 * _reduce 

199 

200 One can implement methods to handle parsing from strings that will be used 

201 in methods such as ``pandas.io.parsers.read_csv``. 

202 

203 * _from_sequence_of_strings 

204 

205 This class does not inherit from 'abc.ABCMeta' for performance reasons. 

206 Methods and properties required by the interface raise 

207 ``pandas.errors.AbstractMethodError`` and no ``register`` method is 

208 provided for registering virtual subclasses. 

209 

210 ExtensionArrays are limited to 1 dimension. 

211 

212 They may be backed by none, one, or many NumPy arrays. For example, 

213 ``pandas.Categorical`` is an extension array backed by two arrays, 

214 one for codes and one for categories. An array of IPv6 address may 

215 be backed by a NumPy structured array with two fields, one for the 

216 lower 64 bits and one for the upper 64 bits. Or they may be backed 

217 by some other storage type, like Python lists. Pandas makes no 

218 assumptions on how the data are stored, just that it can be converted 

219 to a NumPy array. 

220 The ExtensionArray interface does not impose any rules on how this data 

221 is stored. However, currently, the backing data cannot be stored in 

222 attributes called ``.values`` or ``._values`` to ensure full compatibility 

223 with pandas internals. But other names as ``.data``, ``._data``, 

224 ``._items``, ... can be freely used. 

225 

226 If implementing NumPy's ``__array_ufunc__`` interface, pandas expects 

227 that 

228 

229 1. You defer by returning ``NotImplemented`` when any Series are present 

230 in `inputs`. Pandas will extract the arrays and call the ufunc again. 

231 2. You define a ``_HANDLED_TYPES`` tuple as an attribute on the class. 

232 Pandas inspect this to determine whether the ufunc is valid for the 

233 types present. 

234 

235 See :ref:`extending.extension.ufunc` for more. 

236 

237 By default, ExtensionArrays are not hashable. Immutable subclasses may 

238 override this behavior. 

239 """ 

240 

241 # '_typ' is for pandas.core.dtypes.generic.ABCExtensionArray. 

242 # Don't override this. 

243 _typ = "extension" 

244 

245 # ------------------------------------------------------------------------ 

246 # Constructors 

247 # ------------------------------------------------------------------------ 

248 

249 @classmethod 

250 def _from_sequence(cls, scalars, *, dtype: Dtype | None = None, copy=False): 

251 """ 

252 Construct a new ExtensionArray from a sequence of scalars. 

253 

254 Parameters 

255 ---------- 

256 scalars : Sequence 

257 Each element will be an instance of the scalar type for this 

258 array, ``cls.dtype.type`` or be converted into this type in this method. 

259 dtype : dtype, optional 

260 Construct for this particular dtype. This should be a Dtype 

261 compatible with the ExtensionArray. 

262 copy : bool, default False 

263 If True, copy the underlying data. 

264 

265 Returns 

266 ------- 

267 ExtensionArray 

268 """ 

269 raise AbstractMethodError(cls) 

270 

271 @classmethod 

272 def _from_sequence_of_strings( 

273 cls, strings, *, dtype: Dtype | None = None, copy=False 

274 ): 

275 """ 

276 Construct a new ExtensionArray from a sequence of strings. 

277 

278 Parameters 

279 ---------- 

280 strings : Sequence 

281 Each element will be an instance of the scalar type for this 

282 array, ``cls.dtype.type``. 

283 dtype : dtype, optional 

284 Construct for this particular dtype. This should be a Dtype 

285 compatible with the ExtensionArray. 

286 copy : bool, default False 

287 If True, copy the underlying data. 

288 

289 Returns 

290 ------- 

291 ExtensionArray 

292 """ 

293 raise AbstractMethodError(cls) 

294 

295 @classmethod 

296 def _from_factorized(cls, values, original): 

297 """ 

298 Reconstruct an ExtensionArray after factorization. 

299 

300 Parameters 

301 ---------- 

302 values : ndarray 

303 An integer ndarray with the factorized values. 

304 original : ExtensionArray 

305 The original ExtensionArray that factorize was called on. 

306 

307 See Also 

308 -------- 

309 factorize : Top-level factorize method that dispatches here. 

310 ExtensionArray.factorize : Encode the extension array as an enumerated type. 

311 """ 

312 raise AbstractMethodError(cls) 

313 

314 # ------------------------------------------------------------------------ 

315 # Must be a Sequence 

316 # ------------------------------------------------------------------------ 

317 @overload 

318 def __getitem__(self, item: ScalarIndexer) -> Any: 

319 ... 

320 

321 @overload 

322 def __getitem__(self: ExtensionArrayT, item: SequenceIndexer) -> ExtensionArrayT: 

323 ... 

324 

325 def __getitem__( 

326 self: ExtensionArrayT, item: PositionalIndexer 

327 ) -> ExtensionArrayT | Any: 

328 """ 

329 Select a subset of self. 

330 

331 Parameters 

332 ---------- 

333 item : int, slice, or ndarray 

334 * int: The position in 'self' to get. 

335 

336 * slice: A slice object, where 'start', 'stop', and 'step' are 

337 integers or None 

338 

339 * ndarray: A 1-d boolean NumPy ndarray the same length as 'self' 

340 

341 * list[int]: A list of int 

342 

343 Returns 

344 ------- 

345 item : scalar or ExtensionArray 

346 

347 Notes 

348 ----- 

349 For scalar ``item``, return a scalar value suitable for the array's 

350 type. This should be an instance of ``self.dtype.type``. 

351 

352 For slice ``key``, return an instance of ``ExtensionArray``, even 

353 if the slice is length 0 or 1. 

354 

355 For a boolean mask, return an instance of ``ExtensionArray``, filtered 

356 to the values where ``item`` is True. 

357 """ 

358 raise AbstractMethodError(self) 

359 

360 def __setitem__(self, key: int | slice | np.ndarray, value: Any) -> None: 

361 """ 

362 Set one or more values inplace. 

363 

364 This method is not required to satisfy the pandas extension array 

365 interface. 

366 

367 Parameters 

368 ---------- 

369 key : int, ndarray, or slice 

370 When called from, e.g. ``Series.__setitem__``, ``key`` will be 

371 one of 

372 

373 * scalar int 

374 * ndarray of integers. 

375 * boolean ndarray 

376 * slice object 

377 

378 value : ExtensionDtype.type, Sequence[ExtensionDtype.type], or object 

379 value or values to be set of ``key``. 

380 

381 Returns 

382 ------- 

383 None 

384 """ 

385 # Some notes to the ExtensionArray implementor who may have ended up 

386 # here. While this method is not required for the interface, if you 

387 # *do* choose to implement __setitem__, then some semantics should be 

388 # observed: 

389 # 

390 # * Setting multiple values : ExtensionArrays should support setting 

391 # multiple values at once, 'key' will be a sequence of integers and 

392 # 'value' will be a same-length sequence. 

393 # 

394 # * Broadcasting : For a sequence 'key' and a scalar 'value', 

395 # each position in 'key' should be set to 'value'. 

396 # 

397 # * Coercion : Most users will expect basic coercion to work. For 

398 # example, a string like '2018-01-01' is coerced to a datetime 

399 # when setting on a datetime64ns array. In general, if the 

400 # __init__ method coerces that value, then so should __setitem__ 

401 # Note, also, that Series/DataFrame.where internally use __setitem__ 

402 # on a copy of the data. 

403 raise NotImplementedError(f"{type(self)} does not implement __setitem__.") 

404 

405 def __len__(self) -> int: 

406 """ 

407 Length of this array 

408 

409 Returns 

410 ------- 

411 length : int 

412 """ 

413 raise AbstractMethodError(self) 

414 

415 def __iter__(self) -> Iterator[Any]: 

416 """ 

417 Iterate over elements of the array. 

418 """ 

419 # This needs to be implemented so that pandas recognizes extension 

420 # arrays as list-like. The default implementation makes successive 

421 # calls to ``__getitem__``, which may be slower than necessary. 

422 for i in range(len(self)): 

423 yield self[i] 

424 

425 def __contains__(self, item: object) -> bool | np.bool_: 

426 """ 

427 Return for `item in self`. 

428 """ 

429 # GH37867 

430 # comparisons of any item to pd.NA always return pd.NA, so e.g. "a" in [pd.NA] 

431 # would raise a TypeError. The implementation below works around that. 

432 if is_scalar(item) and isna(item): 

433 if not self._can_hold_na: 

434 return False 

435 elif item is self.dtype.na_value or isinstance(item, self.dtype.type): 

436 return self._hasna 

437 else: 

438 return False 

439 else: 

440 # error: Item "ExtensionArray" of "Union[ExtensionArray, ndarray]" has no 

441 # attribute "any" 

442 return (item == self).any() # type: ignore[union-attr] 

443 

444 # error: Signature of "__eq__" incompatible with supertype "object" 

445 def __eq__(self, other: Any) -> ArrayLike: # type: ignore[override] 

446 """ 

447 Return for `self == other` (element-wise equality). 

448 """ 

449 # Implementer note: this should return a boolean numpy ndarray or 

450 # a boolean ExtensionArray. 

451 # When `other` is one of Series, Index, or DataFrame, this method should 

452 # return NotImplemented (to ensure that those objects are responsible for 

453 # first unpacking the arrays, and then dispatch the operation to the 

454 # underlying arrays) 

455 raise AbstractMethodError(self) 

456 

457 # error: Signature of "__ne__" incompatible with supertype "object" 

458 def __ne__(self, other: Any) -> ArrayLike: # type: ignore[override] 

459 """ 

460 Return for `self != other` (element-wise in-equality). 

461 """ 

462 return ~(self == other) 

463 

464 def __init_subclass__(cls, **kwargs) -> None: 

465 factorize = getattr(cls, "factorize") 

466 if ( 466 ↛ 472line 466 didn't jump to line 472

467 "use_na_sentinel" not in inspect.signature(factorize).parameters 

468 # TimelikeOps uses old factorize args to ensure we don't break things 

469 and cls.__name__ not in ("TimelikeOps", "DatetimeArray", "TimedeltaArray") 

470 ): 

471 # See GH#46910 for details on the deprecation 

472 name = cls.__name__ 

473 warnings.warn( 

474 f"The `na_sentinel` argument of `{name}.factorize` is deprecated. " 

475 f"In the future, pandas will use the `use_na_sentinel` argument " 

476 f"instead. Add this argument to `{name}.factorize` to be compatible " 

477 f"with future versions of pandas and silence this warning.", 

478 DeprecationWarning, 

479 stacklevel=find_stack_level(), 

480 ) 

481 

482 def to_numpy( 

483 self, 

484 dtype: npt.DTypeLike | None = None, 

485 copy: bool = False, 

486 na_value: object = lib.no_default, 

487 ) -> np.ndarray: 

488 """ 

489 Convert to a NumPy ndarray. 

490 

491 .. versionadded:: 1.0.0 

492 

493 This is similar to :meth:`numpy.asarray`, but may provide additional control 

494 over how the conversion is done. 

495 

496 Parameters 

497 ---------- 

498 dtype : str or numpy.dtype, optional 

499 The dtype to pass to :meth:`numpy.asarray`. 

500 copy : bool, default False 

501 Whether to ensure that the returned value is a not a view on 

502 another array. Note that ``copy=False`` does not *ensure* that 

503 ``to_numpy()`` is no-copy. Rather, ``copy=True`` ensure that 

504 a copy is made, even if not strictly necessary. 

505 na_value : Any, optional 

506 The value to use for missing values. The default value depends 

507 on `dtype` and the type of the array. 

508 

509 Returns 

510 ------- 

511 numpy.ndarray 

512 """ 

513 result = np.asarray(self, dtype=dtype) 

514 if copy or na_value is not lib.no_default: 

515 result = result.copy() 

516 if na_value is not lib.no_default: 

517 result[self.isna()] = na_value 

518 return result 

519 

520 # ------------------------------------------------------------------------ 

521 # Required attributes 

522 # ------------------------------------------------------------------------ 

523 

524 @property 

525 def dtype(self) -> ExtensionDtype: 

526 """ 

527 An instance of 'ExtensionDtype'. 

528 """ 

529 raise AbstractMethodError(self) 

530 

531 @property 

532 def shape(self) -> Shape: 

533 """ 

534 Return a tuple of the array dimensions. 

535 """ 

536 return (len(self),) 

537 

538 @property 

539 def size(self) -> int: 

540 """ 

541 The number of elements in the array. 

542 """ 

543 # error: Incompatible return value type (got "signedinteger[_64Bit]", 

544 # expected "int") [return-value] 

545 return np.prod(self.shape) # type: ignore[return-value] 

546 

547 @property 

548 def ndim(self) -> int: 

549 """ 

550 Extension Arrays are only allowed to be 1-dimensional. 

551 """ 

552 return 1 

553 

554 @property 

555 def nbytes(self) -> int: 

556 """ 

557 The number of bytes needed to store this object in memory. 

558 """ 

559 # If this is expensive to compute, return an approximate lower bound 

560 # on the number of bytes needed. 

561 raise AbstractMethodError(self) 

562 

563 # ------------------------------------------------------------------------ 

564 # Additional Methods 

565 # ------------------------------------------------------------------------ 

566 

567 @overload 

568 def astype(self, dtype: npt.DTypeLike, copy: bool = ...) -> np.ndarray: 

569 ... 

570 

571 @overload 

572 def astype(self, dtype: ExtensionDtype, copy: bool = ...) -> ExtensionArray: 

573 ... 

574 

575 @overload 

576 def astype(self, dtype: AstypeArg, copy: bool = ...) -> ArrayLike: 

577 ... 

578 

579 def astype(self, dtype: AstypeArg, copy: bool = True) -> ArrayLike: 

580 """ 

581 Cast to a NumPy array or ExtensionArray with 'dtype'. 

582 

583 Parameters 

584 ---------- 

585 dtype : str or dtype 

586 Typecode or data-type to which the array is cast. 

587 copy : bool, default True 

588 Whether to copy the data, even if not necessary. If False, 

589 a copy is made only if the old dtype does not match the 

590 new dtype. 

591 

592 Returns 

593 ------- 

594 array : np.ndarray or ExtensionArray 

595 An ExtensionArray if dtype is ExtensionDtype, 

596 Otherwise a NumPy ndarray with 'dtype' for its dtype. 

597 """ 

598 

599 dtype = pandas_dtype(dtype) 

600 if is_dtype_equal(dtype, self.dtype): 

601 if not copy: 

602 return self 

603 else: 

604 return self.copy() 

605 

606 if isinstance(dtype, ExtensionDtype): 

607 cls = dtype.construct_array_type() 

608 return cls._from_sequence(self, dtype=dtype, copy=copy) 

609 

610 return np.array(self, dtype=dtype, copy=copy) 

611 

612 def isna(self) -> np.ndarray | ExtensionArraySupportsAnyAll: 

613 """ 

614 A 1-D array indicating if each value is missing. 

615 

616 Returns 

617 ------- 

618 na_values : Union[np.ndarray, ExtensionArray] 

619 In most cases, this should return a NumPy ndarray. For 

620 exceptional cases like ``SparseArray``, where returning 

621 an ndarray would be expensive, an ExtensionArray may be 

622 returned. 

623 

624 Notes 

625 ----- 

626 If returning an ExtensionArray, then 

627 

628 * ``na_values._is_boolean`` should be True 

629 * `na_values` should implement :func:`ExtensionArray._reduce` 

630 * ``na_values.any`` and ``na_values.all`` should be implemented 

631 """ 

632 raise AbstractMethodError(self) 

633 

634 @property 

635 def _hasna(self) -> bool: 

636 # GH#22680 

637 """ 

638 Equivalent to `self.isna().any()`. 

639 

640 Some ExtensionArray subclasses may be able to optimize this check. 

641 """ 

642 return bool(self.isna().any()) 

643 

644 def _values_for_argsort(self) -> np.ndarray: 

645 """ 

646 Return values for sorting. 

647 

648 Returns 

649 ------- 

650 ndarray 

651 The transformed values should maintain the ordering between values 

652 within the array. 

653 

654 See Also 

655 -------- 

656 ExtensionArray.argsort : Return the indices that would sort this array. 

657 

658 Notes 

659 ----- 

660 The caller is responsible for *not* modifying these values in-place, so 

661 it is safe for implementors to give views on `self`. 

662 

663 Functions that use this (e.g. ExtensionArray.argsort) should ignore 

664 entries with missing values in the original array (according to `self.isna()`). 

665 This means that the corresponding entries in the returned array don't need to 

666 be modified to sort correctly. 

667 """ 

668 # Note: this is used in `ExtensionArray.argsort/argmin/argmax`. 

669 return np.array(self) 

670 

671 @deprecate_nonkeyword_arguments(version=None, allowed_args=["self"]) 

672 def argsort( 

673 self, 

674 ascending: bool = True, 

675 kind: str = "quicksort", 

676 na_position: str = "last", 

677 *args, 

678 **kwargs, 

679 ) -> np.ndarray: 

680 """ 

681 Return the indices that would sort this array. 

682 

683 Parameters 

684 ---------- 

685 ascending : bool, default True 

686 Whether the indices should result in an ascending 

687 or descending sort. 

688 kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, optional 

689 Sorting algorithm. 

690 *args, **kwargs: 

691 Passed through to :func:`numpy.argsort`. 

692 

693 Returns 

694 ------- 

695 np.ndarray[np.intp] 

696 Array of indices that sort ``self``. If NaN values are contained, 

697 NaN values are placed at the end. 

698 

699 See Also 

700 -------- 

701 numpy.argsort : Sorting implementation used internally. 

702 """ 

703 # Implementor note: You have two places to override the behavior of 

704 # argsort. 

705 # 1. _values_for_argsort : construct the values passed to np.argsort 

706 # 2. argsort : total control over sorting. In case of overriding this, 

707 # it is recommended to also override argmax/argmin 

708 ascending = nv.validate_argsort_with_ascending(ascending, args, kwargs) 

709 

710 values = self._values_for_argsort() 

711 return nargsort( 

712 values, 

713 kind=kind, 

714 ascending=ascending, 

715 na_position=na_position, 

716 mask=np.asarray(self.isna()), 

717 ) 

718 

719 def argmin(self, skipna: bool = True) -> int: 

720 """ 

721 Return the index of minimum value. 

722 

723 In case of multiple occurrences of the minimum value, the index 

724 corresponding to the first occurrence is returned. 

725 

726 Parameters 

727 ---------- 

728 skipna : bool, default True 

729 

730 Returns 

731 ------- 

732 int 

733 

734 See Also 

735 -------- 

736 ExtensionArray.argmax 

737 """ 

738 # Implementor note: You have two places to override the behavior of 

739 # argmin. 

740 # 1. _values_for_argsort : construct the values used in nargminmax 

741 # 2. argmin itself : total control over sorting. 

742 validate_bool_kwarg(skipna, "skipna") 

743 if not skipna and self._hasna: 

744 raise NotImplementedError 

745 return nargminmax(self, "argmin") 

746 

747 def argmax(self, skipna: bool = True) -> int: 

748 """ 

749 Return the index of maximum value. 

750 

751 In case of multiple occurrences of the maximum value, the index 

752 corresponding to the first occurrence is returned. 

753 

754 Parameters 

755 ---------- 

756 skipna : bool, default True 

757 

758 Returns 

759 ------- 

760 int 

761 

762 See Also 

763 -------- 

764 ExtensionArray.argmin 

765 """ 

766 # Implementor note: You have two places to override the behavior of 

767 # argmax. 

768 # 1. _values_for_argsort : construct the values used in nargminmax 

769 # 2. argmax itself : total control over sorting. 

770 validate_bool_kwarg(skipna, "skipna") 

771 if not skipna and self._hasna: 

772 raise NotImplementedError 

773 return nargminmax(self, "argmax") 

774 

775 def fillna( 

776 self: ExtensionArrayT, 

777 value: object | ArrayLike | None = None, 

778 method: FillnaOptions | None = None, 

779 limit: int | None = None, 

780 ) -> ExtensionArrayT: 

781 """ 

782 Fill NA/NaN values using the specified method. 

783 

784 Parameters 

785 ---------- 

786 value : scalar, array-like 

787 If a scalar value is passed it is used to fill all missing values. 

788 Alternatively, an array-like 'value' can be given. It's expected 

789 that the array-like have the same length as 'self'. 

790 method : {'backfill', 'bfill', 'pad', 'ffill', None}, default None 

791 Method to use for filling holes in reindexed Series 

792 pad / ffill: propagate last valid observation forward to next valid 

793 backfill / bfill: use NEXT valid observation to fill gap. 

794 limit : int, default None 

795 If method is specified, this is the maximum number of consecutive 

796 NaN values to forward/backward fill. In other words, if there is 

797 a gap with more than this number of consecutive NaNs, it will only 

798 be partially filled. If method is not specified, this is the 

799 maximum number of entries along the entire axis where NaNs will be 

800 filled. 

801 

802 Returns 

803 ------- 

804 ExtensionArray 

805 With NA/NaN filled. 

806 """ 

807 value, method = validate_fillna_kwargs(value, method) 

808 

809 mask = self.isna() 

810 # error: Argument 2 to "check_value_size" has incompatible type 

811 # "ExtensionArray"; expected "ndarray" 

812 value = missing.check_value_size( 

813 value, mask, len(self) # type: ignore[arg-type] 

814 ) 

815 

816 if mask.any(): 

817 if method is not None: 

818 func = missing.get_fill_func(method) 

819 npvalues = self.astype(object) 

820 func(npvalues, limit=limit, mask=mask) 

821 new_values = self._from_sequence(npvalues, dtype=self.dtype) 

822 else: 

823 # fill with value 

824 new_values = self.copy() 

825 new_values[mask] = value 

826 else: 

827 new_values = self.copy() 

828 return new_values 

829 

830 def dropna(self: ExtensionArrayT) -> ExtensionArrayT: 

831 """ 

832 Return ExtensionArray without NA values. 

833 

834 Returns 

835 ------- 

836 valid : ExtensionArray 

837 """ 

838 # error: Unsupported operand type for ~ ("ExtensionArray") 

839 return self[~self.isna()] # type: ignore[operator] 

840 

841 def shift(self, periods: int = 1, fill_value: object = None) -> ExtensionArray: 

842 """ 

843 Shift values by desired number. 

844 

845 Newly introduced missing values are filled with 

846 ``self.dtype.na_value``. 

847 

848 Parameters 

849 ---------- 

850 periods : int, default 1 

851 The number of periods to shift. Negative values are allowed 

852 for shifting backwards. 

853 

854 fill_value : object, optional 

855 The scalar value to use for newly introduced missing values. 

856 The default is ``self.dtype.na_value``. 

857 

858 Returns 

859 ------- 

860 ExtensionArray 

861 Shifted. 

862 

863 Notes 

864 ----- 

865 If ``self`` is empty or ``periods`` is 0, a copy of ``self`` is 

866 returned. 

867 

868 If ``periods > len(self)``, then an array of size 

869 len(self) is returned, with all values filled with 

870 ``self.dtype.na_value``. 

871 """ 

872 # Note: this implementation assumes that `self.dtype.na_value` can be 

873 # stored in an instance of your ExtensionArray with `self.dtype`. 

874 if not len(self) or periods == 0: 

875 return self.copy() 

876 

877 if isna(fill_value): 

878 fill_value = self.dtype.na_value 

879 

880 empty = self._from_sequence( 

881 [fill_value] * min(abs(periods), len(self)), dtype=self.dtype 

882 ) 

883 if periods > 0: 

884 a = empty 

885 b = self[:-periods] 

886 else: 

887 a = self[abs(periods) :] 

888 b = empty 

889 return self._concat_same_type([a, b]) 

890 

891 def unique(self: ExtensionArrayT) -> ExtensionArrayT: 

892 """ 

893 Compute the ExtensionArray of unique values. 

894 

895 Returns 

896 ------- 

897 uniques : ExtensionArray 

898 """ 

899 uniques = unique(self.astype(object)) 

900 return self._from_sequence(uniques, dtype=self.dtype) 

901 

902 def searchsorted( 

903 self, 

904 value: NumpyValueArrayLike | ExtensionArray, 

905 side: Literal["left", "right"] = "left", 

906 sorter: NumpySorter = None, 

907 ) -> npt.NDArray[np.intp] | np.intp: 

908 """ 

909 Find indices where elements should be inserted to maintain order. 

910 

911 Find the indices into a sorted array `self` (a) such that, if the 

912 corresponding elements in `value` were inserted before the indices, 

913 the order of `self` would be preserved. 

914 

915 Assuming that `self` is sorted: 

916 

917 ====== ================================ 

918 `side` returned index `i` satisfies 

919 ====== ================================ 

920 left ``self[i-1] < value <= self[i]`` 

921 right ``self[i-1] <= value < self[i]`` 

922 ====== ================================ 

923 

924 Parameters 

925 ---------- 

926 value : array-like, list or scalar 

927 Value(s) to insert into `self`. 

928 side : {'left', 'right'}, optional 

929 If 'left', the index of the first suitable location found is given. 

930 If 'right', return the last such index. If there is no suitable 

931 index, return either 0 or N (where N is the length of `self`). 

932 sorter : 1-D array-like, optional 

933 Optional array of integer indices that sort array a into ascending 

934 order. They are typically the result of argsort. 

935 

936 Returns 

937 ------- 

938 array of ints or int 

939 If value is array-like, array of insertion points. 

940 If value is scalar, a single integer. 

941 

942 See Also 

943 -------- 

944 numpy.searchsorted : Similar method from NumPy. 

945 """ 

946 # Note: the base tests provided by pandas only test the basics. 

947 # We do not test 

948 # 1. Values outside the range of the `data_for_sorting` fixture 

949 # 2. Values between the values in the `data_for_sorting` fixture 

950 # 3. Missing values. 

951 arr = self.astype(object) 

952 if isinstance(value, ExtensionArray): 

953 value = value.astype(object) 

954 return arr.searchsorted(value, side=side, sorter=sorter) 

955 

956 def equals(self, other: object) -> bool: 

957 """ 

958 Return if another array is equivalent to this array. 

959 

960 Equivalent means that both arrays have the same shape and dtype, and 

961 all values compare equal. Missing values in the same location are 

962 considered equal (in contrast with normal equality). 

963 

964 Parameters 

965 ---------- 

966 other : ExtensionArray 

967 Array to compare to this Array. 

968 

969 Returns 

970 ------- 

971 boolean 

972 Whether the arrays are equivalent. 

973 """ 

974 if type(self) != type(other): 

975 return False 

976 other = cast(ExtensionArray, other) 

977 if not is_dtype_equal(self.dtype, other.dtype): 

978 return False 

979 elif len(self) != len(other): 

980 return False 

981 else: 

982 equal_values = self == other 

983 if isinstance(equal_values, ExtensionArray): 

984 # boolean array with NA -> fill with False 

985 equal_values = equal_values.fillna(False) 

986 # error: Unsupported left operand type for & ("ExtensionArray") 

987 equal_na = self.isna() & other.isna() # type: ignore[operator] 

988 return bool((equal_values | equal_na).all()) 

989 

990 def isin(self, values) -> npt.NDArray[np.bool_]: 

991 """ 

992 Pointwise comparison for set containment in the given values. 

993 

994 Roughly equivalent to `np.array([x in values for x in self])` 

995 

996 Parameters 

997 ---------- 

998 values : Sequence 

999 

1000 Returns 

1001 ------- 

1002 np.ndarray[bool] 

1003 """ 

1004 return isin(np.asarray(self), values) 

1005 

1006 def _values_for_factorize(self) -> tuple[np.ndarray, Any]: 

1007 """ 

1008 Return an array and missing value suitable for factorization. 

1009 

1010 Returns 

1011 ------- 

1012 values : ndarray 

1013 

1014 An array suitable for factorization. This should maintain order 

1015 and be a supported dtype (Float64, Int64, UInt64, String, Object). 

1016 By default, the extension array is cast to object dtype. 

1017 na_value : object 

1018 The value in `values` to consider missing. This will be treated 

1019 as NA in the factorization routines, so it will be coded as 

1020 `na_sentinel` and not included in `uniques`. By default, 

1021 ``np.nan`` is used. 

1022 

1023 Notes 

1024 ----- 

1025 The values returned by this method are also used in 

1026 :func:`pandas.util.hash_pandas_object`. 

1027 """ 

1028 return self.astype(object), np.nan 

1029 

1030 def factorize( 

1031 self, 

1032 na_sentinel: int | lib.NoDefault = lib.no_default, 

1033 use_na_sentinel: bool | lib.NoDefault = lib.no_default, 

1034 ) -> tuple[np.ndarray, ExtensionArray]: 

1035 """ 

1036 Encode the extension array as an enumerated type. 

1037 

1038 Parameters 

1039 ---------- 

1040 na_sentinel : int, default -1 

1041 Value to use in the `codes` array to indicate missing values. 

1042 

1043 .. deprecated:: 1.5.0 

1044 The na_sentinel argument is deprecated and 

1045 will be removed in a future version of pandas. Specify use_na_sentinel 

1046 as either True or False. 

1047 

1048 use_na_sentinel : bool, default True 

1049 If True, the sentinel -1 will be used for NaN values. If False, 

1050 NaN values will be encoded as non-negative integers and will not drop the 

1051 NaN from the uniques of the values. 

1052 

1053 .. versionadded:: 1.5.0 

1054 

1055 Returns 

1056 ------- 

1057 codes : ndarray 

1058 An integer NumPy array that's an indexer into the original 

1059 ExtensionArray. 

1060 uniques : ExtensionArray 

1061 An ExtensionArray containing the unique values of `self`. 

1062 

1063 .. note:: 

1064 

1065 uniques will *not* contain an entry for the NA value of 

1066 the ExtensionArray if there are any missing values present 

1067 in `self`. 

1068 

1069 See Also 

1070 -------- 

1071 factorize : Top-level factorize method that dispatches here. 

1072 

1073 Notes 

1074 ----- 

1075 :meth:`pandas.factorize` offers a `sort` keyword as well. 

1076 """ 

1077 # Implementer note: There are two ways to override the behavior of 

1078 # pandas.factorize 

1079 # 1. _values_for_factorize and _from_factorize. 

1080 # Specify the values passed to pandas' internal factorization 

1081 # routines, and how to convert from those values back to the 

1082 # original ExtensionArray. 

1083 # 2. ExtensionArray.factorize. 

1084 # Complete control over factorization. 

1085 resolved_na_sentinel = resolve_na_sentinel(na_sentinel, use_na_sentinel) 

1086 arr, na_value = self._values_for_factorize() 

1087 

1088 codes, uniques = factorize_array( 

1089 arr, na_sentinel=resolved_na_sentinel, na_value=na_value 

1090 ) 

1091 

1092 uniques_ea = self._from_factorized(uniques, self)