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

1from __future__ import annotations 

2 

3from collections.abc import ( 

4 Hashable, 

5 Iterator, 

6 Mapping, 

7 MutableMapping, 

8 Sequence, 

9) 

10from datetime import ( 

11 date, 

12 datetime, 

13 timedelta, 

14 tzinfo, 

15) 

16from os import PathLike 

17import sys 

18from typing import ( 

19 TYPE_CHECKING, 

20 Any, 

21 Callable, 

22 Literal, 

23 Optional, 

24 Protocol, 

25 Type as type_t, 

26 TypeVar, 

27 Union, 

28 overload, 

29) 

30 

31import numpy as np 

32 

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

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

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

36if TYPE_CHECKING: 

37 import numpy.typing as npt 

38 

39 from pandas._libs import ( 

40 NaTType, 

41 Period, 

42 Timedelta, 

43 Timestamp, 

44 ) 

45 from pandas._libs.tslibs import BaseOffset 

46 

47 from pandas.core.dtypes.dtypes import ExtensionDtype 

48 

49 from pandas import Interval 

50 from pandas.arrays import ( 

51 DatetimeArray, 

52 TimedeltaArray, 

53 ) 

54 from pandas.core.arrays.base import ExtensionArray 

55 from pandas.core.frame import DataFrame 

56 from pandas.core.generic import NDFrame 

57 from pandas.core.groupby.generic import ( 

58 DataFrameGroupBy, 

59 GroupBy, 

60 SeriesGroupBy, 

61 ) 

62 from pandas.core.indexes.base import Index 

63 from pandas.core.internals import ( 

64 ArrayManager, 

65 BlockManager, 

66 SingleArrayManager, 

67 SingleBlockManager, 

68 ) 

69 from pandas.core.resample import Resampler 

70 from pandas.core.series import Series 

71 from pandas.core.window.rolling import BaseWindow 

72 

73 from pandas.io.formats.format import EngFormatter 

74 from pandas.tseries.holiday import AbstractHolidayCalendar 

75 

76 ScalarLike_co = Union[ 

77 int, 

78 float, 

79 complex, 

80 str, 

81 bytes, 

82 np.generic, 

83 ] 

84 

85 # numpy compatible types 

86 NumpyValueArrayLike = Union[ScalarLike_co, npt.ArrayLike] 

87 # Name "npt._ArrayLikeInt_co" is not defined [name-defined] 

88 NumpySorter = Optional[npt._ArrayLikeInt_co] # type: ignore[name-defined] 

89 

90 from typing import SupportsIndex 

91 

92 if sys.version_info >= (3, 10): 

93 from typing import TypeGuard # pyright: ignore[reportUnusedImport] 

94 else: 

95 from typing_extensions import TypeGuard # pyright: ignore[reportUnusedImport] 

96 

97 if sys.version_info >= (3, 11): 

98 from typing import Self # pyright: ignore[reportUnusedImport] 

99 else: 

100 from typing_extensions import Self # pyright: ignore[reportUnusedImport] 

101else: 

102 npt: Any = None 

103 Self: Any = None 

104 TypeGuard: Any = None 

105 

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

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

108 

109# array-like 

110 

111ArrayLike = Union["ExtensionArray", np.ndarray] 

112AnyArrayLike = Union[ArrayLike, "Index", "Series"] 

113TimeArrayLike = Union["DatetimeArray", "TimedeltaArray"] 

114 

115# list-like 

116 

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

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

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

120 

121 

122class SequenceNotStr(Protocol[_T_co]): 

123 @overload 

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

125 ... 

126 

127 @overload 

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

129 ... 

130 

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

132 ... 

133 

134 def __len__(self) -> int: 

135 ... 

136 

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

138 ... 

139 

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

141 ... 

142 

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

144 ... 

145 

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

147 ... 

148 

149 

150ListLike = Union[AnyArrayLike, SequenceNotStr, range] 

151 

152# scalars 

153 

154PythonScalar = Union[str, float, bool] 

155DatetimeLikeScalar = Union["Period", "Timestamp", "Timedelta"] 

156PandasScalar = Union["Period", "Timestamp", "Timedelta", "Interval"] 

157Scalar = Union[PythonScalar, PandasScalar, np.datetime64, np.timedelta64, date] 

158IntStrT = TypeVar("IntStrT", bound=Union[int, str]) 

159 

160 

161# timestamp and timedelta convertible types 

162 

163TimestampConvertibleTypes = Union[ 

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

165] 

166TimestampNonexistent = Union[ 

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

168] 

169TimedeltaConvertibleTypes = Union[ 

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

171] 

172Timezone = Union[str, tzinfo] 

173 

174ToTimestampHow = 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 

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

183 

184AxisInt = int 

185Axis = Union[AxisInt, Literal["index", "columns", "rows"]] 

186IndexLabel = Union[Hashable, Sequence[Hashable]] 

187Level = Hashable 

188Shape = tuple[int, ...] 

189Suffixes = tuple[Optional[str], Optional[str]] 

190Ordered = Optional[bool] 

191JSONSerializable = Optional[Union[PythonScalar, list, dict]] 

192Frequency = Union[str, "BaseOffset"] 

193Axes = ListLike 

194 

195RandomState = Union[ 

196 int, 

197 np.ndarray, 

198 np.random.Generator, 

199 np.random.BitGenerator, 

200 np.random.RandomState, 

201] 

202 

203# dtypes 

204NpDtype = Union[str, np.dtype, type_t[Union[str, complex, bool, object]]] 

205Dtype = Union["ExtensionDtype", NpDtype] 

206AstypeArg = Union["ExtensionDtype", "npt.DTypeLike"] 

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

208DtypeArg = Union[Dtype, dict[Hashable, Dtype]] 

209DtypeObj = Union[np.dtype, "ExtensionDtype"] 

210 

211# converters 

212ConvertersArg = dict[Hashable, Callable[[Dtype], Dtype]] 

213 

214# parse_dates 

215ParseDatesArg = Union[ 

216 bool, list[Hashable], list[list[Hashable]], dict[Hashable, list[Hashable]] 

217] 

218 

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

220Renamer = Union[Mapping[Any, Hashable], Callable[[Any], Hashable]] 

221 

222# to maintain type information across generic functions and parametrization 

223T = TypeVar("T") 

224 

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

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

227FuncType = Callable[..., Any] 

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

229 

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

231# DataFrame::sort_index, among others 

232ValueKeyFunc = Optional[Callable[["Series"], Union["Series", AnyArrayLike]]] 

233IndexKeyFunc = Optional[Callable[["Index"], Union["Index", AnyArrayLike]]] 

234 

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

236AggFuncTypeBase = Union[Callable, str] 

237AggFuncTypeDict = MutableMapping[ 

238 Hashable, Union[AggFuncTypeBase, list[AggFuncTypeBase]] 

239] 

240AggFuncType = Union[ 

241 AggFuncTypeBase, 

242 list[AggFuncTypeBase], 

243 AggFuncTypeDict, 

244] 

245AggObjType = Union[ 

246 "Series", 

247 "DataFrame", 

248 "GroupBy", 

249 "SeriesGroupBy", 

250 "DataFrameGroupBy", 

251 "BaseWindow", 

252 "Resampler", 

253] 

254 

255PythonFuncType = 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 def read(self, __n: int = ...) -> AnyStr_co: 

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

285 ... 

286 

287 

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

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 def readline(self) -> bytes: 

300 ... 

301 

302 

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

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

305 ... 

306 

307 

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

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

310 # for engine=python 

311 ... 

312 

313 def fileno(self) -> int: 

314 # for _MMapWrapper 

315 ... 

316 

317 def readline(self) -> AnyStr_co: 

318 # for engine=python 

319 ... 

320 

321 @property 

322 def closed(self) -> bool: 

323 # for enine=pyarrow 

324 ... 

325 

326 

327FilePath = Union[str, "PathLike[str]"] 

328 

329# for arbitrary kwargs passed during reading/writing files 

330StorageOptions = Optional[dict[str, Any]] 

331 

332 

333# compression keywords and compression 

334CompressionDict = dict[str, Any] 

335CompressionOptions = Optional[ 

336 Union[Literal["infer", "gzip", "bz2", "zip", "xz", "zstd", "tar"], CompressionDict] 

337] 

338 

339# types in DataFrameFormatter 

340FormattersType = Union[ 

341 list[Callable], tuple[Callable, ...], Mapping[Union[str, int], Callable] 

342] 

343ColspaceType = Mapping[Hashable, Union[str, int]] 

344FloatFormatType = Union[str, Callable, "EngFormatter"] 

345ColspaceArgType = Union[ 

346 str, int, Sequence[Union[str, int]], Mapping[Hashable, Union[str, int]] 

347] 

348 

349# Arguments for fillna() 

350FillnaOptions = Literal["backfill", "bfill", "ffill", "pad"] 

351InterpolateOptions = Literal[ 

352 "linear", 

353 "time", 

354 "index", 

355 "values", 

356 "nearest", 

357 "zero", 

358 "slinear", 

359 "quadratic", 

360 "cubic", 

361 "barycentric", 

362 "polynomial", 

363 "krogh", 

364 "piecewise_polynomial", 

365 "spline", 

366 "pchip", 

367 "akima", 

368 "cubicspline", 

369 "from_derivatives", 

370] 

371 

372# internals 

373Manager = Union[ 

374 "ArrayManager", "SingleArrayManager", "BlockManager", "SingleBlockManager" 

375] 

376SingleManager = Union["SingleArrayManager", "SingleBlockManager"] 

377Manager2D = Union["ArrayManager", "BlockManager"] 

378 

379# indexing 

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

381# to ndarray.__getitem__ 

382# ScalarIndexer is for a single value as the index 

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

384# PositionalIndexerTuple is extends the PositionalIndexer for 2D arrays 

385# These are used in various __getitem__ overloads 

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

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

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

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

390ScalarIndexer = Union[int, np.integer] 

391SequenceIndexer = Union[slice, list[int], np.ndarray] 

392PositionalIndexer = Union[ScalarIndexer, SequenceIndexer] 

393PositionalIndexerTuple = tuple[PositionalIndexer, PositionalIndexer] 

394PositionalIndexer2D = Union[PositionalIndexer, PositionalIndexerTuple] 

395if TYPE_CHECKING: 

396 TakeIndexer = Union[Sequence[int], Sequence[np.integer], npt.NDArray[np.integer]] 

397else: 

398 TakeIndexer = Any 

399 

400# Shared by functions such as drop and astype 

401IgnoreRaise = Literal["ignore", "raise"] 

402 

403# Windowing rank methods 

404WindowingRankType = Literal["average", "min", "max"] 

405 

406# read_csv engines 

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

408 

409# read_json engines 

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

411 

412# read_xml parsers 

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

414 

415# read_html flavors 

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

417 

418# Interval closed type 

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

420IntervalClosedType = Union[IntervalLeftRight, Literal["both", "neither"]] 

421 

422# datetime and NaTType 

423DatetimeNaTType = Union[datetime, "NaTType"] 

424DateTimeErrorChoices = Union[IgnoreRaise, Literal["coerce"]] 

425 

426# sort_index 

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

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

429 

430# Arguments for nsmalles and n_largest 

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

432 

433# quantile interpolation 

434QuantileInterpolation = Literal["linear", "lower", "higher", "midpoint", "nearest"] 

435 

436# plotting 

437PlottingOrientation = Literal["horizontal", "vertical"] 

438 

439# dropna 

440AnyAll = Literal["any", "all"] 

441 

442# merge 

443MergeHow = Literal["left", "right", "inner", "outer", "cross"] 

444MergeValidate = Literal[ 

445 "one_to_one", 

446 "1:1", 

447 "one_to_many", 

448 "1:m", 

449 "many_to_one", 

450 "m:1", 

451 "many_to_many", 

452 "m:m", 

453] 

454 

455# join 

456JoinHow = Literal["left", "right", "inner", "outer"] 

457JoinValidate = Literal[ 

458 "one_to_one", 

459 "1:1", 

460 "one_to_many", 

461 "1:m", 

462 "many_to_one", 

463 "m:1", 

464 "many_to_many", 

465 "m:m", 

466] 

467 

468# reindex 

469ReindexMethod = Union[FillnaOptions, Literal["nearest"]] 

470 

471MatplotlibColor = Union[str, Sequence[float]] 

472TimeGrouperOrigin = Union[ 

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

474] 

475TimeAmbiguous = Union[Literal["infer", "NaT", "raise"], "npt.NDArray[np.bool_]"] 

476TimeNonexistent = Union[ 

477 Literal["shift_forward", "shift_backward", "NaT", "raise"], timedelta 

478] 

479DropKeep = Literal["first", "last", False] 

480CorrelationMethod = Union[ 

481 Literal["pearson", "kendall", "spearman"], Callable[[np.ndarray, np.ndarray], float] 

482] 

483AlignJoin = Literal["outer", "inner", "left", "right"] 

484DtypeBackend = Literal["pyarrow", "numpy_nullable"] 

485 

486TimeUnit = Literal["s", "ms", "us", "ns"] 

487OpenFileErrors = Literal[ 

488 "strict", 

489 "ignore", 

490 "replace", 

491 "surrogateescape", 

492 "xmlcharrefreplace", 

493 "backslashreplace", 

494 "namereplace", 

495] 

496 

497# update 

498UpdateJoin = Literal["left"] 

499 

500# applymap 

501NaAction = Literal["ignore"] 

502 

503# from_dict 

504FromDictOrient = Literal["columns", "index", "tight"] 

505 

506# to_gbc 

507ToGbqIfexist = Literal["fail", "replace", "append"] 

508 

509# to_stata 

510ToStataByteorder = Literal[">", "<", "little", "big"] 

511 

512# ExcelWriter 

513ExcelWriterIfSheetExists = Literal["error", "new", "replace", "overlay"] 

514 

515# Offsets 

516OffsetCalendar = Union[np.busdaycalendar, "AbstractHolidayCalendar"] 

517 

518# read_csv: usecols 

519UsecolsArgType = Union[ 

520 SequenceNotStr[Hashable], 

521 range, 

522 AnyArrayLike, 

523 Callable[[HashableT], bool], 

524 None, 

525]