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 typing import ( 

20 TYPE_CHECKING, 

21 Any, 

22 Literal, 

23 ParamSpec, 

24 Protocol, 

25 SupportsIndex, 

26 TypeAlias, 

27 TypeVar, 

28 Union, 

29 overload, 

30) 

31 

32import numpy as np 

33import numpy.typing as npt 

34 

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

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

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

38 

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

40 

41if TYPE_CHECKING: 

42 from pandas._libs import ( 

43 NaTType, 

44 Period, 

45 Timedelta, 

46 Timestamp, 

47 ) 

48 from pandas._libs.tslibs import BaseOffset 

49 

50 from pandas.core.dtypes.dtypes import ExtensionDtype 

51 

52 from pandas import ( 

53 DatetimeIndex, 

54 Interval, 

55 PeriodIndex, 

56 TimedeltaIndex, 

57 ) 

58 from pandas.arrays import ( 

59 DatetimeArray, 

60 TimedeltaArray, 

61 ) 

62 from pandas.core.arrays.base import ExtensionArray 

63 from pandas.core.frame import DataFrame 

64 from pandas.core.generic import NDFrame 

65 from pandas.core.groupby.generic import ( 

66 DataFrameGroupBy, 

67 GroupBy, 

68 SeriesGroupBy, 

69 ) 

70 from pandas.core.indexes.base import Index 

71 from pandas.core.internals import ( 

72 BlockManager, 

73 SingleBlockManager, 

74 ) 

75 from pandas.core.resample import Resampler 

76 from pandas.core.series import Series 

77 from pandas.core.window.rolling import BaseWindow 

78 

79 from pandas.io.formats.format import EngFormatter 

80 from pandas.tseries.holiday import AbstractHolidayCalendar 

81 

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

83 

84 # numpy compatible types 

85 NumpyValueArrayLike: TypeAlias = ScalarLike_co | npt.ArrayLike 

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

87 

88 

89P = ParamSpec("P") 

90 

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

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

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

94 

95# array-like 

96 

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

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

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

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

101 

102# list-like 

103 

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

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

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

107 

108 

109class SequenceNotStr(Protocol[_T_co]): 

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

111 

112 @overload 

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

114 

115 @overload 

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

117 

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

119 

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

121 

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

123 

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

125 

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

127 

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

129 

130 

131ListLike: TypeAlias = AnyArrayLike | SequenceNotStr | range 

132 

133# scalars 

134 

135PythonScalar: TypeAlias = str | float | bool 

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

137 

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

139# out object 

140_IndexIterScalar: TypeAlias = Union[ 

141 str, 

142 bytes, 

143 date, 

144 datetime, 

145 timedelta, 

146 np.datetime64, 

147 np.timedelta64, 

148 bool, 

149 int, 

150 float, 

151 "Timestamp", 

152 "Timedelta", 

153] 

154Scalar: TypeAlias = Union[ 

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

156] 

157 

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

159 

160# timestamp and timedelta convertible types 

161 

162TimestampConvertibleTypes: TypeAlias = Union[ 

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

164] 

165TimestampNonexistent: TypeAlias = ( 

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

167) 

168 

169TimedeltaConvertibleTypes: TypeAlias = Union[ 

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

171] 

172Timezone: TypeAlias = str | tzinfo 

173 

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

175 

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

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

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

179# passed in, a DataFrame is always returned. 

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

181 

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

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

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

185 

186AxisInt: TypeAlias = int 

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

188IndexLabel: TypeAlias = Hashable | Sequence[Hashable] 

189Level: TypeAlias = Hashable 

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

191Suffixes: TypeAlias = Sequence[str | None] 

192Ordered: TypeAlias = bool | None 

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

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

195Axes: TypeAlias = ListLike 

196 

197RandomState: TypeAlias = ( 

198 int 

199 | np.ndarray 

200 | np.random.Generator 

201 | np.random.BitGenerator 

202 | np.random.RandomState 

203) 

204 

205 

206# dtypes 

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

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

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

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

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

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

213 

214# converters 

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

216 

217# parse_dates 

218ParseDatesArg: TypeAlias = ( 

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

220) 

221 

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

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

224 

225# to maintain type information across generic functions and parametrization 

226T = TypeVar("T") 

227 

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

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

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

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

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

233 

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

235# DataFrame::sort_index, among others 

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

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

238 

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

240AggFuncTypeBase: TypeAlias = Callable | str 

241AggFuncTypeDict: TypeAlias = MutableMapping[ 

242 Hashable, AggFuncTypeBase | list[AggFuncTypeBase] 

243] 

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

245AggObjType: TypeAlias = Union[ 

246 "Series", 

247 "DataFrame", 

248 "GroupBy", 

249 "SeriesGroupBy", 

250 "DataFrameGroupBy", 

251 "BaseWindow", 

252 "Resampler", 

253] 

254 

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

256 

257# filenames and file-like-objects 

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

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

260 

261 

262class BaseBuffer(Protocol): 

263 @property 

264 def mode(self) -> str: 

265 # for _get_filepath_or_buffer 

266 ... 

267 

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

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

270 # with two arguments: zip.ZipFile, read_sas 

271 ... 

272 

273 def seekable(self) -> bool: 

274 # for bz2.BZ2File 

275 ... 

276 

277 def tell(self) -> int: 

278 # for zip.ZipFile, read_stata, to_stata 

279 ... 

280 

281 

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

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

284 

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

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

287 ... 

288 

289 

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

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

292 

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

294 # for gzip.GzipFile, bz2.BZ2File 

295 ... 

296 

297 def flush(self) -> Any: 

298 # for gzip.GzipFile, bz2.BZ2File 

299 ... 

300 

301 

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

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

304 

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

306 

307 

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

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

310 

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

312 

313 

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

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

316 

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

318 # for engine=python 

319 ... 

320 

321 def fileno(self) -> int: 

322 # for _MMapWrapper 

323 ... 

324 

325 def readline(self) -> AnyStr_co: 

326 # for engine=python 

327 ... 

328 

329 @property 

330 def closed(self) -> bool: 

331 # for engine=pyarrow 

332 ... 

333 

334 

335FilePath: TypeAlias = str | PathLike[str] 

336 

337# for arbitrary kwargs passed during reading/writing files 

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

339 

340# compression keywords and compression 

341CompressionDict: TypeAlias = dict[str, Any] 

342CompressionOptions: TypeAlias = ( 

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

344) 

345ParquetCompressionOptions: TypeAlias = ( 

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

347) 

348 

349# types in DataFrameFormatter 

350FormattersType: TypeAlias = ( 

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

352) 

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

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

355ColspaceArgType: TypeAlias = ( 

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

357) 

358 

359# Arguments for fillna() 

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

361InterpolateOptions: TypeAlias = Literal[ 

362 "linear", 

363 "time", 

364 "index", 

365 "values", 

366 "nearest", 

367 "zero", 

368 "slinear", 

369 "quadratic", 

370 "cubic", 

371 "barycentric", 

372 "polynomial", 

373 "krogh", 

374 "piecewise_polynomial", 

375 "spline", 

376 "pchip", 

377 "akima", 

378 "cubicspline", 

379 "from_derivatives", 

380] 

381 

382# internals 

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

384 

385# indexing 

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

387# to ndarray.__getitem__ 

388# ScalarIndexer is for a single value as the index 

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

390# PositionalIndexerTuple is extends the PositionalIndexer for 2D arrays 

391# These are used in various __getitem__ overloads 

392# TODO(typing#684): add Ellipsis, see 

393# https://github.com/python/typing/issues/684#issuecomment-548203158 

394# https://bugs.python.org/issue41810 

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

396ScalarIndexer: TypeAlias = int | np.integer 

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

398PositionalIndexer: TypeAlias = ScalarIndexer | SequenceIndexer 

399PositionalIndexerTuple: TypeAlias = tuple[PositionalIndexer, PositionalIndexer] 

400PositionalIndexer2D: TypeAlias = PositionalIndexer | PositionalIndexerTuple 

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

402 

403# Shared by functions such as drop and astype 

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

405 

406# Windowing rank methods 

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

408 

409# read_csv engines 

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

411 

412# read_json engines 

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

414 

415# read_xml parsers 

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

417 

418# read_html flavors 

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

420 

421# Interval closed type 

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

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

424 

425# datetime and NaTType 

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

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

428 

429# sort_index 

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

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

432 

433# Arguments for nsmallest and nlargest 

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

435 

436# quantile interpolation 

437QuantileInterpolation: TypeAlias = Literal[ 

438 "linear", "lower", "higher", "midpoint", "nearest" 

439] 

440 

441# plotting 

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

443 

444# dropna 

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

446 

447# merge 

448MergeHow: TypeAlias = Literal[ 

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

450] 

451MergeValidate: TypeAlias = Literal[ 

452 "one_to_one", 

453 "1:1", 

454 "one_to_many", 

455 "1:m", 

456 "many_to_one", 

457 "m:1", 

458 "many_to_many", 

459 "m:m", 

460] 

461 

462# join 

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

464JoinValidate: TypeAlias = Literal[ 

465 "one_to_one", 

466 "1:1", 

467 "one_to_many", 

468 "1:m", 

469 "many_to_one", 

470 "m:1", 

471 "many_to_many", 

472 "m:m", 

473] 

474 

475# reindex 

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

477 

478MatplotlibColor: TypeAlias = str | Sequence[float] 

479TimeGrouperOrigin: TypeAlias = Union[ 

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

481] 

482TimeAmbiguous: TypeAlias = ( 

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

484) 

485TimeNonexistent: TypeAlias = ( 

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

487) 

488 

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

490CorrelationMethod: TypeAlias = ( 

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

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

493) 

494 

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

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

497 

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

499OpenFileErrors: TypeAlias = Literal[ 

500 "strict", 

501 "ignore", 

502 "replace", 

503 "surrogateescape", 

504 "xmlcharrefreplace", 

505 "backslashreplace", 

506 "namereplace", 

507] 

508 

509# update 

510UpdateJoin: TypeAlias = Literal["left"] 

511 

512# applymap 

513NaAction: TypeAlias = Literal["ignore"] 

514 

515# from_dict 

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

517 

518# to_stata 

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

520 

521# ExcelWriter 

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

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

524 

525# Offsets 

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

527 

528# read_csv: usecols 

529UsecolsArgType: TypeAlias = ( 

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

531) 

532 

533# maintain the sub-type of any hashable sequence 

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

535 

536SliceType: TypeAlias = Hashable | None 

537 

538 

539# Arrow PyCapsule Interface 

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

541 

542 

543class ArrowArrayExportable(Protocol): 

544 """ 

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

546 

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

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

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

550 

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

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

553 

554 """ 

555 

556 def __arrow_c_array__( 

557 self, requested_schema: object | None = None 

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

559 

560 

561class ArrowStreamExportable(Protocol): 

562 """ 

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

564 

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

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

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

568 libraries. 

569 

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

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

572 

573 """ 

574 

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

576 

577 

578__all__ = ["type_t"]