lib.arg_check

1 ############################################################################### 2 # # 3 # Copyright (C) 2009-2014,2019 Edward d'Auvergne # 4 # Copyright (C) 2014 Troels E. Linnet # 5 # # 6 # This file is part of the program relax (http://www.nmr-relax.com). # 7 # # 8 # This program is free software: you can redistribute it and/or modify # 9 # it under the terms of the GNU General Public License as published by # 10 # the Free Software Foundation, either version 3 of the License, or # 11 # (at your option) any later version. # 12 # # 13 # This program is distributed in the hope that it will be useful, # 14 # but WITHOUT ANY WARRANTY; without even the implied warranty of # 15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # 16 # GNU General Public License for more details. # 17 # # 18 # You should have received a copy of the GNU General Public License # 19 # along with this program. If not, see <http://www.gnu.org/licenses/>. # 20 # # 21 ############################################################################### 22 23 # Module docstring. 24 """Argument checking functions for the relax user functions.""" 25 26 # Python module imports. 27 from numpy import ndarray 28 from types import FunctionType, MethodType 29 30 # relax module imports. 31 import lib.check_types 32 from lib.compat import from_iterable 33 from lib.errors import RelaxError, \ 34 RelaxArrayError, \ 35 RelaxArrayFloatError, \ 36 RelaxArrayIntError, \ 37 RelaxArrayNumError, \ 38 RelaxBoolError, \ 39 RelaxBoolListBoolError, \ 40 RelaxFloatError, \ 41 RelaxFunctionError, \ 42 RelaxIntError, \ 43 RelaxIntListIntError, \ 44 RelaxInvalidError, \ 45 RelaxListError, \ 46 RelaxListBoolError, \ 47 RelaxListFloatError, \ 48 RelaxListIntError, \ 49 RelaxListNumError, \ 50 RelaxListStrError, \ 51 RelaxMatrixFloatError, \ 52 RelaxNoneError, \ 53 RelaxNoneBoolError, \ 54 RelaxNoneBoolListBoolError, \ 55 RelaxNoneFloatError, \ 56 RelaxNoneFunctionError, \ 57 RelaxNoneIntError, \ 58 RelaxNoneIntListIntError, \ 59 RelaxNoneListError, \ 60 RelaxNoneListFloatError, \ 61 RelaxNoneListIntError, \ 62 RelaxNoneListNumError, \ 63 RelaxNoneListStrError, \ 64 RelaxNoneMatrixFloatError, \ 65 RelaxNoneNumError, \ 66 RelaxNoneNumStrListNumStrError, \ 67 RelaxNoneNumTupleNumError, \ 68 RelaxNoneStrError, \ 69 RelaxNoneStrFileError, \ 70 RelaxNoneStrListNumError, \ 71 RelaxNoneStrListStrError, \ 72 RelaxNoneTupleError, \ 73 RelaxNoneTupleNumError, \ 74 RelaxNoneValListValError, \ 75 RelaxNumError, \ 76 RelaxNumStrListNumStrError, \ 77 RelaxNumTupleNumError, \ 78 RelaxNumpyFloatError, \ 79 RelaxNumpyIntError, \ 80 RelaxNumpyNumError, \ 81 RelaxStrError, \ 82 RelaxStrFileError, \ 83 RelaxStrFileListStrFileError, \ 84 RelaxStrListNumError, \ 85 RelaxStrListStrError, \ 86 RelaxTupleError, \ 87 RelaxTupleNumError, \ 88 RelaxValListValError 89 from lib.io import DummyFileObject 90 91

92 -def is_bool(arg, name=None, can_be_none=False, raise_error=True):

93 """Test if the argument is a Boolean. 94 95 @param arg: The argument. 96 @type arg: anything 97 @keyword name: The plain English name of the argument. 98 @type name: str 99 @keyword can_be_none: A flag specifying if the argument can be none. 100 @type can_be_none: bool 101 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 102 @type raise_error: bool 103 @raise RelaxBoolError: If not a Boolean (and the raise_error flag is set). 104 @raise RelaxNoneBoolError: If not a Boolean or None (and the raise_error flag is set). 105 @return: The answer to the question (if raise_error is not set). 106 @rtype: bool 107 """ 108 109 # Check for a Boolean. 110 if isinstance(arg, bool): 111 return True 112 113 # An argument of None is allowed. 114 if can_be_none and arg is None: 115 return True 116 117 # Fail. 118 if not raise_error: 119 return False 120 if not can_be_none: 121 raise RelaxBoolError(name, arg) 122 else: 123 raise RelaxNoneBoolError(name, arg)

124 125

126 -def is_bool_or_bool_list(arg, name=None, size=None, can_be_none=False, can_be_empty=False, none_elements=False, raise_error=True):

127 """Test if the argument is a Boolean or a list of Booleans. 128 129 @param arg: The argument. 130 @type arg: anything 131 @keyword name: The plain English name of the argument. 132 @type name: str 133 @keyword size: The number of elements required. 134 @type size: None or int 135 @keyword can_be_none: A flag specifying if the argument can be none. 136 @type can_be_none: bool 137 @keyword can_be_empty: A flag which if True allows the list to be empty. 138 @type can_be_empty: bool 139 @keyword none_elements: A flag which if True allows the list to contain None. 140 @type none_elements: bool 141 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 142 @type raise_error: bool 143 @raise RelaxBoolListBoolError: If not a Boolean or a list of Booleans (and the raise_error flag is set). 144 @raise RelaxNoneBoolListBoolError: If not a Boolean, a list of Booleans, or None (and the raise_error flag is set). 145 @return: The answer to the question (if raise_error is not set). 146 @rtype: bool 147 """ 148 149 # Init. 150 fail = False 151 152 # An argument of None is allowed. 153 if can_be_none and arg is None: 154 return True 155 156 # A Boolean. 157 if not isinstance(arg, list): 158 if not is_bool(arg, raise_error=False): 159 fail = True 160 161 # A list. 162 else: 163 # Fail size is wrong. 164 if size != None and len(arg) != size: 165 fail = True 166 167 # Fail if empty. 168 if not can_be_empty and arg == []: 169 fail = True 170 171 # Check the arguments. 172 for i in range(len(arg)): 173 # None. 174 if arg[i] == None and none_elements: 175 continue 176 177 # Check if it is a Boolean. 178 if not is_bool(arg[i], raise_error=False): 179 fail = True 180 181 # Fail. 182 if fail: 183 if not raise_error: 184 return False 185 if can_be_none and size != None: 186 raise RelaxNoneBoolListBoolError(name, arg, size) 187 elif can_be_none: 188 raise RelaxNoneBoolListBoolError(name, arg) 189 elif size != None: 190 raise RelaxBoolListBoolError(name, arg, size) 191 else: 192 raise RelaxBoolListBoolError(name, arg) 193 194 # Success. 195 return True

196 197

198 -def is_float(arg, name=None, can_be_none=False, raise_error=True):

199 """Test if the argument is a float. 200 201 @param arg: The argument. 202 @type arg: anything 203 @keyword name: The plain English name of the argument. 204 @type name: str 205 @keyword can_be_none: A flag specifying if the argument can be none. 206 @type can_be_none: bool 207 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 208 @type raise_error: bool 209 @raise RelaxFloatError: If not an integer (and the raise_error flag is set). 210 @raise RelaxNoneFloatError: If not an integer or not None (and the raise_error flag is set). 211 @return: The answer to the question (if raise_error is not set). 212 @rtype: bool 213 """ 214 215 # An argument of None is allowed. 216 if can_be_none and arg is None: 217 return True 218 219 # Check for a float. 220 if lib.check_types.is_float(arg): 221 return True 222 223 # Fail. 224 if not raise_error: 225 return False 226 if not can_be_none: 227 raise RelaxFloatError(name, arg) 228 else: 229 raise RelaxNoneFloatError(name, arg)

230 231

232 -def is_float_array(arg, name=None, size=None, can_be_none=False, raise_error=True):

233 """Test if the argument is a list or a numpy array of floats. 234 235 @param arg: The argument. 236 @type arg: anything 237 @keyword name: The plain English name of the argument. 238 @type name: str 239 @keyword size: The dimension of the array. 240 @type size: None or int 241 @keyword can_be_none: A flag specifying if the argument can be none. 242 @type can_be_none: bool 243 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 244 @type raise_error: bool 245 @raise RelaxListFloatError: If not a list or numpy array of floats (and the raise_error flag is set). 246 @raise RelaxNoneListFloatError: If not a list or numpy array of floats or not None (and the raise_error flag is set). 247 @return: The answer to the question (if raise_error is not set). 248 @rtype: bool 249 """ 250 251 # Init. 252 fail = False 253 254 # An argument of None is allowed. 255 if can_be_none and arg is None: 256 return True 257 258 # Fail if not a list. 259 if not isinstance(arg, list) and not isinstance(arg, ndarray): 260 fail = True 261 262 # Fail if not the right dimension. 263 elif size != None and len(arg) != size: 264 fail = True 265 266 # Numpy array type check. 267 elif isinstance(arg, ndarray) and str(arg.dtype) not in ['float16', 'float32', 'float64', 'float128']: 268 fail = True 269 270 # Loop over the array. 271 else: 272 for i in range(len(arg)): 273 # Fail if not a float. 274 if not lib.check_types.is_float(arg[i]): 275 fail = True 276 277 # Fail. 278 if fail: 279 if not raise_error: 280 return False 281 if can_be_none and size != None: 282 raise RelaxNoneListFloatError(name, arg, size) 283 elif can_be_none: 284 raise RelaxNoneListFloatError(name, arg) 285 elif size != None: 286 raise RelaxListFloatError(name, arg, size) 287 else: 288 raise RelaxListFloatError(name, arg) 289 290 # Success. 291 return True

292 293

294 -def is_float_matrix(arg, name=None, dim=None, can_be_none=False, none_elements=False, raise_error=True):

295 """Test if the argument is a matrix of floats. 296 297 @param arg: The argument. 298 @type arg: anything 299 @keyword name: The plain English name of the argument. 300 @type name: str 301 @keyword dim: The m,n dimensions of the matrix. 302 @type dim: tuple of int 303 @keyword can_be_none: A flag specifying if the argument can be none. 304 @type can_be_none: bool 305 @keyword none_elements: A flag which if True allows the list to contain None. 306 @type none_elements: bool 307 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 308 @type raise_error: bool 309 @raise RelaxMatrixFloatError: If not a matrix of floats (and the raise_error flag is set). 310 @raise RelaxNoneMatrixFloatError: If not a matrix of floats or not None (and the raise_error flag is set). 311 @return: The answer to the question (if raise_error is not set). 312 @rtype: bool 313 """ 314 315 # Init. 316 fail = False 317 318 # An argument of None is allowed. 319 if can_be_none and arg is None: 320 return True 321 322 # Fail if not a list. 323 if not isinstance(arg, list) and not isinstance(arg, ndarray): 324 fail = True 325 326 # Fail on empty lists. 327 elif not len(arg): 328 fail = True 329 330 # Fail if not a matrix. 331 elif not isinstance(arg[0], list) and not isinstance(arg[0], ndarray): 332 fail = True 333 334 # Fail if not the right dimension. 335 elif dim != None and len(arg) != dim[0]: 336 fail = True 337 338 # Numpy array type check. 339 elif isinstance(arg, ndarray) and str(arg.dtype) not in ['float16', 'float32', 'float64', 'float128']: 340 fail = True 341 342 # Loop over the first dimension. 343 else: 344 for i in range(len(arg)): 345 # Catch None elements. 346 if arg[i] is None: 347 if not none_elements: 348 fail = True 349 continue 350 351 # Fail if not a list. 352 if not (isinstance(arg[i], list) or isinstance(arg[i], ndarray)): 353 fail = True 354 355 # Fail if not the right dimension. 356 elif dim != None and len(arg[i]) != dim[1]: 357 fail = True 358 359 # Check for float elements. 360 for j in range(len(arg[i])): 361 if not lib.check_types.is_float(arg[i][j]): 362 fail = True 363 364 # Fail. 365 if fail: 366 if not raise_error: 367 return False 368 if can_be_none and dim != None: 369 raise RelaxNoneMatrixFloatError(name, arg, dim) 370 elif can_be_none: 371 raise RelaxNoneMatrixFloatError(name, arg) 372 elif dim != None: 373 raise RelaxMatrixFloatError(name, arg, dim) 374 else: 375 raise RelaxMatrixFloatError(name, arg) 376 377 # Success. 378 return True

379 380

381 -def is_float_object(arg, name=None, dim=(3, 3), can_be_none=False, raise_error=True):

382 """Test if the argument is a rank-N array of floats. 383 384 @param arg: The argument. 385 @type arg: anything 386 @keyword name: The plain English name of the argument. 387 @type name: str 388 @keyword dim: The m,n dimensions of the matrix. 389 @type dim: tuple of int 390 @keyword can_be_none: A flag specifying if the argument can be none. 391 @type can_be_none: bool 392 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 393 @type raise_error: bool 394 @raise RelaxListFloatError: If not a object of floats (and the raise_error flag is set). 395 @raise RelaxNoneListFloatError: If not a object of floats or not None (and the raise_error flag is set). 396 @return: The answer to the question (if raise_error is not set). 397 @rtype: bool 398 """ 399 400 # Init. 401 fail = False 402 if isinstance(dim, int): 403 dim = [dim] 404 405 # An argument of None is allowed. 406 if can_be_none and arg is None: 407 return True 408 409 # Flatten the structure and determine its rank and dimensionality. 410 flat = arg 411 rank = 1 412 shape = [] 413 if isinstance(arg, list) and len(arg): 414 shape.append(len(arg)) 415 while 1: 416 if isinstance(flat[0], list) and len(flat[0]): 417 shape.append(len(flat[0])) 418 for element in flat: 419 if shape[-1] != len(element): 420 shape[-1] == None 421 flat = list(from_iterable(flat)) 422 rank += 1 423 else: 424 break 425 if isinstance(arg, ndarray): 426 flat = arg.flatten() 427 shape = arg.shape 428 rank = len(shape) 429 shape = tuple(shape) 430 431 # Fail if not a list or numpy array. 432 if not isinstance(arg, list) and not isinstance(arg, ndarray): 433 fail = True 434 435 # Fail if not the right rank. 436 elif dim != None and len(dim) != rank: 437 fail = True 438 439 # Fail if not the right dimensionality. 440 elif dim != None and dim != shape: 441 fail = True 442 443 # Individual element checks. 444 else: 445 for i in range(len(flat)): 446 if not lib.check_types.is_float(flat[i]): 447 fail = True 448 break 449 450 # Fail. 451 if fail: 452 if not raise_error: 453 return False 454 if can_be_none and dim != None: 455 raise RelaxNoneListFloatError(name, arg, dim) 456 elif can_be_none: 457 raise RelaxNoneListFloatError(name, arg) 458 elif dim != None: 459 raise RelaxListFloatError(name, arg, dim) 460 else: 461 raise RelaxListFloatError(name, arg) 462 463 # Success. 464 return True

465 466

467 -def is_func(arg, name=None, can_be_none=False, raise_error=True):

468 """Test if the argument is a function. 469 470 @param arg: The argument. 471 @type arg: anything 472 @keyword name: The plain English name of the argument. 473 @type name: str 474 @keyword can_be_none: A flag specifying if the argument can be none. 475 @type can_be_none: bool 476 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 477 @type raise_error: bool 478 @raise RelaxFunctionError: If not a function (and the raise_error flag is set). 479 @raise RelaxNoneFunctionError: If not a function or not None (and the raise_error flag is set). 480 @return: The answer to the question (if raise_error is not set). 481 @rtype: bool 482 """ 483 484 # An argument of None is allowed. 485 if can_be_none and arg is None: 486 return True 487 488 # Check for a function. 489 if isinstance(arg, FunctionType) or isinstance(arg, MethodType): 490 return True 491 492 # Fail. 493 if not raise_error: 494 return False 495 if not can_be_none: 496 raise RelaxFunctionError(name, arg) 497 else: 498 raise RelaxNoneFunctionError(name, arg)

499 500

501 -def is_int(arg, name=None, can_be_none=False, raise_error=True):

502 """Test if the argument is an integer. 503 504 @param arg: The argument. 505 @type arg: anything 506 @keyword name: The plain English name of the argument. 507 @type name: str 508 @keyword can_be_none: A flag specifying if the argument can be none. 509 @type can_be_none: bool 510 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 511 @type raise_error: bool 512 @raise RelaxIntError: If not an integer (and the raise_error flag is set). 513 @raise RelaxNoneIntError: If not an integer or not None (and the raise_error flag is set). 514 @return: The answer to the question (if raise_error is not set). 515 @rtype: bool 516 """ 517 518 # An argument of None is allowed. 519 if can_be_none and arg is None: 520 return True 521 522 # Check for an integer (avoiding Booleans). 523 if isinstance(arg, int) and not isinstance(arg, bool): 524 return True 525 526 # Fail. 527 if not raise_error: 528 return False 529 if not can_be_none: 530 raise RelaxIntError(name, arg) 531 else: 532 raise RelaxNoneIntError(name, arg)

533 534

535 -def is_int_list(arg, name=None, size=None, can_be_none=False, can_be_empty=False, none_elements=False, list_of_lists=False, raise_error=True):

536 """Test if the argument is a list of integers. 537 538 @param arg: The argument. 539 @type arg: anything 540 @keyword name: The plain English name of the argument. 541 @type name: str 542 @keyword size: The number of elements required. 543 @type size: None or int 544 @keyword can_be_none: A flag specifying if the argument can be none. 545 @type can_be_none: bool 546 @keyword can_be_empty: A flag which if True allows the list to be empty. 547 @type can_be_empty: bool 548 @keyword none_elements: A flag which if True allows the list to contain None. 549 @type none_elements: bool 550 @keyword list_of_lists: A flag which if True allows the argument to be a list of lists. 551 @type list_of_lists: bool 552 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 553 @type raise_error: bool 554 @raise RelaxListIntError: If not a list of integers (and the raise_error flag is set). 555 @raise RelaxNoneListIntError: If a list of integers or None (and the raise_error flag is set). 556 @return: The answer to the question (if raise_error is not set). 557 @rtype: bool 558 """ 559 560 # Init. 561 fail = False 562 563 # An argument of None is allowed. 564 if can_be_none and arg is None: 565 return True 566 567 # Fail if not a list. 568 if not isinstance(arg, list): 569 fail = True 570 571 # Fail size is wrong. 572 elif size != None and len(arg) != size: 573 fail = True 574 575 # Fail if empty. 576 elif not can_be_empty and len(arg) == 0: 577 fail = True 578 579 # Fail if not ints. 580 elif len(arg): 581 for element in arg: 582 # None. 583 if element == None and none_elements: 584 continue 585 586 # Booleans. 587 if isinstance(element, bool): 588 fail = True 589 break 590 591 # List of lists. 592 if list_of_lists and isinstance(element, list): 593 for i in range(len(element)): 594 if not isinstance(element[i], int): 595 fail = True 596 break 597 598 # Simple list. 599 elif not isinstance(element, int): 600 fail = True 601 break 602 603 # Fail. 604 if fail: 605 if not raise_error: 606 return False 607 if can_be_none and size != None: 608 raise RelaxNoneListIntError(name, arg, size) 609 elif can_be_none: 610 raise RelaxNoneListIntError(name, arg) 611 elif size != None: 612 raise RelaxListIntError(name, arg, size) 613 else: 614 raise RelaxListIntError(name, arg) 615 616 # Success. 617 return True

618 619

620 -def is_int_or_int_list(arg, name=None, size=None, can_be_none=False, can_be_empty=False, none_elements=False, raise_error=True):

621 """Test if the argument is an integer or a list of integers. 622 623 @param arg: The argument. 624 @type arg: anything 625 @keyword name: The plain English name of the argument. 626 @type name: str 627 @keyword size: The number of elements required. 628 @type size: None or int 629 @keyword can_be_none: A flag specifying if the argument can be none. 630 @type can_be_none: bool 631 @keyword can_be_empty: A flag which if True allows the list to be empty. 632 @type can_be_empty: bool 633 @keyword none_elements: A flag which if True allows the list to contain None. 634 @type none_elements: bool 635 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 636 @type raise_error: bool 637 @raise RelaxIntListIntError: If not an integer or a list of integers (and the raise_error flag is set). 638 @raise RelaxNoneIntListIntError: If not an integer, a list of integers, or None (and the raise_error flag is set). 639 @return: The answer to the question (if raise_error is not set). 640 @rtype: bool 641 """ 642 643 # Init. 644 fail = False 645 646 # An argument of None is allowed. 647 if can_be_none and arg is None: 648 return True 649 650 # An integer 651 if not isinstance(arg, list): 652 if not is_int(arg, raise_error=False): 653 fail = True 654 655 # A list. 656 else: 657 # Fail size is wrong. 658 if size != None and len(arg) != size: 659 fail = True 660 661 # Fail if empty. 662 if not can_be_empty and arg == []: 663 fail = True 664 665 # Check the arguments. 666 for i in range(len(arg)): 667 # None. 668 if arg[i] == None and none_elements: 669 continue 670 671 # Check if it is an integer. 672 if not is_int(arg[i], raise_error=False): 673 fail = True 674 675 # Fail. 676 if fail: 677 if not raise_error: 678 return False 679 if can_be_none and size != None: 680 raise RelaxNoneIntListIntError(name, arg, size) 681 elif can_be_none: 682 raise RelaxNoneIntListIntError(name, arg) 683 elif size != None: 684 raise RelaxIntListIntError(name, arg, size) 685 else: 686 raise RelaxIntListIntError(name, arg) 687 688 # Success. 689 return True

690 691

692 -def is_list(arg, name=None, size=None, can_be_none=False, can_be_empty=False, list_of_lists=False, raise_error=True):

693 """Test if the argument is a list. 694 695 @param arg: The argument. 696 @type arg: anything 697 @keyword name: The plain English name of the argument. 698 @type name: str 699 @keyword size: The number of elements required. 700 @type size: None or int 701 @keyword can_be_none: A flag specifying if the argument can be none. 702 @type can_be_none: bool 703 @keyword can_be_empty: A flag which if True allows the list to be empty. 704 @type can_be_empty: bool 705 @keyword list_of_lists: A flag which if True allows the argument to be a list of lists of strings. 706 @type list_of_lists: bool 707 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 708 @type raise_error: bool 709 @raise RelaxListError: If not a list (and the raise_error flag is set). 710 @raise RelaxNoneListError: If not a list or None (and the raise_error flag is set). 711 @return: The answer to the question (if raise_error is not set). 712 @rtype: bool 713 """ 714 715 # Init. 716 fail = False 717 718 # An argument of None is allowed. 719 if can_be_none and arg is None: 720 return True 721 722 # Fail if not a list. 723 if not isinstance(arg, list): 724 fail = True 725 726 # Fail size is wrong. 727 elif size != None and len(arg) != size: 728 fail = True 729 730 # Fail if empty. 731 elif not can_be_empty and len(arg) == 0: 732 fail = True 733 734 # Fail. 735 if fail: 736 if not raise_error: 737 return False 738 if can_be_none and size != None: 739 raise RelaxNoneListError(name, arg, size) 740 elif can_be_none: 741 raise RelaxNoneListError(name, arg) 742 elif size != None: 743 raise RelaxListError(name, arg, size) 744 else: 745 raise RelaxListError(name, arg) 746 747 # Success. 748 return True

749 750

751 -def is_none(arg, name, raise_error=True):

752 """Test if the argument is None. 753 754 @param arg: The argument. 755 @type arg: anything 756 @keyword name: The plain English name of the argument. 757 @type name: str 758 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 759 @type raise_error: bool 760 @raise RelaxNoneError: If not None (and the raise_error flag is set). 761 @return: The answer to the question (if raise_error is not set). 762 @rtype: bool 763 """ 764 765 # Check for None. 766 if arg is None: 767 return True 768 769 # Fail. 770 if not raise_error: 771 return False 772 else: 773 raise RelaxNoneError(name)

774 775

776 -def is_num(arg, name=None, can_be_none=False, raise_error=True):

777 """Test if the argument is a number. 778 779 @param arg: The argument. 780 @type arg: anything 781 @keyword name: The plain English name of the argument. 782 @type name: str 783 @keyword can_be_none: A flag specifying if the argument can be none. 784 @type can_be_none: bool 785 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 786 @type raise_error: bool 787 @raise RelaxNumError: If not a number (and the raise_error flag is set). 788 @raise RelaxNoneNumError: If not a number or not None (and the raise_error flag is set). 789 @return: The answer to the question (if raise_error is not set). 790 @rtype: bool 791 """ 792 793 # An argument of None is allowed. 794 if can_be_none and arg is None: 795 return True 796 797 # Check for floats and integers (avoiding Booleans). 798 if (lib.check_types.is_float(arg) or isinstance(arg, int)) and not isinstance(arg, bool): 799 return True 800 801 # Fail. 802 if not raise_error: 803 return False 804 if not can_be_none: 805 raise RelaxNumError(name, arg) 806 else: 807 raise RelaxNoneNumError(name, arg)

808 809

810 -def is_num_list(arg, name=None, size=None, can_be_none=False, can_be_empty=False, raise_error=True):

811 """Test if the argument is a list or numpy array of numbers. 812 813 @param arg: The argument. 814 @type arg: anything 815 @keyword name: The plain English name of the argument. 816 @type name: str 817 @keyword size: The number of elements required. 818 @type size: None or int 819 @keyword can_be_none: A flag specifying if the argument can be none. 820 @type can_be_none: bool 821 @keyword can_be_empty: A flag which if True allows the list to be empty. 822 @type can_be_empty: bool 823 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 824 @type raise_error: bool 825 @raise RelaxListNumError: If not a list of numbers (and the raise_error flag is set). 826 @raise RelaxNoneListNumError: If not a list of numbers or None (and the raise_error flag is set). 827 @return: The answer to the question (if raise_error is not set). 828 @rtype: bool 829 """ 830 831 # Init. 832 fail = False 833 834 # An argument of None is allowed. 835 if can_be_none and arg is None: 836 return True 837 838 # Fail if not a list or numpy array. 839 if not isinstance(arg, list) and not isinstance(arg, ndarray): 840 fail = True 841 842 # Fail size is wrong. 843 elif size != None and len(arg) != size: 844 fail = True 845 846 # Fail if empty. 847 elif not can_be_empty and len(arg) == 0: 848 fail = True 849 850 # Fail if not numbers. 851 elif len(arg): 852 for element in arg: 853 if isinstance(element, bool): 854 fail = True 855 break 856 857 if not lib.check_types.is_float(element) and not lib.check_types.is_int(element): 858 fail = True 859 break 860 861 # Fail. 862 if fail: 863 if not raise_error: 864 return False 865 if can_be_none and size != None: 866 raise RelaxNoneListNumError(name, arg, size) 867 elif can_be_none: 868 raise RelaxNoneListNumError(name, arg) 869 elif size != None: 870 raise RelaxListNumError(name, arg, size) 871 else: 872 raise RelaxListNumError(name, arg) 873 874 # Success. 875 return True

876 877

878 -def is_num_or_num_tuple(arg, name=None, size=None, can_be_none=False, can_be_empty=False, raise_error=True):

879 """Test if the argument is a number or tuple of numbers. 880 881 @param arg: The argument. 882 @type arg: anything 883 @keyword name: The plain English name of the argument. 884 @type name: str 885 @keyword size: The number of elements required. 886 @type size: None or int 887 @keyword can_be_none: A flag specifying if the argument can be none. 888 @type can_be_none: bool 889 @keyword can_be_empty: A flag which if True allows the list to be empty. 890 @type can_be_empty: bool 891 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 892 @type raise_error: bool 893 @raise RelaxNumTupleNumError: If not a number or a tuple of numbers (and the raise_error flag is set). 894 @raise RelaxNoneNumTupleNumError: If not a number, tuple of numbers, or None (and the raise_error flag is set). 895 @return: The answer to the question (if raise_error is not set). 896 @rtype: bool 897 """ 898 899 # Init. 900 fail = False 901 if size != None and not isinstance(size, list): 902 size = [size] 903 904 # An argument of None is allowed. 905 if can_be_none and arg is None: 906 return True 907 908 # A number. 909 if not isinstance(arg, tuple): 910 if not is_num(arg, raise_error=False): 911 fail = True 912 913 # Other checks. 914 else: 915 # Fail size is wrong. 916 if size != None and len(arg) not in size: 917 fail = True 918 919 # Fail if empty. 920 if not can_be_empty and not len(arg): 921 fail = True 922 923 # Fail if not numbers. 924 for i in range(len(arg)): 925 if not is_num(arg[i], raise_error=False): 926 fail = True 927 928 # Fail. 929 if fail: 930 if not raise_error: 931 return False 932 if can_be_none and size != None: 933 raise RelaxNoneNumTupleNumError(name, arg, size) 934 elif can_be_none: 935 raise RelaxNoneNumTupleNumError(name, arg) 936 elif size != None: 937 raise RelaxNumTupleNumError(name, arg, size) 938 else: 939 raise RelaxNumTupleNumError(name, arg) 940 941 # Success. 942 return True

943 944

945 -def is_num_tuple(arg, name=None, size=None, can_be_none=False, can_be_empty=False, raise_error=True):

946 """Test if the argument is a tuple of numbers. 947 948 @param arg: The argument. 949 @type arg: anything 950 @keyword name: The plain English name of the argument. 951 @type name: str 952 @keyword size: The number of elements required. 953 @type size: None or int 954 @keyword can_be_none: A flag specifying if the argument can be none. 955 @type can_be_none: bool 956 @keyword can_be_empty: A flag which if True allows the list to be empty. 957 @type can_be_empty: bool 958 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 959 @type raise_error: bool 960 @raise RelaxTupleNumError: If not a tuple of numbers (and the raise_error flag is set). 961 @raise RelaxNoneTupleNumError: If not a tuple of numbers or None (and the raise_error flag is set). 962 @return: The answer to the question (if raise_error is not set). 963 @rtype: bool 964 """ 965 966 # Init. 967 fail = False 968 969 # An argument of None is allowed. 970 if can_be_none and arg is None: 971 return True 972 973 # Fail if not a tuple. 974 if not isinstance(arg, tuple): 975 fail = True 976 977 # Fail size is wrong. 978 elif size != None and len(arg) != size: 979 fail = True 980 981 # Fail if empty. 982 elif not can_be_empty and len(arg) == 0: 983 fail = True 984 985 # Fail if not numbers. 986 elif len(arg): 987 for element in arg: 988 if isinstance(element, bool): 989 fail = True 990 break 991 992 if not lib.check_types.is_float(element) and not isinstance(element, int): 993 fail = True 994 break 995 996 # Fail. 997 if fail: 998 if not raise_error: 999 return False 1000 if can_be_none and size != None: 1001 raise RelaxNoneTupleNumError(name, arg, size) 1002 elif can_be_none: 1003 raise RelaxNoneTupleNumError(name, arg) 1004 elif size != None: 1005 raise RelaxTupleNumError(name, arg, size) 1006 else: 1007 raise RelaxTupleNumError(name, arg) 1008 1009 # Success. 1010 return True

1011 1012

1013 -def is_str(arg, name=None, can_be_none=False, raise_error=True):

1014 """Test if the argument is a string. 1015 1016 @param arg: The argument. 1017 @type arg: anything 1018 @keyword name: The plain English name of the argument. 1019 @type name: str 1020 @keyword can_be_none: A flag specifying if the argument can be none. 1021 @type can_be_none: bool 1022 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 1023 @type raise_error: bool 1024 @raise RelaxStrError: If not a string (and the raise_error flag is set). 1025 @raise RelaxNoneStrError: If not a string or not None (and the raise_error flag is set). 1026 @return: The answer to the question (if raise_error is not set). 1027 @rtype: bool 1028 """ 1029 1030 # An argument of None is allowed. 1031 if can_be_none and arg is None: 1032 return True 1033 1034 # Check for a string. 1035 if isinstance(arg, str): 1036 return True 1037 1038 # Fail. 1039 if not raise_error: 1040 return False 1041 if not can_be_none: 1042 raise RelaxStrError(name, arg) 1043 else: 1044 raise RelaxNoneStrError(name, arg)

1045 1046

1047 -def is_str_list(arg, name=None, size=None, can_be_none=False, can_be_empty=False, list_of_lists=False, raise_error=True):

1048 """Test if the argument is a list of strings. 1049 1050 @param arg: The argument. 1051 @type arg: anything 1052 @keyword name: The plain English name of the argument. 1053 @type name: str 1054 @keyword size: The number of elements required. 1055 @type size: None or int 1056 @keyword can_be_none: A flag specifying if the argument can be none. 1057 @type can_be_none: bool 1058 @keyword can_be_empty: A flag which if True allows the list to be empty. 1059 @type can_be_empty: bool 1060 @keyword list_of_lists: A flag which if True allows the argument to be a list of lists of strings. 1061 @type list_of_lists: bool 1062 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 1063 @type raise_error: bool 1064 @raise RelaxListStrError: If not a list of strings (and the raise_error flag is set). 1065 @raise RelaxNoneListStrError: If not a list of strings or None (and the raise_error flag is set). 1066 @return: The answer to the question (if raise_error is not set). 1067 @rtype: bool 1068 """ 1069 1070 # Init. 1071 fail = False 1072 1073 # An argument of None is allowed. 1074 if can_be_none and arg is None: 1075 return True 1076 1077 # Fail if not a list. 1078 if not isinstance(arg, list): 1079 fail = True 1080 1081 # Other checks. 1082 else: 1083 # Fail size is wrong. 1084 if size != None and len(arg) != size: 1085 fail = True 1086 1087 # Fail if empty. 1088 if not can_be_empty and arg == []: 1089 fail = True 1090 1091 # Fail if not strings. 1092 for i in range(len(arg)): 1093 # List of lists. 1094 if list_of_lists and isinstance(arg[i], list): 1095 for j in range(len(arg[i])): 1096 if not isinstance(arg[i][j], str): 1097 fail = True 1098 1099 # Simple list. 1100 else: 1101 if not isinstance(arg[i], str): 1102 fail = True 1103 1104 # Fail. 1105 if fail: 1106 if not raise_error: 1107 return False 1108 if can_be_none and size != None: 1109 raise RelaxNoneListStrError(name, arg, size) 1110 elif can_be_none: 1111 raise RelaxNoneListStrError(name, arg) 1112 elif size != None: 1113 raise RelaxListStrError(name, arg, size) 1114 else: 1115 raise RelaxListStrError(name, arg) 1116 1117 # Success. 1118 return True

1119 1120

1121 -def is_str_or_inst(arg, name=None, can_be_none=False, raise_error=True):

1122 """Test if the argument is a string or writable instance (file-like object). 1123 1124 @param arg: The argument. 1125 @type arg: anything 1126 @keyword name: The plain English name of the argument. 1127 @type name: str 1128 @keyword can_be_none: A flag specifying if the argument can be none. 1129 @type can_be_none: bool 1130 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 1131 @type raise_error: bool 1132 @raise RelaxStrFileError: If not a string or writeable instance (and the raise_error flag is set). 1133 @raise RelaxNoneStrFileError: If not a string, writeable instance or not None (and the raise_error flag is set). 1134 @return: The answer to the question (if raise_error is not set). 1135 @rtype: bool 1136 """ 1137 1138 # An argument of None is allowed. 1139 if can_be_none and arg is None: 1140 return True 1141 1142 # Check for a string. 1143 if isinstance(arg, str) or lib.check_types.is_filetype(arg) or isinstance(arg, DummyFileObject) or hasattr(arg, 'write'): 1144 return True 1145 1146 # Fail. 1147 if not raise_error: 1148 return False 1149 if not can_be_none: 1150 raise RelaxStrFileError(name, arg) 1151 else: 1152 raise RelaxNoneStrFileError(name, arg)

1153 1154

1155 -def is_str_or_num_or_str_num_list(arg, name=None, size=None, can_be_none=False, can_be_empty=False, raise_error=True):

1156 """Test if the argument is a number, a string, a list of numbers, or a list of strings. 1157 1158 @param arg: The argument. 1159 @type arg: anything 1160 @keyword name: The plain English name of the argument. 1161 @type name: str 1162 @keyword size: The number of elements required. 1163 @type size: None or int 1164 @keyword can_be_none: A flag specifying if the argument can be none. 1165 @type can_be_none: bool 1166 @keyword can_be_empty: A flag which if True allows the list to be empty. 1167 @type can_be_empty: bool 1168 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 1169 @type raise_error: bool 1170 @raise RelaxNumStrListNumStrError: If not a float, a string, or a list of floats or strings (and the raise_error flag is set). 1171 @raise RelaxNoneNumStrListNumStrError: If not a float, a string, a list of floats or strings, or None (and the raise_error flag is set). 1172 @return: The answer to the question (if raise_error is not set). 1173 @rtype: bool 1174 """ 1175 1176 # Init. 1177 fail = False 1178 1179 # An argument of None is allowed. 1180 if can_be_none and arg is None: 1181 return True 1182 1183 # A number or a string. 1184 if not isinstance(arg, list): 1185 # Check if it is a string or number. 1186 if not (is_str(arg, raise_error=False) or is_num(arg, raise_error=False)): 1187 fail = True 1188 1189 # A list. 1190 else: 1191 # Fail size is wrong. 1192 if size != None and len(arg) != size: 1193 fail = True 1194 1195 # Fail if empty. 1196 if not can_be_empty and arg == []: 1197 fail = True 1198 1199 # Check the arguments. 1200 for i in range(len(arg)): 1201 if not (is_str(arg[i], raise_error=False) or is_num(arg[i], raise_error=False)): 1202 fail = True 1203 1204 # Fail. 1205 if fail: 1206 if not raise_error: 1207 return False 1208 if can_be_none and size != None: 1209 raise RelaxNoneNumStrListNumStrError(name, arg, size) 1210 elif can_be_none: 1211 raise RelaxNoneNumStrListNumStrError(name, arg) 1212 elif size != None: 1213 raise RelaxNumStrListNumStrError(name, arg, size) 1214 else: 1215 raise RelaxNumStrListNumStrError(name, arg) 1216 1217 # Success. 1218 return True

1219 1220

1221 -def is_str_or_num_list(arg, name=None, size=None, can_be_none=False, can_be_empty=False, raise_error=True):

1222 """Test if the argument is a string or a list of numbers. 1223 1224 @param arg: The argument. 1225 @type arg: anything 1226 @keyword name: The plain English name of the argument. 1227 @type name: str 1228 @keyword size: The number of elements required. 1229 @type size: None or int 1230 @keyword can_be_none: A flag specifying if the argument can be none. 1231 @type can_be_none: bool 1232 @keyword can_be_empty: A flag which if True allows the list to be empty. 1233 @type can_be_empty: bool 1234 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 1235 @type raise_error: bool 1236 @raise RelaxStrListNumError: If not a string or a list of numbers (and the raise_error flag is set). 1237 @raise RelaxNoneStrListNumError: If not a string, a list of numbers, or None (and the raise_error flag is set). 1238 @return: The answer to the question (if raise_error is not set). 1239 @rtype: bool 1240 """ 1241 1242 # Init. 1243 fail = False 1244 1245 # An argument of None is allowed. 1246 if can_be_none and arg is None: 1247 return True 1248 1249 # A string. 1250 if not isinstance(arg, list): 1251 if not is_str(arg, raise_error=False): 1252 fail = True 1253 1254 # A list. 1255 else: 1256 # Fail size is wrong. 1257 if size != None and len(arg) != size: 1258 fail = True 1259 1260 # Fail if empty. 1261 if not can_be_empty and arg == []: 1262 fail = True 1263 1264 # Check the arguments. 1265 for i in range(len(arg)): 1266 if not is_num(arg[i], raise_error=False): 1267 fail = True 1268 1269 # Fail. 1270 if fail: 1271 if not raise_error: 1272 return False 1273 if can_be_none and size != None: 1274 raise RelaxNoneStrListNumError(name, arg, size) 1275 elif can_be_none: 1276 raise RelaxNoneStrListNumError(name, arg) 1277 elif size != None: 1278 raise RelaxStrListNumError(name, arg, size) 1279 else: 1280 raise RelaxStrListNumError(name, arg) 1281 1282 # Success. 1283 return True

1284 1285

1286 -def is_str_or_str_list(arg, name=None, size=None, can_be_none=False, can_be_empty=False, raise_error=True):

1287 """Test if the argument is a string or a list of strings. 1288 1289 @param arg: The argument. 1290 @type arg: anything 1291 @keyword name: The plain English name of the argument. 1292 @type name: str 1293 @keyword size: The number of elements required. 1294 @type size: None or int 1295 @keyword can_be_none: A flag specifying if the argument can be none. 1296 @type can_be_none: bool 1297 @keyword can_be_empty: A flag which if True allows the list to be empty. 1298 @type can_be_empty: bool 1299 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 1300 @type raise_error: bool 1301 @raise RelaxStrListStrError: If not a string or a list of strings (and the raise_error flag is set). 1302 @raise RelaxNoneStrListStrError: If not a string, a list of strings, or None (and the raise_error flag is set). 1303 @return: The answer to the question (if raise_error is not set). 1304 @rtype: bool 1305 """ 1306 1307 # Init. 1308 fail = False 1309 1310 # An argument of None is allowed. 1311 if can_be_none and arg is None: 1312 return True 1313 1314 # A string. 1315 if not isinstance(arg, list): 1316 if not is_str(arg, raise_error=False): 1317 fail = True 1318 1319 # A list. 1320 else: 1321 # Fail size is wrong. 1322 if size != None and len(arg) != size: 1323 fail = True 1324 1325 # Fail if empty. 1326 if not can_be_empty and arg == []: 1327 fail = True 1328 1329 # Check the arguments. 1330 for i in range(len(arg)): 1331 if not is_str(arg[i], raise_error=False): 1332 fail = True 1333 1334 # Fail. 1335 if fail: 1336 if not raise_error: 1337 return False 1338 if can_be_none and size != None: 1339 raise RelaxNoneStrListStrError(name, arg, size) 1340 elif can_be_none: 1341 raise RelaxNoneStrListStrError(name, arg) 1342 elif size != None: 1343 raise RelaxStrListStrError(name, arg, size) 1344 else: 1345 raise RelaxStrListStrError(name, arg) 1346 1347 # Success. 1348 return True

1349 1350

1351 -def is_tuple(arg, name=None, size=None, can_be_none=False, can_be_empty=False, raise_error=True):

1352 """Test if the argument is a tuple. 1353 1354 @param arg: The argument. 1355 @type arg: anything 1356 @keyword name: The plain English name of the argument. 1357 @type name: str 1358 @keyword size: The number of elements required. 1359 @type size: None or int 1360 @keyword can_be_none: A flag specifying if the argument can be none. 1361 @type can_be_none: bool 1362 @keyword can_be_empty: A flag which if True allows the list to be empty. 1363 @type can_be_empty: bool 1364 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 1365 @type raise_error: bool 1366 @raise RelaxTupleError: If not a tuple (and the raise_error flag is set). 1367 @raise RelaxNoneTupleError: If not a tuple or not None (and the raise_error flag is set). 1368 @return: The answer to the question (if raise_error is not set). 1369 @rtype: bool 1370 """ 1371 1372 # Init. 1373 fail = False 1374 1375 # An argument of None is allowed. 1376 if can_be_none and arg is None: 1377 return True 1378 1379 # Fail if not a tuple. 1380 if not isinstance(arg, tuple): 1381 fail = True 1382 1383 # Other checks. 1384 else: 1385 # Fail size is wrong. 1386 if size != None and len(arg) != size: 1387 fail = True 1388 1389 # Fail if empty. 1390 if not can_be_empty and arg == []: 1391 fail = True 1392 1393 # Fail. 1394 if fail: 1395 if not raise_error: 1396 return False 1397 if can_be_none and size != None: 1398 raise RelaxNoneTupleError(name, arg, size) 1399 elif can_be_none: 1400 raise RelaxNoneTupleError(name, arg) 1401 elif size != None: 1402 raise RelaxTupleError(name, arg, size) 1403 else: 1404 raise RelaxTupleError(name, arg) 1405 1406 # Success. 1407 return True

1408 1409

1410 -def is_val_or_list(arg, name=None, size=None, can_be_none=False, can_be_empty=False, raise_error=True):

1411 """Test if the argument is a value (bool, str, or number) or a list of values. 1412 1413 @param arg: The argument. 1414 @type arg: anything 1415 @keyword name: The plain English name of the argument. 1416 @type name: str 1417 @keyword size: The number of elements required. 1418 @type size: None or int 1419 @keyword can_be_none: A flag specifying if the argument can be none. 1420 @type can_be_none: bool 1421 @keyword can_be_empty: A flag which if True allows the list to be empty. 1422 @type can_be_empty: bool 1423 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 1424 @type raise_error: bool 1425 @raise RelaxValListValError: If not a value or list of values (and the raise_error flag is set). 1426 @raise RelaxNoneValListValError: If not a value, a list of values, or None (and the raise_error flag is set). 1427 @return: The answer to the question (if raise_error is not set). 1428 @rtype: bool 1429 """ 1430 1431 # Init. 1432 fail = False 1433 1434 # An argument of None is allowed. 1435 if can_be_none and arg is None: 1436 return True 1437 1438 # A value. 1439 if not isinstance(arg, list): 1440 # Check for all types of value. 1441 if not (is_bool(arg, raise_error=False) or is_str(arg, raise_error=False) or is_num(arg, raise_error=False)): 1442 fail = True 1443 1444 # A list. 1445 else: 1446 # Fail size is wrong. 1447 if size != None and len(arg) != size: 1448 fail = True 1449 1450 # Fail if empty. 1451 if not can_be_empty and arg == []: 1452 fail = True 1453 1454 # Check the arguments. 1455 for i in range(len(arg)): 1456 # Check for all types of value. 1457 if not (is_bool(arg[i], raise_error=False) or is_str(arg[i], raise_error=False) or is_num(arg[i], raise_error=False)): 1458 fail = True 1459 1460 # Fail. 1461 if fail: 1462 if not raise_error: 1463 return False 1464 if can_be_none and size != None: 1465 raise RelaxNoneValListValError(name, arg, size) 1466 elif can_be_none: 1467 raise RelaxNoneValListValError(name, arg) 1468 elif size != None: 1469 raise RelaxValListValError(name, arg, size) 1470 else: 1471 raise RelaxValListValError(name, arg) 1472 1473 # Success. 1474 return True

1475 1476

1477 -def validate_arg(arg, name=None, dim=tuple(), basic_types=[], container_types=[], can_be_none=False, can_be_empty=False, none_elements=False, raise_error=True):

1478 """Generic validation function for any argument type. 1479 1480 This function can be used to validate the value of any argument, raising a RelaxError specific for the argument for detailed user feedback. 1481 1482 Types 1483 ===== 1484 1485 The basic Python data types allowed for the argument are specified via the basic_types argument. The currently supported values include: 1486 1487 - 'all': Special value used to deactivate type-checking. 1488 - 'bool': Boolean values (True and False). 1489 - 'float': Floating point numbers. 1490 - 'func': Python function objects. 1491 - 'int': Integer numbers. 1492 - 'number': Special value allowing for any number type. 1493 - 'str': String objects. 1494 - 'file object read': Readable file objects (instance of file or any object with read methods). 1495 - 'file object write': Writable file objects (instance of file or any object with write methods). 1496 1497 The 'number' value is special in that it allows for both 'int' and 'float' values. If the argument should be a higher rank object, then the container_types argument should be supplied. The allowed values currently include: 1498 1499 - 'all': Special value used to deactivate type-checking. 1500 - 'list': Python lists. 1501 - 'number array': Special value meaning both 'list' and 'numpy array'. 1502 - 'numpy array': NumPy array objects. 1503 - 'set': Python sets. 1504 - 'tuple': Python tuples. 1505 1506 Here, the 'number array' is also special and allows for both 'list' and 'numpy array' containers. Note that only the basic types 'float', 'int', and 'number' are allowed with this value. 1507 1508 1509 Rank and dimensionality 1510 ======================= 1511 1512 To distinguish between basic Python data types and higher rank container types, as well as fixing the dimensionality of the higher rank objects, the 'dim' parameter should be supplied. This should be a tuple with elements consisting of integers or None. If multiple ranks or dimensionality are allowed, then a list of tuples can be supplied. 1513 1514 1515 Rank 1516 ---- 1517 1518 The number of elements of the 'dim' tuples define the rank. For example a number is rank 0, a vector is rank 1, and a matrix is rank 2. 1519 1520 1521 Dimensionality 1522 -------------- 1523 1524 The dimensionality, or number of elements, for each rank are fixed by supplying integers in the 'dim' tuple. If the dimensionality can be variable, the value of None should be supplied instead. 1525 1526 1527 Examples 1528 -------- 1529 1530 For basic Python data types, use the empty tuple: 1531 1532 - dim=() 1533 1534 For a list of basic data types of unknown length, use: 1535 1536 - dim=(None,) 1537 1538 For a numpy array of 5 elements, use: 1539 1540 - dim=(5,) 1541 1542 For a numpy 3D matrix, use: 1543 1544 - dim=(3,3) 1545 1546 For a simple string or list of string, use: 1547 1548 - dim=[(), (None,)] 1549 1550 1551 Fall back error 1552 =============== 1553 1554 For arguments which do not currently have a specific RelaxError for telling the user what the did wrong, the fall back RelaxInvalidError object will be raised. If more detailed feedback to the user is desired, then a new RelaxError object should be created and added in the failure section of this function. 1555 1556 1557 @param arg: The argument. 1558 @type arg: anything 1559 @keyword name: The plain English name of the argument, used in the RelaxError printout. 1560 @type name: str 1561 @keyword dim: The dimensions of the object to check. 1562 @type dim: tuple of (int or None) or list of tuples of (int or None) 1563 @keyword basic_types: The types of values are allowed for the argument. 1564 @type basic_types: list of str 1565 @keyword container_types: The container types allowed for the argument. 1566 @type container_types: list of str 1567 @keyword can_be_none: A flag specifying if the argument can be none. 1568 @type can_be_none: bool 1569 @keyword can_be_empty: A flag which if True allows container types to be empty. 1570 @type can_be_empty: bool 1571 @keyword none_elements: A flag which if True allows container types to contain None. 1572 @type none_elements: bool 1573 @keyword raise_error: A flag which if True will cause RelaxErrors to be raised. 1574 @type raise_error: bool 1575 @raise RelaxError: If the function arguments are incorrectly supplied. 1576 @raise RelaxArrayError: If a list or numpy array is expected (and the raise_error flag is set). 1577 @raise RelaxArrayFloatError: If a list or numpy array of floats is expected (and the raise_error flag is set). 1578 @raise RelaxArrayIntError: If a list or numpy array of integers is expected (and the raise_error flag is set). 1579 @raise RelaxArrayNumError: If a list or numpy array of numbers is expected (and the raise_error flag is set). 1580 @raise RelaxBoolError: If a Boolean value is expected (and the raise_error flag is set). 1581 @raise RelaxBoolListBoolError: If a Boolean or list of Booleans is expected (and the raise_error flag is set). 1582 @raise RelaxFloatError: If a float value is expected (and the raise_error flag is set). 1583 @raise RelaxFunctionError: If a function is expected (and the raise_error flag is set). 1584 @raise RelaxIntError: If an integer value is expected (and the raise_error flag is set). 1585 @raise RelaxIntListIntError: If an integer value or list of integers is expected (and the raise_error flag is set). 1586 @raise RelaxListError: If a list of different basic types is expected (and the raise_error flag is set). 1587 @raise RelaxListBoolError: If a list of Booleans is expected (and the raise_error flag is set). 1588 @raise RelaxListFloatError: If a list of floats is expected (and the raise_error flag is set). 1589 @raise RelaxListIntError: If a list of integers is expected (and the raise_error flag is set). 1590 @raise RelaxListNumError: If a list of numbers is expected (and the raise_error flag is set). 1591 @raise RelaxListStrError: If a list of strings is expected (and the raise_error flag is set). 1592 @raise RelaxNumError: If a number value is expected (and the raise_error flag is set). 1593 @raise RelaxNumTupleNumError: If a number or tuple of numbers is expected (and the raise_error flag is set). 1594 @raise RelaxNumpyFloatError: If a numpy array of floats is expected (and the raise_error flag is set). 1595 @raise RelaxNumpyIntError: If a numpy array of integers is expected (and the raise_error flag is set). 1596 @raise RelaxNumpyNumError: If a numpy array is expected (and the raise_error flag is set). 1597 @raise RelaxStrError: If a string value is expected (and the raise_error flag is set). 1598 @raise RelaxStrFileError: If a string value or file object is expected (and the raise_error flag is set). 1599 @raise RelaxStrFileListStrFileError: If a string value, file object, list of strings, or list of file objects is expected (and the raise_error flag is set). 1600 @raise RelaxStrListStrError: If a string value or list of string values is expected (and the raise_error flag is set). 1601 @raise RelaxTupleNumError: If a tuple of numbers is expected (and the raise_error flag is set). 1602 @raise RelaxInvalidError: For all argument combinations not covered by a specific RelaxError (and the raise_error flag is set). 1603 @return: The answer to the question (if raise_error is not set). 1604 @rtype: bool 1605 """ 1606 1607 # An argument of None is allowed. 1608 if can_be_none and arg is None: 1609 return True 1610 1611 # No type-checking. 1612 if 'all' in basic_types and 'all' in container_types: 1613 return True 1614 1615 # Init. 1616 fail = False 1617 1618 # Checks. 1619 if 'number array' in container_types: 1620 for type in basic_types: 1621 if type not in ['float', 'int', 'number']: 1622 raise RelaxError("The 'number array' container type does not support the '%s' basic Python data type." % type) 1623 if 'number' in basic_types and ('int' in basic_types or 'float' in basic_types): 1624 raise RelaxError("The 'int' or 'float' basic data types cannot be supplied if 'number' is a basic type.") 1625 1626 1627 # Process the expected dimensionality. 1628 allowed_rank = [] 1629 allowed_shape = [] 1630 if isinstance(dim, list): 1631 for i in range(len(dim)): 1632 allowed_rank.append(len(dim[i])) 1633 allowed_shape.append(dim[i]) 1634 else: 1635 allowed_rank.append(len(dim)) 1636 allowed_shape.append(dim) 1637 1638 # Determine the argument's rank and dimensionality, and create a flatten version of the structure. 1639 flat = arg 1640 shape = [] 1641 rank = 1 1642 numpy_type = None 1643 if isinstance(arg, set): 1644 if 'set' not in container_types: 1645 fail = True 1646 shape = [len(arg)] 1647 flat = list(arg) 1648 elif isinstance(arg, list) or isinstance(arg, tuple): 1649 if isinstance(arg, list) and ('list' not in container_types and 'number array' not in container_types): 1650 fail = True 1651 if isinstance(arg, tuple) and 'tuple' not in container_types: 1652 fail = True 1653 shape.append(len(arg)) 1654 while 1: 1655 if len(flat) and (isinstance(flat[0], list) or isinstance(flat[0], tuple)): 1656 shape.append(len(flat[0])) 1657 for element in flat: 1658 if isinstance(element, list) and ('list' not in container_types and 'number array' not in container_types): 1659 fail = True 1660 if isinstance(element, tuple) and 'tuple' not in container_types: 1661 fail = True 1662 if shape[-1] != len(element): 1663 shape[-1] == None 1664 flat = list(from_iterable(flat)) 1665 rank += 1 1666 else: 1667 break 1668 shape = tuple(shape) 1669 elif isinstance(arg, ndarray): 1670 if 'numpy array' not in container_types and 'number array' not in container_types: 1671 fail = True 1672 flat = arg.flatten() 1673 shape = arg.shape 1674 rank = len(shape) 1675 numpy_type = str(arg.dtype) 1676 else: 1677 flat = [arg] 1678 rank = 0 1679 shape = tuple() 1680 1681 # Already failed, so skip. 1682 if fail: 1683 pass 1684 1685 # Fail if empty. 1686 elif rank and shape[-1] == 0 and not can_be_empty: 1687 fail = True 1688 1689 # Fail if not the right rank. 1690 elif rank not in allowed_rank: 1691 fail = True 1692 1693 # Fail if not the right dimensionality. 1694 elif shape not in allowed_shape: 1695 index = allowed_rank.index(rank) 1696 for i in range(rank): 1697 if allowed_shape[index][i] != None and allowed_shape[index][i] != shape[i]: 1698 fail = True 1699 1700 # Type checking. 1701 if not fail: 1702 # Numpy types. 1703 if numpy_type: 1704 # Integers. 1705 if numpy_type[:3] == 'int' and 'int' not in basic_types and 'number' not in basic_types: 1706 fail = True 1707 1708 # Floats. 1709 elif numpy_type[:5] == 'float' and 'float' not in basic_types and 'number' not in basic_types: 1710 fail = True 1711 1712 # Individual element checks. 1713 for element in flat: 1714 # None elements. 1715 if element == None: 1716 if not none_elements: 1717 fail = True 1718 continue 1719 1720 # All values are allowed. 1721 if len(basic_types) == 0 or 'all' in basic_types: 1722 continue 1723 1724 # Booleans. 1725 if isinstance(element, bool): 1726 if 'bool' not in basic_types: 1727 fail = True 1728 1729 # Integers. 1730 elif lib.check_types.is_int(element): 1731 if 'int' not in basic_types and 'number' not in basic_types: 1732 fail = True 1733 1734 # Floats. 1735 elif lib.check_types.is_float(element): 1736 if 'float' not in basic_types and 'number' not in basic_types: 1737 fail = True 1738 1739 # Strings. 1740 elif isinstance(element, str): 1741 if 'str' not in basic_types: 1742 fail = True 1743 1744 # Functions. 1745 elif isinstance(element, FunctionType) or isinstance(element, MethodType): 1746 if 'func' not in basic_types: 1747 fail = True 1748 1749 # File objects. 1750 elif lib.check_types.is_filetype_rw(element): 1751 if 'file object read' not in basic_types and 'file object write' not in basic_types: 1752 fail = True 1753 elif lib.check_types.is_filetype_readable(element): 1754 if 'file object read' not in basic_types: 1755 fail = True 1756 elif lib.check_types.is_filetype_writable(element): 1757 if 'file object write' not in basic_types: 1758 fail = True 1759 1760 # Unhandled type. 1761 else: 1762 fail = True 1763 1764 # No need to continue. 1765 if fail: 1766 break 1767 1768 # Failure. 1769 if fail: 1770 # No error. 1771 if not raise_error: 1772 return False 1773 1774 # Multiple types. 1775 if len(basic_types) > 1 or len(basic_types) == 0: 1776 # String or file object. 1777 if len(basic_types) == 2 and 'str' in basic_types and ('file object read' in basic_types or 'file object write' in basic_types): 1778 if max(allowed_rank) == 0: 1779 raise RelaxStrFileError(name, arg, can_be_none=can_be_none) 1780 if max(allowed_rank) == 1: 1781 raise RelaxStrFileListStrFileError(name, arg, can_be_none=can_be_none) 1782 1783 # Array types. 1784 if max(allowed_rank) == 1 and min(allowed_rank) == 1: 1785 # List or numpy array. 1786 if 'list' in container_types and 'numpy array' in container_types: 1787 raise RelaxArrayError(name, arg, can_be_none=can_be_none) 1788 1789 # Lists. 1790 elif 'list' in container_types: 1791 raise RelaxListError(name, arg, can_be_none=can_be_none) 1792 1793 # Numpy arrays. 1794 elif 'numpy array' in container_types: 1795 raise RelaxNumpyNumError(name, arg, can_be_none=can_be_none) 1796 1797 # Tuples. 1798 elif 'tuple' in container_types: 1799 raise RelaxTupleError(name, arg, can_be_none=can_be_none) 1800 1801 # Boolean errors. 1802 elif 'bool' in basic_types: 1803 # Boolean or list of Booleans. 1804 if min(allowed_rank) == 0 and max(allowed_rank) == 1: 1805 raise RelaxBoolListBoolError(name, arg, can_be_none=can_be_none) 1806 1807 # Basic Boolean type. 1808 elif max(allowed_rank) == 0: 1809 raise RelaxBoolError(name, arg, can_be_none=can_be_none) 1810 1811 # Boolean list. 1812 elif max(allowed_rank) == 1 and min(allowed_rank) == 1: 1813 raise RelaxListBoolError(name, arg, can_be_none=can_be_none) 1814 1815 # Float errors. 1816 elif 'float' in basic_types: 1817 # Basic float type. 1818 if max(allowed_rank) == 0: 1819 raise RelaxFloatError(name, arg, can_be_none=can_be_none) 1820 1821 # List or numpy array of floats. 1822 elif 'number array' in container_types: 1823 raise RelaxArrayFloatError(name, arg, dim=dim, can_be_none=can_be_none) 1824 1825 # Numpy integer array. 1826 elif 'numpy array' in container_types: 1827 raise RelaxNumpyFloatError(name, arg, dim=dim, can_be_none=can_be_none) 1828 1829 # List of floats. 1830 elif max(allowed_rank) == 1 and min(allowed_rank) == 1: 1831 raise RelaxListFloatError(name, arg, can_be_none=can_be_none) 1832 1833 # Integer errors. 1834 elif 'int' in basic_types: 1835 # Integer or list of integers. 1836 if min(allowed_rank) == 0 and max(allowed_rank) == 1: 1837 raise RelaxIntListIntError(name, arg, can_be_none=can_be_none) 1838 1839 # Basic integer type. 1840 elif max(allowed_rank) == 0: 1841 raise RelaxIntError(name, arg, can_be_none=can_be_none) 1842 1843 # List or numpy array of integers. 1844 elif 'number array' in container_types: 1845 raise RelaxArrayIntError(name, arg, dim=dim, can_be_none=can_be_none) 1846 1847 # Numpy integer array. 1848 elif 'numpy array' in container_types: 1849 raise RelaxNumpyIntError(name, arg, dim=dim, can_be_none=can_be_none) 1850 1851 # Integer list. 1852 elif max(allowed_rank) == 1 and min(allowed_rank) == 1: 1853 raise RelaxListIntError(name, arg, can_be_none=can_be_none) 1854 1855 # Number errors. 1856 elif 'number' in basic_types: 1857 # Number or container of numbers. 1858 num_cont_num = False 1859 if min(allowed_rank) == 0 and max(allowed_rank) == 1: 1860 num_cont_num = True 1861 1862 # Rank-0. 1863 if len(container_types) == 0: 1864 raise RelaxNumError(name, arg, can_be_none=can_be_none) 1865 1866 # Mixed types. 1867 elif len(container_types) > 1: 1868 pass 1869 1870 # List or numpy array of numbers. 1871 elif 'number array' in container_types: 1872 raise RelaxArrayNumError(name, arg, dim=dim, can_be_none=can_be_none) 1873 1874 # Numpy arrays. 1875 elif 'numpy array' in container_types: 1876 raise RelaxNumpyNumError(name, arg, dim=dim, can_be_none=can_be_none) 1877 1878 # List of numbers. 1879 elif 'list' in container_types: 1880 raise RelaxListNumError(name, arg, dim=dim, can_be_none=can_be_none) 1881 1882 # Tuple of numbers. 1883 elif 'tuple' in container_types: 1884 if num_cont_num: 1885 raise RelaxNumTupleNumError(name, arg, dim=dim, can_be_none=can_be_none) 1886 else: 1887 raise RelaxTupleNumError(name, arg, dim=dim, can_be_none=can_be_none) 1888 1889 # String errors. 1890 elif 'str' in basic_types: 1891 # String or list of strings. 1892 if min(allowed_rank) == 0 and max(allowed_rank) == 1: 1893 raise RelaxStrListStrError(name, arg, can_be_none=can_be_none) 1894 1895 # Basic string type. 1896 elif max(allowed_rank) == 0: 1897 raise RelaxStrError(name, arg, can_be_none=can_be_none) 1898 1899 # List of strings. 1900 elif max(allowed_rank) == 1 and min(allowed_rank) == 1: 1901 raise RelaxListStrError(name, arg, can_be_none=can_be_none) 1902 1903 # Function errors. 1904 elif 'func' in basic_types: 1905 # Basic function type. 1906 if max(allowed_rank) == 0: 1907 raise RelaxFunctionError(name, arg, can_be_none=can_be_none) 1908 1909 # Final fall back. 1910 raise RelaxInvalidError(name, arg) 1911 1912 # Success. 1913 return True

1914

Source Code for Module lib.arg_check