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

1from __future__ import annotations 

2 

3from datetime import ( 

4 datetime, 

5 timedelta, 

6 tzinfo, 

7) 

8from os import PathLike 

9from typing import ( 

10 TYPE_CHECKING, 

11 Any, 

12 Callable, 

13 Dict, 

14 Hashable, 

15 Iterator, 

16 List, 

17 Literal, 

18 Mapping, 

19 Optional, 

20 Protocol, 

21 Sequence, 

22 Tuple, 

23 Type as type_t, 

24 TypeVar, 

25 Union, 

26) 

27 

28import numpy as np 

29 

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

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

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

33if TYPE_CHECKING: 

34 import numpy.typing as npt 

35 

36 from pandas._libs import ( 

37 NaTType, 

38 Period, 

39 Timedelta, 

40 Timestamp, 

41 ) 

42 from pandas._libs.tslibs import BaseOffset 

43 

44 from pandas.core.dtypes.dtypes import ExtensionDtype 

45 

46 from pandas import Interval 

47 from pandas.arrays import ( 

48 DatetimeArray, 

49 TimedeltaArray, 

50 ) 

51 from pandas.core.arrays.base import ExtensionArray 

52 from pandas.core.frame import DataFrame 

53 from pandas.core.generic import NDFrame 

54 from pandas.core.groupby.generic import ( 

55 DataFrameGroupBy, 

56 GroupBy, 

57 SeriesGroupBy, 

58 ) 

59 from pandas.core.indexes.base import Index 

60 from pandas.core.internals import ( 

61 ArrayManager, 

62 BlockManager, 

63 SingleArrayManager, 

64 SingleBlockManager, 

65 ) 

66 from pandas.core.resample import Resampler 

67 from pandas.core.series import Series 

68 from pandas.core.window.rolling import BaseWindow 

69 

70 from pandas.io.formats.format import EngFormatter 

71 

72 ScalarLike_co = Union[ 

73 int, 

74 float, 

75 complex, 

76 str, 

77 bytes, 

78 np.generic, 

79 ] 

80 

81 # numpy compatible types 

82 NumpyValueArrayLike = Union[ScalarLike_co, npt.ArrayLike] 

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

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

85 

86else: 

87 npt: Any = None 

88 

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

90 

91# array-like 

92 

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

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

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

96 

97# scalars 

98 

99PythonScalar = Union[str, float, bool] 

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

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

102Scalar = Union[PythonScalar, PandasScalar, np.datetime64, np.timedelta64, datetime] 

103IntStrT = TypeVar("IntStrT", int, str) 

104 

105 

106# timestamp and timedelta convertible types 

107 

108TimestampConvertibleTypes = Union[ 

109 "Timestamp", datetime, np.datetime64, np.int64, float, str 

110] 

111TimedeltaConvertibleTypes = Union[ 

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

113] 

114Timezone = Union[str, tzinfo] 

115 

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

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

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

119# passed in, a DataFrame is always returned. 

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

121 

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

123 

124AxisInt = int 

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

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

127Level = Hashable 

128Shape = Tuple[int, ...] 

129Suffixes = Tuple[Optional[str], Optional[str]] 

130Ordered = Optional[bool] 

131JSONSerializable = Optional[Union[PythonScalar, List, Dict]] 

132Frequency = Union[str, "BaseOffset"] 

133Axes = Union[AnyArrayLike, List, range] 

134 

135RandomState = Union[ 

136 int, 

137 ArrayLike, 

138 np.random.Generator, 

139 np.random.BitGenerator, 

140 np.random.RandomState, 

141] 

142 

143# dtypes 

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

145Dtype = Union["ExtensionDtype", NpDtype] 

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

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

148DtypeArg = Union[Dtype, Dict[Hashable, Dtype]] 

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

150 

151# converters 

152ConvertersArg = Dict[Hashable, Callable[[Dtype], Dtype]] 

153 

154# parse_dates 

155ParseDatesArg = Union[ 

156 bool, List[Hashable], List[List[Hashable]], Dict[Hashable, List[Hashable]] 

157] 

158 

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

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

161 

162# to maintain type information across generic functions and parametrization 

163T = TypeVar("T") 

164 

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

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

167FuncType = Callable[..., Any] 

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

169 

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

171# DataFrame::sort_index, among others 

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

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

174 

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

176AggFuncTypeBase = Union[Callable, str] 

177AggFuncTypeDict = Dict[Hashable, Union[AggFuncTypeBase, List[AggFuncTypeBase]]] 

178AggFuncType = Union[ 

179 AggFuncTypeBase, 

180 List[AggFuncTypeBase], 

181 AggFuncTypeDict, 

182] 

183AggObjType = Union[ 

184 "Series", 

185 "DataFrame", 

186 "GroupBy", 

187 "SeriesGroupBy", 

188 "DataFrameGroupBy", 

189 "BaseWindow", 

190 "Resampler", 

191] 

192 

193PythonFuncType = Callable[[Any], Any] 

194 

195# filenames and file-like-objects 

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

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

198 

199 

200class BaseBuffer(Protocol): 

201 @property 

202 def mode(self) -> str: 

203 # for _get_filepath_or_buffer 

204 ... 

205 

206 def seek(self, __offset: int, __whence: int = ...) -> int: 

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

208 # with two arguments: zip.ZipFile, read_sas 

209 ... 

210 

211 def seekable(self) -> bool: 

212 # for bz2.BZ2File 

213 ... 

214 

215 def tell(self) -> int: 

216 # for zip.ZipFile, read_stata, to_stata 

217 ... 

218 

219 

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

221 def read(self, __n: int = ...) -> AnyStr_co: 

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

223 ... 

224 

225 

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

227 def write(self, __b: AnyStr_contra) -> Any: 

228 # for gzip.GzipFile, bz2.BZ2File 

229 ... 

230 

231 def flush(self) -> Any: 

232 # for gzip.GzipFile, bz2.BZ2File 

233 ... 

234 

235 

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

237 def readline(self) -> bytes: 

238 ... 

239 

240 

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

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

243 ... 

244 

245 

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

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

248 # for engine=python 

249 ... 

250 

251 def fileno(self) -> int: 

252 # for _MMapWrapper 

253 ... 

254 

255 def readline(self) -> AnyStr_co: 

256 # for engine=python 

257 ... 

258 

259 @property 

260 def closed(self) -> bool: 

261 # for enine=pyarrow 

262 ... 

263 

264 

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

266 

267# for arbitrary kwargs passed during reading/writing files 

268StorageOptions = Optional[Dict[str, Any]] 

269 

270 

271# compression keywords and compression 

272CompressionDict = Dict[str, Any] 

273CompressionOptions = Optional[ 

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

275] 

276 

277# types in DataFrameFormatter 

278FormattersType = Union[ 

279 List[Callable], Tuple[Callable, ...], Mapping[Union[str, int], Callable] 

280] 

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

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

283ColspaceArgType = Union[ 

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

285] 

286 

287# Arguments for fillna() 

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

289 

290# internals 

291Manager = Union[ 

292 "ArrayManager", "SingleArrayManager", "BlockManager", "SingleBlockManager" 

293] 

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

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

296 

297# indexing 

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

299# to ndarray.__getitem__ 

300# ScalarIndexer is for a single value as the index 

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

302# PositionalIndexerTuple is extends the PositionalIndexer for 2D arrays 

303# These are used in various __getitem__ overloads 

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

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

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

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

308ScalarIndexer = Union[int, np.integer] 

309SequenceIndexer = Union[slice, List[int], np.ndarray] 

310PositionalIndexer = Union[ScalarIndexer, SequenceIndexer] 

311PositionalIndexerTuple = Tuple[PositionalIndexer, PositionalIndexer] 

312PositionalIndexer2D = Union[PositionalIndexer, PositionalIndexerTuple] 

313if TYPE_CHECKING: 

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

315else: 

316 TakeIndexer = Any 

317 

318# Shared by functions such as drop and astype 

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

320 

321# Windowing rank methods 

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

323 

324# read_csv engines 

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

326 

327# read_json engines 

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

329 

330# read_xml parsers 

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

332 

333# Interval closed type 

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

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

336 

337# datetime and NaTType 

338DatetimeNaTType = Union[datetime, "NaTType"] 

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

340 

341# sort_index 

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

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

344 

345# quantile interpolation 

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

347 

348# plotting 

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

350 

351# dropna 

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

353 

354# merge 

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

356 

357# join 

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

359 

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

361TimeGrouperOrigin = Union[ 

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

363] 

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

365TimeNonexistent = Union[ 

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

367] 

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

369CorrelationMethod = Union[ 

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

371] 

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

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