1# Copyright 2020 The Abseil Authors. 2# 3# Licensed under the Apache License, Version 2.0 (the "License"); 4# you may not use this file except in compliance with the License. 5# You may obtain a copy of the License at 6# 7# http://www.apache.org/licenses/LICENSE-2.0 8# 9# Unless required by applicable law or agreed to in writing, software 10# distributed under the License is distributed on an "AS IS" BASIS, 11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12# See the License for the specific language governing permissions and 13# limitations under the License. 14"""This modules contains type annotated stubs for DEFINE functions.""" 15 16 17from absl.flags import _argument_parser 18from absl.flags import _flag 19from absl.flags import _flagvalues 20 21import enum 22 23from typing import Text, List, Any, TypeVar, Optional, Union, Type, Iterable, overload, Literal 24 25_T = TypeVar('_T') 26_ET = TypeVar('_ET', bound=enum.Enum) 27 28 29@overload 30def DEFINE( 31 parser: _argument_parser.ArgumentParser[_T], 32 name: Text, 33 default: Any, 34 help: Optional[Text], 35 flag_values : _flagvalues.FlagValues = ..., 36 serializer: Optional[_argument_parser.ArgumentSerializer[_T]] = ..., 37 module_name: Optional[Text] = ..., 38 required: Literal[True] = ..., 39 **args: Any) -> _flagvalues.FlagHolder[_T]: 40 ... 41 42 43@overload 44def DEFINE( 45 parser: _argument_parser.ArgumentParser[_T], 46 name: Text, 47 default: Any, 48 help: Optional[Text], 49 flag_values : _flagvalues.FlagValues = ..., 50 serializer: Optional[_argument_parser.ArgumentSerializer[_T]] = ..., 51 module_name: Optional[Text] = ..., 52 required: bool = ..., 53 **args: Any) -> _flagvalues.FlagHolder[Optional[_T]]: 54 ... 55 56 57@overload 58def DEFINE_flag( 59 flag: _flag.Flag[_T], 60 flag_values: _flagvalues.FlagValues = ..., 61 module_name: Optional[Text] = ..., 62 required: Literal[True] = ... 63) -> _flagvalues.FlagHolder[_T]: 64 ... 65 66@overload 67def DEFINE_flag( 68 flag: _flag.Flag[_T], 69 flag_values: _flagvalues.FlagValues = ..., 70 module_name: Optional[Text] = ..., 71 required: bool = ...) -> _flagvalues.FlagHolder[Optional[_T]]: 72 ... 73 74# typing overloads for DEFINE_* methods... 75# 76# - DEFINE_* method return FlagHolder[Optional[T]] or FlagHolder[T] depending 77# on the arguments. 78# - If the flag value is guaranteed to be not None, the return type is 79# FlagHolder[T]. 80# - If the flag is required OR has a non-None default, the flag value i 81# guaranteed to be not None after flag parsing has finished. 82# The information above is captured with three overloads as follows. 83# 84# (if required=True and passed in as a keyword argument, 85# return type is FlagHolder[Y]) 86# @overload 87# def DEFINE_xxx( 88# ... arguments... 89# default: Union[None, X] = ..., 90# *, 91# required: Literal[True]) -> _flagvalues.FlagHolder[Y]: 92# ... 93# 94# (if default=None, return type is FlagHolder[Optional[Y]]) 95# @overload 96# def DEFINE_xxx( 97# ... arguments... 98# default: None, 99# required: bool = ...) -> _flagvalues.FlagHolder[Optional[Y]]: 100# ... 101# 102# (if default!=None, return type is FlagHolder[Y]): 103# @overload 104# def DEFINE_xxx( 105# ... arguments... 106# default: X, 107# required: bool = ...) -> _flagvalues.FlagHolder[Y]: 108# ... 109# 110# where X = type of non-None default values for the flag 111# and Y = non-None type for flag value 112 113@overload 114def DEFINE_string( 115 name: Text, 116 default: Optional[Text], 117 help: Optional[Text], 118 flag_values: _flagvalues.FlagValues = ..., 119 *, 120 required: Literal[True], 121 **args: Any) -> _flagvalues.FlagHolder[Text]: 122 ... 123 124@overload 125def DEFINE_string( 126 name: Text, 127 default: None, 128 help: Optional[Text], 129 flag_values: _flagvalues.FlagValues = ..., 130 required: bool = ..., 131 **args: Any) -> _flagvalues.FlagHolder[Optional[Text]]: 132 ... 133 134@overload 135def DEFINE_string( 136 name: Text, 137 default: Text, 138 help: Optional[Text], 139 flag_values: _flagvalues.FlagValues = ..., 140 required: bool = ..., 141 **args: Any) -> _flagvalues.FlagHolder[Text]: 142 ... 143 144@overload 145def DEFINE_boolean( 146 name : Text, 147 default: Union[None, Text, bool, int], 148 help: Optional[Text], 149 flag_values: _flagvalues.FlagValues = ..., 150 module_name: Optional[Text] = ..., 151 *, 152 required: Literal[True], 153 **args: Any) -> _flagvalues.FlagHolder[bool]: 154 ... 155 156@overload 157def DEFINE_boolean( 158 name : Text, 159 default: None, 160 help: Optional[Text], 161 flag_values: _flagvalues.FlagValues = ..., 162 module_name: Optional[Text] = ..., 163 required: bool = ..., 164 **args: Any) -> _flagvalues.FlagHolder[Optional[bool]]: 165 ... 166 167@overload 168def DEFINE_boolean( 169 name : Text, 170 default: Union[Text, bool, int], 171 help: Optional[Text], 172 flag_values: _flagvalues.FlagValues = ..., 173 module_name: Optional[Text] = ..., 174 required: bool = ..., 175 **args: Any) -> _flagvalues.FlagHolder[bool]: 176 ... 177 178@overload 179def DEFINE_float( 180 name: Text, 181 default: Union[None, float, Text], 182 help: Optional[Text], 183 lower_bound: Optional[float] = ..., 184 upper_bound: Optional[float] = ..., 185 flag_values: _flagvalues.FlagValues = ..., 186 *, 187 required: Literal[True], 188 **args: Any) -> _flagvalues.FlagHolder[float]: 189 ... 190 191@overload 192def DEFINE_float( 193 name: Text, 194 default: None, 195 help: Optional[Text], 196 lower_bound: Optional[float] = ..., 197 upper_bound: Optional[float] = ..., 198 flag_values: _flagvalues.FlagValues = ..., 199 required: bool = ..., 200 **args: Any) -> _flagvalues.FlagHolder[Optional[float]]: 201 ... 202 203@overload 204def DEFINE_float( 205 name: Text, 206 default: Union[float, Text], 207 help: Optional[Text], 208 lower_bound: Optional[float] = ..., 209 upper_bound: Optional[float] = ..., 210 flag_values: _flagvalues.FlagValues = ..., 211 required: bool = ..., 212 **args: Any) -> _flagvalues.FlagHolder[float]: 213 ... 214 215 216@overload 217def DEFINE_integer( 218 name: Text, 219 default: Union[None, int, Text], 220 help: Optional[Text], 221 lower_bound: Optional[int] = ..., 222 upper_bound: Optional[int] = ..., 223 flag_values: _flagvalues.FlagValues = ..., 224 *, 225 required: Literal[True], 226 **args: Any) -> _flagvalues.FlagHolder[int]: 227 ... 228 229@overload 230def DEFINE_integer( 231 name: Text, 232 default: None, 233 help: Optional[Text], 234 lower_bound: Optional[int] = ..., 235 upper_bound: Optional[int] = ..., 236 flag_values: _flagvalues.FlagValues = ..., 237 required: bool = ..., 238 **args: Any) -> _flagvalues.FlagHolder[Optional[int]]: 239 ... 240 241@overload 242def DEFINE_integer( 243 name: Text, 244 default: Union[int, Text], 245 help: Optional[Text], 246 lower_bound: Optional[int] = ..., 247 upper_bound: Optional[int] = ..., 248 flag_values: _flagvalues.FlagValues = ..., 249 required: bool = ..., 250 **args: Any) -> _flagvalues.FlagHolder[int]: 251 ... 252 253@overload 254def DEFINE_enum( 255 name : Text, 256 default: Optional[Text], 257 enum_values: Iterable[Text], 258 help: Optional[Text], 259 flag_values: _flagvalues.FlagValues = ..., 260 module_name: Optional[Text] = ..., 261 *, 262 required: Literal[True], 263 **args: Any) -> _flagvalues.FlagHolder[Text]: 264 ... 265 266@overload 267def DEFINE_enum( 268 name : Text, 269 default: None, 270 enum_values: Iterable[Text], 271 help: Optional[Text], 272 flag_values: _flagvalues.FlagValues = ..., 273 module_name: Optional[Text] = ..., 274 required: bool = ..., 275 **args: Any) -> _flagvalues.FlagHolder[Optional[Text]]: 276 ... 277 278@overload 279def DEFINE_enum( 280 name : Text, 281 default: Text, 282 enum_values: Iterable[Text], 283 help: Optional[Text], 284 flag_values: _flagvalues.FlagValues = ..., 285 module_name: Optional[Text] = ..., 286 required: bool = ..., 287 **args: Any) -> _flagvalues.FlagHolder[Text]: 288 ... 289 290@overload 291def DEFINE_enum_class( 292 name: Text, 293 default: Union[None, _ET, Text], 294 enum_class: Type[_ET], 295 help: Optional[Text], 296 flag_values: _flagvalues.FlagValues = ..., 297 module_name: Optional[Text] = ..., 298 case_sensitive: bool = ..., 299 *, 300 required: Literal[True], 301 **args: Any) -> _flagvalues.FlagHolder[_ET]: 302 ... 303 304@overload 305def DEFINE_enum_class( 306 name: Text, 307 default: None, 308 enum_class: Type[_ET], 309 help: Optional[Text], 310 flag_values: _flagvalues.FlagValues = ..., 311 module_name: Optional[Text] = ..., 312 case_sensitive: bool = ..., 313 required: bool = ..., 314 **args: Any) -> _flagvalues.FlagHolder[Optional[_ET]]: 315 ... 316 317@overload 318def DEFINE_enum_class( 319 name: Text, 320 default: Union[_ET, Text], 321 enum_class: Type[_ET], 322 help: Optional[Text], 323 flag_values: _flagvalues.FlagValues = ..., 324 module_name: Optional[Text] = ..., 325 case_sensitive: bool = ..., 326 required: bool = ..., 327 **args: Any) -> _flagvalues.FlagHolder[_ET]: 328 ... 329 330 331@overload 332def DEFINE_list( 333 name: Text, 334 default: Union[None, Iterable[Text], Text], 335 help: Text, 336 flag_values: _flagvalues.FlagValues = ..., 337 *, 338 required: Literal[True], 339 **args: Any) -> _flagvalues.FlagHolder[List[Text]]: 340 ... 341 342@overload 343def DEFINE_list( 344 name: Text, 345 default: None, 346 help: Text, 347 flag_values: _flagvalues.FlagValues = ..., 348 required: bool = ..., 349 **args: Any) -> _flagvalues.FlagHolder[Optional[List[Text]]]: 350 ... 351 352@overload 353def DEFINE_list( 354 name: Text, 355 default: Union[Iterable[Text], Text], 356 help: Text, 357 flag_values: _flagvalues.FlagValues = ..., 358 required: bool = ..., 359 **args: Any) -> _flagvalues.FlagHolder[List[Text]]: 360 ... 361 362@overload 363def DEFINE_spaceseplist( 364 name: Text, 365 default: Union[None, Iterable[Text], Text], 366 help: Text, 367 comma_compat: bool = ..., 368 flag_values: _flagvalues.FlagValues = ..., 369 *, 370 required: Literal[True], 371 **args: Any) -> _flagvalues.FlagHolder[List[Text]]: 372 ... 373 374@overload 375def DEFINE_spaceseplist( 376 name: Text, 377 default: None, 378 help: Text, 379 comma_compat: bool = ..., 380 flag_values: _flagvalues.FlagValues = ..., 381 required: bool = ..., 382 **args: Any) -> _flagvalues.FlagHolder[Optional[List[Text]]]: 383 ... 384 385@overload 386def DEFINE_spaceseplist( 387 name: Text, 388 default: Union[Iterable[Text], Text], 389 help: Text, 390 comma_compat: bool = ..., 391 flag_values: _flagvalues.FlagValues = ..., 392 required: bool = ..., 393 **args: Any) -> _flagvalues.FlagHolder[List[Text]]: 394 ... 395 396@overload 397def DEFINE_multi( 398 parser : _argument_parser.ArgumentParser[_T], 399 serializer: _argument_parser.ArgumentSerializer[_T], 400 name: Text, 401 default: Union[None, Iterable[_T], _T, Text], 402 help: Text, 403 flag_values:_flagvalues.FlagValues = ..., 404 module_name: Optional[Text] = ..., 405 *, 406 required: Literal[True], 407 **args: Any) -> _flagvalues.FlagHolder[List[_T]]: 408 ... 409 410@overload 411def DEFINE_multi( 412 parser : _argument_parser.ArgumentParser[_T], 413 serializer: _argument_parser.ArgumentSerializer[_T], 414 name: Text, 415 default: None, 416 help: Text, 417 flag_values:_flagvalues.FlagValues = ..., 418 module_name: Optional[Text] = ..., 419 required: bool = ..., 420 **args: Any) -> _flagvalues.FlagHolder[Optional[List[_T]]]: 421 ... 422 423@overload 424def DEFINE_multi( 425 parser : _argument_parser.ArgumentParser[_T], 426 serializer: _argument_parser.ArgumentSerializer[_T], 427 name: Text, 428 default: Union[Iterable[_T], _T, Text], 429 help: Text, 430 flag_values:_flagvalues.FlagValues = ..., 431 module_name: Optional[Text] = ..., 432 required: bool = ..., 433 **args: Any) -> _flagvalues.FlagHolder[List[_T]]: 434 ... 435 436@overload 437def DEFINE_multi_string( 438 name: Text, 439 default: Union[None, Iterable[Text], Text], 440 help: Text, 441 flag_values: _flagvalues.FlagValues = ..., 442 *, 443 required: Literal[True], 444 **args: Any) -> _flagvalues.FlagHolder[List[Text]]: 445 ... 446 447@overload 448def DEFINE_multi_string( 449 name: Text, 450 default: None, 451 help: Text, 452 flag_values: _flagvalues.FlagValues = ..., 453 required: bool = ..., 454 **args: Any) -> _flagvalues.FlagHolder[Optional[List[Text]]]: 455 ... 456 457@overload 458def DEFINE_multi_string( 459 name: Text, 460 default: Union[Iterable[Text], Text], 461 help: Text, 462 flag_values: _flagvalues.FlagValues = ..., 463 required: bool = ..., 464 **args: Any) -> _flagvalues.FlagHolder[List[Text]]: 465 ... 466 467@overload 468def DEFINE_multi_integer( 469 name: Text, 470 default: Union[None, Iterable[int], int, Text], 471 help: Text, 472 lower_bound: Optional[int] = ..., 473 upper_bound: Optional[int] = ..., 474 flag_values: _flagvalues.FlagValues = ..., 475 *, 476 required: Literal[True], 477 **args: Any) -> _flagvalues.FlagHolder[List[int]]: 478 ... 479 480@overload 481def DEFINE_multi_integer( 482 name: Text, 483 default: None, 484 help: Text, 485 lower_bound: Optional[int] = ..., 486 upper_bound: Optional[int] = ..., 487 flag_values: _flagvalues.FlagValues = ..., 488 required: bool = ..., 489 **args: Any) -> _flagvalues.FlagHolder[Optional[List[int]]]: 490 ... 491 492@overload 493def DEFINE_multi_integer( 494 name: Text, 495 default: Union[Iterable[int], int, Text], 496 help: Text, 497 lower_bound: Optional[int] = ..., 498 upper_bound: Optional[int] = ..., 499 flag_values: _flagvalues.FlagValues = ..., 500 required: bool = ..., 501 **args: Any) -> _flagvalues.FlagHolder[List[int]]: 502 ... 503 504@overload 505def DEFINE_multi_float( 506 name: Text, 507 default: Union[None, Iterable[float], float, Text], 508 help: Text, 509 lower_bound: Optional[float] = ..., 510 upper_bound: Optional[float] = ..., 511 flag_values: _flagvalues.FlagValues = ..., 512 *, 513 required: Literal[True], 514 **args: Any) -> _flagvalues.FlagHolder[List[float]]: 515 ... 516 517@overload 518def DEFINE_multi_float( 519 name: Text, 520 default: None, 521 help: Text, 522 lower_bound: Optional[float] = ..., 523 upper_bound: Optional[float] = ..., 524 flag_values: _flagvalues.FlagValues = ..., 525 required: bool = ..., 526 **args: Any) -> _flagvalues.FlagHolder[Optional[List[float]]]: 527 ... 528 529@overload 530def DEFINE_multi_float( 531 name: Text, 532 default: Union[Iterable[float], float, Text], 533 help: Text, 534 lower_bound: Optional[float] = ..., 535 upper_bound: Optional[float] = ..., 536 flag_values: _flagvalues.FlagValues = ..., 537 required: bool = ..., 538 **args: Any) -> _flagvalues.FlagHolder[List[float]]: 539 ... 540 541 542@overload 543def DEFINE_multi_enum( 544 name: Text, 545 default: Union[None, Iterable[Text], Text], 546 enum_values: Iterable[Text], 547 help: Text, 548 flag_values: _flagvalues.FlagValues = ..., 549 *, 550 required: Literal[True], 551 **args: Any) -> _flagvalues.FlagHolder[List[Text]]: 552 ... 553 554@overload 555def DEFINE_multi_enum( 556 name: Text, 557 default: None, 558 enum_values: Iterable[Text], 559 help: Text, 560 flag_values: _flagvalues.FlagValues = ..., 561 required: bool = ..., 562 **args: Any) -> _flagvalues.FlagHolder[Optional[List[Text]]]: 563 ... 564 565@overload 566def DEFINE_multi_enum( 567 name: Text, 568 default: Union[Iterable[Text], Text], 569 enum_values: Iterable[Text], 570 help: Text, 571 flag_values: _flagvalues.FlagValues = ..., 572 required: bool = ..., 573 **args: Any) -> _flagvalues.FlagHolder[List[Text]]: 574 ... 575 576@overload 577def DEFINE_multi_enum_class( 578 name: Text, 579 # This is separate from `Union[None, _ET, Text]` to avoid a Pytype issue 580 # inferring the return value to FlagHolder[List[Union[_ET, enum.Enum]]] 581 # when an iterable of concrete enum subclasses are used. 582 default: Iterable[_ET], 583 enum_class: Type[_ET], 584 help: Text, 585 flag_values: _flagvalues.FlagValues = ..., 586 module_name: Optional[Text] = ..., 587 *, 588 required: Literal[True], 589 **args: Any) -> _flagvalues.FlagHolder[List[_ET]]: 590 ... 591 592@overload 593def DEFINE_multi_enum_class( 594 name: Text, 595 default: Union[None, _ET, Text], 596 enum_class: Type[_ET], 597 help: Text, 598 flag_values: _flagvalues.FlagValues = ..., 599 module_name: Optional[Text] = ..., 600 *, 601 required: Literal[True], 602 **args: Any) -> _flagvalues.FlagHolder[List[_ET]]: 603 ... 604 605@overload 606def DEFINE_multi_enum_class( 607 name: Text, 608 default: None, 609 enum_class: Type[_ET], 610 help: Text, 611 flag_values: _flagvalues.FlagValues = ..., 612 module_name: Optional[Text] = ..., 613 required: bool = ..., 614 **args: Any) -> _flagvalues.FlagHolder[Optional[List[_ET]]]: 615 ... 616 617@overload 618def DEFINE_multi_enum_class( 619 name: Text, 620 # This is separate from `Union[None, _ET, Text]` to avoid a Pytype issue 621 # inferring the return value to FlagHolder[List[Union[_ET, enum.Enum]]] 622 # when an iterable of concrete enum subclasses are used. 623 default: Iterable[_ET], 624 enum_class: Type[_ET], 625 help: Text, 626 flag_values: _flagvalues.FlagValues = ..., 627 module_name: Optional[Text] = ..., 628 required: bool = ..., 629 **args: Any) -> _flagvalues.FlagHolder[List[_ET]]: 630 ... 631 632@overload 633def DEFINE_multi_enum_class( 634 name: Text, 635 default: Union[_ET, Text], 636 enum_class: Type[_ET], 637 help: Text, 638 flag_values: _flagvalues.FlagValues = ..., 639 module_name: Optional[Text] = ..., 640 required: bool = ..., 641 **args: Any) -> _flagvalues.FlagHolder[List[_ET]]: 642 ... 643 644 645def DEFINE_alias( 646 name: Text, 647 original_name: Text, 648 flag_values: _flagvalues.FlagValues = ..., 649 module_name: Optional[Text] = ...) -> _flagvalues.FlagHolder[Any]: 650 ... 651 652 653def set_default(flag_holder: _flagvalues.FlagHolder[_T], value: _T) -> None: 654 ... 655 656 657def declare_key_flag(flag_name: Union[Text, _flagvalues.FlagHolder], 658 flag_values: _flagvalues.FlagValues = ...) -> None: 659 ... 660 661 662 663def adopt_module_key_flags(module: Any, 664 flag_values: _flagvalues.FlagValues = ...) -> None: 665 ... 666 667 668 669def disclaim_key_flags() -> None: 670 ... 671