Source

JythonBook / appendixC.rst

Full commit
Josh Juneau dd1b66e 

Josh Juneau d9b2bb8 


























































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
Appendix C: Built-in Functions - *Draft*
========================================

Constructor Functions
---------------------

Constructor functions are used to create objects of a given type.

.. note:: 

  In Python, the type is a constructor function; there's no difference
  at all in Python. So you can use the ``type`` function, which we
  will discuss momentarily, to look up the type of an object, then make
  instances of that same type.

First we will look at the constructor functions, which are more
typically used for conversion. This is because there is generally a
convenient literal syntax available, or in the case of ``bool``, there
are only two such constants, ``True`` and ``False``.

.. function:: bool([x])

   Convert a value to a Boolean, using the standard truth testing procedure.  If
   *x* is false or omitted, this returns :const:`False`; otherwise it returns
   :const:`True`. :class:`bool` is also a class, which is a subclass of
   :class:`int`. Class :class:`bool` cannot be subclassed further.  Its only
   instances are :const:`False` and :const:`True`.

   If no argument is given, this function returns :const:`False`.

.. function:: chr(i)

   Return a string of one character whose ASCII code is the integer *i*.  For
   example, ``chr(97)`` returns the string ``'a'``. This is the inverse of
   :func:`ord`.  The argument must be in the range [0..255], inclusive;
   :exc:`ValueError` will be raised if *i* is outside that range. See
   also :func:`unichr`.

.. function:: complex([real[, imag]])

   Create a complex number with the value *real* + *imag*\*j or convert a string or
   number to a complex number.  If the first parameter is a string, it will be
   interpreted as a complex number and the function must be called without a second
   parameter.  The second parameter can never be a string. Each argument may be any
   numeric type (including complex). If *imag* is omitted, it defaults to zero and
   the function serves as a numeric conversion function like :func:`int`,
   :func:`long` and :func:`float`.  If both arguments are omitted, returns ``0j``.

.. function:: dict([arg])
   :noindex:

   Create a new data dictionary, optionally with items taken from *arg*.
   The dictionary type is described in :ref:`typesmapping`.

   For other containers see the built in :class:`list`, :class:`set`, and
   :class:`tuple` classes, and the :mod:`collections` module.

Although there is a convenient literal for creating ``dict`` objects::

  a_dict = { 'alpha' : 1, 'beta' : 2, 'gamma' : 3 }

It can be more convenient to create them using the ``dict`` function::

  a_dict = dict(alpha=1, beta=2, gamma=3)

Of course in this latter case, the keys of the entries being created
must be valid Python keywords.

.. function:: float([x])

   Convert a string or a number to floating point.  If the argument is a string, it
   must contain a possibly signed decimal or floating point number, possibly
   embedded in whitespace. The argument may also be [+|-]nan or [+|-]inf.
   Otherwise, the argument may be a plain or long integer
   or a floating point number, and a floating point number with the same value
   (within Python's floating point precision) is returned.  If no argument is
   given, returns ``0.0``.

.. function:: frozenset([iterable])
   :noindex:

   Return a frozenset object, optionally with elements taken from *iterable*.
   The frozenset type is described in :ref:`types-set`.

   For other containers see the built in :class:`dict`, :class:`list`, and
   :class:`tuple` classes, and the :mod:`collections` module.

.. function:: int([x[, radix]])

   Convert a string or number to a plain integer.  If the argument is a string,
   it must contain a possibly signed decimal number representable as a Python
   integer, possibly embedded in whitespace.  The *radix* parameter gives the
   base for the conversion (which is 10 by default) and may be any integer in
   the range [2, 36], or zero.  If *radix* is zero, the proper radix is
   determined based on the contents of string; the interpretation is the same as
   for integer literals.  (See :ref:`numbers`.)  If *radix* is specified and *x*
   is not a string, :exc:`TypeError` is raised. Otherwise, the argument may be a
   plain or long integer or a floating point number.  Conversion of floating
   point numbers to integers truncates (towards zero).  If the argument is
   outside the integer range a long object will be returned instead.  If no
   arguments are given, returns ``0``.

   The integer type is described in :ref:`typesnumeric`.

.. function:: iter(o[, sentinel])

   Return an :term:`iterator` object.  The first argument is interpreted very differently
   depending on the presence of the second argument. Without a second argument, *o*
   must be a collection object which supports the iteration protocol (the
   :meth:`__iter__` method), or it must support the sequence protocol (the
   :meth:`__getitem__` method with integer arguments starting at ``0``).  If it
   does not support either of those protocols, :exc:`TypeError` is raised. If the
   second argument, *sentinel*, is given, then *o* must be a callable object.  The
   iterator created in this case will call *o* with no arguments for each call to
   its :meth:`next` method; if the value returned is equal to *sentinel*,
   :exc:`StopIteration` will be raised, otherwise the value will be returned.

   .. versionadded:: 2.2

.. function:: list([iterable])

   Return a list whose items are the same and in the same order as *iterable*'s
   items.  *iterable* may be either a sequence, a container that supports
   iteration, or an iterator object.  If *iterable* is already a list, a copy is
   made and returned, similar to ``iterable[:]``.  For instance, ``list('abc')``
   returns ``['a', 'b', 'c']`` and ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``.  If
   no argument is given, returns a new empty list, ``[]``.

   :class:`list` is a mutable sequence type, as documented in
   :ref:`typesseq`. For other containers see the built in :class:`dict`,
   :class:`set`, and :class:`tuple` classes, and the :mod:`collections` module.

.. function:: object()

   Return a new featureless object.  :class:`object` is a base for all new style
   classes.  It has the methods that are common to all instances of new style
   classes.

   .. versionadded:: 2.2

   .. versionchanged:: 2.3
      This function does not accept any arguments. Formerly, it accepted arguments but
      ignored them.

.. function:: open(filename[, mode[, bufsize]])

   Open a file, returning an object of the :class:`file` type described in
   section :ref:`bltin-file-objects`.  If the file cannot be opened,
   :exc:`IOError` is raised.  When opening a file, it's preferable to use
   :func:`open` instead of invoking the :class:`file` constructor directly.

   The first two arguments are the same as for ``stdio``'s :cfunc:`fopen`:
   *filename* is the file name to be opened, and *mode* is a string indicating how
   the file is to be opened.

   The most commonly-used values of *mode* are ``'r'`` for reading, ``'w'`` for
   writing (truncating the file if it already exists), and ``'a'`` for appending
   (which on *some* Unix systems means that *all* writes append to the end of the
   file regardless of the current seek position).  If *mode* is omitted, it
   defaults to ``'r'``.  The default is to use text mode, which may convert
   ``'\n'`` characters to a platform-specific representation on writing and back
   on reading.  Thus, when opening a binary file, you should append ``'b'`` to
   the *mode* value to open the file in binary mode, which will improve
   portability.  (Appending ``'b'`` is useful even on systems that don't treat
   binary and text files differently, where it serves as documentation.)  See below
   for more possible values of *mode*.

   .. index::
      single: line-buffered I/O
      single: unbuffered I/O
      single: buffer size, I/O
      single: I/O control; buffering

   The optional *bufsize* argument specifies the file's desired buffer size: 0
   means unbuffered, 1 means line buffered, any other positive value means use a
   buffer of (approximately) that size.  A negative *bufsize* means to use the
   system default, which is usually line buffered for tty devices and fully
   buffered for other files.  If omitted, the system default is used. [#]_

   Modes ``'r+'``, ``'w+'`` and ``'a+'`` open the file for updating (note that
   ``'w+'`` truncates the file).  Append ``'b'`` to the mode to open the file in
   binary mode, on systems that differentiate between binary and text files; on
   systems that don't have this distinction, adding the ``'b'`` has no effect.

   In addition to the standard :cfunc:`fopen` values *mode* may be ``'U'`` or
   ``'rU'``.  Python is usually built with universal newline support; supplying
   ``'U'`` opens the file as a text file, but lines may be terminated by any of the
   following: the Unix end-of-line convention ``'\n'``,  the Macintosh convention
   ``'\r'``, or the Windows convention ``'\r\n'``. All of these external
   representations are seen as ``'\n'`` by the Python program. If Python is built
   without universal newline support a *mode* with ``'U'`` is the same as normal
   text mode.  Note that file objects so opened also have an attribute called
   :attr:`newlines` which has a value of ``None`` (if no newlines have yet been
   seen), ``'\n'``, ``'\r'``, ``'\r\n'``, or a tuple containing all the newline
   types seen.

   Python enforces that the mode, after stripping ``'U'``, begins with ``'r'``,
   ``'w'`` or ``'a'``.

   Python provides many file handling modules including
   :mod:`fileinput`, :mod:`os`, :mod:`os.path`, :mod:`tempfile`, and
   :mod:`shutil`.

.. function:: ord(c)

   Given a string of length one, return an integer representing the Unicode code
   point of the character when the argument is a unicode object, or the value of
   the byte when the argument is an 8-bit string. For example, ``ord('a')`` returns
   the integer ``97``, ``ord(u'\u2020')`` returns ``8224``.  This is the inverse of
   :func:`chr` for 8-bit strings and of :func:`unichr` for unicode objects.  If a
   unicode argument is given and Python was built with UCS2 Unicode, then the
   character's code point must be in the range [0..65535] inclusive; otherwise the
   string length is two, and a :exc:`TypeError` will be raised.


.. function:: range([start,] stop[, step])

   This is a versatile function to create lists containing arithmetic progressions.
   It is most often used in :keyword:`for` loops.  

   However, we recommend the use of xrange instead.

   The arguments must be plain
   integers.  If the *step* argument is omitted, it defaults to ``1``.  If the
   *start* argument is omitted, it defaults to ``0``.  The full form returns a list
   of plain integers ``[start, start + step, start + 2 * step, ...]``.  If *step*
   is positive, the last element is the largest ``start + i * step`` less than
   *stop*; if *step* is negative, the last element is the smallest ``start + i *
   step`` greater than *stop*.  *step* must not be zero (or else :exc:`ValueError`
   is raised).  Example:

      >>> range(10)
      [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
      >>> range(1, 11)
      [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
      >>> range(0, 30, 5)
      [0, 5, 10, 15, 20, 25]
      >>> range(0, 10, 3)
      [0, 3, 6, 9]
      >>> range(0, -10, -1)
      [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
      >>> range(0)
      []
      >>> range(1, 0)
      []

.. function:: set([iterable])
   :noindex:

   Return a new set, optionally with elements are taken from *iterable*.
   The set type is described in :ref:`types-set`.

   For other containers see the built in :class:`dict`, :class:`list`, and
   :class:`tuple` classes, and the :mod:`collections` module.

   .. versionadded:: 2.4

.. function:: str([object])

   Return a string containing a nicely printable representation of an object.  For
   strings, this returns the string itself.  The difference with ``repr(object)``
   is that ``str(object)`` does not always attempt to return a string that is
   acceptable to :func:`eval`; its goal is to return a printable string.  If no
   argument is given, returns the empty string, ``''``.

   For more information on strings see :ref:`typesseq` which describes sequence
   functionality (strings are sequences), and also the string-specific methods
   described in the :ref:`string-methods` section. To output formatted strings
   use template strings or the ``%`` operator described in the
   :ref:`string-formatting` section. In addition see the :ref:`stringservices`
   section. See also :func:`unicode`.

.. function:: tuple([iterable])

   Return a tuple whose items are the same and in the same order as *iterable*'s
   items.  *iterable* may be a sequence, a container that supports iteration, or an
   iterator object. If *iterable* is already a tuple, it is returned unchanged.
   For instance, ``tuple('abc')`` returns ``('a', 'b', 'c')`` and ``tuple([1, 2,
   3])`` returns ``(1, 2, 3)``.  If no argument is given, returns a new empty
   tuple, ``()``.

   :class:`tuple` is an immutable sequence type, as documented in
   :ref:`typesseq`. For other containers see the built in :class:`dict`,
   :class:`list`, and :class:`set` classes, and the :mod:`collections` module.

.. function:: type(name, bases, dict)
   :noindex:

   Return a new type object.  This is essentially a dynamic form of the
   :keyword:`class` statement. The *name* string is the class name and becomes the
   :attr:`__name__` attribute; the *bases* tuple itemizes the base classes and
   becomes the :attr:`__bases__` attribute; and the *dict* dictionary is the
   namespace containing definitions for class body and becomes the :attr:`__dict__`
   attribute.  For example, the following two statements create identical
   :class:`type` objects:

      >>> class X(object):
      ...     a = 1
      ...
      >>> X = type('X', (object,), dict(a=1))

   .. versionadded:: 2.2

.. function:: unichr(i)

   Return the Unicode string of one character whose Unicode code is the integer
   *i*.  For example, ``unichr(97)`` returns the string ``u'a'``.  This is the
   inverse of :func:`ord` for Unicode strings.  The valid range for the argument
   depends how Python was configured -- it may be either UCS2 [0..0xFFFF] or UCS4
   [0..0x10FFFF]. :exc:`ValueError` is raised otherwise. For ASCII and 8-bit
   strings see :func:`chr`.

   .. versionadded:: 2.0


.. function:: unicode([object[, encoding [, errors]]])

   Return the Unicode string version of *object* using one of the following modes:

   If *encoding* and/or *errors* are given, ``unicode()`` will decode the object
   which can either be an 8-bit string or a character buffer using the codec for
   *encoding*. The *encoding* parameter is a string giving the name of an encoding;
   if the encoding is not known, :exc:`LookupError` is raised. Error handling is
   done according to *errors*; this specifies the treatment of characters which are
   invalid in the input encoding.  If *errors* is ``'strict'`` (the default), a
   :exc:`ValueError` is raised on errors, while a value of ``'ignore'`` causes
   errors to be silently ignored, and a value of ``'replace'`` causes the official
   Unicode replacement character, ``U+FFFD``, to be used to replace input
   characters which cannot be decoded.  See also the :mod:`codecs` module.

   If no optional parameters are given, ``unicode()`` will mimic the behaviour of
   ``str()`` except that it returns Unicode strings instead of 8-bit strings. More
   precisely, if *object* is a Unicode string or subclass it will return that
   Unicode string without any additional decoding applied.

   For objects which provide a :meth:`__unicode__` method, it will call this method
   without arguments to create a Unicode string. For all other objects, the 8-bit
   string version or representation is requested and then converted to a Unicode
   string using the codec for the default encoding in ``'strict'`` mode.

   For more information on Unicode strings see :ref:`typesseq` which describes
   sequence functionality (Unicode strings are sequences), and also the
   string-specific methods described in the :ref:`string-methods` section. To
   output formatted strings use template strings or the ``%`` operator described
   in the :ref:`string-formatting` section. In addition see the
   :ref:`stringservices` section. See also :func:`str`.


Use as decorators:
classmethod, staticmethod, property

``slice`` is rarely used directly.

super
type - 3 arg form
compile


Math Builtin Functions
----------------------

Most math functions are defined in ``math`` (or ``cmath`` for complex math). These are functions that are builtin:

abs, cmp, divmod, pow, round

You may need to use named functions 


Functions on Iterables
----------------------

The next group of builtin functions operate on iterables, which in
Jython also includes all Java objects that implement the
``java.util.Iterator`` interface.

In particular,

.. function:: enumerate(iterable)

.. function:: zip([,iterable, ...])

The ``zip`` function creates a list of tuples by stepping through each
*iterable*. One very common idiom is to use ``zip`` to create a
``dict`` where one iterable has the keys, and the other the
values. This is often seen in working with CSV files (from a header
row) or database cursors (from the ``description``
attribute). However, you might want to consider using
``collections.namedtuple`` instead::

 
.. function:: sorted(iterable[, cmp[, key[, reverse]]])

The ``sorted`` function returns a sorted list. Use the optional *key*
argument to specify a key function to control how it's sorted. So for
example, this will sort the list by the length of the elements in it::
  
  >>> sorted(['Massachusetts', 'Colorado', 'New York', 'California', 'Utah'], key=len)
  ['Utah', 'Colorado', 'New York', 'California', 'Massachusetts']

And this one will sort a list of Unicode strings without regard to it
whether the characters are upper or lowercase::

  >>> sorted(['apple', 'Cherry', 'banana'])
  ['Cherry', 'apple', 'banana']

  >>> sorted(['apple', 'Cherry', 'banana'], key=str.upper)
  ['apple', 'banana', 'Cherry']

Although using a *key* function requires building a decorated version
of the list to be sorted, in practice this uses substantially less
overhead than calling a *cmp* function on every comparison. We
recommend you take advantage of a keyed sort.

.. function:: all(iterable), any(iterable)

``all`` and ``any`` will also short cut, if possible.


and sum(iterable[, start=0]) are functions that you
will find frequent use for. 

.. function:: max(iterable[, key]) or max([, arg, ...][, key]); min(iterable[, key]) or min([, arg, ...][, key])

The ``max`` and ``min`` functions
take a *key* function as an optional argument.


Although ``filter``, ``map``, and ``reduce`` are still useful, their
use is largely superseded by using other functions, in conjunction
with generator expressions. The ``range`` function is still useful for
creating a list of a given sequence, but for portability eventualy to
Python 3.x, using ``list(xrange())`` instead is better.

Some advice:

 * Generator expressions (or list comprehensions) are easier to use
   than ``filter``.

 * Most interesting but simple uses of ``reduce`` can be implemented
   through ``sum``. And anything more complex should likely be written
   as a generator.


.. function:: all(iterable)

Returns True if all of the elements in the iterable are true,
otherwise False and stop the iteration. (If the iterable is empty,
this function returns True).

.. function:: any(iterable)

Returns True if any of the elements in the iterable are true, stopping the iteration.
Otherwise returns False and stop the iteration. (If the iterable is empty,
this function returns True).

.. function:: enumerate(iterable)

.. function:: filter(function, iterable)


.. function:: sum(iterable[, start=0])


Namespace Functions
-------------------
namespace - __import__, delattr, dir, getattr, locals, globals, hasattr, reload, setattr, vars

getattr

.. sidebar::
  
  Java dynamic integration. the supporting special method for getattr
  is __getattr__. When Jython code is compiled, it actually uses
  __getattr__ for implementing attribute lookup. So x.y.z is actually
  compiled to the equivalent chain of
  x.__getattr__('y').__getattr__('z'). Alternatively for more
  efficient Java integration, __findattr__ is supported. It returns
  null instead of throwing an AttributeError if the attribute is not
  part of a given object. But use __getattr__ if you are going to be
  chaining method calls together so as to maintain Python exception
  handling semantics.

  If the given Jython class implements a Java interface (or extends a
  Java class, but this is the less preferrable case in Jython as it is
  in Java in general), then Java code that uses such instances can
  statically bind method lookup.

  [The Clamp project supports an alternate way of exposing Java
  interfaces, such that the interfaces are created from Jython
  code. I'm not so certain about this approach as a best practice
  however. Java interfaces in Java are quite precise with respect to
  interoperability. Other parts are useful, such as AOT compilation of
  Java proxies for Jython classes.]


compile, eval, exec
Creating code objects.

evaluation - eval, execfile, 
predicates - callable, isinstance, issubclass 
hex, oct, id, hash, ord, repr
len
input, rawinput

Just refer to the documentation on these:
deprecated functions - apply, buffer, coerce, intern ...

Operators



.. function:: abs(x)

   Return the absolute value of a number.  The argument may be a plain or long
   integer or a floating point number.  If the argument is a complex number, its
   magnitude is returned.


.. function:: all(iterable)

   Return True if all elements of the *iterable* are true. Equivalent to::

      def all(iterable):
          for element in iterable:
              if not element:
                  return False
          return True

   .. versionadded:: 2.5


.. function:: any(iterable)

   Return True if any element of the *iterable* is true. Equivalent to::

      def any(iterable):
          for element in iterable:
              if element:
                  return True
          return False

   .. versionadded:: 2.5


.. function:: basestring()

   This abstract type is the superclass for :class:`str` and :class:`unicode`. It
   cannot be called or instantiated, but it can be used to test whether an object
   is an instance of :class:`str` or :class:`unicode`. ``isinstance(obj,
   basestring)`` is equivalent to ``isinstance(obj, (str, unicode))``.

   .. versionadded:: 2.3


.. function:: bin(x)

   Convert an integer number to a binary string. The result is a valid Python
   expression.  If *x* is not a Python :class:`int` object, it has to define an
   :meth:`__index__` method that returns an integer.

   .. versionadded:: 2.6



.. function:: callable(object)

   Return :const:`True` if the *object* argument appears callable,
   :const:`False` if not.  If this
   returns true, it is still possible that a call fails, but if it is false,
   calling *object* will never succeed.  Note that classes are callable (calling a
   class returns a new instance); class instances are callable if they have a
   :meth:`__call__` method.



.. function:: classmethod(function)

   Return a class method for *function*.

   A class method receives the class as implicit first argument, just like an
   instance method receives the instance. To declare a class method, use this
   idiom::

      class C:
          @classmethod
          def f(cls, arg1, arg2, ...): ...

   The ``@classmethod`` form is a function :term:`decorator` -- see the description
   of function definitions in :ref:`function` for details.

   It can be called either on the class (such as ``C.f()``) or on an instance (such
   as ``C().f()``).  The instance is ignored except for its class. If a class
   method is called for a derived class, the derived class object is passed as the
   implied first argument.

   Class methods are different than C++ or Java static methods. If you want those,
   see :func:`staticmethod` in this section.

   For more information on class methods, consult the documentation on the standard
   type hierarchy in :ref:`types`.

   .. versionadded:: 2.2

   .. versionchanged:: 2.4
      Function decorator syntax added.


.. function:: cmp(x, y)

   Compare the two objects *x* and *y* and return an integer according to the
   outcome.  The return value is negative if ``x < y``, zero if ``x == y`` and
   strictly positive if ``x > y``.


.. function:: compile(source, filename, mode[, flags[, dont_inherit]])

   Compile the *source* into a code or AST object.  Code objects can be executed
   by an :keyword:`exec` statement or evaluated by a call to :func:`eval`.
   *source* can either be a string or an AST object.  Refer to the :mod:`ast`
   module documentation for information on how to work with AST objects.

   The *filename* argument should give the file from which the code was read;
   pass some recognizable value if it wasn't read from a file (``'<string>'`` is
   commonly used).

   The *mode* argument specifies what kind of code must be compiled; it can be
   ``'exec'`` if *source* consists of a sequence of statements, ``'eval'`` if it
   consists of a single expression, or ``'single'`` if it consists of a single
   interactive statement (in the latter case, expression statements that
   evaluate to something else than ``None`` will be printed).

   The optional arguments *flags* and *dont_inherit* control which future
   statements (see :pep:`236`) affect the compilation of *source*.  If neither
   is present (or both are zero) the code is compiled with those future
   statements that are in effect in the code that is calling compile.  If the
   *flags* argument is given and *dont_inherit* is not (or is zero) then the
   future statements specified by the *flags* argument are used in addition to
   those that would be used anyway. If *dont_inherit* is a non-zero integer then
   the *flags* argument is it -- the future statements in effect around the call
   to compile are ignored.

   Future statements are specified by bits which can be bitwise ORed together to
   specify multiple statements.  The bitfield required to specify a given feature
   can be found as the :attr:`compiler_flag` attribute on the :class:`_Feature`
   instance in the :mod:`__future__` module.

   This function raises :exc:`SyntaxError` if the compiled source is invalid,
   and :exc:`TypeError` if the source contains null bytes.

   .. note::

      When compiling a string with multi-line statements, line endings must be
      represented by a single newline character (``'\n'``), and the input must
      be terminated by at least one newline character.  If line endings are
      represented by ``'\r\n'``, use :meth:`str.replace` to change them into
      ``'\n'``.

   .. versionchanged:: 2.3
      The *flags* and *dont_inherit* arguments were added.

   .. versionchanged:: 2.6
      Support for compiling AST objects.




.. function:: delattr(object, name)

   This is a relative of :func:`setattr`.  The arguments are an object and a
   string.  The string must be the name of one of the object's attributes.  The
   function deletes the named attribute, provided the object allows it.  For
   example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``.



.. function:: dir([object])

   Without arguments, return the list of names in the current local scope.  With an
   argument, attempt to return a list of valid attributes for that object.

   If the object has a method named :meth:`__dir__`, this method will be called and
   must return the list of attributes. This allows objects that implement a custom
   :func:`__getattr__` or :func:`__getattribute__` function to customize the way
   :func:`dir` reports their attributes.

   If the object does not provide :meth:`__dir__`, the function tries its best to
   gather information from the object's :attr:`__dict__` attribute, if defined, and
   from its type object.  The resulting list is not necessarily complete, and may
   be inaccurate when the object has a custom :func:`__getattr__`.

   The default :func:`dir` mechanism behaves differently with different types of
   objects, as it attempts to produce the most relevant, rather than complete,
   information:

   * If the object is a module object, the list contains the names of the module's
     attributes.

   * If the object is a type or class object, the list contains the names of its
     attributes, and recursively of the attributes of its bases.

   * Otherwise, the list contains the object's attributes' names, the names of its
     class's attributes, and recursively of the attributes of its class's base
     classes.

   The resulting list is sorted alphabetically.  For example:

      >>> import struct
      >>> dir()   # doctest: +SKIP
      ['__builtins__', '__doc__', '__name__', 'struct']
      >>> dir(struct)   # doctest: +NORMALIZE_WHITESPACE
      ['Struct', '__builtins__', '__doc__', '__file__', '__name__',
       '__package__', '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
       'unpack', 'unpack_from']
      >>> class Foo(object):
      ...     def __dir__(self):
      ...         return ["kan", "ga", "roo"]
      ...
      >>> f = Foo()
      >>> dir(f)
      ['ga', 'kan', 'roo']

   .. note::

      Because :func:`dir` is supplied primarily as a convenience for use at an
      interactive prompt, it tries to supply an interesting set of names more than it
      tries to supply a rigorously or consistently defined set of names, and its
      detailed behavior may change across releases.  For example, metaclass attributes
      are not in the result list when the argument is a class.


.. function:: divmod(a, b)

   Take two (non complex) numbers as arguments and return a pair of numbers
   consisting of their quotient and remainder when using long division.  With mixed
   operand types, the rules for binary arithmetic operators apply.  For plain and
   long integers, the result is the same as ``(a // b, a % b)``. For floating point
   numbers the result is ``(q, a % b)``, where *q* is usually ``math.floor(a / b)``
   but may be 1 less than that.  In any case ``q * b + a % b`` is very close to
   *a*, if ``a % b`` is non-zero it has the same sign as *b*, and ``0 <= abs(a % b)
   < abs(b)``.

   .. versionchanged:: 2.3
      Using :func:`divmod` with complex numbers is deprecated.


.. function:: enumerate(sequence[, start=0])

   Return an enumerate object. *sequence* must be a sequence, an
   :term:`iterator`, or some other object which supports iteration.  The
   :meth:`next` method of the iterator returned by :func:`enumerate` returns a
   tuple containing a count (from *start* which defaults to 0) and the
   corresponding value obtained from iterating over *iterable*.
   :func:`enumerate` is useful for obtaining an indexed series: ``(0, seq[0])``,
   ``(1, seq[1])``, ``(2, seq[2])``, .... For example:

      >>> for i, season in enumerate(['Spring', 'Summer', 'Fall', 'Winter']):
      ...     print i, season
      0 Spring
      1 Summer
      2 Fall
      3 Winter

   .. versionadded:: 2.3
   .. versionadded:: 2.6
      The *start* parameter.


.. function:: eval(expression[, globals[, locals]])

   The arguments are a string and optional globals and locals.  If provided,
   *globals* must be a dictionary.  If provided, *locals* can be any mapping
   object.

   .. versionchanged:: 2.4
      formerly *locals* was required to be a dictionary.

   The *expression* argument is parsed and evaluated as a Python expression
   (technically speaking, a condition list) using the *globals* and *locals*
   dictionaries as global and local namespace.  If the *globals* dictionary is
   present and lacks '__builtins__', the current globals are copied into *globals*
   before *expression* is parsed.  This means that *expression* normally has full
   access to the standard :mod:`__builtin__` module and restricted environments are
   propagated.  If the *locals* dictionary is omitted it defaults to the *globals*
   dictionary.  If both dictionaries are omitted, the expression is executed in the
   environment where :func:`eval` is called.  The return value is the result of
   the evaluated expression. Syntax errors are reported as exceptions.  Example:

      >>> x = 1
      >>> print eval('x+1')
      2

   This function can also be used to execute arbitrary code objects (such as
   those created by :func:`compile`).  In this case pass a code object instead
   of a string.  If the code object has been compiled with ``'exec'`` as the
   *kind* argument, :func:`eval`\'s return value will be ``None``.

   Hints: dynamic execution of statements is supported by the :keyword:`exec`
   statement.  Execution of statements from a file is supported by the
   :func:`execfile` function.  The :func:`globals` and :func:`locals` functions
   returns the current global and local dictionary, respectively, which may be
   useful to pass around for use by :func:`eval` or :func:`execfile`.


.. function:: execfile(filename[, globals[, locals]])

   This function is similar to the :keyword:`exec` statement, but parses a file
   instead of a string.  It is different from the :keyword:`import` statement in
   that it does not use the module administration --- it reads the file
   unconditionally and does not create a new module. [#]_

   The arguments are a file name and two optional dictionaries.  The file is parsed
   and evaluated as a sequence of Python statements (similarly to a module) using
   the *globals* and *locals* dictionaries as global and local namespace. If
   provided, *locals* can be any mapping object.

   .. versionchanged:: 2.4
      formerly *locals* was required to be a dictionary.

   If the *locals* dictionary is omitted it defaults to the *globals* dictionary.
   If both dictionaries are omitted, the expression is executed in the environment
   where :func:`execfile` is called.  The return value is ``None``.

   .. warning::

      The default *locals* act as described for function :func:`locals` below:
      modifications to the default *locals* dictionary should not be attempted.  Pass
      an explicit *locals* dictionary if you need to see effects of the code on
      *locals* after function :func:`execfile` returns.  :func:`execfile` cannot be
      used reliably to modify a function's locals.


.. function:: file(filename[, mode[, bufsize]])

   Constructor function for the :class:`file` type, described further in section
   :ref:`bltin-file-objects`.  The constructor's arguments are the same as those
   of the :func:`open` built-in function described below.

   When opening a file, it's preferable to use :func:`open` instead of  invoking
   this constructor directly.  :class:`file` is more suited to type testing (for
   example, writing ``isinstance(f, file)``).

   .. versionadded:: 2.2


.. function:: filter(function, iterable)

   Construct a list from those elements of *iterable* for which *function* returns
   true.  *iterable* may be either a sequence, a container which supports
   iteration, or an iterator.  If *iterable* is a string or a tuple, the result
   also has that type; otherwise it is always a list.  If *function* is ``None``,
   the identity function is assumed, that is, all elements of *iterable* that are
   false are removed.

   Note that ``filter(function, iterable)`` is equivalent to ``[item for item in
   iterable if function(item)]`` if function is not ``None`` and ``[item for item
   in iterable if item]`` if function is ``None``.

   See :func:`itertools.filterfalse` for the complementary function that returns
   elements of *iterable* for which *function* returns false.


.. function:: getattr(object, name[, default])

   Return the value of the named attributed of *object*.  *name* must be a string.
   If the string is the name of one of the object's attributes, the result is the
   value of that attribute.  For example, ``getattr(x, 'foobar')`` is equivalent to
   ``x.foobar``.  If the named attribute does not exist, *default* is returned if
   provided, otherwise :exc:`AttributeError` is raised.


.. function:: globals()

   Return a dictionary representing the current global symbol table. This is always
   the dictionary of the current module (inside a function or method, this is the
   module where it is defined, not the module from which it is called).


.. function:: hasattr(object, name)

   The arguments are an object and a string.  The result is ``True`` if the string
   is the name of one of the object's attributes, ``False`` if not. (This is
   implemented by calling ``getattr(object, name)`` and seeing whether it raises an
   exception or not.)


.. function:: hash(object)

   Return the hash value of the object (if it has one).  Hash values are integers.
   They are used to quickly compare dictionary keys during a dictionary lookup.
   Numeric values that compare equal have the same hash value (even if they are of
   different types, as is the case for 1 and 1.0).


.. function:: help([object])

   Invoke the built-in help system.  (This function is intended for interactive
   use.)  If no argument is given, the interactive help system starts on the
   interpreter console.  If the argument is a string, then the string is looked up
   as the name of a module, function, class, method, keyword, or documentation
   topic, and a help page is printed on the console.  If the argument is any other
   kind of object, a help page on the object is generated.

   This function is added to the built-in namespace by the :mod:`site` module.

   .. versionadded:: 2.2


.. function:: hex(x)

   Convert an integer number (of any size) to a hexadecimal string. The result is a
   valid Python expression.

   .. versionchanged:: 2.4
      Formerly only returned an unsigned literal.


.. function:: id(object)

   Return the "identity" of an object.  This is an integer (or long integer) which
   is guaranteed to be unique and constant for this object during its lifetime.
   Two objects with non-overlapping lifetimes may have the same :func:`id` value.
   (Implementation note: this is the address of the object.)


.. function:: input([prompt])

   Equivalent to ``eval(raw_input(prompt))``.

   .. warning::

      This function is not safe from user errors!  It expects a valid Python
      expression as input; if the input is not syntactically valid, a
      :exc:`SyntaxError` will be raised. Other exceptions may be raised if there is an
      error during evaluation.  (On the other hand, sometimes this is exactly what you
      need when writing a quick script for expert use.)

   If the :mod:`readline` module was loaded, then :func:`input` will use it to
   provide elaborate line editing and history features.

   Consider using the :func:`raw_input` function for general input from users.



.. function:: isinstance(object, classinfo)

   Return true if the *object* argument is an instance of the *classinfo* argument,
   or of a (direct or indirect) subclass thereof.  Also return true if *classinfo*
   is a type object (new-style class) and *object* is an object of that type or of
   a (direct or indirect) subclass thereof.  If *object* is not a class instance or
   an object of the given type, the function always returns false.  If *classinfo*
   is neither a class object nor a type object, it may be a tuple of class or type
   objects, or may recursively contain other such tuples (other sequence types are
   not accepted).  If *classinfo* is not a class, type, or tuple of classes, types,
   and such tuples, a :exc:`TypeError` exception is raised.

   .. versionchanged:: 2.2
      Support for a tuple of type information was added.


.. function:: issubclass(class, classinfo)

   Return true if *class* is a subclass (direct or indirect) of *classinfo*.  A
   class is considered a subclass of itself. *classinfo* may be a tuple of class
   objects, in which case every entry in *classinfo* will be checked. In any other
   case, a :exc:`TypeError` exception is raised.

   .. versionchanged:: 2.3
      Support for a tuple of type information was added.




.. function:: len(s)

   Return the length (the number of items) of an object.  The argument may be a
   sequence (string, tuple or list) or a mapping (dictionary).



.. function:: locals()

   Update and return a dictionary representing the current local symbol table.

   .. warning::

      The contents of this dictionary should not be modified; changes may not affect
      the values of local variables used by the interpreter.

   Free variables are returned by :func:`locals` when it is called in a function block.
   Modifications of free variables may not affect the values used by the
   interpreter.  Free variables are not returned in class blocks.


.. function:: long([x[, radix]])

   Convert a string or number to a long integer.  If the argument is a string, it
   must contain a possibly signed number of arbitrary size, possibly embedded in
   whitespace. The *radix* argument is interpreted in the same way as for
   :func:`int`, and may only be given when *x* is a string. Otherwise, the argument
   may be a plain or long integer or a floating point number, and a long integer
   with the same value is returned.    Conversion of floating point numbers to
   integers truncates (towards zero).  If no arguments are given, returns ``0L``.

   The long type is described in :ref:`typesnumeric`.

.. function:: map(function, iterable, ...)

   Apply *function* to every item of *iterable* and return a list of the results.
   If additional *iterable* arguments are passed, *function* must take that many
   arguments and is applied to the items from all iterables in parallel.  If one
   iterable is shorter than another it is assumed to be extended with ``None``
   items.  If *function* is ``None``, the identity function is assumed; if there
   are multiple arguments, :func:`map` returns a list consisting of tuples
   containing the corresponding items from all iterables (a kind of transpose
   operation).  The *iterable* arguments may be a sequence  or any iterable object;
   the result is always a list.


.. function:: max(iterable[, args...][key])

   With a single argument *iterable*, return the largest item of a non-empty
   iterable (such as a string, tuple or list).  With more than one argument, return
   the largest of the arguments.

   The optional *key* argument specifies a one-argument ordering function like that
   used for :meth:`list.sort`.  The *key* argument, if supplied, must be in keyword
   form (for example, ``max(a,b,c,key=func)``).

   .. versionchanged:: 2.5
      Added support for the optional *key* argument.


.. function:: min(iterable[, args...][key])

   With a single argument *iterable*, return the smallest item of a non-empty
   iterable (such as a string, tuple or list).  With more than one argument, return
   the smallest of the arguments.

   The optional *key* argument specifies a one-argument ordering function like that
   used for :meth:`list.sort`.  The *key* argument, if supplied, must be in keyword
   form (for example, ``min(a,b,c,key=func)``).

   .. versionchanged:: 2.5
      Added support for the optional *key* argument.


.. function:: next(iterator[, default])

   Retrieve the next item from the *iterator* by calling its :meth:`next`
   method.  If *default* is given, it is returned if the iterator is exhausted,
   otherwise :exc:`StopIteration` is raised.

   .. versionadded:: 2.6




.. function:: oct(x)

   Convert an integer number (of any size) to an octal string.  The result is a
   valid Python expression.

   .. versionchanged:: 2.4
      Formerly only returned an unsigned literal.




.. function:: pow(x, y[, z])

   Return *x* to the power *y*; if *z* is present, return *x* to the power *y*,
   modulo *z* (computed more efficiently than ``pow(x, y) % z``). The two-argument
   form ``pow(x, y)`` is equivalent to using the power operator: ``x**y``.

   The arguments must have numeric types.  With mixed operand types, the coercion
   rules for binary arithmetic operators apply.  For int and long int operands, the
   result has the same type as the operands (after coercion) unless the second
   argument is negative; in that case, all arguments are converted to float and a
   float result is delivered.  For example, ``10**2`` returns ``100``, but
   ``10**-2`` returns ``0.01``.  (This last feature was added in Python 2.2.  In
   Python 2.1 and before, if both arguments were of integer types and the second
   argument was negative, an exception was raised.) If the second argument is
   negative, the third argument must be omitted. If *z* is present, *x* and *y*
   must be of integer types, and *y* must be non-negative.  (This restriction was
   added in Python 2.2.  In Python 2.1 and before, floating 3-argument ``pow()``
   returned platform-dependent results depending on floating-point rounding
   accidents.)


.. function:: print([object, ...][, sep=' '][, end='\n'][, file=sys.stdout])

   Print *object*\(s) to the stream *file*, separated by *sep* and followed by
   *end*.  *sep*, *end* and *file*, if present, must be given as keyword
   arguments.

   All non-keyword arguments are converted to strings like :func:`str` does and
   written to the stream, separated by *sep* and followed by *end*.  Both *sep*
   and *end* must be strings; they can also be ``None``, which means to use the
   default values.  If no *object* is given, :func:`print` will just write
   *end*.

   The *file* argument must be an object with a ``write(string)`` method; if it
   is not present or ``None``, :data:`sys.stdout` will be used.

   .. note::

      This function is not normally available as a builtin since the name
      ``print`` is recognized as the :keyword:`print` statement.  To disable the
      statement and use the :func:`print` function, use this future statement at
      the top of your module::

         from __future__ import print_function

   .. versionadded:: 2.6


.. function:: property([fget[, fset[, fdel[, doc]]]])

   Return a property attribute for :term:`new-style class`\es (classes that
   derive from :class:`object`).

   *fget* is a function for getting an attribute value, likewise *fset* is a
   function for setting, and *fdel* a function for del'ing, an attribute.  Typical
   use is to define a managed attribute x::

      class C(object):
          def __init__(self):
              self._x = None

          def getx(self):
              return self._x
          def setx(self, value):
              self._x = value
          def delx(self):
              del self._x
          x = property(getx, setx, delx, "I'm the 'x' property.")

   If given, *doc* will be the docstring of the property attribute. Otherwise, the
   property will copy *fget*'s docstring (if it exists).  This makes it possible to
   create read-only properties easily using :func:`property` as a :term:`decorator`::

      class Parrot(object):
          def __init__(self):
              self._voltage = 100000

          @property
          def voltage(self):
              """Get the current voltage."""
              return self._voltage

   turns the :meth:`voltage` method into a "getter" for a read-only attribute
   with the same name.

   A property object has :attr:`getter`, :attr:`setter`, and :attr:`deleter`
   methods usable as decorators that create a copy of the property with the
   corresponding accessor function set to the decorated function.  This is
   best explained with an example::

      class C(object):
          def __init__(self):
              self._x = None

          @property
          def x(self):
              """I'm the 'x' property."""
              return self._x

          @x.setter
          def x(self, value):
              self._x = value

          @x.deleter
          def x(self):
              del self._x

   This code is exactly equivalent to the first example.  Be sure to give the
   additional functions the same name as the original property (``x`` in this
   case.)

   The returned property also has the attributes ``fget``, ``fset``, and
   ``fdel`` corresponding to the constructor arguments.

   .. versionadded:: 2.2

   .. versionchanged:: 2.5
      Use *fget*'s docstring if no *doc* given.

   .. versionchanged:: 2.6
      The ``getter``, ``setter``, and ``deleter`` attributes were added.



.. function:: raw_input([prompt])

   If the *prompt* argument is present, it is written to standard output without a
   trailing newline.  The function then reads a line from input, converts it to a
   string (stripping a trailing newline), and returns that. When EOF is read,
   :exc:`EOFError` is raised. Example::

      >>> s = raw_input('--> ')
      --> Monty Python's Flying Circus
      >>> s
      "Monty Python's Flying Circus"

   If the :mod:`readline` module was loaded, then :func:`raw_input` will use it to
   provide elaborate line editing and history features.


.. function:: reduce(function, iterable[, initializer])

   Apply *function* of two arguments cumulatively to the items of *iterable*, from
   left to right, so as to reduce the iterable to a single value.  For example,
   ``reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])`` calculates ``((((1+2)+3)+4)+5)``.
   The left argument, *x*, is the accumulated value and the right argument, *y*, is
   the update value from the *iterable*.  If the optional *initializer* is present,
   it is placed before the items of the iterable in the calculation, and serves as
   a default when the iterable is empty.  If *initializer* is not given and
   *iterable* contains only one item, the first item is returned.


.. function:: reload(module)

   Reload a previously imported *module*.  The argument must be a module object, so
   it must have been successfully imported before.  This is useful if you have
   edited the module source file using an external editor and want to try out the
   new version without leaving the Python interpreter.  The return value is the
   module object (the same as the *module* argument).

   When ``reload(module)`` is executed:

   * Python modules' code is recompiled and the module-level code reexecuted,
     defining a new set of objects which are bound to names in the module's
     dictionary.  The ``init`` function of extension modules is not called a second
     time.

   * As with all other objects in Python the old objects are only reclaimed after
     their reference counts drop to zero.

   * The names in the module namespace are updated to point to any new or changed
     objects.

   * Other references to the old objects (such as names external to the module) are
     not rebound to refer to the new objects and must be updated in each namespace
     where they occur if that is desired.

   There are a number of other caveats:

   If a module is syntactically correct but its initialization fails, the first
   :keyword:`import` statement for it does not bind its name locally, but does
   store a (partially initialized) module object in ``sys.modules``.  To reload the
   module you must first :keyword:`import` it again (this will bind the name to the
   partially initialized module object) before you can :func:`reload` it.

   When a module is reloaded, its dictionary (containing the module's global
   variables) is retained.  Redefinitions of names will override the old
   definitions, so this is generally not a problem.  If the new version of a module
   does not define a name that was defined by the old version, the old definition
   remains.  This feature can be used to the module's advantage if it maintains a
   global table or cache of objects --- with a :keyword:`try` statement it can test
   for the table's presence and skip its initialization if desired::

      try:
          cache
      except NameError:
          cache = {}

   It is legal though generally not very useful to reload built-in or dynamically
   loaded modules, except for :mod:`sys`, :mod:`__main__` and :mod:`__builtin__`.
   In many cases, however, extension modules are not designed to be initialized
   more than once, and may fail in arbitrary ways when reloaded.

   If a module imports objects from another module using :keyword:`from` ...
   :keyword:`import` ..., calling :func:`reload` for the other module does not
   redefine the objects imported from it --- one way around this is to re-execute
   the :keyword:`from` statement, another is to use :keyword:`import` and qualified
   names (*module*.*name*) instead.

   If a module instantiates instances of a class, reloading the module that defines
   the class does not affect the method definitions of the instances --- they
   continue to use the old class definition.  The same is true for derived classes.


.. function:: repr(object)

   Return a string containing a printable representation of an object.  This is
   the same value yielded by conversions (reverse quotes).  It is sometimes
   useful to be able to access this operation as an ordinary function.  For many
   types, this function makes an attempt to return a string that would yield an
   object with the same value when passed to :func:`eval`, otherwise the
   representation is a string enclosed in angle brackets that contains the name
   of the type of the object together with additional information often
   including the name and address of the object.  A class can control what this
   function returns for its instances by defining a :meth:`__repr__` method.


.. function:: reversed(seq)

   Return a reverse :term:`iterator`.  *seq* must be an object which has
   a :meth:`__reversed__` method or supports the sequence protocol (the
   :meth:`__len__` method and the :meth:`__getitem__` method with integer
   arguments starting at ``0``).

   .. versionadded:: 2.4

   .. versionchanged:: 2.6
      Added the possibility to write a custom :meth:`__reversed__` method.


.. function:: round(x[, n])

   Return the floating point value *x* rounded to *n* digits after the decimal
   point.  If *n* is omitted, it defaults to zero. The result is a floating point
   number.  Values are rounded to the closest multiple of 10 to the power minus
   *n*; if two multiples are equally close, rounding is done away from 0 (so. for
   example, ``round(0.5)`` is ``1.0`` and ``round(-0.5)`` is ``-1.0``).




.. function:: setattr(object, name, value)

   This is the counterpart of :func:`getattr`.  The arguments are an object, a
   string and an arbitrary value.  The string may name an existing attribute or a
   new attribute.  The function assigns the value to the attribute, provided the
   object allows it.  For example, ``setattr(x, 'foobar', 123)`` is equivalent to
   ``x.foobar = 123``.


.. function:: slice([start,] stop[, step])

   .. index:: single: Numerical Python

   Return a :term:`slice` object representing the set of indices specified by
   ``range(start, stop, step)``.  The *start* and *step* arguments default to
   ``None``.  Slice objects have read-only data attributes :attr:`start`,
   :attr:`stop` and :attr:`step` which merely return the argument values (or their
   default).  They have no other explicit functionality; however they are used by
   Numerical Python and other third party extensions.  Slice objects are also
   generated when extended indexing syntax is used.  For example:
   ``a[start:stop:step]`` or ``a[start:stop, i]``.  See :func:`itertools.islice`
   for an alternate version that returns an iterator.


.. function:: sorted(iterable[, cmp[, key[, reverse]]])

   Return a new sorted list from the items in *iterable*.

   The optional arguments *cmp*, *key*, and *reverse* have the same meaning as
   those for the :meth:`list.sort` method (described in section
   :ref:`typesseq-mutable`).

   *cmp* specifies a custom comparison function of two arguments (iterable
   elements) which should return a negative, zero or positive number depending on
   whether the first argument is considered smaller than, equal to, or larger than
   the second argument: ``cmp=lambda x,y: cmp(x.lower(), y.lower())``.  The default
   value is ``None``.

   *key* specifies a function of one argument that is used to extract a comparison
   key from each list element: ``key=str.lower``.  The default value is ``None``.

   *reverse* is a boolean value.  If set to ``True``, then the list elements are
   sorted as if each comparison were reversed.

   In general, the *key* and *reverse* conversion processes are much faster
   than specifying an equivalent *cmp* function.  This is because *cmp* is
   called multiple times for each list element while *key* and *reverse* touch
   each element only once.  To convert an old-style *cmp* function to a *key*
   function, see the `CmpToKey recipe in the ASPN cookbook
   <http://code.activestate.com/recipes/576653/>`_\.

   .. versionadded:: 2.4


.. function:: staticmethod(function)

   Return a static method for *function*.

   A static method does not receive an implicit first argument. To declare a static
   method, use this idiom::

      class C:
          @staticmethod
          def f(arg1, arg2, ...): ...

   The ``@staticmethod`` form is a function :term:`decorator` -- see the
   description of function definitions in :ref:`function` for details.

   It can be called either on the class (such as ``C.f()``) or on an instance (such
   as ``C().f()``).  The instance is ignored except for its class.

   Static methods in Python are similar to those found in Java or C++. For a more
   advanced concept, see :func:`classmethod` in this section.

   For more information on static methods, consult the documentation on the
   standard type hierarchy in :ref:`types`.

   .. versionadded:: 2.2

   .. versionchanged:: 2.4
      Function decorator syntax added.



.. function:: sum(iterable[, start])

   Sums *start* and the items of an *iterable* from left to right and returns the
   total.  *start* defaults to ``0``. The *iterable*'s items are normally numbers,
   and are not allowed to be strings.  The fast, correct way to concatenate a
   sequence of strings is by calling ``''.join(sequence)``. Note that
   ``sum(range(n), m)`` is equivalent to ``reduce(operator.add, range(n), m)``
   To add floating point values with extended precision, see :func:`math.fsum`\.

   .. versionadded:: 2.3


.. function:: super(type[, object-or-type])

   Return a proxy object that delegates method calls to a parent or sibling
   class of *type*.  This is useful for accessing inherited methods that have
   been overridden in a class. The search order is same as that used by
   :func:`getattr` except that the *type* itself is skipped.

   The :attr:`__mro__` attribute of the *type* lists the method resolution
   search order used by both :func:`getattr` and :func:`super`.  The attribute
   is dynamic and can change whenever the inheritance hierarchy is updated.

   If the second argument is omitted, the super object returned is unbound.  If
   the second argument is an object, ``isinstance(obj, type)`` must be true.  If
   the second argument is a type, ``issubclass(type2, type)`` must be true (this
   is useful for classmethods).

   .. note::
      :func:`super` only works for :term:`new-style class`\es.

   There are two typical use cases for *super*.  In a class hierarchy with
   single inheritance, *super* can be used to refer to parent classes without
   naming them explicitly, thus making the code more maintainable.  This use
   closely parallels the use of *super* in other programming languages.

   The second use case is to support cooperative multiple inheritance in a
   dynamic execution environment.  This use case is unique to Python and is
   not found in statically compiled languages or languages that only support
   single inheritance.  This makes it possible to implement "diamond diagrams"
   where multiple base classes implement the same method.  Good design dictates
   that this method have the same calling signature in every case (because the
   order of calls is determined at runtime, because that order adapts
   to changes in the class hierarchy, and because that order can include
   sibling classes that are unknown prior to runtime).

   For both use cases, a typical superclass call looks like this::

      class C(B):
          def method(self, arg):
              super(C, self).method(arg)

   Note that :func:`super` is implemented as part of the binding process for
   explicit dotted attribute lookups such as ``super().__getitem__(name)``.
   It does so by implementing its own :meth:`__getattribute__` method for searching
   classes in a predictable order that supports cooperative multiple inheritance.
   Accordingly, :func:`super` is undefined for implicit lookups using statements or
   operators such as ``super()[name]``.

   Also note that :func:`super` is not limited to use inside methods.  The two
   argument form specifies the arguments exactly and makes the appropriate
   references.

   .. versionadded:: 2.2




.. function:: type(object)

   .. index:: object: type

   Return the type of an *object*.  The return value is a type object.  The
   :func:`isinstance` built-in function is recommended for testing the type of an
   object.

   With three arguments, :func:`type` functions as a constructor as detailed below.





.. function:: vars([object])

   Without arguments, return a dictionary corresponding to the current local symbol
   table.  With a module, class or class instance object as argument (or anything
   else that has a :attr:`__dict__` attribute), returns a dictionary corresponding
   to the object's symbol table.

   .. warning::

      The returned dictionary should not be modified:
      the effects on the corresponding symbol table are undefined. [#]_


.. function:: xrange([start,] stop[, step])

   This function is very similar to :func:`range`, but returns an "xrange object"
   instead of a list.  This is an opaque sequence type which yields the same values
   as the corresponding list, without actually storing them all simultaneously.
   The advantage of :func:`xrange` over :func:`range` is minimal (since
   :func:`xrange` still has to create the values when asked for them) except when a
   very large range is used on a memory-starved machine or when all of the range's
   elements are never used (such as when the loop is usually terminated with
   :keyword:`break`).

   .. note::

      :func:`xrange` is intended to be simple and fast. Implementations may impose
      restrictions to achieve this. The C implementation of Python restricts all
      arguments to native C longs ("short" Python integers), and also requires that
      the number of elements fit in a native C long.  If a larger range is needed,
      an alternate version can be crafted using the :mod:`itertools` module:
      ``islice(count(start, step), (stop-start+step-1)//step)``.


.. function:: zip([iterable, ...])

   This function returns a list of tuples, where the *i*-th tuple contains the
   *i*-th element from each of the argument sequences or iterables. The returned
   list is truncated in length to the length of the shortest argument sequence.
   When there are multiple arguments which are all of the same length, :func:`zip`
   is similar to :func:`map` with an initial argument of ``None``. With a single
   sequence argument, it returns a list of 1-tuples. With no arguments, it returns
   an empty list.

   The left-to-right evaluation order of the iterables is guaranteed. This
   makes possible an idiom for clustering a data series into n-length groups
   using ``zip(*[iter(s)]*n)``.

   :func:`zip` in conjunction with the ``*`` operator can be used to unzip a
   list::

      >>> x = [1, 2, 3]
      >>> y = [4, 5, 6]
      >>> zipped = zip(x, y)
      >>> zipped
      [(1, 4), (2, 5), (3, 6)]
      >>> x2, y2 = zip(*zipped)
      >>> x == x2, y == y2
      True

   .. versionadded:: 2.0

   .. versionchanged:: 2.4
      Formerly, :func:`zip` required at least one argument and ``zip()`` raised a
      :exc:`TypeError` instead of returning an empty list.


.. function:: __import__(name[, globals[, locals[, fromlist[, level]]]])

   .. index::
      statement: import
      module: imp

   .. note::

      This is an advanced function that is not needed in everyday Python
      programming.

   This function is invoked by the :keyword:`import` statement.  It can be
   replaced (by importing the :mod:`builtins` module and assigning to
   ``builtins.__import__``) in order to change semantics of the
   :keyword:`import` statement, but nowadays it is usually simpler to use import
   hooks (see :pep:`302`).  Direct use of :func:`__import__` is rare, except in
   cases where you want to import a module whose name is only known at runtime.

   The function imports the module *name*, potentially using the given *globals*
   and *locals* to determine how to interpret the name in a package context.
   The *fromlist* gives the names of objects or submodules that should be
   imported from the module given by *name*.  The standard implementation does
   not use its *locals* argument at all, and uses its *globals* only to
   determine the package context of the :keyword:`import` statement.

   *level* specifies whether to use absolute or relative imports.  The default
   is ``-1`` which indicates both absolute and relative imports will be
   attempted.  ``0`` means only perform absolute imports.  Positive values for
   *level* indicate the number of parent directories to search relative to the
   directory of the module calling :func:`__import__`.

   When the *name* variable is of the form ``package.module``, normally, the
   top-level package (the name up till the first dot) is returned, *not* the
   module named by *name*.  However, when a non-empty *fromlist* argument is
   given, the module named by *name* is returned.

   For example, the statement ``import spam`` results in bytecode resembling the
   following code::

      spam = __import__('spam', globals(), locals(), [], -1)

   The statement ``import spam.ham`` results in this call::

      spam = __import__('spam.ham', globals(), locals(), [], -1)

   Note how :func:`__import__` returns the toplevel module here because this is
   the object that is bound to a name by the :keyword:`import` statement.

   On the other hand, the statement ``from spam.ham import eggs, sausage as
   saus`` results in ::

      _temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], -1)
      eggs = _temp.eggs
      saus = _temp.sausage

   Here, the ``spam.ham`` module is returned from :func:`__import__`.  From this
   object, the names to import are retrieved and assigned to their respective
   names.

   If you simply want to import a module (potentially within a package) by name,
   you can get it from :data:`sys.modules`::

      >>> import sys
      >>> name = 'foo.bar.baz'
      >>> __import__(name)
      <module 'foo' from ...>
      >>> baz = sys.modules[name]
      >>> baz
      <module 'foo.bar.baz' from ...>

   .. versionchanged:: 2.5
      The level parameter was added.

   .. versionchanged:: 2.5
      Keyword support for parameters was added.

..  ---------------------------------------------------------------------------