Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/pandas/_typing.py: 87%

1from __future__ import annotations 

2 

3from builtins import type as type_t # pyright: ignore[reportUnusedImport] 

4from collections.abc import ( 

5 Callable, 

6 Hashable, 

7 Iterator, 

8 Mapping, 

9 MutableMapping, 

10 Sequence, 

11) 

12from datetime import ( 

13 date, 

14 datetime, 

15 timedelta, 

16 tzinfo, 

17) 

18from os import PathLike 

19from types import EllipsisType 

20from typing import ( 

21 TYPE_CHECKING, 

22 Any, 

23 Literal, 

24 ParamSpec, 

25 Protocol, 

26 SupportsIndex, 

27 TypeAlias, 

28 TypeVar, 

29 Union, 

30 overload, 

31) 

32 

33import numpy as np 

34import numpy.typing as npt 

35 

36# To prevent import cycles place any internal imports in the branch below 

37# and use a string literal forward reference to it in subsequent types 

38# https://mypy.readthedocs.io/en/latest/common_issues.html#import-cycles 

39 

40# Note that Union is needed when a Union includes a pandas type 

41 

42if TYPE_CHECKING: 

43 from pandas._libs import ( 

44 NaTType, 

45 Period, 

46 Timedelta, 

47 Timestamp, 

48 ) 

49 from pandas._libs.tslibs import BaseOffset 

50 

51 from pandas.core.dtypes.dtypes import ExtensionDtype 

52 

53 from pandas import ( 

54 DatetimeIndex, 

55 Interval, 

56 PeriodIndex, 

57 TimedeltaIndex, 

58 ) 

59 from pandas.arrays import ( 

60 DatetimeArray, 

61 TimedeltaArray, 

62 ) 

63 from pandas.core.arrays.base import ExtensionArray 

64 from pandas.core.frame import DataFrame 

65 from pandas.core.generic import NDFrame 

66 from pandas.core.groupby.generic import ( 

67 DataFrameGroupBy, 

68 GroupBy, 

69 SeriesGroupBy, 

70 ) 

71 from pandas.core.indexes.base import Index 

72 from pandas.core.internals import ( 

73 BlockManager, 

74 SingleBlockManager, 

75 ) 

76 from pandas.core.resample import Resampler 

77 from pandas.core.series import Series 

78 from pandas.core.window.rolling import BaseWindow 

79 

80 from pandas.io.formats.format import EngFormatter 

81 from pandas.tseries.holiday import AbstractHolidayCalendar 

82 

83 ScalarLike_co: TypeAlias = int | float | complex | str | bytes | np.generic 

84 

85 # numpy compatible types 

86 NumpyValueArrayLike: TypeAlias = ScalarLike_co | npt.ArrayLike 

87 NumpySorter: TypeAlias = npt.NDArray[np.integer] | None 

88 

89 

90P = ParamSpec("P") 

91 

92HashableT = TypeVar("HashableT", bound=Hashable) 

93HashableT2 = TypeVar("HashableT2", bound=Hashable) 

94MutableMappingT = TypeVar("MutableMappingT", bound=MutableMapping) 

95 

96# array-like 

97 

98ArrayLike: TypeAlias = Union["ExtensionArray", np.ndarray] 

99ArrayLikeT = TypeVar("ArrayLikeT", "ExtensionArray", np.ndarray) 

100AnyArrayLike: TypeAlias = Union[ArrayLike, "Index", "Series"] 

101TimeArrayLike: TypeAlias = Union["DatetimeArray", "TimedeltaArray"] 

102 

103# list-like 

104 

105# from https://github.com/hauntsaninja/useful_types 

106# includes Sequence-like objects but excludes str and bytes 

107_T_co = TypeVar("_T_co", covariant=True) 

108 

109 

110class SequenceNotStr(Protocol[_T_co]): 

111 __module__: str = "pandas.api.typing.aliases" 

112 

113 @overload 

114 def __getitem__(self, index: SupportsIndex, /) -> _T_co: ... 

115 

116 @overload 

117 def __getitem__(self, index: slice, /) -> Sequence[_T_co]: ... 

118 

119 def __contains__(self, value: object, /) -> bool: ... 

120 

121 def __len__(self) -> int: ... 

122 

123 def __iter__(self) -> Iterator[_T_co]: ... 

124 

125 def index(self, value: Any, start: int = ..., stop: int = ..., /) -> int: ... 

126 

127 def count(self, value: Any, /) -> int: ... 

128 

129 def __reversed__(self) -> Iterator[_T_co]: ... 

130 

131 

132ListLike: TypeAlias = AnyArrayLike | SequenceNotStr | range 

133 

134# scalars 

135 

136PythonScalar: TypeAlias = str | float | bool 

137DatetimeLikeScalar: TypeAlias = Union["Period", "Timestamp", "Timedelta"] 

138 

139# aligned with pandas-stubs - typical scalars found in Series. Explicitly leaves 

140# out object 

141_IndexIterScalar: TypeAlias = Union[ 

142 str, 

143 bytes, 

144 date, 

145 datetime, 

146 timedelta, 

147 np.datetime64, 

148 np.timedelta64, 

149 bool, 

150 int, 

151 float, 

152 "Timestamp", 

153 "Timedelta", 

154] 

155Scalar: TypeAlias = Union[ 

156 _IndexIterScalar, "Interval", complex, np.integer, np.floating, np.complexfloating 

157] 

158 

159IntStrT = TypeVar("IntStrT", bound=int | str) 

160 

161# timestamp and timedelta convertible types 

162 

163TimestampConvertibleTypes: TypeAlias = Union[ 

164 "Timestamp", date, np.datetime64, np.int64, float, str 

165] 

166TimestampNonexistent: TypeAlias = ( 

167 Literal["shift_forward", "shift_backward", "NaT", "raise"] | timedelta 

168) 

169 

170TimedeltaConvertibleTypes: TypeAlias = Union[ 

171 "Timedelta", timedelta, np.timedelta64, np.int64, float, str 

172] 

173Timezone: TypeAlias = str | tzinfo 

174 

175ToTimestampHow: TypeAlias = Literal["s", "e", "start", "end"] 

176 

177# NDFrameT is stricter and ensures that the same subclass of NDFrame always is 

178# used. E.g. `def func(a: NDFrameT) -> NDFrameT: ...` means that if a 

179# Series is passed into a function, a Series is always returned and if a DataFrame is 

180# passed in, a DataFrame is always returned. 

181NDFrameT = TypeVar("NDFrameT", bound="NDFrame") 

182 

183IndexT = TypeVar("IndexT", bound="Index") 

184FreqIndexT = TypeVar("FreqIndexT", "DatetimeIndex", "PeriodIndex", "TimedeltaIndex") 

185NumpyIndexT = TypeVar("NumpyIndexT", np.ndarray, "Index") 

186 

187AxisInt: TypeAlias = int 

188Axis: TypeAlias = AxisInt | Literal["index", "columns", "rows"] 

189IndexLabel: TypeAlias = Hashable | Sequence[Hashable] 

190Level: TypeAlias = Hashable 

191Shape: TypeAlias = tuple[int, ...] 

192Suffixes: TypeAlias = Sequence[str | None] 

193Ordered: TypeAlias = bool | None 

194JSONSerializable: TypeAlias = PythonScalar | list | dict | None 

195Frequency: TypeAlias = Union[str, "BaseOffset"] 

196Axes: TypeAlias = ListLike 

197 

198RandomState: TypeAlias = ( 

199 int 

200 | np.ndarray 

201 | np.random.Generator 

202 | np.random.BitGenerator 

203 | np.random.RandomState 

204) 

205 

206 

207# dtypes 

208NpDtype: TypeAlias = str | np.dtype | type[str | complex | bool | object] 

209Dtype: TypeAlias = Union["ExtensionDtype", NpDtype] 

210AstypeArg: TypeAlias = Union["ExtensionDtype", npt.DTypeLike] 

211# DtypeArg specifies all allowable dtypes in a functions its dtype argument 

212DtypeArg: TypeAlias = Dtype | Mapping[Hashable, Dtype] 

213DtypeObj: TypeAlias = Union[np.dtype, "ExtensionDtype"] 

214 

215# converters 

216ConvertersArg: TypeAlias = dict[Hashable, Callable[[Dtype], Dtype]] 

217 

218# parse_dates 

219ParseDatesArg: TypeAlias = ( 

220 bool | list[Hashable] | list[list[Hashable]] | dict[Hashable, list[Hashable]] 

221) 

222 

223# For functions like rename that convert one label to another 

224Renamer: TypeAlias = Mapping[Any, Hashable] | Callable[[Any], Hashable] 

225 

226# to maintain type information across generic functions and parametrization 

227T = TypeVar("T") 

228 

229# used in decorators to preserve the signature of the function it decorates 

230# see https://mypy.readthedocs.io/en/stable/generics.html#declaring-decorators 

231FuncType: TypeAlias = Callable[..., Any] 

232F = TypeVar("F", bound=FuncType) 

233TypeT = TypeVar("TypeT", bound=type) 

234 

235# types of vectorized key functions for DataFrame::sort_values and 

236# DataFrame::sort_index, among others 

237ValueKeyFunc: TypeAlias = Callable[["Series"], Union["Series", AnyArrayLike]] | None 

238IndexKeyFunc: TypeAlias = Callable[["Index"], Union["Index", AnyArrayLike]] | None 

239 

240# types of `func` kwarg for DataFrame.aggregate and Series.aggregate 

241AggFuncTypeBase: TypeAlias = Callable | str 

242AggFuncTypeDict: TypeAlias = MutableMapping[ 

243 Hashable, AggFuncTypeBase | list[AggFuncTypeBase] 

244] 

245AggFuncType: TypeAlias = AggFuncTypeBase | list[AggFuncTypeBase] | AggFuncTypeDict 

246AggObjType: TypeAlias = Union[ 

247 "Series", 

248 "DataFrame", 

249 "GroupBy", 

250 "SeriesGroupBy", 

251 "DataFrameGroupBy", 

252 "BaseWindow", 

253 "Resampler", 

254] 

255 

256PythonFuncType: TypeAlias = Callable[[Any], Any] 

257 

258# filenames and file-like-objects 

259AnyStr_co = TypeVar("AnyStr_co", str, bytes, covariant=True) 

260AnyStr_contra = TypeVar("AnyStr_contra", str, bytes, contravariant=True) 

261 

262 

263class BaseBuffer(Protocol): 

264 def seek(self, offset: int, whence: int = ..., /) -> int: 

265 # with one argument: gzip.GzipFile, bz2.BZ2File 

266 # with two arguments: zip.ZipFile, read_sas 

267 ... 

268 

269 def seekable(self) -> bool: 

270 # for bz2.BZ2File 

271 ... 

272 

273 def tell(self) -> int: 

274 # for zip.ZipFile, read_stata, to_stata 

275 ... 

276 

277 

278class ReadBuffer(BaseBuffer, Protocol[AnyStr_co]): 

279 __module__: str = "pandas.api.typing.aliases" 

280 

281 def read(self, n: int = ..., /) -> AnyStr_co: 

282 # for BytesIOWrapper, gzip.GzipFile, bz2.BZ2File 

283 ... 

284 

285 

286class WriteBuffer(BaseBuffer, Protocol[AnyStr_contra]): 

287 __module__: str = "pandas.api.typing.aliases" 

288 

289 def write(self, b: AnyStr_contra, /) -> Any: 

290 # for gzip.GzipFile, bz2.BZ2File 

291 ... 

292 

293 def flush(self) -> Any: 

294 # for gzip.GzipFile, bz2.BZ2File 

295 ... 

296 

297 

298class ReadPickleBuffer(ReadBuffer[bytes], Protocol): 

299 __module__: str = "pandas.api.typing.aliases" 

300 

301 def readline(self) -> bytes: ... 

302 

303 

304class WriteExcelBuffer(WriteBuffer[bytes], Protocol): 

305 __module__: str = "pandas.api.typing.aliases" 

306 

307 def truncate(self, size: int | None = ..., /) -> int: ... 

308 

309 

310class ReadCsvBuffer(ReadBuffer[AnyStr_co], Protocol): 

311 __module__: str = "pandas.api.typing.aliases" 

312 

313 def __iter__(self) -> Iterator[AnyStr_co]: 

314 # for engine=python 

315 ... 

316 

317 def fileno(self) -> int: 

318 # for _MMapWrapper 

319 ... 

320 

321 def readline(self) -> AnyStr_co: 

322 # for engine=python 

323 ... 

324 

325 @property 

326 def closed(self) -> bool: 

327 # for engine=pyarrow 

328 ... 

329 

330 

331FilePath: TypeAlias = str | PathLike[str] 

332 

333# for arbitrary kwargs passed during reading/writing files 

334StorageOptions: TypeAlias = dict[str, Any] | None 

335 

336# compression keywords and compression 

337CompressionDict: TypeAlias = dict[str, Any] 

338CompressionOptions: TypeAlias = ( 

339 Literal["infer", "gzip", "bz2", "zip", "xz", "zstd", "tar"] | CompressionDict | None 

340) 

341ParquetCompressionOptions: TypeAlias = ( 

342 Literal["snappy", "gzip", "brotli", "lz4", "zstd"] | None 

343) 

344 

345# types in DataFrameFormatter 

346FormattersType: TypeAlias = ( 

347 list[Callable] | tuple[Callable, ...] | Mapping[str | int, Callable] 

348) 

349ColspaceType: TypeAlias = Mapping[Hashable, str | int] 

350FloatFormatType: TypeAlias = Union[str, Callable, "EngFormatter"] 

351ColspaceArgType: TypeAlias = ( 

352 str | int | Sequence[str | int] | Mapping[Hashable, str | int] 

353) 

354 

355# Arguments for fillna() 

356FillnaOptions: TypeAlias = Literal["backfill", "bfill", "ffill", "pad"] 

357InterpolateOptions: TypeAlias = Literal[ 

358 "linear", 

359 "time", 

360 "index", 

361 "values", 

362 "nearest", 

363 "zero", 

364 "slinear", 

365 "quadratic", 

366 "cubic", 

367 "barycentric", 

368 "polynomial", 

369 "krogh", 

370 "piecewise_polynomial", 

371 "spline", 

372 "pchip", 

373 "akima", 

374 "cubicspline", 

375 "from_derivatives", 

376] 

377 

378# internals 

379Manager: TypeAlias = Union["BlockManager", "SingleBlockManager"] 

380 

381# indexing 

382# PositionalIndexer -> valid 1D positional indexer, e.g. can pass 

383# to ndarray.__getitem__ 

384# ScalarIndexer is for a single value as the index 

385# SequenceIndexer is for list like or slices (but not tuples) 

386# PositionalIndexerTuple is extends the PositionalIndexer for 2D arrays 

387# These are used in various __getitem__ overloads 

388# Using List[int] here rather than Sequence[int] to disallow tuples. 

389ScalarIndexer: TypeAlias = int | np.integer 

390SequenceIndexer: TypeAlias = slice | EllipsisType | list[int] | np.ndarray 

391PositionalIndexer: TypeAlias = ScalarIndexer | SequenceIndexer 

392PositionalIndexerTuple: TypeAlias = tuple[PositionalIndexer, PositionalIndexer] 

393PositionalIndexer2D: TypeAlias = PositionalIndexer | PositionalIndexerTuple 

394TakeIndexer: TypeAlias = Sequence[int] | Sequence[np.integer] | npt.NDArray[np.integer] 

395 

396# Shared by functions such as drop and astype 

397IgnoreRaise: TypeAlias = Literal["ignore", "raise"] 

398 

399# Windowing rank methods 

400WindowingRankType: TypeAlias = Literal["average", "min", "max"] 

401 

402# rank tie-breaking methods (Series.rank / DataFrame.rank / GroupBy.rank) 

403RankMethod: TypeAlias = Literal["average", "min", "max", "first", "dense"] 

404RankNaOption: TypeAlias = Literal["keep", "top", "bottom"] 

405 

406# read_csv engines 

407CSVEngine: TypeAlias = Literal["c", "python", "pyarrow", "python-fwf"] 

408 

409# read_json engines 

410JSONEngine: TypeAlias = Literal["ujson", "pyarrow"] 

411 

412# read_xml parsers 

413XMLParsers: TypeAlias = Literal["lxml", "etree"] 

414 

415# read_html flavors 

416HTMLFlavors: TypeAlias = Literal["lxml", "html5lib", "bs4"] 

417 

418# Interval closed type 

419IntervalLeftRight: TypeAlias = Literal["left", "right"] 

420IntervalClosedType: TypeAlias = IntervalLeftRight | Literal["both", "neither"] 

421 

422# datetime and NaTType 

423DatetimeNaTType: TypeAlias = Union[datetime, "NaTType"] 

424DateTimeErrorChoices: TypeAlias = Literal["raise", "coerce"] 

425 

426# sort_index 

427SortKind: TypeAlias = Literal["quicksort", "mergesort", "heapsort", "stable"] 

428NaPosition: TypeAlias = Literal["first", "last"] 

429 

430# Arguments for nsmallest and nlargest 

431NsmallestNlargestKeep: TypeAlias = Literal["first", "last", "all"] 

432 

433# quantile interpolation 

434QuantileInterpolation: TypeAlias = Literal[ 

435 "linear", "lower", "higher", "midpoint", "nearest" 

436] 

437 

438# plotting 

439PlottingOrientation: TypeAlias = Literal["horizontal", "vertical"] 

440 

441# dropna 

442AnyAll: TypeAlias = Literal["any", "all"] 

443 

444# merge 

445MergeHow: TypeAlias = Literal[ 

446 "left", "right", "inner", "outer", "cross", "left_anti", "right_anti" 

447] 

448MergeValidate: TypeAlias = Literal[ 

449 "one_to_one", 

450 "1:1", 

451 "one_to_many", 

452 "1:m", 

453 "many_to_one", 

454 "m:1", 

455 "many_to_many", 

456 "m:m", 

457] 

458 

459# join 

460JoinHow: TypeAlias = Literal["left", "right", "inner", "outer"] 

461JoinValidate: TypeAlias = Literal[ 

462 "one_to_one", 

463 "1:1", 

464 "one_to_many", 

465 "1:m", 

466 "many_to_one", 

467 "m:1", 

468 "many_to_many", 

469 "m:m", 

470] 

471 

472# reindex 

473ReindexMethod: TypeAlias = FillnaOptions | Literal["nearest"] 

474 

475MatplotlibColor: TypeAlias = str | Sequence[float] 

476TimeGrouperOrigin: TypeAlias = Union[ 

477 "Timestamp", Literal["epoch", "start", "start_day", "end", "end_day"] 

478] 

479TimeAmbiguous: TypeAlias = ( 

480 Literal["infer", "NaT", "raise"] | bool | npt.NDArray[np.bool_] 

481) 

482TimeNonexistent: TypeAlias = ( 

483 Literal["shift_forward", "shift_backward", "NaT", "raise"] | timedelta 

484) 

485 

486DropKeep: TypeAlias = Literal["first", "last", False] 

487CorrelationMethod: TypeAlias = ( 

488 Literal["pearson", "kendall", "spearman"] 

489 | Callable[[np.ndarray, np.ndarray], float] 

490) 

491 

492AlignJoin: TypeAlias = Literal["outer", "inner", "left", "right"] 

493DtypeBackend: TypeAlias = Literal["pyarrow", "numpy_nullable"] 

494 

495TimeUnit: TypeAlias = Literal["s", "ms", "us", "ns"] 

496OpenFileErrors: TypeAlias = Literal[ 

497 "strict", 

498 "ignore", 

499 "replace", 

500 "surrogateescape", 

501 "xmlcharrefreplace", 

502 "backslashreplace", 

503 "namereplace", 

504] 

505 

506# update 

507UpdateJoin: TypeAlias = Literal["left"] 

508 

509# applymap 

510NaAction: TypeAlias = Literal["ignore"] 

511 

512# from_dict 

513FromDictOrient: TypeAlias = Literal["columns", "index", "tight"] 

514 

515# to_stata 

516ToStataByteorder: TypeAlias = Literal[">", "<", "little", "big"] 

517 

518# ExcelWriter 

519ExcelWriterIfSheetExists: TypeAlias = Literal["error", "new", "replace", "overlay"] 

520ExcelWriterMergeCells: TypeAlias = bool | Literal["columns"] 

521 

522# Offsets 

523OffsetCalendar: TypeAlias = Union[np.busdaycalendar, "AbstractHolidayCalendar"] 

524 

525# read_csv: usecols 

526UsecolsArgType: TypeAlias = ( 

527 SequenceNotStr[Hashable] | range | AnyArrayLike | Callable[[HashableT], bool] | None 

528) 

529 

530# maintain the sub-type of any hashable sequence 

531SequenceT = TypeVar("SequenceT", bound=Sequence[Hashable]) 

532 

533SliceType: TypeAlias = Hashable | None 

534 

535 

536# Arrow PyCapsule Interface 

537# from https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html#protocol-typehints 

538 

539 

540class ArrowArrayExportable(Protocol): 

541 """ 

542 An object with an ``__arrow_c_array__`` method. 

543 

544 This method indicates the object is an Arrow-compatible object implementing 

545 the `Arrow PyCapsule Protocol`_ (exposing the `Arrow C Data Interface`_ in 

546 Python), enabling zero-copy Arrow data interchange across libraries. 

547 

548 .. _Arrow PyCapsule Protocol: https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html 

549 .. _Arrow C Data Interface: https://arrow.apache.org/docs/format/CDataInterface.html 

550 

551 """ 

552 

553 def __arrow_c_array__( 

554 self, requested_schema: object | None = None 

555 ) -> tuple[object, object]: ... 

556 

557 

558class ArrowStreamExportable(Protocol): 

559 """ 

560 An object with an ``__arrow_c_stream__`` method. 

561 

562 This method indicates the object is an Arrow-compatible object implementing 

563 the `Arrow PyCapsule Protocol`_ (exposing the `Arrow C Data Interface`_ 

564 for streams in Python), enabling zero-copy Arrow data interchange across 

565 libraries. 

566 

567 .. _Arrow PyCapsule Protocol: https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html 

568 .. _Arrow C Stream Interface: https://arrow.apache.org/docs/format/CStreamInterface.html 

569 

570 """ 

571 

572 def __arrow_c_stream__(self, requested_schema: object | None = None) -> object: ... 

573 

574 

575__all__ = ["type_t"]