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 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329 2330 2331 2332 2333 2334 2335 2336 2337 2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568 2569 2570 2571 2572 2573 2574 2575 2576 2577 2578 2579 2580 2581 2582 2583 2584 2585 2586 2587 2588 2589 2590 2591 2592 2593 2594 2595 2596 2597 2598 2599 2600 2601 2602 2603 2604 2605 2606 2607 2608 2609 2610 2611 2612 2613 2614 2615 2616 2617 2618 2619 2620 2621 2622 2623 2624 2625 2626 2627 2628 2629 2630 2631 2632 2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 2646 2647 2648 2649 2650 2651 2652 2653 2654 2655 2656 2657 2658 2659 2660 2661 2662 2663 2664 2665 2666 2667 2668 2669 2670 2671 2672 2673 2674 2675 2676 2677 2678 2679 2680 2681 2682 2683 2684 2685 2686 2687 2688 2689 2690 2691 2692 2693 2694 2695 2696 2697 2698 2699 2700 2701 2702 2703 2704 2705 2706 2707 2708 2709 2710 2711 2712 2713 2714 2715 2716 2717 2718 2719 2720 2721 2722 2723 2724 2725 2726 2727 2728 2729 2730 2731 2732 2733 2734 2735 2736 2737 2738 2739 2740 2741 2742 2743 2744 2745 2746 2747 2748 2749 2750 2751 2752 2753 2754 2755 2756 2757 2758 2759 2760 2761 2762 2763 2764 2765 2766 2767 2768 2769 2770 2771 2772 2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 2784 2785 2786 2787 2788 2789 2790 2791 2792 2793 2794 2795 2796 2797 2798 2799 2800 2801 2802 2803 2804 2805 2806 2807 2808 2809 2810 2811 2812 2813 2814 2815 2816 2817 2818 2819 2820 2821 2822 2823 2824 2825 2826 2827 2828 2829 2830 2831 2832 2833 2834 2835 2836 2837 2838 2839 2840 2841 2842 2843 2844 2845 2846 2847 2848 2849 2850 2851 2852 2853 2854 2855 2856 2857 2858 2859 2860 2861 2862 2863 2864 2865 2866 2867 2868 2869 2870 2871 2872 2873 2874 2875 2876 2877 2878 2879 2880 2881 2882 2883 2884 2885 2886 2887 2888 2889 2890 2891 2892 2893 2894 2895 2896 2897 2898 2899 2900 2901 2902 2903 2904 2905 2906 2907 2908 2909 2910 2911 2912 2913 2914 2915 2916 2917 2918 2919 2920 2921 2922 2923 2924 2925 2926 2927 2928 2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 2948 2949 2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 3011 3012 3013 3014 3015 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026 3027 3028 3029 3030 3031 3032 3033 3034 3035 3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3068 3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 3080 3081 3082 3083 3084 3085 3086 3087 3088 3089 3090 3091 3092 3093 3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 3104 3105 3106 3107 3108 3109 3110 3111 3112 3113 3114 3115 3116 3117 3118 3119 3120 3121 3122 3123 3124 3125 3126 3127 3128 3129 3130 3131 3132 3133 3134 3135 3136 3137 3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 3158 3159 3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 3434 3435 3436 3437 3438 3439 3440 3441 3442 3443 3444 3445 3446 3447 3448 3449 3450 3451 3452 3453 3454 3455 3456 3457 3458 3459 3460 3461 3462 3463 3464 3465 3466 3467 3468 3469 3470 3471 3472 3473 3474 3475 3476 3477 3478 3479 3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 3538 3539 3540 3541 3542 3543 3544 3545 3546 3547 3548 3549 3550 3551 3552 3553 3554 3555 3556 3557 3558 3559 3560 3561 3562 3563 3564 3565 3566 3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581 3582 3583 3584 3585 3586 3587 3588 3589 3590 3591 3592 3593 3594 3595 3596 3597 3598 3599 3600 3601 3602 3603 3604 3605 3606 3607 3608 3609 3610 3611 3612 3613 3614 3615 3616 3617 3618 3619 3620 3621 3622 3623 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642 3643 3644 3645 3646 3647 3648 3649 3650 3651 3652 3653 3654 3655 3656 3657 3658 3659 3660 3661 3662 3663 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686 3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3697 3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801 3802 3803 3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837 3838 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 3850 3851 3852 3853 3854 3855 3856 3857 3858 3859 3860 3861 3862 3863 3864 3865 3866 3867 3868 3869 3870 3871 3872 3873 3874 3875 3876 3877 3878 3879 3880 3881 3882 3883 3884 3885 3886 3887 3888 3889 3890 3891 3892 3893 3894 3895 3896 3897 3898 3899 3900 3901 3902 3903 3904 3905 3906 3907 3908 3909 3910 3911 3912 3913 3914 3915 3916 3917 3918 3919 3920 3921 3922 3923 3924 3925 3926 3927 3928 3929 3930 3931 3932 3933 3934 3935 3936 3937 3938 3939 3940 3941 3942 3943 3944 3945 3946 3947 3948 3949 3950 3951 3952 3953 3954 3955 3956 3957 3958 3959 3960 3961 3962 3963 3964 3965 3966 3967 3968 3969 3970 3971 3972 3973 3974 3975 3976 3977 3978 3979 3980 3981 3982 3983 3984 3985 3986 3987 3988 3989 3990 3991 3992 3993 3994 3995 3996 3997 3998 3999 4000 4001 4002 4003 4004 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4016 4017 4018 4019 4020 4021 4022 4023 4024 4025 4026 4027 4028 4029 4030 4031 4032 4033 4034 4035 4036 4037 4038 4039 4040 4041 4042 4043 4044 4045 4046 4047 4048 4049 4050 4051 4052 4053 4054 4055 4056 4057 4058 4059 4060 4061 4062 4063 4064 4065 4066 4067 4068 4069 4070 4071 4072 4073 4074 4075 4076 4077 4078 4079 4080 4081 4082 4083 4084 4085 4086 4087 4088 4089 4090 4091 4092 4093 4094 4095 4096 4097 4098 4099 4100 4101 4102 4103 4104 4105 4106 4107 4108 4109 4110 4111 4112 4113 4114 4115 4116 4117 4118 4119 4120 4121 4122 4123 4124 4125 4126 4127 4128 4129 4130 4131 4132 4133 4134 4135 4136 4137 4138 4139 4140 4141 4142 4143 4144 4145 4146 4147 4148 4149 4150 4151 4152 4153 4154 4155 4156 4157 4158 4159 4160 4161 4162 4163 4164 4165 4166 4167 4168 4169 4170 4171 4172 4173 4174 4175 4176 4177 4178 4179 4180 4181 4182 4183 4184 4185 4186 4187 4188 4189 4190 4191 4192 4193 4194 4195 4196 4197 4198 4199 4200 4201 4202 4203 4204 4205 4206 4207 4208 4209 4210 4211 4212 4213 4214 4215 4216 4217 4218 4219 4220 4221 4222 4223 4224 4225 4226 4227 4228 4229 4230 4231 4232 4233 4234 4235 4236 4237 4238 4239 4240 4241 4242 4243 4244 4245 4246 4247 4248 4249 4250 4251 4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 4266 4267 4268 4269 4270 4271 4272 4273 4274 4275 4276 4277 4278 4279 4280 4281 4282 4283 4284 4285 4286 4287 4288 4289 4290 4291 4292 4293 4294 4295 4296 4297 4298 4299 4300 4301 4302 4303 4304 4305 4306 4307 4308 4309 4310 4311 4312 4313 4314 4315 4316 4317 4318 4319 4320 4321 4322 4323 4324 4325 4326 4327 4328 4329 4330 4331 4332 4333 4334 4335 4336 4337 4338 4339 4340 4341 4342 4343 4344 4345 4346 4347 4348 4349 4350 4351 4352 4353 4354 4355 4356 4357 4358 4359 4360 4361 4362 4363 4364 4365 4366 4367 4368 4369 4370 4371 4372 4373 4374 4375 4376 4377 4378 4379 4380 4381 4382 4383 4384 4385 4386 4387 4388 4389 4390 4391 4392 4393 4394 4395 4396 4397 4398 4399 4400 4401 4402 4403 4404 4405 4406 4407 4408 4409 4410 4411 4412 4413 4414 4415 4416 4417 4418 4419 4420 4421 4422 4423 4424 4425 4426 4427 4428 4429 4430 4431 4432 4433 4434 4435 4436 4437 4438 4439 4440 4441 4442 4443 4444 4445 4446 4447 4448 4449 4450 4451 4452 4453 4454 4455 4456 4457 4458 4459 4460 4461 4462 4463 4464 4465 4466 4467 4468 4469 4470 4471 4472 4473 4474 4475 4476 4477 4478 4479 4480 4481 4482 4483 4484 4485 4486 4487 4488 4489 4490 4491 4492 4493 4494 4495 4496 4497 4498 4499 4500 4501 4502 4503 4504 4505 4506 4507 4508 4509 4510 4511 4512 4513 4514 4515 4516 4517 4518 4519 4520 4521 4522 4523 4524 4525 4526 4527 4528 4529 4530 4531 4532 4533 4534 4535 4536 4537 4538 4539 4540 4541 4542 4543 4544 4545 4546 4547 4548 4549 4550 4551 4552 4553 4554 4555 4556 4557 4558 4559 4560 4561 4562 4563 4564 4565 4566 4567 4568 4569 4570 4571 4572 4573 4574 4575 4576 4577 4578 4579 4580 4581 4582 4583 4584 4585 4586 4587 4588 4589 4590 4591 4592 4593 4594 4595 4596 4597 4598 4599 4600 4601 4602 4603 4604 4605 4606 4607 4608 4609 4610 4611 4612 4613 4614 4615 4616 4617 4618 4619 4620 4621 4622 4623 4624 4625 4626 4627 4628 4629 4630 4631 4632 4633 4634 4635 4636 4637 4638 4639 4640 4641 4642 4643 4644 4645 4646 4647 4648 4649 4650 4651 4652 4653 4654 4655 4656 4657 4658 4659 4660 4661 4662 4663 4664 4665 4666 4667 4668 4669 4670 4671 4672 4673 4674 4675 4676 4677 4678 4679 4680 4681 4682 4683 4684 4685 4686 4687 4688 4689 4690 4691 4692 4693 4694 4695 4696 4697 4698 4699 4700 4701 4702 4703 4704 4705 4706 4707 4708 4709 4710 4711 4712 4713 4714 4715 4716 4717 4718 4719 4720 4721 4722 4723 4724 4725 4726 4727 4728 4729 4730 4731 4732 4733 4734 4735 4736 4737 4738 4739 4740 4741 4742 4743 4744 4745 4746 4747 4748 4749 4750 4751 4752 4753 4754 4755 4756 4757 4758 4759 4760 4761 4762 4763 4764 4765 4766 4767 4768 4769 4770 4771 4772 4773 4774 4775 4776 4777 4778 4779 4780 4781 4782 4783 4784 4785 4786 4787 4788 4789 4790 4791 4792 4793 4794 4795 4796 4797 4798 4799 4800 4801 4802 4803 4804 4805 4806 4807 4808 4809 4810 4811 4812 4813 4814 4815 4816 4817 4818 4819 4820 4821 4822 4823 4824 4825 4826 4827 4828 4829 4830 4831 4832 4833 4834 4835 4836 4837 4838 4839 4840 4841 4842 4843 4844 4845 4846 4847 4848 4849 4850 4851 4852 4853 4854 4855 4856 4857 4858 4859 4860 4861 4862 4863 4864 4865 4866 4867 4868 4869 4870 4871 4872 4873 4874 4875 4876 4877 4878 4879 4880 4881 4882 4883 4884 4885 4886 4887 4888 4889 4890 4891 4892 4893 4894 4895 4896 4897 4898 4899 4900 4901 4902 4903 4904 4905 4906 4907 4908 4909 4910 4911 4912 4913 4914 4915 4916 4917 4918 4919 4920 4921 4922 4923 4924 4925 4926 4927 4928 4929 4930 4931 4932 4933 4934 4935 4936 4937 4938 4939 4940 4941 4942 4943 4944 4945 4946 4947 4948 4949 4950 4951 4952 4953 4954 4955 4956 4957 4958 4959 4960 4961 4962 4963 4964 4965 4966 4967 4968 4969 4970 4971 4972 4973 4974 4975 4976 4977 4978 4979 4980 4981 4982 4983 4984 4985 4986 4987 4988 4989 4990 4991 4992 4993 4994 4995 4996 4997 4998 4999 5000 5001 5002 5003 5004 5005 5006 5007 5008 5009 5010 5011 5012 5013 5014 5015 5016 5017 5018 5019 5020 5021 5022 5023 5024 5025 5026 5027 5028 5029 5030 5031 5032 5033 5034 5035 5036 5037 5038 5039 5040 5041 5042 5043 5044 5045 5046 5047 5048 5049 5050 5051 5052 5053 5054 5055 5056 5057 5058 5059 5060 5061 5062 5063 5064 5065 5066 5067 5068 5069 5070 5071 5072 5073 5074 5075 5076 5077 5078 5079 5080 5081 5082 5083 5084 5085 5086 5087 5088 5089 5090 5091 5092 5093 5094 5095 5096 5097 5098 5099 5100 5101 5102 5103 5104 5105 5106 5107 5108 5109 5110 5111 5112 5113 5114 5115 5116 5117 5118 5119 5120 5121 5122 5123 5124 5125 5126 5127 5128 5129 5130 5131 5132 5133 5134 5135 5136 5137 5138 5139 5140 5141 5142 5143 5144 5145 5146 5147 5148 5149 5150 5151 5152 5153 5154 5155 5156 5157 5158 5159 5160 5161 5162 5163 5164 5165 5166 5167 5168 5169 5170 5171 5172 5173 5174 5175 5176 5177 5178 5179 5180 5181 5182 5183 5184 5185 5186 5187 5188 5189 5190 5191 5192 5193 5194 5195 5196 5197 5198 5199 5200 5201 5202 5203 5204 5205 5206 5207 5208 5209 5210 5211 5212 5213 5214 5215 5216 5217 5218 5219 5220 5221 5222 5223 5224 5225 5226 5227 5228 5229 5230 5231 5232 5233 5234 5235 5236 5237 5238 5239 5240 5241 5242 5243 5244 5245 5246 5247 5248 5249 5250 5251 5252 5253 5254 5255 5256 5257 5258 5259 5260 5261 5262 5263 5264 5265 5266 5267 5268 5269 5270 5271 5272 5273 5274 5275 5276 5277 5278 5279 5280 5281 5282 5283 5284 5285 5286 5287 5288 5289 5290 5291 5292 5293 5294 5295 5296 5297 5298 5299 5300 5301 5302 5303 5304 5305 5306 5307 5308 5309 5310 5311 5312 5313 5314 5315 5316 5317 5318 5319 5320 5321 5322 5323 5324 5325 5326 5327 5328 5329 5330 5331 5332 5333 5334 5335 5336 5337 5338 5339 5340 5341 5342 5343 5344 5345 5346 5347 5348 5349 5350 5351 5352 5353 5354 5355 5356 5357 5358 5359 5360 5361 5362 5363 5364 5365 5366 5367 5368 5369 5370 5371 5372 5373 5374 5375 5376 5377 5378 5379 5380 5381 5382 5383 5384 5385 5386 5387 5388 5389 5390 5391 5392 5393 5394 5395 5396 5397 5398 5399 5400 5401 5402 5403 5404 5405 5406 5407 5408 5409 5410 5411 5412 5413 5414 5415 5416 5417 5418 5419 5420 5421 5422 5423 5424 5425 5426 5427 5428 5429 5430 5431 5432 5433 5434 5435 5436 5437 5438 5439 5440 5441 5442 5443 5444 5445 5446 5447 5448 5449 5450 5451 5452 5453 5454 5455 5456 5457 5458 5459 5460 5461 5462 5463 5464 5465 5466 5467 5468 5469 5470 5471 5472 5473 5474 5475 5476 5477 5478 5479 5480 5481 5482 5483 5484 5485 5486 5487 5488 5489 5490 5491 5492 5493 5494 5495 5496 5497 5498 5499 5500 5501 5502 5503 5504 5505 5506 5507 5508 5509 5510 5511 5512 5513 5514 5515 5516 5517 5518 5519 5520 5521 5522 5523 5524 5525 5526 5527 5528 5529 5530 5531 5532 5533 5534 5535 5536 5537 5538 5539 5540 5541 5542 5543 5544 5545 5546 5547 5548 5549 5550 5551 5552 5553 5554 5555 5556 5557 5558 5559 5560 5561 5562 5563 5564 5565 5566 5567 5568 5569 5570 5571 5572 5573 5574 5575 5576 5577 5578 5579 5580 5581 5582 5583 5584 5585 5586 5587 5588 5589 5590 5591 5592 5593 5594 5595 5596 5597 5598 5599 5600 5601 5602 5603 5604 5605 5606 5607 5608 5609 5610 5611 5612 5613 5614 5615 5616 5617 5618 5619 5620 5621 5622 5623 5624 5625 5626 5627 5628 5629 5630 5631 5632 5633 5634 5635 5636 5637 5638 5639 5640 5641 5642 5643 5644 5645 5646 5647 5648 5649 5650 5651 5652 5653 5654 5655 5656 5657 5658 5659 5660 5661 5662 5663 5664 5665 5666 5667 5668 5669 5670 5671 5672 5673 5674 5675 5676 5677 5678 5679 5680 5681 5682 5683 5684 5685 5686 5687 5688 5689 5690 5691 5692 5693 5694 5695 5696 5697 5698 5699 5700 5701 5702 5703 5704 5705 5706 5707 5708 5709 5710 5711 5712 5713 5714 5715 5716 5717 5718 5719 5720 5721 5722 5723 5724 5725 5726 5727 5728 5729 5730 5731 5732 5733 5734 5735 5736 5737 5738 5739 5740 5741 5742 5743 5744 5745 5746 5747 5748 5749 5750 5751 5752 5753 5754 5755 5756 5757 5758 5759 5760 5761 5762 5763 5764 5765 5766 5767 5768 5769 5770 5771 5772 5773 5774 5775 5776 5777 5778 5779 5780 5781 5782 5783 5784 5785 5786 5787 5788 5789 5790 5791 5792 5793 5794 5795 5796 5797 5798 5799 5800 5801 5802 5803 5804 5805 5806 5807 5808 5809 5810 5811 5812 5813 5814 5815 5816 5817 5818 5819 5820 5821 5822 5823 5824 5825 5826 5827 5828 5829 5830 5831 5832 5833 5834 5835 5836 5837 5838 5839 5840 5841 5842 5843 5844 5845 5846 5847 5848 5849 5850 5851 5852 5853 5854 5855 5856 5857 5858 5859 5860 5861 5862 5863 5864 5865 5866 5867 5868 5869 5870 5871 5872 5873 5874 5875 5876 5877 5878 5879 5880 5881 5882 5883 5884 5885 5886 5887 5888 5889 5890 5891 5892 5893 5894 5895 5896 5897 5898 5899 5900 5901 5902 5903 5904 5905 5906 5907 5908 5909 5910 5911 5912 5913 5914 5915 5916 5917 5918 5919 5920 5921 5922 5923 5924 5925 5926 5927 5928 5929 5930 5931 5932 5933 5934 5935 5936 5937 5938 5939 5940 5941 5942 5943 5944 5945 5946 5947 5948 5949 5950 5951 5952 5953 5954 5955 5956 5957 5958 5959 5960 5961 5962 5963 5964 5965 5966 5967 5968 5969 5970 5971 5972 5973 5974 5975 5976 5977 5978 5979 5980 5981 5982 5983 5984 5985 5986 5987 5988 5989 5990 5991 5992 5993 5994 5995 5996 5997 5998 5999 6000 6001 6002 6003 6004 6005 6006 6007 6008 6009 6010 6011 6012 6013 6014 6015 6016 6017 6018 6019 6020 6021 6022 6023 6024 6025 6026 6027 6028 6029 6030 6031 6032 6033 6034 6035 6036 6037 6038 6039 6040 6041 6042 6043 6044 6045 6046 6047 6048 6049 6050 6051 6052 6053 6054 6055 6056 6057 6058 6059 6060 6061 6062 6063 6064 6065 6066 6067 6068 6069 6070 6071 6072 6073 6074 6075 6076 6077 6078 6079 6080 6081 6082 6083 6084 6085 6086 6087 6088 6089 6090 6091 6092 6093 6094 6095 6096 6097 6098 6099 6100 6101 6102 6103 6104 6105 6106 6107 6108 6109 6110 6111 6112 6113 6114 6115 6116 6117 6118 6119 6120 6121 6122 6123 6124 6125 6126 6127 6128 6129 6130 6131 6132 6133 6134 6135 6136 6137 6138 6139 6140 6141 6142 6143 6144 6145 6146 6147 6148 6149 6150 6151 6152 6153 6154 6155 6156 6157 6158 6159 6160 6161 6162 6163 6164 6165 6166 6167 6168 6169 6170 6171 6172 6173 6174 6175 6176 6177 6178 6179 6180 6181 6182 6183 6184 6185 6186 6187 6188 6189 6190 6191 6192 6193 6194 6195 6196 6197 6198 6199 6200 6201 6202 6203 6204 6205 6206 6207 6208 6209 6210 6211 6212 6213 6214 6215 6216 6217 6218 6219 6220 6221 6222 6223 6224 6225 6226 6227 6228 6229 6230 6231 6232 6233 6234 6235 6236 6237 6238 6239 6240 6241 6242 6243 6244 6245 6246 6247 6248 6249 6250 6251 6252 6253 6254 6255 6256 6257 6258 6259 6260 6261 6262 6263 6264 6265 6266 6267 6268 6269 6270 6271 6272 6273 6274 6275 6276 6277 6278 6279 6280 6281 6282 6283 6284 6285 6286 6287 6288 6289 6290 6291 6292 6293 6294 6295 6296 6297 6298 6299 6300 6301 6302 6303 6304 6305 6306 6307 6308 6309 6310 6311 6312 6313 6314 6315 6316 6317 6318 6319 6320 6321 6322 6323 6324 6325 6326 6327 6328 6329 6330 6331 6332 6333 6334 6335 6336 6337 6338 6339 6340 6341 6342 6343 6344 6345 6346 6347 6348 6349 6350 6351 6352 6353 6354 6355 6356 6357 6358 6359 6360 6361 6362 6363 6364 6365 6366 6367 6368 6369 6370 6371 6372 6373 6374 6375 6376 6377 6378 6379 6380 6381 6382 6383 6384 6385 6386 6387 6388 6389 6390 6391 6392 6393 6394 6395 6396 6397 6398 6399 6400 6401 6402 6403 6404 6405 6406 6407 6408 6409 6410 6411 6412 6413 6414 6415 6416 6417 6418 6419 6420 6421 6422 6423 6424 6425 6426 6427 6428 6429 6430 6431 6432 6433 6434 6435 6436 6437 6438 6439 6440 6441 6442 6443 6444 6445 6446 6447 6448 6449 6450 6451 6452 6453 6454 6455 6456 6457 6458 6459 6460 6461 6462 6463 6464 6465 6466 6467 6468 6469 6470 6471 6472 6473 6474 6475 6476 6477 6478 6479 6480 6481 6482 6483 6484 6485 6486 6487 6488 6489 6490 6491 6492 6493 6494 6495 6496 6497 6498 6499 6500 6501 6502 6503 6504 6505 6506 6507 6508 6509 6510 6511 6512 6513 6514 6515 6516 6517 6518 6519 6520 6521 6522 6523 6524 6525 6526 6527 6528 6529 6530 6531 6532 6533 6534 6535 6536 6537 6538 6539 6540 6541 6542 6543 6544 6545 6546 6547 6548 6549 6550 6551 6552 6553 6554 6555 6556 6557 6558 6559 6560 6561 6562 6563 6564 6565 6566 6567 6568 6569 6570 6571 6572 6573 6574 6575 6576 6577 6578 6579 6580 6581 6582 6583 6584 6585 6586 6587 6588 6589 6590 6591 6592 6593 6594 6595 6596 6597 6598 6599 6600 6601 6602 6603 6604 6605 6606 6607 6608 6609 6610 6611 6612 6613 6614 6615 6616 6617 6618 6619 6620 6621 6622 6623 6624 6625 6626 6627 6628 6629 6630 6631 6632 6633 6634 6635 6636 6637 6638 6639 6640 6641 6642 6643 6644 6645 6646 6647 6648 6649 6650 6651 6652 6653 6654 6655 6656 6657 6658 6659 6660 6661 6662 6663 6664 6665 6666 6667 6668 6669 6670 6671 6672 6673 6674 6675 6676 6677 6678 6679 6680 6681 6682 6683 6684 6685 6686 6687 6688 6689 6690 6691 6692 6693 6694 6695 6696 6697 6698 6699 6700 6701 6702 6703 6704 6705 6706 6707 6708 6709 6710 6711 6712 6713 6714 6715 6716 6717 6718 6719 6720 6721 6722 6723 6724 6725 6726 6727 6728 6729 6730 6731 6732 6733 6734 6735 6736 6737 6738 6739 6740 6741 6742 6743 6744 6745 6746 6747 6748 6749 6750 6751 6752 6753 6754 6755 6756 6757 6758 6759 6760 6761 6762 6763 6764 6765 6766 6767 6768 6769 6770 6771 6772 6773 6774 6775 6776 6777 6778 6779 6780 6781 6782 6783 6784 6785 6786 6787 6788 6789 6790 6791 6792 6793 6794 6795 6796 6797 6798 6799 6800 6801 6802 6803 6804 6805 6806 6807 6808 6809 6810 6811 6812 6813 6814 6815 6816 6817 6818 6819 6820 6821 6822 6823 6824 6825 6826 6827 6828 6829 6830 6831 6832 6833 6834 6835 6836 6837 6838 6839 6840 6841 6842 6843 6844 6845 6846 6847 6848 6849 6850 6851 6852 6853 6854 6855 6856 6857 6858 6859 6860 6861 6862 6863 6864 6865 6866 6867 6868 6869 6870 6871 6872 6873 6874 6875 6876 6877 6878 6879 6880 6881 6882 6883 6884 6885 6886 6887 6888 6889 6890 6891 6892 6893 6894 6895 6896 6897 6898 6899 6900 6901 6902 6903 6904 6905 6906 6907 6908 6909 6910 6911 6912 6913 6914 6915 6916 6917 6918 6919 6920 6921 6922 6923 6924 6925 6926 6927 6928 6929 6930 6931 6932 6933 6934 6935 6936 6937 6938 6939 6940 6941 6942 6943 6944 6945 6946 6947 6948 6949 6950 6951 6952 6953 6954 6955 6956 6957 6958 6959 6960 6961 6962 6963 6964 6965 6966 6967 6968 6969 6970 6971 6972 6973 6974 6975 6976 6977 6978 6979 6980 6981 6982 6983 6984 6985 6986 6987 6988 6989 6990 6991 6992 6993 6994 6995 6996 6997 6998 6999 7000 7001 7002 7003 7004 7005 7006 7007 7008 7009 7010 7011 7012 7013 7014 7015 7016 7017 7018 7019 7020 7021 7022 7023 7024 7025 7026 7027 7028 7029 7030 7031 7032 7033 7034 7035 7036 7037 7038 7039 7040 7041 7042 7043 7044 7045 7046 7047 7048 7049 7050 7051 7052 7053 7054 7055 7056 7057 7058 7059 7060 7061 7062 7063 7064 7065 7066 7067 7068 7069 7070 7071 7072 7073 7074 7075 7076 7077 7078 7079 7080 7081 7082 7083 7084 7085 7086 7087 7088 7089 7090 7091 7092 7093 7094 7095 7096 7097 7098 7099 7100 7101 7102 7103 7104 7105 7106 7107 7108 7109 7110 7111 7112 7113 7114 7115 7116 7117 7118 7119 7120 7121 7122 7123 7124 7125 7126 7127 7128 7129 7130 7131 7132 7133 7134 7135 7136 7137 7138 7139 7140 7141 7142 7143 7144 7145 7146 7147 7148 7149 7150 7151 7152 7153 7154 7155 7156 7157 7158 7159 7160 7161 7162 7163 7164 7165 7166 7167 7168 7169 7170 7171 7172 7173 7174 7175 7176 7177 7178 7179 7180 7181 7182 7183 7184 7185 7186 7187 7188 7189 7190 7191 7192 7193 7194 7195 7196 7197 7198 7199 7200 7201 7202 7203 7204 7205 7206 7207 7208 7209 7210 7211 7212 7213 7214 7215 7216 7217 7218 7219 7220 7221 7222 7223 7224 7225 7226 7227 7228 7229 7230 7231 7232 7233 7234 7235 7236 7237 7238 7239 7240 7241 7242 7243 7244 7245 7246 7247 7248 7249 7250 7251 7252 7253 7254 7255 7256 7257 7258 7259 7260 7261 7262 7263 7264 7265 7266 7267 7268 7269 7270 7271 7272 7273 7274 7275 7276 7277 7278 7279 7280 7281 7282 7283 7284 7285 7286 7287 7288 7289 7290 7291 7292 7293 7294 7295 7296 7297 7298 7299 7300 7301 7302 7303 7304 7305 7306 7307 7308 7309 7310 7311 7312 7313 7314 7315 7316 7317 7318 7319 7320 7321 7322 7323 7324 7325 7326 7327 7328 7329 7330 7331 7332 7333 7334 7335 7336 7337 7338 7339 7340 7341 7342 7343 7344 7345 7346 7347 7348 7349 7350 7351 7352 7353 7354 7355 7356 7357 7358 7359 7360 7361 7362 7363 7364 7365 7366 7367 7368 7369 7370 7371 7372 7373 7374 7375 7376 7377 7378 7379 7380 7381 7382 7383 7384 7385 7386 7387 7388 7389 7390 7391 7392 7393 7394 7395 7396 7397 7398 7399 7400 7401 7402 7403 7404 7405 7406 7407 7408 7409 7410 7411 7412 7413 7414 7415 7416 7417 7418 7419 7420 7421 7422 7423 7424 7425 7426 7427 7428 7429 7430 7431 7432 7433 7434 7435 7436 7437 7438 7439 7440 7441 7442 7443 7444 7445 7446 7447 7448 7449 7450 7451 7452 7453 7454 7455 7456 7457 7458 7459 7460 7461 7462 7463 7464 7465 7466 7467 7468 7469 7470 7471 7472 7473 7474 7475 7476 7477 7478 7479 7480 7481 7482 7483 7484 7485 7486 7487 7488 7489 7490 7491 7492 7493 7494 7495 7496 7497 7498 7499 7500 7501 7502 7503 7504 7505 7506 7507 7508 7509 7510 7511 7512 7513 7514 7515 7516 7517 7518 7519 7520 7521 7522 7523 7524 7525 7526 7527 7528 7529 7530 7531 7532 7533 7534 7535 7536 7537 7538 7539 7540 7541 7542 7543 7544 7545 7546 7547 7548 7549 7550 7551 7552 7553 7554 7555 7556 7557 7558 7559 7560 7561 7562 7563 7564 7565 7566 7567 7568 7569 7570 7571 7572 7573 7574 7575 7576 7577 7578 7579 7580 7581 7582 7583 7584 7585 7586 7587 7588 7589 7590 7591 7592 7593 7594 7595 7596 7597 7598 7599 7600 7601 7602 7603 7604 7605 7606 7607 7608 7609 7610 7611 7612 7613 7614 7615 7616 7617 7618 7619 7620 7621 7622 7623 7624 7625 7626 7627 7628 7629 7630 7631 7632 7633 7634 7635 7636 7637 7638 7639 7640 7641 7642 7643 7644 7645 7646 7647 7648 7649 7650 7651 7652 7653 7654 7655 7656 7657 7658 7659 7660 7661 7662 7663 7664 7665 7666 7667 7668 7669 7670 7671 7672 7673 7674 7675 7676 7677 7678 7679 7680 7681 7682 7683 7684 7685 7686 7687 7688 7689 7690 7691 7692 7693 7694 7695 7696 7697 7698 7699 7700 7701 7702 7703 7704 7705 7706 7707 7708 7709 7710 7711 7712 7713 7714 7715 7716 7717 7718 7719 7720 7721 7722 7723 7724 7725 7726 7727 7728 7729 7730 7731 7732 7733 7734 7735 7736 7737 7738 7739 7740 7741 7742 7743 7744 7745 7746 7747 7748 7749 7750 7751 7752 7753 7754 7755 7756 7757 7758 7759 7760 7761 7762 7763 7764 7765 7766 7767 7768 7769 7770 7771 7772 7773 7774 7775 7776 7777 7778 7779 7780 7781 7782 7783 7784 7785 7786 7787 7788 7789 7790 7791 7792 7793 7794 7795 7796 7797 7798 7799 7800 7801 7802 7803 7804 7805 7806 7807 7808 7809 7810 7811 7812 7813 7814 7815 7816 7817 7818 7819 7820 7821 7822 7823 7824 7825 7826 7827 7828 7829 7830 7831 7832 7833 7834 7835 7836 7837 7838 7839 7840 7841 7842 7843 7844 7845 7846 7847 7848 7849 7850 7851 7852 7853 7854 7855 7856 7857 7858 7859 7860 7861 7862 7863 7864 7865 7866 7867 7868 7869 7870 7871 7872 7873 7874 7875 7876 7877 7878 7879 7880 7881 7882 7883 7884 7885 7886 7887 7888 7889 7890 7891 7892 7893 7894 7895 7896 7897 7898 7899 7900 7901 7902 7903 7904 7905 7906 7907 7908 7909 7910 7911 7912 7913 7914 7915 7916 7917 7918 7919 7920 7921 7922 7923 7924 7925 7926 7927 7928 7929 7930 7931 7932 7933 7934 7935 7936 7937 7938 7939 7940 7941 7942 7943 7944 7945 7946 7947 7948 7949 7950 7951 7952 7953 7954 7955 7956 7957 7958 7959 7960 7961 7962 7963 7964 7965 7966 7967 7968 7969 7970 7971 7972 7973 7974 7975 7976 7977 7978 7979 7980 7981 7982 7983 7984 7985 7986 7987 7988 7989 7990 7991 7992 7993 7994 7995 7996 7997 7998 7999 8000 8001 8002 8003 8004 8005 8006 8007 8008 8009 8010 8011 8012 8013 8014 8015 8016 8017 8018 8019 8020 8021 8022 8023 8024 8025 8026 8027 8028 8029 8030 8031 8032 8033 8034 8035 8036 8037 8038 8039 8040 8041 8042 8043 8044 8045 8046 8047 8048 8049 8050 8051 8052 8053 8054 8055 8056 8057 8058 8059 8060 8061 8062 8063 8064 8065 8066 8067 8068 8069 8070 8071 8072 8073 8074 8075 8076 8077 8078 8079 8080 8081 8082 8083 8084 8085 8086 8087 8088 8089 8090 8091 8092 8093 8094 8095 8096 8097 8098 8099 8100 8101 8102 8103 8104 8105 8106 8107 8108 8109 8110 8111 8112 8113 8114 8115 8116 8117 8118 8119 8120 8121 8122 8123 8124 8125 8126 8127 8128 8129 8130 8131 8132 8133 8134 8135 8136 8137 8138 8139 8140 8141 8142 8143 8144 8145 8146 8147 8148 8149 8150 8151 8152 8153 8154 8155 8156 8157 8158 8159 8160 8161 8162 8163 8164 8165 8166 8167 8168 8169 8170 8171 8172 8173 8174 8175 8176 8177 8178 8179 8180 8181 8182 8183 8184 8185 8186 8187 8188 8189 8190 8191 8192 8193 8194 8195 8196 8197 8198 8199 8200 8201 8202 8203 8204 8205 8206 8207 8208 8209 8210 8211 8212 8213 8214 8215 8216 8217 8218 8219 8220 8221 8222 8223 8224 8225 8226 8227 8228 8229 8230 8231 8232 8233 8234 8235 8236 8237 8238 8239 8240 8241 8242 8243 8244 8245 8246 8247 8248 8249 8250 8251 8252 8253 8254 8255 8256 8257 8258 8259 8260 8261 8262 8263 8264 8265 8266 8267 8268 8269 8270 8271 8272 8273 8274 8275 8276 8277 8278 8279 8280 8281 8282 8283 8284 8285 8286 8287 8288 8289 8290 8291 8292 8293 8294 8295 8296 8297 8298 8299 8300 8301 8302 8303 8304 8305 8306 8307 8308 8309 8310 8311 8312 8313 8314 8315 8316 8317 8318 8319 8320 8321 8322 8323 8324 8325 8326 8327 8328 8329 8330 8331 8332 8333 8334 8335 8336 8337 8338 8339 8340 8341 8342 8343 8344 8345 8346 8347 8348 8349 8350 8351 8352 8353 8354 8355 8356 8357 8358 8359 8360 8361 8362 8363 8364 8365 8366 8367 8368 8369 8370 8371 8372 8373 8374 8375 8376 8377 8378 8379 8380 8381 8382 8383 8384 8385 8386 8387 8388 8389 8390 8391 8392 8393 8394 8395 8396 8397 8398 8399 8400 8401 8402 8403 8404 8405 8406 8407 8408 8409 8410 8411 8412 8413 8414 8415 8416 8417 8418 8419 8420 8421 8422 8423 8424 8425 8426 8427 8428 8429 8430 8431 8432 8433 8434 8435 8436 8437 8438 8439 8440 8441 8442 8443 8444 8445 8446 8447 8448 8449 8450 8451 8452 8453 8454 8455 8456 8457 8458 8459 8460 8461 8462 8463 8464 8465 8466 8467 8468 8469 8470 8471 8472 8473 8474 8475 8476 8477 8478 8479 8480 8481 8482 8483 8484 8485 8486 8487 8488 8489 8490 8491 8492 8493 8494 8495 8496 8497 8498 8499 8500 8501 8502 8503 8504 8505 8506 8507 8508 8509 8510 8511 8512 8513 8514 8515 8516 8517 8518 8519 8520 8521 8522 8523 8524 8525 8526 8527 8528 8529 8530 8531 8532 8533 8534 8535 8536 8537 8538 8539 8540 8541 8542 8543 8544 8545 8546 8547 8548 8549 8550 8551 8552 8553 8554 8555 8556 8557 8558 8559 8560 8561 8562 8563 8564 8565 8566 8567 8568 8569 8570 8571 8572 8573 8574 8575 8576 8577 8578 8579 8580 8581 8582 8583 8584 8585 8586 8587 8588 8589 8590 8591 8592 8593 8594 8595 8596 8597 8598 8599 8600 8601 8602 8603 8604 8605 8606 8607 8608 8609 8610 8611 8612 8613 8614 8615 8616 8617 8618 8619 8620 8621 8622 8623 8624 8625 8626 8627 8628 8629 8630 8631 8632 8633 8634 8635 8636 8637 8638 8639 8640 8641 8642 8643 8644 8645 8646 8647 8648 8649 8650 8651 8652 8653 8654 8655 8656 8657 8658 8659 8660 8661 8662 8663 8664 8665 8666 8667 8668 8669 8670 8671 8672 8673 8674 8675 8676 8677 8678 8679 8680 8681 8682 8683 8684 8685 8686 8687 8688 8689 8690 8691 8692 8693 8694 8695 8696 8697 8698 8699 8700 8701 8702 8703 8704 8705 8706 8707 8708 8709 8710 8711 8712 8713 8714 8715 8716 8717 8718 8719 8720 8721 8722 8723 8724 8725 8726 8727 8728 8729 8730 8731 8732 8733 8734 8735 8736 8737 8738 8739 8740 8741 8742 8743 8744 8745 8746 8747 8748 8749 8750 8751 8752 8753 8754 8755 8756 8757 8758 8759 8760 8761 8762 8763 8764 8765 8766 8767 8768 8769 8770 8771 8772 8773 8774 8775 8776 8777 8778 8779 8780 8781 8782 8783 8784 8785 8786 8787 8788 8789 8790 8791 8792 8793 8794 8795 8796 8797 8798 8799 8800 8801 8802 8803 8804 8805 8806 8807 8808 8809 8810 8811 8812 8813 8814 8815 8816 8817 8818 8819 8820 8821 8822 8823 8824 8825 8826 8827 8828 8829 8830 8831 8832 8833 8834 8835 8836 8837 8838 8839 8840 8841 8842 8843 8844 8845 8846 8847 8848 8849 8850 8851 8852 8853 8854 8855 8856 8857 8858 8859 8860 8861 8862 8863 8864 8865 8866 8867 8868 8869 8870 8871 8872 8873 8874 8875 8876 8877 8878 8879 8880 8881 8882 8883 8884 8885 8886 8887 8888 8889 8890 8891 8892 8893 8894 8895 8896 8897 8898 8899 8900 8901 8902 8903 8904 8905 8906 8907 8908 8909 8910 8911 8912 8913 8914 8915 8916 8917 8918 8919 8920 8921 8922 8923 8924 8925 8926 8927 8928 8929 8930 8931 8932 8933 8934 8935 8936 8937 8938 8939 8940 8941 8942 8943 8944 8945 8946 8947 8948 8949 8950 8951 8952 8953 8954 8955 8956 8957 8958 8959 8960 8961 8962 8963 8964 8965 8966 8967 8968 8969 8970 8971 8972 8973 8974 8975 8976 8977 8978 8979 8980 8981 8982 8983 8984 8985 8986 8987 8988 8989 8990 8991 8992 8993 8994 8995 8996 8997 8998 8999 9000 9001 9002 9003 9004 9005 9006 9007 9008 9009 9010 9011 9012 9013 9014 9015 9016 9017 9018 9019 9020 9021 9022 9023 9024 9025 9026 9027 9028 9029 9030 9031 9032 9033 9034 9035 9036 9037 9038 9039 9040 9041 9042 9043 9044 9045 9046 9047 9048 9049 9050 9051 9052 9053 9054 9055 9056 9057 9058 9059 9060 9061 9062 9063 9064 9065 9066 9067 9068 9069 9070 9071 9072 9073 9074 9075 9076 9077 9078 9079 9080 9081 9082 9083 9084 9085 9086 9087 9088 9089 9090 9091 9092 9093 9094 9095 9096 9097 9098 9099 9100 9101 9102 9103 9104 9105 9106 9107 9108 9109 9110 9111 9112 9113 9114 9115 9116 9117 9118 9119 9120 9121 9122 9123 9124 9125 9126 9127 9128 9129 9130 9131 9132 9133 9134 9135 9136 9137 9138 9139 9140 9141 9142 9143 9144 9145 9146 9147 9148 9149 9150 9151 9152 9153 9154 9155 9156 9157 9158 9159 9160 9161 9162 9163 9164 9165 9166 9167 9168 9169 9170 9171 9172 9173 9174 9175 9176 9177 9178 9179 9180 9181 9182 9183 9184 9185 9186 9187 9188 9189 9190 9191 9192 9193 9194 9195 9196 9197 9198 9199 9200 9201 9202 9203 9204 9205 9206 9207 9208 9209 9210 9211 9212 9213 9214 9215 9216 9217 9218 9219 9220 9221 9222 9223 9224 9225 9226 9227 9228 9229 9230 9231 9232 9233 9234 9235 9236 9237 9238 9239 9240 9241 9242 9243 9244 9245 9246 9247 9248 9249 9250 9251 9252 9253 9254 9255 9256 9257 9258 9259 9260 9261 9262 9263 9264 9265 9266 9267 9268 9269 9270 9271 9272 9273 9274 9275 9276 9277 9278 9279 9280 9281 9282 9283 9284 9285 9286 9287 9288 9289 9290 9291 9292 9293 9294 9295 9296 9297 9298 9299 9300 9301 9302 9303 9304 9305 9306 9307 9308 9309 9310 9311 9312 9313 9314 9315 9316 9317 9318 9319 9320 9321 9322 9323 9324 9325 9326 9327 9328 9329 9330 9331 9332 9333 9334 9335 9336 9337 9338 9339 9340 9341 9342 9343 9344 9345 9346 9347 9348 9349 9350 9351 9352 9353 9354 9355 9356 9357 9358 9359 9360 9361 9362 9363 9364 9365 9366 9367 9368 9369 9370 9371 9372 9373 9374 9375 9376 9377 9378 9379 9380 9381 9382 9383 9384 9385 9386 9387 9388 9389 9390 9391 9392 9393 9394 9395 9396 9397 9398 9399 9400 9401 9402 9403 9404 9405 9406 9407 9408 9409 9410 9411 9412 9413 9414 9415 9416 9417 9418 9419 9420 9421 9422 9423 9424 9425 9426 9427 9428 9429 9430 9431 9432 9433 9434 9435 9436 9437 9438 9439 9440 9441 9442 9443 9444 9445 9446 9447 9448 9449 9450 9451 9452 9453 9454 9455 9456 9457 9458 9459 9460 9461 9462 9463 9464 9465 9466 9467 9468 9469 9470 9471 9472 9473 9474 9475 9476 9477 9478 9479 9480 9481 9482 9483 9484 9485 9486 9487 9488 9489 9490 9491 9492 9493 9494 9495 9496 9497 9498 9499 9500 9501 9502 9503 9504 9505 9506 9507 9508 9509 9510 9511 9512 9513 9514 9515 9516 9517 9518 9519 9520 9521 9522 9523 9524 9525 9526 9527 9528 9529 9530 9531 9532 9533 9534 9535 9536 9537 9538 9539 9540 9541 9542 9543 9544 9545 9546 9547 9548 9549 9550 9551 9552 9553 9554 9555 9556 9557 9558 9559 9560 9561 9562 9563 9564 9565 9566 9567 9568 9569 9570 9571 9572 9573 9574 9575 9576 9577 9578 9579 9580 9581 9582 9583 9584 9585 9586 9587 9588 9589 9590 9591 9592 9593 9594 9595 9596 9597 9598 9599 9600 9601 9602 9603 9604 9605 9606 9607 9608 9609 9610 9611 9612 9613 9614 9615 9616 9617 9618 9619 9620 9621 9622 9623 9624 9625 9626 9627 9628 9629 9630 9631 9632 9633 9634 9635 9636 9637 9638 9639 9640 9641 9642 9643 9644 9645 9646 9647 9648 9649 9650 9651 9652 9653 9654 9655 9656 9657 9658 9659 9660 9661 9662 9663 9664 9665 9666 9667 9668 9669 9670 9671 9672 9673 9674 9675 9676 9677 9678 9679 9680 9681 9682 9683 9684 9685 9686 9687 9688 9689 9690 9691 9692 9693 9694 9695 9696 9697 9698 9699 9700 9701 9702 9703 9704 9705 9706 9707 9708 9709 9710 9711 9712 9713 9714 9715 9716 9717 9718 9719 9720 9721 9722 9723 9724 9725 9726 9727 9728 9729 9730 9731 9732 9733 9734 9735 9736 9737 9738 9739 9740 9741 9742 9743 9744 9745 9746 9747 9748 9749 9750 9751 9752 9753 9754 9755 9756 9757 9758 9759 9760 9761 9762 9763 9764 9765 9766 9767 9768 9769 9770 9771 9772 9773 9774 9775 9776 9777 9778 9779 9780 9781 9782 9783 9784 9785 9786 9787 9788 9789 9790 9791 9792 9793 9794 9795 9796 9797 9798 9799 9800 9801 9802 9803 9804 9805 9806 9807 9808 9809 9810 9811 9812 9813 9814 9815 9816 9817 9818 9819 9820 9821 9822 9823 9824 9825 9826 9827 9828 9829 9830 9831 9832 9833 9834 9835 9836 9837 9838 9839 9840 9841 9842 9843 9844 9845 9846 9847 9848 9849 9850 9851 9852 9853 9854 9855 9856 9857 9858 9859 9860 9861 9862 9863 9864 9865 9866 9867 9868 9869 9870 9871 9872 9873 9874 9875 9876 9877 9878 9879 9880 9881 9882 9883 9884 9885 9886 9887 9888 9889 9890 9891 9892 9893 9894 9895 9896 9897 9898 9899 9900 9901 9902 9903 9904 9905 9906 9907 9908 9909 9910 9911 9912 9913 9914 9915 9916 9917 9918 9919 9920 9921 9922 9923 9924 9925 9926 9927 9928 9929 9930 9931 9932 9933 9934 9935 9936 9937 9938 9939 9940 9941 9942 9943 9944 9945 9946 9947 9948 9949 9950 9951 9952 9953 9954 9955 9956 9957 9958 9959 9960 9961 9962 9963 9964 9965 9966 9967 9968 9969 9970 9971 9972 9973 9974 9975 9976 9977 9978 9979 9980 9981 9982 9983 9984 9985 9986 9987 9988 9989 9990 9991 9992 9993 9994 9995 9996 9997 9998 9999 10000 10001 10002 10003 10004 10005 10006 10007 10008 10009 10010 10011 10012 10013 10014 10015 10016 10017 10018 10019 10020 10021 10022 10023 10024 10025 10026 10027 10028 10029 10030 10031 10032 10033 10034 10035 10036 10037 10038 10039 10040 10041 10042 10043 10044 10045 10046 10047 10048 10049 10050 10051 10052 10053 10054 10055 10056 10057 10058 10059 10060 10061 10062 10063 10064 10065 10066 10067 10068 10069 10070 10071 10072 10073 10074 10075 10076 10077 10078 10079 10080 10081 10082 10083 10084 10085 10086 10087 10088 10089 10090 10091 10092 10093 10094 10095 10096 10097 10098 10099 10100 10101 10102 10103 10104 10105 10106 10107 10108 10109 10110 10111 10112 10113 10114 10115 10116 10117 10118 10119 10120 10121 10122 10123 10124 10125 10126 10127 10128 10129 10130 10131 10132 10133 10134 10135 10136 10137 10138 10139 10140 10141 10142 10143 10144 10145 10146 10147 10148 10149 10150 10151 10152 10153 10154 10155 10156 10157 10158 10159 10160 10161 10162 10163 10164 10165 10166 10167 10168 10169 10170 10171 10172 10173 10174 10175 10176 10177 10178 10179 10180 10181 10182 10183 10184 10185 10186 10187 10188 10189 10190 10191 10192 10193 10194 10195 10196 10197 10198 10199 10200 10201 10202 10203 10204 10205 10206 10207 10208 10209 10210 10211 10212 10213 10214 10215 10216 10217 10218 10219 10220 10221 10222 10223 10224 10225 10226 10227 10228 10229 10230 10231 10232 10233 10234 10235 10236 10237 10238 10239 10240 10241 10242 10243 10244 10245 10246 10247 10248 10249 10250 10251 10252 10253 10254 10255 10256 10257 10258 10259 10260 10261 10262 10263 10264 10265 10266 10267 10268 10269 10270 10271 10272 10273 10274 10275 10276 10277 10278 10279 10280 10281 10282 10283 10284 10285 10286 10287 10288 10289 10290 10291 10292 10293 10294 10295 10296 10297 10298 10299 10300 10301 10302 10303 10304 10305 10306 10307 10308 10309 10310 10311 10312 10313 10314 10315 10316 10317 10318 10319 10320 10321 10322 10323 10324 10325 10326 10327 10328 10329 10330 10331 10332 10333 10334 10335 10336 10337 10338 10339 10340 10341 10342 10343 10344 10345 10346 10347 10348 10349 10350 10351 10352 10353 10354 10355 10356 10357 10358 10359 10360 10361 10362 10363 10364 10365 10366 10367 10368 10369 10370 10371 10372 10373 10374 10375 10376 10377 10378 10379 10380 10381 10382 10383 10384 10385 10386 10387 10388 10389 10390 10391 10392 10393 10394 10395 10396 10397 10398 10399 10400 10401 10402 10403 10404 10405 10406 10407 10408 10409 10410 10411 10412 10413 10414 10415 10416 10417 10418 10419 10420 10421 10422 10423 10424 10425 10426 10427 10428 10429 10430 10431 10432 10433 10434 10435 10436 10437 10438 10439 10440 10441 10442 10443 10444 10445 10446 10447 10448 10449 10450 10451 10452 10453 10454 10455 10456 10457 10458 10459 10460 10461 10462 10463 10464 10465 10466 10467 10468 10469 10470 10471 10472 10473 10474 10475 10476 10477 10478 10479 10480 10481 10482 10483 10484 10485 10486 10487 10488 10489 10490 10491 10492 10493 10494 10495 10496 10497 10498 10499 10500 10501 10502 10503 10504 10505 10506 10507 10508 10509 10510 10511 10512 10513 10514 10515 10516 10517 10518 10519 10520 10521 10522 10523 10524 10525 10526 10527 10528 10529 10530 10531 10532 10533 10534 10535 10536 10537 10538 10539 10540 10541 10542 10543 10544 10545 10546 10547 10548 10549 10550 10551 10552 10553 10554 10555 10556 10557 10558 10559 10560 10561 10562 10563 10564 10565 10566 10567 10568 10569 10570 10571 10572 10573 10574 10575 10576 10577 10578 10579 10580 10581 10582 10583 10584 10585 10586 10587 10588 10589 10590 10591 10592 10593 10594 10595 10596 10597 10598 10599 10600 10601 10602 10603 10604 10605 10606 10607 10608 10609 10610 10611 10612 10613 10614 10615 10616 10617 10618 10619 10620 10621 10622 10623 10624 10625 10626 10627 10628 10629 10630 10631 10632 10633 10634 10635 10636 10637 10638 10639 10640 10641 10642 10643 10644 10645 10646 10647 10648 10649 10650 10651 10652 10653 10654 10655 10656 10657 10658 10659 10660 10661 10662 10663 10664 10665 10666 10667 10668 10669 10670 10671 10672 10673 10674 10675 10676 10677 10678 10679 10680 10681 10682 10683 10684 10685 10686 10687 10688 10689 10690 10691 10692 10693 10694 10695 10696 10697 10698 10699 10700 10701 10702 10703 10704 10705 10706 10707 10708 10709 10710 10711 10712 10713 10714 10715 10716 10717 10718 10719 10720 10721 10722 10723 10724 10725 10726 10727 10728 10729 10730 10731 10732 10733 10734 10735 10736 10737 10738 10739 10740 10741 10742 10743 10744 10745 10746 10747 10748 10749 10750 10751 10752 10753 10754 10755 10756 10757 10758 10759 10760 10761 10762 10763 10764 10765 10766 10767 10768 10769 10770 10771 10772 10773 10774 10775 10776 10777 10778 10779 10780 10781 10782 10783 10784 10785 10786 10787 10788 10789 10790 10791 10792 10793 10794 10795 10796 10797 10798 10799 10800 10801 10802 10803 10804 10805 10806 10807 10808 10809 10810 10811 10812 10813 10814 10815 10816 10817 10818 10819 10820 10821 10822 10823 10824 10825 10826 10827 10828 10829 10830 10831 10832 10833 10834 10835 10836 10837 10838 10839 10840 10841 10842 10843 10844 10845 10846 10847 10848 10849 10850 10851 10852 10853 10854 10855 10856 10857 10858 10859 10860 10861 10862 10863 10864 10865 10866 10867 10868 10869 10870 10871 10872 10873 10874 10875 10876 10877 10878 10879 10880 10881 10882 10883 10884 10885 10886 10887 10888 10889 10890 10891 10892 10893 10894 10895 10896 10897 10898 10899 10900 10901 10902 10903 10904 10905 10906 10907 10908 10909 10910 10911 10912 10913 10914 10915 10916 10917 10918 10919 10920 10921 10922 10923 10924 10925 10926 10927 10928 10929 10930 10931 10932 10933 10934 10935 10936 10937 10938 10939 10940 10941 10942 10943 10944 10945 10946 10947 10948 10949 10950 10951 10952 10953 10954 10955 10956 10957 10958 10959 10960 10961 10962 10963 10964 10965 10966 10967 10968 10969 10970 10971 10972 10973 10974 10975 10976 10977 10978 10979 10980 10981 10982 10983 10984 10985 10986 10987 10988 10989 10990 10991 10992 10993 10994 10995 10996 10997 10998 10999 11000 11001 11002 11003 11004 11005 11006 11007 11008 11009 11010 11011 11012 11013 11014 11015 11016 11017 11018 11019 11020 11021 11022 11023 11024 11025 11026 11027 11028 11029 11030 11031 11032 11033 11034 11035 11036 11037 11038 11039 11040 11041 11042 11043 11044 11045 11046 11047 11048 11049 11050 11051 11052 11053 11054 11055 11056 11057 11058 11059 11060 11061 11062 11063 11064 11065 11066 11067 11068 11069 11070 11071 11072 11073 11074 11075 11076 11077 11078 11079 11080 11081 11082 11083 11084 11085 11086 11087 11088 11089 11090 11091 11092 11093 11094 11095 11096 11097 11098 11099 11100 11101 11102 11103 11104 11105 11106 11107 11108 11109 11110 11111 11112 11113 11114 11115 11116 11117 11118 11119 11120 11121 11122 11123 11124 11125 11126 11127 11128 11129 11130 11131 11132 11133 11134 11135 11136 11137 11138 11139 11140 11141 11142 11143 11144 11145 11146 11147 11148 11149 11150 11151 11152 11153 11154 11155 11156 11157 11158 11159 11160 11161 11162 11163 11164 11165 11166 11167 11168 11169 11170 11171 11172 11173 11174 11175 11176 11177 11178 11179 11180 11181 11182 11183 11184 11185 11186 11187 11188 11189 11190 11191 11192 11193 11194 11195 11196 11197 11198 11199 11200 11201 11202 11203 11204 11205 11206 11207 11208 11209 11210 11211 11212 11213 11214 11215 11216 11217 11218 11219 11220 11221 11222 11223 11224 11225 11226 11227 11228 11229 11230 11231 11232 11233 11234 11235 11236 11237 11238 11239 11240 11241 11242 11243 11244 11245 11246 11247 11248 11249 11250 11251 11252 11253 11254 11255 11256 11257 11258 11259 11260 11261 11262 11263 11264 11265 11266 11267 11268 11269 11270 11271 11272 11273 11274 11275 11276 11277 11278 11279 11280 11281 11282 11283 11284 11285 11286 11287 11288 11289 11290 11291 11292 11293 11294 11295 11296 11297 11298 11299 11300 11301 11302 11303 11304 11305 11306 11307 11308 11309 11310 11311 11312 11313 11314 11315 11316 11317 11318 11319 11320 11321 11322 11323 11324 11325 11326 11327 11328 11329 11330 11331 11332 11333 11334 11335 11336 11337 11338 11339 11340 11341 11342 11343 11344 11345 11346 11347 11348 11349 11350 11351 11352 11353 11354 11355 11356 11357 11358 11359 11360 11361 11362 11363 11364 11365 11366 11367 11368 11369 11370 11371 11372 11373 11374 11375 11376 11377 11378 11379 11380 11381 11382 11383 11384 11385 11386 11387 11388 11389 11390 11391 11392 11393 11394 11395 11396 11397 11398 11399 11400 11401 11402 11403 11404 11405 11406 11407 11408 11409 11410 11411 11412 11413 11414 11415 11416 11417 11418 11419 11420 11421 11422 11423 11424 11425 11426 11427 11428 11429 11430 11431 11432 11433 11434 11435 11436 11437 11438 11439 11440 11441 11442 11443 11444 11445 11446 11447 11448 11449 11450 11451 11452 11453 11454 11455 11456 11457 11458 11459 11460 11461 11462 11463 11464 11465 11466 11467 11468 11469 11470 11471 11472 11473 11474 11475 11476 11477 11478 11479 11480 11481 11482 11483 11484 11485 11486 11487 11488 11489 11490 11491 11492 11493 11494 11495 11496 11497 11498 11499 11500 11501 11502 11503 11504 11505 11506 11507 11508 11509 11510 11511 11512 11513 11514 11515 11516 11517 11518 11519 11520 11521 11522 11523 11524 11525 11526 11527 11528 11529 11530 11531 11532 11533 11534 11535 11536 11537 11538 11539 11540 11541 11542 11543 11544 11545 11546 11547 11548 11549 11550 11551 11552 11553 11554 11555 11556 11557 11558 11559 11560 11561 11562 11563 11564 11565 11566 11567 11568 11569 11570 11571 11572 11573 11574 11575 11576 11577 11578 11579 11580 11581 11582 11583 11584 11585 11586 11587 11588 11589 11590 11591 11592 11593 11594 11595 11596 11597 11598 11599 11600 11601 11602 11603 11604 11605 11606 11607 11608 11609 11610 11611 11612 11613 11614 11615 11616 11617 11618 11619 11620 11621 11622 11623 11624 11625 11626 11627 11628 11629 11630 11631 11632 11633 11634 11635 11636 11637 11638 11639 11640 11641 11642 11643 11644 11645 11646 11647 11648 11649 11650 11651 11652 11653 11654 11655 11656 11657 11658 11659 11660 11661 11662 11663 11664 11665 11666 11667 11668 11669 11670 11671 11672 11673 11674 11675 11676 11677 11678 11679 11680 11681 11682 11683 11684 11685 11686 11687 11688 11689 11690 11691 11692 11693 11694 11695 11696 11697 11698 11699 11700 11701 11702 11703 11704 11705 11706 11707 11708 11709 11710 11711 11712 11713 11714 11715 11716 11717 11718 11719 11720 11721 11722 11723 11724 11725 11726 11727 11728 11729 11730 11731 11732 11733 11734 11735 11736 11737 11738 11739 11740 11741 11742 11743 11744 11745 11746 11747 11748 11749 11750 11751 11752 11753 11754 11755 11756 11757 11758 11759 11760 11761 11762 11763 11764 11765 11766 11767 11768 11769 11770 11771 11772 11773 11774 11775 11776 11777 11778 11779 11780 11781 11782 11783 11784 11785 11786 11787 11788 11789 11790 11791 11792 11793 11794 11795 11796 11797 11798 11799 11800 11801 11802 11803 11804 11805 11806 11807 11808 11809 11810 11811 11812 11813 11814 11815 11816 11817 11818 11819 11820 11821 11822 11823 11824 11825 11826 11827 11828 11829 11830 11831 11832 11833 11834 11835 11836 11837 11838 11839 11840 11841 11842 11843 11844 11845 11846 11847 11848 11849 11850 11851 11852 11853 11854 11855 11856 11857 11858 11859 11860 11861 11862 11863 11864 11865 11866 11867 11868 11869 11870 11871 11872 11873 11874 11875 11876 11877 11878 11879 11880 11881 11882 11883 11884 11885 11886 11887 11888 11889 11890 11891 11892 11893 11894 11895 11896 11897 11898 11899 11900 11901 11902 11903 11904 11905 11906 11907 11908 11909 11910 11911 11912 11913 11914 11915 11916 11917 11918 11919 11920 11921 11922 11923 11924 11925 11926 11927 11928 11929 11930 11931 11932 11933 11934 11935 11936 11937 11938 11939 11940 11941 11942 11943 11944 11945 11946 11947 11948 11949 11950 11951 11952 11953 11954 11955 11956 11957 11958 11959 11960 11961 11962 11963 11964 11965 11966 11967 11968 11969 11970 11971 11972 11973 11974 11975 11976 11977 11978 11979 11980 11981 11982 11983 11984 11985 11986 11987 11988 11989 11990 11991 11992 11993 11994 11995 11996 11997 11998 11999 12000 12001 12002 12003 12004 12005 12006 12007 12008 12009 12010 12011 12012 12013 12014 12015 12016 12017 12018 12019 12020 12021 12022 12023 12024 12025 12026 12027 12028 12029 12030 12031 12032 12033 12034 12035 12036 12037 12038 12039 12040 12041 12042 12043 12044 12045 12046 12047 12048 12049 12050 12051 12052 12053 12054 12055 12056 12057 12058 12059 12060 12061 12062 12063 12064 12065 12066 12067 12068 12069 12070 12071 12072 12073 12074 12075 12076 12077 12078 12079 12080 12081 12082 12083 12084 12085 12086 12087 12088 12089 12090 12091 12092 12093 12094 12095 12096 12097 12098 12099 12100 12101 12102 12103 12104 12105 12106 12107 12108 12109 12110 12111 12112 12113 12114 12115 12116 12117 12118 12119 12120 12121 12122 12123 12124 12125 12126 12127 12128 12129 12130 12131 12132 12133 12134 12135 12136 12137 12138 12139 12140 12141 12142 12143 12144 12145 12146 12147 12148 12149 12150 12151 12152 12153 12154 12155 12156 12157 12158 12159 12160 12161 12162 12163 12164 12165 12166 12167 12168 12169 12170 12171 12172 12173 12174 12175 12176 12177 12178 12179 12180 12181 12182 12183 12184 12185 12186 12187 12188 12189 12190 12191 12192 12193 12194 12195 12196 12197 12198 12199 12200 12201 12202 12203 12204 12205 12206 12207 12208 12209 12210 12211 12212 12213 12214 12215 12216 12217 12218 12219 12220 12221 12222 12223 12224 12225 12226 12227 12228 12229 12230 12231 12232 12233 12234 12235 12236 12237 12238 12239 12240 12241 12242 12243 12244 12245 12246 12247 12248 12249 12250 12251 12252 12253 12254 12255 12256 12257 12258 12259 12260 12261 12262 12263 12264 12265 12266 12267 12268 12269 12270 12271 12272 12273 12274 12275 12276 12277 12278 12279 12280 12281 12282 12283 12284 12285 12286 12287 12288 12289 12290 12291 12292 12293 12294 12295 12296 12297 12298 12299 12300 12301 12302 12303 12304 12305 12306 12307 12308 12309 12310 12311 12312 12313 12314 12315 12316 12317 12318 12319 12320 12321 12322 12323 12324 12325 12326 12327 12328 12329 12330 12331 12332 12333 12334 12335 12336 12337 12338 12339 12340 12341 12342 12343 12344 12345 12346 12347 12348 12349 12350 12351 12352 12353 12354 12355 12356 12357 12358 12359 12360 12361 12362 12363 12364 12365 12366 12367 12368 12369 12370 12371 12372 12373 12374 12375 12376 12377 12378 12379 12380 12381 12382 12383 12384 12385 12386 12387 12388 12389 12390 12391 12392 12393 12394 12395 12396 12397 12398 12399 12400 12401 12402 12403 12404 12405 12406 12407 12408 12409 12410 12411 12412 12413 12414 12415 12416 12417 12418 12419 12420 12421 12422 12423 12424 12425 12426 12427 12428 12429 12430 12431 12432 12433 12434 12435 12436 12437 12438 12439 12440 12441 12442 12443 12444 12445 12446 12447 12448 12449 12450 12451 12452 12453 12454 12455 12456 12457 12458 12459 12460 12461 12462 12463 12464 12465 12466 12467 12468 12469 12470 12471 12472 12473 12474 12475 12476 12477 12478 12479 12480 12481 12482 12483 12484 12485 12486 12487 12488 12489 12490 12491 12492 12493 12494 12495 12496 12497 12498 12499 12500 12501 12502 12503 12504 12505 12506 12507 12508 12509 12510 12511 12512 12513 12514 12515 12516 12517 12518 12519 12520 12521 12522 12523 12524 12525 12526 12527 12528 12529 12530 12531 12532 12533 12534 12535 12536 12537 12538 12539 12540 12541 12542 12543 12544 12545 12546 12547 12548 12549 12550 12551 12552 12553 12554 12555 12556 12557 12558 12559 12560 12561 12562 12563 12564 12565 12566 12567 12568 12569 12570 12571 12572 12573 12574 12575 12576 12577 12578 12579 12580 12581 12582 12583 12584 12585 12586 12587 12588 12589 12590 12591 12592 12593 12594 12595 12596 12597 12598 12599 12600 12601 12602 12603 12604 12605 12606 12607 12608 12609 12610 12611 12612 12613 12614 12615 12616 12617 12618 12619 12620 12621 12622 12623 12624 12625 12626 12627 12628 12629 12630 12631 12632 12633 12634 12635 12636 12637 12638 12639 12640 12641 12642 12643 12644 12645 12646 12647 12648 12649 12650 12651 12652 12653 12654 12655 12656 12657 12658 12659 12660 12661 12662 12663 12664 12665 12666 12667 12668 12669 12670 12671 12672 12673 12674 12675 12676 12677 12678 12679 12680 12681 12682 12683 12684 12685 12686 12687 12688 12689 12690 12691 12692 12693 12694 12695 12696 12697 12698 12699 12700 12701 12702 12703 12704 12705 12706 12707 12708 12709 12710 12711 12712 12713 12714 12715 12716 12717 12718 12719 12720 12721 12722 12723 12724 12725 12726 12727 12728 12729 12730 12731 12732 12733 12734 12735 12736 12737 12738 12739 12740 12741 12742 12743 12744 12745 12746 12747 12748 12749 12750 12751 12752 12753 12754 12755 12756 12757 12758 12759 12760 12761 12762 12763 12764 12765 12766 12767 12768 12769 12770 12771 12772 12773 12774 12775 12776 12777 12778 12779 12780 12781 12782 12783 12784 12785 12786 12787 12788 12789 12790 12791 12792 12793 12794 12795 12796 12797 12798 12799 12800 12801 12802 12803 12804 12805 12806 12807 12808 12809 12810 12811 12812 12813 12814 12815 12816 12817 12818 12819 12820 12821 12822 12823 12824 12825 12826 12827 12828 12829 12830 12831 12832 12833 12834 12835 12836 12837 12838 12839 12840 12841 12842 12843 12844 12845 12846 12847 12848 12849 12850 12851 12852 12853 12854 12855 12856 12857 12858 12859 12860 12861 12862 12863 12864 12865 12866 12867 12868 12869 12870 12871 12872 12873 12874 12875 12876 12877 12878 12879 12880 12881 12882 12883 12884 12885 12886 12887 12888 12889 12890 12891 12892 12893 12894 12895 12896 12897 12898 12899 12900 12901 12902 12903 12904 12905 12906 12907 12908 12909 12910 12911 12912 12913 12914 12915 12916 12917 12918 12919 12920 12921 12922 12923 12924 12925 12926 12927 12928 12929 12930 12931 12932 12933 12934 12935 12936 12937 12938 12939 12940 12941 12942 12943 12944 12945 12946 12947 12948 12949 12950 12951 12952 12953 12954 12955 12956 12957 12958 12959 12960 12961 12962 12963 12964 12965 12966 12967 12968 12969 12970 12971 12972 12973 12974 12975 12976 12977 12978 12979 12980 12981 12982 12983 12984 12985 12986 12987 12988 12989 12990 12991 12992 12993 12994 12995 12996 12997 12998 12999 13000 13001 13002 13003 13004 13005 13006 13007 13008 13009 13010 13011 13012 13013 13014 13015 13016 13017 13018 13019 13020 13021 13022 13023 13024 13025 13026 13027 13028 13029 13030 13031 13032 13033 13034 13035 13036 13037 13038 13039 13040 13041 13042 13043 13044 13045 13046 13047 13048 13049 13050 13051 13052 13053 13054 13055 13056 13057 13058 13059 13060 13061 13062 13063 13064 13065 13066 13067 13068 13069 13070 13071 13072 13073 13074 13075 13076 13077 13078 13079 13080 13081 13082 13083 13084 13085 13086 13087 13088 13089 13090 13091 13092 13093 13094 13095 13096 13097 13098 13099 13100 13101 13102 13103 13104 13105 13106 13107 13108 13109 13110 13111 13112 13113 13114 13115 13116 13117 13118 13119 13120 13121 13122 13123 13124 13125 13126 13127 13128 13129 13130 13131 13132 13133 13134 13135 13136 13137 13138 13139 13140 13141 13142 13143 13144 13145 13146 13147 13148 13149 13150 13151 13152 13153 13154 13155 13156 13157 13158 13159 13160 13161 13162 13163 13164 13165 13166 13167 13168 13169 13170 13171 13172 13173 13174 13175 13176 13177 13178 13179 13180 13181 13182 13183 13184 13185 13186 13187 13188 13189 13190 13191 13192 13193 13194 13195 13196 13197 13198 13199 13200 13201 13202 13203 13204 13205 13206 13207 13208 13209 13210 13211 13212 13213 13214 13215 13216 13217 13218 13219 13220 13221 13222 13223 13224 13225 13226 13227 13228 13229 13230 13231 13232 13233 13234 13235 13236 13237 13238 13239 13240 13241 13242 13243 13244 13245 13246 13247 13248 13249 13250 13251 13252 13253 13254 13255 13256 13257 13258 13259 13260 13261 13262 13263 13264 13265 13266 13267 13268 13269 13270 13271 13272 13273 13274 13275 13276 13277 13278 13279 13280 13281 13282 13283 13284 13285 13286 13287 13288 13289 13290 13291 13292 13293 13294 13295 13296 13297 13298 13299 13300 13301 13302 13303 13304 13305 13306 13307 13308 13309 13310 13311 13312 13313 13314 13315 13316 13317 13318 13319 13320 13321 13322 13323 13324 13325 13326 13327 13328 13329 13330 13331 13332 13333 13334 13335 13336 13337 13338 13339 13340 13341 13342 13343 13344 13345 13346 13347 13348 13349 13350 13351 13352 13353 13354 13355 13356 13357 13358 13359 13360 13361 13362 13363 13364 13365 13366 13367 13368 13369 13370 13371 13372 13373 13374 13375 13376 13377 13378 13379 13380 13381 13382 13383 13384 13385 13386 13387 13388 13389 13390 13391 13392 13393 13394 13395 13396 13397 13398 13399 13400 13401 13402 13403 13404 13405 13406 13407 13408 13409 13410 13411 13412 13413 13414 13415 13416 13417 13418 13419 13420 13421 13422 13423 13424 13425 13426 13427 13428 13429 13430 13431 13432 13433 13434 13435 13436 13437 13438 13439 13440 13441 13442 13443 13444 13445 13446 13447 13448 13449 13450 13451 13452 13453 13454 13455 13456 13457 13458 13459 13460 13461 13462 13463 13464 13465 13466 13467 13468 13469 13470 13471 13472 13473 13474 13475 13476 13477 13478 13479 13480 13481 13482 13483 13484 13485 13486 13487 13488 13489 13490 13491 13492 13493 13494 13495 13496 13497 13498 13499 13500 13501 13502 13503 13504 13505 13506 13507 13508 13509 13510 13511 13512 13513 13514 13515 13516 13517 13518 13519 13520 13521 13522 13523 13524 13525 13526 13527 13528 13529 13530 13531 13532 13533 13534 13535 13536 13537 13538 13539 13540 13541 13542 13543 13544 13545 13546 13547 13548 13549 13550 13551 13552 13553 13554 13555 13556 13557 13558 13559 13560 13561 13562 13563 13564 13565 13566 13567 13568 13569 13570 13571 13572 13573 13574 13575 13576 13577 13578 13579 13580 13581 13582 13583 13584 13585 13586 13587 13588 13589 13590 13591 13592 13593 13594 13595 13596 13597 13598 13599 13600 13601 13602 13603 13604 13605 13606 13607 13608 13609 13610 13611 13612 13613 13614 13615 13616 13617 13618 13619 13620 13621 13622 13623 13624 13625 13626 13627 13628 13629 13630 13631 13632 13633 13634 13635 13636 13637 13638 13639 13640 13641 13642 13643 13644 13645 13646 13647 13648 13649 13650 13651 13652 13653 13654 13655 13656 13657 13658 13659 13660 13661 13662 13663 13664 13665 13666 13667 13668 13669 13670 13671 13672 13673 13674 13675 13676 13677 13678 13679 13680 13681 13682 13683 13684 13685 13686 13687 13688 13689 13690 13691 13692 13693 13694 13695 13696 13697 13698 13699 13700 13701 13702 13703 13704 13705 13706 13707 13708 13709 13710 13711 13712 13713 13714 13715 13716 13717 13718 13719 13720 13721 13722 13723 13724 13725 13726 13727 13728 13729 13730 13731 13732 13733 13734 13735 13736 13737 13738 13739 13740 13741 13742 13743 13744 13745 13746 13747 13748 13749 13750 13751 13752 13753 13754 13755 13756 13757 13758 13759 13760 13761 13762 13763 13764 13765 13766 13767 13768 13769 13770 13771 13772 13773 13774 13775 13776 13777 13778 13779 13780 13781 13782 13783 13784 13785 13786 13787 13788 13789 13790 13791 13792 13793 13794 13795 13796 13797 13798 13799 13800 13801 13802 13803 13804 13805 13806 13807 13808 13809 13810 13811 13812 13813 13814 13815 13816 13817 13818 13819 13820 13821 13822 13823 13824 13825 13826 13827 13828 13829 13830 13831 13832 13833 13834 13835 13836 13837 13838 13839 13840 13841 13842 13843 13844 13845 13846 13847 13848 13849 13850 13851 13852 13853 13854 13855 13856 13857 13858 13859 13860 13861 13862 13863 13864 13865 13866 13867 13868 13869 13870 13871 13872 13873 13874 13875 13876 13877 13878 13879 13880 13881 13882 13883 13884 13885 13886 13887 13888 13889 13890 13891 13892 13893 13894 13895 13896 13897 13898 13899 13900 13901 13902 13903 13904 13905 13906 13907 13908 13909 13910 13911 13912 13913 13914 13915 13916 13917 13918 13919 13920 13921 13922 13923 13924 13925 13926 13927 13928 13929 13930 13931 13932 13933 13934 13935 13936 13937 13938 13939 13940 13941 13942 13943 13944 13945 13946 13947 13948 13949 13950 13951 13952 13953 13954 13955 13956 13957 13958 13959 13960 13961 13962 13963 13964 13965 13966 13967 13968 13969 13970 13971 13972 13973 13974 13975 13976 13977 13978 13979 13980 13981 13982 13983 13984 13985 13986 13987 13988 13989 13990 13991 13992 13993 13994 13995 13996 13997 13998 13999 14000 14001 14002 14003 14004 14005 14006 14007 14008 14009 14010 14011 14012 14013 14014 14015 14016 14017 14018 14019 14020 14021 14022 14023 14024 14025 14026 14027 14028 14029 14030 14031 14032 14033 14034 14035 14036 14037 14038 14039 14040 14041 14042 14043 14044 14045 14046 14047 14048 14049 14050 14051 14052 14053 14054 14055 14056 14057 14058 14059 14060 14061 14062 14063 14064 14065 14066 14067 14068 14069 14070 14071 14072 14073 14074 14075 14076 14077 14078 14079 14080 14081 14082 14083 14084 14085 14086 14087 14088 14089 14090 14091 14092 14093 14094 14095 14096 14097 14098 14099 14100 14101 14102 14103 14104 14105 14106 14107 14108 14109 14110 14111 14112 14113 14114 14115 14116 14117 14118 14119 14120 14121 14122 14123 14124 14125 14126 14127 14128 14129 14130 14131 14132 14133 14134 14135 14136 14137 14138 14139 14140 14141 14142 14143 14144 14145 14146 14147 14148 14149 14150 14151 14152 14153 14154 14155 14156 14157 14158 14159 14160 14161 14162 14163 14164 14165 14166 14167 14168 14169 14170 14171 14172 14173 14174 14175 14176 14177 14178 14179 14180 14181 14182 14183 14184 14185 14186 14187 14188 14189 14190 14191 14192 14193 14194 14195 14196 14197 14198 14199 14200 14201 14202 14203 14204 14205 14206 14207 14208 14209 14210 14211 14212 14213 14214 14215 14216 14217 14218 14219 14220 14221 14222 14223 14224 14225 14226 14227 14228 14229 14230 14231 14232 14233 14234 14235 14236 14237 14238 14239 14240 14241 14242 14243 14244 14245 14246 14247 14248 14249 14250 14251 14252 14253 14254 14255 14256 14257 14258 14259 14260 14261 14262 14263 14264 14265 14266 14267 14268 14269 14270 14271 14272 14273 14274 14275 14276 14277 14278 14279 14280 14281 14282 14283 14284 14285 14286 14287 14288 14289 14290 14291 14292 14293 14294 14295 14296 14297 14298 14299 14300 14301 14302 14303 14304 14305 14306 14307 14308 14309 14310 14311 14312 14313 14314 14315 14316 14317 14318 14319 14320 14321 14322 14323 14324 14325 14326 14327 14328 14329 14330 14331 14332 14333 14334 14335 14336 14337 14338 14339 14340 14341 14342 14343 14344 14345 14346 14347 14348 14349 14350 14351 14352 14353 14354 14355 14356 14357 14358 14359 14360 14361 14362 14363 14364 14365 14366 14367 14368 14369 14370 14371 14372 14373 14374 14375 14376 14377 14378 14379 14380 14381 14382 14383 14384 14385 14386 14387 14388 14389 14390 14391 14392 14393 14394 14395 14396 14397 14398 14399 14400 14401 14402 14403 14404 14405 14406 14407 14408 14409 14410 14411 14412 14413 14414 14415 14416 14417 14418 14419 14420 14421 14422 14423 14424 14425 14426 14427 14428 14429 14430 14431 14432 14433 14434 14435 14436 14437 14438 14439 14440 14441 14442 14443 14444 14445 14446 14447 14448 14449 14450 14451 14452 14453 14454 14455 14456 14457 14458 14459 14460 14461 14462 14463 14464 14465 14466 14467 14468 14469 14470 14471 14472 14473 14474 14475 14476 14477 14478 14479 14480 14481 14482 14483 14484 14485 14486 14487 14488 14489 14490 14491 14492 14493 14494 14495 14496 14497 14498 14499 14500 14501 14502 14503 14504 14505 14506 14507 14508 14509 14510 14511 14512 14513 14514 14515 14516 14517 14518 14519 14520 14521 14522 14523 14524 14525 14526 14527 14528 14529 14530 14531 14532 14533 14534 14535 14536 14537 14538 14539 14540 14541 14542 14543 14544 14545 14546 14547 14548 14549 14550 14551 14552 14553 14554 14555 14556 14557 14558 14559 14560 14561 14562 14563 14564 14565 14566 14567 14568 14569 14570 14571 14572 14573 14574 14575 14576 14577 14578 14579 14580 14581 14582 14583 14584 14585 14586 14587 14588 14589 14590 14591 14592 14593 14594 14595 14596 14597 14598 14599 14600 14601 14602 14603 14604 14605 14606 14607 14608 14609 14610 14611 14612 14613 14614 14615 14616 14617 14618 14619 14620 14621 14622 14623 14624 14625 14626 14627 14628 14629 14630 14631 14632 14633 14634 14635 14636 14637 14638 14639 14640 14641 14642 14643 14644 14645 14646 14647 14648 14649 14650 14651 14652 14653 14654 14655 14656 14657 14658 14659 14660 14661 14662 14663 14664 14665 14666 14667 14668 14669 14670 14671 14672 14673 14674 14675 14676 14677 14678 14679 14680 14681 14682 14683 14684 14685 14686 14687 14688 14689 14690 14691 14692 14693 14694 14695 14696 14697 14698 14699 14700 14701 14702 14703 14704 14705 14706 14707 14708 14709 14710 14711 14712 14713 14714 14715 14716 14717 14718 14719 14720 14721 14722 14723 14724 14725 14726 14727 14728 14729 14730 14731 14732 14733 14734 14735 14736 14737 14738 14739 14740 14741 14742 14743 14744 14745 14746 14747 14748 14749 14750 14751 14752 14753 14754 14755 14756 14757 14758 14759 14760 14761 14762 14763 14764 14765 14766 14767 14768 14769 14770 14771 14772 14773 14774 14775 14776 14777 14778 14779 14780 14781 14782 14783 14784 14785 14786 14787 14788 14789 14790 14791 14792 14793 14794 14795 14796 14797 14798 14799 14800 14801 14802 14803 14804 14805 14806 14807 14808 14809 14810 14811 14812 14813 14814 14815 14816 14817 14818 14819 14820 14821 14822 14823 14824 14825 14826 14827 14828 14829 14830 14831 14832 14833 14834 14835 14836 14837 14838 14839 14840 14841 14842 14843 14844 14845 14846 14847 14848 14849 14850 14851 14852 14853 14854 14855 14856 14857 14858 14859 14860 14861 14862 14863 14864 14865 14866 14867 14868 14869 14870 14871 14872 14873 14874 14875 14876 14877 14878 14879 14880 14881 14882 14883 14884 14885 14886 14887 14888 14889 14890 14891 14892 14893 14894 14895 14896 14897 14898 14899 14900 14901 14902 14903 14904 14905 14906 14907 14908 14909 14910 14911 14912 14913 14914 14915 14916 14917 14918 14919 14920 14921 14922 14923 14924 14925 14926 14927 14928 14929 14930 14931 14932 14933 14934 14935 14936 14937 14938 14939 14940 14941 14942 14943 14944 14945 14946 14947 14948 14949 14950 14951 14952 14953 14954 14955 14956 14957 14958 14959 14960 14961 14962 14963 14964 14965 14966 14967 14968 14969 14970 14971 14972 14973 14974 14975 14976 14977 14978 14979 14980 14981 14982 14983 14984 14985 14986 14987 14988 14989 14990 14991 14992 14993 14994 14995 14996 14997 14998 14999 15000 15001 15002 15003 15004 15005 15006 15007 15008 15009 15010 15011 15012 15013 15014 15015 15016 15017 15018 15019 15020 15021 15022 15023 15024 15025 15026 15027 15028 15029 15030 15031 15032 15033 15034 15035 15036 15037 15038 15039 15040 15041 15042 15043 15044 15045 15046 15047 15048 15049 15050 15051 15052 15053 15054 15055 15056 15057 15058 15059 15060 15061 15062 15063 15064 15065 15066 15067 15068 15069 15070 15071 15072 15073 15074 15075 15076 15077 15078 15079 15080 15081 15082 15083 15084 15085 15086 15087 15088 15089 15090 15091 15092 15093 15094 15095 15096 15097 15098 15099 15100 15101 15102 15103 15104 15105 15106 15107 15108 15109 15110 15111 15112 15113 15114 15115 15116 15117 15118 15119 15120 15121 15122 15123 15124 15125 15126 15127 15128 15129 15130 15131 15132 15133 15134 15135 15136 15137 15138 15139 15140 15141 15142 15143 15144 15145 15146 15147 15148 15149 15150 15151 15152 15153 15154 15155 15156 15157 15158 15159 15160 15161 15162 15163 15164 15165 15166 15167 15168 15169 15170 15171 15172 15173 15174 15175 15176 15177 15178 15179 15180 15181 15182 15183 15184 15185 15186 15187 15188 15189 15190 15191 15192 15193 15194 15195 15196 15197 15198 15199 15200 15201 15202 15203 15204 15205 15206 15207 15208 15209 15210 15211 15212 15213 15214 15215 15216 15217 15218 15219 15220 15221 15222 15223 15224 15225 15226 15227 15228 15229 15230 15231 15232 15233 15234 15235 15236 15237 15238 15239 15240 15241 15242 15243 15244 15245 15246 15247 15248 15249 15250 15251 15252 15253 15254 15255 15256 15257 15258 15259 15260 15261 15262 15263 15264 15265 15266 15267 15268 15269 15270 15271 15272 15273 15274 15275 15276 15277 15278 15279 15280 15281 15282 15283 15284 15285 15286 15287 15288 15289 15290 15291 15292 15293 15294 15295 15296 15297 15298 15299 15300 15301 15302 15303 15304 15305 15306 15307 15308 15309 15310 15311 15312 15313 15314 15315 15316 15317 15318 15319 15320 15321 15322 15323 15324 15325 15326 15327 15328 15329 15330 15331 15332 15333 15334 15335 15336 15337 15338 15339 15340 15341 15342 15343 15344 15345 15346 15347 15348 15349 15350 15351 15352 15353 15354 15355 15356 15357 15358 15359 15360 15361 15362 15363 15364 15365 15366 15367 15368 15369 15370 15371 15372 15373 15374 15375 15376 15377 15378 15379 15380 15381 15382 15383 15384 15385 15386 15387 15388 15389 15390 15391 15392 15393 15394 15395 15396 15397 15398 15399 15400 15401 15402 15403 15404 15405 15406 15407 15408 15409 15410 15411 15412 15413 15414 15415 15416 15417 15418 15419 15420 15421 15422 15423 15424 15425 15426 15427 15428 15429 15430 15431 15432 15433 15434 15435 15436 15437 15438 15439 15440 15441 15442 15443 15444 15445 15446 15447 15448 15449 15450 15451 15452 15453 15454 15455 15456 15457 15458 15459 15460 15461 15462 15463 15464 15465 15466 15467 15468 15469 15470 15471 15472 15473 15474 15475 15476 15477 15478 15479 15480 15481 15482 15483 15484 15485 15486 15487 15488 15489 15490 15491 15492 15493 15494 15495 15496 15497 15498 15499 15500 15501 15502 15503 15504 15505 15506 15507 15508 15509 15510 15511 15512 15513 15514 15515 15516 15517 15518 15519 15520 15521 15522 15523 15524 15525 15526 15527 15528 15529 15530 15531 15532 15533 15534 15535 15536 15537 15538 15539 15540 15541 15542 15543 15544 15545 15546 15547 15548 15549 15550 15551 15552 15553 15554 15555 15556 15557 15558 15559 15560 15561 15562 15563 15564 15565 15566 15567 15568 15569 15570 15571 15572 15573 15574 15575 15576 15577 15578 15579 15580 15581 15582 15583 15584 15585 15586 15587 15588 15589 15590 15591 15592 15593 15594 15595 15596 15597 15598 15599 15600 15601 15602 15603 15604 15605 15606 15607 15608 15609 15610 15611 15612 15613 15614 15615 15616 15617 15618 15619 15620 15621 15622 15623 15624 15625 15626 15627 15628 15629 15630 15631 15632 15633 15634 15635 15636 15637 15638 15639 15640 15641 15642 15643 15644 15645 15646 15647 15648 15649 15650 15651 15652 15653 15654 15655 15656 15657 15658 15659 15660 15661 15662 15663 15664 15665 15666 15667 15668 15669 15670 15671 15672 15673 15674 15675 15676 15677 15678 15679 15680 15681 15682 15683 15684 15685 15686 15687 15688 15689 15690 15691 15692 15693 15694 15695 15696 15697 15698 15699 15700 15701 15702 15703 15704 15705 15706 15707 15708 15709 15710 15711 15712 15713 15714 15715 15716 15717 15718 15719 15720 15721 15722 15723 15724 15725 15726 15727 15728 15729 15730 15731 15732 15733 15734 15735 15736 15737 15738 15739 15740 15741 15742 15743 15744 15745 15746 15747 15748 15749 15750 15751 15752 15753 15754 15755 15756 15757 15758 15759 15760 15761 15762 15763 15764 15765 15766 15767 15768 15769 15770 15771 15772 15773 15774 15775 15776 15777 15778 15779 15780 15781 15782 15783 15784 15785 15786 15787 15788 15789 15790 15791 15792 15793 15794 15795 15796 15797 15798 15799 15800 15801 15802 15803 15804 15805 15806 15807 15808 15809 15810 15811 15812 15813 15814 15815 15816 15817 15818 15819 15820 15821 15822 15823 15824 15825 15826 15827 15828 15829 15830 15831 15832 15833 15834 15835 15836 15837 15838 15839 15840 15841 15842 15843 15844 15845 15846 15847 15848 15849 15850 15851 15852 15853 15854 15855 15856 15857 15858 15859 15860 15861 15862 15863 15864 15865 15866 15867 15868 15869 15870 15871 15872 15873 15874 15875 15876 15877 15878 15879 15880 15881 15882 15883 15884 15885 15886 15887 15888 15889 15890 15891 15892 15893 15894 15895 15896 15897 15898 15899 15900 15901 15902 15903 15904 15905 15906 15907 15908 15909 15910 15911 15912 15913 15914 15915 15916 15917 15918 15919 15920 15921 15922 15923 15924 15925 15926 15927 15928 15929 15930 15931 15932 15933 15934 15935 15936 15937 15938 15939 15940 15941 15942 15943 15944 15945 15946 15947 15948 15949 15950 15951 15952 15953 15954 15955 15956 15957 15958 15959 15960 15961 15962 15963 15964 15965 15966 15967 15968 15969 15970 15971 15972 15973 15974 15975 15976 15977 15978 15979 15980 15981 15982 15983 15984 15985 15986 15987 15988 15989 15990 15991 15992 15993 15994 15995 15996 15997 15998 15999 16000 16001 16002 16003 16004 16005 16006 16007 16008 16009 16010 16011 16012 16013 16014 16015 16016 16017 16018 16019 16020 16021 16022 16023 16024 16025 16026 16027 16028 16029 16030 16031 16032 16033 16034 16035 16036 16037 16038 16039 16040 16041 16042 16043 16044 16045 16046 16047 16048 16049 16050 16051 16052 16053 16054 16055 16056 16057 16058 16059 16060 16061 16062 16063 16064 16065 16066 16067 16068 16069 16070 16071 16072 16073 16074 16075 16076 16077 16078 16079 16080 16081 16082 16083 16084 16085 16086 16087 16088 16089 16090 16091 16092 16093 16094 16095 16096 16097 16098 16099 16100 16101 16102 16103 16104 16105 16106 16107 16108 16109 16110 16111 16112 16113 16114 16115 16116 16117 16118 16119 16120 16121 16122 16123 16124 16125 16126 16127 16128 16129 16130 16131 16132 16133 16134 16135 16136 16137 16138 16139 16140 16141 16142 16143 16144 16145 16146 16147 16148 16149 16150 16151 16152 16153 16154 16155 16156 16157 16158 16159 16160 16161 16162 16163 16164 16165 16166 16167 16168 16169 16170 16171 16172 16173 16174 16175 16176 16177 16178 16179 16180 16181 16182 16183 16184 16185 16186 16187 16188 16189 16190 16191 16192 16193 16194 16195 16196 16197 16198 16199 16200 16201 16202 16203 16204 16205 16206 16207 16208 16209 16210 16211 16212 16213 16214 16215 16216 16217 16218 16219 16220 16221 16222 16223 16224 16225 16226 16227 16228 16229 16230 16231 16232 16233 16234 16235 16236 16237 16238 16239 16240 16241 16242 16243 16244 16245 16246 16247 16248 16249 16250 16251 16252 16253 16254 16255 16256 16257 16258 16259 16260 16261 16262 16263 16264 16265 16266 16267 16268 16269 16270 16271 16272 16273 16274 16275 16276 16277 16278 16279 16280 16281 16282 16283 16284 16285 16286 16287 16288 16289 16290 16291 16292 16293 16294 16295 16296 16297 16298 16299 16300 16301 16302 16303 16304 16305 16306 16307 16308 16309 16310 16311 16312 16313 16314 16315 16316 16317 16318 16319 16320 16321 16322 16323 16324 16325 16326 16327 16328 16329 16330 16331 16332 16333 16334 16335 16336 16337 16338 16339 16340 16341 16342 16343 16344 16345 16346 16347 16348 16349 16350 16351 16352 16353 16354 16355 16356 16357 16358 16359 16360 16361 16362 16363 16364 16365 16366 16367 16368 16369 16370 16371 16372 16373 16374 16375 16376 16377 16378 16379 16380 16381 16382 16383 16384 16385 16386 16387 16388 16389 16390 16391 16392 16393 16394 16395 16396 16397 16398 16399 16400 16401 16402 16403 16404 16405 16406 16407 16408 16409 16410 16411 16412 16413 16414 16415 16416 16417 16418 16419 16420 16421 16422 16423 16424 16425 16426 16427 16428 16429 16430 16431 16432 16433 16434 16435 16436 16437 16438 16439 16440 16441 16442 16443 16444 16445 16446 16447 16448 16449 16450 16451 16452 16453 16454 16455 16456 16457 16458 16459 16460 16461 16462 16463 16464 16465 16466 16467 16468 16469 16470 16471 16472 16473 16474 16475 16476 16477 16478 16479 16480 16481 16482 16483 16484 16485 16486 16487 16488 16489 16490 16491 16492 16493 16494 16495 16496 16497 16498 16499 16500 16501 16502 16503 16504 16505 16506 16507 16508 16509 16510 16511 16512 16513 16514 16515 16516 16517 16518 16519 16520 16521 16522 16523 16524 16525 16526 16527 16528 16529 16530 16531 16532 16533 16534 16535 16536 16537 16538 16539 16540 16541 16542 16543 16544 16545 16546 16547 16548 16549 16550 16551 16552 16553 16554 16555 16556 16557 16558 16559 16560 16561 16562 16563 16564 16565 16566 16567 16568 16569 16570 16571 16572 16573 16574 16575 16576 16577 16578 16579 16580 16581 16582 16583 16584 16585 16586 16587 16588 16589 16590 16591 16592 16593 16594 16595 16596 16597 16598 16599 16600 16601 16602 16603 16604 16605 16606 16607 16608 16609 16610 16611 16612 16613 16614 16615 16616 16617 16618 16619 16620 16621 16622 16623 16624 16625 16626 16627 16628 16629 16630 16631 16632 16633 16634 16635 16636 16637 16638 16639 16640 16641 16642 16643 16644 16645 16646 16647 16648 16649 16650 16651 16652 16653 16654 16655 16656 16657 16658 16659 16660 16661 16662 16663 16664 16665 16666 16667 16668 16669 16670 16671 16672 16673 16674 16675 16676 16677 16678 16679 16680 16681 16682 16683 16684 16685 16686 16687 16688 16689 16690 16691 16692 16693 16694 16695 16696 16697 16698 16699 16700 16701 16702 16703 16704 16705 16706 16707 16708 16709 16710 16711 16712 16713 16714 16715 16716 16717 16718 16719 16720 16721 16722 16723 16724 16725 16726 16727 16728 16729 16730 16731 16732 16733 16734 16735 16736 16737 16738 16739 16740 16741 16742 16743 16744 16745 16746 16747 16748 16749 16750 16751 16752 16753 16754 16755 16756 16757 16758 16759 16760 16761 16762 16763 16764 16765 16766 16767 16768 16769 16770 16771 16772 16773 16774 16775 16776 16777 16778 16779 16780 16781 16782 16783 16784 16785 16786 16787 16788 16789 16790 16791 16792 16793 16794 16795 16796 16797 16798 16799 16800 16801 16802 16803 16804 16805 16806 16807 16808 16809 16810 16811 16812 16813 16814 16815 16816 16817 16818 16819 16820 16821 16822 16823 16824 16825 16826 16827 16828 16829 16830 16831 16832 16833 16834 16835 16836 16837 16838 16839 16840 16841 16842 16843 16844 16845 16846 16847 16848 16849 16850 16851 16852 16853 16854 16855 16856 16857 16858 16859 16860 16861 16862 16863 16864 16865 16866 16867 16868 16869 16870 16871 16872 16873 16874 16875 16876 16877 16878 16879 16880 16881 16882 16883 16884 16885 16886 16887 16888 16889 16890 16891 16892 16893 16894 16895 16896 16897 16898 16899 16900 16901 16902 16903 16904 16905 16906 16907 16908 16909 16910 16911 16912 16913 16914 16915 16916 16917 16918 16919 16920 16921 16922 16923 16924 16925 16926 16927 16928 16929 16930 16931 16932 16933 16934 16935 16936 16937 16938 16939 16940 16941 16942 16943 16944 16945 16946 16947 16948 16949 16950 16951 16952 16953 16954 16955 16956 16957 16958 16959 16960 16961 16962 16963 16964 16965 16966 16967 16968 16969 16970 16971 16972 16973 16974 16975 16976 16977 16978 16979 16980 16981 16982 16983 16984 16985 16986 16987 16988 16989 16990 16991 16992 16993 16994 16995 16996 16997 16998 16999 17000 17001 17002 17003 17004 17005 17006 17007 17008 17009 17010 17011 17012 17013 17014 17015 17016 17017 17018 17019 17020 17021 17022 17023 17024 17025 17026 17027 17028 17029 17030 17031 17032 17033 17034 17035 17036 17037 17038 17039 17040 17041 17042 17043 17044 17045 17046 17047 17048 17049 17050 17051 17052 17053 17054 17055 17056 17057 17058 17059 17060 17061 17062 17063 17064 17065 17066 17067 17068 17069 17070 17071 17072 17073 17074 17075 17076 17077 17078 17079 17080 17081 17082 17083 17084 17085 17086 17087 17088 17089 17090 17091 17092 17093 17094 17095 17096 17097 17098 17099 17100 17101 17102 17103 17104 17105 17106 17107 17108 17109 17110 17111 17112 17113 17114 17115 17116 17117 17118 17119 17120 17121 17122 17123 17124 17125 17126 17127 17128 17129 17130 17131 17132 17133 17134 17135 17136 17137 17138 17139 17140 17141 17142 17143 17144 17145 17146 17147 17148 17149 17150 17151 17152 17153 17154 17155 17156 17157 17158 17159 17160 17161 17162 17163 17164 17165 17166 17167 17168 17169 17170 17171 17172 17173 17174 17175 17176 17177 17178 17179 17180 17181 17182 17183 17184 17185 17186 17187 17188 17189 17190 17191 17192 17193 17194 17195 17196 17197 17198 17199 17200 17201 17202 17203 17204 17205 17206 17207 17208 17209 17210 17211 17212 17213 17214 17215 17216 17217 17218 17219 17220 17221 17222 17223 17224 17225 17226 17227 17228 17229 17230 17231 17232 17233 17234 17235 17236 17237 17238 17239 17240 17241 17242 17243 17244 17245 17246 17247 17248 17249 17250 17251 17252 17253 17254 17255 17256 17257 17258 17259 17260 17261 17262 17263 17264 17265 17266 17267 17268 17269 17270 17271 17272 17273 17274 17275 17276 17277 17278 17279 17280 17281 17282 17283 17284 17285 17286 17287 17288 17289 17290 17291 17292 17293 17294 17295 17296 17297 17298 17299 17300 17301 17302 17303 17304 17305 17306 17307 17308 17309 17310 17311 17312 17313 17314 17315 17316 17317 17318 17319 17320 17321 17322 17323 17324 17325 17326 17327 17328 17329 17330 17331 17332 17333 17334 17335 17336 17337 17338 17339 17340 17341 17342 17343 17344 17345 17346 17347 17348 17349 17350 17351 17352 17353 17354 17355 17356 17357 17358 17359 17360 17361 17362 17363 17364 17365 17366 17367 17368 17369 17370 17371 17372 17373 17374 17375 17376 17377 17378 17379 17380 17381 17382 17383 17384 17385 17386 17387 17388 17389 17390 17391 17392 17393 17394 17395 17396 17397 17398 17399 17400 17401 17402 17403 17404 17405 17406 17407 17408 17409 17410 17411 17412 17413 17414 17415 17416 17417 17418 17419 17420 17421 17422 17423 17424 17425 17426 17427 17428 17429 17430 17431 17432 17433 17434 17435 17436 17437 17438 17439 17440 17441 17442 17443 17444 17445 17446 17447 17448 17449 17450 17451 17452 17453 17454 17455 17456 17457 17458 17459 17460 17461 17462 17463 17464 17465 17466 17467 17468 17469 17470 17471 17472 17473 17474 17475 17476 17477 17478 17479 17480 17481 17482 17483 17484 17485 17486 17487 17488 17489 17490 17491 17492 17493 17494 17495 17496 17497 17498 17499 17500 17501 17502 17503 17504 17505 17506 17507 17508 17509 17510 17511 17512 17513 17514 17515 17516 17517 17518 17519 17520 17521 17522 17523 17524 17525 17526 17527 17528 17529 17530 17531 17532 17533 17534 17535 17536 17537 17538 17539 17540 17541 17542 17543 17544 17545 17546 17547 17548 17549 17550 17551 17552 17553 17554 17555 17556 17557 17558 17559 17560 17561 17562 17563 17564 17565 17566 17567 17568 17569 17570 17571 17572 17573 17574 17575 17576 17577 17578 17579 17580 17581 17582 17583 17584 17585 17586 17587 17588 17589 17590 17591 17592 17593 17594 17595 17596 17597 17598 17599 17600 17601 17602 17603 17604 17605 17606 17607 17608 17609 17610 17611 17612 17613 17614 17615 17616 17617 17618 17619 17620 17621 17622 17623 17624 17625 17626 17627 17628 17629 17630 17631 17632 17633 17634 17635 17636 17637 17638 17639 17640 17641 17642 17643 17644 17645 17646 17647 17648 17649 17650 17651 17652 17653 17654 17655 17656 17657 17658 17659 17660 17661 17662 17663 17664 17665 17666 17667 17668 17669 17670 17671 17672 17673 17674 17675 17676 17677 17678 17679 17680 17681 17682 17683 17684 17685 17686 17687 17688 17689 17690 17691 17692 17693 17694 17695 17696 17697 17698 17699 17700 17701 17702 17703 17704 17705 17706 17707 17708 17709 17710 17711 17712 17713 17714 17715 17716 17717 17718 17719 17720 17721 17722 17723 17724 17725 17726 17727 17728 17729 17730 17731 17732 17733 17734 17735 17736 17737 17738 17739 17740 17741 17742 17743 17744 17745 17746 17747 17748 17749 17750 17751 17752 17753 17754 17755 17756 17757 17758 17759 17760 17761 17762 17763 17764 17765 17766 17767 17768 17769 17770 17771 17772 17773 17774 17775 17776 17777 17778 17779 17780 17781 17782 17783 17784 17785 17786 17787 17788 17789 17790 17791 17792 17793 17794 17795 17796 17797 17798 17799 17800 17801 17802 17803 17804 17805 17806 17807 17808 17809 17810 17811 17812 17813 17814 17815 17816 17817 17818 17819 17820 17821 17822 17823 17824 17825 17826 17827 17828 17829 17830 17831 17832 17833 17834 17835 17836 17837 17838 17839 17840 17841 17842 17843 17844 17845 17846 17847 17848 17849 17850 17851 17852 17853 17854 17855 17856 17857 17858 17859 17860 17861 17862 17863 17864 17865 17866 17867 17868 17869 17870 17871 17872 17873 17874 17875 17876 17877 17878 17879 17880 17881 17882 17883 17884 17885 17886 17887 17888 17889 17890 17891 17892 17893 17894 17895 17896 17897 17898 17899 17900 17901 17902 17903 17904 17905 17906 17907 17908 17909 17910 17911 17912 17913 17914 17915 17916 17917 17918 17919 17920 17921 17922 17923 17924 17925 17926 17927 17928 17929 17930 17931 17932 17933 17934 17935 17936 17937 17938 17939 17940 17941 17942 17943 17944 17945 17946 17947 17948 17949 17950 17951 17952 17953 17954 17955 17956 17957 17958 17959 17960 17961 17962 17963 17964 17965 17966 17967 17968 17969 17970 17971 17972 17973 17974 17975 17976 17977 17978 17979 17980 17981 17982 17983 17984 17985 17986 17987 17988 17989 17990 17991 17992 17993 17994 17995 17996 17997 17998 17999 18000 18001 18002 18003 18004 18005 18006 18007 18008 18009 18010 18011 18012 18013 18014 18015 18016 18017 18018 18019 18020 18021 18022 18023 18024 18025 18026 18027 18028 18029 18030 18031 18032 18033 18034 18035 18036 18037 18038 18039 18040 18041 18042 18043 18044 18045 18046 18047 18048 18049 18050 18051 18052 18053 18054 18055 18056 18057 18058 18059 18060 18061 18062 18063 18064 18065 18066 18067 18068 18069 18070 18071 18072 18073 18074 18075 18076 18077 18078 18079 18080 18081 18082 18083 18084 18085 18086 18087 18088 18089 18090 18091 18092 18093 18094 18095 18096 18097 18098 18099 18100 18101 18102 18103 18104 18105 18106 18107 18108 18109 18110 18111 18112 18113 18114 18115 18116 18117 18118 18119 18120 18121 18122 18123 18124 18125 18126 18127 18128 18129 18130 18131 18132 18133 18134 18135 18136 18137 18138 18139 18140 18141 18142 18143 18144 18145 18146 18147 18148 18149 18150 18151 18152 18153 18154 18155 18156 18157 18158 18159 18160 18161 18162 18163 18164 18165 18166 18167 18168 18169 18170 18171 18172 18173 18174 18175 18176 18177 18178 18179 18180 18181 18182 18183 18184 18185 18186 18187 18188 18189 18190 18191 18192 18193 18194 18195 18196 18197 18198 18199 18200 18201 18202 18203 18204 18205 18206 18207 18208 18209 18210 18211 18212 18213 18214 18215 18216 18217 18218 18219 18220 18221 18222 18223 18224 18225 18226 18227 18228 18229 18230 18231 18232 18233 18234 18235 18236 18237 18238 18239 18240 18241 18242 18243 18244 18245 18246 18247 18248 18249 18250 18251 18252 18253 18254 18255 18256 18257 18258 18259 18260 18261 18262 18263 18264 18265 18266 18267 18268 18269 18270 18271 18272 18273 18274 18275 18276 18277 18278 18279 18280 18281 18282 18283 18284 18285 18286 18287 18288 18289 18290 18291 18292 18293 18294 18295 18296 18297 18298 18299 18300 18301 18302 18303 18304 18305 18306 18307 18308 18309 18310 18311 18312 18313 18314 18315 18316 18317 18318 18319 18320 18321 18322 18323 18324 18325 18326 18327 18328 18329 18330 18331 18332 18333 18334 18335 18336 18337 18338 18339 18340 18341 18342 18343 18344 18345 18346 18347 18348 18349 18350 18351 18352 18353 18354 18355 18356 18357 18358 18359 18360 18361 18362 18363 18364 18365 18366 18367 18368 18369 18370 18371 18372 18373 18374 18375 18376 18377 18378 18379 18380 18381 18382 18383 18384 18385 18386 18387 18388 18389 18390 18391 18392 18393 18394 18395 18396 18397 18398 18399 18400 18401 18402 18403 18404 18405 18406 18407 18408 18409 18410 18411 18412 18413 18414 18415 18416 18417 18418 18419 18420 18421 18422 18423 18424 18425 18426 18427 18428 18429 18430 18431 18432 18433 18434 18435 18436 18437 18438 18439 18440 18441 18442 18443 18444 18445 18446 18447 18448 18449 18450 18451 18452 18453 18454 18455 18456 18457 18458 18459 18460 18461 18462 18463 18464 18465 18466 18467 18468 18469 18470 18471 18472 18473 18474 18475 18476 18477 18478 18479 18480 18481 18482 18483 18484 18485 18486 18487 18488 18489 18490 18491 18492 18493 18494 18495 18496 18497 18498 18499 18500 18501 18502 18503 18504 18505 18506 18507 18508 18509 18510 18511 18512 18513 18514 18515 18516 18517 18518 18519 18520 18521 18522 18523 18524 18525 18526 18527 18528 18529 18530 18531 18532 18533 18534 18535 18536 18537 18538 18539 18540 18541 18542 18543 18544 18545 18546 18547 18548 18549 18550 18551 18552 18553 18554 18555 18556 18557 18558 18559 18560 18561 18562 18563 18564 18565 18566 18567 18568 18569 18570 18571 18572 18573 18574 18575 18576 18577 18578 18579 18580 18581 18582 18583 18584 18585 18586 18587 18588 18589 18590 18591 18592 18593 18594 18595 18596 18597 18598 18599 18600 18601 18602 18603 18604 18605 18606 18607 18608 18609 18610 18611 18612 18613 18614 18615 18616 18617 18618 18619 18620 18621 18622 18623 18624 18625 18626 18627 18628 18629 18630 18631 18632 18633 18634 18635 18636 18637 18638 18639 18640 18641 18642 18643 18644 18645 18646 18647 18648 18649 18650 18651 18652 18653 18654 18655 18656 18657 18658 18659 18660 18661 18662 18663 18664 18665 18666 18667 18668 18669 18670 18671 18672 18673 18674 18675 18676 18677 18678 18679 18680 18681 18682 18683 18684 18685 18686 18687 18688 18689 18690 18691 18692 18693 18694 18695 18696 18697 18698 18699 18700 18701 18702 18703 18704 18705 18706 18707 18708 18709 18710 18711 18712 18713 18714 18715 18716 18717 18718 18719 18720 18721 18722 18723 18724 18725 18726 18727 18728 18729 18730 18731 18732 18733 18734 18735 18736 18737 18738 18739 18740 18741 18742 18743 18744 18745 18746 18747 18748 18749 18750 18751 18752 18753 18754 18755 18756 18757 18758 18759 18760 18761 18762 18763 18764 18765 18766 18767 18768 18769 18770 18771 18772 18773 18774 18775 18776 18777 18778 18779 18780 18781 18782 18783 18784 18785 18786 18787 18788 18789 18790 18791 18792 18793 18794 18795 18796 18797 18798 18799 18800 18801 18802 18803 18804 18805 18806 18807 18808 18809 18810 18811 18812 18813 18814 18815 18816 18817 18818 18819 18820 18821 18822 18823 18824 18825 18826 18827 18828 18829 18830 18831 18832 18833 18834 18835 18836 18837 18838 18839 18840 18841 18842 18843 18844 18845 18846 18847 18848 18849 18850 18851 18852 18853 18854 18855 18856 18857 18858 18859 18860 18861 18862 18863 18864 18865 18866 18867 18868 18869 18870 18871 18872 18873 18874 18875 18876 18877 18878 18879 18880 18881 18882 18883 18884 18885 18886 18887 18888 18889 18890 18891 18892 18893 18894 18895 18896 18897 18898 18899 18900 18901 18902 18903 18904 18905 18906 18907 18908 18909 18910 18911 18912 18913 18914 18915 18916 18917 18918 18919 18920 18921 18922 18923 18924 18925 18926 18927 18928 18929 18930 18931 18932 18933 18934 18935 18936 18937 18938 18939 18940 18941 18942 18943 18944 18945 18946 18947 18948 18949 18950 18951 18952 18953 18954 18955 18956 18957 18958 18959 18960 18961 18962 18963 18964 18965 18966 18967 18968 18969 18970 18971 18972 18973 18974 18975 18976 18977 18978 18979 18980 18981 18982 18983 18984 18985 18986 18987 18988 18989 18990 18991 18992 18993 18994 18995 18996 18997 18998 18999 19000 19001 19002 19003 19004 19005 19006 19007 19008 19009 19010 19011 19012 19013 19014 19015 19016 19017 19018 19019 19020 19021 19022 19023 19024 19025 19026 19027 19028 19029 19030 19031 19032 19033 19034 19035 19036 19037 19038 19039 19040 19041 19042 19043 19044 19045 19046 19047 19048 19049 19050 19051 19052 19053 19054 19055 19056 19057 19058 19059 19060 19061 19062 19063 19064 19065 19066 19067 19068 19069 19070 19071 19072 19073 19074 19075 19076 19077 19078 19079 19080 19081 19082 19083 19084 19085 19086 19087 19088 19089 19090 19091 19092 19093 19094 19095 19096 19097 19098 19099 19100 19101 19102 19103 19104 19105 19106 19107 19108 19109 19110 19111 19112 19113 19114 19115 19116 19117 19118 19119 19120 19121 19122 19123 19124 19125 19126 19127 19128 19129 19130 19131 19132 19133 19134 19135 19136 19137 19138 19139 19140 19141 19142 19143 19144 19145 19146 19147 19148 19149 19150 19151 19152 19153 19154 19155 19156 19157 19158 19159 19160 19161 19162 19163 19164 19165 19166 19167 19168 19169 19170 19171 19172 19173 19174 19175 19176 19177 19178 19179 19180 19181 19182 19183 19184 19185 19186 19187 19188 19189 19190 19191 19192 19193 19194 19195 19196 19197 19198 19199 19200 19201 19202 19203 19204 19205 19206 19207 19208 19209 19210 19211 19212 19213 19214 19215 19216 19217 19218 19219 19220 19221 19222 19223 19224 19225 19226 19227 19228 19229 19230 19231 19232 19233 19234 19235 19236 19237 19238 19239 19240 19241 19242 19243 19244 19245 19246 19247 19248 19249 19250 19251 19252 19253 19254 19255 19256 19257 19258 19259 19260 19261 19262 19263 19264 19265 19266 19267 19268 19269 19270 19271 19272 19273 19274 19275 19276 19277 19278 19279 19280 19281 19282 19283 19284 19285 19286 19287 19288 19289 19290 19291 19292 19293 19294 19295 19296 19297 19298 19299 19300 19301 19302 19303 19304 19305 19306 19307 19308 19309 19310 19311 19312 19313 19314 19315 19316 19317 19318 19319 19320 19321 19322 19323 19324 19325 19326 19327 19328 19329 19330 19331 19332 19333 19334 19335 19336 19337 19338 19339 19340 19341 19342 19343 19344 19345 19346 19347 19348 19349 19350 19351 19352 19353 19354 19355 19356 19357 19358 19359 19360 19361 19362 19363 19364 19365 19366 19367 19368 19369 19370 19371 19372 19373 19374 19375 19376 19377 19378 19379 19380 19381 19382 19383 19384 19385 19386 19387 19388 19389 19390 19391 19392 19393 19394 19395 19396 19397 19398 19399 19400 19401 19402 19403 19404 19405 19406 19407 19408 19409 19410 19411 19412 19413 19414 19415 19416 19417 19418 19419 19420 19421 19422 19423 19424 19425 19426 19427 19428 19429 19430 19431 19432 19433 19434 19435 19436 19437 19438 19439 19440 19441 19442 19443 19444 19445 19446 19447 19448 19449 19450 19451 19452 19453 19454 19455 19456 19457 19458 19459 19460 19461 19462 19463 19464 19465 19466 19467 19468 19469 19470 19471 19472 19473 19474 19475 19476 19477 19478 19479 19480 19481 19482 19483 19484 19485 19486 19487 19488 19489 19490 19491 19492 19493 19494 19495 19496 19497 19498 19499 19500 19501 19502 19503 19504 19505 19506 19507 19508 19509 19510 19511 19512 19513 19514 19515 19516 19517 19518 19519 19520 19521 19522 19523 19524 19525 19526 19527 19528 19529 19530 19531 19532 19533 19534 19535 19536 19537 19538 19539 19540 19541 19542 19543 19544 19545 19546 19547 19548 19549 19550 19551 19552 19553 19554 19555 19556 19557 19558 19559 19560 19561 19562 19563 19564 19565 19566 19567 19568 19569 19570 19571 19572 19573 19574 19575 19576 19577 19578 19579 19580 19581 19582 19583 19584 19585 19586 19587 19588 19589 19590 19591 19592 19593 19594 19595 19596 19597 19598 19599 19600 19601 19602 19603 19604 19605 19606 19607 19608 19609 19610 19611 19612 19613 19614 19615 19616 19617 19618 19619 19620 19621 19622 19623 19624 19625 19626 19627 19628 19629 19630 19631 19632 19633 19634 19635 19636 19637 19638 19639 19640 19641 19642 19643 19644 19645 19646 19647 19648 19649 19650 19651 19652 19653 19654 19655 19656 19657 19658 19659 19660 19661 19662 19663 19664 19665 19666 19667 19668 19669 19670 19671 19672 19673 19674 19675 19676 19677 19678 19679 19680 19681 19682 19683 19684 19685 19686 19687 19688 19689 19690 19691 19692 19693 19694 19695 19696 19697 19698 19699 19700 19701 19702 19703 19704 19705 19706 19707 19708 19709 19710 19711 19712 19713 19714 19715 19716 19717 19718 19719 19720 19721 19722 19723 19724 19725 19726 19727 19728 19729 19730 19731 19732 19733 19734 19735 19736 19737 19738 19739 19740 19741 19742 19743 19744 19745 19746 19747 19748 19749 19750 19751 19752 19753 19754 19755 19756 19757 19758 19759 19760 19761 19762 19763 19764 19765 19766 19767 19768 19769 19770 19771 19772 19773 19774 19775 19776 19777 19778 19779 19780 19781 19782 19783 19784 19785 19786 19787 19788 19789 19790 19791 19792 19793 19794 19795 19796 19797 19798 19799 19800 19801 19802 19803 19804 19805 19806 19807 19808 19809 19810 19811 19812 19813 19814 19815 19816 19817 19818 19819 19820 19821 19822 19823 19824 19825 19826 19827 19828 19829 19830 19831 19832 19833 19834 19835 19836 19837 19838 19839 19840 19841 19842 19843 19844 19845 19846 19847 19848 19849 19850 19851 19852 19853 19854 19855 19856 19857 19858 19859 19860 19861 19862 19863 19864 19865 19866 19867 19868 19869 19870 19871 19872 19873 19874 19875 19876 19877 19878 19879 19880 19881 19882 19883 19884 19885 19886 19887 19888 19889 19890 19891 19892 19893 19894 19895 19896 19897 19898 19899 19900 19901 19902 19903 19904 19905 19906 19907 19908 19909 19910 19911 19912 19913 19914 19915 19916 19917 19918 19919 19920 19921 19922 19923 19924 19925 19926 19927 19928 19929 19930 19931 19932 19933 19934 19935 19936 19937 19938 19939 19940 19941 19942 19943 19944 19945 19946 19947 19948 19949 19950 19951 19952 19953 19954 19955 19956 19957 19958 19959 19960 19961 19962 19963 19964 19965 19966 19967 19968 19969 19970 19971 19972 19973 19974 19975 19976 19977 19978 19979 19980 19981 19982 19983 19984 19985 19986 19987 19988 19989 19990 19991 19992 19993 19994 19995 19996 19997 19998 19999 20000 20001 20002 20003 20004 20005 20006 20007 20008 20009 20010 20011 20012 20013 20014 20015 20016 20017 20018 20019 20020 20021 20022 20023 20024 20025 20026 20027 20028 20029 20030 20031 20032 20033 20034 20035 20036 20037 20038 20039 20040 20041 20042 20043 20044 20045 20046 20047 20048 20049 20050 20051 20052 20053 20054 20055 20056 20057 20058 20059 20060 20061 20062 20063 20064 20065 20066 20067 20068 20069 20070 20071 20072 20073 20074 20075 20076 20077 20078 20079 20080 20081 20082 20083 20084 20085 20086 20087 20088 20089 20090 20091 20092 20093 20094 20095 20096 20097 20098 20099 20100 20101 20102 20103 20104 20105 20106 20107 20108 20109 20110 20111 20112 20113 20114 20115 20116 20117 20118 20119 20120 20121 20122 20123 20124 20125 20126 20127 20128 20129 20130 20131 20132 20133 20134 20135 20136 20137 20138 20139 20140 20141 20142 20143 20144 20145 20146 20147 20148 20149 20150 20151 20152 20153 20154 20155 20156 20157 20158 20159 20160 20161 20162 20163 20164 20165 20166 20167 20168 20169 20170 20171 20172 20173 20174 20175 20176 20177 20178 20179 20180 20181 20182 20183 20184 20185 20186 20187 20188 20189 20190 20191 20192 20193 20194 20195 20196 20197 20198 20199 20200 20201 20202 20203 20204 20205 20206 20207 20208 20209 20210 20211 20212 20213 20214 20215 20216 20217 20218 20219 20220 20221 20222 20223 20224 20225 20226 20227 20228 20229 20230 20231 20232 20233 20234 20235 20236 20237 20238 20239 20240 20241 20242 20243 20244 20245 20246 20247 20248 20249 20250 20251 20252 20253 20254 20255 20256 20257 20258 20259 20260 20261 20262 20263 20264 20265 20266 20267 20268 20269 20270 20271 20272 20273 20274 20275 20276 20277 20278 20279 20280 20281 20282 20283 20284 20285 20286 20287 20288 20289 20290 20291 20292 20293 20294 20295 20296 20297 20298 20299 20300 20301 20302 20303 20304 20305 20306 20307 20308 20309 20310 20311 20312 20313 20314 20315 20316 20317 20318 20319 20320 20321 20322 20323 20324 20325 20326 20327 20328 20329 20330 20331 20332 20333 20334 20335 20336 20337 20338 20339 20340 20341 20342 20343 20344 20345 20346 20347 20348 20349 20350 20351 20352 20353 20354 20355 20356 20357 20358 20359 20360 20361 20362 20363 20364 20365 20366 20367 20368 20369 20370 20371 20372 20373 20374 20375 20376 20377 20378 20379 20380 20381 20382 20383 20384 20385 20386 20387 20388 20389 20390 20391 20392 20393 20394 20395 20396 20397 20398 20399 20400 20401 20402 20403 20404 20405 20406 20407 20408 20409 20410 20411 20412 20413 20414 20415 20416 20417 20418 20419 20420 20421 20422 20423 20424 20425 20426 20427 20428 20429 20430 20431 20432 20433 20434 20435 20436 20437 20438 20439 20440 20441 20442 20443 20444 20445 20446 20447 20448 20449 20450 20451 20452 20453 20454 20455 20456 20457 20458 20459 20460 20461 20462 20463 20464 20465 20466 20467 20468 20469 20470 20471 20472 20473 20474 20475 20476 20477 20478 20479 20480 20481 20482 20483 20484 20485 20486 20487 20488 20489 20490 20491 20492 20493 20494 20495 20496 20497 20498 20499 20500 20501 20502 20503 20504 20505 20506 20507 20508 20509 20510 20511 20512 20513 20514 20515 20516 20517 20518 20519 20520 20521 20522 20523 20524 20525 20526 20527 20528 20529 20530 20531 20532 20533 20534 20535 20536 20537 20538 20539 20540 20541 20542 20543 20544 20545 20546 20547 20548 20549 20550 20551 20552 20553 20554 20555 20556 20557 20558 20559 20560 20561 20562 20563 20564 20565 20566 20567 20568 20569 20570 20571 20572 20573 20574 20575 20576 20577 20578 20579 20580 20581 20582 20583 20584 20585 20586 20587 20588 20589 20590 20591 20592 20593 20594 20595 20596 20597 20598 20599 20600 20601 20602 20603 20604 20605 20606 20607 20608 20609 20610 20611 20612 20613 20614 20615 20616 20617 20618 20619 20620 20621 20622 20623 20624 20625 20626 20627 20628 20629 20630 20631 20632 20633 20634 20635 20636 20637 20638 20639 20640 20641 20642 20643 20644 20645 20646 20647 20648 20649 20650 20651 20652 20653 20654 20655 20656 20657 20658 20659 20660 20661 20662 20663 20664 20665 20666 20667 20668 20669 20670 20671 20672 20673 20674 20675 20676 20677 20678 20679 20680 20681 20682 20683 20684 20685 20686 20687 20688 20689 20690 20691 20692 20693 20694 20695 20696 20697 20698 20699 20700 20701 20702 20703 20704 20705 20706 20707 20708 20709 20710 20711 20712 20713 20714 20715 20716 20717 20718 20719 20720 20721 20722 20723 20724 20725 20726 20727 20728 20729 20730 20731 20732 20733 20734 20735 20736 20737 20738 20739 20740 20741 20742 20743 20744 20745 20746 20747 20748 20749 20750 20751 20752 20753 20754 20755 20756 20757 20758 20759 20760 20761 20762 20763 20764 20765 20766 20767 20768 20769 20770 20771 20772 20773 20774 20775 20776 20777 20778 20779 20780 20781 20782 20783 20784 20785 20786 20787 20788 20789 20790 20791 20792 20793 20794 20795 20796 20797 20798 20799 20800 20801 20802 20803 20804 20805 20806 20807 20808 20809 20810 20811 20812 20813 20814 20815 20816 20817 20818 20819 20820 20821 20822 20823 20824 20825 20826 20827 20828 20829 20830 20831 20832 20833 20834 20835 20836 20837 20838 20839 20840 20841 20842 20843 20844 20845 20846 20847 20848 20849 20850 20851 20852 20853 20854 20855 20856 20857 20858 20859 20860 20861 20862 20863 20864 20865 20866 20867 20868 20869 20870 20871 20872 20873 20874 20875 20876 20877 20878 20879 20880 20881 20882 20883 20884 20885 20886 20887 20888 20889 20890 20891 20892 20893 20894 20895 20896 20897 20898 20899 20900 20901 20902 20903 20904 20905 20906 20907 20908 20909 20910 20911 20912 20913 20914 20915 20916 20917 20918 20919 20920 20921 20922 20923 20924 20925 20926 20927 20928 20929 20930 20931 20932 20933 20934 20935 20936 20937 20938 20939 20940 20941 20942 20943 20944 20945 20946 20947 20948 20949 20950 20951 20952 20953 20954 20955 20956 20957 20958 20959 20960 20961 20962 20963 20964 20965 20966 20967 20968 20969 20970 20971 20972 20973 20974 20975 20976 20977 20978 20979 20980 20981 20982 20983 20984 20985 20986 20987 20988 20989 20990 20991 20992 20993 20994 20995 20996 20997 20998 20999 21000 21001 21002 21003 21004 21005 21006 21007 21008 21009 21010 21011 21012 21013 21014 21015 21016 21017 21018 21019 21020 21021 21022 21023 21024 21025 21026 21027 21028 21029 21030 21031 21032 21033 21034 21035 21036 21037 21038 21039 21040 21041 21042 21043 21044 21045 21046 21047 21048 21049 21050 21051 21052 21053 21054 21055 21056 21057 21058 21059 21060 21061 21062 21063 21064 21065 21066 21067 21068 21069 21070 21071 21072 21073 21074 21075 21076 21077 21078 21079 21080 21081 21082 21083 21084 21085 21086 21087 21088 21089 21090 21091 21092 21093 21094 21095 21096 21097 21098 21099 21100 21101 21102 21103 21104 21105 21106 21107 21108 21109 21110 21111 21112 21113 21114 21115 21116 21117 21118 21119 21120 21121 21122 21123 21124 21125 21126 21127 21128 21129 21130 21131 21132 21133 21134 21135 21136 21137 21138 21139 21140 21141 21142 21143 21144 21145 21146 21147 21148 21149 21150 21151 21152 21153 21154 21155 21156 21157 21158 21159 21160 21161 21162 21163 21164 21165 21166 21167 21168 21169 21170 21171 21172 21173 21174 21175 21176 21177 21178 21179 21180 21181 21182 21183 21184 21185 21186 21187 21188 21189 21190 21191 21192 21193 21194 21195 21196 21197 21198 21199 21200 21201 21202 21203 21204 21205 21206 21207 21208 21209 21210 21211 21212 21213 21214 21215 21216 21217 21218 21219 21220 21221 21222 21223 21224 21225 21226 21227 21228 21229 21230 21231 21232 21233 21234 21235 21236 21237 21238 21239 21240 21241 21242 21243 21244 21245 21246 21247 21248 21249 21250 21251 21252 21253 21254 21255 21256 21257 21258 21259 21260 21261 21262 21263 21264 21265 21266 21267 21268 21269 21270 21271 21272 21273 21274 21275 21276 21277 21278 21279 21280 21281 21282 21283 21284 21285 21286 21287 21288 21289 21290 21291 21292 21293 21294 21295 21296 21297 21298 21299 21300 21301 21302 21303 21304 21305 21306 21307 21308 21309 21310 21311 21312 21313 21314 21315 21316 21317 21318 21319 21320 21321 21322 21323 21324 21325 21326 21327 21328 21329 21330 21331 21332 21333 21334 21335 21336 21337 21338 21339 21340 21341 21342 21343 21344 21345 21346 21347 21348 21349 21350 21351 21352 21353 21354 21355 21356 21357 21358 21359 21360 21361 21362 21363 21364 21365 21366 21367 21368 21369 21370 21371 21372 21373 21374 21375 21376 21377 21378 21379 21380 21381 21382 21383 21384 21385 21386 21387 21388 21389 21390 21391 21392 21393 21394 21395 21396 21397 21398 21399 21400 21401 21402 21403 21404 21405 21406 21407 21408 21409 21410 21411 21412 21413 21414 21415 21416 21417 21418 21419 21420 21421 21422 21423 21424 21425 21426 21427 21428 21429 21430 21431 21432 21433 21434 21435 21436 21437 21438 21439 21440 21441 21442 21443 21444 21445 21446 21447 21448 21449 21450 21451 21452 21453 21454 21455 21456 21457 21458 21459 21460 21461 21462 21463 21464 21465 21466 21467 21468 21469 21470 21471 21472 21473 21474 21475 21476 21477 21478 21479 21480 21481 21482 21483 21484 21485 21486 21487 21488 21489 21490 21491 21492 21493 21494 21495 21496 21497 21498 21499 21500 21501 21502 21503 21504 21505 21506 21507 21508 21509 21510 21511 21512 21513 21514 21515 21516 21517 21518 21519 21520 21521 21522 21523 21524 21525 21526 21527 21528 21529 21530 21531 21532 21533 21534 21535 21536 21537 21538 21539 21540 21541 21542 21543 21544 21545 21546 21547 21548 21549 21550 21551 21552 21553 21554 21555 21556 21557 21558 21559 21560 21561 21562 21563 21564 21565 21566 21567 21568 21569 21570 21571 21572 21573 21574 21575 21576 21577 21578 21579 21580 21581 21582 21583 21584 21585 21586 21587 21588 21589 21590 21591 21592 21593 21594 21595 21596 21597 21598 21599 21600 21601 21602 21603 21604 21605 21606 21607 21608 21609 21610 21611 21612 21613 21614 21615 21616 21617 21618 21619 21620 21621 21622 21623 21624 21625 21626 21627 21628 21629 21630 21631 21632 21633 21634 21635 21636 21637 21638 21639 21640 21641 21642 21643 21644 21645 21646 21647 21648 21649 21650 21651 21652 21653 21654 21655 21656 21657 21658 21659 21660 21661 21662 21663 21664 21665 21666 21667 21668 21669 21670 21671 21672 21673 21674 21675 21676 21677 21678 21679 21680 21681 21682 21683 21684 21685 21686 21687 21688 21689 21690 21691 21692 21693 21694 21695 21696 21697 21698 21699 21700 21701 21702 21703 21704 21705 21706 21707 21708 21709 21710 21711 21712 21713 21714 21715 21716 21717 21718 21719 21720 21721 21722 21723 21724 21725 21726 21727 21728 21729 21730 21731 21732 21733 21734 21735 21736 21737 21738 21739 21740 21741 21742 21743 21744 21745 21746 21747 21748 21749 21750 21751 21752 21753 21754 21755 21756 21757 21758 21759 21760 21761 21762 21763 21764 21765 21766 21767 21768 21769 21770 21771 21772 21773 21774 21775 21776 21777 21778 21779 21780 21781 21782 21783 21784 21785 21786 21787 21788 21789 21790 21791 21792 21793 21794 21795 21796 21797 21798 21799 21800 21801 21802 21803 21804 21805 21806 21807 21808 21809 21810 21811 21812 21813 21814 21815 21816 21817 21818 21819 21820 21821 21822 21823 21824 21825 21826 21827 21828 21829 21830 21831 21832 21833 21834 21835 21836 21837 21838 21839 21840 21841 21842 21843 21844 21845 21846 21847 21848 21849 21850 21851 21852 21853 21854 21855 21856 21857 21858 21859 21860 21861 21862 21863 21864 21865 21866 21867 21868 21869 21870 21871 21872 21873 21874 21875 21876 21877 21878 21879 21880 21881 21882 21883 21884 21885 21886 21887 21888 21889 21890 21891 21892 21893 21894 21895 21896 21897 21898 21899 21900 21901 21902 21903 21904 21905 21906 21907 21908 21909 21910 21911 21912 21913 21914 21915 21916 21917 21918 21919 21920 21921 21922 21923 21924 21925 21926 21927 21928 21929 21930 21931 21932 21933 21934 21935 21936 21937 21938 21939 21940 21941 21942 21943 21944 21945 21946 21947 21948 21949 21950 21951 21952 21953 21954 21955 21956 21957 21958 21959 21960 21961 21962 21963 21964 21965 21966 21967 21968 21969 21970 21971 21972 21973 21974 21975 21976 21977 21978 21979 21980 21981 21982 21983 21984 21985 21986 21987 21988 21989 21990 21991 21992 21993 21994 21995 21996 21997 21998 21999 22000 22001 22002 22003 22004 22005 22006 22007 22008 22009 22010 22011 22012 22013 22014 22015 22016 22017 22018 22019 22020 22021 22022 22023 22024 22025 22026 22027 22028 22029 22030 22031 22032 22033 22034 22035 22036 22037 22038 22039 22040 22041 22042 22043 22044 22045 22046 22047 22048 22049 22050 22051 22052 22053 22054 22055 22056 22057 22058 22059 22060 22061 22062 22063 22064 22065 22066 22067 22068 22069 22070 22071 22072 22073 22074 22075 22076 22077 22078 22079 22080 22081 22082 22083 22084 22085 22086 22087 22088 22089 22090 22091 22092 22093 22094 22095 22096 22097 22098 22099 22100 22101 22102 22103 22104 22105 22106 22107 22108 22109 22110 22111 22112 22113 22114 22115 22116 22117 22118 22119 22120 22121 22122 22123 22124 22125 22126 22127 22128 22129 22130 22131 22132 22133 22134 22135 22136 22137 22138 22139 22140 22141 22142 22143 22144 22145 22146 22147 22148 22149 22150 22151 22152 22153 22154 22155 22156 22157 22158 22159 22160 22161 22162 22163 22164 22165 22166 22167 22168 22169 22170 22171 22172 22173 22174 22175 22176 22177 22178 22179 22180 22181 22182 22183 22184 22185 22186 22187 22188 22189 22190 22191 22192 22193 22194 22195 22196 22197 22198 22199 22200 22201 22202 22203 22204 22205 22206 22207 22208 22209 22210 22211 22212 22213 22214 22215 22216 22217 22218 22219 22220 22221 22222 22223 22224 22225 22226 22227 22228 22229 22230 22231 22232 22233 22234 22235 22236 22237 22238 22239 22240 22241 22242 22243 22244 22245 22246 22247 22248 22249 22250 22251 22252 22253 22254 22255 22256 22257 22258 22259 22260 22261 22262 22263 22264 22265 22266 22267 22268 22269 22270 22271 22272 22273 22274 22275 22276 22277 22278 22279 22280 22281 22282 22283 22284 22285 22286 22287 22288 22289 22290 22291 22292 22293 22294 22295 22296 22297 22298 22299 22300 22301 22302 22303 22304 22305 22306 22307 22308 22309 22310 22311 22312 22313 22314 22315 22316 22317 22318 22319 22320 22321 22322 22323 22324 22325 22326 22327 22328 22329 22330 22331 22332 22333 22334 22335 22336 22337 22338 22339 22340 22341 22342 22343 22344 22345 22346 22347 22348 22349 22350 22351 22352 22353 22354 22355 22356 22357 22358 22359 22360 22361 22362 22363 22364 22365 22366 22367 22368 22369 22370 22371 22372 22373 22374 22375 22376 22377 22378 22379 22380 22381 22382 22383 22384 22385 22386 22387 22388 22389 22390 22391 22392 22393 22394 22395 22396 22397 22398 22399 22400 22401 22402 22403 22404 22405 22406 22407 22408 22409 22410 22411 22412 22413 22414 22415 22416 22417 22418 22419 22420 22421 22422 22423 22424 22425 22426 22427 22428 22429 22430 22431 22432 22433 22434 22435 22436 22437 22438 22439 22440 22441 22442 22443 22444 22445 22446 22447 22448 22449 22450 22451 22452 22453 22454 22455 22456 22457 22458 22459 22460 22461 22462 22463 22464 22465 22466 22467 22468 22469 22470 22471 22472 22473 22474 22475 22476 22477 22478 22479 22480 22481 22482 22483 22484 22485 22486 22487 22488 22489 22490 22491 22492 22493 22494 22495 22496 22497 22498 22499 22500 22501 22502 22503 22504 22505 22506 22507 22508 22509 22510 22511 22512 22513 22514 22515 22516 22517 22518 22519 22520 22521 22522 22523 22524 22525 22526 22527 22528 22529 22530 22531 22532 22533 22534 22535 22536 22537 22538 22539 22540 22541 22542 22543 22544 22545 22546 22547 22548 22549 22550 22551 22552 22553 22554 22555 22556 22557 22558 22559 22560 22561 22562 22563 22564 22565 22566 22567 22568 22569 22570 22571 22572 22573 22574 22575 22576 22577 22578 22579 22580 22581 22582 22583 22584 22585 22586 22587 22588 22589 22590 22591 22592 22593 22594 22595 22596 22597 22598 22599 22600 22601 22602 22603 22604 22605 22606 22607 22608 22609 22610 22611 22612 22613 22614 22615 22616 22617 22618 22619 22620 22621 22622 22623 22624 22625 22626 22627 22628 22629 22630 22631 22632 22633 22634 22635 22636 22637 22638 22639 22640 22641 22642 22643 22644 22645 22646 22647 22648 22649 22650 22651 22652 22653 22654 22655 22656 22657 22658 22659 22660 22661 22662 22663 22664 22665 22666 22667 22668 22669 22670 22671 22672 22673 22674 22675 22676 22677 22678 22679 22680 22681 22682 22683 22684 22685 22686 22687 22688 22689 22690 22691 22692 22693 22694 22695 22696 22697 22698 22699 22700 22701 22702 22703 22704 22705 22706 22707 22708 22709 22710 22711 22712 22713 22714 22715 22716 22717 22718 22719 22720 22721 22722 22723 22724 22725 22726 22727 22728 22729 22730 22731 22732 22733 22734 22735 22736 22737 22738 22739 22740 22741 22742 22743 22744 22745 22746 22747 22748 22749 22750 22751 22752 22753 22754 22755 22756 22757 22758 22759 22760 22761 22762 22763 22764 22765 22766 22767 22768 22769 22770 22771 22772 22773 22774 22775 22776 22777 22778 22779 22780 22781 22782 22783 22784 22785 22786 22787 22788 22789 22790 22791 22792 22793 22794 22795 22796 22797 22798 22799 22800 22801 22802 22803 22804 22805 22806 22807 22808 22809 22810 22811 22812 22813 22814 22815 22816 22817 22818 22819 22820 22821 22822 22823 22824 22825 22826 22827 22828 22829 22830 22831 22832 22833 22834 22835 22836 22837 22838 22839 22840 22841 22842 22843 22844 22845 22846 22847 22848 22849 22850 22851 22852 22853 22854 22855 22856 22857 22858 22859 22860 22861 22862 22863 22864 22865 22866 22867 22868 22869 22870 22871 22872 22873 22874 22875 22876 22877 22878 22879 22880 22881 22882 22883 22884 22885 22886 22887 22888 22889 22890 22891 22892 22893 22894 22895 22896 22897 22898 22899 22900 22901 22902 22903 22904 22905 22906 22907 22908 22909 22910 22911 22912 22913 22914 22915 22916 22917 22918 22919 22920 22921 22922 22923 22924 22925 22926 22927 22928 22929 22930 22931 22932 22933 22934 22935 22936 22937 22938 22939 22940 22941 22942 22943 22944 22945 22946 22947 22948 22949 22950 22951 22952 22953 22954 22955 22956 22957 22958 22959 22960 22961 22962 22963 22964 22965 22966 22967 22968 22969 22970 22971 22972 22973 22974 22975 22976 22977 22978 22979 22980 22981 22982 22983 22984 22985 22986 22987 22988 22989 22990 22991 22992 22993 22994 22995 22996 22997 22998 22999 23000 23001 23002 23003 23004 23005 23006 23007 23008 23009 23010 23011 23012 23013 23014 23015 23016 23017 23018 23019 23020 23021 23022 23023 23024 23025 23026 23027 23028 23029 23030 23031 23032 23033 23034 23035 23036 23037 23038 23039 23040 23041 23042 23043 23044 23045 23046 23047 23048 23049 23050 23051 23052 23053 23054 23055 23056 23057 23058 23059 23060 23061 23062 23063 23064 23065 23066 23067 23068 23069 23070 23071 23072 23073 23074 23075 23076 23077 23078 23079 23080 23081 23082 23083 23084 23085 23086 23087 23088 23089 23090 23091 23092 23093 23094 23095 23096 23097 23098 23099 23100 23101 23102 23103 23104 23105 23106 23107 23108 23109 23110 23111 23112 23113 23114 23115 23116 23117 23118 23119 23120 23121 23122 23123 23124 23125 23126 23127 23128 23129 23130 23131 23132 23133 23134 23135 23136 23137 23138 23139 23140 23141 23142 23143 23144 23145 23146 23147 23148 23149 23150 23151 23152 23153 23154 23155 23156 23157 23158 23159 23160 23161 23162 23163 23164 23165 23166 23167 23168 23169 23170 23171 23172 23173 23174 23175 23176 23177 23178 23179 23180 23181 23182 23183 23184 23185 23186 23187 23188 23189 23190 23191 23192 23193 23194 23195 23196 23197 23198 23199 23200 23201 23202 23203 23204 23205 23206 23207 23208 23209 23210 23211 23212 23213 23214 23215 23216 23217 23218 23219 23220 23221 23222 23223 23224 23225 23226 23227 23228 23229 23230 23231 23232 23233 23234 23235 23236 23237 23238 23239 23240 23241 23242 23243 23244 23245 23246 23247 23248 23249 23250 23251 23252 23253 23254 23255 23256 23257 23258 23259 23260 23261 23262 23263 23264 23265 23266 23267 23268 23269 23270 23271 23272 23273 23274 23275 23276 23277 23278 23279 23280 23281 23282 23283 23284 23285 23286 23287 23288 23289 23290 23291 23292 23293 23294 23295 23296 23297 23298 23299 23300 23301 23302 23303 23304 23305 23306 23307 23308 23309 23310 23311 23312 23313 23314 23315 23316 23317 23318 23319 23320 23321 23322 23323 23324 23325 23326 23327 23328 23329 23330 23331 23332 23333 23334 23335 23336 23337 23338 23339 23340 23341 23342 23343 23344 23345 23346 23347 23348 23349 23350 23351 23352 23353 23354 23355 23356 23357 23358 23359 23360 23361 23362 23363 23364 23365 23366 23367 23368 23369 23370 23371 23372 23373 23374 23375 23376 23377 23378 23379 23380 23381 23382 23383 23384 23385 23386 23387 23388 23389 23390 23391 23392 23393 23394 23395 23396 23397 23398 23399 23400 23401 23402 23403 23404 23405 23406 23407 23408 23409 23410 23411 23412 23413 23414 23415 23416 23417 23418 23419 23420 23421 23422 23423 23424 23425 23426 23427 23428 23429 23430 23431 23432 23433 23434 23435 23436 23437 23438 23439 23440 23441 23442 23443 23444 23445 23446 23447 23448 23449 23450 23451 23452 23453 23454 23455 23456 23457 23458 23459 23460 23461 23462 23463 23464 23465 23466 23467 23468 23469 23470 23471 23472 23473 23474 23475 23476 23477 23478 23479 23480 23481 23482 23483 23484 23485 23486 23487 23488 23489 23490 23491 23492 23493 23494 23495 23496 23497 23498 23499 23500 23501 23502 23503 23504 23505 23506 23507 23508 23509 23510 23511 23512 23513 23514 23515 23516 23517 23518 23519 23520 23521 23522 23523 23524 23525 23526 23527 23528 23529 23530 23531 23532 23533 23534 23535 23536 23537 23538 23539 23540 23541 23542 23543 23544 23545 23546 23547 23548 23549 23550 23551 23552 23553 23554 23555 23556 23557 23558 23559 23560 23561 23562 23563 23564 23565 23566 23567 23568 23569 23570 23571 23572 23573 23574 23575 23576 23577 23578 23579 23580 23581 23582 23583 23584 23585 23586 23587 23588 23589 23590 23591 23592 23593 23594 23595 23596 23597 23598 23599 23600 23601 23602 23603 23604 23605 23606 23607 23608 23609 23610 23611 23612 23613 23614 23615 23616 23617 23618 23619 23620 23621 23622 23623 23624 23625 23626 23627 23628 23629 23630 23631 23632 23633 23634 23635 23636 23637 23638 23639 23640 23641 23642 23643 23644 23645 23646 23647 23648 23649 23650 23651 23652 23653 23654 23655 23656 23657 23658 23659 23660 23661 23662 23663 23664 23665 23666 23667 23668 23669 23670 23671 23672 23673 23674 23675 23676 23677 23678 23679 23680 23681 23682 23683 23684 23685 23686 23687 23688 23689 23690 23691 23692 23693 23694 23695 23696 23697 23698 23699 23700 23701 23702 23703 23704 23705 23706 23707 23708 23709 23710 23711 23712 23713 23714 23715 23716 23717 23718 23719 23720 23721 23722 23723 23724 23725 23726 23727 23728 23729 23730 23731 23732 23733 23734 23735 23736 23737 23738 23739 23740 23741 23742 23743 23744 23745 23746 23747 23748 23749 23750 23751 23752 23753 23754 23755 23756 23757 23758 23759 23760 23761 23762 23763 23764 23765 23766 23767 23768 23769 23770 23771 23772 23773 23774 23775 23776 23777 23778 23779 23780 23781 23782 23783 23784 23785 23786 23787 23788 23789 23790 23791 23792 23793 23794 23795 23796 23797 23798 23799 23800 23801 23802 23803 23804 23805 23806 23807 23808 23809 23810 23811 23812 23813 23814 23815 23816 23817 23818 23819 23820 23821 23822 23823 23824 23825 23826 23827 23828 23829 23830 23831 23832 23833 23834 23835 23836 23837 23838 23839 23840 23841 23842 23843 23844 23845 23846 23847 23848 23849 23850 23851 23852 23853 23854 23855 23856 23857 23858 23859 23860 23861 23862 23863 23864 23865 23866 23867 23868 23869 23870 23871 23872 23873 23874 23875 23876 23877 23878 23879 23880 23881 23882 23883 23884 23885 23886 23887 23888 23889 23890 23891 23892 23893 23894 23895 23896 23897 23898 23899 23900 23901 23902 23903 23904 23905 23906 23907 23908 23909 23910 23911 23912 23913 23914 23915 23916 23917 23918 23919 23920 23921 23922 23923 23924 23925 23926 23927 23928 23929 23930 23931 23932 23933 23934 23935 23936 23937 23938 23939 23940 23941 23942 23943 23944 23945 23946 23947 23948 23949 23950 23951 23952 23953 23954 23955 23956 23957 23958 23959 23960 23961 23962 23963 23964 23965 23966 23967 23968 23969 23970 23971 23972 23973 23974 23975 23976 23977 23978 23979 23980 23981 23982 23983 23984 23985 23986 23987 23988 23989 23990 23991 23992 23993 23994 23995 23996 23997 23998 23999 24000 24001 24002 24003 24004 24005 24006 24007 24008 24009 24010 24011 24012 24013 24014 24015 24016 24017 24018 24019 24020 24021 24022 24023 24024 24025 24026 24027 24028 24029 24030 24031 24032 24033 24034 24035 24036 24037 24038 24039 24040 24041 24042 24043 24044 24045 24046 24047 24048 24049 24050 24051 24052 24053 24054 24055 24056 24057 24058 24059 24060 24061 24062 24063 24064 24065 24066 24067 24068 24069 24070 24071 24072 24073 24074 24075 24076 24077 24078 24079 24080 24081 24082 24083 24084 24085 24086 24087 24088 24089 24090 24091 24092 24093 24094 24095 24096 24097 24098 24099 24100 24101 24102 24103 24104 24105 24106 24107 24108 24109 24110 24111 24112 24113 24114 24115 24116 24117 24118 24119 24120 24121 24122 24123 24124 24125 24126 24127 24128 24129 24130 24131 24132 24133 24134 24135 24136 24137 24138 24139 24140 24141 24142 24143 24144 24145 24146 24147 24148 24149 24150 24151 24152 24153 24154 24155 24156 24157 24158 24159 24160 24161 24162 24163 24164 24165 24166 24167 24168 24169 24170 24171 24172 24173 24174 24175 24176 24177 24178 24179 24180 24181 24182 24183 24184 24185 24186 24187 24188 24189 24190 24191 24192 24193 24194 24195 24196 24197 24198 24199 24200 24201 24202 24203 24204 24205 24206 24207 24208 24209 24210 24211 24212 24213 24214 24215 24216 24217 24218 24219 24220 24221 24222 24223 24224 24225 24226 24227 24228 24229 24230 24231 24232 24233 24234 24235 24236 24237 24238 24239 24240 24241 24242 24243 24244 24245 24246 24247 24248 24249 24250 24251 24252 24253 24254 24255 24256 24257 24258 24259 24260 24261 24262 24263 24264 24265 24266 24267 24268 24269 24270 24271 24272 24273 24274 24275 24276 24277 24278 24279 24280 24281 24282 24283 24284 24285 24286 24287 24288 24289 24290 24291 24292 24293 24294 24295 24296 24297 24298 24299 24300 24301 24302 24303 24304 24305 24306 24307 24308 24309 24310 24311 24312 24313 24314 24315 24316 24317 24318 24319 24320 24321 24322 24323 24324 24325 24326 24327 24328 24329 24330 24331 24332 24333 24334 24335 24336 24337 24338 24339 24340 24341 24342 24343 24344 24345 24346 24347 24348 24349 24350 24351 24352 24353 24354 24355 24356 24357 24358 24359 24360 24361 24362 24363 24364 24365 24366 24367 24368 24369 24370 24371 24372 24373 24374 24375 24376 24377 24378 24379 24380 24381 24382 24383 24384 24385 24386 24387 24388 24389 24390 24391 24392 24393 24394 24395 24396 24397 24398 24399 24400 24401 24402 24403 24404 24405 24406 24407 24408 24409 24410 24411 24412 24413 24414 24415 24416 24417 24418 24419 24420 24421 24422 24423 24424 24425 24426 24427 24428 24429 24430 24431 24432 24433 24434 24435 24436 24437 24438 24439 24440 24441 24442 24443 24444 24445 24446 24447 24448 24449 24450 24451 24452 24453 24454 24455 24456 24457 24458 24459 24460 24461 24462 24463 24464 24465 24466 24467 24468 24469 24470 24471 24472 24473 24474 24475 24476 24477 24478 24479 24480 24481 24482 24483 24484 24485 24486 24487 24488 24489 24490 24491 24492 24493 24494 24495 24496 24497 24498 24499 24500 24501 24502 24503 24504 24505 24506 24507 24508 24509 24510 24511 24512 24513 24514 24515 24516 24517 24518 24519 24520 24521 24522 24523 24524 24525 24526 24527 24528 24529 24530 24531 24532 24533 24534 24535 24536 24537 24538 24539 24540 24541 24542 24543 24544 24545 24546 24547 24548 24549 24550 24551 24552 24553 24554 24555 24556 24557 24558 24559 24560 24561 24562 24563 24564 24565 24566 24567 24568 24569 24570 24571 24572 24573 24574 24575 24576 24577 24578 24579 24580 24581 24582 24583 24584 24585 24586 24587 24588 24589 24590 24591 24592 24593 24594 24595 24596 24597 24598 24599 24600 24601 24602 24603 24604 24605 24606 24607 24608 24609 24610 24611 24612 24613 24614 24615 24616 24617 24618 24619 24620 24621 24622 24623 24624 24625 24626 24627 24628 24629 24630 24631 24632 24633 24634 24635 24636 24637 24638 24639 24640 24641 24642 24643 24644 24645 24646 24647 24648 24649 24650 24651 24652 24653 24654 24655 24656 24657 24658 24659 24660 24661 24662 24663 24664 24665 24666 24667 24668 24669 24670 24671 24672 24673 24674 24675 24676 24677 24678 24679 24680 24681 24682 24683 24684 24685 24686 24687 24688 24689 24690 24691 24692 24693 24694 24695 24696 24697 24698 24699 24700 24701 24702 24703 24704 24705 24706 24707 24708 24709 24710 24711 24712 24713 24714 24715 24716 24717 24718 24719 24720 24721 24722 24723 24724 24725 24726 24727 24728 24729 24730 24731 24732 24733 24734 24735 24736 24737 24738 24739 24740 24741 24742 24743 24744 24745 24746 24747 24748 24749 24750 24751 24752 24753 24754 24755 24756 24757 24758 24759 24760 24761 24762 24763 24764 24765 24766 24767 24768 24769 24770 24771 24772 24773 24774 24775 24776 24777 24778 24779 24780 24781 24782 24783 24784 24785 24786 24787 24788 24789 24790 24791 24792 24793 24794 24795 24796 24797 24798 24799 24800 24801 24802 24803 24804 24805 24806 24807 24808 24809 24810 24811 24812 24813 24814 24815 24816 24817 24818 24819 24820 24821 24822 24823 24824 24825 24826 24827 24828 24829 24830 24831 24832 24833 24834 24835 24836 24837 24838 24839 24840 24841 24842 24843 24844 24845 24846 24847 24848 24849 24850 24851 24852 24853 24854 24855 24856 24857 24858 24859 24860 24861 24862 24863 24864 24865 24866 24867 24868 24869 24870 24871 24872 24873 24874 24875 24876 24877 24878 24879 24880 24881 24882 24883 24884 24885 24886 24887 24888 24889 24890 24891 24892 24893 24894 24895 24896 24897 24898 24899 24900 24901 24902 24903 24904 24905 24906 24907 24908 24909 24910 24911 24912 24913 24914 24915 24916 24917 24918 24919 24920 24921 24922 24923 24924 24925 24926 24927 24928 24929 24930 24931 24932 24933 24934 24935 24936 24937 24938 24939 24940 24941 24942 24943 24944 24945 24946 24947 24948 24949 24950 24951 24952 24953 24954 24955 24956 24957 24958 24959 24960 24961 24962 24963 24964 24965 24966 24967 24968 24969 24970 24971 24972 24973 24974 24975 24976 24977 24978 24979 24980 24981 24982 24983 24984 24985 24986 24987 24988 24989 24990 24991 24992 24993 24994 24995 24996 24997 24998 24999 25000 25001 25002 25003 25004 25005 25006 25007 25008 25009 25010 25011 25012 25013 25014 25015 25016 25017 25018 25019 25020 25021 25022 25023 25024 25025 25026 25027 25028 25029 25030 25031 25032 25033 25034 25035 25036 25037 25038 25039 25040 25041 25042 25043 25044 25045 25046 25047 25048 25049 25050 25051 25052 25053 25054 25055 25056 25057 25058 25059 25060 25061 25062 25063 25064 25065 25066 25067 25068 25069 25070 25071 25072 25073 25074 25075 25076 25077 25078 25079 25080 25081 25082 25083 25084 25085 25086 25087 25088 25089 25090 25091 25092 25093 25094 25095 25096 25097 25098 25099 25100 25101 25102 25103 25104 25105 25106 25107 25108 25109 25110 25111 25112 25113 25114 25115 25116 25117 25118 25119 25120 25121 25122 25123 25124 25125 25126 25127 25128 25129 25130 25131 25132 25133 25134 25135 25136 25137 25138 25139 25140 25141 25142 25143 25144 25145 25146 25147 25148 25149 25150 25151 25152 25153 25154 25155 25156 25157 25158 25159 25160 25161 25162 25163 25164 25165 25166 25167 25168 25169 25170 25171 25172 25173 25174 25175 25176 25177 25178 25179 25180 25181 25182 25183 25184 25185 25186 25187 25188 25189 25190 25191 25192 25193 25194 25195 25196 25197 25198 25199 25200 25201 25202 25203 25204 25205 25206 25207 25208 25209 25210 25211 25212 25213 25214 25215 25216 25217 25218 25219 25220 25221 25222 25223 25224 25225 25226 25227 25228 25229 25230 25231 25232 25233 25234 25235 25236 25237 25238 25239 25240 25241 25242 25243 25244 25245 25246 25247 25248 25249 25250 25251 25252 25253 25254 25255 25256 25257 25258 25259 25260 25261 25262 25263 25264 25265 25266 25267 25268 25269 25270 25271 25272 25273 25274 25275 25276 25277 25278 25279 25280 25281 25282 25283 25284 25285 25286 25287 25288 25289 25290 25291 25292 25293 25294 25295 25296 25297 25298 25299 25300 25301 25302 25303 25304 25305 25306 25307 25308 25309 25310 25311 25312 25313 25314 25315 25316 25317 25318 25319 25320 25321 25322 25323 25324 25325 25326 25327 25328 25329 25330 25331 25332 25333 25334 25335 25336 25337 25338 25339 25340 25341 25342 25343 25344 25345 25346 25347 25348 25349 25350 25351 25352 25353 25354 25355 25356 25357 25358 25359 25360 25361 25362 25363 25364 25365 25366 25367 25368 25369 25370 25371 25372 25373 25374 25375 25376 25377 25378 25379 25380 25381 25382 25383 25384 25385 25386 25387 25388 25389 25390 25391 25392 25393 25394 25395 25396 25397 25398 25399 25400 25401 25402 25403 25404 25405 25406 25407 25408 25409 25410 25411 25412 25413 25414 25415 25416 25417 25418 25419 25420 25421 25422 25423 25424 25425 25426 25427 25428 25429 25430 25431 25432 25433 25434 25435 25436 25437 25438 25439 25440 25441 25442 25443 25444 25445 25446 25447 25448 25449 25450 25451 25452 25453 25454 25455 25456 25457 25458 25459 25460 25461 25462 25463 25464 25465 25466 25467 25468 25469 25470 25471 25472 25473 25474 25475 25476 25477 25478 25479 25480 25481 25482 25483 25484 25485 25486 25487 25488 25489 25490 25491 25492 25493 25494 25495 25496 25497 25498 25499 25500 25501 25502 25503 25504 25505 25506 25507 25508 25509 25510 25511 25512 25513 25514 25515 25516 25517 25518 25519 25520 25521 25522 25523 25524 25525 25526 25527 25528 25529 25530 25531 25532 25533 25534 25535 25536 25537 25538 25539 25540 25541 25542 25543 25544 25545 25546 25547 25548 25549 25550 25551 25552 25553 25554 25555 25556 25557 25558 25559 25560 25561 25562 25563 25564 25565 25566 25567 25568 25569 25570 25571 25572 25573 25574 25575 25576 25577 25578 25579 25580 25581 25582 25583 25584 25585 25586 25587 25588 25589 25590 25591 25592 25593 25594 25595 25596 25597 25598 25599 25600 25601 25602 25603 25604 25605 25606 25607 25608 25609 25610 25611 25612 25613 25614 25615 25616 25617 25618 25619 25620 25621 25622 25623 25624 25625 25626 25627 25628 25629 25630 25631 25632 25633 25634 25635 25636 25637 25638 25639 25640 25641 25642 25643 25644 25645 25646 25647 25648 25649 25650 25651 25652 25653 25654 25655 25656 25657 25658 25659 25660 25661 25662 25663 25664 25665 25666 25667 25668 25669 25670 25671 25672 25673 25674 25675 25676 25677 25678 25679 25680 25681 25682 25683 25684 25685 25686 25687 25688 25689 25690 25691 25692 25693 25694 25695 25696 25697 25698 25699 25700 25701 25702 25703 25704 25705 25706 25707 25708 25709 25710 25711 25712 25713 25714 25715 25716 25717 25718 25719 25720 25721 25722 25723 25724 25725 25726 25727 25728 25729 25730 25731 25732 25733 25734 25735 25736 25737 25738 25739 25740 25741 25742 25743 25744 25745 25746 25747 25748 25749 25750 25751 25752 25753 25754 25755 25756 25757 25758 25759 25760 25761 25762 25763 25764 25765 25766 25767 25768 25769 25770 25771 25772 25773 25774 25775 25776 25777 25778 25779 25780 25781 25782 25783 25784 25785 25786 25787 25788 25789 25790 25791 25792 25793 25794 25795 25796 25797 25798 25799 25800 25801 25802 25803 25804 25805 25806 25807 25808 25809 25810 25811 25812 25813 25814 25815 25816 25817 25818 25819 25820 25821 25822 25823 25824 25825 25826 25827 25828 25829 25830 25831 25832 25833 25834 25835 25836 25837 25838 25839 25840 25841 25842 25843 25844 25845 25846 25847 25848 25849 25850 25851 25852 25853 25854 25855 25856 25857 25858 25859 25860 25861 25862 25863 25864 25865 25866 25867 25868 25869 25870 25871 25872 25873 25874 25875 25876 25877 25878 25879 25880 25881 25882 25883 25884 25885 25886 25887 25888 25889 25890 25891 25892 25893 25894 25895 25896 25897 25898 25899 25900 25901 25902 25903 25904 25905 25906 25907 25908 25909 25910 25911 25912 25913 25914 25915 25916 25917 25918 25919 25920 25921 25922 25923 25924 25925 25926 25927 25928 25929 25930 25931 25932 25933 25934 25935 25936 25937 25938 25939 25940 25941 25942 25943 25944 25945 25946 25947 25948 25949 25950 25951 25952 25953 25954 25955 25956 25957 25958 25959 25960 25961 25962 25963 25964 25965 25966 25967 25968 25969 25970 25971 25972 25973 25974 25975 25976 25977 25978 25979 25980 25981 25982 25983 25984 25985 25986 25987 25988 25989 25990 25991 25992 25993 25994 25995 25996 25997 25998 25999 26000 26001 26002 26003 26004 26005 26006 26007 26008 26009 26010 26011 26012 26013 26014 26015 26016 26017 26018 26019 26020 26021 26022 26023 26024 26025 26026 26027 26028 26029 26030 26031 26032 26033 26034 26035 26036 26037 26038 26039 26040 26041 26042 26043 26044 26045 26046 26047 26048 26049 26050 26051 26052 26053 26054 26055 26056 26057 26058 26059 26060 26061 26062 26063 26064 26065 26066 26067 26068 26069 26070 26071 26072 26073 26074 26075 26076 26077 26078 26079 26080 26081 26082 26083 26084 26085 26086 26087 26088 26089 26090 26091 26092 26093 26094 26095 26096 26097 26098 26099 26100 26101 26102 26103 26104 26105 26106 26107 26108 26109 26110 26111 26112 26113 26114 26115 26116 26117 26118 26119 26120 26121 26122 26123 26124 26125 26126 26127 26128 26129 26130 26131 26132 26133 26134 26135 26136 26137 26138 26139 26140 26141 26142 26143 26144 26145 26146 26147 26148 26149 26150 26151 26152 26153 26154 26155 26156 26157 26158 26159 26160 26161 26162 26163 26164 26165 26166 26167 26168 26169 26170 26171 26172 26173 26174 26175 26176 26177 26178 26179 26180 26181 26182 26183 26184 26185 26186 26187 26188 26189 26190 26191 26192 26193 26194 26195 26196 26197 26198 26199 26200 26201 26202 26203 26204 26205 26206 26207 26208 26209 26210 26211 26212 26213 26214 26215 26216 26217 26218 26219 26220 26221 26222 26223 26224 26225 26226 26227 26228 26229 26230 26231 26232 26233 26234 26235 26236 26237 26238 26239 26240 26241 26242 26243 26244 26245 26246 26247 26248 26249 26250 26251 26252 26253 26254 26255 26256 26257 26258 26259 26260 26261 26262 26263 26264 26265 26266 26267 26268 26269 26270 26271 26272 26273 26274 26275 26276 26277 26278 26279 26280 26281 26282 26283 26284 26285 26286 26287 26288 26289 26290 26291 26292 26293 26294 26295 26296 26297 26298 26299 26300 26301 26302 26303 26304 26305 26306 26307 26308 26309 26310 26311 26312 26313 26314 26315 26316 26317 26318 26319 26320 26321 26322 26323 26324 26325 26326 26327 26328 26329 26330 26331 26332 26333 26334 26335 26336 26337 26338 26339 26340 26341 26342 26343 26344 26345 26346 26347 26348 26349 26350 26351 26352 26353 26354 26355 26356 26357 26358 26359 26360 26361 26362 26363 26364 26365 26366 26367 26368 26369 26370 26371 26372 26373 26374 26375 26376 26377 26378 26379 26380 26381 26382 26383 26384 26385 26386 26387 26388 26389 26390 26391 26392 26393 26394 26395 26396 26397 26398 26399 26400 26401 26402 26403 26404 26405 26406 26407 26408 26409 26410 26411 26412 26413 26414 26415 26416 26417 26418 26419 26420 26421 26422 26423 26424 26425 26426 26427 26428 26429 26430 26431 26432 26433 26434 26435 26436 26437 26438 26439 26440 26441 26442 26443 26444 26445 26446 26447 26448 26449 26450 26451 26452 26453 26454 26455 26456 26457 26458 26459 26460 26461 26462 26463 26464 26465 26466 26467 26468 26469 26470 26471 26472 26473 26474 26475 26476 26477 26478 26479 26480 26481 26482 26483 26484 26485 26486 26487 26488 26489 26490 26491 26492 26493 26494 26495 26496 26497 26498 26499 26500 26501 26502 26503 26504 26505 26506 26507 26508 26509 26510 26511 26512 26513 26514 26515 26516 26517 26518 26519 26520 26521 26522 26523 26524 26525 26526 26527 26528 26529 26530 26531 26532 26533 26534 26535 26536 26537 26538 26539 26540 26541 26542 26543 26544 26545 26546 26547 26548 26549 26550 26551 26552 26553 26554 26555 26556 26557 26558 26559 26560 26561 26562 26563 26564 26565 26566 26567 26568 26569 26570 26571 26572 26573 26574 26575 26576 26577 26578 26579 26580 26581 26582 26583 26584 26585 26586 26587 26588 26589 26590 26591 26592 26593 26594 26595 26596 26597 26598 26599 26600 26601 26602 26603 26604 26605 26606 26607 26608 26609 26610 26611 26612 26613 26614 26615 26616 26617 26618 26619 26620 26621 26622 26623 26624 26625 26626 26627 26628 26629 26630 26631 26632 26633 26634 26635 26636 26637 26638 26639 26640 26641 26642 26643 26644 26645 26646 26647 26648 26649 26650 26651 26652 26653 26654 26655 26656 26657 26658 26659 26660 26661 26662 26663 26664 26665 26666 26667 26668 26669 26670 26671 26672 26673 26674 26675 26676 26677 26678 26679 26680 26681 26682 26683 26684 26685 26686 26687 26688 26689 26690 26691 26692 26693 26694 26695 26696 26697 26698 26699 26700 26701 26702 26703 26704 26705 26706 26707 26708 26709 26710 26711 26712 26713 26714 26715 26716 26717 26718 26719 26720 26721 26722 26723 26724 26725 26726 26727 26728 26729 26730 26731 26732 26733 26734 26735 26736 26737 26738 26739 26740 26741 26742 26743 26744 26745 26746 26747 26748 26749 26750 26751 26752 26753 26754 26755 26756 26757 26758 26759 26760 26761 26762 26763 26764 26765 26766 26767 26768 26769 26770 26771 26772 26773 26774 26775 26776 26777 26778 26779 26780 26781 26782 26783 26784 26785 26786 26787 26788 26789 26790 26791 26792 26793 26794 26795 26796 26797 26798 26799 26800 26801 26802 26803 26804 26805 26806 26807 26808 26809 26810 26811 26812 26813 26814 26815 26816 26817 26818 26819 26820 26821 26822 26823 26824 26825 26826 26827 26828 26829 26830 26831 26832 26833 26834 26835 26836 26837 26838 26839 26840 26841 26842 26843 26844 26845 26846 26847 26848 26849 26850 26851 26852 26853 26854 26855 26856 26857 26858 26859 26860 26861 26862 26863 26864 26865 26866 26867 26868 26869 26870 26871 26872 26873 26874 26875 26876 26877 26878 26879 26880 26881 26882 26883 26884 26885 26886 26887 26888 26889 26890 26891 26892 26893 26894 26895 26896 26897 26898 26899 26900 26901 26902 26903 26904 26905 26906 26907 26908 26909 26910 26911 26912 26913 26914 26915 26916 26917 26918 26919 26920 26921 26922 26923 26924 26925 26926 26927 26928 26929 26930 26931 26932 26933 26934 26935 26936 26937 26938 26939 26940 26941 26942 26943 26944 26945 26946 26947 26948 26949 26950 26951 26952 26953 26954 26955 26956 26957 26958 26959 26960 26961 26962 26963 26964 26965 26966 26967 26968 26969 26970 26971 26972 26973 26974 26975 26976 26977 26978 26979 26980 26981 26982 26983 26984 26985 26986 26987 26988 26989 26990 26991 26992 26993 26994 26995 26996 26997 26998 26999 27000 27001 27002 27003 27004 27005 27006 27007 27008 27009 27010 27011 27012 27013 27014 27015 27016 27017 27018 27019 27020 27021 27022 27023 27024 27025 27026 27027 27028 27029 27030 27031 27032 27033 27034 27035 27036 27037 27038 27039 27040 27041 27042 27043 27044 27045 27046 27047 27048 27049 27050 27051 27052 27053 27054 27055 27056 27057 27058 27059 27060 27061 27062 27063 27064 27065 27066 27067 27068 27069 27070 27071 27072 27073 27074 27075 27076 27077 27078 27079 27080 27081 27082 27083 27084 27085 27086 27087 27088 27089 27090 27091 27092 27093 27094 27095 27096 27097 27098 27099 27100 27101 27102 27103 27104 27105 27106 27107 27108 27109 27110 27111 27112 27113 27114 27115 27116 27117 27118 27119 27120 27121 27122 27123 27124 27125 27126 27127 27128 27129 27130 27131 27132 27133 27134 27135 27136 27137 27138 27139 27140 27141 27142 27143 27144 27145 27146 27147 27148 27149 27150 27151 27152 27153 27154 27155 27156 27157 27158 27159 27160 27161 27162 27163 27164 27165 27166 27167 27168 27169 27170 27171 27172 27173 27174 27175 27176 27177 27178 27179 27180 27181 27182 27183 27184 27185 27186 27187 27188 27189 27190 27191 27192 27193 27194 27195 27196 27197 27198 27199 27200 27201 27202 27203 27204 27205 27206 27207 27208 27209 27210 27211 27212 27213 27214 27215 27216 27217 27218 27219 27220 27221 27222 27223 27224 27225 27226 27227 27228 27229 27230 27231 27232 27233 27234 27235 27236 27237 27238 27239 27240 27241 27242 27243 27244 27245 27246 27247 27248 27249 27250 27251 27252 27253 27254 27255 27256 27257 27258 27259 27260 27261 27262 27263 27264 27265 27266 27267 27268 27269 27270 27271 27272 27273 27274 27275 27276 27277 27278 27279 27280 27281 27282 27283 27284 27285 27286 27287 27288 27289 27290 27291 27292 27293 27294 27295 27296 27297 27298 27299 27300 27301 27302 27303 27304 27305 27306 27307 27308 27309 27310 27311 27312 27313 27314 27315 27316 27317 27318 27319 27320 27321 27322 27323 27324 27325 27326 27327 27328 27329 27330 27331 27332 27333 27334 27335 27336 27337 27338 27339 27340 27341 27342 27343 27344 27345 27346 27347 27348 27349 27350 27351 27352 27353 27354 27355 27356 27357 27358 27359 27360 27361 27362 27363 27364 27365 27366 27367 27368 27369 27370 27371 27372 27373 27374 27375 27376 27377 27378 27379 27380 27381 27382 27383 27384 27385 27386 27387 27388 27389 27390 27391 27392 27393 27394 27395 27396 27397 27398 27399 27400 27401 27402 27403 27404 27405 27406 27407 27408 27409 27410 27411 27412 27413 27414 27415 27416 27417 27418 27419 27420 27421 27422 27423 27424 27425 27426 27427 27428 27429 27430 27431 27432 27433 27434 27435 27436 27437 27438 27439 27440 27441 27442 27443 27444 27445 27446 27447 27448 27449 27450 27451 27452 27453 27454 27455 27456 27457 27458 27459 27460 27461 27462 27463 27464 27465 27466 27467 27468 27469 27470 27471 27472 27473 27474 27475 27476 27477 27478 27479 27480 27481 27482 27483 27484 27485 27486 27487 27488 27489 27490 27491 27492 27493 27494 27495 27496 27497 27498 27499 27500 27501 27502 27503 27504 27505 27506 27507 27508 27509 27510 27511 27512 27513 27514 27515 27516 27517 27518 27519 27520 27521 27522 27523 27524 27525 27526 27527 27528 27529 27530 27531 27532 27533 27534 27535 27536 27537 27538 27539 27540 27541 27542 27543 27544 27545 27546 27547 27548 27549 27550 27551 27552 27553 27554 27555 27556 27557 27558 27559 27560 27561 27562 27563 27564 27565 27566 27567 27568 27569 27570 27571 27572 27573 27574 27575 27576 27577 27578 27579 27580 27581 27582 27583 27584 27585 27586 27587 27588 27589 27590 27591 27592 27593 27594 27595 27596 27597 27598 27599 27600 27601 27602 27603 27604 27605 27606 27607 27608 27609 27610 27611 27612 27613 27614 27615 27616 27617 27618 27619 27620 27621 27622 27623 27624 27625 27626 27627 27628 27629 27630 27631 27632 27633 27634 27635 27636 27637 27638 27639 27640 27641 27642 27643 27644 27645 27646 27647 27648 27649 27650 27651 27652 27653 27654 27655 27656 27657 27658 27659 27660 27661 27662 27663 27664 27665 27666 27667 27668 27669 27670 27671 27672 27673 27674 27675 27676 27677 27678 27679 27680 27681 27682 27683 27684 27685 27686 27687 27688 27689 27690 27691 27692 27693 27694 27695 27696 27697 27698 27699 27700 27701 27702 27703 27704 27705 27706 27707 27708 27709 27710 27711 27712 27713 27714 27715 27716 27717 27718 27719 27720 27721 27722 27723 27724 27725 27726 27727 27728 27729 27730 27731 27732 27733 27734 27735 27736 27737 27738 27739 27740 27741 27742 27743 27744 27745 27746 27747 27748 27749 27750 27751 27752 27753 27754 27755 27756 27757 27758 27759 27760 27761 27762 27763 27764 27765 27766 27767 27768 27769 27770 27771 27772 27773 27774 27775 27776 27777 27778 27779 27780 27781 27782 27783 27784 27785 27786 27787 27788 27789 27790 27791 27792 27793 27794 27795 27796 27797 27798 27799 27800 27801 27802 27803 27804 27805 27806 27807 27808 27809 27810 27811 27812 27813 27814 27815 27816 27817 27818 27819 27820 27821 27822 27823 27824 27825 27826 27827 27828 27829 27830 27831 27832 27833 27834 27835 27836 27837 27838 27839 27840 27841 27842 27843 27844 27845 27846 27847 27848 27849 27850 27851 27852 27853 27854 27855 27856 27857 27858 27859 27860 27861 27862 27863 27864 27865 27866 27867 27868 27869 27870 27871 27872 27873 27874 27875 27876 27877 27878 27879 27880 27881 27882 27883 27884 27885 27886 27887 27888 27889 27890 27891 27892 27893 27894 27895 27896 27897 27898 27899 27900 27901 27902 27903 27904 27905 27906 27907 27908 27909 27910 27911 27912 27913 27914 27915 27916 27917 27918 27919 27920 27921 27922 27923 27924 27925 27926 27927 27928 27929 27930 27931 27932 27933 27934 27935 27936 27937 27938 27939 27940 27941 27942 27943 27944 27945 27946 27947 27948 27949 27950 27951 27952 27953 27954 27955 27956 27957 27958 27959 27960 27961 27962 27963 27964 27965 27966 27967 27968 27969 27970 27971 27972 27973 27974 27975 27976 27977 27978 27979 27980 27981 27982 27983 27984 27985 27986 27987 27988 27989 27990 27991 27992 27993 27994 27995 27996 27997 27998 27999 28000 28001 28002 28003 28004 28005 28006 28007 28008 28009 28010 28011 28012 28013 28014 28015 28016 28017 28018 28019 28020 28021 28022 28023 28024 28025 28026 28027 28028 28029 28030 28031 28032 28033 28034 28035 28036 28037 28038 28039 28040 28041 28042 28043 28044 28045 28046 28047 28048 28049 28050 28051 28052 28053 28054 28055 28056 28057 28058 28059 28060 28061 28062 28063 28064 28065 28066 28067 28068 28069 28070 28071 28072 28073 28074 28075 28076 28077 28078 28079 28080 28081 28082 28083 28084 28085 28086 28087 28088 28089 28090 28091 28092 28093 28094 28095 28096 28097 28098 28099 28100 28101 28102 28103 28104 28105 28106 28107 28108 28109 28110 28111 28112 28113 28114 28115 28116 28117 28118 28119 28120 28121 28122 28123 28124 28125 28126 28127 28128 28129 28130 28131 28132 28133 28134 28135 28136 28137 28138 28139 28140 28141 28142 28143 28144 28145 28146 28147 28148 28149 28150 28151 28152 28153 28154 28155 28156 28157 28158 28159 28160 28161 28162 28163 28164 28165 28166 28167 28168 28169 28170 28171 28172 28173 28174 28175 28176 28177 28178 28179 28180 28181 28182 28183 28184 28185 28186 28187 28188 28189 28190 28191 28192 28193 28194 28195 28196 28197 28198 28199 28200 28201 28202 28203 28204 28205 28206 28207 28208 28209 28210 28211 28212 28213 28214 28215 28216 28217 28218 28219 28220 28221 28222 28223 28224 28225 28226 28227 28228 28229 28230 28231 28232 28233 28234 28235 28236 28237 28238 28239 28240 28241 28242 28243 28244 28245 28246 28247 28248 28249 28250 28251 28252 28253 28254 28255 28256 28257 28258 28259 28260 28261 28262 28263 28264 28265 28266 28267 28268 28269 28270 28271 28272 28273 28274 28275 28276 28277 28278 28279 28280 28281 28282 28283 28284 28285 28286 28287 28288 28289 28290 28291 28292 28293 28294 28295 28296 28297 28298 28299 28300 28301 28302 28303 28304 28305 28306 28307 28308 28309 28310 28311 28312 28313 28314 28315 28316 28317 28318 28319 28320 28321 28322 28323 28324 28325 28326 28327 28328 28329 28330 28331 28332 28333 28334 28335 28336 28337 28338 28339 28340 28341 28342 28343 28344 28345 28346 28347 28348 28349 28350 28351 28352 28353 28354 28355 28356 28357 28358 28359 28360 28361 28362 28363 28364 28365 28366 28367 28368 28369 28370 28371 28372 28373 28374 28375 28376 28377 28378 28379 28380 28381 28382 28383 28384 28385 28386 28387 28388 28389 28390 28391 28392 28393 28394 28395 28396 28397 28398 28399 28400 28401 28402 28403 28404 28405 28406 28407 28408 28409 28410 28411 28412 28413 28414 28415 28416 28417 28418 28419 28420 28421 28422 28423 28424 28425 28426 28427 28428 28429 28430 28431 28432 28433 28434 28435 28436 28437 28438 28439 28440 28441 28442 28443 28444 28445 28446 28447 28448 28449 28450 28451 28452 28453 28454 28455 28456 28457 28458 28459 28460 28461 28462 28463 28464 28465 28466 28467 28468 28469 28470 28471 28472 28473 28474 28475 28476 28477 28478 28479 28480 28481 28482 28483 28484 28485 28486 28487 28488 28489 28490 28491 28492 28493 28494 28495 28496 28497 28498 28499 28500 28501 28502 28503 28504 28505 28506 28507 28508 28509 28510 28511 28512 28513 28514 28515 28516 28517 28518 28519 28520 28521 28522 28523 28524 28525 28526 28527 28528 28529 28530 28531 28532 28533 28534 28535 28536 28537 28538 28539 28540 28541 28542 28543 28544 28545 28546 28547 28548 28549 28550 28551 28552 28553 28554 28555 28556 28557 28558 28559 28560 28561 28562 28563 28564 28565 28566 28567 28568 28569 28570 28571 28572 28573 28574 28575 28576 28577 28578 28579 28580 28581 28582 28583 28584 28585 28586 28587 28588 28589 28590 28591 28592 28593 28594 28595 28596 28597 28598 28599 28600 28601 28602 28603 28604 28605 28606 28607 28608 28609 28610 28611 28612 28613 28614 28615 28616 28617 28618 28619 28620 28621 28622 28623 28624 28625 28626 28627 28628 28629 28630 28631 28632 28633 28634 28635 28636 28637 28638 28639 28640 28641 28642 28643 28644 28645 28646 28647 28648 28649 28650 28651 28652 28653 28654 28655 28656 28657 28658 28659 28660 28661 28662 28663 28664 28665 28666 28667 28668 28669 28670 28671 28672 28673 28674 28675 28676 28677 28678 28679 28680 28681 28682 28683 28684 28685 28686 28687 28688 28689 28690 28691 28692 28693 28694 28695 28696 28697 28698 28699 28700 28701 28702 28703 28704 28705 28706 28707 28708 28709 28710 28711 28712 28713 28714 28715 28716 28717 28718 28719 28720 28721 28722 28723 28724 28725 28726 28727 28728 28729 28730 28731 28732 28733 28734 28735 28736 28737 28738 28739 28740 28741 28742 28743 28744 28745 28746 28747 28748 28749 28750 28751 28752 28753 28754 28755 28756 28757 28758 28759 28760 28761 28762 28763 28764 28765 28766 28767 28768 28769 28770 28771 28772 28773 28774 28775 28776 28777 28778 28779 28780 28781 28782 28783 28784 28785 28786 28787 28788 28789 28790 28791 28792 28793 28794 28795 28796 28797 28798 28799 28800 28801 28802 28803 28804 28805 28806 28807 28808 28809 28810 28811 28812 28813 28814 28815 28816 28817 28818 28819 28820 28821 28822 28823 28824 28825 28826 28827 28828 28829 28830 28831 28832 28833 28834 28835 28836 28837 28838 28839 28840 28841 28842 28843 28844 28845 28846 28847 28848 28849 28850 28851 28852 28853 28854 28855 28856 28857 28858 28859 28860 28861 28862 28863 28864 28865 28866 28867 28868 28869 28870 28871 28872 28873 28874 28875 28876 28877 28878 28879 28880 28881 28882 28883 28884 28885 28886 28887 28888 28889 28890 28891 28892 28893 28894 28895 28896 28897 28898 28899 28900 28901 28902 28903 28904 28905 28906 28907 28908 28909 28910 28911 28912 28913 28914 28915 28916 28917 28918 28919 28920 28921 28922 28923 28924 28925 28926 28927 28928 28929 28930 28931 28932 28933 28934 28935 28936 28937 28938 28939 28940 28941 28942 28943 28944 28945 28946 28947 28948 28949 28950 28951 28952 28953 28954 28955 28956 28957 28958 28959 28960 28961 28962 28963 28964 28965 28966 28967 28968 28969 28970 28971 28972 28973 28974 28975 28976 28977 28978 28979 28980 28981 28982 28983 28984 28985 28986 28987 28988 28989 28990 28991 28992 28993 28994 28995 28996 28997 28998 28999 29000 29001 29002 29003 29004 29005 29006 29007 29008 29009 29010 29011 29012 29013 29014 29015 29016 29017 29018 29019 29020 29021 29022 29023 29024 29025 29026 29027 29028 29029 29030 29031 29032 29033 29034 29035 29036 29037 29038 29039 29040 29041 29042 29043 29044 29045 29046 29047 29048 29049 29050 29051 29052 29053 29054 29055 29056 29057 29058 29059 29060 29061 29062 29063 29064 29065 29066 29067 29068 29069 29070 29071 29072 29073 29074 29075 29076 29077 29078 29079 29080 29081 29082 29083 29084 29085 29086 29087 29088 29089 29090 29091 29092 29093 29094 29095 29096 29097 29098 29099 29100 29101 29102 29103 29104 29105 29106 29107 29108 29109 29110 29111 29112 29113 29114 29115 29116 29117 29118 29119 29120 29121 29122 29123 29124 29125 29126 29127 29128 29129 29130 29131 29132 29133 29134 29135 29136 29137 29138 29139 29140 29141 29142 29143 29144 29145 29146 29147 29148 29149 29150 29151 29152 29153 29154 29155 29156 29157 29158 29159 29160 29161 29162 29163 29164 29165 29166 29167 29168 29169 29170 29171 29172 29173 29174 29175 29176 29177 29178 29179 29180 29181 29182 29183 29184 29185 29186 29187 29188 29189 29190 29191 29192 29193 29194 29195 29196 29197 29198 29199 29200 29201 29202 29203 29204 29205 29206 29207 29208 29209 29210 29211 29212 29213 29214 29215 29216 29217 29218 29219 29220 29221 29222 29223 29224 29225 29226 29227 29228 29229 29230 29231 29232 29233 29234 29235 29236 29237 29238 29239 29240 29241 29242 29243 29244 29245 29246 29247 29248 29249 29250 29251 29252 29253 29254 29255 29256 29257 29258 29259 29260 29261 29262 29263 29264 29265 29266 29267 29268 29269 29270 29271 29272 29273 29274 29275 29276 29277 29278 29279 29280 29281 29282 29283 29284 29285 29286 29287 29288 29289 29290 29291 29292 29293 29294 29295 29296 29297 29298 29299 29300 29301 29302 29303 29304 29305 29306 29307 29308 29309 29310 29311 29312 29313 29314 29315 29316 29317 29318 29319 29320 29321 29322 29323 29324 29325 29326 29327 29328 29329 29330 29331 29332 29333 29334 29335 29336 29337 29338 29339 29340 29341 29342 29343 29344 29345 29346 29347 29348 29349 29350 29351 29352 29353 29354 29355 29356 29357 29358 29359 29360 29361 29362 29363 29364 29365 29366 29367 29368 29369 29370 29371 29372 29373 29374 29375 29376 29377 29378 29379 29380 29381 29382 29383 29384 29385 29386 29387 29388 29389 29390 29391 29392 29393 29394 29395 29396 29397 29398 29399 29400 29401 29402 29403 29404 29405 29406 29407 29408 29409 29410 29411 29412 29413 29414 29415 29416 29417 29418 29419 29420 29421 29422 29423 29424 29425 29426 29427 29428 29429 29430 29431 29432 29433 29434 29435 29436 29437 29438 29439 29440 29441 29442 29443 29444 29445 29446 29447 29448 29449 29450 29451 29452 29453 29454 29455 29456 29457 29458 29459 29460 29461 29462 29463 29464 29465 29466 29467 29468 29469 29470 29471 29472 29473 29474 29475 29476 29477 29478 29479 29480 29481 29482 29483 29484 29485 29486 29487 29488 29489 29490 29491 29492 29493 29494 29495 29496 29497 29498 29499 29500 29501 29502 29503 29504 29505 29506 29507 29508 29509 29510 29511 29512 29513 29514 29515 29516 29517 29518 29519 29520 29521 29522 29523 29524 29525 29526 29527 29528 29529 29530 29531 29532 29533 29534 29535 29536 29537 29538 29539 29540 29541 29542 29543 29544 29545 29546 29547 29548 29549 29550 29551 29552 29553 29554 29555 29556 29557 29558 29559 29560 29561 29562 29563 29564 29565 29566 29567 29568 29569 29570 29571 29572 29573 29574 29575 29576 29577 29578 29579 29580 29581 29582 29583 29584 29585 29586 29587 29588 29589 29590 29591 29592 29593 29594 29595 29596 29597 29598 29599 29600 29601 29602 29603 29604 29605 29606 29607 29608 29609 29610 29611 29612 29613 29614 29615 29616 29617 29618 29619 29620 29621 29622 29623 29624 29625 29626 29627 29628 29629 29630 29631 29632 29633 29634 29635 29636 29637 29638 29639 29640 29641 29642 29643 29644 29645 29646 29647 29648 29649 29650 29651 29652 29653 29654 29655 29656 29657 29658 29659 29660 29661 29662 29663 29664 29665 29666 29667 29668 29669 29670 29671 29672 29673 29674 29675 29676 29677 29678 29679 29680 29681 29682 29683 29684 29685 29686 29687 29688 29689 29690 29691 29692 29693 29694 29695 29696 29697 29698 29699 29700 29701 29702 29703 29704 29705 29706 29707 29708 29709 29710 29711 29712 29713 29714 29715 29716 29717 29718 29719 29720 29721 29722 29723 29724 29725 29726 29727 29728 29729 29730 29731 29732 29733 29734 29735 29736 29737 29738 29739 29740 29741 29742 29743 29744 29745 29746 29747 29748 29749 29750 29751 29752 29753 29754 29755 29756 29757 29758 29759 29760 29761 29762 29763 29764 29765 29766 29767 29768 29769 29770 29771 29772 29773 29774 29775 29776 29777 29778 29779 29780 29781 29782 29783 29784 29785 29786 29787 29788 29789 29790 29791 29792 29793 29794 29795 29796 29797 29798 29799 29800 29801 29802 29803 29804 29805 29806 29807 29808 29809 29810 29811 29812 29813 29814 29815 29816 29817 29818 29819 29820 29821 29822 29823 29824 29825 29826 29827 29828 29829 29830 29831 29832 29833 29834 29835 29836 29837 29838 29839 29840 29841 29842 29843 29844 29845 29846 29847 29848 29849 29850 29851 29852 29853 29854 29855 29856 29857 29858 29859 29860 29861 29862 29863 29864 29865 29866 29867 29868 29869 29870 29871 29872 29873 29874 29875 29876 29877 29878 29879 29880 29881 29882 29883 29884 29885 29886 29887 29888 29889 29890 29891 29892 29893 29894 29895 29896 29897 29898 29899 29900 29901 29902 29903 29904 29905 29906 29907 29908 29909 29910 29911 29912 29913 29914 29915 29916 29917 29918 29919 29920 29921 29922 29923 29924 29925 29926 29927 29928 29929 29930 29931 29932 29933 29934
|
Description: Updates from the 3.14 branch (until 2026-03-11).
We pick the latest updates from the maintainance branch, and carry them in a
patch, rather than creating and uploading uploading a new .orig tarball.
# git diff --no-renames 323c59a5e348347be2ce2b7ea55fcb30bf68b2d3 0a80015ac26d60bff54f57ce9f73ffc5386249b1 | filterdiff -x ?/.hgignore -x ?/.hgeol -x ?/.hgtags -x ?/.hgtouch -x ?/.gitignore -x ?/.gitattributes -x '?/.github/*' -x '?/.git*' -x ?/.codecov.yml -x ?/.travis.yml -x ?/configure --remove-timestamps
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index ed88e9ca81b..1d09596671a 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,6 +1,6 @@
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
- rev: v0.14.10
+ rev: a27a2e47c7751b639d2b5badf0ef6ff11fee893f # frozen: v0.15.4
hooks:
- id: ruff-check
name: Run Ruff (lint) on Apple/
@@ -52,20 +52,20 @@ repos:
files: ^Tools/wasm/
- repo: https://github.com/psf/black-pre-commit-mirror
- rev: 25.12.0
+ rev: ea488cebbfd88a5f50b8bd95d5c829d0bb76feb8 # frozen: 26.1.0
hooks:
- id: black
name: Run Black on Tools/jit/
files: ^Tools/jit/
- repo: https://github.com/Lucas-C/pre-commit-hooks
- rev: v1.5.5
+ rev: ad1b27d73581aa16cca06fc4a0761fc563ffe8e8 # frozen: v1.5.6
hooks:
- id: remove-tabs
types: [python]
- repo: https://github.com/pre-commit/pre-commit-hooks
- rev: v6.0.0
+ rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c # frozen: v6.0.0
hooks:
- id: check-case-conflict
- id: check-merge-conflict
@@ -83,24 +83,24 @@ repos:
files: '^\.github/CODEOWNERS|\.(gram)$'
- repo: https://github.com/python-jsonschema/check-jsonschema
- rev: 0.36.0
+ rev: 9f48a48aa91a6040d749ad68ec70907d907a5a7f # frozen: 0.37.0
hooks:
- id: check-dependabot
- id: check-github-workflows
- id: check-readthedocs
- repo: https://github.com/rhysd/actionlint
- rev: v1.7.9
+ rev: 393031adb9afb225ee52ae2ccd7a5af5525e03e8 # frozen: v1.7.11
hooks:
- id: actionlint
- - repo: https://github.com/woodruffw/zizmor-pre-commit
- rev: v1.19.0
+ - repo: https://github.com/zizmorcore/zizmor-pre-commit
+ rev: b546b77c44c466a54a42af5499dcc0dcc1a3193f # frozen: v1.22.0
hooks:
- id: zizmor
- repo: https://github.com/sphinx-contrib/sphinx-lint
- rev: v1.0.2
+ rev: c883505f64b59c3c5c9375191e4ad9f98e727ccd # frozen: v1.0.2
hooks:
- id: sphinx-lint
args: [--enable=default-role]
diff --git a/Android/android.py b/Android/android.py
index 629696be3db..0a894a958a0 100755
--- a/Android/android.py
+++ b/Android/android.py
@@ -208,7 +208,7 @@ def make_build_python(context):
def unpack_deps(host, prefix_dir):
os.chdir(prefix_dir)
deps_url = "https://github.com/beeware/cpython-android-source-deps/releases/download"
- for name_ver in ["bzip2-1.0.8-3", "libffi-3.4.4-3", "openssl-3.0.18-0",
+ for name_ver in ["bzip2-1.0.8-3", "libffi-3.4.4-3", "openssl-3.0.19-1",
"sqlite-3.50.4-0", "xz-5.4.6-1", "zstd-1.5.7-1"]:
filename = f"{name_ver}-{host}.tar.gz"
download(f"{deps_url}/{name_ver}/{filename}")
diff --git a/Apple/__main__.py b/Apple/__main__.py
index 256966e76c2..253bdfaab55 100644
--- a/Apple/__main__.py
+++ b/Apple/__main__.py
@@ -316,7 +316,7 @@ def unpack_deps(
for name_ver in [
"BZip2-1.0.8-2",
"libFFI-3.4.7-2",
- "OpenSSL-3.0.18-1",
+ "OpenSSL-3.0.19-1",
"XZ-5.6.4-2",
"mpdecimal-4.0.0-2",
"zstd-1.5.7-1",
diff --git a/Doc/.ruff.toml b/Doc/.ruff.toml
index 3e676e13c3f..6b573fd58d0 100644
--- a/Doc/.ruff.toml
+++ b/Doc/.ruff.toml
@@ -32,6 +32,9 @@ ignore = [
"E501", # Ignore line length errors (we use auto-formatting)
]
+[lint.per-file-ignores]
+"tools/check-html-ids.py" = ["I001"] # Unsorted imports
+
[format]
preview = true
quote-style = "preserve"
diff --git a/Doc/Makefile b/Doc/Makefile
index 4d605980a62..5b7fdf8ec08 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -58,7 +58,7 @@ build:
@if [ -f ../Misc/NEWS ] ; then \
echo "Using existing Misc/NEWS file"; \
cp ../Misc/NEWS build/NEWS; \
- elif $(BLURB) help >/dev/null 2>&1 && $(SPHINXBUILD) --version >/dev/null 2>&1; then \
+ elif $(BLURB) --version && $(SPHINXBUILD) --version ; then \
if [ -d ../Misc/NEWS.d ]; then \
echo "Building NEWS from Misc/NEWS.d with blurb"; \
$(BLURB) merge -f build/NEWS; \
@@ -336,3 +336,9 @@ autobuild-stable-html:
exit 1;; \
esac
@$(MAKE) autobuild-dev-html
+
+# Collect HTML IDs to a JSON document
+.PHONY: html-ids
+html-ids:
+ $(PYTHON) tools/check-html-ids.py collect build/html \
+ -o build/html/html-ids.json.gz
diff --git a/Doc/bugs.rst b/Doc/bugs.rst
index 1d27579e53f..9f2b9876ba5 100644
--- a/Doc/bugs.rst
+++ b/Doc/bugs.rst
@@ -9,7 +9,7 @@ stability. In order to maintain this reputation, the developers would like to
know of any deficiencies you find in Python.
It can be sometimes faster to fix bugs yourself and contribute patches to
-Python as it streamlines the process and involves less people. Learn how to
+Python as it streamlines the process and involves fewer people. Learn how to
:ref:`contribute <contributing-to-python>`.
Documentation bugs
diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index d7fe9e2c9ec..3a7fa0d1ff6 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -673,28 +673,46 @@ Signal Handling
single: SIGINT (C macro)
single: KeyboardInterrupt (built-in exception)
- This function interacts with Python's signal handling.
+ Handle external interruptions, such as signals or activating a debugger,
+ whose processing has been delayed until it is safe
+ to run Python code and/or raise exceptions.
- If the function is called from the main thread and under the main Python
- interpreter, it checks whether a signal has been sent to the processes
- and if so, invokes the corresponding signal handler. If the :mod:`signal`
- module is supported, this can invoke a signal handler written in Python.
+ For example, pressing :kbd:`Ctrl-C` causes a terminal to send the
+ :py:data:`signal.SIGINT` signal.
+ This function executes the corresponding Python signal handler, which,
+ by default, raises the :exc:`KeyboardInterrupt` exception.
- The function attempts to handle all pending signals, and then returns ``0``.
- However, if a Python signal handler raises an exception, the error
- indicator is set and the function returns ``-1`` immediately (such that
- other pending signals may not have been handled yet: they will be on the
- next :c:func:`PyErr_CheckSignals()` invocation).
+ :c:func:`!PyErr_CheckSignals` should be called by long-running C code
+ frequently enough so that the response appears immediate to humans.
- If the function is called from a non-main thread, or under a non-main
- Python interpreter, it does nothing and returns ``0``.
+ Handlers invoked by this function currently include:
- This function can be called by long-running C code that wants to
- be interruptible by user requests (such as by pressing Ctrl-C).
+ - Signal handlers, including Python functions registered using
+ the :mod:`signal` module.
- .. note::
- The default Python signal handler for :c:macro:`!SIGINT` raises the
- :exc:`KeyboardInterrupt` exception.
+ Signal handlers are only run in the main thread of the main interpreter.
+
+ (This is where the function got the name: originally, signals
+ were the only way to interrupt the interpreter.)
+
+ - Running the garbage collector, if necessary.
+
+ - Executing a pending :ref:`remote debugger <remote-debugging>` script.
+
+ If any handler raises an exception, immediately return ``-1`` with that
+ exception set.
+ Any remaining interruptions are left to be processed on the next
+ :c:func:`PyErr_CheckSignals()` invocation, if appropriate.
+
+ If all handlers finish successfully, or there are no handlers to run,
+ return ``0``.
+
+ .. versionchanged:: 3.12
+ This function may now invoke the garbage collector.
+
+ .. versionchanged:: 3.14
+ This function may now execute a remote debugger script, if remote
+ debugging is enabled.
.. c:function:: void PyErr_SetInterrupt()
diff --git a/Doc/c-api/float.rst b/Doc/c-api/float.rst
index 51540004c93..75ea3d819d3 100644
--- a/Doc/c-api/float.rst
+++ b/Doc/c-api/float.rst
@@ -80,7 +80,7 @@ Floating-Point Objects
.. c:macro:: Py_INFINITY
- This macro expands a to constant expression of type :c:expr:`double`, that
+ This macro expands to a constant expression of type :c:expr:`double`, that
represents the positive infinity.
On most platforms, this is equivalent to the :c:macro:`!INFINITY` macro from
@@ -89,7 +89,7 @@ Floating-Point Objects
.. c:macro:: Py_NAN
- This macro expands a to constant expression of type :c:expr:`double`, that
+ This macro expands to a constant expression of type :c:expr:`double`, that
represents a quiet not-a-number (qNaN) value.
On most platforms, this is equivalent to the :c:macro:`!NAN` macro from
diff --git a/Doc/c-api/frame.rst b/Doc/c-api/frame.rst
index fb17cf7f1da..967cfc72765 100644
--- a/Doc/c-api/frame.rst
+++ b/Doc/c-api/frame.rst
@@ -50,6 +50,7 @@ See also :ref:`Reflection <reflection>`.
Return a :term:`strong reference`, or ``NULL`` if *frame* has no outer
frame.
+ This raises no exceptions.
.. versionadded:: 3.9
diff --git a/Doc/c-api/index.rst b/Doc/c-api/index.rst
index e9df2a304d9..eabe00f4004 100644
--- a/Doc/c-api/index.rst
+++ b/Doc/c-api/index.rst
@@ -1,7 +1,7 @@
.. _c-api-index:
##################################
- Python/C API Reference Manual
+ Python/C API reference manual
##################################
This manual documents the API used by C and C++ programmers who want to write
@@ -21,7 +21,12 @@ document the API functions in detail.
utilities.rst
abstract.rst
concrete.rst
- init.rst
+ interp-lifecycle.rst
+ threads.rst
+ synchronization.rst
+ tls.rst
+ subinterpreters.rst
+ profiling.rst
init_config.rst
memory.rst
objimpl.rst
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 1559f1c8fcd..e56c67f9534 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -1,2927 +1,13 @@
-.. highlight:: c
+:orphan:
+Initialization, finalization, and threads
+=========================================
-.. _initialization:
+This page has been split up into the following:
-*****************************************
-Initialization, Finalization, and Threads
-*****************************************
-
-See :ref:`Python Initialization Configuration <init-config>` for details
-on how to configure the interpreter prior to initialization.
-
-.. _pre-init-safe:
-
-Before Python Initialization
-============================
-
-In an application embedding Python, the :c:func:`Py_Initialize` function must
-be called before using any other Python/C API functions; with the exception of
-a few functions and the :ref:`global configuration variables
-<global-conf-vars>`.
-
-The following functions can be safely called before Python is initialized:
-
-* Functions that initialize the interpreter:
-
- * :c:func:`Py_Initialize`
- * :c:func:`Py_InitializeEx`
- * :c:func:`Py_InitializeFromConfig`
- * :c:func:`Py_BytesMain`
- * :c:func:`Py_Main`
- * the runtime pre-initialization functions covered in :ref:`init-config`
-
-* Configuration functions:
-
- * :c:func:`PyImport_AppendInittab`
- * :c:func:`PyImport_ExtendInittab`
- * :c:func:`!PyInitFrozenExtensions`
- * :c:func:`PyMem_SetAllocator`
- * :c:func:`PyMem_SetupDebugHooks`
- * :c:func:`PyObject_SetArenaAllocator`
- * :c:func:`Py_SetProgramName`
- * :c:func:`Py_SetPythonHome`
- * :c:func:`PySys_ResetWarnOptions`
- * the configuration functions covered in :ref:`init-config`
-
-* Informative functions:
-
- * :c:func:`Py_IsInitialized`
- * :c:func:`PyMem_GetAllocator`
- * :c:func:`PyObject_GetArenaAllocator`
- * :c:func:`Py_GetBuildInfo`
- * :c:func:`Py_GetCompiler`
- * :c:func:`Py_GetCopyright`
- * :c:func:`Py_GetPlatform`
- * :c:func:`Py_GetVersion`
- * :c:func:`Py_IsInitialized`
-
-* Utilities:
-
- * :c:func:`Py_DecodeLocale`
- * the status reporting and utility functions covered in :ref:`init-config`
-
-* Memory allocators:
-
- * :c:func:`PyMem_RawMalloc`
- * :c:func:`PyMem_RawRealloc`
- * :c:func:`PyMem_RawCalloc`
- * :c:func:`PyMem_RawFree`
-
-* Synchronization:
-
- * :c:func:`PyMutex_Lock`
- * :c:func:`PyMutex_Unlock`
-
-.. note::
-
- Despite their apparent similarity to some of the functions listed above,
- the following functions **should not be called** before the interpreter has
- been initialized: :c:func:`Py_EncodeLocale`, :c:func:`Py_GetPath`,
- :c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`,
- :c:func:`Py_GetProgramFullPath`, :c:func:`Py_GetPythonHome`,
- :c:func:`Py_GetProgramName`, :c:func:`PyEval_InitThreads`, and
- :c:func:`Py_RunMain`.
-
-
-.. _global-conf-vars:
-
-Global configuration variables
-==============================
-
-Python has variables for the global configuration to control different features
-and options. By default, these flags are controlled by :ref:`command line
-options <using-on-interface-options>`.
-
-When a flag is set by an option, the value of the flag is the number of times
-that the option was set. For example, ``-b`` sets :c:data:`Py_BytesWarningFlag`
-to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
-
-.. c:var:: int Py_BytesWarningFlag
-
- This API is kept for backward compatibility: setting
- :c:member:`PyConfig.bytes_warning` should be used instead, see :ref:`Python
- Initialization Configuration <init-config>`.
-
- Issue a warning when comparing :class:`bytes` or :class:`bytearray` with
- :class:`str` or :class:`bytes` with :class:`int`. Issue an error if greater
- or equal to ``2``.
-
- Set by the :option:`-b` option.
-
- .. deprecated-removed:: 3.12 3.15
-
-.. c:var:: int Py_DebugFlag
-
- This API is kept for backward compatibility: setting
- :c:member:`PyConfig.parser_debug` should be used instead, see :ref:`Python
- Initialization Configuration <init-config>`.
-
- Turn on parser debugging output (for expert only, depending on compilation
- options).
-
- Set by the :option:`-d` option and the :envvar:`PYTHONDEBUG` environment
- variable.
-
- .. deprecated-removed:: 3.12 3.15
-
-.. c:var:: int Py_DontWriteBytecodeFlag
-
- This API is kept for backward compatibility: setting
- :c:member:`PyConfig.write_bytecode` should be used instead, see :ref:`Python
- Initialization Configuration <init-config>`.
-
- If set to non-zero, Python won't try to write ``.pyc`` files on the
- import of source modules.
-
- Set by the :option:`-B` option and the :envvar:`PYTHONDONTWRITEBYTECODE`
- environment variable.
-
- .. deprecated-removed:: 3.12 3.15
-
-.. c:var:: int Py_FrozenFlag
-
- This API is kept for backward compatibility: setting
- :c:member:`PyConfig.pathconfig_warnings` should be used instead, see
- :ref:`Python Initialization Configuration <init-config>`.
-
- Suppress error messages when calculating the module search path in
- :c:func:`Py_GetPath`.
-
- Private flag used by ``_freeze_module`` and ``frozenmain`` programs.
-
- .. deprecated-removed:: 3.12 3.15
-
-.. c:var:: int Py_HashRandomizationFlag
-
- This API is kept for backward compatibility: setting
- :c:member:`PyConfig.hash_seed` and :c:member:`PyConfig.use_hash_seed` should
- be used instead, see :ref:`Python Initialization Configuration
- <init-config>`.
-
- Set to ``1`` if the :envvar:`PYTHONHASHSEED` environment variable is set to
- a non-empty string.
-
- If the flag is non-zero, read the :envvar:`PYTHONHASHSEED` environment
- variable to initialize the secret hash seed.
-
- .. deprecated-removed:: 3.12 3.15
-
-.. c:var:: int Py_IgnoreEnvironmentFlag
-
- This API is kept for backward compatibility: setting
- :c:member:`PyConfig.use_environment` should be used instead, see
- :ref:`Python Initialization Configuration <init-config>`.
-
- Ignore all :envvar:`!PYTHON*` environment variables, e.g.
- :envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set.
-
- Set by the :option:`-E` and :option:`-I` options.
-
- .. deprecated-removed:: 3.12 3.15
-
-.. c:var:: int Py_InspectFlag
-
- This API is kept for backward compatibility: setting
- :c:member:`PyConfig.inspect` should be used instead, see
- :ref:`Python Initialization Configuration <init-config>`.
-
- When a script is passed as first argument or the :option:`-c` option is used,
- enter interactive mode after executing the script or the command, even when
- :data:`sys.stdin` does not appear to be a terminal.
-
- Set by the :option:`-i` option and the :envvar:`PYTHONINSPECT` environment
- variable.
-
- .. deprecated-removed:: 3.12 3.15
-
-.. c:var:: int Py_InteractiveFlag
-
- This API is kept for backward compatibility: setting
- :c:member:`PyConfig.interactive` should be used instead, see
- :ref:`Python Initialization Configuration <init-config>`.
-
- Set by the :option:`-i` option.
-
- .. deprecated-removed:: 3.12 3.15
-
-.. c:var:: int Py_IsolatedFlag
-
- This API is kept for backward compatibility: setting
- :c:member:`PyConfig.isolated` should be used instead, see
- :ref:`Python Initialization Configuration <init-config>`.
-
- Run Python in isolated mode. In isolated mode :data:`sys.path` contains
- neither the script's directory nor the user's site-packages directory.
-
- Set by the :option:`-I` option.
-
- .. versionadded:: 3.4
-
- .. deprecated-removed:: 3.12 3.15
-
-.. c:var:: int Py_LegacyWindowsFSEncodingFlag
-
- This API is kept for backward compatibility: setting
- :c:member:`PyPreConfig.legacy_windows_fs_encoding` should be used instead, see
- :ref:`Python Initialization Configuration <init-config>`.
-
- If the flag is non-zero, use the ``mbcs`` encoding with ``replace`` error
- handler, instead of the UTF-8 encoding with ``surrogatepass`` error handler,
- for the :term:`filesystem encoding and error handler`.
-
- Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment
- variable is set to a non-empty string.
-
- See :pep:`529` for more details.
-
- .. availability:: Windows.
-
- .. deprecated-removed:: 3.12 3.15
-
-.. c:var:: int Py_LegacyWindowsStdioFlag
-
- This API is kept for backward compatibility: setting
- :c:member:`PyConfig.legacy_windows_stdio` should be used instead, see
- :ref:`Python Initialization Configuration <init-config>`.
-
- If the flag is non-zero, use :class:`io.FileIO` instead of
- :class:`!io._WindowsConsoleIO` for :mod:`sys` standard streams.
-
- Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSSTDIO` environment
- variable is set to a non-empty string.
-
- See :pep:`528` for more details.
-
- .. availability:: Windows.
-
- .. deprecated-removed:: 3.12 3.15
-
-.. c:var:: int Py_NoSiteFlag
-
- This API is kept for backward compatibility: setting
- :c:member:`PyConfig.site_import` should be used instead, see
- :ref:`Python Initialization Configuration <init-config>`.
-
- Disable the import of the module :mod:`site` and the site-dependent
- manipulations of :data:`sys.path` that it entails. Also disable these
- manipulations if :mod:`site` is explicitly imported later (call
- :func:`site.main` if you want them to be triggered).
-
- Set by the :option:`-S` option.
-
- .. deprecated-removed:: 3.12 3.15
-
-.. c:var:: int Py_NoUserSiteDirectory
-
- This API is kept for backward compatibility: setting
- :c:member:`PyConfig.user_site_directory` should be used instead, see
- :ref:`Python Initialization Configuration <init-config>`.
-
- Don't add the :data:`user site-packages directory <site.USER_SITE>` to
- :data:`sys.path`.
-
- Set by the :option:`-s` and :option:`-I` options, and the
- :envvar:`PYTHONNOUSERSITE` environment variable.
-
- .. deprecated-removed:: 3.12 3.15
-
-.. c:var:: int Py_OptimizeFlag
-
- This API is kept for backward compatibility: setting
- :c:member:`PyConfig.optimization_level` should be used instead, see
- :ref:`Python Initialization Configuration <init-config>`.
-
- Set by the :option:`-O` option and the :envvar:`PYTHONOPTIMIZE` environment
- variable.
-
- .. deprecated-removed:: 3.12 3.15
-
-.. c:var:: int Py_QuietFlag
-
- This API is kept for backward compatibility: setting
- :c:member:`PyConfig.quiet` should be used instead, see :ref:`Python
- Initialization Configuration <init-config>`.
-
- Don't display the copyright and version messages even in interactive mode.
-
- Set by the :option:`-q` option.
-
- .. versionadded:: 3.2
-
- .. deprecated-removed:: 3.12 3.15
-
-.. c:var:: int Py_UnbufferedStdioFlag
-
- This API is kept for backward compatibility: setting
- :c:member:`PyConfig.buffered_stdio` should be used instead, see :ref:`Python
- Initialization Configuration <init-config>`.
-
- Force the stdout and stderr streams to be unbuffered.
-
- Set by the :option:`-u` option and the :envvar:`PYTHONUNBUFFERED`
- environment variable.
-
- .. deprecated-removed:: 3.12 3.15
-
-.. c:var:: int Py_VerboseFlag
-
- This API is kept for backward compatibility: setting
- :c:member:`PyConfig.verbose` should be used instead, see :ref:`Python
- Initialization Configuration <init-config>`.
-
- Print a message each time a module is initialized, showing the place
- (filename or built-in module) from which it is loaded. If greater or equal
- to ``2``, print a message for each file that is checked for when
- searching for a module. Also provides information on module cleanup at exit.
-
- Set by the :option:`-v` option and the :envvar:`PYTHONVERBOSE` environment
- variable.
-
- .. deprecated-removed:: 3.12 3.15
-
-
-Initializing and finalizing the interpreter
-===========================================
-
-
-.. c:function:: void Py_Initialize()
-
- .. index::
- single: PyEval_InitThreads()
- single: modules (in module sys)
- single: path (in module sys)
- pair: module; builtins
- pair: module; __main__
- pair: module; sys
- triple: module; search; path
- single: Py_FinalizeEx (C function)
-
- Initialize the Python interpreter. In an application embedding Python,
- this should be called before using any other Python/C API functions; see
- :ref:`Before Python Initialization <pre-init-safe>` for the few exceptions.
-
- This initializes the table of loaded modules (``sys.modules``), and creates
- the fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`.
- It also initializes the module search path (``sys.path``). It does not set
- ``sys.argv``; use the :ref:`Python Initialization Configuration <init-config>`
- API for that. This is a no-op when called for a second time (without calling
- :c:func:`Py_FinalizeEx` first). There is no return value; it is a fatal
- error if the initialization fails.
-
- Use :c:func:`Py_InitializeFromConfig` to customize the
- :ref:`Python Initialization Configuration <init-config>`.
-
- .. note::
- On Windows, changes the console mode from ``O_TEXT`` to ``O_BINARY``,
- which will also affect non-Python uses of the console using the C Runtime.
-
-
-.. c:function:: void Py_InitializeEx(int initsigs)
-
- This function works like :c:func:`Py_Initialize` if *initsigs* is ``1``. If
- *initsigs* is ``0``, it skips initialization registration of signal handlers,
- which may be useful when CPython is embedded as part of a larger application.
-
- Use :c:func:`Py_InitializeFromConfig` to customize the
- :ref:`Python Initialization Configuration <init-config>`.
-
-
-.. c:function:: PyStatus Py_InitializeFromConfig(const PyConfig *config)
-
- Initialize Python from *config* configuration, as described in
- :ref:`init-from-config`.
-
- See the :ref:`init-config` section for details on pre-initializing the
- interpreter, populating the runtime configuration structure, and querying
- the returned status structure.
-
-
-.. c:function:: int Py_IsInitialized()
-
- Return true (nonzero) when the Python interpreter has been initialized, false
- (zero) if not. After :c:func:`Py_FinalizeEx` is called, this returns false until
- :c:func:`Py_Initialize` is called again.
-
-
-.. c:function:: int Py_IsFinalizing()
-
- Return true (non-zero) if the main Python interpreter is
- :term:`shutting down <interpreter shutdown>`. Return false (zero) otherwise.
-
- .. versionadded:: 3.13
-
-
-.. c:function:: int Py_FinalizeEx()
-
- Undo all initializations made by :c:func:`Py_Initialize` and subsequent use of
- Python/C API functions, and destroy all sub-interpreters (see
- :c:func:`Py_NewInterpreter` below) that were created and not yet destroyed since
- the last call to :c:func:`Py_Initialize`. This is a no-op when called for a second
- time (without calling :c:func:`Py_Initialize` again first).
-
- Since this is the reverse of :c:func:`Py_Initialize`, it should be called
- in the same thread with the same interpreter active. That means
- the main thread and the main interpreter.
- This should never be called while :c:func:`Py_RunMain` is running.
-
- Normally the return value is ``0``.
- If there were errors during finalization (flushing buffered data),
- ``-1`` is returned.
-
- Note that Python will do a best effort at freeing all memory allocated by the Python
- interpreter. Therefore, any C-Extension should make sure to correctly clean up all
- of the preveiously allocated PyObjects before using them in subsequent calls to
- :c:func:`Py_Initialize`. Otherwise it could introduce vulnerabilities and incorrect
- behavior.
-
- This function is provided for a number of reasons. An embedding application
- might want to restart Python without having to restart the application itself.
- An application that has loaded the Python interpreter from a dynamically
- loadable library (or DLL) might want to free all memory allocated by Python
- before unloading the DLL. During a hunt for memory leaks in an application a
- developer might want to free all memory allocated by Python before exiting from
- the application.
-
- **Bugs and caveats:** The destruction of modules and objects in modules is done
- in random order; this may cause destructors (:meth:`~object.__del__` methods) to fail
- when they depend on other objects (even functions) or modules. Dynamically
- loaded extension modules loaded by Python are not unloaded. Small amounts of
- memory allocated by the Python interpreter may not be freed (if you find a leak,
- please report it). Memory tied up in circular references between objects is not
- freed. Interned strings will all be deallocated regardless of their reference count.
- Some memory allocated by extension modules may not be freed. Some extensions may not
- work properly if their initialization routine is called more than once; this can
- happen if an application calls :c:func:`Py_Initialize` and :c:func:`Py_FinalizeEx`
- more than once. :c:func:`Py_FinalizeEx` must not be called recursively from
- within itself. Therefore, it must not be called by any code that may be run
- as part of the interpreter shutdown process, such as :py:mod:`atexit`
- handlers, object finalizers, or any code that may be run while flushing the
- stdout and stderr files.
-
- .. audit-event:: cpython._PySys_ClearAuditHooks "" c.Py_FinalizeEx
-
- .. versionadded:: 3.6
-
-
-.. c:function:: void Py_Finalize()
-
- This is a backwards-compatible version of :c:func:`Py_FinalizeEx` that
- disregards the return value.
-
-
-.. c:function:: int Py_BytesMain(int argc, char **argv)
-
- Similar to :c:func:`Py_Main` but *argv* is an array of bytes strings,
- allowing the calling application to delegate the text decoding step to
- the CPython runtime.
-
- .. versionadded:: 3.8
-
-
-.. c:function:: int Py_Main(int argc, wchar_t **argv)
-
- The main program for the standard interpreter, encapsulating a full
- initialization/finalization cycle, as well as additional
- behaviour to implement reading configurations settings from the environment
- and command line, and then executing ``__main__`` in accordance with
- :ref:`using-on-cmdline`.
-
- This is made available for programs which wish to support the full CPython
- command line interface, rather than just embedding a Python runtime in a
- larger application.
-
- The *argc* and *argv* parameters are similar to those which are passed to a
- C program's :c:func:`main` function, except that the *argv* entries are first
- converted to ``wchar_t`` using :c:func:`Py_DecodeLocale`. It is also
- important to note that the argument list entries may be modified to point to
- strings other than those passed in (however, the contents of the strings
- pointed to by the argument list are not modified).
-
- The return value is ``2`` if the argument list does not represent a valid
- Python command line, and otherwise the same as :c:func:`Py_RunMain`.
-
- In terms of the CPython runtime configuration APIs documented in the
- :ref:`runtime configuration <init-config>` section (and without accounting
- for error handling), ``Py_Main`` is approximately equivalent to::
-
- PyConfig config;
- PyConfig_InitPythonConfig(&config);
- PyConfig_SetArgv(&config, argc, argv);
- Py_InitializeFromConfig(&config);
- PyConfig_Clear(&config);
-
- Py_RunMain();
-
- In normal usage, an embedding application will call this function
- *instead* of calling :c:func:`Py_Initialize`, :c:func:`Py_InitializeEx` or
- :c:func:`Py_InitializeFromConfig` directly, and all settings will be applied
- as described elsewhere in this documentation. If this function is instead
- called *after* a preceding runtime initialization API call, then exactly
- which environmental and command line configuration settings will be updated
- is version dependent (as it depends on which settings correctly support
- being modified after they have already been set once when the runtime was
- first initialized).
-
-
-.. c:function:: int Py_RunMain(void)
-
- Executes the main module in a fully configured CPython runtime.
-
- Executes the command (:c:member:`PyConfig.run_command`), the script
- (:c:member:`PyConfig.run_filename`) or the module
- (:c:member:`PyConfig.run_module`) specified on the command line or in the
- configuration. If none of these values are set, runs the interactive Python
- prompt (REPL) using the ``__main__`` module's global namespace.
-
- If :c:member:`PyConfig.inspect` is not set (the default), the return value
- will be ``0`` if the interpreter exits normally (that is, without raising
- an exception), the exit status of an unhandled :exc:`SystemExit`, or ``1``
- for any other unhandled exception.
-
- If :c:member:`PyConfig.inspect` is set (such as when the :option:`-i` option
- is used), rather than returning when the interpreter exits, execution will
- instead resume in an interactive Python prompt (REPL) using the ``__main__``
- module's global namespace. If the interpreter exited with an exception, it
- is immediately raised in the REPL session. The function return value is
- then determined by the way the *REPL session* terminates: ``0``, ``1``, or
- the status of a :exc:`SystemExit`, as specified above.
-
- This function always finalizes the Python interpreter before it returns.
-
- See :ref:`Python Configuration <init-python-config>` for an example of a
- customized Python that always runs in isolated mode using
- :c:func:`Py_RunMain`.
-
-.. c:function:: int PyUnstable_AtExit(PyInterpreterState *interp, void (*func)(void *), void *data)
-
- Register an :mod:`atexit` callback for the target interpreter *interp*.
- This is similar to :c:func:`Py_AtExit`, but takes an explicit interpreter and
- data pointer for the callback.
-
- There must be an :term:`attached thread state` for *interp*.
-
- .. versionadded:: 3.13
-
-Process-wide parameters
-=======================
-
-
-.. c:function:: void Py_SetProgramName(const wchar_t *name)
-
- .. index::
- single: Py_Initialize()
- single: main()
- single: Py_GetPath()
-
- This API is kept for backward compatibility: setting
- :c:member:`PyConfig.program_name` should be used instead, see :ref:`Python
- Initialization Configuration <init-config>`.
-
- This function should be called before :c:func:`Py_Initialize` is called for
- the first time, if it is called at all. It tells the interpreter the value
- of the ``argv[0]`` argument to the :c:func:`main` function of the program
- (converted to wide characters).
- This is used by :c:func:`Py_GetPath` and some other functions below to find
- the Python run-time libraries relative to the interpreter executable. The
- default value is ``'python'``. The argument should point to a
- zero-terminated wide character string in static storage whose contents will not
- change for the duration of the program's execution. No code in the Python
- interpreter will change the contents of this storage.
-
- Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
- :c:expr:`wchar_t*` string.
-
- .. deprecated-removed:: 3.11 3.15
-
-
-.. c:function:: wchar_t* Py_GetProgramName()
-
- Return the program name set with :c:member:`PyConfig.program_name`, or the default.
- The returned string points into static storage; the caller should not modify its
- value.
-
- This function should not be called before :c:func:`Py_Initialize`, otherwise
- it returns ``NULL``.
-
- .. versionchanged:: 3.10
- It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
-
- .. deprecated-removed:: 3.13 3.15
- Use :c:func:`PyConfig_Get("executable") <PyConfig_Get>`
- (:data:`sys.executable`) instead.
-
-
-.. c:function:: wchar_t* Py_GetPrefix()
-
- Return the *prefix* for installed platform-independent files. This is derived
- through a number of complicated rules from the program name set with
- :c:member:`PyConfig.program_name` and some environment variables; for example, if the
- program name is ``'/usr/local/bin/python'``, the prefix is ``'/usr/local'``. The
- returned string points into static storage; the caller should not modify its
- value. This corresponds to the :makevar:`prefix` variable in the top-level
- :file:`Makefile` and the :option:`--prefix` argument to the :program:`configure`
- script at build time. The value is available to Python code as ``sys.base_prefix``.
- It is only useful on Unix. See also the next function.
-
- This function should not be called before :c:func:`Py_Initialize`, otherwise
- it returns ``NULL``.
-
- .. versionchanged:: 3.10
- It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
-
- .. deprecated-removed:: 3.13 3.15
- Use :c:func:`PyConfig_Get("base_prefix") <PyConfig_Get>`
- (:data:`sys.base_prefix`) instead. Use :c:func:`PyConfig_Get("prefix")
- <PyConfig_Get>` (:data:`sys.prefix`) if :ref:`virtual environments
- <venv-def>` need to be handled.
-
-
-.. c:function:: wchar_t* Py_GetExecPrefix()
-
- Return the *exec-prefix* for installed platform-*dependent* files. This is
- derived through a number of complicated rules from the program name set with
- :c:member:`PyConfig.program_name` and some environment variables; for example, if the
- program name is ``'/usr/local/bin/python'``, the exec-prefix is
- ``'/usr/local'``. The returned string points into static storage; the caller
- should not modify its value. This corresponds to the :makevar:`exec_prefix`
- variable in the top-level :file:`Makefile` and the ``--exec-prefix``
- argument to the :program:`configure` script at build time. The value is
- available to Python code as ``sys.base_exec_prefix``. It is only useful on
- Unix.
-
- Background: The exec-prefix differs from the prefix when platform dependent
- files (such as executables and shared libraries) are installed in a different
- directory tree. In a typical installation, platform dependent files may be
- installed in the :file:`/usr/local/plat` subtree while platform independent may
- be installed in :file:`/usr/local`.
-
- Generally speaking, a platform is a combination of hardware and software
- families, e.g. Sparc machines running the Solaris 2.x operating system are
- considered the same platform, but Intel machines running Solaris 2.x are another
- platform, and Intel machines running Linux are yet another platform. Different
- major revisions of the same operating system generally also form different
- platforms. Non-Unix operating systems are a different story; the installation
- strategies on those systems are so different that the prefix and exec-prefix are
- meaningless, and set to the empty string. Note that compiled Python bytecode
- files are platform independent (but not independent from the Python version by
- which they were compiled!).
-
- System administrators will know how to configure the :program:`mount` or
- :program:`automount` programs to share :file:`/usr/local` between platforms
- while having :file:`/usr/local/plat` be a different filesystem for each
- platform.
-
- This function should not be called before :c:func:`Py_Initialize`, otherwise
- it returns ``NULL``.
-
- .. versionchanged:: 3.10
- It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
-
- .. deprecated-removed:: 3.13 3.15
- Use :c:func:`PyConfig_Get("base_exec_prefix") <PyConfig_Get>`
- (:data:`sys.base_exec_prefix`) instead. Use
- :c:func:`PyConfig_Get("exec_prefix") <PyConfig_Get>`
- (:data:`sys.exec_prefix`) if :ref:`virtual environments <venv-def>` need
- to be handled.
-
-.. c:function:: wchar_t* Py_GetProgramFullPath()
-
- .. index::
- single: executable (in module sys)
-
- Return the full program name of the Python executable; this is computed as a
- side-effect of deriving the default module search path from the program name
- (set by :c:member:`PyConfig.program_name`). The returned string points into
- static storage; the caller should not modify its value. The value is available
- to Python code as ``sys.executable``.
-
- This function should not be called before :c:func:`Py_Initialize`, otherwise
- it returns ``NULL``.
-
- .. versionchanged:: 3.10
- It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
-
- .. deprecated-removed:: 3.13 3.15
- Use :c:func:`PyConfig_Get("executable") <PyConfig_Get>`
- (:data:`sys.executable`) instead.
-
-
-.. c:function:: wchar_t* Py_GetPath()
-
- .. index::
- triple: module; search; path
- single: path (in module sys)
-
- Return the default module search path; this is computed from the program name
- (set by :c:member:`PyConfig.program_name`) and some environment variables.
- The returned string consists of a series of directory names separated by a
- platform dependent delimiter character. The delimiter character is ``':'``
- on Unix and macOS, ``';'`` on Windows. The returned string points into
- static storage; the caller should not modify its value. The list
- :data:`sys.path` is initialized with this value on interpreter startup; it
- can be (and usually is) modified later to change the search path for loading
- modules.
-
- This function should not be called before :c:func:`Py_Initialize`, otherwise
- it returns ``NULL``.
-
- .. XXX should give the exact rules
-
- .. versionchanged:: 3.10
- It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
-
- .. deprecated-removed:: 3.13 3.15
- Use :c:func:`PyConfig_Get("module_search_paths") <PyConfig_Get>`
- (:data:`sys.path`) instead.
-
-.. c:function:: const char* Py_GetVersion()
-
- Return the version of this Python interpreter. This is a string that looks
- something like ::
-
- "3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \n[GCC 4.2.3]"
-
- .. index:: single: version (in module sys)
-
- The first word (up to the first space character) is the current Python version;
- the first characters are the major and minor version separated by a
- period. The returned string points into static storage; the caller should not
- modify its value. The value is available to Python code as :data:`sys.version`.
-
- See also the :c:var:`Py_Version` constant.
-
-
-.. c:function:: const char* Py_GetPlatform()
-
- .. index:: single: platform (in module sys)
-
- Return the platform identifier for the current platform. On Unix, this is
- formed from the "official" name of the operating system, converted to lower
- case, followed by the major revision number; e.g., for Solaris 2.x, which is
- also known as SunOS 5.x, the value is ``'sunos5'``. On macOS, it is
- ``'darwin'``. On Windows, it is ``'win'``. The returned string points into
- static storage; the caller should not modify its value. The value is available
- to Python code as ``sys.platform``.
-
-
-.. c:function:: const char* Py_GetCopyright()
-
- Return the official copyright string for the current Python version, for example
-
- ``'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'``
-
- .. index:: single: copyright (in module sys)
-
- The returned string points into static storage; the caller should not modify its
- value. The value is available to Python code as ``sys.copyright``.
-
-
-.. c:function:: const char* Py_GetCompiler()
-
- Return an indication of the compiler used to build the current Python version,
- in square brackets, for example::
-
- "[GCC 2.7.2.2]"
-
- .. index:: single: version (in module sys)
-
- The returned string points into static storage; the caller should not modify its
- value. The value is available to Python code as part of the variable
- ``sys.version``.
-
-
-.. c:function:: const char* Py_GetBuildInfo()
-
- Return information about the sequence number and build date and time of the
- current Python interpreter instance, for example ::
-
- "#67, Aug 1 1997, 22:34:28"
-
- .. index:: single: version (in module sys)
-
- The returned string points into static storage; the caller should not modify its
- value. The value is available to Python code as part of the variable
- ``sys.version``.
-
-
-.. c:function:: void PySys_SetArgvEx(int argc, wchar_t **argv, int updatepath)
-
- .. index::
- single: main()
- single: Py_FatalError()
- single: argv (in module sys)
-
- This API is kept for backward compatibility: setting
- :c:member:`PyConfig.argv`, :c:member:`PyConfig.parse_argv` and
- :c:member:`PyConfig.safe_path` should be used instead, see :ref:`Python
- Initialization Configuration <init-config>`.
-
- Set :data:`sys.argv` based on *argc* and *argv*. These parameters are
- similar to those passed to the program's :c:func:`main` function with the
- difference that the first entry should refer to the script file to be
- executed rather than the executable hosting the Python interpreter. If there
- isn't a script that will be run, the first entry in *argv* can be an empty
- string. If this function fails to initialize :data:`sys.argv`, a fatal
- condition is signalled using :c:func:`Py_FatalError`.
-
- If *updatepath* is zero, this is all the function does. If *updatepath*
- is non-zero, the function also modifies :data:`sys.path` according to the
- following algorithm:
-
- - If the name of an existing script is passed in ``argv[0]``, the absolute
- path of the directory where the script is located is prepended to
- :data:`sys.path`.
- - Otherwise (that is, if *argc* is ``0`` or ``argv[0]`` doesn't point
- to an existing file name), an empty string is prepended to
- :data:`sys.path`, which is the same as prepending the current working
- directory (``"."``).
-
- Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
- :c:expr:`wchar_t*` string.
-
- See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv`
- members of the :ref:`Python Initialization Configuration <init-config>`.
-
- .. note::
- It is recommended that applications embedding the Python interpreter
- for purposes other than executing a single script pass ``0`` as *updatepath*,
- and update :data:`sys.path` themselves if desired.
- See :cve:`2008-5983`.
-
- On versions before 3.1.3, you can achieve the same effect by manually
- popping the first :data:`sys.path` element after having called
- :c:func:`PySys_SetArgv`, for example using::
-
- PyRun_SimpleString("import sys; sys.path.pop(0)\n");
-
- .. versionadded:: 3.1.3
-
- .. XXX impl. doesn't seem consistent in allowing ``0``/``NULL`` for the params;
- check w/ Guido.
-
- .. deprecated-removed:: 3.11 3.15
-
-
-.. c:function:: void PySys_SetArgv(int argc, wchar_t **argv)
-
- This API is kept for backward compatibility: setting
- :c:member:`PyConfig.argv` and :c:member:`PyConfig.parse_argv` should be used
- instead, see :ref:`Python Initialization Configuration <init-config>`.
-
- This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set
- to ``1`` unless the :program:`python` interpreter was started with the
- :option:`-I`.
-
- Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
- :c:expr:`wchar_t*` string.
-
- See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv`
- members of the :ref:`Python Initialization Configuration <init-config>`.
-
- .. versionchanged:: 3.4 The *updatepath* value depends on :option:`-I`.
-
- .. deprecated-removed:: 3.11 3.15
-
-
-.. c:function:: void Py_SetPythonHome(const wchar_t *home)
-
- This API is kept for backward compatibility: setting
- :c:member:`PyConfig.home` should be used instead, see :ref:`Python
- Initialization Configuration <init-config>`.
-
- Set the default "home" directory, that is, the location of the standard
- Python libraries. See :envvar:`PYTHONHOME` for the meaning of the
- argument string.
-
- The argument should point to a zero-terminated character string in static
- storage whose contents will not change for the duration of the program's
- execution. No code in the Python interpreter will change the contents of
- this storage.
-
- Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
- :c:expr:`wchar_t*` string.
-
- .. deprecated-removed:: 3.11 3.15
-
-
-.. c:function:: wchar_t* Py_GetPythonHome()
-
- Return the default "home", that is, the value set by
- :c:member:`PyConfig.home`, or the value of the :envvar:`PYTHONHOME`
- environment variable if it is set.
-
- This function should not be called before :c:func:`Py_Initialize`, otherwise
- it returns ``NULL``.
-
- .. versionchanged:: 3.10
- It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
-
- .. deprecated-removed:: 3.13 3.15
- Use :c:func:`PyConfig_Get("home") <PyConfig_Get>` or the
- :envvar:`PYTHONHOME` environment variable instead.
-
-
-.. _threads:
-
-Thread State and the Global Interpreter Lock
-============================================
-
-.. index::
- single: global interpreter lock
- single: interpreter lock
- single: lock, interpreter
-
-Unless on a :term:`free-threaded <free threading>` build of :term:`CPython`,
-the Python interpreter is not fully thread-safe. In order to support
-multi-threaded Python programs, there's a global lock, called the :term:`global
-interpreter lock` or :term:`GIL`, that must be held by the current thread before
-it can safely access Python objects. Without the lock, even the simplest
-operations could cause problems in a multi-threaded program: for example, when
-two threads simultaneously increment the reference count of the same object, the
-reference count could end up being incremented only once instead of twice.
-
-.. index:: single: setswitchinterval (in module sys)
-
-Therefore, the rule exists that only the thread that has acquired the
-:term:`GIL` may operate on Python objects or call Python/C API functions.
-In order to emulate concurrency of execution, the interpreter regularly
-tries to switch threads (see :func:`sys.setswitchinterval`). The lock is also
-released around potentially blocking I/O operations like reading or writing
-a file, so that other Python threads can run in the meantime.
-
-.. index::
- single: PyThreadState (C type)
-
-The Python interpreter keeps some thread-specific bookkeeping information
-inside a data structure called :c:type:`PyThreadState`, known as a :term:`thread state`.
-Each OS thread has a thread-local pointer to a :c:type:`PyThreadState`; a thread state
-referenced by this pointer is considered to be :term:`attached <attached thread state>`.
-
-A thread can only have one :term:`attached thread state` at a time. An attached
-thread state is typically analogous with holding the :term:`GIL`, except on
-:term:`free-threaded <free threading>` builds. On builds with the :term:`GIL` enabled,
-:term:`attaching <attached thread state>` a thread state will block until the :term:`GIL`
-can be acquired. However, even on builds with the :term:`GIL` disabled, it is still required
-to have an attached thread state to call most of the C API.
-
-In general, there will always be an :term:`attached thread state` when using Python's C API.
-Only in some specific cases (such as in a :c:macro:`Py_BEGIN_ALLOW_THREADS` block) will the
-thread not have an attached thread state. If uncertain, check if :c:func:`PyThreadState_GetUnchecked` returns
-``NULL``.
-
-Detaching the thread state from extension code
-----------------------------------------------
-
-Most extension code manipulating the :term:`thread state` has the following simple
-structure::
-
- Save the thread state in a local variable.
- ... Do some blocking I/O operation ...
- Restore the thread state from the local variable.
-
-This is so common that a pair of macros exists to simplify it::
-
- Py_BEGIN_ALLOW_THREADS
- ... Do some blocking I/O operation ...
- Py_END_ALLOW_THREADS
-
-.. index::
- single: Py_BEGIN_ALLOW_THREADS (C macro)
- single: Py_END_ALLOW_THREADS (C macro)
-
-The :c:macro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a
-hidden local variable; the :c:macro:`Py_END_ALLOW_THREADS` macro closes the
-block.
-
-The block above expands to the following code::
-
- PyThreadState *_save;
-
- _save = PyEval_SaveThread();
- ... Do some blocking I/O operation ...
- PyEval_RestoreThread(_save);
-
-.. index::
- single: PyEval_RestoreThread (C function)
- single: PyEval_SaveThread (C function)
-
-Here is how these functions work:
-
-The :term:`attached thread state` holds the :term:`GIL` for the entire interpreter. When detaching
-the :term:`attached thread state`, the :term:`GIL` is released, allowing other threads to attach
-a thread state to their own thread, thus getting the :term:`GIL` and can start executing.
-The pointer to the prior :term:`attached thread state` is stored as a local variable.
-Upon reaching :c:macro:`Py_END_ALLOW_THREADS`, the thread state that was
-previously :term:`attached <attached thread state>` is passed to :c:func:`PyEval_RestoreThread`.
-This function will block until another releases its :term:`thread state <attached thread state>`,
-thus allowing the old :term:`thread state <attached thread state>` to get re-attached and the
-C API can be called again.
-
-For :term:`free-threaded <free threading>` builds, the :term:`GIL` is normally
-out of the question, but detaching the :term:`thread state <attached thread state>` is still required
-for blocking I/O and long operations. The difference is that threads don't have to wait for the :term:`GIL`
-to be released to attach their thread state, allowing true multi-core parallelism.
-
-.. note::
- Calling system I/O functions is the most common use case for detaching
- the :term:`thread state <attached thread state>`, but it can also be useful before calling
- long-running computations which don't need access to Python objects, such
- as compression or cryptographic functions operating over memory buffers.
- For example, the standard :mod:`zlib` and :mod:`hashlib` modules detach the
- :term:`thread state <attached thread state>` when compressing or hashing data.
-
-
-.. _gilstate:
-
-Non-Python created threads
---------------------------
-
-When threads are created using the dedicated Python APIs (such as the
-:mod:`threading` module), a thread state is automatically associated to them
-and the code showed above is therefore correct. However, when threads are
-created from C (for example by a third-party library with its own thread
-management), they don't hold the :term:`GIL`, because they don't have an
-:term:`attached thread state`.
-
-If you need to call Python code from these threads (often this will be part
-of a callback API provided by the aforementioned third-party library),
-you must first register these threads with the interpreter by
-creating an :term:`attached thread state` before you can start using the Python/C
-API. When you are done, you should detach the :term:`thread state <attached thread state>`, and
-finally free it.
-
-The :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` functions do
-all of the above automatically. The typical idiom for calling into Python
-from a C thread is::
-
- PyGILState_STATE gstate;
- gstate = PyGILState_Ensure();
-
- /* Perform Python actions here. */
- result = CallSomeFunction();
- /* evaluate result or handle exception */
-
- /* Release the thread. No Python API allowed beyond this point. */
- PyGILState_Release(gstate);
-
-Note that the ``PyGILState_*`` functions assume there is only one global
-interpreter (created automatically by :c:func:`Py_Initialize`). Python
-supports the creation of additional interpreters (using
-:c:func:`Py_NewInterpreter`), but mixing multiple interpreters and the
-``PyGILState_*`` API is unsupported. This is because :c:func:`PyGILState_Ensure`
-and similar functions default to :term:`attaching <attached thread state>` a
-:term:`thread state` for the main interpreter, meaning that the thread can't safely
-interact with the calling subinterpreter.
-
-Supporting subinterpreters in non-Python threads
-------------------------------------------------
-
-If you would like to support subinterpreters with non-Python created threads, you
-must use the ``PyThreadState_*`` API instead of the traditional ``PyGILState_*``
-API.
-
-In particular, you must store the interpreter state from the calling
-function and pass it to :c:func:`PyThreadState_New`, which will ensure that
-the :term:`thread state` is targeting the correct interpreter::
-
- /* The return value of PyInterpreterState_Get() from the
- function that created this thread. */
- PyInterpreterState *interp = ThreadData->interp;
- PyThreadState *tstate = PyThreadState_New(interp);
- PyThreadState_Swap(tstate);
-
- /* GIL of the subinterpreter is now held.
- Perform Python actions here. */
- result = CallSomeFunction();
- /* evaluate result or handle exception */
-
- /* Destroy the thread state. No Python API allowed beyond this point. */
- PyThreadState_Clear(tstate);
- PyThreadState_DeleteCurrent();
-
-.. _fork-and-threads:
-
-Cautions about fork()
----------------------
-
-Another important thing to note about threads is their behaviour in the face
-of the C :c:func:`fork` call. On most systems with :c:func:`fork`, after a
-process forks only the thread that issued the fork will exist. This has a
-concrete impact both on how locks must be handled and on all stored state
-in CPython's runtime.
-
-The fact that only the "current" thread remains
-means any locks held by other threads will never be released. Python solves
-this for :func:`os.fork` by acquiring the locks it uses internally before
-the fork, and releasing them afterwards. In addition, it resets any
-:ref:`lock-objects` in the child. When extending or embedding Python, there
-is no way to inform Python of additional (non-Python) locks that need to be
-acquired before or reset after a fork. OS facilities such as
-:c:func:`!pthread_atfork` would need to be used to accomplish the same thing.
-Additionally, when extending or embedding Python, calling :c:func:`fork`
-directly rather than through :func:`os.fork` (and returning to or calling
-into Python) may result in a deadlock by one of Python's internal locks
-being held by a thread that is defunct after the fork.
-:c:func:`PyOS_AfterFork_Child` tries to reset the necessary locks, but is not
-always able to.
-
-The fact that all other threads go away also means that CPython's
-runtime state there must be cleaned up properly, which :func:`os.fork`
-does. This means finalizing all other :c:type:`PyThreadState` objects
-belonging to the current interpreter and all other
-:c:type:`PyInterpreterState` objects. Due to this and the special
-nature of the :ref:`"main" interpreter <sub-interpreter-support>`,
-:c:func:`fork` should only be called in that interpreter's "main"
-thread, where the CPython global runtime was originally initialized.
-The only exception is if :c:func:`exec` will be called immediately
-after.
-
-.. _cautions-regarding-runtime-finalization:
-
-Cautions regarding runtime finalization
----------------------------------------
-
-In the late stage of :term:`interpreter shutdown`, after attempting to wait for
-non-daemon threads to exit (though this can be interrupted by
-:class:`KeyboardInterrupt`) and running the :mod:`atexit` functions, the runtime
-is marked as *finalizing*: :c:func:`Py_IsFinalizing` and
-:func:`sys.is_finalizing` return true. At this point, only the *finalization
-thread* that initiated finalization (typically the main thread) is allowed to
-acquire the :term:`GIL`.
-
-If any thread, other than the finalization thread, attempts to attach a :term:`thread state`
-during finalization, either explicitly or
-implicitly, the thread enters **a permanently blocked state**
-where it remains until the program exits. In most cases this is harmless, but this can result
-in deadlock if a later stage of finalization attempts to acquire a lock owned by the
-blocked thread, or otherwise waits on the blocked thread.
-
-Gross? Yes. This prevents random crashes and/or unexpectedly skipped C++
-finalizations further up the call stack when such threads were forcibly exited
-here in CPython 3.13 and earlier. The CPython runtime :term:`thread state` C APIs
-have never had any error reporting or handling expectations at :term:`thread state`
-attachment time that would've allowed for graceful exit from this situation. Changing that
-would require new stable C APIs and rewriting the majority of C code in the
-CPython ecosystem to use those with error handling.
-
-
-High-level API
---------------
-
-These are the most commonly used types and functions when writing C extension
-code, or when embedding the Python interpreter:
-
-.. c:type:: PyInterpreterState
-
- This data structure represents the state shared by a number of cooperating
- threads. Threads belonging to the same interpreter share their module
- administration and a few other internal items. There are no public members in
- this structure.
-
- Threads belonging to different interpreters initially share nothing, except
- process state like available memory, open file descriptors and such. The global
- interpreter lock is also shared by all threads, regardless of to which
- interpreter they belong.
-
- .. versionchanged:: 3.12
-
- :pep:`684` introduced the possibility
- of a :ref:`per-interpreter GIL <per-interpreter-gil>`.
- See :c:func:`Py_NewInterpreterFromConfig`.
-
-
-.. c:type:: PyThreadState
-
- This data structure represents the state of a single thread. The only public
- data member is:
-
- .. c:member:: PyInterpreterState *interp
-
- This thread's interpreter state.
-
-
-.. c:function:: void PyEval_InitThreads()
-
- .. index::
- single: PyEval_AcquireThread()
- single: PyEval_ReleaseThread()
- single: PyEval_SaveThread()
- single: PyEval_RestoreThread()
-
- Deprecated function which does nothing.
-
- In Python 3.6 and older, this function created the GIL if it didn't exist.
-
- .. versionchanged:: 3.9
- The function now does nothing.
-
- .. versionchanged:: 3.7
- This function is now called by :c:func:`Py_Initialize()`, so you don't
- have to call it yourself anymore.
-
- .. versionchanged:: 3.2
- This function cannot be called before :c:func:`Py_Initialize()` anymore.
-
- .. deprecated:: 3.9
-
- .. index:: pair: module; _thread
-
-
-.. c:function:: PyThreadState* PyEval_SaveThread()
-
- Detach the :term:`attached thread state` and return it.
- The thread will have no :term:`thread state` upon returning.
-
-
-.. c:function:: void PyEval_RestoreThread(PyThreadState *tstate)
-
- Set the :term:`attached thread state` to *tstate*.
- The passed :term:`thread state` **should not** be :term:`attached <attached thread state>`,
- otherwise deadlock ensues. *tstate* will be attached upon returning.
-
- .. note::
- Calling this function from a thread when the runtime is finalizing will
- hang the thread until the program exits, even if the thread was not
- created by Python. Refer to
- :ref:`cautions-regarding-runtime-finalization` for more details.
-
- .. versionchanged:: 3.14
- Hangs the current thread, rather than terminating it, if called while the
- interpreter is finalizing.
-
-.. c:function:: PyThreadState* PyThreadState_Get()
-
- Return the :term:`attached thread state`. If the thread has no attached
- thread state, (such as when inside of :c:macro:`Py_BEGIN_ALLOW_THREADS`
- block), then this issues a fatal error (so that the caller needn't check
- for ``NULL``).
-
- See also :c:func:`PyThreadState_GetUnchecked`.
-
-.. c:function:: PyThreadState* PyThreadState_GetUnchecked()
-
- Similar to :c:func:`PyThreadState_Get`, but don't kill the process with a
- fatal error if it is NULL. The caller is responsible to check if the result
- is NULL.
-
- .. versionadded:: 3.13
- In Python 3.5 to 3.12, the function was private and known as
- ``_PyThreadState_UncheckedGet()``.
-
-
-.. c:function:: PyThreadState* PyThreadState_Swap(PyThreadState *tstate)
-
- Set the :term:`attached thread state` to *tstate*, and return the
- :term:`thread state` that was attached prior to calling.
-
- This function is safe to call without an :term:`attached thread state`; it
- will simply return ``NULL`` indicating that there was no prior thread state.
-
- .. seealso::
- :c:func:`PyEval_ReleaseThread`
-
- .. note::
- Similar to :c:func:`PyGILState_Ensure`, this function will hang the
- thread if the runtime is finalizing.
-
-
-The following functions use thread-local storage, and are not compatible
-with sub-interpreters:
-
-.. c:type:: PyGILState_STATE
-
- The type of the value returned by :c:func:`PyGILState_Ensure` and passed to
- :c:func:`PyGILState_Release`.
-
- .. c:enumerator:: PyGILState_LOCKED
-
- The GIL was already held when :c:func:`PyGILState_Ensure` was called.
-
- .. c:enumerator:: PyGILState_UNLOCKED
-
- The GIL was not held when :c:func:`PyGILState_Ensure` was called.
-
-.. c:function:: PyGILState_STATE PyGILState_Ensure()
-
- Ensure that the current thread is ready to call the Python C API regardless
- of the current state of Python, or of the :term:`attached thread state`. This may
- be called as many times as desired by a thread as long as each call is
- matched with a call to :c:func:`PyGILState_Release`. In general, other
- thread-related APIs may be used between :c:func:`PyGILState_Ensure` and
- :c:func:`PyGILState_Release` calls as long as the thread state is restored to
- its previous state before the Release(). For example, normal usage of the
- :c:macro:`Py_BEGIN_ALLOW_THREADS` and :c:macro:`Py_END_ALLOW_THREADS` macros is
- acceptable.
-
- The return value is an opaque "handle" to the :term:`attached thread state` when
- :c:func:`PyGILState_Ensure` was called, and must be passed to
- :c:func:`PyGILState_Release` to ensure Python is left in the same state. Even
- though recursive calls are allowed, these handles *cannot* be shared - each
- unique call to :c:func:`PyGILState_Ensure` must save the handle for its call
- to :c:func:`PyGILState_Release`.
-
- When the function returns, there will be an :term:`attached thread state`
- and the thread will be able to call arbitrary Python code. Failure is a fatal error.
-
- .. warning::
- Calling this function when the runtime is finalizing is unsafe. Doing
- so will either hang the thread until the program ends, or fully crash
- the interpreter in rare cases. Refer to
- :ref:`cautions-regarding-runtime-finalization` for more details.
-
- .. versionchanged:: 3.14
- Hangs the current thread, rather than terminating it, if called while the
- interpreter is finalizing.
-
-.. c:function:: void PyGILState_Release(PyGILState_STATE)
-
- Release any resources previously acquired. After this call, Python's state will
- be the same as it was prior to the corresponding :c:func:`PyGILState_Ensure` call
- (but generally this state will be unknown to the caller, hence the use of the
- GILState API).
-
- Every call to :c:func:`PyGILState_Ensure` must be matched by a call to
- :c:func:`PyGILState_Release` on the same thread.
-
-.. c:function:: PyThreadState* PyGILState_GetThisThreadState()
-
- Get the :term:`attached thread state` for this thread. May return ``NULL`` if no
- GILState API has been used on the current thread. Note that the main thread
- always has such a thread-state, even if no auto-thread-state call has been
- made on the main thread. This is mainly a helper/diagnostic function.
-
- .. note::
- This function may return non-``NULL`` even when the :term:`thread state`
- is detached.
- Prefer :c:func:`PyThreadState_Get` or :c:func:`PyThreadState_GetUnchecked`
- for most cases.
-
- .. seealso:: :c:func:`PyThreadState_Get`
-
-.. c:function:: int PyGILState_Check()
-
- Return ``1`` if the current thread is holding the :term:`GIL` and ``0`` otherwise.
- This function can be called from any thread at any time.
- Only if it has had its :term:`thread state <attached thread state>` initialized
- via :c:func:`PyGILState_Ensure` will it return ``1``.
- This is mainly a helper/diagnostic function. It can be useful
- for example in callback contexts or memory allocation functions when
- knowing that the :term:`GIL` is locked can allow the caller to perform sensitive
- actions or otherwise behave differently.
-
- .. note::
- If the current Python process has ever created a subinterpreter, this
- function will *always* return ``1``. Prefer :c:func:`PyThreadState_GetUnchecked`
- for most cases.
-
- .. versionadded:: 3.4
-
-
-The following macros are normally used without a trailing semicolon; look for
-example usage in the Python source distribution.
-
-
-.. c:macro:: Py_BEGIN_ALLOW_THREADS
-
- This macro expands to ``{ PyThreadState *_save; _save = PyEval_SaveThread();``.
- Note that it contains an opening brace; it must be matched with a following
- :c:macro:`Py_END_ALLOW_THREADS` macro. See above for further discussion of this
- macro.
-
-
-.. c:macro:: Py_END_ALLOW_THREADS
-
- This macro expands to ``PyEval_RestoreThread(_save); }``. Note that it contains
- a closing brace; it must be matched with an earlier
- :c:macro:`Py_BEGIN_ALLOW_THREADS` macro. See above for further discussion of
- this macro.
-
-
-.. c:macro:: Py_BLOCK_THREADS
-
- This macro expands to ``PyEval_RestoreThread(_save);``: it is equivalent to
- :c:macro:`Py_END_ALLOW_THREADS` without the closing brace.
-
-
-.. c:macro:: Py_UNBLOCK_THREADS
-
- This macro expands to ``_save = PyEval_SaveThread();``: it is equivalent to
- :c:macro:`Py_BEGIN_ALLOW_THREADS` without the opening brace and variable
- declaration.
-
-
-Low-level API
--------------
-
-All of the following functions must be called after :c:func:`Py_Initialize`.
-
-.. versionchanged:: 3.7
- :c:func:`Py_Initialize()` now initializes the :term:`GIL`
- and sets an :term:`attached thread state`.
-
-
-.. c:function:: PyInterpreterState* PyInterpreterState_New()
-
- Create a new interpreter state object. An :term:`attached thread state` is not needed,
- but may optionally exist if it is necessary to serialize calls to this
- function.
-
- .. audit-event:: cpython.PyInterpreterState_New "" c.PyInterpreterState_New
-
-
-.. c:function:: void PyInterpreterState_Clear(PyInterpreterState *interp)
-
- Reset all information in an interpreter state object. There must be
- an :term:`attached thread state` for the interpreter.
-
- .. audit-event:: cpython.PyInterpreterState_Clear "" c.PyInterpreterState_Clear
-
-
-.. c:function:: void PyInterpreterState_Delete(PyInterpreterState *interp)
-
- Destroy an interpreter state object. There **should not** be an
- :term:`attached thread state` for the target interpreter. The interpreter
- state must have been reset with a previous call to :c:func:`PyInterpreterState_Clear`.
-
-
-.. c:function:: PyThreadState* PyThreadState_New(PyInterpreterState *interp)
-
- Create a new thread state object belonging to the given interpreter object.
- An :term:`attached thread state` is not needed.
-
-.. c:function:: void PyThreadState_Clear(PyThreadState *tstate)
-
- Reset all information in a :term:`thread state` object. *tstate*
- must be :term:`attached <attached thread state>`
-
- .. versionchanged:: 3.9
- This function now calls the :c:member:`!PyThreadState.on_delete` callback.
- Previously, that happened in :c:func:`PyThreadState_Delete`.
-
- .. versionchanged:: 3.13
- The :c:member:`!PyThreadState.on_delete` callback was removed.
-
-
-.. c:function:: void PyThreadState_Delete(PyThreadState *tstate)
-
- Destroy a :term:`thread state` object. *tstate* should not
- be :term:`attached <attached thread state>` to any thread.
- *tstate* must have been reset with a previous call to
- :c:func:`PyThreadState_Clear`.
-
-
-.. c:function:: void PyThreadState_DeleteCurrent(void)
-
- Detach the :term:`attached thread state` (which must have been reset
- with a previous call to :c:func:`PyThreadState_Clear`) and then destroy it.
-
- No :term:`thread state` will be :term:`attached <attached thread state>` upon
- returning.
-
-.. c:function:: PyFrameObject* PyThreadState_GetFrame(PyThreadState *tstate)
-
- Get the current frame of the Python thread state *tstate*.
-
- Return a :term:`strong reference`. Return ``NULL`` if no frame is currently
- executing.
-
- See also :c:func:`PyEval_GetFrame`.
-
- *tstate* must not be ``NULL``, and must be :term:`attached <attached thread state>`.
-
- .. versionadded:: 3.9
-
-
-.. c:function:: uint64_t PyThreadState_GetID(PyThreadState *tstate)
-
- Get the unique :term:`thread state` identifier of the Python thread state *tstate*.
-
- *tstate* must not be ``NULL``, and must be :term:`attached <attached thread state>`.
-
- .. versionadded:: 3.9
-
-
-.. c:function:: PyInterpreterState* PyThreadState_GetInterpreter(PyThreadState *tstate)
-
- Get the interpreter of the Python thread state *tstate*.
-
- *tstate* must not be ``NULL``, and must be :term:`attached <attached thread state>`.
-
- .. versionadded:: 3.9
-
-
-.. c:function:: void PyThreadState_EnterTracing(PyThreadState *tstate)
-
- Suspend tracing and profiling in the Python thread state *tstate*.
-
- Resume them using the :c:func:`PyThreadState_LeaveTracing` function.
-
- .. versionadded:: 3.11
-
-
-.. c:function:: void PyThreadState_LeaveTracing(PyThreadState *tstate)
-
- Resume tracing and profiling in the Python thread state *tstate* suspended
- by the :c:func:`PyThreadState_EnterTracing` function.
-
- See also :c:func:`PyEval_SetTrace` and :c:func:`PyEval_SetProfile`
- functions.
-
- .. versionadded:: 3.11
-
-
-.. c:function:: int PyUnstable_ThreadState_SetStackProtection(PyThreadState *tstate, void *stack_start_addr, size_t stack_size)
-
- Set the stack protection start address and stack protection size
- of a Python thread state.
-
- On success, return ``0``.
- On failure, set an exception and return ``-1``.
-
- CPython implements :ref:`recursion control <recursion>` for C code by raising
- :py:exc:`RecursionError` when it notices that the machine execution stack is close
- to overflow. See for example the :c:func:`Py_EnterRecursiveCall` function.
- For this, it needs to know the location of the current thread's stack, which it
- normally gets from the operating system.
- When the stack is changed, for example using context switching techniques like the
- Boost library's ``boost::context``, you must call
- :c:func:`~PyUnstable_ThreadState_SetStackProtection` to inform CPython of the change.
-
- Call :c:func:`~PyUnstable_ThreadState_SetStackProtection` either before
- or after changing the stack.
- Do not call any other Python C API between the call and the stack
- change.
-
- See :c:func:`PyUnstable_ThreadState_ResetStackProtection` for undoing this operation.
-
- .. versionadded:: 3.14.1
-
- .. warning::
-
- This function was added in a bugfix release, and
- extensions that use it will be incompatible with Python 3.14.0.
- Most packaging tools for Python are not able to handle this
- incompatibility automatically, and will need explicit configuration.
- When using PyPA standards (wheels and source distributions),
- specify ``Requires-Python: != 3.14.0.*`` in
- `core metadata <https://packaging.python.org/en/latest/specifications/core-metadata/#requires-python>`_.
-
-
-.. c:function:: void PyUnstable_ThreadState_ResetStackProtection(PyThreadState *tstate)
-
- Reset the stack protection start address and stack protection size
- of a Python thread state to the operating system defaults.
-
- See :c:func:`PyUnstable_ThreadState_SetStackProtection` for an explanation.
-
- .. versionadded:: 3.14.1
-
- .. warning::
-
- This function was added in a bugfix release, and
- extensions that use it will be incompatible with Python 3.14.0.
- Most packaging tools for Python are not able to handle this
- incompatibility automatically, and will need explicit configuration.
- When using PyPA standards (wheels and source distributions),
- specify ``Requires-Python: != 3.14.0.*`` in
- `core metadata <https://packaging.python.org/en/latest/specifications/core-metadata/#requires-python>`_.
-
-
-.. c:function:: PyInterpreterState* PyInterpreterState_Get(void)
-
- Get the current interpreter.
-
- Issue a fatal error if there no :term:`attached thread state`.
- It cannot return NULL.
-
- .. versionadded:: 3.9
-
-
-.. c:function:: int64_t PyInterpreterState_GetID(PyInterpreterState *interp)
-
- Return the interpreter's unique ID. If there was any error in doing
- so then ``-1`` is returned and an error is set.
-
- The caller must have an :term:`attached thread state`.
-
- .. versionadded:: 3.7
-
-
-.. c:function:: PyObject* PyInterpreterState_GetDict(PyInterpreterState *interp)
-
- Return a dictionary in which interpreter-specific data may be stored.
- If this function returns ``NULL`` then no exception has been raised and
- the caller should assume no interpreter-specific dict is available.
-
- This is not a replacement for :c:func:`PyModule_GetState()`, which
- extensions should use to store interpreter-specific state information.
-
- The returned dictionary is borrowed from the interpreter and is valid until
- interpreter shutdown.
-
- .. versionadded:: 3.8
-
-
-.. c:type:: PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, _PyInterpreterFrame *frame, int throwflag)
-
- Type of a frame evaluation function.
-
- The *throwflag* parameter is used by the ``throw()`` method of generators:
- if non-zero, handle the current exception.
-
- .. versionchanged:: 3.9
- The function now takes a *tstate* parameter.
-
- .. versionchanged:: 3.11
- The *frame* parameter changed from ``PyFrameObject*`` to ``_PyInterpreterFrame*``.
-
-.. c:function:: _PyFrameEvalFunction _PyInterpreterState_GetEvalFrameFunc(PyInterpreterState *interp)
-
- Get the frame evaluation function.
-
- See the :pep:`523` "Adding a frame evaluation API to CPython".
-
- .. versionadded:: 3.9
-
-.. c:function:: void _PyInterpreterState_SetEvalFrameFunc(PyInterpreterState *interp, _PyFrameEvalFunction eval_frame)
-
- Set the frame evaluation function.
-
- See the :pep:`523` "Adding a frame evaluation API to CPython".
-
- .. versionadded:: 3.9
-
-
-.. c:function:: PyObject* PyThreadState_GetDict()
-
- Return a dictionary in which extensions can store thread-specific state
- information. Each extension should use a unique key to use to store state in
- the dictionary. It is okay to call this function when no :term:`thread state`
- is :term:`attached <attached thread state>`. If this function returns
- ``NULL``, no exception has been raised and the caller should assume no
- thread state is attached.
-
-
-.. c:function:: int PyThreadState_SetAsyncExc(unsigned long id, PyObject *exc)
-
- Asynchronously raise an exception in a thread. The *id* argument is the thread
- id of the target thread; *exc* is the exception object to be raised. This
- function does not steal any references to *exc*. To prevent naive misuse, you
- must write your own C extension to call this. Must be called with an :term:`attached thread state`.
- Returns the number of thread states modified; this is normally one, but will be
- zero if the thread id isn't found. If *exc* is ``NULL``, the pending
- exception (if any) for the thread is cleared. This raises no exceptions.
-
- .. versionchanged:: 3.7
- The type of the *id* parameter changed from :c:expr:`long` to
- :c:expr:`unsigned long`.
-
-.. c:function:: void PyEval_AcquireThread(PyThreadState *tstate)
-
- :term:`Attach <attached thread state>` *tstate* to the current thread,
- which must not be ``NULL`` or already :term:`attached <attached thread state>`.
-
- The calling thread must not already have an :term:`attached thread state`.
-
- .. note::
- Calling this function from a thread when the runtime is finalizing will
- hang the thread until the program exits, even if the thread was not
- created by Python. Refer to
- :ref:`cautions-regarding-runtime-finalization` for more details.
-
- .. versionchanged:: 3.8
- Updated to be consistent with :c:func:`PyEval_RestoreThread`,
- :c:func:`Py_END_ALLOW_THREADS`, and :c:func:`PyGILState_Ensure`,
- and terminate the current thread if called while the interpreter is finalizing.
-
- .. versionchanged:: 3.14
- Hangs the current thread, rather than terminating it, if called while the
- interpreter is finalizing.
-
- :c:func:`PyEval_RestoreThread` is a higher-level function which is always
- available (even when threads have not been initialized).
-
-
-.. c:function:: void PyEval_ReleaseThread(PyThreadState *tstate)
-
- Detach the :term:`attached thread state`.
- The *tstate* argument, which must not be ``NULL``, is only used to check
- that it represents the :term:`attached thread state` --- if it isn't, a fatal error is
- reported.
-
- :c:func:`PyEval_SaveThread` is a higher-level function which is always
- available (even when threads have not been initialized).
-
-
-.. _sub-interpreter-support:
-
-Sub-interpreter support
-=======================
-
-While in most uses, you will only embed a single Python interpreter, there
-are cases where you need to create several independent interpreters in the
-same process and perhaps even in the same thread. Sub-interpreters allow
-you to do that.
-
-The "main" interpreter is the first one created when the runtime initializes.
-It is usually the only Python interpreter in a process. Unlike sub-interpreters,
-the main interpreter has unique process-global responsibilities like signal
-handling. It is also responsible for execution during runtime initialization and
-is usually the active interpreter during runtime finalization. The
-:c:func:`PyInterpreterState_Main` function returns a pointer to its state.
-
-You can switch between sub-interpreters using the :c:func:`PyThreadState_Swap`
-function. You can create and destroy them using the following functions:
-
-
-.. c:type:: PyInterpreterConfig
-
- Structure containing most parameters to configure a sub-interpreter.
- Its values are used only in :c:func:`Py_NewInterpreterFromConfig` and
- never modified by the runtime.
-
- .. versionadded:: 3.12
-
- Structure fields:
-
- .. c:member:: int use_main_obmalloc
-
- If this is ``0`` then the sub-interpreter will use its own
- "object" allocator state.
- Otherwise it will use (share) the main interpreter's.
-
- If this is ``0`` then
- :c:member:`~PyInterpreterConfig.check_multi_interp_extensions`
- must be ``1`` (non-zero).
- If this is ``1`` then :c:member:`~PyInterpreterConfig.gil`
- must not be :c:macro:`PyInterpreterConfig_OWN_GIL`.
-
- .. c:member:: int allow_fork
-
- If this is ``0`` then the runtime will not support forking the
- process in any thread where the sub-interpreter is currently active.
- Otherwise fork is unrestricted.
-
- Note that the :mod:`subprocess` module still works
- when fork is disallowed.
-
- .. c:member:: int allow_exec
-
- If this is ``0`` then the runtime will not support replacing the
- current process via exec (e.g. :func:`os.execv`) in any thread
- where the sub-interpreter is currently active.
- Otherwise exec is unrestricted.
-
- Note that the :mod:`subprocess` module still works
- when exec is disallowed.
-
- .. c:member:: int allow_threads
-
- If this is ``0`` then the sub-interpreter's :mod:`threading` module
- won't create threads.
- Otherwise threads are allowed.
-
- .. c:member:: int allow_daemon_threads
-
- If this is ``0`` then the sub-interpreter's :mod:`threading` module
- won't create daemon threads.
- Otherwise daemon threads are allowed (as long as
- :c:member:`~PyInterpreterConfig.allow_threads` is non-zero).
-
- .. c:member:: int check_multi_interp_extensions
-
- If this is ``0`` then all extension modules may be imported,
- including legacy (single-phase init) modules,
- in any thread where the sub-interpreter is currently active.
- Otherwise only multi-phase init extension modules
- (see :pep:`489`) may be imported.
- (Also see :c:macro:`Py_mod_multiple_interpreters`.)
-
- This must be ``1`` (non-zero) if
- :c:member:`~PyInterpreterConfig.use_main_obmalloc` is ``0``.
-
- .. c:member:: int gil
-
- This determines the operation of the GIL for the sub-interpreter.
- It may be one of the following:
-
- .. c:namespace:: NULL
-
- .. c:macro:: PyInterpreterConfig_DEFAULT_GIL
-
- Use the default selection (:c:macro:`PyInterpreterConfig_SHARED_GIL`).
-
- .. c:macro:: PyInterpreterConfig_SHARED_GIL
-
- Use (share) the main interpreter's GIL.
-
- .. c:macro:: PyInterpreterConfig_OWN_GIL
-
- Use the sub-interpreter's own GIL.
-
- If this is :c:macro:`PyInterpreterConfig_OWN_GIL` then
- :c:member:`PyInterpreterConfig.use_main_obmalloc` must be ``0``.
-
-
-.. c:function:: PyStatus Py_NewInterpreterFromConfig(PyThreadState **tstate_p, const PyInterpreterConfig *config)
-
- .. index::
- pair: module; builtins
- pair: module; __main__
- pair: module; sys
- single: stdout (in module sys)
- single: stderr (in module sys)
- single: stdin (in module sys)
-
- Create a new sub-interpreter. This is an (almost) totally separate environment
- for the execution of Python code. In particular, the new interpreter has
- separate, independent versions of all imported modules, including the
- fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. The
- table of loaded modules (``sys.modules``) and the module search path
- (``sys.path``) are also separate. The new environment has no ``sys.argv``
- variable. It has new standard I/O stream file objects ``sys.stdin``,
- ``sys.stdout`` and ``sys.stderr`` (however these refer to the same underlying
- file descriptors).
-
- The given *config* controls the options with which the interpreter
- is initialized.
-
- Upon success, *tstate_p* will be set to the first :term:`thread state`
- created in the new sub-interpreter. This thread state is
- :term:`attached <attached thread state>`.
- Note that no actual thread is created; see the discussion of thread states
- below. If creation of the new interpreter is unsuccessful,
- *tstate_p* is set to ``NULL``;
- no exception is set since the exception state is stored in the
- :term:`attached thread state`, which might not exist.
-
- Like all other Python/C API functions, an :term:`attached thread state`
- must be present before calling this function, but it might be detached upon
- returning. On success, the returned thread state will be :term:`attached <attached thread state>`.
- If the sub-interpreter is created with its own :term:`GIL` then the
- :term:`attached thread state` of the calling interpreter will be detached.
- When the function returns, the new interpreter's :term:`thread state`
- will be :term:`attached <attached thread state>` to the current thread and
- the previous interpreter's :term:`attached thread state` will remain detached.
-
- .. versionadded:: 3.12
-
- Sub-interpreters are most effective when isolated from each other,
- with certain functionality restricted::
-
- PyInterpreterConfig config = {
- .use_main_obmalloc = 0,
- .allow_fork = 0,
- .allow_exec = 0,
- .allow_threads = 1,
- .allow_daemon_threads = 0,
- .check_multi_interp_extensions = 1,
- .gil = PyInterpreterConfig_OWN_GIL,
- };
- PyThreadState *tstate = NULL;
- PyStatus status = Py_NewInterpreterFromConfig(&tstate, &config);
- if (PyStatus_Exception(status)) {
- Py_ExitStatusException(status);
- }
-
- Note that the config is used only briefly and does not get modified.
- During initialization the config's values are converted into various
- :c:type:`PyInterpreterState` values. A read-only copy of the config
- may be stored internally on the :c:type:`PyInterpreterState`.
-
- .. index::
- single: Py_FinalizeEx (C function)
- single: Py_Initialize (C function)
-
- Extension modules are shared between (sub-)interpreters as follows:
-
- * For modules using multi-phase initialization,
- e.g. :c:func:`PyModule_FromDefAndSpec`, a separate module object is
- created and initialized for each interpreter.
- Only C-level static and global variables are shared between these
- module objects.
-
- * For modules using single-phase initialization,
- e.g. :c:func:`PyModule_Create`, the first time a particular extension
- is imported, it is initialized normally, and a (shallow) copy of its
- module's dictionary is squirreled away.
- When the same extension is imported by another (sub-)interpreter, a new
- module is initialized and filled with the contents of this copy; the
- extension's ``init`` function is not called.
- Objects in the module's dictionary thus end up shared across
- (sub-)interpreters, which might cause unwanted behavior (see
- `Bugs and caveats`_ below).
-
- Note that this is different from what happens when an extension is
- imported after the interpreter has been completely re-initialized by
- calling :c:func:`Py_FinalizeEx` and :c:func:`Py_Initialize`; in that
- case, the extension's ``initmodule`` function *is* called again.
- As with multi-phase initialization, this means that only C-level static
- and global variables are shared between these modules.
-
- .. index:: single: close (in module os)
-
-
-.. c:function:: PyThreadState* Py_NewInterpreter(void)
-
- .. index::
- pair: module; builtins
- pair: module; __main__
- pair: module; sys
- single: stdout (in module sys)
- single: stderr (in module sys)
- single: stdin (in module sys)
-
- Create a new sub-interpreter. This is essentially just a wrapper
- around :c:func:`Py_NewInterpreterFromConfig` with a config that
- preserves the existing behavior. The result is an unisolated
- sub-interpreter that shares the main interpreter's GIL, allows
- fork/exec, allows daemon threads, and allows single-phase init
- modules.
-
-
-.. c:function:: void Py_EndInterpreter(PyThreadState *tstate)
-
- .. index:: single: Py_FinalizeEx (C function)
-
- Destroy the (sub-)interpreter represented by the given :term:`thread state`.
- The given thread state must be :term:`attached <attached thread state>`.
- When the call returns, there will be no :term:`attached thread state`.
- All thread states associated with this interpreter are destroyed.
-
- :c:func:`Py_FinalizeEx` will destroy all sub-interpreters that
- haven't been explicitly destroyed at that point.
-
-
-.. _per-interpreter-gil:
-
-A Per-Interpreter GIL
----------------------
-
-Using :c:func:`Py_NewInterpreterFromConfig` you can create
-a sub-interpreter that is completely isolated from other interpreters,
-including having its own GIL. The most important benefit of this
-isolation is that such an interpreter can execute Python code without
-being blocked by other interpreters or blocking any others. Thus a
-single Python process can truly take advantage of multiple CPU cores
-when running Python code. The isolation also encourages a different
-approach to concurrency than that of just using threads.
-(See :pep:`554` and :pep:`684`.)
-
-Using an isolated interpreter requires vigilance in preserving that
-isolation. That especially means not sharing any objects or mutable
-state without guarantees about thread-safety. Even objects that are
-otherwise immutable (e.g. ``None``, ``(1, 5)``) can't normally be shared
-because of the refcount. One simple but less-efficient approach around
-this is to use a global lock around all use of some state (or object).
-Alternately, effectively immutable objects (like integers or strings)
-can be made safe in spite of their refcounts by making them :term:`immortal`.
-In fact, this has been done for the builtin singletons, small integers,
-and a number of other builtin objects.
-
-If you preserve isolation then you will have access to proper multi-core
-computing without the complications that come with free-threading.
-Failure to preserve isolation will expose you to the full consequences
-of free-threading, including races and hard-to-debug crashes.
-
-Aside from that, one of the main challenges of using multiple isolated
-interpreters is how to communicate between them safely (not break
-isolation) and efficiently. The runtime and stdlib do not provide
-any standard approach to this yet. A future stdlib module would help
-mitigate the effort of preserving isolation and expose effective tools
-for communicating (and sharing) data between interpreters.
-
-.. versionadded:: 3.12
-
-
-Bugs and caveats
-----------------
-
-Because sub-interpreters (and the main interpreter) are part of the same
-process, the insulation between them isn't perfect --- for example, using
-low-level file operations like :func:`os.close` they can
-(accidentally or maliciously) affect each other's open files. Because of the
-way extensions are shared between (sub-)interpreters, some extensions may not
-work properly; this is especially likely when using single-phase initialization
-or (static) global variables.
-It is possible to insert objects created in one sub-interpreter into
-a namespace of another (sub-)interpreter; this should be avoided if possible.
-
-Special care should be taken to avoid sharing user-defined functions,
-methods, instances or classes between sub-interpreters, since import
-operations executed by such objects may affect the wrong (sub-)interpreter's
-dictionary of loaded modules. It is equally important to avoid sharing
-objects from which the above are reachable.
-
-Also note that combining this functionality with ``PyGILState_*`` APIs
-is delicate, because these APIs assume a bijection between Python thread states
-and OS-level threads, an assumption broken by the presence of sub-interpreters.
-It is highly recommended that you don't switch sub-interpreters between a pair
-of matching :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` calls.
-Furthermore, extensions (such as :mod:`ctypes`) using these APIs to allow calling
-of Python code from non-Python created threads will probably be broken when using
-sub-interpreters.
-
-
-Asynchronous Notifications
-==========================
-
-A mechanism is provided to make asynchronous notifications to the main
-interpreter thread. These notifications take the form of a function
-pointer and a void pointer argument.
-
-
-.. c:function:: int Py_AddPendingCall(int (*func)(void *), void *arg)
-
- Schedule a function to be called from the main interpreter thread. On
- success, ``0`` is returned and *func* is queued for being called in the
- main thread. On failure, ``-1`` is returned without setting any exception.
-
- When successfully queued, *func* will be *eventually* called from the
- main interpreter thread with the argument *arg*. It will be called
- asynchronously with respect to normally running Python code, but with
- both these conditions met:
-
- * on a :term:`bytecode` boundary;
- * with the main thread holding an :term:`attached thread state`
- (*func* can therefore use the full C API).
-
- *func* must return ``0`` on success, or ``-1`` on failure with an exception
- set. *func* won't be interrupted to perform another asynchronous
- notification recursively, but it can still be interrupted to switch
- threads if the :term:`thread state <attached thread state>` is detached.
-
- This function doesn't need an :term:`attached thread state`. However, to call this
- function in a subinterpreter, the caller must have an :term:`attached thread state`.
- Otherwise, the function *func* can be scheduled to be called from the wrong interpreter.
-
- .. warning::
- This is a low-level function, only useful for very special cases.
- There is no guarantee that *func* will be called as quick as
- possible. If the main thread is busy executing a system call,
- *func* won't be called before the system call returns. This
- function is generally **not** suitable for calling Python code from
- arbitrary C threads. Instead, use the :ref:`PyGILState API<gilstate>`.
-
- .. versionadded:: 3.1
-
- .. versionchanged:: 3.9
- If this function is called in a subinterpreter, the function *func* is
- now scheduled to be called from the subinterpreter, rather than being
- called from the main interpreter. Each subinterpreter now has its own
- list of scheduled calls.
-
- .. versionchanged:: 3.12
- This function now always schedules *func* to be run in the main
- interpreter.
-
-
-.. c:function:: int Py_MakePendingCalls(void)
-
- Execute all pending calls. This is usually executed automatically by the
- interpreter.
-
- This function returns ``0`` on success, and returns ``-1`` with an exception
- set on failure.
-
- If this is not called in the main thread of the main
- interpreter, this function does nothing and returns ``0``.
- The caller must hold an :term:`attached thread state`.
-
- .. versionadded:: 3.1
-
- .. versionchanged:: 3.12
- This function only runs pending calls in the main interpreter.
-
-
-.. _profiling:
-
-Profiling and Tracing
-=====================
-
-.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
-
-
-The Python interpreter provides some low-level support for attaching profiling
-and execution tracing facilities. These are used for profiling, debugging, and
-coverage analysis tools.
-
-This C interface allows the profiling or tracing code to avoid the overhead of
-calling through Python-level callable objects, making a direct C function call
-instead. The essential attributes of the facility have not changed; the
-interface allows trace functions to be installed per-thread, and the basic
-events reported to the trace function are the same as had been reported to the
-Python-level trace functions in previous versions.
-
-
-.. c:type:: int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)
-
- The type of the trace function registered using :c:func:`PyEval_SetProfile` and
- :c:func:`PyEval_SetTrace`. The first parameter is the object passed to the
- registration function as *obj*, *frame* is the frame object to which the event
- pertains, *what* is one of the constants :c:data:`PyTrace_CALL`,
- :c:data:`PyTrace_EXCEPTION`, :c:data:`PyTrace_LINE`, :c:data:`PyTrace_RETURN`,
- :c:data:`PyTrace_C_CALL`, :c:data:`PyTrace_C_EXCEPTION`, :c:data:`PyTrace_C_RETURN`,
- or :c:data:`PyTrace_OPCODE`, and *arg* depends on the value of *what*:
-
- +-------------------------------+----------------------------------------+
- | Value of *what* | Meaning of *arg* |
- +===============================+========================================+
- | :c:data:`PyTrace_CALL` | Always :c:data:`Py_None`. |
- +-------------------------------+----------------------------------------+
- | :c:data:`PyTrace_EXCEPTION` | Exception information as returned by |
- | | :func:`sys.exc_info`. |
- +-------------------------------+----------------------------------------+
- | :c:data:`PyTrace_LINE` | Always :c:data:`Py_None`. |
- +-------------------------------+----------------------------------------+
- | :c:data:`PyTrace_RETURN` | Value being returned to the caller, |
- | | or ``NULL`` if caused by an exception. |
- +-------------------------------+----------------------------------------+
- | :c:data:`PyTrace_C_CALL` | Function object being called. |
- +-------------------------------+----------------------------------------+
- | :c:data:`PyTrace_C_EXCEPTION` | Function object being called. |
- +-------------------------------+----------------------------------------+
- | :c:data:`PyTrace_C_RETURN` | Function object being called. |
- +-------------------------------+----------------------------------------+
- | :c:data:`PyTrace_OPCODE` | Always :c:data:`Py_None`. |
- +-------------------------------+----------------------------------------+
-
-.. c:var:: int PyTrace_CALL
-
- The value of the *what* parameter to a :c:type:`Py_tracefunc` function when a new
- call to a function or method is being reported, or a new entry into a generator.
- Note that the creation of the iterator for a generator function is not reported
- as there is no control transfer to the Python bytecode in the corresponding
- frame.
-
-
-.. c:var:: int PyTrace_EXCEPTION
-
- The value of the *what* parameter to a :c:type:`Py_tracefunc` function when an
- exception has been raised. The callback function is called with this value for
- *what* when after any bytecode is processed after which the exception becomes
- set within the frame being executed. The effect of this is that as exception
- propagation causes the Python stack to unwind, the callback is called upon
- return to each frame as the exception propagates. Only trace functions receives
- these events; they are not needed by the profiler.
-
-
-.. c:var:: int PyTrace_LINE
-
- The value passed as the *what* parameter to a :c:type:`Py_tracefunc` function
- (but not a profiling function) when a line-number event is being reported.
- It may be disabled for a frame by setting :attr:`~frame.f_trace_lines` to
- *0* on that frame.
-
-
-.. c:var:: int PyTrace_RETURN
-
- The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a
- call is about to return.
-
-
-.. c:var:: int PyTrace_C_CALL
-
- The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C
- function is about to be called.
-
-
-.. c:var:: int PyTrace_C_EXCEPTION
-
- The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C
- function has raised an exception.
-
-
-.. c:var:: int PyTrace_C_RETURN
-
- The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C
- function has returned.
-
-
-.. c:var:: int PyTrace_OPCODE
-
- The value for the *what* parameter to :c:type:`Py_tracefunc` functions (but not
- profiling functions) when a new opcode is about to be executed. This event is
- not emitted by default: it must be explicitly requested by setting
- :attr:`~frame.f_trace_opcodes` to *1* on the frame.
-
-
-.. c:function:: void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)
-
- Set the profiler function to *func*. The *obj* parameter is passed to the
- function as its first parameter, and may be any Python object, or ``NULL``. If
- the profile function needs to maintain state, using a different value for *obj*
- for each thread provides a convenient and thread-safe place to store it. The
- profile function is called for all monitored events except :c:data:`PyTrace_LINE`
- :c:data:`PyTrace_OPCODE` and :c:data:`PyTrace_EXCEPTION`.
-
- See also the :func:`sys.setprofile` function.
-
- The caller must have an :term:`attached thread state`.
-
-.. c:function:: void PyEval_SetProfileAllThreads(Py_tracefunc func, PyObject *obj)
-
- Like :c:func:`PyEval_SetProfile` but sets the profile function in all running threads
- belonging to the current interpreter instead of the setting it only on the current thread.
-
- The caller must have an :term:`attached thread state`.
-
- As :c:func:`PyEval_SetProfile`, this function ignores any exceptions raised while
- setting the profile functions in all threads.
-
-.. versionadded:: 3.12
-
-
-.. c:function:: void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)
-
- Set the tracing function to *func*. This is similar to
- :c:func:`PyEval_SetProfile`, except the tracing function does receive line-number
- events and per-opcode events, but does not receive any event related to C function
- objects being called. Any trace function registered using :c:func:`PyEval_SetTrace`
- will not receive :c:data:`PyTrace_C_CALL`, :c:data:`PyTrace_C_EXCEPTION` or
- :c:data:`PyTrace_C_RETURN` as a value for the *what* parameter.
-
- See also the :func:`sys.settrace` function.
-
- The caller must have an :term:`attached thread state`.
-
-.. c:function:: void PyEval_SetTraceAllThreads(Py_tracefunc func, PyObject *obj)
-
- Like :c:func:`PyEval_SetTrace` but sets the tracing function in all running threads
- belonging to the current interpreter instead of the setting it only on the current thread.
-
- The caller must have an :term:`attached thread state`.
-
- As :c:func:`PyEval_SetTrace`, this function ignores any exceptions raised while
- setting the trace functions in all threads.
-
-.. versionadded:: 3.12
-
-Reference tracing
-=================
-
-.. versionadded:: 3.13
-
-.. c:type:: int (*PyRefTracer)(PyObject *, int event, void* data)
-
- The type of the trace function registered using :c:func:`PyRefTracer_SetTracer`.
- The first parameter is a Python object that has been just created (when **event**
- is set to :c:data:`PyRefTracer_CREATE`) or about to be destroyed (when **event**
- is set to :c:data:`PyRefTracer_DESTROY`). The **data** argument is the opaque pointer
- that was provided when :c:func:`PyRefTracer_SetTracer` was called.
-
-.. versionadded:: 3.13
-
-.. c:var:: int PyRefTracer_CREATE
-
- The value for the *event* parameter to :c:type:`PyRefTracer` functions when a Python
- object has been created.
-
-.. c:var:: int PyRefTracer_DESTROY
-
- The value for the *event* parameter to :c:type:`PyRefTracer` functions when a Python
- object has been destroyed.
-
-.. c:function:: int PyRefTracer_SetTracer(PyRefTracer tracer, void *data)
-
- Register a reference tracer function. The function will be called when a new
- Python has been created or when an object is going to be destroyed. If
- **data** is provided it must be an opaque pointer that will be provided when
- the tracer function is called. Return ``0`` on success. Set an exception and
- return ``-1`` on error.
-
- Not that tracer functions **must not** create Python objects inside or
- otherwise the call will be re-entrant. The tracer also **must not** clear
- any existing exception or set an exception. A :term:`thread state` will be active
- every time the tracer function is called.
-
- There must be an :term:`attached thread state` when calling this function.
-
-.. versionadded:: 3.13
-
-.. c:function:: PyRefTracer PyRefTracer_GetTracer(void** data)
-
- Get the registered reference tracer function and the value of the opaque data
- pointer that was registered when :c:func:`PyRefTracer_SetTracer` was called.
- If no tracer was registered this function will return NULL and will set the
- **data** pointer to NULL.
-
- There must be an :term:`attached thread state` when calling this function.
-
-.. versionadded:: 3.13
-
-.. _advanced-debugging:
-
-Advanced Debugger Support
-=========================
-
-.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
-
-
-These functions are only intended to be used by advanced debugging tools.
-
-
-.. c:function:: PyInterpreterState* PyInterpreterState_Head()
-
- Return the interpreter state object at the head of the list of all such objects.
-
-
-.. c:function:: PyInterpreterState* PyInterpreterState_Main()
-
- Return the main interpreter state object.
-
-
-.. c:function:: PyInterpreterState* PyInterpreterState_Next(PyInterpreterState *interp)
-
- Return the next interpreter state object after *interp* from the list of all
- such objects.
-
-
-.. c:function:: PyThreadState * PyInterpreterState_ThreadHead(PyInterpreterState *interp)
-
- Return the pointer to the first :c:type:`PyThreadState` object in the list of
- threads associated with the interpreter *interp*.
-
-
-.. c:function:: PyThreadState* PyThreadState_Next(PyThreadState *tstate)
-
- Return the next thread state object after *tstate* from the list of all such
- objects belonging to the same :c:type:`PyInterpreterState` object.
-
-
-.. _thread-local-storage:
-
-Thread Local Storage Support
-============================
-
-.. sectionauthor:: Masayuki Yamamoto <ma3yuki.8mamo10@gmail.com>
-
-The Python interpreter provides low-level support for thread-local storage
-(TLS) which wraps the underlying native TLS implementation to support the
-Python-level thread local storage API (:class:`threading.local`). The
-CPython C level APIs are similar to those offered by pthreads and Windows:
-use a thread key and functions to associate a :c:expr:`void*` value per
-thread.
-
-A :term:`thread state` does *not* need to be :term:`attached <attached thread state>`
-when calling these functions; they suppl their own locking.
-
-Note that :file:`Python.h` does not include the declaration of the TLS APIs,
-you need to include :file:`pythread.h` to use thread-local storage.
-
-.. note::
- None of these API functions handle memory management on behalf of the
- :c:expr:`void*` values. You need to allocate and deallocate them yourself.
- If the :c:expr:`void*` values happen to be :c:expr:`PyObject*`, these
- functions don't do refcount operations on them either.
-
-.. _thread-specific-storage-api:
-
-Thread Specific Storage (TSS) API
----------------------------------
-
-TSS API is introduced to supersede the use of the existing TLS API within the
-CPython interpreter. This API uses a new type :c:type:`Py_tss_t` instead of
-:c:expr:`int` to represent thread keys.
-
-.. versionadded:: 3.7
-
-.. seealso:: "A New C-API for Thread-Local Storage in CPython" (:pep:`539`)
-
-
-.. c:type:: Py_tss_t
-
- This data structure represents the state of a thread key, the definition of
- which may depend on the underlying TLS implementation, and it has an
- internal field representing the key's initialization state. There are no
- public members in this structure.
-
- When :ref:`Py_LIMITED_API <stable>` is not defined, static allocation of
- this type by :c:macro:`Py_tss_NEEDS_INIT` is allowed.
-
-
-.. c:macro:: Py_tss_NEEDS_INIT
-
- This macro expands to the initializer for :c:type:`Py_tss_t` variables.
- Note that this macro won't be defined with :ref:`Py_LIMITED_API <stable>`.
-
-
-Dynamic Allocation
-~~~~~~~~~~~~~~~~~~
-
-Dynamic allocation of the :c:type:`Py_tss_t`, required in extension modules
-built with :ref:`Py_LIMITED_API <stable>`, where static allocation of this type
-is not possible due to its implementation being opaque at build time.
-
-
-.. c:function:: Py_tss_t* PyThread_tss_alloc()
-
- Return a value which is the same state as a value initialized with
- :c:macro:`Py_tss_NEEDS_INIT`, or ``NULL`` in the case of dynamic allocation
- failure.
-
-
-.. c:function:: void PyThread_tss_free(Py_tss_t *key)
-
- Free the given *key* allocated by :c:func:`PyThread_tss_alloc`, after
- first calling :c:func:`PyThread_tss_delete` to ensure any associated
- thread locals have been unassigned. This is a no-op if the *key*
- argument is ``NULL``.
-
- .. note::
- A freed key becomes a dangling pointer. You should reset the key to
- ``NULL``.
-
-
-Methods
-~~~~~~~
-
-The parameter *key* of these functions must not be ``NULL``. Moreover, the
-behaviors of :c:func:`PyThread_tss_set` and :c:func:`PyThread_tss_get` are
-undefined if the given :c:type:`Py_tss_t` has not been initialized by
-:c:func:`PyThread_tss_create`.
-
-
-.. c:function:: int PyThread_tss_is_created(Py_tss_t *key)
-
- Return a non-zero value if the given :c:type:`Py_tss_t` has been initialized
- by :c:func:`PyThread_tss_create`.
-
-
-.. c:function:: int PyThread_tss_create(Py_tss_t *key)
-
- Return a zero value on successful initialization of a TSS key. The behavior
- is undefined if the value pointed to by the *key* argument is not
- initialized by :c:macro:`Py_tss_NEEDS_INIT`. This function can be called
- repeatedly on the same key -- calling it on an already initialized key is a
- no-op and immediately returns success.
-
-
-.. c:function:: void PyThread_tss_delete(Py_tss_t *key)
-
- Destroy a TSS key to forget the values associated with the key across all
- threads, and change the key's initialization state to uninitialized. A
- destroyed key is able to be initialized again by
- :c:func:`PyThread_tss_create`. This function can be called repeatedly on
- the same key -- calling it on an already destroyed key is a no-op.
-
-
-.. c:function:: int PyThread_tss_set(Py_tss_t *key, void *value)
-
- Return a zero value to indicate successfully associating a :c:expr:`void*`
- value with a TSS key in the current thread. Each thread has a distinct
- mapping of the key to a :c:expr:`void*` value.
-
-
-.. c:function:: void* PyThread_tss_get(Py_tss_t *key)
-
- Return the :c:expr:`void*` value associated with a TSS key in the current
- thread. This returns ``NULL`` if no value is associated with the key in the
- current thread.
-
-
-.. _thread-local-storage-api:
-
-Thread Local Storage (TLS) API
-------------------------------
-
-.. deprecated:: 3.7
- This API is superseded by
- :ref:`Thread Specific Storage (TSS) API <thread-specific-storage-api>`.
-
-.. note::
- This version of the API does not support platforms where the native TLS key
- is defined in a way that cannot be safely cast to ``int``. On such platforms,
- :c:func:`PyThread_create_key` will return immediately with a failure status,
- and the other TLS functions will all be no-ops on such platforms.
-
-Due to the compatibility problem noted above, this version of the API should not
-be used in new code.
-
-.. c:function:: int PyThread_create_key()
-.. c:function:: void PyThread_delete_key(int key)
-.. c:function:: int PyThread_set_key_value(int key, void *value)
-.. c:function:: void* PyThread_get_key_value(int key)
-.. c:function:: void PyThread_delete_key_value(int key)
-.. c:function:: void PyThread_ReInitTLS()
-
-Synchronization Primitives
-==========================
-
-The C-API provides a basic mutual exclusion lock.
-
-.. c:type:: PyMutex
-
- A mutual exclusion lock. The :c:type:`!PyMutex` should be initialized to
- zero to represent the unlocked state. For example::
-
- PyMutex mutex = {0};
-
- Instances of :c:type:`!PyMutex` should not be copied or moved. Both the
- contents and address of a :c:type:`!PyMutex` are meaningful, and it must
- remain at a fixed, writable location in memory.
-
- .. note::
-
- A :c:type:`!PyMutex` currently occupies one byte, but the size should be
- considered unstable. The size may change in future Python releases
- without a deprecation period.
-
- .. versionadded:: 3.13
-
-.. c:function:: void PyMutex_Lock(PyMutex *m)
-
- Lock mutex *m*. If another thread has already locked it, the calling
- thread will block until the mutex is unlocked. While blocked, the thread
- will temporarily detach the :term:`thread state <attached thread state>` if one exists.
-
- .. versionadded:: 3.13
-
-.. c:function:: void PyMutex_Unlock(PyMutex *m)
-
- Unlock mutex *m*. The mutex must be locked --- otherwise, the function will
- issue a fatal error.
-
- .. versionadded:: 3.13
-
-.. c:function:: int PyMutex_IsLocked(PyMutex *m)
-
- Returns non-zero if the mutex *m* is currently locked, zero otherwise.
-
- .. note::
-
- This function is intended for use in assertions and debugging only and
- should not be used to make concurrency control decisions, as the lock
- state may change immediately after the check.
-
- .. versionadded:: 3.14
-
-.. _python-critical-section-api:
-
-Python Critical Section API
----------------------------
-
-The critical section API provides a deadlock avoidance layer on top of
-per-object locks for :term:`free-threaded <free threading>` CPython. They are
-intended to replace reliance on the :term:`global interpreter lock`, and are
-no-ops in versions of Python with the global interpreter lock.
-
-Critical sections are intended to be used for custom types implemented
-in C-API extensions. They should generally not be used with built-in types like
-:class:`list` and :class:`dict` because their public C-APIs
-already use critical sections internally, with the notable
-exception of :c:func:`PyDict_Next`, which requires critical section
-to be acquired externally.
-
-Critical sections avoid deadlocks by implicitly suspending active critical
-sections, hence, they do not provide exclusive access such as provided by
-traditional locks like :c:type:`PyMutex`. When a critical section is started,
-the per-object lock for the object is acquired. If the code executed inside the
-critical section calls C-API functions then it can suspend the critical section thereby
-releasing the per-object lock, so other threads can acquire the per-object lock
-for the same object.
-
-Variants that accept :c:type:`PyMutex` pointers rather than Python objects are also
-available. Use these variants to start a critical section in a situation where
-there is no :c:type:`PyObject` -- for example, when working with a C type that
-does not extend or wrap :c:type:`PyObject` but still needs to call into the C
-API in a manner that might lead to deadlocks.
-
-The functions and structs used by the macros are exposed for cases
-where C macros are not available. They should only be used as in the
-given macro expansions. Note that the sizes and contents of the structures may
-change in future Python versions.
-
-.. note::
-
- Operations that need to lock two objects at once must use
- :c:macro:`Py_BEGIN_CRITICAL_SECTION2`. You *cannot* use nested critical
- sections to lock more than one object at once, because the inner critical
- section may suspend the outer critical sections. This API does not provide
- a way to lock more than two objects at once.
-
-Example usage::
-
- static PyObject *
- set_field(MyObject *self, PyObject *value)
- {
- Py_BEGIN_CRITICAL_SECTION(self);
- Py_SETREF(self->field, Py_XNewRef(value));
- Py_END_CRITICAL_SECTION();
- Py_RETURN_NONE;
- }
-
-In the above example, :c:macro:`Py_SETREF` calls :c:macro:`Py_DECREF`, which
-can call arbitrary code through an object's deallocation function. The critical
-section API avoids potential deadlocks due to reentrancy and lock ordering
-by allowing the runtime to temporarily suspend the critical section if the
-code triggered by the finalizer blocks and calls :c:func:`PyEval_SaveThread`.
-
-.. c:macro:: Py_BEGIN_CRITICAL_SECTION(op)
-
- Acquires the per-object lock for the object *op* and begins a
- critical section.
-
- In the free-threaded build, this macro expands to::
-
- {
- PyCriticalSection _py_cs;
- PyCriticalSection_Begin(&_py_cs, (PyObject*)(op))
-
- In the default build, this macro expands to ``{``.
-
- .. versionadded:: 3.13
-
-.. c:macro:: Py_BEGIN_CRITICAL_SECTION_MUTEX(m)
-
- Locks the mutex *m* and begins a critical section.
-
- In the free-threaded build, this macro expands to::
-
- {
- PyCriticalSection _py_cs;
- PyCriticalSection_BeginMutex(&_py_cs, m)
-
- Note that unlike :c:macro:`Py_BEGIN_CRITICAL_SECTION`, there is no cast for
- the argument of the macro - it must be a :c:type:`PyMutex` pointer.
-
- On the default build, this macro expands to ``{``.
-
- .. versionadded:: 3.14
-
-.. c:macro:: Py_END_CRITICAL_SECTION()
-
- Ends the critical section and releases the per-object lock.
-
- In the free-threaded build, this macro expands to::
-
- PyCriticalSection_End(&_py_cs);
- }
-
- In the default build, this macro expands to ``}``.
-
- .. versionadded:: 3.13
-
-.. c:macro:: Py_BEGIN_CRITICAL_SECTION2(a, b)
-
- Acquires the per-objects locks for the objects *a* and *b* and begins a
- critical section. The locks are acquired in a consistent order (lowest
- address first) to avoid lock ordering deadlocks.
-
- In the free-threaded build, this macro expands to::
-
- {
- PyCriticalSection2 _py_cs2;
- PyCriticalSection2_Begin(&_py_cs2, (PyObject*)(a), (PyObject*)(b))
-
- In the default build, this macro expands to ``{``.
-
- .. versionadded:: 3.13
-
-.. c:macro:: Py_BEGIN_CRITICAL_SECTION2_MUTEX(m1, m2)
-
- Locks the mutexes *m1* and *m2* and begins a critical section.
-
- In the free-threaded build, this macro expands to::
-
- {
- PyCriticalSection2 _py_cs2;
- PyCriticalSection2_BeginMutex(&_py_cs2, m1, m2)
-
- Note that unlike :c:macro:`Py_BEGIN_CRITICAL_SECTION2`, there is no cast for
- the arguments of the macro - they must be :c:type:`PyMutex` pointers.
-
- On the default build, this macro expands to ``{``.
-
- .. versionadded:: 3.14
-
-.. c:macro:: Py_END_CRITICAL_SECTION2()
-
- Ends the critical section and releases the per-object locks.
-
- In the free-threaded build, this macro expands to::
-
- PyCriticalSection2_End(&_py_cs2);
- }
-
- In the default build, this macro expands to ``}``.
-
- .. versionadded:: 3.13
-
-
-Legacy Locking APIs
--------------------
-
-These APIs are obsolete since Python 3.13 with the introduction of
-:c:type:`PyMutex`.
-
-.. versionchanged:: 3.15
- These APIs are now a simple wrapper around ``PyMutex``.
-
-
-.. c:type:: PyThread_type_lock
-
- A pointer to a mutual exclusion lock.
-
-
-.. c:type:: PyLockStatus
-
- The result of acquiring a lock with a timeout.
-
- .. c:namespace:: NULL
-
- .. c:enumerator:: PY_LOCK_FAILURE
-
- Failed to acquire the lock.
-
- .. c:enumerator:: PY_LOCK_ACQUIRED
-
- The lock was successfully acquired.
-
- .. c:enumerator:: PY_LOCK_INTR
-
- The lock was interrupted by a signal.
-
-
-.. c:function:: PyThread_type_lock PyThread_allocate_lock(void)
-
- Allocate a new lock.
-
- On success, this function returns a lock; on failure, this
- function returns ``0`` without an exception set.
-
- The caller does not need to hold an :term:`attached thread state`.
-
- .. versionchanged:: 3.15
- This function now always uses :c:type:`PyMutex`. In prior versions, this
- would use a lock provided by the operating system.
-
-
-.. c:function:: void PyThread_free_lock(PyThread_type_lock lock)
-
- Destroy *lock*. The lock should not be held by any thread when calling
- this.
-
- The caller does not need to hold an :term:`attached thread state`.
-
-
-.. c:function:: PyLockStatus PyThread_acquire_lock_timed(PyThread_type_lock lock, long long microseconds, int intr_flag)
-
- Acquire *lock* with a timeout.
-
- This will wait for *microseconds* microseconds to acquire the lock. If the
- timeout expires, this function returns :c:enumerator:`PY_LOCK_FAILURE`.
- If *microseconds* is ``-1``, this will wait indefinitely until the lock has
- been released.
-
- If *intr_flag* is ``1``, acquiring the lock may be interrupted by a signal,
- in which case this function returns :c:enumerator:`PY_LOCK_INTR`. Upon
- interruption, it's generally expected that the caller makes a call to
- :c:func:`Py_MakePendingCalls` to propagate an exception to Python code.
-
- If the lock is successfully acquired, this function returns
- :c:enumerator:`PY_LOCK_ACQUIRED`.
-
- The caller does not need to hold an :term:`attached thread state`.
-
-
-.. c:function:: int PyThread_acquire_lock(PyThread_type_lock lock, int waitflag)
-
- Acquire *lock*.
-
- If *waitflag* is ``1`` and another thread currently holds the lock, this
- function will wait until the lock can be acquired and will always return
- ``1``.
-
- If *waitflag* is ``0`` and another thread holds the lock, this function will
- not wait and instead return ``0``. If the lock is not held by any other
- thread, then this function will acquire it and return ``1``.
-
- Unlike :c:func:`PyThread_acquire_lock_timed`, acquiring the lock cannot be
- interrupted by a signal.
-
- The caller does not need to hold an :term:`attached thread state`.
-
-
-.. c:function:: int PyThread_release_lock(PyThread_type_lock lock)
-
- Release *lock*. If *lock* is not held, then this function issues a
- fatal error.
-
- The caller does not need to hold an :term:`attached thread state`.
-
-
-Operating System Thread APIs
-============================
-
-.. c:macro:: PYTHREAD_INVALID_THREAD_ID
-
- Sentinel value for an invalid thread ID.
-
- This is currently equivalent to ``(unsigned long)-1``.
-
-
-.. c:function:: unsigned long PyThread_start_new_thread(void (*func)(void *), void *arg)
-
- Start function *func* in a new thread with argument *arg*.
- The resulting thread is not intended to be joined.
-
- *func* must not be ``NULL``, but *arg* may be ``NULL``.
-
- On success, this function returns the identifier of the new thread; on failure,
- this returns :c:macro:`PYTHREAD_INVALID_THREAD_ID`.
-
- The caller does not need to hold an :term:`attached thread state`.
-
-
-.. c:function:: unsigned long PyThread_get_thread_ident(void)
-
- Return the identifier of the current thread, which will never be zero.
-
- This function cannot fail, and the caller does not need to hold an
- :term:`attached thread state`.
-
- .. seealso::
- :py:func:`threading.get_ident`
-
-
-.. c:function:: PyObject *PyThread_GetInfo(void)
-
- Get general information about the current thread in the form of a
- :ref:`struct sequence <struct-sequence-objects>` object. This information is
- accessible as :py:attr:`sys.thread_info` in Python.
-
- On success, this returns a new :term:`strong reference` to the thread
- information; on failure, this returns ``NULL`` with an exception set.
-
- The caller must hold an :term:`attached thread state`.
-
-
-.. c:macro:: PY_HAVE_THREAD_NATIVE_ID
-
- This macro is defined when the system supports native thread IDs.
-
-
-.. c:function:: unsigned long PyThread_get_thread_native_id(void)
-
- Get the native identifier of the current thread as it was assigned by the operating
- system's kernel, which will never be less than zero.
-
- This function is only available when :c:macro:`PY_HAVE_THREAD_NATIVE_ID` is
- defined.
-
- This function cannot fail, and the caller does not need to hold an
- :term:`attached thread state`.
-
- .. seealso::
- :py:func:`threading.get_native_id`
-
-
-.. c:function:: void PyThread_exit_thread(void)
-
- Terminate the current thread. This function is generally considered unsafe
- and should be avoided. It is kept solely for backwards compatibility.
-
- This function is only safe to call if all functions in the full call
- stack are written to safely allow it.
-
- .. warning::
-
- If the current system uses POSIX threads (also known as "pthreads"),
- this calls :manpage:`pthread_exit(3)`, which attempts to unwind the stack
- and call C++ destructors on some libc implementations. However, if a
- ``noexcept`` function is reached, it may terminate the process.
- Other systems, such as macOS, do unwinding.
-
- On Windows, this function calls ``_endthreadex()``, which kills the thread
- without calling C++ destructors.
-
- In any case, there is a risk of corruption on the thread's stack.
-
- .. deprecated:: 3.14
-
-
-.. c:function:: void PyThread_init_thread(void)
-
- Initialize ``PyThread*`` APIs. Python executes this function automatically,
- so there's little need to call it from an extension module.
-
-
-.. c:function:: int PyThread_set_stacksize(size_t size)
-
- Set the stack size of the current thread to *size* bytes.
-
- This function returns ``0`` on success, ``-1`` if *size* is invalid, or
- ``-2`` if the system does not support changing the stack size. This function
- does not set exceptions.
-
- The caller does not need to hold an :term:`attached thread state`.
-
-
-.. c:function:: size_t PyThread_get_stacksize(void)
-
- Return the stack size of the current thread in bytes, or ``0`` if the system's
- default stack size is in use.
-
- The caller does not need to hold an :term:`attached thread state`.
+- :ref:`initialization`
+- :ref:`threads`
+- :ref:`synchronization`
+- :ref:`thread-local-storage`
+- :ref:`sub-interpreter-support`
+- :ref:`profiling`
diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst
index 424d7de7089..9b1b88b2f8d 100644
--- a/Doc/c-api/init_config.rst
+++ b/Doc/c-api/init_config.rst
@@ -544,9 +544,9 @@ Configuration Options
Visibility:
-* Public: Can by get by :c:func:`PyConfig_Get` and set by
+* Public: Can be retrieved by :c:func:`PyConfig_Get` and set by
:c:func:`PyConfig_Set`.
-* Read-only: Can by get by :c:func:`PyConfig_Get`, but cannot be set by
+* Read-only: Can be retrieved by :c:func:`PyConfig_Get`, but cannot be set by
:c:func:`PyConfig_Set`.
@@ -1155,7 +1155,7 @@ PyConfig
Most ``PyConfig`` methods :ref:`preinitialize Python <c-preinit>` if needed.
In that case, the Python preinitialization configuration
- (:c:type:`PyPreConfig`) in based on the :c:type:`PyConfig`. If configuration
+ (:c:type:`PyPreConfig`) is based on the :c:type:`PyConfig`. If configuration
fields which are in common with :c:type:`PyPreConfig` are tuned, they must
be set before calling a :c:type:`PyConfig` method:
diff --git a/Doc/c-api/interp-lifecycle.rst b/Doc/c-api/interp-lifecycle.rst
new file mode 100644
index 00000000000..f8c8fdaa05b
--- /dev/null
+++ b/Doc/c-api/interp-lifecycle.rst
@@ -0,0 +1,956 @@
+.. highlight:: c
+
+.. _initialization:
+
+Interpreter initialization and finalization
+===========================================
+
+See :ref:`Python Initialization Configuration <init-config>` for details
+on how to configure the interpreter prior to initialization.
+
+.. _pre-init-safe:
+
+Before Python initialization
+----------------------------
+
+In an application embedding Python, the :c:func:`Py_Initialize` function must
+be called before using any other Python/C API functions; with the exception of
+a few functions and the :ref:`global configuration variables
+<global-conf-vars>`.
+
+The following functions can be safely called before Python is initialized:
+
+* Functions that initialize the interpreter:
+
+ * :c:func:`Py_Initialize`
+ * :c:func:`Py_InitializeEx`
+ * :c:func:`Py_InitializeFromConfig`
+ * :c:func:`Py_BytesMain`
+ * :c:func:`Py_Main`
+ * the runtime pre-initialization functions covered in :ref:`init-config`
+
+* Configuration functions:
+
+ * :c:func:`PyImport_AppendInittab`
+ * :c:func:`PyImport_ExtendInittab`
+ * :c:func:`!PyInitFrozenExtensions`
+ * :c:func:`PyMem_SetAllocator`
+ * :c:func:`PyMem_SetupDebugHooks`
+ * :c:func:`PyObject_SetArenaAllocator`
+ * :c:func:`Py_SetProgramName`
+ * :c:func:`Py_SetPythonHome`
+ * the configuration functions covered in :ref:`init-config`
+
+* Informative functions:
+
+ * :c:func:`Py_IsInitialized`
+ * :c:func:`PyMem_GetAllocator`
+ * :c:func:`PyObject_GetArenaAllocator`
+ * :c:func:`Py_GetBuildInfo`
+ * :c:func:`Py_GetCompiler`
+ * :c:func:`Py_GetCopyright`
+ * :c:func:`Py_GetPlatform`
+ * :c:func:`Py_GetVersion`
+ * :c:func:`Py_IsInitialized`
+
+* Utilities:
+
+ * :c:func:`Py_DecodeLocale`
+ * the status reporting and utility functions covered in :ref:`init-config`
+
+* Memory allocators:
+
+ * :c:func:`PyMem_RawMalloc`
+ * :c:func:`PyMem_RawRealloc`
+ * :c:func:`PyMem_RawCalloc`
+ * :c:func:`PyMem_RawFree`
+
+* Synchronization:
+
+ * :c:func:`PyMutex_Lock`
+ * :c:func:`PyMutex_Unlock`
+
+.. note::
+
+ Despite their apparent similarity to some of the functions listed above,
+ the following functions **should not be called** before the interpreter has
+ been initialized: :c:func:`Py_EncodeLocale`, :c:func:`PyEval_InitThreads`, and
+ :c:func:`Py_RunMain`.
+
+
+.. _global-conf-vars:
+
+Global configuration variables
+------------------------------
+
+Python has variables for the global configuration to control different features
+and options. By default, these flags are controlled by :ref:`command line
+options <using-on-interface-options>`.
+
+When a flag is set by an option, the value of the flag is the number of times
+that the option was set. For example, ``-b`` sets :c:data:`Py_BytesWarningFlag`
+to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
+
+
+.. c:var:: int Py_BytesWarningFlag
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.bytes_warning` should be used instead, see :ref:`Python
+ Initialization Configuration <init-config>`.
+
+ Issue a warning when comparing :class:`bytes` or :class:`bytearray` with
+ :class:`str` or :class:`bytes` with :class:`int`. Issue an error if greater
+ or equal to ``2``.
+
+ Set by the :option:`-b` option.
+
+ .. deprecated-removed:: 3.12 3.15
+
+
+.. c:var:: int Py_DebugFlag
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.parser_debug` should be used instead, see :ref:`Python
+ Initialization Configuration <init-config>`.
+
+ Turn on parser debugging output (for expert only, depending on compilation
+ options).
+
+ Set by the :option:`-d` option and the :envvar:`PYTHONDEBUG` environment
+ variable.
+
+ .. deprecated-removed:: 3.12 3.15
+
+
+.. c:var:: int Py_DontWriteBytecodeFlag
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.write_bytecode` should be used instead, see :ref:`Python
+ Initialization Configuration <init-config>`.
+
+ If set to non-zero, Python won't try to write ``.pyc`` files on the
+ import of source modules.
+
+ Set by the :option:`-B` option and the :envvar:`PYTHONDONTWRITEBYTECODE`
+ environment variable.
+
+ .. deprecated-removed:: 3.12 3.15
+
+
+.. c:var:: int Py_FrozenFlag
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.pathconfig_warnings` should be used instead, see
+ :ref:`Python Initialization Configuration <init-config>`.
+
+ Private flag used by ``_freeze_module`` and ``frozenmain`` programs.
+
+ .. deprecated-removed:: 3.12 3.15
+
+
+.. c:var:: int Py_HashRandomizationFlag
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.hash_seed` and :c:member:`PyConfig.use_hash_seed` should
+ be used instead, see :ref:`Python Initialization Configuration
+ <init-config>`.
+
+ Set to ``1`` if the :envvar:`PYTHONHASHSEED` environment variable is set to
+ a non-empty string.
+
+ If the flag is non-zero, read the :envvar:`PYTHONHASHSEED` environment
+ variable to initialize the secret hash seed.
+
+ .. deprecated-removed:: 3.12 3.15
+
+
+.. c:var:: int Py_IgnoreEnvironmentFlag
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.use_environment` should be used instead, see
+ :ref:`Python Initialization Configuration <init-config>`.
+
+ Ignore all :envvar:`!PYTHON*` environment variables, e.g.
+ :envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set.
+
+ Set by the :option:`-E` and :option:`-I` options.
+
+ .. deprecated-removed:: 3.12 3.15
+
+
+.. c:var:: int Py_InspectFlag
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.inspect` should be used instead, see
+ :ref:`Python Initialization Configuration <init-config>`.
+
+ When a script is passed as first argument or the :option:`-c` option is used,
+ enter interactive mode after executing the script or the command, even when
+ :data:`sys.stdin` does not appear to be a terminal.
+
+ Set by the :option:`-i` option and the :envvar:`PYTHONINSPECT` environment
+ variable.
+
+ .. deprecated-removed:: 3.12 3.15
+
+
+.. c:var:: int Py_InteractiveFlag
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.interactive` should be used instead, see
+ :ref:`Python Initialization Configuration <init-config>`.
+
+ Set by the :option:`-i` option.
+
+ .. deprecated-removed:: 3.12 3.15
+
+
+.. c:var:: int Py_IsolatedFlag
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.isolated` should be used instead, see
+ :ref:`Python Initialization Configuration <init-config>`.
+
+ Run Python in isolated mode. In isolated mode :data:`sys.path` contains
+ neither the script's directory nor the user's site-packages directory.
+
+ Set by the :option:`-I` option.
+
+ .. versionadded:: 3.4
+
+ .. deprecated-removed:: 3.12 3.15
+
+
+.. c:var:: int Py_LegacyWindowsFSEncodingFlag
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyPreConfig.legacy_windows_fs_encoding` should be used instead, see
+ :ref:`Python Initialization Configuration <init-config>`.
+
+ If the flag is non-zero, use the ``mbcs`` encoding with ``replace`` error
+ handler, instead of the UTF-8 encoding with ``surrogatepass`` error handler,
+ for the :term:`filesystem encoding and error handler`.
+
+ Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment
+ variable is set to a non-empty string.
+
+ See :pep:`529` for more details.
+
+ .. availability:: Windows.
+
+ .. deprecated-removed:: 3.12 3.15
+
+
+.. c:var:: int Py_LegacyWindowsStdioFlag
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.legacy_windows_stdio` should be used instead, see
+ :ref:`Python Initialization Configuration <init-config>`.
+
+ If the flag is non-zero, use :class:`io.FileIO` instead of
+ :class:`!io._WindowsConsoleIO` for :mod:`sys` standard streams.
+
+ Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSSTDIO` environment
+ variable is set to a non-empty string.
+
+ See :pep:`528` for more details.
+
+ .. availability:: Windows.
+
+ .. deprecated-removed:: 3.12 3.15
+
+
+.. c:var:: int Py_NoSiteFlag
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.site_import` should be used instead, see
+ :ref:`Python Initialization Configuration <init-config>`.
+
+ Disable the import of the module :mod:`site` and the site-dependent
+ manipulations of :data:`sys.path` that it entails. Also disable these
+ manipulations if :mod:`site` is explicitly imported later (call
+ :func:`site.main` if you want them to be triggered).
+
+ Set by the :option:`-S` option.
+
+ .. deprecated-removed:: 3.12 3.15
+
+
+.. c:var:: int Py_NoUserSiteDirectory
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.user_site_directory` should be used instead, see
+ :ref:`Python Initialization Configuration <init-config>`.
+
+ Don't add the :data:`user site-packages directory <site.USER_SITE>` to
+ :data:`sys.path`.
+
+ Set by the :option:`-s` and :option:`-I` options, and the
+ :envvar:`PYTHONNOUSERSITE` environment variable.
+
+ .. deprecated-removed:: 3.12 3.15
+
+
+.. c:var:: int Py_OptimizeFlag
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.optimization_level` should be used instead, see
+ :ref:`Python Initialization Configuration <init-config>`.
+
+ Set by the :option:`-O` option and the :envvar:`PYTHONOPTIMIZE` environment
+ variable.
+
+ .. deprecated-removed:: 3.12 3.15
+
+
+.. c:var:: int Py_QuietFlag
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.quiet` should be used instead, see :ref:`Python
+ Initialization Configuration <init-config>`.
+
+ Don't display the copyright and version messages even in interactive mode.
+
+ Set by the :option:`-q` option.
+
+ .. versionadded:: 3.2
+
+ .. deprecated-removed:: 3.12 3.15
+
+
+.. c:var:: int Py_UnbufferedStdioFlag
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.buffered_stdio` should be used instead, see :ref:`Python
+ Initialization Configuration <init-config>`.
+
+ Force the stdout and stderr streams to be unbuffered.
+
+ Set by the :option:`-u` option and the :envvar:`PYTHONUNBUFFERED`
+ environment variable.
+
+ .. deprecated-removed:: 3.12 3.15
+
+
+.. c:var:: int Py_VerboseFlag
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.verbose` should be used instead, see :ref:`Python
+ Initialization Configuration <init-config>`.
+
+ Print a message each time a module is initialized, showing the place
+ (filename or built-in module) from which it is loaded. If greater or equal
+ to ``2``, print a message for each file that is checked for when
+ searching for a module. Also provides information on module cleanup at exit.
+
+ Set by the :option:`-v` option and the :envvar:`PYTHONVERBOSE` environment
+ variable.
+
+ .. deprecated-removed:: 3.12 3.15
+
+
+Initializing and finalizing the interpreter
+-------------------------------------------
+
+.. c:function:: void Py_Initialize()
+
+ .. index::
+ single: PyEval_InitThreads()
+ single: modules (in module sys)
+ single: path (in module sys)
+ pair: module; builtins
+ pair: module; __main__
+ pair: module; sys
+ triple: module; search; path
+ single: Py_FinalizeEx (C function)
+
+ Initialize the Python interpreter. In an application embedding Python,
+ this should be called before using any other Python/C API functions; see
+ :ref:`Before Python Initialization <pre-init-safe>` for the few exceptions.
+
+ This initializes the table of loaded modules (``sys.modules``), and creates
+ the fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`.
+ It also initializes the module search path (``sys.path``). It does not set
+ ``sys.argv``; use the :ref:`Python Initialization Configuration <init-config>`
+ API for that. This is a no-op when called for a second time (without calling
+ :c:func:`Py_FinalizeEx` first). There is no return value; it is a fatal
+ error if the initialization fails.
+
+ Use :c:func:`Py_InitializeFromConfig` to customize the
+ :ref:`Python Initialization Configuration <init-config>`.
+
+ .. note::
+ On Windows, changes the console mode from ``O_TEXT`` to ``O_BINARY``,
+ which will also affect non-Python uses of the console using the C Runtime.
+
+
+.. c:function:: void Py_InitializeEx(int initsigs)
+
+ This function works like :c:func:`Py_Initialize` if *initsigs* is ``1``. If
+ *initsigs* is ``0``, it skips initialization registration of signal handlers,
+ which may be useful when CPython is embedded as part of a larger application.
+
+ Use :c:func:`Py_InitializeFromConfig` to customize the
+ :ref:`Python Initialization Configuration <init-config>`.
+
+
+.. c:function:: PyStatus Py_InitializeFromConfig(const PyConfig *config)
+
+ Initialize Python from *config* configuration, as described in
+ :ref:`init-from-config`.
+
+ See the :ref:`init-config` section for details on pre-initializing the
+ interpreter, populating the runtime configuration structure, and querying
+ the returned status structure.
+
+
+.. c:function:: int Py_IsInitialized()
+
+ Return true (nonzero) when the Python interpreter has been initialized, false
+ (zero) if not. After :c:func:`Py_FinalizeEx` is called, this returns false until
+ :c:func:`Py_Initialize` is called again.
+
+
+.. c:function:: int Py_IsFinalizing()
+
+ Return true (non-zero) if the main Python interpreter is
+ :term:`shutting down <interpreter shutdown>`. Return false (zero) otherwise.
+
+ .. versionadded:: 3.13
+
+
+.. c:function:: int Py_FinalizeEx()
+
+ Undo all initializations made by :c:func:`Py_Initialize` and subsequent use of
+ Python/C API functions, and destroy all sub-interpreters (see
+ :c:func:`Py_NewInterpreter` below) that were created and not yet destroyed since
+ the last call to :c:func:`Py_Initialize`. This is a no-op when called for a second
+ time (without calling :c:func:`Py_Initialize` again first).
+
+ Since this is the reverse of :c:func:`Py_Initialize`, it should be called
+ in the same thread with the same interpreter active. That means
+ the main thread and the main interpreter.
+ This should never be called while :c:func:`Py_RunMain` is running.
+
+ Normally the return value is ``0``.
+ If there were errors during finalization (flushing buffered data),
+ ``-1`` is returned.
+
+ Note that Python will do a best effort at freeing all memory allocated by the Python
+ interpreter. Therefore, any C-Extension should make sure to correctly clean up all
+ of the previously allocated PyObjects before using them in subsequent calls to
+ :c:func:`Py_Initialize`. Otherwise it could introduce vulnerabilities and incorrect
+ behavior.
+
+ This function is provided for a number of reasons. An embedding application
+ might want to restart Python without having to restart the application itself.
+ An application that has loaded the Python interpreter from a dynamically
+ loadable library (or DLL) might want to free all memory allocated by Python
+ before unloading the DLL. During a hunt for memory leaks in an application a
+ developer might want to free all memory allocated by Python before exiting from
+ the application.
+
+ **Bugs and caveats:** The destruction of modules and objects in modules is done
+ in random order; this may cause destructors (:meth:`~object.__del__` methods) to fail
+ when they depend on other objects (even functions) or modules. Dynamically
+ loaded extension modules loaded by Python are not unloaded. Small amounts of
+ memory allocated by the Python interpreter may not be freed (if you find a leak,
+ please report it). Memory tied up in circular references between objects is not
+ freed. Interned strings will all be deallocated regardless of their reference count.
+ Some memory allocated by extension modules may not be freed. Some extensions may not
+ work properly if their initialization routine is called more than once; this can
+ happen if an application calls :c:func:`Py_Initialize` and :c:func:`Py_FinalizeEx`
+ more than once. :c:func:`Py_FinalizeEx` must not be called recursively from
+ within itself. Therefore, it must not be called by any code that may be run
+ as part of the interpreter shutdown process, such as :py:mod:`atexit`
+ handlers, object finalizers, or any code that may be run while flushing the
+ stdout and stderr files.
+
+ .. audit-event:: cpython._PySys_ClearAuditHooks "" c.Py_FinalizeEx
+
+ .. versionadded:: 3.6
+
+
+.. c:function:: void Py_Finalize()
+
+ This is a backwards-compatible version of :c:func:`Py_FinalizeEx` that
+ disregards the return value.
+
+
+.. c:function:: int Py_BytesMain(int argc, char **argv)
+
+ Similar to :c:func:`Py_Main` but *argv* is an array of bytes strings,
+ allowing the calling application to delegate the text decoding step to
+ the CPython runtime.
+
+ .. versionadded:: 3.8
+
+
+.. c:function:: int Py_Main(int argc, wchar_t **argv)
+
+ The main program for the standard interpreter, encapsulating a full
+ initialization/finalization cycle, as well as additional
+ behaviour to implement reading configurations settings from the environment
+ and command line, and then executing ``__main__`` in accordance with
+ :ref:`using-on-cmdline`.
+
+ This is made available for programs which wish to support the full CPython
+ command line interface, rather than just embedding a Python runtime in a
+ larger application.
+
+ The *argc* and *argv* parameters are similar to those which are passed to a
+ C program's :c:func:`main` function, except that the *argv* entries are first
+ converted to ``wchar_t`` using :c:func:`Py_DecodeLocale`. It is also
+ important to note that the argument list entries may be modified to point to
+ strings other than those passed in (however, the contents of the strings
+ pointed to by the argument list are not modified).
+
+ The return value is ``2`` if the argument list does not represent a valid
+ Python command line, and otherwise the same as :c:func:`Py_RunMain`.
+
+ In terms of the CPython runtime configuration APIs documented in the
+ :ref:`runtime configuration <init-config>` section (and without accounting
+ for error handling), ``Py_Main`` is approximately equivalent to::
+
+ PyConfig config;
+ PyConfig_InitPythonConfig(&config);
+ PyConfig_SetArgv(&config, argc, argv);
+ Py_InitializeFromConfig(&config);
+ PyConfig_Clear(&config);
+
+ Py_RunMain();
+
+ In normal usage, an embedding application will call this function
+ *instead* of calling :c:func:`Py_Initialize`, :c:func:`Py_InitializeEx` or
+ :c:func:`Py_InitializeFromConfig` directly, and all settings will be applied
+ as described elsewhere in this documentation. If this function is instead
+ called *after* a preceding runtime initialization API call, then exactly
+ which environmental and command line configuration settings will be updated
+ is version dependent (as it depends on which settings correctly support
+ being modified after they have already been set once when the runtime was
+ first initialized).
+
+
+.. c:function:: int Py_RunMain(void)
+
+ Executes the main module in a fully configured CPython runtime.
+
+ Executes the command (:c:member:`PyConfig.run_command`), the script
+ (:c:member:`PyConfig.run_filename`) or the module
+ (:c:member:`PyConfig.run_module`) specified on the command line or in the
+ configuration. If none of these values are set, runs the interactive Python
+ prompt (REPL) using the ``__main__`` module's global namespace.
+
+ If :c:member:`PyConfig.inspect` is not set (the default), the return value
+ will be ``0`` if the interpreter exits normally (that is, without raising
+ an exception), the exit status of an unhandled :exc:`SystemExit`, or ``1``
+ for any other unhandled exception.
+
+ If :c:member:`PyConfig.inspect` is set (such as when the :option:`-i` option
+ is used), rather than returning when the interpreter exits, execution will
+ instead resume in an interactive Python prompt (REPL) using the ``__main__``
+ module's global namespace. If the interpreter exited with an exception, it
+ is immediately raised in the REPL session. The function return value is
+ then determined by the way the *REPL session* terminates: ``0``, ``1``, or
+ the status of a :exc:`SystemExit`, as specified above.
+
+ This function always finalizes the Python interpreter before it returns.
+
+ See :ref:`Python Configuration <init-python-config>` for an example of a
+ customized Python that always runs in isolated mode using
+ :c:func:`Py_RunMain`.
+
+.. c:function:: int PyUnstable_AtExit(PyInterpreterState *interp, void (*func)(void *), void *data)
+
+ Register an :mod:`atexit` callback for the target interpreter *interp*.
+ This is similar to :c:func:`Py_AtExit`, but takes an explicit interpreter and
+ data pointer for the callback.
+
+ There must be an :term:`attached thread state` for *interp*.
+
+ .. versionadded:: 3.13
+
+
+.. _cautions-regarding-runtime-finalization:
+
+Cautions regarding runtime finalization
+---------------------------------------
+
+In the late stage of :term:`interpreter shutdown`, after attempting to wait for
+non-daemon threads to exit (though this can be interrupted by
+:class:`KeyboardInterrupt`) and running the :mod:`atexit` functions, the runtime
+is marked as *finalizing*: :c:func:`Py_IsFinalizing` and
+:func:`sys.is_finalizing` return true. At this point, only the *finalization
+thread* that initiated finalization (typically the main thread) is allowed to
+acquire the :term:`GIL`.
+
+If any thread, other than the finalization thread, attempts to attach a :term:`thread state`
+during finalization, either explicitly or
+implicitly, the thread enters **a permanently blocked state**
+where it remains until the program exits. In most cases this is harmless, but this can result
+in deadlock if a later stage of finalization attempts to acquire a lock owned by the
+blocked thread, or otherwise waits on the blocked thread.
+
+Gross? Yes. This prevents random crashes and/or unexpectedly skipped C++
+finalizations further up the call stack when such threads were forcibly exited
+here in CPython 3.13 and earlier. The CPython runtime :term:`thread state` C APIs
+have never had any error reporting or handling expectations at :term:`thread state`
+attachment time that would've allowed for graceful exit from this situation. Changing that
+would require new stable C APIs and rewriting the majority of C code in the
+CPython ecosystem to use those with error handling.
+
+
+Process-wide parameters
+-----------------------
+
+.. c:function:: void Py_SetProgramName(const wchar_t *name)
+
+ .. index::
+ single: Py_Initialize()
+ single: main()
+ single: Py_GetPath()
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.program_name` should be used instead, see :ref:`Python
+ Initialization Configuration <init-config>`.
+
+ This function should be called before :c:func:`Py_Initialize` is called for
+ the first time, if it is called at all. It tells the interpreter the value
+ of the ``argv[0]`` argument to the :c:func:`main` function of the program
+ (converted to wide characters).
+ This is used by :c:func:`Py_GetPath` and some other functions below to find
+ the Python run-time libraries relative to the interpreter executable. The
+ default value is ``'python'``. The argument should point to a
+ zero-terminated wide character string in static storage whose contents will not
+ change for the duration of the program's execution. No code in the Python
+ interpreter will change the contents of this storage.
+
+ Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
+ :c:expr:`wchar_t*` string.
+
+ .. deprecated-removed:: 3.11 3.15
+
+
+.. c:function:: wchar_t* Py_GetProgramName()
+
+ Return the program name set with :c:member:`PyConfig.program_name`, or the default.
+ The returned string points into static storage; the caller should not modify its
+ value.
+
+ This function should not be called before :c:func:`Py_Initialize`, otherwise
+ it returns ``NULL``.
+
+ .. versionchanged:: 3.10
+ It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
+
+ .. deprecated-removed:: 3.13 3.15
+ Use :c:func:`PyConfig_Get("executable") <PyConfig_Get>`
+ (:data:`sys.executable`) instead.
+
+
+.. c:function:: wchar_t* Py_GetPrefix()
+
+ Return the *prefix* for installed platform-independent files. This is derived
+ through a number of complicated rules from the program name set with
+ :c:member:`PyConfig.program_name` and some environment variables; for example, if the
+ program name is ``'/usr/local/bin/python'``, the prefix is ``'/usr/local'``. The
+ returned string points into static storage; the caller should not modify its
+ value. This corresponds to the :makevar:`prefix` variable in the top-level
+ :file:`Makefile` and the :option:`--prefix` argument to the :program:`configure`
+ script at build time. The value is available to Python code as ``sys.base_prefix``.
+ It is only useful on Unix. See also the next function.
+
+ This function should not be called before :c:func:`Py_Initialize`, otherwise
+ it returns ``NULL``.
+
+ .. versionchanged:: 3.10
+ It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
+
+ .. deprecated-removed:: 3.13 3.15
+ Use :c:func:`PyConfig_Get("base_prefix") <PyConfig_Get>`
+ (:data:`sys.base_prefix`) instead. Use :c:func:`PyConfig_Get("prefix")
+ <PyConfig_Get>` (:data:`sys.prefix`) if :ref:`virtual environments
+ <venv-def>` need to be handled.
+
+
+.. c:function:: wchar_t* Py_GetExecPrefix()
+
+ Return the *exec-prefix* for installed platform-*dependent* files. This is
+ derived through a number of complicated rules from the program name set with
+ :c:member:`PyConfig.program_name` and some environment variables; for example, if the
+ program name is ``'/usr/local/bin/python'``, the exec-prefix is
+ ``'/usr/local'``. The returned string points into static storage; the caller
+ should not modify its value. This corresponds to the :makevar:`exec_prefix`
+ variable in the top-level :file:`Makefile` and the ``--exec-prefix``
+ argument to the :program:`configure` script at build time. The value is
+ available to Python code as ``sys.base_exec_prefix``. It is only useful on
+ Unix.
+
+ Background: The exec-prefix differs from the prefix when platform dependent
+ files (such as executables and shared libraries) are installed in a different
+ directory tree. In a typical installation, platform dependent files may be
+ installed in the :file:`/usr/local/plat` subtree while platform independent may
+ be installed in :file:`/usr/local`.
+
+ Generally speaking, a platform is a combination of hardware and software
+ families, e.g. Sparc machines running the Solaris 2.x operating system are
+ considered the same platform, but Intel machines running Solaris 2.x are another
+ platform, and Intel machines running Linux are yet another platform. Different
+ major revisions of the same operating system generally also form different
+ platforms. Non-Unix operating systems are a different story; the installation
+ strategies on those systems are so different that the prefix and exec-prefix are
+ meaningless, and set to the empty string. Note that compiled Python bytecode
+ files are platform independent (but not independent from the Python version by
+ which they were compiled!).
+
+ System administrators will know how to configure the :program:`mount` or
+ :program:`automount` programs to share :file:`/usr/local` between platforms
+ while having :file:`/usr/local/plat` be a different filesystem for each
+ platform.
+
+ This function should not be called before :c:func:`Py_Initialize`, otherwise
+ it returns ``NULL``.
+
+ .. versionchanged:: 3.10
+ It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
+
+ .. deprecated-removed:: 3.13 3.15
+ Use :c:func:`PyConfig_Get("base_exec_prefix") <PyConfig_Get>`
+ (:data:`sys.base_exec_prefix`) instead. Use
+ :c:func:`PyConfig_Get("exec_prefix") <PyConfig_Get>`
+ (:data:`sys.exec_prefix`) if :ref:`virtual environments <venv-def>` need
+ to be handled.
+
+
+.. c:function:: wchar_t* Py_GetProgramFullPath()
+
+ .. index::
+ single: executable (in module sys)
+
+ Return the full program name of the Python executable; this is computed as a
+ side-effect of deriving the default module search path from the program name
+ (set by :c:member:`PyConfig.program_name`). The returned string points into
+ static storage; the caller should not modify its value. The value is available
+ to Python code as ``sys.executable``.
+
+ This function should not be called before :c:func:`Py_Initialize`, otherwise
+ it returns ``NULL``.
+
+ .. versionchanged:: 3.10
+ It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
+
+ .. deprecated-removed:: 3.13 3.15
+ Use :c:func:`PyConfig_Get("executable") <PyConfig_Get>`
+ (:data:`sys.executable`) instead.
+
+
+.. c:function:: wchar_t* Py_GetPath()
+
+ .. index::
+ triple: module; search; path
+ single: path (in module sys)
+
+ Return the default module search path; this is computed from the program name
+ (set by :c:member:`PyConfig.program_name`) and some environment variables.
+ The returned string consists of a series of directory names separated by a
+ platform dependent delimiter character. The delimiter character is ``':'``
+ on Unix and macOS, ``';'`` on Windows. The returned string points into
+ static storage; the caller should not modify its value. The list
+ :data:`sys.path` is initialized with this value on interpreter startup; it
+ can be (and usually is) modified later to change the search path for loading
+ modules.
+
+ This function should not be called before :c:func:`Py_Initialize`, otherwise
+ it returns ``NULL``.
+
+ .. XXX should give the exact rules
+
+ .. versionchanged:: 3.10
+ It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
+
+ .. deprecated-removed:: 3.13 3.15
+ Use :c:func:`PyConfig_Get("module_search_paths") <PyConfig_Get>`
+ (:data:`sys.path`) instead.
+
+.. c:function:: const char* Py_GetVersion()
+
+ Return the version of this Python interpreter. This is a string that looks
+ something like ::
+
+ "3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \n[GCC 4.2.3]"
+
+ .. index:: single: version (in module sys)
+
+ The first word (up to the first space character) is the current Python version;
+ the first characters are the major and minor version separated by a
+ period. The returned string points into static storage; the caller should not
+ modify its value. The value is available to Python code as :data:`sys.version`.
+
+ See also the :c:var:`Py_Version` constant.
+
+
+.. c:function:: const char* Py_GetPlatform()
+
+ .. index:: single: platform (in module sys)
+
+ Return the platform identifier for the current platform. On Unix, this is
+ formed from the "official" name of the operating system, converted to lower
+ case, followed by the major revision number; e.g., for Solaris 2.x, which is
+ also known as SunOS 5.x, the value is ``'sunos5'``. On macOS, it is
+ ``'darwin'``. On Windows, it is ``'win'``. The returned string points into
+ static storage; the caller should not modify its value. The value is available
+ to Python code as ``sys.platform``.
+
+
+.. c:function:: const char* Py_GetCopyright()
+
+ Return the official copyright string for the current Python version, for example
+
+ ``'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'``
+
+ .. index:: single: copyright (in module sys)
+
+ The returned string points into static storage; the caller should not modify its
+ value. The value is available to Python code as ``sys.copyright``.
+
+
+.. c:function:: const char* Py_GetCompiler()
+
+ Return an indication of the compiler used to build the current Python version,
+ in square brackets, for example::
+
+ "[GCC 2.7.2.2]"
+
+ .. index:: single: version (in module sys)
+
+ The returned string points into static storage; the caller should not modify its
+ value. The value is available to Python code as part of the variable
+ ``sys.version``.
+
+
+.. c:function:: const char* Py_GetBuildInfo()
+
+ Return information about the sequence number and build date and time of the
+ current Python interpreter instance, for example ::
+
+ "#67, Aug 1 1997, 22:34:28"
+
+ .. index:: single: version (in module sys)
+
+ The returned string points into static storage; the caller should not modify its
+ value. The value is available to Python code as part of the variable
+ ``sys.version``.
+
+
+.. c:function:: void PySys_SetArgvEx(int argc, wchar_t **argv, int updatepath)
+
+ .. index::
+ single: main()
+ single: Py_FatalError()
+ single: argv (in module sys)
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.argv`, :c:member:`PyConfig.parse_argv` and
+ :c:member:`PyConfig.safe_path` should be used instead, see :ref:`Python
+ Initialization Configuration <init-config>`.
+
+ Set :data:`sys.argv` based on *argc* and *argv*. These parameters are
+ similar to those passed to the program's :c:func:`main` function with the
+ difference that the first entry should refer to the script file to be
+ executed rather than the executable hosting the Python interpreter. If there
+ isn't a script that will be run, the first entry in *argv* can be an empty
+ string. If this function fails to initialize :data:`sys.argv`, a fatal
+ condition is signalled using :c:func:`Py_FatalError`.
+
+ If *updatepath* is zero, this is all the function does. If *updatepath*
+ is non-zero, the function also modifies :data:`sys.path` according to the
+ following algorithm:
+
+ - If the name of an existing script is passed in ``argv[0]``, the absolute
+ path of the directory where the script is located is prepended to
+ :data:`sys.path`.
+ - Otherwise (that is, if *argc* is ``0`` or ``argv[0]`` doesn't point
+ to an existing file name), an empty string is prepended to
+ :data:`sys.path`, which is the same as prepending the current working
+ directory (``"."``).
+
+ Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
+ :c:expr:`wchar_t*` string.
+
+ See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv`
+ members of the :ref:`Python Initialization Configuration <init-config>`.
+
+ .. note::
+ It is recommended that applications embedding the Python interpreter
+ for purposes other than executing a single script pass ``0`` as *updatepath*,
+ and update :data:`sys.path` themselves if desired.
+ See :cve:`2008-5983`.
+
+ On versions before 3.1.3, you can achieve the same effect by manually
+ popping the first :data:`sys.path` element after having called
+ :c:func:`PySys_SetArgv`, for example using::
+
+ PyRun_SimpleString("import sys; sys.path.pop(0)\n");
+
+ .. versionadded:: 3.1.3
+
+ .. deprecated-removed:: 3.11 3.15
+
+
+.. c:function:: void PySys_SetArgv(int argc, wchar_t **argv)
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.argv` and :c:member:`PyConfig.parse_argv` should be used
+ instead, see :ref:`Python Initialization Configuration <init-config>`.
+
+ This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set
+ to ``1`` unless the :program:`python` interpreter was started with the
+ :option:`-I`.
+
+ Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
+ :c:expr:`wchar_t*` string.
+
+ See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv`
+ members of the :ref:`Python Initialization Configuration <init-config>`.
+
+ .. versionchanged:: 3.4 The *updatepath* value depends on :option:`-I`.
+
+ .. deprecated-removed:: 3.11 3.15
+
+
+.. c:function:: void Py_SetPythonHome(const wchar_t *home)
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.home` should be used instead, see :ref:`Python
+ Initialization Configuration <init-config>`.
+
+ Set the default "home" directory, that is, the location of the standard
+ Python libraries. See :envvar:`PYTHONHOME` for the meaning of the
+ argument string.
+
+ The argument should point to a zero-terminated character string in static
+ storage whose contents will not change for the duration of the program's
+ execution. No code in the Python interpreter will change the contents of
+ this storage.
+
+ Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
+ :c:expr:`wchar_t*` string.
+
+ .. deprecated-removed:: 3.11 3.15
+
+
+.. c:function:: wchar_t* Py_GetPythonHome()
+
+ Return the default "home", that is, the value set by
+ :c:member:`PyConfig.home`, or the value of the :envvar:`PYTHONHOME`
+ environment variable if it is set.
+
+ This function should not be called before :c:func:`Py_Initialize`, otherwise
+ it returns ``NULL``.
+
+ .. versionchanged:: 3.10
+ It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
+
+ .. deprecated-removed:: 3.13 3.15
+ Use :c:func:`PyConfig_Get("home") <PyConfig_Get>` or the
+ :envvar:`PYTHONHOME` environment variable instead.
diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index c7520adc121..d73377fb6e6 100644
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -116,124 +116,152 @@ defined closer to where they are useful (for example, :c:macro:`Py_RETURN_NONE`,
Others of a more general utility are defined here. This is not necessarily a
complete listing.
+.. c:macro:: Py_CAN_START_THREADS
-.. c:macro:: Py_ABS(x)
-
- Return the absolute value of ``x``.
+ If this macro is defined, then the current system is able to start threads.
- If the result cannot be represented (for example, if ``x`` has
- :c:macro:`!INT_MIN` value for :c:expr:`int` type), the behavior is
- undefined.
+ Currently, all systems supported by CPython (per :pep:`11`), with the
+ exception of some WebAssembly platforms, support starting threads.
- .. versionadded:: 3.3
+ .. versionadded:: 3.13
-.. c:macro:: Py_ALWAYS_INLINE
+.. c:macro:: Py_GETENV(s)
- Ask the compiler to always inline a static inline function. The compiler can
- ignore it and decide to not inline the function.
+ Like :samp:`getenv({s})`, but returns ``NULL`` if :option:`-E` was passed
+ on the command line (see :c:member:`PyConfig.use_environment`).
- It can be used to inline performance critical static inline functions when
- building Python in debug mode with function inlining disabled. For example,
- MSC disables function inlining when building in debug mode.
- Marking blindly a static inline function with Py_ALWAYS_INLINE can result in
- worse performances (due to increased code size for example). The compiler is
- usually smarter than the developer for the cost/benefit analysis.
+Docstring macros
+----------------
- If Python is :ref:`built in debug mode <debug-build>` (if the :c:macro:`Py_DEBUG`
- macro is defined), the :c:macro:`Py_ALWAYS_INLINE` macro does nothing.
+.. c:macro:: PyDoc_STRVAR(name, str)
- It must be specified before the function return type. Usage::
+ Creates a variable with name *name* that can be used in docstrings.
+ If Python is built without docstrings (:option:`--without-doc-strings`),
+ the value will be an empty string.
- static inline Py_ALWAYS_INLINE int random(void) { return 4; }
+ Example::
- .. versionadded:: 3.11
+ PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element.");
-.. c:macro:: Py_CHARMASK(c)
+ static PyMethodDef deque_methods[] = {
+ // ...
+ {"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},
+ // ...
+ }
- Argument must be a character or an integer in the range [-128, 127] or [0,
- 255]. This macro returns ``c`` cast to an ``unsigned char``.
+ Expands to :samp:`PyDoc_VAR({name}) = PyDoc_STR({str})`.
-.. c:macro:: Py_DEPRECATED(version)
+.. c:macro:: PyDoc_STR(str)
- Use this for deprecated declarations. The macro must be placed before the
- symbol name.
+ Expands to the given input string, or an empty string
+ if docstrings are disabled (:option:`--without-doc-strings`).
Example::
- Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);
+ static PyMethodDef pysqlite_row_methods[] = {
+ {"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS,
+ PyDoc_STR("Returns the keys of the row.")},
+ {NULL, NULL}
+ };
- .. versionchanged:: 3.8
- MSVC support was added.
+.. c:macro:: PyDoc_VAR(name)
-.. c:macro:: Py_GETENV(s)
+ Declares a static character array variable with the given *name*.
+ Expands to :samp:`static const char {name}[]`
- Like ``getenv(s)``, but returns ``NULL`` if :option:`-E` was passed on the
- command line (see :c:member:`PyConfig.use_environment`).
+ For example::
-.. c:macro:: Py_LOCAL(type)
+ PyDoc_VAR(python_doc) = PyDoc_STR(
+ "A genus of constricting snakes in the Pythonidae family native "
+ "to the tropics and subtropics of the Eastern Hemisphere.");
- Declare a function returning the specified *type* using a fast-calling
- qualifier for functions that are local to the current file.
- Semantically, this is equivalent to ``static type``.
-.. c:macro:: Py_LOCAL_INLINE(type)
+General utility macros
+----------------------
- Equivalent to :c:macro:`Py_LOCAL` but additionally requests the function
- be inlined.
+The following macros are for common tasks not specific to Python.
-.. c:macro:: Py_LOCAL_SYMBOL
+.. c:macro:: Py_UNUSED(arg)
- Macro used to declare a symbol as local to the shared library (hidden).
- On supported platforms, it ensures the symbol is not exported.
+ Use this for unused arguments in a function definition to silence compiler
+ warnings. Example: ``int func(int a, int Py_UNUSED(b)) { return a; }``.
- On compatible versions of GCC/Clang, it
- expands to ``__attribute__((visibility("hidden")))``.
+ .. versionadded:: 3.4
-.. c:macro:: Py_MAX(x, y)
+.. c:macro:: Py_GCC_ATTRIBUTE(name)
- Return the maximum value between ``x`` and ``y``.
+ Use a GCC attribute *name*, hiding it from compilers that don't support GCC
+ attributes (such as MSVC).
- .. versionadded:: 3.3
+ This expands to :samp:`__attribute__(({name)})` on a GCC compiler,
+ and expands to nothing on compilers that don't support GCC attributes.
-.. c:macro:: Py_MEMBER_SIZE(type, member)
- Return the size of a structure (``type``) ``member`` in bytes.
+Numeric utilities
+^^^^^^^^^^^^^^^^^
- .. versionadded:: 3.6
+.. c:macro:: Py_ABS(x)
-.. c:macro:: Py_MEMCPY(dest, src, n)
+ Return the absolute value of ``x``.
- This is a :term:`soft deprecated` alias to :c:func:`!memcpy`.
- Use :c:func:`!memcpy` directly instead.
+ The argument may be evaluated more than once.
+ Consequently, do not pass an expression with side-effects directly
+ to this macro.
- .. deprecated:: 3.14
- The macro is :term:`soft deprecated`.
+ If the result cannot be represented (for example, if ``x`` has
+ :c:macro:`!INT_MIN` value for :c:expr:`int` type), the behavior is
+ undefined.
+
+ Corresponds roughly to :samp:`(({x}) < 0 ? -({x}) : ({x}))`
+
+ .. versionadded:: 3.3
-.. c:macro:: Py_MIN(x, y)
+.. c:macro:: Py_MAX(x, y)
+ Py_MIN(x, y)
+
+ Return the larger or smaller of the arguments, respectively.
- Return the minimum value between ``x`` and ``y``.
+ Any arguments may be evaluated more than once.
+ Consequently, do not pass an expression with side-effects directly
+ to this macro.
+
+ :c:macro:`!Py_MAX` corresponds roughly to
+ :samp:`((({x}) > ({y})) ? ({x}) : ({y}))`.
.. versionadded:: 3.3
-.. c:macro:: Py_NO_INLINE
+.. c:macro:: Py_ARITHMETIC_RIGHT_SHIFT(type, integer, positions)
- Disable inlining on a function. For example, it reduces the C stack
- consumption: useful on LTO+PGO builds which heavily inline code (see
- :issue:`33720`).
+ Similar to :samp:`{integer} >> {positions}`, but forces sign extension,
+ as the C standard does not define whether a right-shift of a signed
+ integer will perform sign extension or a zero-fill.
- Usage::
+ *integer* should be any signed integer type.
+ *positions* is the number of positions to shift to the right.
- Py_NO_INLINE static int random(void) { return 4; }
+ Both *integer* and *positions* can be evaluated more than once;
+ consequently, avoid directly passing a function call or some other
+ operation with side-effects to this macro. Instead, store the result as a
+ variable and then pass it.
- .. versionadded:: 3.11
+ *type* is unused and only kept for backwards compatibility. Historically,
+ *type* was used to cast *integer*.
-.. c:macro:: Py_STRINGIFY(x)
+ .. versionchanged:: 3.1
- Convert ``x`` to a C string. E.g. ``Py_STRINGIFY(123)`` returns
- ``"123"``.
+ This macro is now valid for all signed integer types, not just those for
+ which ``unsigned type`` is legal. As a result, *type* is no longer
+ used.
- .. versionadded:: 3.4
+.. c:macro:: Py_CHARMASK(c)
+
+ Argument must be a character or an integer in the range [-128, 127] or [0,
+ 255]. This macro returns ``c`` cast to an ``unsigned char``.
+
+
+Assertion utilities
+^^^^^^^^^^^^^^^^^^^
.. c:macro:: Py_UNREACHABLE()
@@ -246,8 +274,11 @@ complete listing.
avoids a warning about unreachable code. For example, the macro is
implemented with ``__builtin_unreachable()`` on GCC in release mode.
- A use for ``Py_UNREACHABLE()`` is following a call a function that
- never returns but that is not declared :c:macro:`_Py_NO_RETURN`.
+ In debug mode, and on unsupported compilers, the macro expands to a call to
+ :c:func:`Py_FatalError`.
+
+ A use for ``Py_UNREACHABLE()`` is following a call to a function that
+ never returns but that is not declared ``_Noreturn``.
If a code path is very unlikely code but can be reached under exceptional
case, this macro must not be used. For example, under low memory condition
@@ -257,18 +288,29 @@ complete listing.
.. versionadded:: 3.7
-.. c:macro:: Py_UNUSED(arg)
+.. c:macro:: Py_SAFE_DOWNCAST(value, larger, smaller)
- Use this for unused arguments in a function definition to silence compiler
- warnings. Example: ``int func(int a, int Py_UNUSED(b)) { return a; }``.
+ Cast *value* to type *smaller* from type *larger*, validating that no
+ information was lost.
- .. versionadded:: 3.4
+ On release builds of Python, this is roughly equivalent to
+ :samp:`(({smaller}) {value})`
+ (in C++, :samp:`static_cast<{smaller}>({value})` will be used instead).
+
+ On debug builds (implying that :c:macro:`Py_DEBUG` is defined), this asserts
+ that no information was lost with the cast from *larger* to *smaller*.
+
+ *value*, *larger*, and *smaller* may all be evaluated more than once in the
+ expression; consequently, do not pass an expression with side-effects
+ directly to this macro.
.. c:macro:: Py_BUILD_ASSERT(cond)
Asserts a compile-time condition *cond*, as a statement.
The build will fail if the condition is false or cannot be evaluated at compile time.
+ Corresponds roughly to :samp:`static_assert({cond})` on C23 and above.
+
For example::
Py_BUILD_ASSERT(sizeof(PyTime_t) == sizeof(int64_t));
@@ -287,62 +329,127 @@ complete listing.
.. versionadded:: 3.3
-.. c:macro:: PyDoc_STRVAR(name, str)
- Creates a variable with name *name* that can be used in docstrings.
- If Python is built without docstrings, the value will be empty.
+Type size utilities
+^^^^^^^^^^^^^^^^^^^
- Use :c:macro:`PyDoc_STRVAR` for docstrings to support building
- Python without docstrings, as specified in :pep:`7`.
+.. c:macro:: Py_ARRAY_LENGTH(array)
- Example::
+ Compute the length of a statically allocated C array at compile time.
- PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element.");
+ The *array* argument must be a C array with a size known at compile time.
+ Passing an array with an unknown size, such as a heap-allocated array,
+ will result in a compilation error on some compilers, or otherwise produce
+ incorrect results.
- static PyMethodDef deque_methods[] = {
- // ...
- {"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},
- // ...
- }
+ This is roughly equivalent to::
-.. c:macro:: PyDoc_STR(str)
+ sizeof(array) / sizeof((array)[0])
- Creates a docstring for the given input string or an empty string
- if docstrings are disabled.
+.. c:macro:: Py_MEMBER_SIZE(type, member)
- Use :c:macro:`PyDoc_STR` in specifying docstrings to support
- building Python without docstrings, as specified in :pep:`7`.
+ Return the size of a structure (*type*) *member* in bytes.
- Example::
+ Corresponds roughly to :samp:`sizeof((({type} *)NULL)->{member})`.
- static PyMethodDef pysqlite_row_methods[] = {
- {"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS,
- PyDoc_STR("Returns the keys of the row.")},
- {NULL, NULL}
- };
+ .. versionadded:: 3.6
-.. c:macro:: PyDoc_VAR(name)
- Declares a static character array variable with the given name *name*.
+Macro definition utilities
+^^^^^^^^^^^^^^^^^^^^^^^^^^
- For example::
+.. c:macro:: Py_FORCE_EXPANSION(X)
- PyDoc_VAR(python_doc) = PyDoc_STR("A genus of constricting snakes in the Pythonidae family native "
- "to the tropics and subtropics of the Eastern Hemisphere.");
+ This is equivalent to :samp:`{X}`, which is useful for token-pasting in
+ macros, as macro expansions in *X* are forcefully evaluated by the
+ preprocessor.
-.. c:macro:: Py_ARRAY_LENGTH(array)
+.. c:macro:: Py_STRINGIFY(x)
- Compute the length of a statically allocated C array at compile time.
+ Convert ``x`` to a C string. For example, ``Py_STRINGIFY(123)`` returns
+ ``"123"``.
- The *array* argument must be a C array with a size known at compile time.
- Passing an array with an unknown size, such as a heap-allocated array,
- will result in a compilation error on some compilers, or otherwise produce
- incorrect results.
+ .. versionadded:: 3.4
- This is roughly equivalent to::
- sizeof(array) / sizeof((array)[0])
+Declaration utilities
+---------------------
+
+The following macros can be used in declarations.
+They are most useful for defining the C API itself, and have limited use
+for extension authors.
+Most of them expand to compiler-specific spellings of common extensions
+to the C language.
+
+.. c:macro:: Py_ALWAYS_INLINE
+
+ Ask the compiler to always inline a static inline function. The compiler can
+ ignore it and decide to not inline the function.
+
+ Corresponds to ``always_inline`` attribute in GCC and ``__forceinline``
+ in MSVC.
+
+ It can be used to inline performance critical static inline functions when
+ building Python in debug mode with function inlining disabled. For example,
+ MSC disables function inlining when building in debug mode.
+
+ Marking blindly a static inline function with Py_ALWAYS_INLINE can result in
+ worse performances (due to increased code size for example). The compiler is
+ usually smarter than the developer for the cost/benefit analysis.
+
+ If Python is :ref:`built in debug mode <debug-build>` (if the :c:macro:`Py_DEBUG`
+ macro is defined), the :c:macro:`Py_ALWAYS_INLINE` macro does nothing.
+
+ It must be specified before the function return type. Usage::
+
+ static inline Py_ALWAYS_INLINE int random(void) { return 4; }
+
+ .. versionadded:: 3.11
+
+.. c:macro:: Py_NO_INLINE
+
+ Disable inlining on a function. For example, it reduces the C stack
+ consumption: useful on LTO+PGO builds which heavily inline code (see
+ :issue:`33720`).
+
+ Corresponds to the ``noinline`` attribute/specification on GCC and MSVC.
+
+ Usage::
+
+ Py_NO_INLINE static int random(void) { return 4; }
+
+ .. versionadded:: 3.11
+
+.. c:macro:: Py_DEPRECATED(version)
+
+ Use this to declare APIs that were deprecated in a specific CPython version.
+ The macro must be placed before the symbol name.
+
+ Example::
+
+ Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);
+
+ .. versionchanged:: 3.8
+ MSVC support was added.
+
+.. c:macro:: Py_LOCAL(type)
+
+ Declare a function returning the specified *type* using a fast-calling
+ qualifier for functions that are local to the current file.
+ Semantically, this is equivalent to :samp:`static {type}`.
+
+.. c:macro:: Py_LOCAL_INLINE(type)
+
+ Equivalent to :c:macro:`Py_LOCAL` but additionally requests the function
+ be inlined.
+.. c:macro:: Py_LOCAL_SYMBOL
+
+ Macro used to declare a symbol as local to the shared library (hidden).
+ On supported platforms, it ensures the symbol is not exported.
+
+ On compatible versions of GCC/Clang, it
+ expands to ``__attribute__((visibility("hidden")))``.
.. c:macro:: Py_EXPORTED_SYMBOL
@@ -376,6 +483,48 @@ complete listing.
extension modules should not use it for their own symbols.
+Outdated macros
+---------------
+
+The following macros have been used to features that have been standardized
+in C11.
+
+.. c:macro:: Py_ALIGNED(num)
+
+ Specify alignment to *num* bytes on compilers that support it.
+
+ Consider using the C11 standard ``_Alignas`` specifier over this macro.
+
+.. c:macro:: Py_LL(number)
+ Py_ULL(number)
+
+ Use *number* as a ``long long`` or ``unsigned long long`` integer literal,
+ respectively.
+
+ Expands to *number* followed by ``LL`` or ``LLU``, respectively, but will
+ expand to some compiler-specific suffixes on some older compilers.
+
+ Consider using the C99 standard suffixes ``LL`` and ``LLU`` directly.
+
+.. c:macro:: Py_MEMCPY(dest, src, n)
+
+ This is a :term:`soft deprecated` alias to :c:func:`!memcpy`.
+ Use :c:func:`!memcpy` directly instead.
+
+ .. deprecated:: 3.14
+ The macro is :term:`soft deprecated`.
+
+.. c:macro:: Py_VA_COPY
+
+ This is a :term:`soft deprecated` alias to the C99-standard ``va_copy``
+ function.
+
+ Historically, this would use a compiler-specific method to copy a ``va_list``.
+
+ .. versionchanged:: 3.6
+ This is now an alias to ``va_copy``.
+
+
.. _api-objects:
Objects, Types and Reference Counts
diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst
index a3be75a2a76..0dd57eaf37e 100644
--- a/Doc/c-api/memory.rst
+++ b/Doc/c-api/memory.rst
@@ -208,8 +208,11 @@ The following function sets, modeled after the ANSI C standard, but specifying
behavior when requesting zero bytes, are available for allocating and releasing
memory from the Python heap.
-The :ref:`default memory allocator <default-memory-allocators>` uses the
-:ref:`pymalloc memory allocator <pymalloc>`.
+In the GIL-enabled build (default build) the
+:ref:`default memory allocator <default-memory-allocators>` uses the
+:ref:`pymalloc memory allocator <pymalloc>`, whereas in the
+:term:`free-threaded build`, the default is the
+:ref:`mimalloc memory allocator <mimalloc>` instead.
.. warning::
@@ -219,6 +222,11 @@ The :ref:`default memory allocator <default-memory-allocators>` uses the
The default allocator is now pymalloc instead of system :c:func:`malloc`.
+.. versionchanged:: 3.13
+
+ In the :term:`free-threaded <free threading>` build, the default allocator
+ is now :ref:`mimalloc <mimalloc>`.
+
.. c:function:: void* PyMem_Malloc(size_t n)
Allocates *n* bytes and returns a pointer of type :c:expr:`void*` to the
@@ -344,7 +352,9 @@ memory from the Python heap.
the :ref:`Customize Memory Allocators <customize-memory-allocators>` section.
The :ref:`default object allocator <default-memory-allocators>` uses the
-:ref:`pymalloc memory allocator <pymalloc>`.
+:ref:`pymalloc memory allocator <pymalloc>`. In the
+:term:`free-threaded <free threading>` build, the default is the
+:ref:`mimalloc memory allocator <mimalloc>` instead.
.. warning::
@@ -424,14 +434,16 @@ Default Memory Allocators
Default memory allocators:
-=============================== ==================== ================== ===================== ====================
-Configuration Name PyMem_RawMalloc PyMem_Malloc PyObject_Malloc
-=============================== ==================== ================== ===================== ====================
-Release build ``"pymalloc"`` ``malloc`` ``pymalloc`` ``pymalloc``
-Debug build ``"pymalloc_debug"`` ``malloc`` + debug ``pymalloc`` + debug ``pymalloc`` + debug
-Release build, without pymalloc ``"malloc"`` ``malloc`` ``malloc`` ``malloc``
-Debug build, without pymalloc ``"malloc_debug"`` ``malloc`` + debug ``malloc`` + debug ``malloc`` + debug
-=============================== ==================== ================== ===================== ====================
+=================================== ======================= ==================== ====================== ======================
+Configuration Name PyMem_RawMalloc PyMem_Malloc PyObject_Malloc
+=================================== ======================= ==================== ====================== ======================
+Release build ``"pymalloc"`` ``malloc`` ``pymalloc`` ``pymalloc``
+Debug build ``"pymalloc_debug"`` ``malloc`` + debug ``pymalloc`` + debug ``pymalloc`` + debug
+Release build, without pymalloc ``"malloc"`` ``malloc`` ``malloc`` ``malloc``
+Debug build, without pymalloc ``"malloc_debug"`` ``malloc`` + debug ``malloc`` + debug ``malloc`` + debug
+Free-threaded build ``"mimalloc"`` ``mimalloc`` ``mimalloc`` ``mimalloc``
+Free-threaded debug build ``"mimalloc_debug"`` ``mimalloc`` + debug ``mimalloc`` + debug ``mimalloc`` + debug
+=================================== ======================= ==================== ====================== ======================
Legend:
@@ -439,8 +451,7 @@ Legend:
* ``malloc``: system allocators from the standard C library, C functions:
:c:func:`malloc`, :c:func:`calloc`, :c:func:`realloc` and :c:func:`free`.
* ``pymalloc``: :ref:`pymalloc memory allocator <pymalloc>`.
-* ``mimalloc``: :ref:`mimalloc memory allocator <mimalloc>`. The pymalloc
- allocator will be used if mimalloc support isn't available.
+* ``mimalloc``: :ref:`mimalloc memory allocator <mimalloc>`.
* "+ debug": with :ref:`debug hooks on the Python memory allocators
<pymem-debug-hooks>`.
* "Debug build": :ref:`Python build in debug mode <debug-build>`.
@@ -733,9 +744,27 @@ The mimalloc allocator
.. versionadded:: 3.13
-Python supports the mimalloc allocator when the underlying platform support is available.
-mimalloc "is a general purpose allocator with excellent performance characteristics.
-Initially developed by Daan Leijen for the runtime systems of the Koka and Lean languages."
+Python supports the `mimalloc <https://github.com/microsoft/mimalloc/>`__
+allocator when the underlying platform support is available.
+mimalloc is a general purpose allocator with excellent performance
+characteristics, initially developed by Daan Leijen for the runtime systems
+of the Koka and Lean languages.
+
+Unlike :ref:`pymalloc <pymalloc>`, which is optimized for small objects (512
+bytes or fewer), mimalloc handles allocations of any size.
+
+In the :term:`free-threaded <free threading>` build, mimalloc is the default
+and **required** allocator for the :c:macro:`PYMEM_DOMAIN_MEM` and
+:c:macro:`PYMEM_DOMAIN_OBJ` domains. It cannot be disabled in free-threaded
+builds. The free-threaded build uses per-thread mimalloc heaps, which allows
+allocation and deallocation to proceed without locking in most cases.
+
+In the default (non-free-threaded) build, mimalloc is available but not the
+default allocator. It can be selected at runtime using
+:envvar:`PYTHONMALLOC`\ ``=mimalloc`` (or ``mimalloc_debug`` to include
+:ref:`debug hooks <pymem-debug-hooks>`). It can be disabled at build time
+using the :option:`--without-mimalloc` configure option, but this option
+cannot be combined with :option:`--disable-gil`.
tracemalloc C API
=================
diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
index eed47c8966c..49ac4de6655 100644
--- a/Doc/c-api/module.rst
+++ b/Doc/c-api/module.rst
@@ -277,6 +277,11 @@ data stored in module state.
No longer called before the module state is allocated.
+.. c:var:: PyTypeObject PyModuleDef_Type
+
+ The type of ``PyModuleDef`` objects.
+
+
Module slots
............
diff --git a/Doc/c-api/profiling.rst b/Doc/c-api/profiling.rst
new file mode 100644
index 00000000000..0200f2eac6d
--- /dev/null
+++ b/Doc/c-api/profiling.rst
@@ -0,0 +1,239 @@
+.. highlight:: c
+
+.. _profiling:
+
+Profiling and tracing
+=====================
+
+The Python interpreter provides some low-level support for attaching profiling
+and execution tracing facilities. These are used for profiling, debugging, and
+coverage analysis tools.
+
+This C interface allows the profiling or tracing code to avoid the overhead of
+calling through Python-level callable objects, making a direct C function call
+instead. The essential attributes of the facility have not changed; the
+interface allows trace functions to be installed per-thread, and the basic
+events reported to the trace function are the same as had been reported to the
+Python-level trace functions in previous versions.
+
+
+.. c:type:: int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)
+
+ The type of the trace function registered using :c:func:`PyEval_SetProfile` and
+ :c:func:`PyEval_SetTrace`. The first parameter is the object passed to the
+ registration function as *obj*, *frame* is the frame object to which the event
+ pertains, *what* is one of the constants :c:data:`PyTrace_CALL`,
+ :c:data:`PyTrace_EXCEPTION`, :c:data:`PyTrace_LINE`, :c:data:`PyTrace_RETURN`,
+ :c:data:`PyTrace_C_CALL`, :c:data:`PyTrace_C_EXCEPTION`, :c:data:`PyTrace_C_RETURN`,
+ or :c:data:`PyTrace_OPCODE`, and *arg* depends on the value of *what*:
+
+ +-------------------------------+----------------------------------------+
+ | Value of *what* | Meaning of *arg* |
+ +===============================+========================================+
+ | :c:data:`PyTrace_CALL` | Always :c:data:`Py_None`. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_EXCEPTION` | Exception information as returned by |
+ | | :func:`sys.exc_info`. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_LINE` | Always :c:data:`Py_None`. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_RETURN` | Value being returned to the caller, |
+ | | or ``NULL`` if caused by an exception. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_C_CALL` | Function object being called. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_C_EXCEPTION` | Function object being called. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_C_RETURN` | Function object being called. |
+ +-------------------------------+----------------------------------------+
+ | :c:data:`PyTrace_OPCODE` | Always :c:data:`Py_None`. |
+ +-------------------------------+----------------------------------------+
+
+.. c:var:: int PyTrace_CALL
+
+ The value of the *what* parameter to a :c:type:`Py_tracefunc` function when a new
+ call to a function or method is being reported, or a new entry into a generator.
+ Note that the creation of the iterator for a generator function is not reported
+ as there is no control transfer to the Python bytecode in the corresponding
+ frame.
+
+
+.. c:var:: int PyTrace_EXCEPTION
+
+ The value of the *what* parameter to a :c:type:`Py_tracefunc` function when an
+ exception has been raised. The callback function is called with this value for
+ *what* when after any bytecode is processed after which the exception becomes
+ set within the frame being executed. The effect of this is that as exception
+ propagation causes the Python stack to unwind, the callback is called upon
+ return to each frame as the exception propagates. Only trace functions receive
+ these events; they are not needed by the profiler.
+
+
+.. c:var:: int PyTrace_LINE
+
+ The value passed as the *what* parameter to a :c:type:`Py_tracefunc` function
+ (but not a profiling function) when a line-number event is being reported.
+ It may be disabled for a frame by setting :attr:`~frame.f_trace_lines` to
+ *0* on that frame.
+
+
+.. c:var:: int PyTrace_RETURN
+
+ The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a
+ call is about to return.
+
+
+.. c:var:: int PyTrace_C_CALL
+
+ The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C
+ function is about to be called.
+
+
+.. c:var:: int PyTrace_C_EXCEPTION
+
+ The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C
+ function has raised an exception.
+
+
+.. c:var:: int PyTrace_C_RETURN
+
+ The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C
+ function has returned.
+
+
+.. c:var:: int PyTrace_OPCODE
+
+ The value for the *what* parameter to :c:type:`Py_tracefunc` functions (but not
+ profiling functions) when a new opcode is about to be executed. This event is
+ not emitted by default: it must be explicitly requested by setting
+ :attr:`~frame.f_trace_opcodes` to *1* on the frame.
+
+
+.. c:function:: void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)
+
+ Set the profiler function to *func*. The *obj* parameter is passed to the
+ function as its first parameter, and may be any Python object, or ``NULL``. If
+ the profile function needs to maintain state, using a different value for *obj*
+ for each thread provides a convenient and thread-safe place to store it. The
+ profile function is called for all monitored events except :c:data:`PyTrace_LINE`
+ :c:data:`PyTrace_OPCODE` and :c:data:`PyTrace_EXCEPTION`.
+
+ See also the :func:`sys.setprofile` function.
+
+ The caller must have an :term:`attached thread state`.
+
+
+.. c:function:: void PyEval_SetProfileAllThreads(Py_tracefunc func, PyObject *obj)
+
+ Like :c:func:`PyEval_SetProfile` but sets the profile function in all running threads
+ belonging to the current interpreter instead of the setting it only on the current thread.
+
+ The caller must have an :term:`attached thread state`.
+
+ As :c:func:`PyEval_SetProfile`, this function ignores any exceptions raised while
+ setting the profile functions in all threads.
+
+.. versionadded:: 3.12
+
+
+.. c:function:: void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)
+
+ Set the tracing function to *func*. This is similar to
+ :c:func:`PyEval_SetProfile`, except the tracing function does receive line-number
+ events and per-opcode events, but does not receive any event related to C function
+ objects being called. Any trace function registered using :c:func:`PyEval_SetTrace`
+ will not receive :c:data:`PyTrace_C_CALL`, :c:data:`PyTrace_C_EXCEPTION` or
+ :c:data:`PyTrace_C_RETURN` as a value for the *what* parameter.
+
+ See also the :func:`sys.settrace` function.
+
+ The caller must have an :term:`attached thread state`.
+
+
+.. c:function:: void PyEval_SetTraceAllThreads(Py_tracefunc func, PyObject *obj)
+
+ Like :c:func:`PyEval_SetTrace` but sets the tracing function in all running threads
+ belonging to the current interpreter instead of the setting it only on the current thread.
+
+ The caller must have an :term:`attached thread state`.
+
+ As :c:func:`PyEval_SetTrace`, this function ignores any exceptions raised while
+ setting the trace functions in all threads.
+
+.. versionadded:: 3.12
+
+
+Reference tracing
+=================
+
+.. versionadded:: 3.13
+
+
+.. c:type:: int (*PyRefTracer)(PyObject *, int event, void* data)
+
+ The type of the trace function registered using :c:func:`PyRefTracer_SetTracer`.
+ The first parameter is a Python object that has been just created (when **event**
+ is set to :c:data:`PyRefTracer_CREATE`) or about to be destroyed (when **event**
+ is set to :c:data:`PyRefTracer_DESTROY`). The **data** argument is the opaque pointer
+ that was provided when :c:func:`PyRefTracer_SetTracer` was called.
+
+ If a new tracing function is registered replacing the current one, a call to the
+ trace function will be made with the object set to **NULL** and **event** set to
+ :c:data:`PyRefTracer_TRACKER_REMOVED`. This will happen just before the new
+ function is registered.
+
+.. versionadded:: 3.13
+
+
+.. c:var:: int PyRefTracer_CREATE
+
+ The value for the *event* parameter to :c:type:`PyRefTracer` functions when a Python
+ object has been created.
+
+
+.. c:var:: int PyRefTracer_DESTROY
+
+ The value for the *event* parameter to :c:type:`PyRefTracer` functions when a Python
+ object has been destroyed.
+
+
+.. c:var:: int PyRefTracer_TRACKER_REMOVED
+
+ The value for the *event* parameter to :c:type:`PyRefTracer` functions when the
+ current tracer is about to be replaced by a new one.
+
+ .. versionadded:: 3.14
+
+
+.. c:function:: int PyRefTracer_SetTracer(PyRefTracer tracer, void *data)
+
+ Register a reference tracer function. The function will be called when a new
+ Python object has been created or when an object is going to be destroyed. If
+ **data** is provided it must be an opaque pointer that will be provided when
+ the tracer function is called. Return ``0`` on success. Set an exception and
+ return ``-1`` on error.
+
+ Note that tracer functions **must not** create Python objects inside or
+ otherwise the call will be re-entrant. The tracer also **must not** clear
+ any existing exception or set an exception. A :term:`thread state` will be active
+ every time the tracer function is called.
+
+ There must be an :term:`attached thread state` when calling this function.
+
+ If another tracer function was already registered, the old function will be
+ called with **event** set to :c:data:`PyRefTracer_TRACKER_REMOVED` just before
+ the new function is registered.
+
+.. versionadded:: 3.13
+
+
+.. c:function:: PyRefTracer PyRefTracer_GetTracer(void** data)
+
+ Get the registered reference tracer function and the value of the opaque data
+ pointer that was registered when :c:func:`PyRefTracer_SetTracer` was called.
+ If no tracer was registered this function will return NULL and will set the
+ **data** pointer to NULL.
+
+ There must be an :term:`attached thread state` when calling this function.
+
+.. versionadded:: 3.13
diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst
index b4e7cb1d77e..a3e164011a8 100644
--- a/Doc/c-api/structures.rst
+++ b/Doc/c-api/structures.rst
@@ -408,7 +408,7 @@ There are these calling conventions:
These two constants are not used to indicate the calling convention but the
-binding when use with methods of classes. These may not be used for functions
+binding when used with methods of classes. These may not be used for functions
defined for modules. At most one of these flags may be set for any given
method.
diff --git a/Doc/c-api/subinterpreters.rst b/Doc/c-api/subinterpreters.rst
new file mode 100644
index 00000000000..44e3fc96841
--- /dev/null
+++ b/Doc/c-api/subinterpreters.rst
@@ -0,0 +1,470 @@
+.. highlight:: c
+
+.. _sub-interpreter-support:
+
+Multiple interpreters in a Python process
+=========================================
+
+While in most uses, you will only embed a single Python interpreter, there
+are cases where you need to create several independent interpreters in the
+same process and perhaps even in the same thread. Sub-interpreters allow
+you to do that.
+
+The "main" interpreter is the first one created when the runtime initializes.
+It is usually the only Python interpreter in a process. Unlike sub-interpreters,
+the main interpreter has unique process-global responsibilities like signal
+handling. It is also responsible for execution during runtime initialization and
+is usually the active interpreter during runtime finalization. The
+:c:func:`PyInterpreterState_Main` function returns a pointer to its state.
+
+You can switch between sub-interpreters using the :c:func:`PyThreadState_Swap`
+function. You can create and destroy them using the following functions:
+
+
+.. c:type:: PyInterpreterConfig
+
+ Structure containing most parameters to configure a sub-interpreter.
+ Its values are used only in :c:func:`Py_NewInterpreterFromConfig` and
+ never modified by the runtime.
+
+ .. versionadded:: 3.12
+
+ Structure fields:
+
+ .. c:member:: int use_main_obmalloc
+
+ If this is ``0`` then the sub-interpreter will use its own
+ "object" allocator state.
+ Otherwise it will use (share) the main interpreter's.
+
+ If this is ``0`` then
+ :c:member:`~PyInterpreterConfig.check_multi_interp_extensions`
+ must be ``1`` (non-zero).
+ If this is ``1`` then :c:member:`~PyInterpreterConfig.gil`
+ must not be :c:macro:`PyInterpreterConfig_OWN_GIL`.
+
+ .. c:member:: int allow_fork
+
+ If this is ``0`` then the runtime will not support forking the
+ process in any thread where the sub-interpreter is currently active.
+ Otherwise fork is unrestricted.
+
+ Note that the :mod:`subprocess` module still works
+ when fork is disallowed.
+
+ .. c:member:: int allow_exec
+
+ If this is ``0`` then the runtime will not support replacing the
+ current process via exec (e.g. :func:`os.execv`) in any thread
+ where the sub-interpreter is currently active.
+ Otherwise exec is unrestricted.
+
+ Note that the :mod:`subprocess` module still works
+ when exec is disallowed.
+
+ .. c:member:: int allow_threads
+
+ If this is ``0`` then the sub-interpreter's :mod:`threading` module
+ won't create threads.
+ Otherwise threads are allowed.
+
+ .. c:member:: int allow_daemon_threads
+
+ If this is ``0`` then the sub-interpreter's :mod:`threading` module
+ won't create daemon threads.
+ Otherwise daemon threads are allowed (as long as
+ :c:member:`~PyInterpreterConfig.allow_threads` is non-zero).
+
+ .. c:member:: int check_multi_interp_extensions
+
+ If this is ``0`` then all extension modules may be imported,
+ including legacy (single-phase init) modules,
+ in any thread where the sub-interpreter is currently active.
+ Otherwise only multi-phase init extension modules
+ (see :pep:`489`) may be imported.
+ (Also see :c:macro:`Py_mod_multiple_interpreters`.)
+
+ This must be ``1`` (non-zero) if
+ :c:member:`~PyInterpreterConfig.use_main_obmalloc` is ``0``.
+
+ .. c:member:: int gil
+
+ This determines the operation of the GIL for the sub-interpreter.
+ It may be one of the following:
+
+ .. c:namespace:: NULL
+
+ .. c:macro:: PyInterpreterConfig_DEFAULT_GIL
+
+ Use the default selection (:c:macro:`PyInterpreterConfig_SHARED_GIL`).
+
+ .. c:macro:: PyInterpreterConfig_SHARED_GIL
+
+ Use (share) the main interpreter's GIL.
+
+ .. c:macro:: PyInterpreterConfig_OWN_GIL
+
+ Use the sub-interpreter's own GIL.
+
+ If this is :c:macro:`PyInterpreterConfig_OWN_GIL` then
+ :c:member:`PyInterpreterConfig.use_main_obmalloc` must be ``0``.
+
+
+.. c:function:: PyStatus Py_NewInterpreterFromConfig(PyThreadState **tstate_p, const PyInterpreterConfig *config)
+
+ .. index::
+ pair: module; builtins
+ pair: module; __main__
+ pair: module; sys
+ single: stdout (in module sys)
+ single: stderr (in module sys)
+ single: stdin (in module sys)
+
+ Create a new sub-interpreter. This is an (almost) totally separate environment
+ for the execution of Python code. In particular, the new interpreter has
+ separate, independent versions of all imported modules, including the
+ fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. The
+ table of loaded modules (``sys.modules``) and the module search path
+ (``sys.path``) are also separate. The new environment has no ``sys.argv``
+ variable. It has new standard I/O stream file objects ``sys.stdin``,
+ ``sys.stdout`` and ``sys.stderr`` (however these refer to the same underlying
+ file descriptors).
+
+ The given *config* controls the options with which the interpreter
+ is initialized.
+
+ Upon success, *tstate_p* will be set to the first :term:`thread state`
+ created in the new sub-interpreter. This thread state is
+ :term:`attached <attached thread state>`.
+ Note that no actual thread is created; see the discussion of thread states
+ below. If creation of the new interpreter is unsuccessful,
+ *tstate_p* is set to ``NULL``;
+ no exception is set since the exception state is stored in the
+ :term:`attached thread state`, which might not exist.
+
+ Like all other Python/C API functions, an :term:`attached thread state`
+ must be present before calling this function, but it might be detached upon
+ returning. On success, the returned thread state will be :term:`attached <attached thread state>`.
+ If the sub-interpreter is created with its own :term:`GIL` then the
+ :term:`attached thread state` of the calling interpreter will be detached.
+ When the function returns, the new interpreter's :term:`thread state`
+ will be :term:`attached <attached thread state>` to the current thread and
+ the previous interpreter's :term:`attached thread state` will remain detached.
+
+ .. versionadded:: 3.12
+
+ Sub-interpreters are most effective when isolated from each other,
+ with certain functionality restricted::
+
+ PyInterpreterConfig config = {
+ .use_main_obmalloc = 0,
+ .allow_fork = 0,
+ .allow_exec = 0,
+ .allow_threads = 1,
+ .allow_daemon_threads = 0,
+ .check_multi_interp_extensions = 1,
+ .gil = PyInterpreterConfig_OWN_GIL,
+ };
+ PyThreadState *tstate = NULL;
+ PyStatus status = Py_NewInterpreterFromConfig(&tstate, &config);
+ if (PyStatus_Exception(status)) {
+ Py_ExitStatusException(status);
+ }
+
+ Note that the config is used only briefly and does not get modified.
+ During initialization the config's values are converted into various
+ :c:type:`PyInterpreterState` values. A read-only copy of the config
+ may be stored internally on the :c:type:`PyInterpreterState`.
+
+ .. index::
+ single: Py_FinalizeEx (C function)
+ single: Py_Initialize (C function)
+
+ Extension modules are shared between (sub-)interpreters as follows:
+
+ * For modules using multi-phase initialization,
+ e.g. :c:func:`PyModule_FromDefAndSpec`, a separate module object is
+ created and initialized for each interpreter.
+ Only C-level static and global variables are shared between these
+ module objects.
+
+ * For modules using legacy
+ :ref:`single-phase initialization <single-phase-initialization>`,
+ e.g. :c:func:`PyModule_Create`, the first time a particular extension
+ is imported, it is initialized normally, and a (shallow) copy of its
+ module's dictionary is squirreled away.
+ When the same extension is imported by another (sub-)interpreter, a new
+ module is initialized and filled with the contents of this copy; the
+ extension's ``init`` function is not called.
+ Objects in the module's dictionary thus end up shared across
+ (sub-)interpreters, which might cause unwanted behavior (see
+ `Bugs and caveats`_ below).
+
+ Note that this is different from what happens when an extension is
+ imported after the interpreter has been completely re-initialized by
+ calling :c:func:`Py_FinalizeEx` and :c:func:`Py_Initialize`; in that
+ case, the extension's ``initmodule`` function *is* called again.
+ As with multi-phase initialization, this means that only C-level static
+ and global variables are shared between these modules.
+
+ .. index:: single: close (in module os)
+
+
+.. c:function:: PyThreadState* Py_NewInterpreter(void)
+
+ .. index::
+ pair: module; builtins
+ pair: module; __main__
+ pair: module; sys
+ single: stdout (in module sys)
+ single: stderr (in module sys)
+ single: stdin (in module sys)
+
+ Create a new sub-interpreter. This is essentially just a wrapper
+ around :c:func:`Py_NewInterpreterFromConfig` with a config that
+ preserves the existing behavior. The result is an unisolated
+ sub-interpreter that shares the main interpreter's GIL, allows
+ fork/exec, allows daemon threads, and allows single-phase init
+ modules.
+
+
+.. c:function:: void Py_EndInterpreter(PyThreadState *tstate)
+
+ .. index:: single: Py_FinalizeEx (C function)
+
+ Destroy the (sub-)interpreter represented by the given :term:`thread state`.
+ The given thread state must be :term:`attached <attached thread state>`.
+ When the call returns, there will be no :term:`attached thread state`.
+ All thread states associated with this interpreter are destroyed.
+
+ :c:func:`Py_FinalizeEx` will destroy all sub-interpreters that
+ haven't been explicitly destroyed at that point.
+
+
+.. _per-interpreter-gil:
+
+A per-interpreter GIL
+---------------------
+
+.. versionadded:: 3.12
+
+Using :c:func:`Py_NewInterpreterFromConfig` you can create
+a sub-interpreter that is completely isolated from other interpreters,
+including having its own GIL. The most important benefit of this
+isolation is that such an interpreter can execute Python code without
+being blocked by other interpreters or blocking any others. Thus a
+single Python process can truly take advantage of multiple CPU cores
+when running Python code. The isolation also encourages a different
+approach to concurrency than that of just using threads.
+(See :pep:`554` and :pep:`684`.)
+
+Using an isolated interpreter requires vigilance in preserving that
+isolation. That especially means not sharing any objects or mutable
+state without guarantees about thread-safety. Even objects that are
+otherwise immutable (e.g. ``None``, ``(1, 5)``) can't normally be shared
+because of the refcount. One simple but less-efficient approach around
+this is to use a global lock around all use of some state (or object).
+Alternately, effectively immutable objects (like integers or strings)
+can be made safe in spite of their refcounts by making them :term:`immortal`.
+In fact, this has been done for the builtin singletons, small integers,
+and a number of other builtin objects.
+
+If you preserve isolation then you will have access to proper multi-core
+computing without the complications that come with free-threading.
+Failure to preserve isolation will expose you to the full consequences
+of free-threading, including races and hard-to-debug crashes.
+
+Aside from that, one of the main challenges of using multiple isolated
+interpreters is how to communicate between them safely (not break
+isolation) and efficiently. The runtime and stdlib do not provide
+any standard approach to this yet. A future stdlib module would help
+mitigate the effort of preserving isolation and expose effective tools
+for communicating (and sharing) data between interpreters.
+
+
+Bugs and caveats
+----------------
+
+Because sub-interpreters (and the main interpreter) are part of the same
+process, the insulation between them isn't perfect --- for example, using
+low-level file operations like :func:`os.close` they can
+(accidentally or maliciously) affect each other's open files. Because of the
+way extensions are shared between (sub-)interpreters, some extensions may not
+work properly; this is especially likely when using single-phase initialization
+or (static) global variables.
+It is possible to insert objects created in one sub-interpreter into
+a namespace of another (sub-)interpreter; this should be avoided if possible.
+
+Special care should be taken to avoid sharing user-defined functions,
+methods, instances or classes between sub-interpreters, since import
+operations executed by such objects may affect the wrong (sub-)interpreter's
+dictionary of loaded modules. It is equally important to avoid sharing
+objects from which the above are reachable.
+
+Also note that combining this functionality with ``PyGILState_*`` APIs
+is delicate, because these APIs assume a bijection between Python thread states
+and OS-level threads, an assumption broken by the presence of sub-interpreters.
+It is highly recommended that you don't switch sub-interpreters between a pair
+of matching :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` calls.
+Furthermore, extensions (such as :mod:`ctypes`) using these APIs to allow calling
+of Python code from non-Python created threads will probably be broken when using
+sub-interpreters.
+
+
+High-level APIs
+---------------
+
+.. c:type:: PyInterpreterState
+
+ This data structure represents the state shared by a number of cooperating
+ threads. Threads belonging to the same interpreter share their module
+ administration and a few other internal items. There are no public members in
+ this structure.
+
+ Threads belonging to different interpreters initially share nothing, except
+ process state like available memory, open file descriptors and such. The global
+ interpreter lock is also shared by all threads, regardless of to which
+ interpreter they belong.
+
+ .. versionchanged:: 3.12
+
+ :pep:`684` introduced the possibility
+ of a :ref:`per-interpreter GIL <per-interpreter-gil>`.
+ See :c:func:`Py_NewInterpreterFromConfig`.
+
+
+.. c:function:: PyInterpreterState* PyInterpreterState_Get(void)
+
+ Get the current interpreter.
+
+ Issue a fatal error if there is no :term:`attached thread state`.
+ It cannot return NULL.
+
+ .. versionadded:: 3.9
+
+
+.. c:function:: int64_t PyInterpreterState_GetID(PyInterpreterState *interp)
+
+ Return the interpreter's unique ID. If there was any error in doing
+ so then ``-1`` is returned and an error is set.
+
+ The caller must have an :term:`attached thread state`.
+
+ .. versionadded:: 3.7
+
+
+.. c:function:: PyObject* PyInterpreterState_GetDict(PyInterpreterState *interp)
+
+ Return a dictionary in which interpreter-specific data may be stored.
+ If this function returns ``NULL`` then no exception has been raised and
+ the caller should assume no interpreter-specific dict is available.
+
+ This is not a replacement for :c:func:`PyModule_GetState()`, which
+ extensions should use to store interpreter-specific state information.
+
+ The returned dictionary is borrowed from the interpreter and is valid until
+ interpreter shutdown.
+
+ .. versionadded:: 3.8
+
+
+.. c:type:: PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, _PyInterpreterFrame *frame, int throwflag)
+
+ Type of a frame evaluation function.
+
+ The *throwflag* parameter is used by the ``throw()`` method of generators:
+ if non-zero, handle the current exception.
+
+ .. versionchanged:: 3.9
+ The function now takes a *tstate* parameter.
+
+ .. versionchanged:: 3.11
+ The *frame* parameter changed from ``PyFrameObject*`` to ``_PyInterpreterFrame*``.
+
+
+.. c:function:: _PyFrameEvalFunction _PyInterpreterState_GetEvalFrameFunc(PyInterpreterState *interp)
+
+ Get the frame evaluation function.
+
+ See the :pep:`523` "Adding a frame evaluation API to CPython".
+
+ .. versionadded:: 3.9
+
+
+.. c:function:: void _PyInterpreterState_SetEvalFrameFunc(PyInterpreterState *interp, _PyFrameEvalFunction eval_frame)
+
+ Set the frame evaluation function.
+
+ See the :pep:`523` "Adding a frame evaluation API to CPython".
+
+ .. versionadded:: 3.9
+
+
+Low-level APIs
+--------------
+
+All of the following functions must be called after :c:func:`Py_Initialize`.
+
+.. versionchanged:: 3.7
+ :c:func:`Py_Initialize()` now initializes the :term:`GIL`
+ and sets an :term:`attached thread state`.
+
+
+.. c:function:: PyInterpreterState* PyInterpreterState_New()
+
+ Create a new interpreter state object. An :term:`attached thread state` is not needed,
+ but may optionally exist if it is necessary to serialize calls to this
+ function.
+
+ .. audit-event:: cpython.PyInterpreterState_New "" c.PyInterpreterState_New
+
+
+.. c:function:: void PyInterpreterState_Clear(PyInterpreterState *interp)
+
+ Reset all information in an interpreter state object. There must be
+ an :term:`attached thread state` for the interpreter.
+
+ .. audit-event:: cpython.PyInterpreterState_Clear "" c.PyInterpreterState_Clear
+
+
+.. c:function:: void PyInterpreterState_Delete(PyInterpreterState *interp)
+
+ Destroy an interpreter state object. There **should not** be an
+ :term:`attached thread state` for the target interpreter. The interpreter
+ state must have been reset with a previous call to :c:func:`PyInterpreterState_Clear`.
+
+
+.. _advanced-debugging:
+
+Advanced debugger support
+-------------------------
+
+These functions are only intended to be used by advanced debugging tools.
+
+
+.. c:function:: PyInterpreterState* PyInterpreterState_Head()
+
+ Return the interpreter state object at the head of the list of all such objects.
+
+
+.. c:function:: PyInterpreterState* PyInterpreterState_Main()
+
+ Return the main interpreter state object.
+
+
+.. c:function:: PyInterpreterState* PyInterpreterState_Next(PyInterpreterState *interp)
+
+ Return the next interpreter state object after *interp* from the list of all
+ such objects.
+
+
+.. c:function:: PyThreadState * PyInterpreterState_ThreadHead(PyInterpreterState *interp)
+
+ Return the pointer to the first :c:type:`PyThreadState` object in the list of
+ threads associated with the interpreter *interp*.
+
+
+.. c:function:: PyThreadState* PyThreadState_Next(PyThreadState *tstate)
+
+ Return the next thread state object after *tstate* from the list of all such
+ objects belonging to the same :c:type:`PyInterpreterState` object.
diff --git a/Doc/c-api/synchronization.rst b/Doc/c-api/synchronization.rst
new file mode 100644
index 00000000000..954ac55e538
--- /dev/null
+++ b/Doc/c-api/synchronization.rst
@@ -0,0 +1,301 @@
+.. highlight:: c
+
+.. _synchronization:
+
+Synchronization primitives
+==========================
+
+The C-API provides a basic mutual exclusion lock.
+
+.. c:type:: PyMutex
+
+ A mutual exclusion lock. The :c:type:`!PyMutex` should be initialized to
+ zero to represent the unlocked state. For example::
+
+ PyMutex mutex = {0};
+
+ Instances of :c:type:`!PyMutex` should not be copied or moved. Both the
+ contents and address of a :c:type:`!PyMutex` are meaningful, and it must
+ remain at a fixed, writable location in memory.
+
+ .. note::
+
+ A :c:type:`!PyMutex` currently occupies one byte, but the size should be
+ considered unstable. The size may change in future Python releases
+ without a deprecation period.
+
+ .. versionadded:: 3.13
+
+.. c:function:: void PyMutex_Lock(PyMutex *m)
+
+ Lock mutex *m*. If another thread has already locked it, the calling
+ thread will block until the mutex is unlocked. While blocked, the thread
+ will temporarily detach the :term:`thread state <attached thread state>` if one exists.
+
+ .. versionadded:: 3.13
+
+.. c:function:: void PyMutex_Unlock(PyMutex *m)
+
+ Unlock mutex *m*. The mutex must be locked --- otherwise, the function will
+ issue a fatal error.
+
+ .. versionadded:: 3.13
+
+.. c:function:: int PyMutex_IsLocked(PyMutex *m)
+
+ Returns non-zero if the mutex *m* is currently locked, zero otherwise.
+
+ .. note::
+
+ This function is intended for use in assertions and debugging only and
+ should not be used to make concurrency control decisions, as the lock
+ state may change immediately after the check.
+
+ .. versionadded:: 3.14
+
+.. _python-critical-section-api:
+
+Python critical section API
+---------------------------
+
+The critical section API provides a deadlock avoidance layer on top of
+per-object locks for :term:`free-threaded <free threading>` CPython. They are
+intended to replace reliance on the :term:`global interpreter lock`, and are
+no-ops in versions of Python with the global interpreter lock.
+
+Critical sections are intended to be used for custom types implemented
+in C-API extensions. They should generally not be used with built-in types like
+:class:`list` and :class:`dict` because their public C-APIs
+already use critical sections internally, with the notable
+exception of :c:func:`PyDict_Next`, which requires critical section
+to be acquired externally.
+
+Critical sections avoid deadlocks by implicitly suspending active critical
+sections, hence, they do not provide exclusive access such as provided by
+traditional locks like :c:type:`PyMutex`. When a critical section is started,
+the per-object lock for the object is acquired. If the code executed inside the
+critical section calls C-API functions then it can suspend the critical section thereby
+releasing the per-object lock, so other threads can acquire the per-object lock
+for the same object.
+
+Variants that accept :c:type:`PyMutex` pointers rather than Python objects are also
+available. Use these variants to start a critical section in a situation where
+there is no :c:type:`PyObject` -- for example, when working with a C type that
+does not extend or wrap :c:type:`PyObject` but still needs to call into the C
+API in a manner that might lead to deadlocks.
+
+The functions and structs used by the macros are exposed for cases
+where C macros are not available. They should only be used as in the
+given macro expansions. Note that the sizes and contents of the structures may
+change in future Python versions.
+
+.. note::
+
+ Operations that need to lock two objects at once must use
+ :c:macro:`Py_BEGIN_CRITICAL_SECTION2`. You *cannot* use nested critical
+ sections to lock more than one object at once, because the inner critical
+ section may suspend the outer critical sections. This API does not provide
+ a way to lock more than two objects at once.
+
+Example usage::
+
+ static PyObject *
+ set_field(MyObject *self, PyObject *value)
+ {
+ Py_BEGIN_CRITICAL_SECTION(self);
+ Py_SETREF(self->field, Py_XNewRef(value));
+ Py_END_CRITICAL_SECTION();
+ Py_RETURN_NONE;
+ }
+
+In the above example, :c:macro:`Py_SETREF` calls :c:macro:`Py_DECREF`, which
+can call arbitrary code through an object's deallocation function. The critical
+section API avoids potential deadlocks due to reentrancy and lock ordering
+by allowing the runtime to temporarily suspend the critical section if the
+code triggered by the finalizer blocks and calls :c:func:`PyEval_SaveThread`.
+
+.. c:macro:: Py_BEGIN_CRITICAL_SECTION(op)
+
+ Acquires the per-object lock for the object *op* and begins a
+ critical section.
+
+ In the free-threaded build, this macro expands to::
+
+ {
+ PyCriticalSection _py_cs;
+ PyCriticalSection_Begin(&_py_cs, (PyObject*)(op))
+
+ In the default build, this macro expands to ``{``.
+
+ .. versionadded:: 3.13
+
+.. c:macro:: Py_BEGIN_CRITICAL_SECTION_MUTEX(m)
+
+ Locks the mutex *m* and begins a critical section.
+
+ In the free-threaded build, this macro expands to::
+
+ {
+ PyCriticalSection _py_cs;
+ PyCriticalSection_BeginMutex(&_py_cs, m)
+
+ Note that unlike :c:macro:`Py_BEGIN_CRITICAL_SECTION`, there is no cast for
+ the argument of the macro - it must be a :c:type:`PyMutex` pointer.
+
+ On the default build, this macro expands to ``{``.
+
+ .. versionadded:: 3.14
+
+.. c:macro:: Py_END_CRITICAL_SECTION()
+
+ Ends the critical section and releases the per-object lock.
+
+ In the free-threaded build, this macro expands to::
+
+ PyCriticalSection_End(&_py_cs);
+ }
+
+ In the default build, this macro expands to ``}``.
+
+ .. versionadded:: 3.13
+
+.. c:macro:: Py_BEGIN_CRITICAL_SECTION2(a, b)
+
+ Acquires the per-object locks for the objects *a* and *b* and begins a
+ critical section. The locks are acquired in a consistent order (lowest
+ address first) to avoid lock ordering deadlocks.
+
+ In the free-threaded build, this macro expands to::
+
+ {
+ PyCriticalSection2 _py_cs2;
+ PyCriticalSection2_Begin(&_py_cs2, (PyObject*)(a), (PyObject*)(b))
+
+ In the default build, this macro expands to ``{``.
+
+ .. versionadded:: 3.13
+
+.. c:macro:: Py_BEGIN_CRITICAL_SECTION2_MUTEX(m1, m2)
+
+ Locks the mutexes *m1* and *m2* and begins a critical section.
+
+ In the free-threaded build, this macro expands to::
+
+ {
+ PyCriticalSection2 _py_cs2;
+ PyCriticalSection2_BeginMutex(&_py_cs2, m1, m2)
+
+ Note that unlike :c:macro:`Py_BEGIN_CRITICAL_SECTION2`, there is no cast for
+ the arguments of the macro - they must be :c:type:`PyMutex` pointers.
+
+ On the default build, this macro expands to ``{``.
+
+ .. versionadded:: 3.14
+
+.. c:macro:: Py_END_CRITICAL_SECTION2()
+
+ Ends the critical section and releases the per-object locks.
+
+ In the free-threaded build, this macro expands to::
+
+ PyCriticalSection2_End(&_py_cs2);
+ }
+
+ In the default build, this macro expands to ``}``.
+
+ .. versionadded:: 3.13
+
+
+Legacy locking APIs
+-------------------
+
+These APIs are obsolete since Python 3.13 with the introduction of
+:c:type:`PyMutex`.
+
+
+.. c:type:: PyThread_type_lock
+
+ A pointer to a mutual exclusion lock.
+
+
+.. c:type:: PyLockStatus
+
+ The result of acquiring a lock with a timeout.
+
+ .. c:namespace:: NULL
+
+ .. c:enumerator:: PY_LOCK_FAILURE
+
+ Failed to acquire the lock.
+
+ .. c:enumerator:: PY_LOCK_ACQUIRED
+
+ The lock was successfully acquired.
+
+ .. c:enumerator:: PY_LOCK_INTR
+
+ The lock was interrupted by a signal.
+
+
+.. c:function:: PyThread_type_lock PyThread_allocate_lock(void)
+
+ Allocate a new lock.
+
+ On success, this function returns a lock; on failure, this
+ function returns ``0`` without an exception set.
+
+ The caller does not need to hold an :term:`attached thread state`.
+
+
+.. c:function:: void PyThread_free_lock(PyThread_type_lock lock)
+
+ Destroy *lock*. The lock should not be held by any thread when calling
+ this.
+
+ The caller does not need to hold an :term:`attached thread state`.
+
+
+.. c:function:: PyLockStatus PyThread_acquire_lock_timed(PyThread_type_lock lock, long long microseconds, int intr_flag)
+
+ Acquire *lock* with a timeout.
+
+ This will wait for *microseconds* microseconds to acquire the lock. If the
+ timeout expires, this function returns :c:enumerator:`PY_LOCK_FAILURE`.
+ If *microseconds* is ``-1``, this will wait indefinitely until the lock has
+ been released.
+
+ If *intr_flag* is ``1``, acquiring the lock may be interrupted by a signal,
+ in which case this function returns :c:enumerator:`PY_LOCK_INTR`. Upon
+ interruption, it's generally expected that the caller makes a call to
+ :c:func:`Py_MakePendingCalls` to propagate an exception to Python code.
+
+ If the lock is successfully acquired, this function returns
+ :c:enumerator:`PY_LOCK_ACQUIRED`.
+
+ The caller does not need to hold an :term:`attached thread state`.
+
+
+.. c:function:: int PyThread_acquire_lock(PyThread_type_lock lock, int waitflag)
+
+ Acquire *lock*.
+
+ If *waitflag* is ``1`` and another thread currently holds the lock, this
+ function will wait until the lock can be acquired and will always return
+ ``1``.
+
+ If *waitflag* is ``0`` and another thread holds the lock, this function will
+ not wait and instead return ``0``. If the lock is not held by any other
+ thread, then this function will acquire it and return ``1``.
+
+ Unlike :c:func:`PyThread_acquire_lock_timed`, acquiring the lock cannot be
+ interrupted by a signal.
+
+ The caller does not need to hold an :term:`attached thread state`.
+
+
+.. c:function:: int PyThread_release_lock(PyThread_type_lock lock)
+
+ Release *lock*. If *lock* is not held, then this function issues a
+ fatal error.
+
+ The caller does not need to hold an :term:`attached thread state`.
diff --git a/Doc/c-api/threads.rst b/Doc/c-api/threads.rst
new file mode 100644
index 00000000000..badbdee564d
--- /dev/null
+++ b/Doc/c-api/threads.rst
@@ -0,0 +1,867 @@
+.. highlight:: c
+
+.. _threads:
+
+Thread states and the global interpreter lock
+=============================================
+
+.. index::
+ single: global interpreter lock
+ single: interpreter lock
+ single: lock, interpreter
+
+Unless on a :term:`free-threaded build` of :term:`CPython`,
+the Python interpreter is generally not thread-safe. In order to support
+multi-threaded Python programs, there's a global lock, called the :term:`global
+interpreter lock` or :term:`GIL`, that must be held by a thread before
+accessing Python objects. Without the lock, even the simplest operations
+could cause problems in a multi-threaded program: for example, when
+two threads simultaneously increment the reference count of the same object, the
+reference count could end up being incremented only once instead of twice.
+
+As such, only a thread that holds the GIL may operate on Python objects or
+invoke Python's C API.
+
+.. index:: single: setswitchinterval (in module sys)
+
+In order to emulate concurrency, the interpreter regularly tries to switch
+threads between bytecode instructions (see :func:`sys.setswitchinterval`).
+This is why locks are also necessary for thread-safety in pure-Python code.
+
+Additionally, the global interpreter lock is released around blocking I/O
+operations, such as reading or writing to a file. From the C API, this is done
+by :ref:`detaching the thread state <detaching-thread-state>`.
+
+
+.. index::
+ single: PyThreadState (C type)
+
+The Python interpreter keeps some thread-local information inside
+a data structure called :c:type:`PyThreadState`, known as a :term:`thread state`.
+Each thread has a thread-local pointer to a :c:type:`PyThreadState`; a thread state
+referenced by this pointer is considered to be :term:`attached <attached thread state>`.
+
+A thread can only have one :term:`attached thread state` at a time. An attached
+thread state is typically analogous with holding the GIL, except on
+free-threaded builds. On builds with the GIL enabled, attaching a thread state
+will block until the GIL can be acquired. However, even on builds with the GIL
+disabled, it is still required to have an attached thread state, as the interpreter
+needs to keep track of which threads may access Python objects.
+
+.. note::
+
+ Even on the free-threaded build, attaching a thread state may block, as the
+ GIL can be re-enabled or threads might be temporarily suspended (such as during
+ a garbage collection).
+
+Generally, there will always be an attached thread state when using Python's
+C API, including during embedding and when implementing methods, so it's uncommon
+to need to set up a thread state on your own. Only in some specific cases, such
+as in a :c:macro:`Py_BEGIN_ALLOW_THREADS` block or in a fresh thread, will the
+thread not have an attached thread state.
+If uncertain, check if :c:func:`PyThreadState_GetUnchecked` returns ``NULL``.
+
+If it turns out that you do need to create a thread state, call :c:func:`PyThreadState_New`
+followed by :c:func:`PyThreadState_Swap`, or use the dangerous
+:c:func:`PyGILState_Ensure` function.
+
+
+.. _detaching-thread-state:
+
+Detaching the thread state from extension code
+----------------------------------------------
+
+Most extension code manipulating the :term:`thread state` has the following simple
+structure::
+
+ Save the thread state in a local variable.
+ ... Do some blocking I/O operation ...
+ Restore the thread state from the local variable.
+
+This is so common that a pair of macros exists to simplify it::
+
+ Py_BEGIN_ALLOW_THREADS
+ ... Do some blocking I/O operation ...
+ Py_END_ALLOW_THREADS
+
+.. index::
+ single: Py_BEGIN_ALLOW_THREADS (C macro)
+ single: Py_END_ALLOW_THREADS (C macro)
+
+The :c:macro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a
+hidden local variable; the :c:macro:`Py_END_ALLOW_THREADS` macro closes the
+block.
+
+The block above expands to the following code::
+
+ PyThreadState *_save;
+
+ _save = PyEval_SaveThread();
+ ... Do some blocking I/O operation ...
+ PyEval_RestoreThread(_save);
+
+.. index::
+ single: PyEval_RestoreThread (C function)
+ single: PyEval_SaveThread (C function)
+
+Here is how these functions work:
+
+The attached thread state implies that the GIL is held for the interpreter.
+To detach it, :c:func:`PyEval_SaveThread` is called and the result is stored
+in a local variable.
+
+By detaching the thread state, the GIL is released, which allows other threads
+to attach to the interpreter and execute while the current thread performs
+blocking I/O. When the I/O operation is complete, the old thread state is
+reattached by calling :c:func:`PyEval_RestoreThread`, which will wait until
+the GIL can be acquired.
+
+.. note::
+ Performing blocking I/O is the most common use case for detaching
+ the thread state, but it is also useful to call it over long-running
+ native code that doesn't need access to Python objects or Python's C API.
+ For example, the standard :mod:`zlib` and :mod:`hashlib` modules detach the
+ :term:`thread state <attached thread state>` when compressing or hashing
+ data.
+
+On a :term:`free-threaded build`, the :term:`GIL` is usually out of the question,
+but **detaching the thread state is still required**, because the interpreter
+periodically needs to block all threads to get a consistent view of Python objects
+without the risk of race conditions.
+For example, CPython currently suspends all threads for a short period of time
+while running the garbage collector.
+
+.. warning::
+
+ Detaching the thread state can lead to unexpected behavior during interpreter
+ finalization. See :ref:`cautions-regarding-runtime-finalization` for more
+ details.
+
+
+APIs
+^^^^
+
+The following macros are normally used without a trailing semicolon; look for
+example usage in the Python source distribution.
+
+.. note::
+
+ These macros are still necessary on the :term:`free-threaded build` to prevent
+ deadlocks.
+
+.. c:macro:: Py_BEGIN_ALLOW_THREADS
+
+ This macro expands to ``{ PyThreadState *_save; _save = PyEval_SaveThread();``.
+ Note that it contains an opening brace; it must be matched with a following
+ :c:macro:`Py_END_ALLOW_THREADS` macro. See above for further discussion of this
+ macro.
+
+
+.. c:macro:: Py_END_ALLOW_THREADS
+
+ This macro expands to ``PyEval_RestoreThread(_save); }``. Note that it contains
+ a closing brace; it must be matched with an earlier
+ :c:macro:`Py_BEGIN_ALLOW_THREADS` macro. See above for further discussion of
+ this macro.
+
+
+.. c:macro:: Py_BLOCK_THREADS
+
+ This macro expands to ``PyEval_RestoreThread(_save);``: it is equivalent to
+ :c:macro:`Py_END_ALLOW_THREADS` without the closing brace.
+
+
+.. c:macro:: Py_UNBLOCK_THREADS
+
+ This macro expands to ``_save = PyEval_SaveThread();``: it is equivalent to
+ :c:macro:`Py_BEGIN_ALLOW_THREADS` without the opening brace and variable
+ declaration.
+
+
+Non-Python created threads
+--------------------------
+
+When threads are created using the dedicated Python APIs (such as the
+:mod:`threading` module), a thread state is automatically associated with them,
+However, when a thread is created from native code (for example, by a
+third-party library with its own thread management), it doesn't hold an
+attached thread state.
+
+If you need to call Python code from these threads (often this will be part
+of a callback API provided by the aforementioned third-party library),
+you must first register these threads with the interpreter by
+creating a new thread state and attaching it.
+
+The most robust way to do this is through :c:func:`PyThreadState_New` followed
+by :c:func:`PyThreadState_Swap`.
+
+.. note::
+ ``PyThreadState_New`` requires an argument pointing to the desired
+ interpreter; such a pointer can be acquired via a call to
+ :c:func:`PyInterpreterState_Get` from the code where the thread was
+ created.
+
+For example::
+
+ /* The return value of PyInterpreterState_Get() from the
+ function that created this thread. */
+ PyInterpreterState *interp = thread_data->interp;
+
+ /* Create a new thread state for the interpreter. It does not start out
+ attached. */
+ PyThreadState *tstate = PyThreadState_New(interp);
+
+ /* Attach the thread state, which will acquire the GIL. */
+ PyThreadState_Swap(tstate);
+
+ /* Perform Python actions here. */
+ result = CallSomeFunction();
+ /* evaluate result or handle exception */
+
+ /* Destroy the thread state. No Python API allowed beyond this point. */
+ PyThreadState_Clear(tstate);
+ PyThreadState_DeleteCurrent();
+
+.. warning::
+
+ If the interpreter finalized before ``PyThreadState_Swap`` was called, then
+ ``interp`` will be a dangling pointer!
+
+.. _gilstate:
+
+Legacy API
+----------
+
+Another common pattern to call Python code from a non-Python thread is to use
+:c:func:`PyGILState_Ensure` followed by a call to :c:func:`PyGILState_Release`.
+
+These functions do not work well when multiple interpreters exist in the Python
+process. If no Python interpreter has ever been used in the current thread (which
+is common for threads created outside Python), ``PyGILState_Ensure`` will create
+and attach a thread state for the "main" interpreter (the first interpreter in
+the Python process).
+
+Additionally, these functions have thread-safety issues during interpreter
+finalization. Using ``PyGILState_Ensure`` during finalization will likely
+crash the process.
+
+Usage of these functions look like such::
+
+ PyGILState_STATE gstate;
+ gstate = PyGILState_Ensure();
+
+ /* Perform Python actions here. */
+ result = CallSomeFunction();
+ /* evaluate result or handle exception */
+
+ /* Release the thread. No Python API allowed beyond this point. */
+ PyGILState_Release(gstate);
+
+
+.. _fork-and-threads:
+
+Cautions about fork()
+---------------------
+
+Another important thing to note about threads is their behaviour in the face
+of the C :c:func:`fork` call. On most systems with :c:func:`fork`, after a
+process forks only the thread that issued the fork will exist. This has a
+concrete impact both on how locks must be handled and on all stored state
+in CPython's runtime.
+
+The fact that only the "current" thread remains
+means any locks held by other threads will never be released. Python solves
+this for :func:`os.fork` by acquiring the locks it uses internally before
+the fork, and releasing them afterwards. In addition, it resets any
+:ref:`lock-objects` in the child. When extending or embedding Python, there
+is no way to inform Python of additional (non-Python) locks that need to be
+acquired before or reset after a fork. OS facilities such as
+:c:func:`!pthread_atfork` would need to be used to accomplish the same thing.
+Additionally, when extending or embedding Python, calling :c:func:`fork`
+directly rather than through :func:`os.fork` (and returning to or calling
+into Python) may result in a deadlock by one of Python's internal locks
+being held by a thread that is defunct after the fork.
+:c:func:`PyOS_AfterFork_Child` tries to reset the necessary locks, but is not
+always able to.
+
+The fact that all other threads go away also means that CPython's
+runtime state there must be cleaned up properly, which :func:`os.fork`
+does. This means finalizing all other :c:type:`PyThreadState` objects
+belonging to the current interpreter and all other
+:c:type:`PyInterpreterState` objects. Due to this and the special
+nature of the :ref:`"main" interpreter <sub-interpreter-support>`,
+:c:func:`fork` should only be called in that interpreter's "main"
+thread, where the CPython global runtime was originally initialized.
+The only exception is if :c:func:`exec` will be called immediately
+after.
+
+
+High-level APIs
+---------------
+
+These are the most commonly used types and functions when writing multi-threaded
+C extensions.
+
+
+.. c:type:: PyThreadState
+
+ This data structure represents the state of a single thread. The only public
+ data member is:
+
+ .. c:member:: PyInterpreterState *interp
+
+ This thread's interpreter state.
+
+
+.. c:function:: void PyEval_InitThreads()
+
+ .. index::
+ single: PyEval_AcquireThread()
+ single: PyEval_ReleaseThread()
+ single: PyEval_SaveThread()
+ single: PyEval_RestoreThread()
+
+ Deprecated function which does nothing.
+
+ In Python 3.6 and older, this function created the GIL if it didn't exist.
+
+ .. versionchanged:: 3.9
+ The function now does nothing.
+
+ .. versionchanged:: 3.7
+ This function is now called by :c:func:`Py_Initialize()`, so you don't
+ have to call it yourself anymore.
+
+ .. versionchanged:: 3.2
+ This function cannot be called before :c:func:`Py_Initialize()` anymore.
+
+ .. deprecated:: 3.9
+
+ .. index:: pair: module; _thread
+
+
+.. c:function:: PyThreadState* PyEval_SaveThread()
+
+ Detach the :term:`attached thread state` and return it.
+ The thread will have no :term:`thread state` upon returning.
+
+
+.. c:function:: void PyEval_RestoreThread(PyThreadState *tstate)
+
+ Set the :term:`attached thread state` to *tstate*.
+ The passed :term:`thread state` **should not** be :term:`attached <attached thread state>`,
+ otherwise deadlock ensues. *tstate* will be attached upon returning.
+
+ .. note::
+ Calling this function from a thread when the runtime is finalizing will
+ hang the thread until the program exits, even if the thread was not
+ created by Python. Refer to
+ :ref:`cautions-regarding-runtime-finalization` for more details.
+
+ .. versionchanged:: 3.14
+ Hangs the current thread, rather than terminating it, if called while the
+ interpreter is finalizing.
+
+.. c:function:: PyThreadState* PyThreadState_Get()
+
+ Return the :term:`attached thread state`. If the thread has no attached
+ thread state, (such as when inside of :c:macro:`Py_BEGIN_ALLOW_THREADS`
+ block), then this issues a fatal error (so that the caller needn't check
+ for ``NULL``).
+
+ See also :c:func:`PyThreadState_GetUnchecked`.
+
+.. c:function:: PyThreadState* PyThreadState_GetUnchecked()
+
+ Similar to :c:func:`PyThreadState_Get`, but don't kill the process with a
+ fatal error if it is NULL. The caller is responsible to check if the result
+ is NULL.
+
+ .. versionadded:: 3.13
+ In Python 3.5 to 3.12, the function was private and known as
+ ``_PyThreadState_UncheckedGet()``.
+
+
+.. c:function:: PyThreadState* PyThreadState_Swap(PyThreadState *tstate)
+
+ Set the :term:`attached thread state` to *tstate*, and return the
+ :term:`thread state` that was attached prior to calling.
+
+ This function is safe to call without an :term:`attached thread state`; it
+ will simply return ``NULL`` indicating that there was no prior thread state.
+
+ .. seealso::
+ :c:func:`PyEval_ReleaseThread`
+
+ .. note::
+ Similar to :c:func:`PyGILState_Ensure`, this function will hang the
+ thread if the runtime is finalizing.
+
+
+GIL-state APIs
+--------------
+
+The following functions use thread-local storage, and are not compatible
+with sub-interpreters:
+
+.. c:type:: PyGILState_STATE
+
+ The type of the value returned by :c:func:`PyGILState_Ensure` and passed to
+ :c:func:`PyGILState_Release`.
+
+ .. c:enumerator:: PyGILState_LOCKED
+
+ The GIL was already held when :c:func:`PyGILState_Ensure` was called.
+
+ .. c:enumerator:: PyGILState_UNLOCKED
+
+ The GIL was not held when :c:func:`PyGILState_Ensure` was called.
+
+.. c:function:: PyGILState_STATE PyGILState_Ensure()
+
+ Ensure that the current thread is ready to call the Python C API regardless
+ of the current state of Python, or of the :term:`attached thread state`. This may
+ be called as many times as desired by a thread as long as each call is
+ matched with a call to :c:func:`PyGILState_Release`. In general, other
+ thread-related APIs may be used between :c:func:`PyGILState_Ensure` and
+ :c:func:`PyGILState_Release` calls as long as the thread state is restored to
+ its previous state before the Release(). For example, normal usage of the
+ :c:macro:`Py_BEGIN_ALLOW_THREADS` and :c:macro:`Py_END_ALLOW_THREADS` macros is
+ acceptable.
+
+ The return value is an opaque "handle" to the :term:`attached thread state` when
+ :c:func:`PyGILState_Ensure` was called, and must be passed to
+ :c:func:`PyGILState_Release` to ensure Python is left in the same state. Even
+ though recursive calls are allowed, these handles *cannot* be shared - each
+ unique call to :c:func:`PyGILState_Ensure` must save the handle for its call
+ to :c:func:`PyGILState_Release`.
+
+ When the function returns, there will be an :term:`attached thread state`
+ and the thread will be able to call arbitrary Python code. Failure is a fatal error.
+
+ .. warning::
+ Calling this function when the runtime is finalizing is unsafe. Doing
+ so will either hang the thread until the program ends, or fully crash
+ the interpreter in rare cases. Refer to
+ :ref:`cautions-regarding-runtime-finalization` for more details.
+
+ .. versionchanged:: 3.14
+ Hangs the current thread, rather than terminating it, if called while the
+ interpreter is finalizing.
+
+.. c:function:: void PyGILState_Release(PyGILState_STATE)
+
+ Release any resources previously acquired. After this call, Python's state will
+ be the same as it was prior to the corresponding :c:func:`PyGILState_Ensure` call
+ (but generally this state will be unknown to the caller, hence the use of the
+ GILState API).
+
+ Every call to :c:func:`PyGILState_Ensure` must be matched by a call to
+ :c:func:`PyGILState_Release` on the same thread.
+
+.. c:function:: PyThreadState* PyGILState_GetThisThreadState()
+
+ Get the :term:`attached thread state` for this thread. May return ``NULL`` if no
+ GILState API has been used on the current thread. Note that the main thread
+ always has such a thread-state, even if no auto-thread-state call has been
+ made on the main thread. This is mainly a helper/diagnostic function.
+
+ .. note::
+ This function may return non-``NULL`` even when the :term:`thread state`
+ is detached.
+ Prefer :c:func:`PyThreadState_Get` or :c:func:`PyThreadState_GetUnchecked`
+ for most cases.
+
+ .. seealso:: :c:func:`PyThreadState_Get`
+
+.. c:function:: int PyGILState_Check()
+
+ Return ``1`` if the current thread is holding the :term:`GIL` and ``0`` otherwise.
+ This function can be called from any thread at any time.
+ Only if it has had its :term:`thread state <attached thread state>` initialized
+ via :c:func:`PyGILState_Ensure` will it return ``1``.
+ This is mainly a helper/diagnostic function. It can be useful
+ for example in callback contexts or memory allocation functions when
+ knowing that the :term:`GIL` is locked can allow the caller to perform sensitive
+ actions or otherwise behave differently.
+
+ .. note::
+ If the current Python process has ever created a subinterpreter, this
+ function will *always* return ``1``. Prefer :c:func:`PyThreadState_GetUnchecked`
+ for most cases.
+
+ .. versionadded:: 3.4
+
+
+Low-level APIs
+--------------
+
+.. c:function:: PyThreadState* PyThreadState_New(PyInterpreterState *interp)
+
+ Create a new thread state object belonging to the given interpreter object.
+ An :term:`attached thread state` is not needed.
+
+.. c:function:: void PyThreadState_Clear(PyThreadState *tstate)
+
+ Reset all information in a :term:`thread state` object. *tstate*
+ must be :term:`attached <attached thread state>`
+
+ .. versionchanged:: 3.9
+ This function now calls the :c:member:`!PyThreadState.on_delete` callback.
+ Previously, that happened in :c:func:`PyThreadState_Delete`.
+
+ .. versionchanged:: 3.13
+ The :c:member:`!PyThreadState.on_delete` callback was removed.
+
+
+.. c:function:: void PyThreadState_Delete(PyThreadState *tstate)
+
+ Destroy a :term:`thread state` object. *tstate* should not
+ be :term:`attached <attached thread state>` to any thread.
+ *tstate* must have been reset with a previous call to
+ :c:func:`PyThreadState_Clear`.
+
+
+.. c:function:: void PyThreadState_DeleteCurrent(void)
+
+ Detach the :term:`attached thread state` (which must have been reset
+ with a previous call to :c:func:`PyThreadState_Clear`) and then destroy it.
+
+ No :term:`thread state` will be :term:`attached <attached thread state>` upon
+ returning.
+
+.. c:function:: PyFrameObject* PyThreadState_GetFrame(PyThreadState *tstate)
+
+ Get the current frame of the Python thread state *tstate*.
+
+ Return a :term:`strong reference`. Return ``NULL`` if no frame is currently
+ executing.
+
+ See also :c:func:`PyEval_GetFrame`.
+
+ *tstate* must not be ``NULL``, and must be :term:`attached <attached thread state>`.
+
+ .. versionadded:: 3.9
+
+
+.. c:function:: uint64_t PyThreadState_GetID(PyThreadState *tstate)
+
+ Get the unique :term:`thread state` identifier of the Python thread state *tstate*.
+
+ *tstate* must not be ``NULL``, and must be :term:`attached <attached thread state>`.
+
+ .. versionadded:: 3.9
+
+
+.. c:function:: PyInterpreterState* PyThreadState_GetInterpreter(PyThreadState *tstate)
+
+ Get the interpreter of the Python thread state *tstate*.
+
+ *tstate* must not be ``NULL``, and must be :term:`attached <attached thread state>`.
+
+ .. versionadded:: 3.9
+
+
+.. c:function:: void PyThreadState_EnterTracing(PyThreadState *tstate)
+
+ Suspend tracing and profiling in the Python thread state *tstate*.
+
+ Resume them using the :c:func:`PyThreadState_LeaveTracing` function.
+
+ .. versionadded:: 3.11
+
+
+.. c:function:: void PyThreadState_LeaveTracing(PyThreadState *tstate)
+
+ Resume tracing and profiling in the Python thread state *tstate* suspended
+ by the :c:func:`PyThreadState_EnterTracing` function.
+
+ See also :c:func:`PyEval_SetTrace` and :c:func:`PyEval_SetProfile`
+ functions.
+
+ .. versionadded:: 3.11
+
+
+.. c:function:: int PyUnstable_ThreadState_SetStackProtection(PyThreadState *tstate, void *stack_start_addr, size_t stack_size)
+
+ Set the stack protection start address and stack protection size
+ of a Python thread state.
+
+ On success, return ``0``.
+ On failure, set an exception and return ``-1``.
+
+ CPython implements :ref:`recursion control <recursion>` for C code by raising
+ :py:exc:`RecursionError` when it notices that the machine execution stack is close
+ to overflow. See for example the :c:func:`Py_EnterRecursiveCall` function.
+ For this, it needs to know the location of the current thread's stack, which it
+ normally gets from the operating system.
+ When the stack is changed, for example using context switching techniques like the
+ Boost library's ``boost::context``, you must call
+ :c:func:`~PyUnstable_ThreadState_SetStackProtection` to inform CPython of the change.
+
+ Call :c:func:`~PyUnstable_ThreadState_SetStackProtection` either before
+ or after changing the stack.
+ Do not call any other Python C API between the call and the stack
+ change.
+
+ See :c:func:`PyUnstable_ThreadState_ResetStackProtection` for undoing this operation.
+
+ .. versionadded:: 3.15
+
+
+.. c:function:: void PyUnstable_ThreadState_ResetStackProtection(PyThreadState *tstate)
+
+ Reset the stack protection start address and stack protection size
+ of a Python thread state to the operating system defaults.
+
+ See :c:func:`PyUnstable_ThreadState_SetStackProtection` for an explanation.
+
+ .. versionadded:: 3.15
+
+
+.. c:function:: PyObject* PyThreadState_GetDict()
+
+ Return a dictionary in which extensions can store thread-specific state
+ information. Each extension should use a unique key to use to store state in
+ the dictionary. It is okay to call this function when no :term:`thread state`
+ is :term:`attached <attached thread state>`. If this function returns
+ ``NULL``, no exception has been raised and the caller should assume no
+ thread state is attached.
+
+
+.. c:function:: void PyEval_AcquireThread(PyThreadState *tstate)
+
+ :term:`Attach <attached thread state>` *tstate* to the current thread,
+ which must not be ``NULL`` or already :term:`attached <attached thread state>`.
+
+ The calling thread must not already have an :term:`attached thread state`.
+
+ .. note::
+ Calling this function from a thread when the runtime is finalizing will
+ hang the thread until the program exits, even if the thread was not
+ created by Python. Refer to
+ :ref:`cautions-regarding-runtime-finalization` for more details.
+
+ .. versionchanged:: 3.8
+ Updated to be consistent with :c:func:`PyEval_RestoreThread`,
+ :c:func:`Py_END_ALLOW_THREADS`, and :c:func:`PyGILState_Ensure`,
+ and terminate the current thread if called while the interpreter is finalizing.
+
+ .. versionchanged:: 3.14
+ Hangs the current thread, rather than terminating it, if called while the
+ interpreter is finalizing.
+
+ :c:func:`PyEval_RestoreThread` is a higher-level function which is always
+ available (even when threads have not been initialized).
+
+
+.. c:function:: void PyEval_ReleaseThread(PyThreadState *tstate)
+
+ Detach the :term:`attached thread state`.
+ The *tstate* argument, which must not be ``NULL``, is only used to check
+ that it represents the :term:`attached thread state` --- if it isn't, a fatal error is
+ reported.
+
+ :c:func:`PyEval_SaveThread` is a higher-level function which is always
+ available (even when threads have not been initialized).
+
+
+Asynchronous notifications
+==========================
+
+A mechanism is provided to make asynchronous notifications to the main
+interpreter thread. These notifications take the form of a function
+pointer and a void pointer argument.
+
+
+.. c:function:: int Py_AddPendingCall(int (*func)(void *), void *arg)
+
+ Schedule a function to be called from the main interpreter thread. On
+ success, ``0`` is returned and *func* is queued for being called in the
+ main thread. On failure, ``-1`` is returned without setting any exception.
+
+ When successfully queued, *func* will be *eventually* called from the
+ main interpreter thread with the argument *arg*. It will be called
+ asynchronously with respect to normally running Python code, but with
+ both these conditions met:
+
+ * on a :term:`bytecode` boundary;
+ * with the main thread holding an :term:`attached thread state`
+ (*func* can therefore use the full C API).
+
+ *func* must return ``0`` on success, or ``-1`` on failure with an exception
+ set. *func* won't be interrupted to perform another asynchronous
+ notification recursively, but it can still be interrupted to switch
+ threads if the :term:`thread state <attached thread state>` is detached.
+
+ This function doesn't need an :term:`attached thread state`. However, to call this
+ function in a subinterpreter, the caller must have an :term:`attached thread state`.
+ Otherwise, the function *func* can be scheduled to be called from the wrong interpreter.
+
+ .. warning::
+ This is a low-level function, only useful for very special cases.
+ There is no guarantee that *func* will be called as quick as
+ possible. If the main thread is busy executing a system call,
+ *func* won't be called before the system call returns. This
+ function is generally **not** suitable for calling Python code from
+ arbitrary C threads. Instead, use the :ref:`PyGILState API<gilstate>`.
+
+ .. versionadded:: 3.1
+
+ .. versionchanged:: 3.9
+ If this function is called in a subinterpreter, the function *func* is
+ now scheduled to be called from the subinterpreter, rather than being
+ called from the main interpreter. Each subinterpreter now has its own
+ list of scheduled calls.
+
+ .. versionchanged:: 3.12
+ This function now always schedules *func* to be run in the main
+ interpreter.
+
+
+.. c:function:: int Py_MakePendingCalls(void)
+
+ Execute all pending calls. This is usually executed automatically by the
+ interpreter.
+
+ This function returns ``0`` on success, and returns ``-1`` with an exception
+ set on failure.
+
+ If this is not called in the main thread of the main
+ interpreter, this function does nothing and returns ``0``.
+ The caller must hold an :term:`attached thread state`.
+
+ .. versionadded:: 3.1
+
+ .. versionchanged:: 3.12
+ This function only runs pending calls in the main interpreter.
+
+
+.. c:function:: int PyThreadState_SetAsyncExc(unsigned long id, PyObject *exc)
+
+ Asynchronously raise an exception in a thread. The *id* argument is the thread
+ id of the target thread; *exc* is the exception object to be raised. This
+ function does not steal any references to *exc*. To prevent naive misuse, you
+ must write your own C extension to call this. Must be called with an :term:`attached thread state`.
+ Returns the number of thread states modified; this is normally one, but will be
+ zero if the thread id isn't found. If *exc* is ``NULL``, the pending
+ exception (if any) for the thread is cleared. This raises no exceptions.
+
+ .. versionchanged:: 3.7
+ The type of the *id* parameter changed from :c:expr:`long` to
+ :c:expr:`unsigned long`.
+
+
+Operating system thread APIs
+============================
+
+.. c:macro:: PYTHREAD_INVALID_THREAD_ID
+
+ Sentinel value for an invalid thread ID.
+
+ This is currently equivalent to ``(unsigned long)-1``.
+
+
+.. c:function:: unsigned long PyThread_start_new_thread(void (*func)(void *), void *arg)
+
+ Start function *func* in a new thread with argument *arg*.
+ The resulting thread is not intended to be joined.
+
+ *func* must not be ``NULL``, but *arg* may be ``NULL``.
+
+ On success, this function returns the identifier of the new thread; on failure,
+ this returns :c:macro:`PYTHREAD_INVALID_THREAD_ID`.
+
+ The caller does not need to hold an :term:`attached thread state`.
+
+
+.. c:function:: unsigned long PyThread_get_thread_ident(void)
+
+ Return the identifier of the current thread, which will never be zero.
+
+ This function cannot fail, and the caller does not need to hold an
+ :term:`attached thread state`.
+
+ .. seealso::
+ :py:func:`threading.get_ident`
+
+
+.. c:function:: PyObject *PyThread_GetInfo(void)
+
+ Get general information about the current thread in the form of a
+ :ref:`struct sequence <struct-sequence-objects>` object. This information is
+ accessible as :py:attr:`sys.thread_info` in Python.
+
+ On success, this returns a new :term:`strong reference` to the thread
+ information; on failure, this returns ``NULL`` with an exception set.
+
+ The caller must hold an :term:`attached thread state`.
+
+
+.. c:macro:: PY_HAVE_THREAD_NATIVE_ID
+
+ This macro is defined when the system supports native thread IDs.
+
+
+.. c:function:: unsigned long PyThread_get_thread_native_id(void)
+
+ Get the native identifier of the current thread as it was assigned by the operating
+ system's kernel, which will never be less than zero.
+
+ This function is only available when :c:macro:`PY_HAVE_THREAD_NATIVE_ID` is
+ defined.
+
+ This function cannot fail, and the caller does not need to hold an
+ :term:`attached thread state`.
+
+ .. seealso::
+ :py:func:`threading.get_native_id`
+
+
+.. c:function:: void PyThread_exit_thread(void)
+
+ Terminate the current thread. This function is generally considered unsafe
+ and should be avoided. It is kept solely for backwards compatibility.
+
+ This function is only safe to call if all functions in the full call
+ stack are written to safely allow it.
+
+ .. warning::
+
+ If the current system uses POSIX threads (also known as "pthreads"),
+ this calls :manpage:`pthread_exit(3)`, which attempts to unwind the stack
+ and call C++ destructors on some libc implementations. However, if a
+ ``noexcept`` function is reached, it may terminate the process.
+ Other systems, such as macOS, do unwinding.
+
+ On Windows, this function calls ``_endthreadex()``, which kills the thread
+ without calling C++ destructors.
+
+ In any case, there is a risk of corruption on the thread's stack.
+
+ .. deprecated:: 3.14
+
+
+.. c:function:: void PyThread_init_thread(void)
+
+ Initialize ``PyThread*`` APIs. Python executes this function automatically,
+ so there's little need to call it from an extension module.
+
+
+.. c:function:: int PyThread_set_stacksize(size_t size)
+
+ Set the stack size of the current thread to *size* bytes.
+
+ This function returns ``0`` on success, ``-1`` if *size* is invalid, or
+ ``-2`` if the system does not support changing the stack size. This function
+ does not set exceptions.
+
+ The caller does not need to hold an :term:`attached thread state`.
+
+
+.. c:function:: size_t PyThread_get_stacksize(void)
+
+ Return the stack size of the current thread in bytes, or ``0`` if the system's
+ default stack size is in use.
+
+ The caller does not need to hold an :term:`attached thread state`.
diff --git a/Doc/c-api/tls.rst b/Doc/c-api/tls.rst
new file mode 100644
index 00000000000..93ac5557141
--- /dev/null
+++ b/Doc/c-api/tls.rst
@@ -0,0 +1,155 @@
+.. highlight:: c
+
+.. _thread-local-storage:
+
+Thread-local storage support
+============================
+
+The Python interpreter provides low-level support for thread-local storage
+(TLS) which wraps the underlying native TLS implementation to support the
+Python-level thread-local storage API (:class:`threading.local`). The
+CPython C level APIs are similar to those offered by pthreads and Windows:
+use a thread key and functions to associate a :c:expr:`void*` value per
+thread.
+
+A :term:`thread state` does *not* need to be :term:`attached <attached thread state>`
+when calling these functions; they supply their own locking.
+
+Note that :file:`Python.h` does not include the declaration of the TLS APIs,
+you need to include :file:`pythread.h` to use thread-local storage.
+
+.. note::
+ None of these API functions handle memory management on behalf of the
+ :c:expr:`void*` values. You need to allocate and deallocate them yourself.
+ If the :c:expr:`void*` values happen to be :c:expr:`PyObject*`, these
+ functions don't do refcount operations on them either.
+
+.. _thread-specific-storage-api:
+
+Thread-specific storage API
+---------------------------
+
+The thread-specific storage (TSS) API was introduced to supersede the use of the existing TLS API within the
+CPython interpreter. This API uses a new type :c:type:`Py_tss_t` instead of
+:c:expr:`int` to represent thread keys.
+
+.. versionadded:: 3.7
+
+.. seealso:: "A New C-API for Thread-Local Storage in CPython" (:pep:`539`)
+
+
+.. c:type:: Py_tss_t
+
+ This data structure represents the state of a thread key, the definition of
+ which may depend on the underlying TLS implementation, and it has an
+ internal field representing the key's initialization state. There are no
+ public members in this structure.
+
+ When :ref:`Py_LIMITED_API <stable>` is not defined, static allocation of
+ this type by :c:macro:`Py_tss_NEEDS_INIT` is allowed.
+
+
+.. c:macro:: Py_tss_NEEDS_INIT
+
+ This macro expands to the initializer for :c:type:`Py_tss_t` variables.
+ Note that this macro won't be defined with :ref:`Py_LIMITED_API <stable>`.
+
+
+Dynamic allocation
+------------------
+
+Dynamic allocation of the :c:type:`Py_tss_t`, required in extension modules
+built with :ref:`Py_LIMITED_API <stable>`, where static allocation of this type
+is not possible due to its implementation being opaque at build time.
+
+
+.. c:function:: Py_tss_t* PyThread_tss_alloc()
+
+ Return a value which is the same state as a value initialized with
+ :c:macro:`Py_tss_NEEDS_INIT`, or ``NULL`` in the case of dynamic allocation
+ failure.
+
+
+.. c:function:: void PyThread_tss_free(Py_tss_t *key)
+
+ Free the given *key* allocated by :c:func:`PyThread_tss_alloc`, after
+ first calling :c:func:`PyThread_tss_delete` to ensure any associated
+ thread locals have been unassigned. This is a no-op if the *key*
+ argument is ``NULL``.
+
+ .. note::
+ A freed key becomes a dangling pointer. You should reset the key to
+ ``NULL``.
+
+
+Methods
+-------
+
+The parameter *key* of these functions must not be ``NULL``. Moreover, the
+behaviors of :c:func:`PyThread_tss_set` and :c:func:`PyThread_tss_get` are
+undefined if the given :c:type:`Py_tss_t` has not been initialized by
+:c:func:`PyThread_tss_create`.
+
+
+.. c:function:: int PyThread_tss_is_created(Py_tss_t *key)
+
+ Return a non-zero value if the given :c:type:`Py_tss_t` has been initialized
+ by :c:func:`PyThread_tss_create`.
+
+
+.. c:function:: int PyThread_tss_create(Py_tss_t *key)
+
+ Return a zero value on successful initialization of a TSS key. The behavior
+ is undefined if the value pointed to by the *key* argument is not
+ initialized by :c:macro:`Py_tss_NEEDS_INIT`. This function can be called
+ repeatedly on the same key -- calling it on an already initialized key is a
+ no-op and immediately returns success.
+
+
+.. c:function:: void PyThread_tss_delete(Py_tss_t *key)
+
+ Destroy a TSS key to forget the values associated with the key across all
+ threads, and change the key's initialization state to uninitialized. A
+ destroyed key is able to be initialized again by
+ :c:func:`PyThread_tss_create`. This function can be called repeatedly on
+ the same key -- calling it on an already destroyed key is a no-op.
+
+
+.. c:function:: int PyThread_tss_set(Py_tss_t *key, void *value)
+
+ Return a zero value to indicate successfully associating a :c:expr:`void*`
+ value with a TSS key in the current thread. Each thread has a distinct
+ mapping of the key to a :c:expr:`void*` value.
+
+
+.. c:function:: void* PyThread_tss_get(Py_tss_t *key)
+
+ Return the :c:expr:`void*` value associated with a TSS key in the current
+ thread. This returns ``NULL`` if no value is associated with the key in the
+ current thread.
+
+
+.. _thread-local-storage-api:
+
+Legacy APIs
+-----------
+
+.. deprecated:: 3.7
+ This API is superseded by the
+ :ref:`thread-specific storage (TSS) API <thread-specific-storage-api>`.
+
+.. note::
+ This version of the API does not support platforms where the native TLS key
+ is defined in a way that cannot be safely cast to ``int``. On such platforms,
+ :c:func:`PyThread_create_key` will return immediately with a failure status,
+ and the other TLS functions will all be no-ops on such platforms.
+
+Due to the compatibility problem noted above, this version of the API should not
+be used in new code.
+
+.. c:function:: int PyThread_create_key()
+.. c:function:: void PyThread_delete_key(int key)
+.. c:function:: int PyThread_set_key_value(int key, void *value)
+.. c:function:: void* PyThread_get_key_value(int key)
+.. c:function:: void PyThread_delete_key_value(int key)
+.. c:function:: void PyThread_ReInitTLS()
diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst
index 2f2060d0582..7fe810f585f 100644
--- a/Doc/c-api/type.rst
+++ b/Doc/c-api/type.rst
@@ -274,6 +274,10 @@ Type Objects
Return the module object associated with the given type when the type was
created using :c:func:`PyType_FromModuleAndSpec`.
+ The returned reference is :term:`borrowed <borrowed reference>` from *type*,
+ and will be valid as long as you hold a reference to *type*.
+ Do not release it with :c:func:`Py_DECREF` or similar.
+
If no module is associated with the given type, sets :py:class:`TypeError`
and returns ``NULL``.
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 5129e9ee6f0..a0db4c31065 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -1484,6 +1484,52 @@ and :c:data:`PyType_Type` effectively act as defaults.)
It will be removed in a future version of CPython
+ .. c:macro:: Py_TPFLAGS_HAVE_VERSION_TAG
+
+ This is a :term:`soft deprecated` macro that does nothing.
+ Historically, this would indicate that the
+ :c:member:`~PyTypeObject.tp_version_tag` field was available and
+ initialized.
+
+
+ .. c:macro:: Py_TPFLAGS_INLINE_VALUES
+
+ This bit indicates that instances of this type will have an "inline values"
+ array (containing the object's attributes) placed directly after the end
+ of the object.
+
+ This requires that :c:macro:`Py_TPFLAGS_HAVE_GC` is set.
+
+ **Inheritance:**
+
+ This flag is not inherited.
+
+ .. versionadded:: 3.13
+
+
+ .. c:macro:: Py_TPFLAGS_IS_ABSTRACT
+
+ This bit indicates that this is an abstract type and therefore cannot
+ be instantiated.
+
+ **Inheritance:**
+
+ This flag is not inherited.
+
+ .. seealso::
+ :mod:`abc`
+
+
+ .. c:macro:: Py_TPFLAGS_HAVE_STACKLESS_EXTENSION
+
+ Internal. Do not set or unset this flag.
+ Historically, this was a reserved flag for use in Stackless Python.
+
+ .. warning::
+ This flag is present in header files, but is not be used.
+ This may be removed in a future version of CPython.
+
+
.. c:member:: const char* PyTypeObject.tp_doc
.. corresponding-type-slot:: Py_tp_doc
diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst
index 7eb9f0b54ab..6256bf7a145 100644
--- a/Doc/c-api/veryhigh.rst
+++ b/Doc/c-api/veryhigh.rst
@@ -191,7 +191,7 @@ the same library that the Python runtime is using.
objects *globals* and *locals* with the compiler flags specified by
*flags*. *globals* must be a dictionary; *locals* can be any object
that implements the mapping protocol. The parameter *start* specifies
- the start symbol and must one of the :ref:`available start symbols <start-symbols>`.
+ the start symbol and must be one of the :ref:`available start symbols <start-symbols>`.
Returns the result of executing the code as a Python object, or ``NULL`` if an
exception was raised.
diff --git a/Doc/conf.py b/Doc/conf.py
index a4275835059..a6819d4af26 100644
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -42,6 +42,7 @@
# Skip if downstream redistributors haven't installed them
_OPTIONAL_EXTENSIONS = (
+ 'linklint.ext',
'notfound.extension',
'sphinxext.opengraph',
)
@@ -553,6 +554,7 @@
# mapping unique short aliases to a base URL and a prefix.
# https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
extlinks = {
+ "oss-fuzz": ("https://issues.oss-fuzz.com/issues/%s", "#%s"),
"pypi": ("https://pypi.org/project/%s/", "%s"),
"source": (SOURCE_URI, "%s"),
}
diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat
index 1cc1b44a5b8..48b800fdf9a 100644
--- a/Doc/data/refcounts.dat
+++ b/Doc/data/refcounts.dat
@@ -2415,6 +2415,9 @@ PyType_GetFlags:PyTypeObject*:type:0:
PyType_GetName:PyObject*::+1:
PyType_GetName:PyTypeObject*:type:0:
+PyType_GetModule:PyObject*::0:
+PyType_GetModule:PyTypeObject*:type:0:
+
PyType_GetModuleByDef:PyObject*::0:
PyType_GetModuleByDef:PyTypeObject*:type:0:
PyType_GetModuleByDef:PyModuleDef*:def::
diff --git a/Doc/deprecations/pending-removal-in-3.15.rst b/Doc/deprecations/pending-removal-in-3.15.rst
index c80588b27b6..600510cf7f0 100644
--- a/Doc/deprecations/pending-removal-in-3.15.rst
+++ b/Doc/deprecations/pending-removal-in-3.15.rst
@@ -64,7 +64,7 @@ Pending removal in Python 3.15
* :func:`~threading.RLock` will take no arguments in Python 3.15.
Passing any arguments has been deprecated since Python 3.14,
- as the Python version does not permit any arguments,
+ as the Python version does not permit any arguments,
but the C version allows any number of positional or keyword arguments,
ignoring every argument.
diff --git a/Doc/deprecations/pending-removal-in-future.rst b/Doc/deprecations/pending-removal-in-future.rst
index 43e06da6c28..d9a2d50378e 100644
--- a/Doc/deprecations/pending-removal-in-future.rst
+++ b/Doc/deprecations/pending-removal-in-future.rst
@@ -35,7 +35,6 @@ although there is currently no date scheduled for their removal.
* Support for ``__complex__()`` method returning a strict subclass of
:class:`complex`: these methods will be required to return an instance of
:class:`complex`.
- * Delegation of ``int()`` to ``__trunc__()`` method.
* Passing a complex number as the *real* or *imag* argument in the
:func:`complex` constructor is now deprecated; it should only be passed
as a single positional argument.
diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst
index 138a5ca7a75..ff34bb5d71c 100644
--- a/Doc/faq/programming.rst
+++ b/Doc/faq/programming.rst
@@ -8,11 +8,11 @@ Programming FAQ
.. contents::
-General Questions
+General questions
=================
-Is there a source code level debugger with breakpoints, single-stepping, etc.?
-------------------------------------------------------------------------------
+Is there a source code-level debugger with breakpoints and single-stepping?
+---------------------------------------------------------------------------
Yes.
@@ -25,8 +25,7 @@ Reference Manual <pdb>`. You can also write your own debugger by using the code
for pdb as an example.
The IDLE interactive development environment, which is part of the standard
-Python distribution (normally available as
-`Tools/scripts/idle3 <https://github.com/python/cpython/blob/main/Tools/scripts/idle3>`_),
+Python distribution (normally available as :mod:`idlelib`),
includes a graphical debugger.
PythonWin is a Python IDE that includes a GUI debugger based on pdb. The
@@ -48,7 +47,6 @@ There are a number of commercial Python IDEs that include graphical debuggers.
They include:
* `Wing IDE <https://wingware.com/>`_
-* `Komodo IDE <https://www.activestate.com/products/komodo-ide/>`_
* `PyCharm <https://www.jetbrains.com/pycharm/>`_
@@ -57,13 +55,15 @@ Are there tools to help find bugs or perform static analysis?
Yes.
-`Pylint <https://pylint.pycqa.org/en/latest/index.html>`_ and
-`Pyflakes <https://github.com/PyCQA/pyflakes>`_ do basic checking that will
+`Ruff <https://docs.astral.sh/ruff/>`__,
+`Pylint <https://pylint.readthedocs.io/>`__ and
+`Pyflakes <https://github.com/PyCQA/pyflakes>`__ do basic checking that will
help you catch bugs sooner.
-Static type checkers such as `Mypy <https://mypy-lang.org/>`_,
-`Pyre <https://pyre-check.org/>`_, and
-`Pytype <https://github.com/google/pytype>`_ can check type hints in Python
+Static type checkers such as `mypy <https://mypy-lang.org/>`__,
+`ty <https://docs.astral.sh/ty/>`__,
+`Pyrefly <https://pyrefly.org/>`__, and
+`pytype <https://github.com/google/pytype>`__ can check type hints in Python
source code.
@@ -79,7 +79,7 @@ set of modules required by a program and bind these modules together with a
Python binary to produce a single executable.
One is to use the freeze tool, which is included in the Python source tree as
-`Tools/freeze <https://github.com/python/cpython/tree/main/Tools/freeze>`_.
+:source:`Tools/freeze`.
It converts Python byte code to C arrays; with a C compiler you can
embed all your modules into a new program, which is then linked with the
standard Python modules.
@@ -103,6 +103,7 @@ executables:
* `py2app <https://github.com/ronaldoussoren/py2app>`_ (macOS only)
* `py2exe <https://www.py2exe.org/>`_ (Windows only)
+
Are there coding standards or a style guide for Python programs?
----------------------------------------------------------------
@@ -110,7 +111,7 @@ Yes. The coding style required for standard library modules is documented as
:pep:`8`.
-Core Language
+Core language
=============
.. _faq-unboundlocalerror:
@@ -143,7 +144,7 @@ results in an :exc:`!UnboundLocalError`:
>>> foo()
Traceback (most recent call last):
...
- UnboundLocalError: local variable 'x' referenced before assignment
+ UnboundLocalError: cannot access local variable 'x' where it is not associated with a value
This is because when you make an assignment to a variable in a scope, that
variable becomes local to that scope and shadows any similarly named variable
@@ -208,7 +209,7 @@ Why do lambdas defined in a loop with different values all return the same resul
----------------------------------------------------------------------------------
Assume you use a for loop to define a few different lambdas (or even plain
-functions), e.g.::
+functions), for example::
>>> squares = []
>>> for x in range(5):
@@ -227,7 +228,7 @@ they all return ``16``::
This happens because ``x`` is not local to the lambdas, but is defined in
the outer scope, and it is accessed when the lambda is called --- not when it
is defined. At the end of the loop, the value of ``x`` is ``4``, so all the
-functions now return ``4**2``, i.e. ``16``. You can also verify this by
+functions now return ``4**2``, that is ``16``. You can also verify this by
changing the value of ``x`` and see how the results of the lambdas change::
>>> x = 8
@@ -298,9 +299,9 @@ using multiple imports per line uses less screen space.
It's good practice if you import modules in the following order:
-1. standard library modules -- e.g. :mod:`sys`, :mod:`os`, :mod:`argparse`, :mod:`re`
+1. standard library modules -- such as :mod:`sys`, :mod:`os`, :mod:`argparse`, :mod:`re`
2. third-party library modules (anything installed in Python's site-packages
- directory) -- e.g. :mod:`!dateutil`, :mod:`!requests`, :mod:`!PIL.Image`
+ directory) -- such as :pypi:`dateutil`, :pypi:`requests`, :pypi:`tzdata`
3. locally developed modules
It is sometimes necessary to move imports to a function or class to avoid
@@ -494,11 +495,11 @@ new objects).
In other words:
-* If we have a mutable object (:class:`list`, :class:`dict`, :class:`set`,
- etc.), we can use some specific operations to mutate it and all the variables
+* If we have a mutable object (such as :class:`list`, :class:`dict`, :class:`set`),
+ we can use some specific operations to mutate it and all the variables
that refer to it will see the change.
-* If we have an immutable object (:class:`str`, :class:`int`, :class:`tuple`,
- etc.), all the variables that refer to it will always see the same value,
+* If we have an immutable object (such as :class:`str`, :class:`int`, :class:`tuple`),
+ all the variables that refer to it will always see the same value,
but operations that transform that value into a new value always return a new
object.
@@ -511,7 +512,7 @@ How do I write a function with output parameters (call by reference)?
Remember that arguments are passed by assignment in Python. Since assignment
just creates references to objects, there's no alias between an argument name in
-the caller and callee, and so no call-by-reference per se. You can achieve the
+the caller and callee, and consequently no call-by-reference. You can achieve the
desired effect in a number of ways.
1) By returning a tuple of the results::
@@ -714,8 +715,8 @@ not::
"a" in ("b", "a")
-The same is true of the various assignment operators (``=``, ``+=`` etc). They
-are not truly operators but syntactic delimiters in assignment statements.
+The same is true of the various assignment operators (``=``, ``+=``, and so on).
+They are not truly operators but syntactic delimiters in assignment statements.
Is there an equivalent of C's "?:" ternary operator?
@@ -868,9 +869,9 @@ with either a space or parentheses.
How do I convert a string to a number?
--------------------------------------
-For integers, use the built-in :func:`int` type constructor, e.g. ``int('144')
+For integers, use the built-in :func:`int` type constructor, for example, ``int('144')
== 144``. Similarly, :func:`float` converts to a floating-point number,
-e.g. ``float('144') == 144.0``.
+for example, ``float('144') == 144.0``.
By default, these interpret the number as decimal, so that ``int('0144') ==
144`` holds true, and ``int('0x144')`` raises :exc:`ValueError`. ``int(string,
@@ -887,18 +888,18 @@ unwanted side effects. For example, someone could pass
directory.
:func:`eval` also has the effect of interpreting numbers as Python expressions,
-so that e.g. ``eval('09')`` gives a syntax error because Python does not allow
+so that, for example, ``eval('09')`` gives a syntax error because Python does not allow
leading '0' in a decimal number (except '0').
How do I convert a number to a string?
--------------------------------------
-To convert, e.g., the number ``144`` to the string ``'144'``, use the built-in type
+For example, to convert the number ``144`` to the string ``'144'``, use the built-in type
constructor :func:`str`. If you want a hexadecimal or octal representation, use
the built-in functions :func:`hex` or :func:`oct`. For fancy formatting, see
-the :ref:`f-strings` and :ref:`formatstrings` sections,
-e.g. ``"{:04d}".format(144)`` yields
+the :ref:`f-strings` and :ref:`formatstrings` sections.
+For example, ``"{:04d}".format(144)`` yields
``'0144'`` and ``"{:.3f}".format(1.0/3.0)`` yields ``'0.333'``.
@@ -908,7 +909,7 @@ How do I modify a string in place?
You can't, because strings are immutable. In most situations, you should
simply construct a new string from the various parts you want to assemble
it from. However, if you need an object with the ability to modify in-place
-unicode data, try using an :class:`io.StringIO` object or the :mod:`array`
+Unicode data, try using an :class:`io.StringIO` object or the :mod:`array`
module::
>>> import io
@@ -1066,13 +1067,14 @@ the raw string::
Also see the specification in the :ref:`language reference <strings>`.
+
Performance
===========
My program is too slow. How do I speed it up?
---------------------------------------------
-That's a tough one, in general. First, here are a list of things to
+That's a tough one, in general. First, here is a list of things to
remember before diving further:
* Performance characteristics vary across Python implementations. This FAQ
@@ -1125,6 +1127,7 @@ yourself.
The wiki page devoted to `performance tips
<https://wiki.python.org/moin/PythonSpeed/PerformanceTips>`_.
+
.. _efficient_string_concatenation:
What is the most efficient way to concatenate many strings together?
@@ -1143,7 +1146,7 @@ them into a list and call :meth:`str.join` at the end::
chunks.append(s)
result = ''.join(chunks)
-(another reasonably efficient idiom is to use :class:`io.StringIO`)
+(Another reasonably efficient idiom is to use :class:`io.StringIO`.)
To accumulate many :class:`bytes` objects, the recommended idiom is to extend
a :class:`bytearray` object using in-place concatenation (the ``+=`` operator)::
@@ -1153,7 +1156,7 @@ a :class:`bytearray` object using in-place concatenation (the ``+=`` operator)::
result += b
-Sequences (Tuples/Lists)
+Sequences (tuples/lists)
========================
How do I convert between tuples and lists?
@@ -1217,8 +1220,8 @@ list, deleting duplicates as you go::
else:
last = mylist[i]
-If all elements of the list may be used as set keys (i.e. they are all
-:term:`hashable`) this is often faster ::
+If all elements of the list may be used as set keys (that is, they are all
+:term:`hashable`) this is often faster::
mylist = list(set(mylist))
@@ -1254,7 +1257,7 @@ difference is that a Python list can contain objects of many different types.
The ``array`` module also provides methods for creating arrays of fixed types
with compact representations, but they are slower to index than lists. Also
note that `NumPy <https://numpy.org/>`_
-and other third party packages define array-like structures with
+and other third-party packages define array-like structures with
various characteristics as well.
To get Lisp-style linked lists, you can emulate *cons cells* using tuples::
@@ -1324,7 +1327,7 @@ Or, you can use an extension that provides a matrix datatype; `NumPy
How do I apply a method or function to a sequence of objects?
-------------------------------------------------------------
-To call a method or function and accumulate the return values is a list,
+To call a method or function and accumulate the return values in a list,
a :term:`list comprehension` is an elegant solution::
result = [obj.method() for obj in mylist]
@@ -1340,6 +1343,7 @@ a plain :keyword:`for` loop will suffice::
for obj in mylist:
function(obj)
+
.. _faq-augmented-assignment-tuple-error:
Why does a_tuple[i] += ['item'] raise an exception when the addition works?
@@ -1444,7 +1448,7 @@ How can I sort one list by values from another list?
----------------------------------------------------
Merge them into an iterator of tuples, sort the resulting list, and then pick
-out the element you want. ::
+out the element you want.
>>> list1 = ["what", "I'm", "sorting", "by"]
>>> list2 = ["something", "else", "to", "sort"]
@@ -1504,14 +1508,15 @@ How do I check if an object is an instance of a given class or of a subclass of
Use the built-in function :func:`isinstance(obj, cls) <isinstance>`. You can
check if an object
is an instance of any of a number of classes by providing a tuple instead of a
-single class, e.g. ``isinstance(obj, (class1, class2, ...))``, and can also
-check whether an object is one of Python's built-in types, e.g.
+single class, for example, ``isinstance(obj, (class1, class2, ...))``, and can also
+check whether an object is one of Python's built-in types, for example,
``isinstance(obj, str)`` or ``isinstance(obj, (int, float, complex))``.
Note that :func:`isinstance` also checks for virtual inheritance from an
:term:`abstract base class`. So, the test will return ``True`` for a
registered class even if hasn't directly or indirectly inherited from it. To
-test for "true inheritance", scan the :term:`MRO` of the class:
+test for "true inheritance", scan the :term:`method resolution order` (MRO) of
+the class:
.. testcode::
@@ -1574,7 +1579,7 @@ call it::
What is delegation?
-------------------
-Delegation is an object oriented technique (also called a design pattern).
+Delegation is an object-oriented technique (also called a design pattern).
Let's say you have an object ``x`` and want to change the behaviour of just one
of its methods. You can create a new class that provides a new implementation
of the method you're interested in changing and delegates all other methods to
@@ -1645,7 +1650,7 @@ How can I organize my code to make it easier to change the base class?
You could assign the base class to an alias and derive from the alias. Then all
you have to change is the value assigned to the alias. Incidentally, this trick
-is also handy if you want to decide dynamically (e.g. depending on availability
+is also handy if you want to decide dynamically (such as depending on availability
of resources) which base class to use. Example::
class Base:
@@ -1710,9 +1715,9 @@ How can I overload constructors (or methods) in Python?
This answer actually applies to all methods, but the question usually comes up
first in the context of constructors.
-In C++ you'd write
+In C++ you'd write:
-.. code-block:: c
+.. code-block:: c++
class C {
C() { cout << "No arguments\n"; }
@@ -1731,7 +1736,7 @@ default arguments. For example::
This is not entirely equivalent, but close enough in practice.
-You could also try a variable-length argument list, e.g. ::
+You could also try a variable-length argument list, for example::
def __init__(self, *args):
...
@@ -1774,6 +1779,7 @@ to use private variable names at all.
The :ref:`private name mangling specifications <private-name-mangling>`
for details and special cases.
+
My class defines __del__ but it is not called when I delete the object.
-----------------------------------------------------------------------
@@ -1783,7 +1789,7 @@ The :keyword:`del` statement does not necessarily call :meth:`~object.__del__` -
decrements the object's reference count, and if this reaches zero
:meth:`!__del__` is called.
-If your data structures contain circular links (e.g. a tree where each child has
+If your data structures contain circular links (for example, a tree where each child has
a parent reference and each parent has a list of children) the reference counts
will never go back to zero. Once in a while Python runs an algorithm to detect
such cycles, but the garbage collector might run some time after the last
@@ -1852,6 +1858,8 @@ to the object:
13891296
+.. _faq-identity-with-is:
+
When can I rely on identity tests with the *is* operator?
---------------------------------------------------------
@@ -1883,9 +1891,9 @@ are preferred. In particular, identity tests should not be used to check
constants such as :class:`int` and :class:`str` which aren't guaranteed to be
singletons::
- >>> a = 1000
- >>> b = 500
- >>> c = b + 500
+ >>> a = 10_000_000
+ >>> b = 5_000_000
+ >>> c = b + 5_000_000
>>> a is c
False
@@ -1954,9 +1962,9 @@ parent class:
.. testcode::
- from datetime import date
+ import datetime as dt
- class FirstOfMonthDate(date):
+ class FirstOfMonthDate(dt.date):
"Always choose the first day of the month"
def __new__(cls, year, month, day):
return super().__new__(cls, year, month, 1)
@@ -1999,7 +2007,7 @@ The two principal tools for caching methods are
former stores results at the instance level and the latter at the class
level.
-The *cached_property* approach only works with methods that do not take
+The ``cached_property`` approach only works with methods that do not take
any arguments. It does not create a reference to the instance. The
cached method result will be kept only as long as the instance is alive.
@@ -2008,7 +2016,7 @@ method result will be released right away. The disadvantage is that if
instances accumulate, so too will the accumulated method results. They
can grow without bound.
-The *lru_cache* approach works with methods that have :term:`hashable`
+The ``lru_cache`` approach works with methods that have :term:`hashable`
arguments. It creates a reference to the instance unless special
efforts are made to pass in weak references.
@@ -2042,11 +2050,11 @@ This example shows the various techniques::
# Depends on the station_id, date, and units.
The above example assumes that the *station_id* never changes. If the
-relevant instance attributes are mutable, the *cached_property* approach
+relevant instance attributes are mutable, the ``cached_property`` approach
can't be made to work because it cannot detect changes to the
attributes.
-To make the *lru_cache* approach work when the *station_id* is mutable,
+To make the ``lru_cache`` approach work when the *station_id* is mutable,
the class needs to define the :meth:`~object.__eq__` and :meth:`~object.__hash__`
methods so that the cache can detect relevant attribute updates::
@@ -2092,10 +2100,10 @@ one user but run as another, such as if you are testing with a web server.
Unless the :envvar:`PYTHONDONTWRITEBYTECODE` environment variable is set,
creation of a .pyc file is automatic if you're importing a module and Python
-has the ability (permissions, free space, etc...) to create a ``__pycache__``
+has the ability (permissions, free space, and so on) to create a ``__pycache__``
subdirectory and write the compiled module to that subdirectory.
-Running Python on a top level script is not considered an import and no
+Running Python on a top-level script is not considered an import and no
``.pyc`` will be created. For example, if you have a top-level module
``foo.py`` that imports another module ``xyz.py``, when you run ``foo`` (by
typing ``python foo.py`` as a shell command), a ``.pyc`` will be created for
@@ -2114,7 +2122,7 @@ the ``compile()`` function in that module interactively::
This will write the ``.pyc`` to a ``__pycache__`` subdirectory in the same
location as ``foo.py`` (or you can override that with the optional parameter
-``cfile``).
+*cfile*).
You can also automatically compile all files in a directory or directories using
the :mod:`compileall` module. You can do it from the shell prompt by running
@@ -2219,7 +2227,7 @@ changed module, do this::
importlib.reload(modname)
Warning: this technique is not 100% fool-proof. In particular, modules
-containing statements like ::
+containing statements like::
from modname import some_objects
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 7c41f5bc27b..6151143a97b 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -786,6 +786,19 @@ Glossary
An object that both finds and loads a module; both a
:term:`finder` and :term:`loader` object.
+ index
+ A numeric value that represents the position of an element in
+ a :term:`sequence`.
+
+ In Python, indexing starts at zero.
+ For example, ``things[0]`` names the *first* element of ``things``;
+ ``things[1]`` names the second one.
+
+ In some contexts, Python allows negative indexes for counting from the
+ end of a sequence, and indexing using :term:`slices <slice>`.
+
+ See also :term:`subscript`.
+
interactive
Python has an interactive interpreter which means you can enter
statements and expressions at the interpreter prompt, immediately
@@ -863,6 +876,9 @@ Glossary
CPython does not guarantee :term:`thread-safe` behavior of iterator
operations.
+ key
+ A value that identifies an entry in a :term:`mapping`.
+ See also :term:`subscript`.
key function
A key function or collation function is a callable that returns a value
@@ -935,6 +951,16 @@ Glossary
to locks exist such as queues, producer/consumer patterns, and
thread-local state. See also :term:`deadlock`, and :term:`reentrant`.
+ lock-free
+ An operation that does not acquire any :term:`lock` and uses atomic CPU
+ instructions to ensure correctness. Lock-free operations can execute
+ concurrently without blocking each other and cannot be blocked by
+ operations that hold locks. In :term:`free-threaded <free threading>`
+ Python, built-in types like :class:`dict` and :class:`list` provide
+ lock-free read operations, which means other threads may observe
+ intermediate states during multi-step modifications even when those
+ modifications hold the :term:`per-object lock`.
+
loader
An object that loads a module.
It must define the :meth:`!exec_module` and :meth:`!create_module` methods
@@ -1201,6 +1227,16 @@ Glossary
<faq-argument-vs-parameter>`, the :class:`inspect.Parameter` class, the
:ref:`function` section, and :pep:`362`.
+ per-object lock
+ A :term:`lock` associated with an individual object instance rather than
+ a global lock shared across all objects. In :term:`free-threaded
+ <free threading>` Python, built-in types like :class:`dict` and
+ :class:`list` use per-object locks to allow concurrent operations on
+ different objects while serializing operations on the same object.
+ Operations that hold the per-object lock prevent other locking operations
+ on the same object from proceeding, but do not block :term:`lock-free`
+ operations.
+
path entry
A single location on the :term:`import path` which the :term:`path
based finder` consults to find modules for importing.
@@ -1323,7 +1359,7 @@ Glossary
'email.mime.text'
race condition
- A condition of a program where the its behavior
+ A condition of a program where the behavior
depends on the relative timing or ordering of events, particularly in
multi-threaded programs. Race conditions can lead to
:term:`non-deterministic` behavior and bugs that are difficult to
@@ -1417,10 +1453,11 @@ Glossary
chosen based on the type of a single argument.
slice
- An object usually containing a portion of a :term:`sequence`. A slice is
- created using the subscript notation, ``[]`` with colons between numbers
- when several are given, such as in ``variable_name[1:3:5]``. The bracket
- (subscript) notation uses :class:`slice` objects internally.
+ An object of type :class:`slice`, used to describe a portion of
+ a :term:`sequence`.
+ A slice object is created when using the :ref:`slicing <slicings>` form
+ of :ref:`subscript notation <subscriptions>`, with colons inside square
+ brackets, such as in ``variable_name[1:3:5]``.
soft deprecated
A soft deprecated API should not be used in new code,
@@ -1478,6 +1515,14 @@ Glossary
See also :term:`borrowed reference`.
+ subscript
+ The expression in square brackets of a
+ :ref:`subscription expression <subscriptions>`, for example,
+ the ``3`` in ``items[3]``.
+ Usually used to select an element of a container.
+ Also called a :term:`key` when subscripting a :term:`mapping`,
+ or an :term:`index` when subscripting a :term:`sequence`.
+
synchronization primitive
A basic building block for coordinating (synchronizing) the execution of
multiple threads to ensure :term:`thread-safe` access to shared resources.
diff --git a/Doc/howto/logging.rst b/Doc/howto/logging.rst
index b7225ff1c2c..454e2f4930e 100644
--- a/Doc/howto/logging.rst
+++ b/Doc/howto/logging.rst
@@ -28,7 +28,7 @@ When to use logging
^^^^^^^^^^^^^^^^^^^
You can access logging functionality by creating a logger via ``logger =
-getLogger(__name__)``, and then calling the logger's :meth:`~Logger.debug`,
+logging.getLogger(__name__)``, and then calling the logger's :meth:`~Logger.debug`,
:meth:`~Logger.info`, :meth:`~Logger.warning`, :meth:`~Logger.error` and
:meth:`~Logger.critical` methods. To determine when to use logging, and to see
which logger methods to use when, see the table below. It states, for each of a
diff --git a/Doc/improve-page-nojs.rst b/Doc/improve-page-nojs.rst
new file mode 100644
index 00000000000..91b3a88b95d
--- /dev/null
+++ b/Doc/improve-page-nojs.rst
@@ -0,0 +1,29 @@
+:orphan:
+
+****************************
+Improve a documentation page
+****************************
+
+.. This is the no-javascript version of this page. The one most people
+ will see (with JavaScript enabled) is improve-page.rst. If you edit
+ this page, please also edit that one, and vice versa.
+
+.. only:: html and not epub
+
+We are always interested to hear ideas about improvements to the documentation.
+
+.. only:: translation
+
+ If the bug or suggested improvement concerns the translation of this
+ documentation, open an issue or edit the page in
+ `translation's repository <TRANSLATION_REPO_>`_ instead.
+
+You have a few ways to ask questions or suggest changes:
+
+- You can start a discussion about the page on the Python discussion forum.
+ This link will start a topic in the Documentation category:
+ `New Documentation topic <https://discuss.python.org/new-topic?category=documentation>`_.
+
+- You can open an issue on the Python GitHub issue tracker. This link will
+ create a new issue with the "docs" label:
+ `New docs issue <https://github.com/python/cpython/issues/new?template=documentation.yml>`_.
diff --git a/Doc/improve-page.rst b/Doc/improve-page.rst
new file mode 100644
index 00000000000..dc89fcb22fb
--- /dev/null
+++ b/Doc/improve-page.rst
@@ -0,0 +1,65 @@
+:orphan:
+
+****************************
+Improve a documentation page
+****************************
+
+.. This is the JavaScript-enabled version of this page. Another version
+ (for those with JavaScript disabled) is improve-page-nojs.rst. If you
+ edit this page, please also edit that one, and vice versa.
+
+.. only:: html and not epub
+
+ .. raw:: html
+
+ <script>
+ function applyReplacements(text, params) {
+ return text
+ .replace(/PAGETITLE/g, params.get('pagetitle'))
+ .replace(/PAGEURL/g, params.get('pageurl'))
+ .replace(/PAGESOURCE/g, params.get('pagesource'));
+ }
+
+ document.addEventListener('DOMContentLoaded', () => {
+ const params = new URLSearchParams(window.location.search);
+ const walker = document.createTreeWalker(
+ document.body,
+ NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT,
+ null
+ );
+
+ while (walker.nextNode()) {
+ const node = walker.currentNode;
+
+ if (node.nodeType === Node.TEXT_NODE) {
+ node.textContent = applyReplacements(node.textContent, params)
+ } else if (node.nodeName === 'A' && node.href) {
+ node.setAttribute('href', applyReplacements(node.getAttribute('href'), params));
+ }
+ }
+ });
+ </script>
+
+We are always interested to hear ideas about improvements to the documentation.
+
+You were reading "PAGETITLE" at `<PAGEURL>`_. The source for that page is on
+`GitHub <https://github.com/python/cpython/blob/main/Doc/PAGESOURCE?plain=1>`_.
+
+.. only:: translation
+
+ If the bug or suggested improvement concerns the translation of this
+ documentation, open an issue or edit the page in
+ `translation's repository <TRANSLATION_REPO_>`_ instead.
+
+You have a few ways to ask questions or suggest changes:
+
+- You can start a discussion about the page on the Python discussion forum.
+ This link will start a pre-populated topic:
+ `Question about page "PAGETITLE" <https://discuss.python.org/new-topic?category=documentation&title=Question+about+page+%22PAGETITLE%22&body=About+the+page+at+PAGEURL%3A>`_.
+
+- You can open an issue on the Python GitHub issue tracker. This link will
+ create a new pre-populated issue:
+ `Docs: problem with page "PAGETITLE" <https://github.com/python/cpython/issues/new?template=documentation.yml&title=Docs%3A+problem+with+page+%22PAGETITLE%22&description=The+page+at+PAGEURL+has+a+problem%3A>`_.
+
+- You can `edit the page on GitHub <https://github.com/python/cpython/blob/main/Doc/PAGESOURCE?plain=1>`_
+ to open a pull request and begin the contribution process.
diff --git a/Doc/includes/tzinfo_examples.py b/Doc/includes/tzinfo_examples.py
index 1fa6e615e46..762b1b62fc8 100644
--- a/Doc/includes/tzinfo_examples.py
+++ b/Doc/includes/tzinfo_examples.py
@@ -1,68 +1,70 @@
-from datetime import tzinfo, timedelta, datetime
-
-ZERO = timedelta(0)
-HOUR = timedelta(hours=1)
-SECOND = timedelta(seconds=1)
+import datetime as dt
# A class capturing the platform's idea of local time.
# (May result in wrong values on historical times in
# timezones where UTC offset and/or the DST rules had
# changed in the past.)
-import time as _time
+import time
+
+ZERO = dt.timedelta(0)
+HOUR = dt.timedelta(hours=1)
+SECOND = dt.timedelta(seconds=1)
-STDOFFSET = timedelta(seconds = -_time.timezone)
-if _time.daylight:
- DSTOFFSET = timedelta(seconds = -_time.altzone)
+STDOFFSET = dt.timedelta(seconds=-time.timezone)
+if time.daylight:
+ DSTOFFSET = dt.timedelta(seconds=-time.altzone)
else:
DSTOFFSET = STDOFFSET
DSTDIFF = DSTOFFSET - STDOFFSET
-class LocalTimezone(tzinfo):
- def fromutc(self, dt):
- assert dt.tzinfo is self
- stamp = (dt - datetime(1970, 1, 1, tzinfo=self)) // SECOND
- args = _time.localtime(stamp)[:6]
+class LocalTimezone(dt.tzinfo):
+
+ def fromutc(self, when):
+ assert when.tzinfo is self
+ stamp = (when - dt.datetime(1970, 1, 1, tzinfo=self)) // SECOND
+ args = time.localtime(stamp)[:6]
dst_diff = DSTDIFF // SECOND
# Detect fold
- fold = (args == _time.localtime(stamp - dst_diff))
- return datetime(*args, microsecond=dt.microsecond,
- tzinfo=self, fold=fold)
+ fold = (args == time.localtime(stamp - dst_diff))
+ return dt.datetime(*args, microsecond=when.microsecond,
+ tzinfo=self, fold=fold)
- def utcoffset(self, dt):
- if self._isdst(dt):
+ def utcoffset(self, when):
+ if self._isdst(when):
return DSTOFFSET
else:
return STDOFFSET
- def dst(self, dt):
- if self._isdst(dt):
+ def dst(self, when):
+ if self._isdst(when):
return DSTDIFF
else:
return ZERO
- def tzname(self, dt):
- return _time.tzname[self._isdst(dt)]
+ def tzname(self, when):
+ return time.tzname[self._isdst(when)]
- def _isdst(self, dt):
- tt = (dt.year, dt.month, dt.day,
- dt.hour, dt.minute, dt.second,
- dt.weekday(), 0, 0)
- stamp = _time.mktime(tt)
- tt = _time.localtime(stamp)
+ def _isdst(self, when):
+ tt = (when.year, when.month, when.day,
+ when.hour, when.minute, when.second,
+ when.weekday(), 0, 0)
+ stamp = time.mktime(tt)
+ tt = time.localtime(stamp)
return tt.tm_isdst > 0
+
Local = LocalTimezone()
# A complete implementation of current DST rules for major US time zones.
-def first_sunday_on_or_after(dt):
- days_to_go = 6 - dt.weekday()
+def first_sunday_on_or_after(when):
+ days_to_go = 6 - when.weekday()
if days_to_go:
- dt += timedelta(days_to_go)
- return dt
+ when += dt.timedelta(days_to_go)
+ return when
# US DST Rules
@@ -75,21 +77,22 @@ def first_sunday_on_or_after(dt):
#
# In the US, since 2007, DST starts at 2am (standard time) on the second
# Sunday in March, which is the first Sunday on or after Mar 8.
-DSTSTART_2007 = datetime(1, 3, 8, 2)
+DSTSTART_2007 = dt.datetime(1, 3, 8, 2)
# and ends at 2am (DST time) on the first Sunday of Nov.
-DSTEND_2007 = datetime(1, 11, 1, 2)
+DSTEND_2007 = dt.datetime(1, 11, 1, 2)
# From 1987 to 2006, DST used to start at 2am (standard time) on the first
# Sunday in April and to end at 2am (DST time) on the last
# Sunday of October, which is the first Sunday on or after Oct 25.
-DSTSTART_1987_2006 = datetime(1, 4, 1, 2)
-DSTEND_1987_2006 = datetime(1, 10, 25, 2)
+DSTSTART_1987_2006 = dt.datetime(1, 4, 1, 2)
+DSTEND_1987_2006 = dt.datetime(1, 10, 25, 2)
# From 1967 to 1986, DST used to start at 2am (standard time) on the last
# Sunday in April (the one on or after April 24) and to end at 2am (DST time)
# on the last Sunday of October, which is the first Sunday
# on or after Oct 25.
-DSTSTART_1967_1986 = datetime(1, 4, 24, 2)
+DSTSTART_1967_1986 = dt.datetime(1, 4, 24, 2)
DSTEND_1967_1986 = DSTEND_1987_2006
+
def us_dst_range(year):
# Find start and end times for US DST. For years before 1967, return
# start = end for no DST.
@@ -100,17 +103,17 @@ def us_dst_range(year):
elif 1966 < year < 1987:
dststart, dstend = DSTSTART_1967_1986, DSTEND_1967_1986
else:
- return (datetime(year, 1, 1), ) * 2
+ return (dt.datetime(year, 1, 1), ) * 2
start = first_sunday_on_or_after(dststart.replace(year=year))
end = first_sunday_on_or_after(dstend.replace(year=year))
return start, end
-class USTimeZone(tzinfo):
+class USTimeZone(dt.tzinfo):
def __init__(self, hours, reprname, stdname, dstname):
- self.stdoffset = timedelta(hours=hours)
+ self.stdoffset = dt.timedelta(hours=hours)
self.reprname = reprname
self.stdname = stdname
self.dstname = dstname
@@ -118,45 +121,45 @@ def __init__(self, hours, reprname, stdname, dstname):
def __repr__(self):
return self.reprname
- def tzname(self, dt):
- if self.dst(dt):
+ def tzname(self, when):
+ if self.dst(when):
return self.dstname
else:
return self.stdname
- def utcoffset(self, dt):
- return self.stdoffset + self.dst(dt)
+ def utcoffset(self, when):
+ return self.stdoffset + self.dst(when)
- def dst(self, dt):
- if dt is None or dt.tzinfo is None:
+ def dst(self, when):
+ if when is None or when.tzinfo is None:
# An exception may be sensible here, in one or both cases.
# It depends on how you want to treat them. The default
# fromutc() implementation (called by the default astimezone()
- # implementation) passes a datetime with dt.tzinfo is self.
+ # implementation) passes a datetime with when.tzinfo is self.
return ZERO
- assert dt.tzinfo is self
- start, end = us_dst_range(dt.year)
+ assert when.tzinfo is self
+ start, end = us_dst_range(when.year)
# Can't compare naive to aware objects, so strip the timezone from
- # dt first.
- dt = dt.replace(tzinfo=None)
- if start + HOUR <= dt < end - HOUR:
+ # when first.
+ when = when.replace(tzinfo=None)
+ if start + HOUR <= when < end - HOUR:
# DST is in effect.
return HOUR
- if end - HOUR <= dt < end:
- # Fold (an ambiguous hour): use dt.fold to disambiguate.
- return ZERO if dt.fold else HOUR
- if start <= dt < start + HOUR:
+ if end - HOUR <= when < end:
+ # Fold (an ambiguous hour): use when.fold to disambiguate.
+ return ZERO if when.fold else HOUR
+ if start <= when < start + HOUR:
# Gap (a non-existent hour): reverse the fold rule.
- return HOUR if dt.fold else ZERO
+ return HOUR if when.fold else ZERO
# DST is off.
return ZERO
- def fromutc(self, dt):
- assert dt.tzinfo is self
- start, end = us_dst_range(dt.year)
+ def fromutc(self, when):
+ assert when.tzinfo is self
+ start, end = us_dst_range(when.year)
start = start.replace(tzinfo=self)
end = end.replace(tzinfo=self)
- std_time = dt + self.stdoffset
+ std_time = when + self.stdoffset
dst_time = std_time + HOUR
if end <= dst_time < end + HOUR:
# Repeated hour
diff --git a/Doc/installing/index.rst b/Doc/installing/index.rst
index 3a485a43a5a..412005f3ec8 100644
--- a/Doc/installing/index.rst
+++ b/Doc/installing/index.rst
@@ -6,8 +6,6 @@
Installing Python Modules
*************************
-:Email: distutils-sig@python.org
-
As a popular open source development project, Python has an active
supporting community of contributors and users that also make their software
available for other Python developers to use under open source license terms.
diff --git a/Doc/library/__future__.rst b/Doc/library/__future__.rst
index 5d916b30112..749e4543c5b 100644
--- a/Doc/library/__future__.rst
+++ b/Doc/library/__future__.rst
@@ -15,7 +15,7 @@ before the release in which the feature becomes standard.
While these future statements are given additional special meaning by the
Python compiler, they are still executed like any other import statement and
-the :mod:`__future__` exists and is handled by the import system the same way
+the :mod:`!__future__` exists and is handled by the import system the same way
any other Python module would be. This design serves three purposes:
* To avoid confusing existing tools that analyze import statements and expect to
@@ -23,17 +23,17 @@ any other Python module would be. This design serves three purposes:
* To document when incompatible changes were introduced, and when they will be
--- or were --- made mandatory. This is a form of executable documentation, and
- can be inspected programmatically via importing :mod:`__future__` and examining
+ can be inspected programmatically via importing :mod:`!__future__` and examining
its contents.
* To ensure that :ref:`future statements <future>` run under releases prior to
- Python 2.1 at least yield runtime exceptions (the import of :mod:`__future__`
+ Python 2.1 at least yield runtime exceptions (the import of :mod:`!__future__`
will fail, because there was no module of that name prior to 2.1).
Module Contents
---------------
-No feature description will ever be deleted from :mod:`__future__`. Since its
+No feature description will ever be deleted from :mod:`!__future__`. Since its
introduction in Python 2.1 the following features have found their way into the
language using this mechanism:
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index d8df91c882f..2b2bf0a9d6e 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -13,7 +13,7 @@
.. note::
- While :mod:`argparse` is the default recommended standard library module
+ While :mod:`!argparse` is the default recommended standard library module
for implementing basic command line applications, authors with more
exacting requirements for exactly how their command line applications
behave may find it doesn't provide the necessary level of control.
@@ -604,13 +604,11 @@ subparser names, the feature can be enabled by setting ``suggest_on_error`` to
``True``. Note that this only applies for arguments when the choices specified
are strings::
- >>> parser = argparse.ArgumentParser(description='Process some integers.',
- suggest_on_error=True)
- >>> parser.add_argument('--action', choices=['sum', 'max'])
- >>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
- ... help='an integer for the accumulator')
- >>> parser.parse_args(['--action', 'sumn', 1, 2, 3])
- tester.py: error: argument --action: invalid choice: 'sumn', maybe you meant 'sum'? (choose from 'sum', 'max')
+ >>> parser = argparse.ArgumentParser(suggest_on_error=True)
+ >>> parser.add_argument('--action', choices=['debug', 'dryrun'])
+ >>> parser.parse_args(['--action', 'debugg'])
+ usage: tester.py [-h] [--action {debug,dryrun}]
+ tester.py: error: argument --action: invalid choice: 'debugg', maybe you meant 'debug'? (choose from debug, dryrun)
If you're writing code that needs to be compatible with older Python versions
and want to opportunistically use ``suggest_on_error`` when it's available, you
@@ -734,9 +732,9 @@ By default, :mod:`!argparse` automatically handles the internal naming and
display names of arguments, simplifying the process without requiring
additional configuration.
As such, you do not need to specify the dest_ and metavar_ parameters.
-The dest_ parameter defaults to the argument name with underscores ``_``
-replacing hyphens ``-`` . The metavar_ parameter defaults to the
-upper-cased name. For example::
+For optional arguments, the dest_ parameter defaults to the argument name, with
+underscores ``_`` replacing hyphens ``-``. The metavar_ parameter defaults to
+the upper-cased name. For example::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo-bar')
diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst
index 424c0a92fb2..d2bff573588 100644
--- a/Doc/library/ast.rst
+++ b/Doc/library/ast.rst
@@ -15,7 +15,7 @@
--------------
-The :mod:`ast` module helps Python applications to process trees of the Python
+The :mod:`!ast` module helps Python applications to process trees of the Python
abstract syntax grammar. The abstract syntax itself might change with each
Python release; this module helps to find out programmatically what the current
grammar looks like.
@@ -46,7 +46,7 @@ Node classes
This is the base of all AST node classes. The actual node classes are
derived from the :file:`Parser/Python.asdl` file, which is reproduced
:ref:`above <abstract-grammar>`. They are defined in the :mod:`!_ast` C
- module and re-exported in :mod:`ast`.
+ module and re-exported in :mod:`!ast`.
There is one class defined for each left-hand side symbol in the abstract
grammar (for example, :class:`ast.stmt` or :class:`ast.expr`). In addition,
@@ -2217,10 +2217,10 @@ Async and await
occurrences of the same value (for example, :class:`ast.Add`).
-:mod:`ast` helpers
-------------------
+:mod:`!ast` helpers
+-------------------
-Apart from the node classes, the :mod:`ast` module defines these utility functions
+Apart from the node classes, the :mod:`!ast` module defines these utility functions
and classes for traversing abstract syntax trees:
.. function:: parse(source, filename='<unknown>', mode='exec', *, type_comments=False, feature_version=None, optimize=-1)
@@ -2597,7 +2597,7 @@ Command-line usage
.. versionadded:: 3.9
-The :mod:`ast` module can be executed as a script from the command line.
+The :mod:`!ast` module can be executed as a script from the command line.
It is as simple as:
.. code-block:: sh
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index 72f484fd1cb..bdb24b3a58c 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -297,8 +297,9 @@ clocks to track time.
are called is undefined.
The optional positional *args* will be passed to the callback when
- it is called. If you want the callback to be called with keyword
- arguments use :func:`functools.partial`.
+ it is called. Use :func:`functools.partial`
+ :ref:`to pass keyword arguments <asyncio-pass-keywords>` to
+ *callback*.
An optional keyword-only *context* argument allows specifying a
custom :class:`contextvars.Context` for the *callback* to run in.
@@ -1034,8 +1035,8 @@ Watching file descriptors
.. method:: loop.add_writer(fd, callback, *args)
Start monitoring the *fd* file descriptor for write availability and
- invoke *callback* with the specified arguments once *fd* is available for
- writing.
+ invoke *callback* with the specified arguments *args* once *fd* is
+ available for writing.
Any preexisting callback registered for *fd* is cancelled and replaced by
*callback*.
@@ -1308,7 +1309,8 @@ Unix signals
.. method:: loop.add_signal_handler(signum, callback, *args)
- Set *callback* as the handler for the *signum* signal.
+ Set *callback* as the handler for the *signum* signal,
+ passing *args* as positional arguments.
The callback will be invoked by *loop*, along with other queued callbacks
and runnable coroutines of that event loop. Unlike signal handlers
@@ -1343,7 +1345,8 @@ Executing code in thread or process pools
.. awaitablemethod:: loop.run_in_executor(executor, func, *args)
- Arrange for *func* to be called in the specified executor.
+ Arrange for *func* to be called in the specified executor
+ passing *args* as positional arguments.
The *executor* argument should be an :class:`concurrent.futures.Executor`
instance. The default executor is used if *executor* is ``None``.
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index f825ae92ec7..5331db04aeb 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -771,6 +771,9 @@ Timeouts
An :ref:`asynchronous context manager <async-context-managers>`
for cancelling overdue coroutines.
+ Prefer using :func:`asyncio.timeout` or :func:`asyncio.timeout_at`
+ rather than instantiating :class:`!Timeout` directly.
+
``when`` should be an absolute time at which the context should time out,
as measured by the event loop's clock:
diff --git a/Doc/library/atexit.rst b/Doc/library/atexit.rst
index 02d2f0807df..24a3492ba10 100644
--- a/Doc/library/atexit.rst
+++ b/Doc/library/atexit.rst
@@ -9,9 +9,9 @@
--------------
-The :mod:`atexit` module defines functions to register and unregister cleanup
+The :mod:`!atexit` module defines functions to register and unregister cleanup
functions. Functions thus registered are automatically executed upon normal
-interpreter termination. :mod:`atexit` runs these functions in the *reverse*
+interpreter termination. :mod:`!atexit` runs these functions in the *reverse*
order in which they were registered; if you register ``A``, ``B``, and ``C``,
at interpreter termination time they will be run in the order ``C``, ``B``,
``A``.
@@ -64,7 +64,7 @@ a cleanup function is undefined.
Remove *func* from the list of functions to be run at interpreter shutdown.
:func:`unregister` silently does nothing if *func* was not previously
registered. If *func* has been registered more than once, every occurrence
- of that function in the :mod:`atexit` call stack will be removed. Equality
+ of that function in the :mod:`!atexit` call stack will be removed. Equality
comparisons (``==``) are used internally during unregistration, so function
references do not need to have matching identities.
@@ -72,14 +72,14 @@ a cleanup function is undefined.
.. seealso::
Module :mod:`readline`
- Useful example of :mod:`atexit` to read and write :mod:`readline` history
+ Useful example of :mod:`!atexit` to read and write :mod:`readline` history
files.
.. _atexit-example:
-:mod:`atexit` Example
----------------------
+:mod:`!atexit` Example
+----------------------
The following simple example demonstrates how a module can initialize a counter
from a file when it is imported and save the counter's updated value
diff --git a/Doc/library/bdb.rst b/Doc/library/bdb.rst
index 2b87f2626b2..8d357f18952 100644
--- a/Doc/library/bdb.rst
+++ b/Doc/library/bdb.rst
@@ -8,7 +8,7 @@
--------------
-The :mod:`bdb` module handles basic debugger functions, like setting breakpoints
+The :mod:`!bdb` module handles basic debugger functions, like setting breakpoints
or managing execution via the debugger.
The following exception is defined:
@@ -18,7 +18,7 @@ The following exception is defined:
Exception raised by the :class:`Bdb` class for quitting the debugger.
-The :mod:`bdb` module also defines two classes:
+The :mod:`!bdb` module also defines two classes:
.. class:: Breakpoint(self, file, line, temporary=False, cond=None, funcname=None)
diff --git a/Doc/library/binascii.rst b/Doc/library/binascii.rst
index 1bab785684b..91b43332016 100644
--- a/Doc/library/binascii.rst
+++ b/Doc/library/binascii.rst
@@ -10,10 +10,10 @@
--------------
-The :mod:`binascii` module contains a number of methods to convert between
+The :mod:`!binascii` module contains a number of methods to convert between
binary and various ASCII-encoded binary representations. Normally, you will not
use these functions directly but use wrapper modules like
-:mod:`base64` instead. The :mod:`binascii` module contains
+:mod:`base64` instead. The :mod:`!binascii` module contains
low-level functions written in C for greater speed that are used by the
higher-level modules.
@@ -28,7 +28,7 @@ higher-level modules.
ASCII-only unicode strings are now accepted by the ``a2b_*`` functions.
-The :mod:`binascii` module defines the following functions:
+The :mod:`!binascii` module defines the following functions:
.. function:: a2b_uu(string)
diff --git a/Doc/library/bisect.rst b/Doc/library/bisect.rst
index d5ec4212c1f..ecc8d69a2b3 100644
--- a/Doc/library/bisect.rst
+++ b/Doc/library/bisect.rst
@@ -16,7 +16,7 @@ having to sort the list after each insertion. For long lists of items with
expensive comparison operations, this can be an improvement over
linear searches or frequent resorting.
-The module is called :mod:`bisect` because it uses a basic bisection
+The module is called :mod:`!bisect` because it uses a basic bisection
algorithm to do its work. Unlike other bisection tools that search for a
specific value, the functions in this module are designed to locate an
insertion point. Accordingly, the functions never call an :meth:`~object.__eq__`
@@ -27,9 +27,9 @@ point between values in an array.
.. note::
The functions in this module are not thread-safe. If multiple threads
- concurrently use :mod:`bisect` functions on the same sequence, this
+ concurrently use :mod:`!bisect` functions on the same sequence, this
may result in undefined behaviour. Likewise, if the provided sequence
- is mutated by a different thread while a :mod:`bisect` function
+ is mutated by a different thread while a :mod:`!bisect` function
is operating on it, the result is undefined. For example, using
:py:func:`~bisect.insort_left` on the same list from multiple threads
may result in the list becoming unsorted.
@@ -203,9 +203,9 @@ example uses :py:func:`~bisect.bisect` to look up a letter grade for an exam sco
based on a set of ordered numeric breakpoints: 90 and up is an 'A', 80 to 89 is
a 'B', and so on::
- >>> def grade(score, breakpoints=[60, 70, 80, 90], grades='FDCBA'):
- ... i = bisect(breakpoints, score)
- ... return grades[i]
+ >>> def grade(score)
+ ... i = bisect([60, 70, 80, 90], score)
+ ... return "FDCBA"[i]
...
>>> [grade(score) for score in [33, 99, 77, 70, 89, 90, 100]]
['F', 'A', 'C', 'C', 'B', 'A', 'A']
diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst
index 12650861c0f..32e223ddbdd 100644
--- a/Doc/library/bz2.rst
+++ b/Doc/library/bz2.rst
@@ -16,7 +16,7 @@
This module provides a comprehensive interface for compressing and
decompressing data using the bzip2 compression algorithm.
-The :mod:`bz2` module contains:
+The :mod:`!bz2` module contains:
* The :func:`.open` function and :class:`BZ2File` class for reading and
writing compressed files.
@@ -317,7 +317,7 @@ One-shot (de)compression
Examples of usage
-----------------
-Below are some examples of typical usage of the :mod:`bz2` module.
+Below are some examples of typical usage of the :mod:`!bz2` module.
Using :func:`compress` and :func:`decompress` to demonstrate round-trip compression:
diff --git a/Doc/library/calendar.rst b/Doc/library/calendar.rst
index 39090e36ed9..73b3b8b4da4 100644
--- a/Doc/library/calendar.rst
+++ b/Doc/library/calendar.rst
@@ -447,7 +447,7 @@ For simple text calendars this module provides the following functions.
inverse.
-The :mod:`calendar` module exports the following data attributes:
+The :mod:`!calendar` module exports the following data attributes:
.. data:: day_name
@@ -540,7 +540,7 @@ The :mod:`calendar` module exports the following data attributes:
.. versionadded:: 3.12
-The :mod:`calendar` module defines the following exceptions:
+The :mod:`!calendar` module defines the following exceptions:
.. exception:: IllegalMonthError(month)
@@ -579,7 +579,7 @@ Command-line usage
.. versionadded:: 2.5
-The :mod:`calendar` module can be executed as a script from the command line
+The :mod:`!calendar` module can be executed as a script from the command line
to interactively print a calendar.
.. code-block:: shell
diff --git a/Doc/library/cmath.rst b/Doc/library/cmath.rst
index b6d5dbee21d..f602003e49b 100644
--- a/Doc/library/cmath.rst
+++ b/Doc/library/cmath.rst
@@ -124,7 +124,7 @@ rectangular coordinates to polar coordinates and back.
The modulus (absolute value) of a complex number *z* can be
computed using the built-in :func:`abs` function. There is no
- separate :mod:`cmath` module function for this operation.
+ separate :mod:`!cmath` module function for this operation.
.. function:: polar(z)
@@ -357,7 +357,7 @@ Note that the selection of functions is similar, but not identical, to that in
module :mod:`math`. The reason for having two modules is that some users aren't
interested in complex numbers, and perhaps don't even know what they are. They
would rather have ``math.sqrt(-1)`` raise an exception than return a complex
-number. Also note that the functions defined in :mod:`cmath` always return a
+number. Also note that the functions defined in :mod:`!cmath` always return a
complex number, even if the answer can be expressed as a real number (in which
case the complex number has an imaginary part of zero).
diff --git a/Doc/library/cmd.rst b/Doc/library/cmd.rst
index 66544f82f6f..1757dedabbf 100644
--- a/Doc/library/cmd.rst
+++ b/Doc/library/cmd.rst
@@ -245,7 +245,7 @@ Cmd Example
.. sectionauthor:: Raymond Hettinger <python at rcn dot com>
-The :mod:`cmd` module is mainly useful for building custom shells that let a
+The :mod:`!cmd` module is mainly useful for building custom shells that let a
user work with a program interactively.
This section presents a simple example of how to build a shell around a few of
diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index 24b5a9d64b2..b4a8326e9a8 100644
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -310,7 +310,7 @@ and writing to platform dependent files:
Codec Base Classes
------------------
-The :mod:`codecs` module defines a set of base classes which define the
+The :mod:`!codecs` module defines a set of base classes which define the
interfaces for working with codec objects, and can also be used as the basis
for custom codec implementations.
@@ -1544,8 +1544,8 @@ mapping. It is not supported by :meth:`str.encode` (which only produces
Restoration of the ``rot13`` alias.
-:mod:`encodings` --- Encodings package
---------------------------------------
+:mod:`!encodings` --- Encodings package
+---------------------------------------
.. module:: encodings
:synopsis: Encodings package
@@ -1604,8 +1604,8 @@ This module implements the following exception:
Raised when a codec is invalid or incompatible.
-:mod:`encodings.idna` --- Internationalized Domain Names in Applications
-------------------------------------------------------------------------
+:mod:`!encodings.idna` --- Internationalized Domain Names in Applications
+-------------------------------------------------------------------------
.. module:: encodings.idna
:synopsis: Internationalized Domain Names implementation
@@ -1647,7 +1647,7 @@ When receiving host names from the wire (such as in reverse name lookup), no
automatic conversion to Unicode is performed: applications wishing to present
such host names to the user should decode them to Unicode.
-The module :mod:`encodings.idna` also implements the nameprep procedure, which
+The module :mod:`!encodings.idna` also implements the nameprep procedure, which
performs certain normalizations on host names, to achieve case-insensitivity of
international domain names, and to unify similar characters. The nameprep
functions can be used directly if desired.
@@ -1670,8 +1670,8 @@ functions can be used directly if desired.
Convert a label to Unicode, as specified in :rfc:`3490`.
-:mod:`encodings.mbcs` --- Windows ANSI codepage
------------------------------------------------
+:mod:`!encodings.mbcs` --- Windows ANSI codepage
+------------------------------------------------
.. module:: encodings.mbcs
:synopsis: Windows ANSI codepage
@@ -1688,8 +1688,8 @@ This module implements the ANSI codepage (CP_ACP).
Support any error handler.
-:mod:`encodings.utf_8_sig` --- UTF-8 codec with BOM signature
--------------------------------------------------------------
+:mod:`!encodings.utf_8_sig` --- UTF-8 codec with BOM signature
+--------------------------------------------------------------
.. module:: encodings.utf_8_sig
:synopsis: UTF-8 codec with BOM signature
diff --git a/Doc/library/codeop.rst b/Doc/library/codeop.rst
index 16f674adb4b..2e6d6598038 100644
--- a/Doc/library/codeop.rst
+++ b/Doc/library/codeop.rst
@@ -11,7 +11,7 @@
--------------
-The :mod:`codeop` module provides utilities upon which the Python
+The :mod:`!codeop` module provides utilities upon which the Python
read-eval-print loop can be emulated, as is done in the :mod:`code` module. As
a result, you probably don't want to use the module directly; if you want to
include such a loop in your program you probably want to use the :mod:`code`
@@ -25,7 +25,7 @@ There are two parts to this job:
#. Remembering which future statements the user has entered, so subsequent
input can be compiled with these in effect.
-The :mod:`codeop` module provides a way of doing each of these things, and a way
+The :mod:`!codeop` module provides a way of doing each of these things, and a way
of doing them both.
To do just the former:
diff --git a/Doc/library/colorsys.rst b/Doc/library/colorsys.rst
index ffebf4e40dd..2d3dc2b8b57 100644
--- a/Doc/library/colorsys.rst
+++ b/Doc/library/colorsys.rst
@@ -10,7 +10,7 @@
--------------
-The :mod:`colorsys` module defines bidirectional conversions of color values
+The :mod:`!colorsys` module defines bidirectional conversions of color values
between colors expressed in the RGB (Red Green Blue) color space used in
computer monitors and three other coordinate systems: YIQ, HLS (Hue Lightness
Saturation) and HSV (Hue Saturation Value). Coordinates in all of these color
@@ -24,7 +24,7 @@ spaces, the coordinates are all between 0 and 1.
https://poynton.ca/ColorFAQ.html and
https://www.cambridgeincolour.com/tutorials/color-spaces.htm.
-The :mod:`colorsys` module defines the following functions:
+The :mod:`!colorsys` module defines the following functions:
.. function:: rgb_to_yiq(r, g, b)
diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst
index e4b505c3f97..a32c3828313 100644
--- a/Doc/library/concurrent.futures.rst
+++ b/Doc/library/concurrent.futures.rst
@@ -12,7 +12,7 @@ and :source:`Lib/concurrent/futures/interpreter.py`
--------------
-The :mod:`concurrent.futures` module provides a high-level interface for
+The :mod:`!concurrent.futures` module provides a high-level interface for
asynchronously executing callables.
The asynchronous execution can be performed with threads, using
@@ -156,7 +156,9 @@ And::
print(f.result())
executor = ThreadPoolExecutor(max_workers=1)
- executor.submit(wait_on_future)
+ future = executor.submit(wait_on_future)
+ # Note: calling future.result() would also cause a deadlock because
+ # the single worker thread is already waiting for wait_on_future().
.. class:: ThreadPoolExecutor(max_workers=None, thread_name_prefix='', initializer=None, initargs=())
diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst
index bb109a9b742..f73252a9026 100644
--- a/Doc/library/configparser.rst
+++ b/Doc/library/configparser.rst
@@ -80,7 +80,7 @@ Let's take a very basic configuration file that looks like this:
The structure of INI files is described `in the following section
<#supported-ini-file-structure>`_. Essentially, the file
consists of sections, each of which contains keys with values.
-:mod:`configparser` classes can read and write such files. Let's start by
+:mod:`!configparser` classes can read and write such files. Let's start by
creating the above configuration file programmatically.
.. doctest::
@@ -449,7 +449,7 @@ Mapping Protocol Access
.. versionadded:: 3.2
Mapping protocol access is a generic name for functionality that enables using
-custom objects as if they were dictionaries. In case of :mod:`configparser`,
+custom objects as if they were dictionaries. In case of :mod:`!configparser`,
the mapping interface implementation is using the
``parser['section']['option']`` notation.
@@ -459,7 +459,7 @@ the original parser on demand. What's even more important is that when values
are changed on a section proxy, they are actually mutated in the original
parser.
-:mod:`configparser` objects behave as close to actual dictionaries as possible.
+:mod:`!configparser` objects behave as close to actual dictionaries as possible.
The mapping interface is complete and adheres to the
:class:`~collections.abc.MutableMapping` ABC.
However, there are a few differences that should be taken into account:
@@ -507,7 +507,7 @@ Customizing Parser Behaviour
----------------------------
There are nearly as many INI format variants as there are applications using it.
-:mod:`configparser` goes a long way to provide support for the largest sensible
+:mod:`!configparser` goes a long way to provide support for the largest sensible
set of INI styles available. The default functionality is mainly dictated by
historical background and it's very likely that you will want to customize some
of the features.
@@ -560,7 +560,7 @@ the :meth:`!__init__` options:
* *allow_no_value*, default value: ``False``
Some configuration files are known to include settings without values, but
- which otherwise conform to the syntax supported by :mod:`configparser`. The
+ which otherwise conform to the syntax supported by :mod:`!configparser`. The
*allow_no_value* parameter to the constructor can be used to
indicate that such values should be accepted:
@@ -615,7 +615,7 @@ the :meth:`!__init__` options:
prefixes for whole line comments.
.. versionchanged:: 3.2
- In previous versions of :mod:`configparser` behaviour matched
+ In previous versions of :mod:`!configparser` behaviour matched
``comment_prefixes=('#',';')`` and ``inline_comment_prefixes=(';',)``.
Please note that config parsers don't support escaping of comment prefixes so
@@ -672,7 +672,7 @@ the :meth:`!__init__` options:
parsers in new applications.
.. versionchanged:: 3.2
- In previous versions of :mod:`configparser` behaviour matched
+ In previous versions of :mod:`!configparser` behaviour matched
``strict=False``.
* *empty_lines_in_values*, default value: ``True``
@@ -842,7 +842,7 @@ be overridden by subclasses or by attribute assignment.
Legacy API Examples
-------------------
-Mainly because of backwards compatibility concerns, :mod:`configparser`
+Mainly because of backwards compatibility concerns, :mod:`!configparser`
provides also a legacy API with explicit ``get``/``set`` methods. While there
are valid use cases for the methods outlined below, mapping protocol access is
preferred for new projects. The legacy API is at times more advanced,
@@ -1378,7 +1378,7 @@ Exceptions
.. exception:: Error
- Base class for all other :mod:`configparser` exceptions.
+ Base class for all other :mod:`!configparser` exceptions.
.. exception:: NoSectionError
diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst
index 176be4ff333..7e221c9cabb 100644
--- a/Doc/library/contextlib.rst
+++ b/Doc/library/contextlib.rst
@@ -21,9 +21,9 @@ Functions and classes provided:
.. class:: AbstractContextManager
An :term:`abstract base class` for classes that implement
- :meth:`object.__enter__` and :meth:`object.__exit__`. A default
- implementation for :meth:`object.__enter__` is provided which returns
- ``self`` while :meth:`object.__exit__` is an abstract method which by default
+ :meth:`~object.__enter__` and :meth:`~object.__exit__`. A default
+ implementation for :meth:`~object.__enter__` is provided which returns
+ ``self`` while :meth:`~object.__exit__` is an abstract method which by default
returns ``None``. See also the definition of :ref:`typecontextmanager`.
.. versionadded:: 3.6
@@ -32,9 +32,9 @@ Functions and classes provided:
.. class:: AbstractAsyncContextManager
An :term:`abstract base class` for classes that implement
- :meth:`object.__aenter__` and :meth:`object.__aexit__`. A default
- implementation for :meth:`object.__aenter__` is provided which returns
- ``self`` while :meth:`object.__aexit__` is an abstract method which by default
+ :meth:`~object.__aenter__` and :meth:`~object.__aexit__`. A default
+ implementation for :meth:`~object.__aenter__` is provided which returns
+ ``self`` while :meth:`~object.__aexit__` is an abstract method which by default
returns ``None``. See also the definition of
:ref:`async-context-managers`.
@@ -228,7 +228,7 @@ Functions and classes provided:
.. function:: nullcontext(enter_result=None)
- Return a context manager that returns *enter_result* from ``__enter__``, but
+ Return a context manager that returns *enter_result* from :meth:`~object.__enter__`, but
otherwise does nothing. It is intended to be used as a stand-in for an
optional context manager, for example::
@@ -335,7 +335,7 @@ Functions and classes provided:
For example, the output of :func:`help` normally is sent to *sys.stdout*.
You can capture that output in a string by redirecting the output to an
:class:`io.StringIO` object. The replacement stream is returned from the
- ``__enter__`` method and so is available as the target of the
+ :meth:`~object.__enter__` method and so is available as the target of the
:keyword:`with` statement::
with redirect_stdout(io.StringIO()) as f:
@@ -396,7 +396,8 @@ Functions and classes provided:
A base class that enables a context manager to also be used as a decorator.
Context managers inheriting from ``ContextDecorator`` have to implement
- ``__enter__`` and ``__exit__`` as normal. ``__exit__`` retains its optional
+ :meth:`~object.__enter__` and :meth:`~object.__exit__` as normal.
+ ``__exit__`` retains its optional
exception handling even when used as a decorator.
``ContextDecorator`` is used by :func:`contextmanager`, so you get this
@@ -668,7 +669,7 @@ Examples and Recipes
--------------------
This section describes some examples and recipes for making effective use of
-the tools provided by :mod:`contextlib`.
+the tools provided by :mod:`!contextlib`.
Supporting a variable number of context managers
@@ -697,9 +698,9 @@ context management protocol.
Catching exceptions from ``__enter__`` methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-It is occasionally desirable to catch exceptions from an ``__enter__``
+It is occasionally desirable to catch exceptions from an :meth:`~object.__enter__`
method implementation, *without* inadvertently catching exceptions from
-the :keyword:`with` statement body or the context manager's ``__exit__``
+the :keyword:`with` statement body or the context manager's :meth:`~object.__exit__`
method. By using :class:`ExitStack` the steps in the context management
protocol can be separated slightly in order to allow this::
diff --git a/Doc/library/copy.rst b/Doc/library/copy.rst
index 210ad718800..121c44a16ad 100644
--- a/Doc/library/copy.rst
+++ b/Doc/library/copy.rst
@@ -80,7 +80,7 @@ of lists by assigning a slice of the entire list, for example,
Classes can use the same interfaces to control copying that they use to control
pickling. See the description of module :mod:`pickle` for information on these
-methods. In fact, the :mod:`copy` module uses the registered
+methods. In fact, the :mod:`!copy` module uses the registered
pickle functions from the :mod:`copyreg` module.
.. index::
diff --git a/Doc/library/copyreg.rst b/Doc/library/copyreg.rst
index 6e3144824eb..d59936029da 100644
--- a/Doc/library/copyreg.rst
+++ b/Doc/library/copyreg.rst
@@ -12,7 +12,7 @@
--------------
-The :mod:`copyreg` module offers a way to define functions used while pickling
+The :mod:`!copyreg` module offers a way to define functions used while pickling
specific objects. The :mod:`pickle` and :mod:`copy` modules use those functions
when pickling/copying those objects. The module provides configuration
information about object constructors which are not classes.
diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst
index 4a033d823e6..5c086ab9422 100644
--- a/Doc/library/csv.rst
+++ b/Doc/library/csv.rst
@@ -25,14 +25,14 @@ similar enough that it is possible to write a single module which can
efficiently manipulate such data, hiding the details of reading and writing the
data from the programmer.
-The :mod:`csv` module implements classes to read and write tabular data in CSV
+The :mod:`!csv` module implements classes to read and write tabular data in CSV
format. It allows programmers to say, "write this data in the format preferred
by Excel," or "read data from this file which was generated by Excel," without
knowing the precise details of the CSV format used by Excel. Programmers can
also describe the CSV formats understood by other applications or define their
own special-purpose CSV formats.
-The :mod:`csv` module's :class:`reader` and :class:`writer` objects read and
+The :mod:`!csv` module's :class:`reader` and :class:`writer` objects read and
write sequences. Programmers can also read and write data in dictionary form
using the :class:`DictReader` and :class:`DictWriter` classes.
@@ -47,7 +47,7 @@ using the :class:`DictReader` and :class:`DictWriter` classes.
Module Contents
---------------
-The :mod:`csv` module defines the following functions:
+The :mod:`!csv` module defines the following functions:
.. index::
@@ -146,7 +146,7 @@ The :mod:`csv` module defines the following functions:
given, this becomes the new limit.
-The :mod:`csv` module defines the following classes:
+The :mod:`!csv` module defines the following classes:
.. class:: DictReader(f, fieldnames=None, restkey=None, restval=None, \
dialect='excel', *args, **kwds)
@@ -314,7 +314,7 @@ An example for :class:`Sniffer` use::
.. _csv-constants:
-The :mod:`csv` module defines the following constants:
+The :mod:`!csv` module defines the following constants:
.. data:: QUOTE_ALL
@@ -375,7 +375,7 @@ The :mod:`csv` module defines the following constants:
.. versionadded:: 3.12
-The :mod:`csv` module defines the following exception:
+The :mod:`!csv` module defines the following exception:
.. exception:: Error
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index d2f4da08327..7ec4941c444 100644
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -10,7 +10,7 @@
--------------
-:mod:`ctypes` is a foreign function library for Python. It provides C compatible
+:mod:`!ctypes` is a foreign function library for Python. It provides C compatible
data types, and allows calling functions in DLLs or shared libraries. It can be
used to wrap these libraries in pure Python.
@@ -22,10 +22,6 @@ used to wrap these libraries in pure Python.
ctypes tutorial
---------------
-Note: The code samples in this tutorial use :mod:`doctest` to make sure that
-they actually work. Since some code samples behave differently under Linux,
-Windows, or macOS, they contain doctest directives in comments.
-
Note: Some code samples reference the ctypes :class:`c_int` type. On platforms
where ``sizeof(long) == sizeof(int)`` it is an alias to :class:`c_long`.
So, you should not be confused if :class:`c_long` is printed if you would expect
@@ -36,13 +32,16 @@ So, you should not be confused if :class:`c_long` is printed if you would expect
Loading dynamic link libraries
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-:mod:`ctypes` exports the *cdll*, and on Windows *windll* and *oledll*
+:mod:`!ctypes` exports the :py:data:`~ctypes.cdll`, and on Windows
+:py:data:`~ctypes.windll` and :py:data:`~ctypes.oledll`
objects, for loading dynamic link libraries.
-You load libraries by accessing them as attributes of these objects. *cdll*
-loads libraries which export functions using the standard ``cdecl`` calling
-convention, while *windll* libraries call functions using the ``stdcall``
-calling convention. *oledll* also uses the ``stdcall`` calling convention, and
+You load libraries by accessing them as attributes of these objects.
+:py:data:`!cdll` loads libraries which export functions using the
+standard ``cdecl`` calling convention, while :py:data:`!windll`
+libraries call functions using the ``stdcall``
+calling convention.
+:py:data:`~oledll` also uses the ``stdcall`` calling convention, and
assumes the functions return a Windows :c:type:`!HRESULT` error code. The error
code is used to automatically raise an :class:`OSError` exception when the
function call fails.
@@ -72,11 +71,13 @@ Windows appends the usual ``.dll`` file suffix automatically.
being used by Python. Where possible, use native Python functionality,
or else import and use the ``msvcrt`` module.
-On Linux, it is required to specify the filename *including* the extension to
+Other systems require the filename *including* the extension to
load a library, so attribute access can not be used to load libraries. Either the
:meth:`~LibraryLoader.LoadLibrary` method of the dll loaders should be used,
-or you should load the library by creating an instance of CDLL by calling
-the constructor::
+or you should load the library by creating an instance of :py:class:`CDLL`
+by calling the constructor.
+
+For example, on Linux::
>>> cdll.LoadLibrary("libc.so.6") # doctest: +LINUX
<CDLL 'libc.so.6', handle ... at ...>
@@ -85,7 +86,14 @@ the constructor::
<CDLL 'libc.so.6', handle ... at ...>
>>>
-.. XXX Add section for macOS.
+On macOS::
+
+ >>> cdll.LoadLibrary("libc.dylib") # doctest: +MACOS
+ <CDLL 'libc.dylib', handle ... at ...>
+ >>> libc = CDLL("libc.dylib") # doctest: +MACOS
+ >>> libc # doctest: +MACOS
+ <CDLL 'libc.dylib', handle ... at ...>
+
.. _ctypes-accessing-functions-from-loaded-dlls:
@@ -182,7 +190,7 @@ handle (passing ``None`` as single argument to call it with a ``NULL`` pointer):
To find out the correct calling convention you have to look into the C header
file or the documentation for the function you want to call.
-On Windows, :mod:`ctypes` uses win32 structured exception handling to prevent
+On Windows, :mod:`!ctypes` uses win32 structured exception handling to prevent
crashes from general protection faults when functions are called with invalid
argument values::
@@ -192,7 +200,7 @@ argument values::
OSError: exception: access violation reading 0x00000020
>>>
-There are, however, enough ways to crash Python with :mod:`ctypes`, so you
+There are, however, enough ways to crash Python with :mod:`!ctypes`, so you
should be careful anyway. The :mod:`faulthandler` module can be helpful in
debugging crashes (e.g. from segmentation faults produced by erroneous C library
calls).
@@ -205,7 +213,7 @@ as pointer to the memory block that contains their data (:c:expr:`char *` or
:c:expr:`int` type, their value is masked to fit into the C type.
Before we move on calling functions with other parameter types, we have to learn
-more about :mod:`ctypes` data types.
+more about :mod:`!ctypes` data types.
.. _ctypes-fundamental-data-types:
@@ -213,7 +221,7 @@ more about :mod:`ctypes` data types.
Fundamental data types
^^^^^^^^^^^^^^^^^^^^^^
-:mod:`ctypes` defines a number of primitive C compatible data types:
+:mod:`!ctypes` defines a number of primitive C compatible data types:
+----------------------+------------------------------------------+----------------------------+
| ctypes type | C type | Python type |
@@ -397,7 +405,7 @@ from within *IDLE* or *PythonWin*::
>>>
As has been mentioned before, all Python types except integers, strings, and
-bytes objects have to be wrapped in their corresponding :mod:`ctypes` type, so
+bytes objects have to be wrapped in their corresponding :mod:`!ctypes` type, so
that they can be converted to the required C data type::
>>> printf(b"An int %d, a double %f\n", 1234, c_double(3.14))
@@ -431,10 +439,10 @@ specify :attr:`~_CFuncPtr.argtypes` for all variadic functions.
Calling functions with your own custom data types
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-You can also customize :mod:`ctypes` argument conversion to allow instances of
-your own classes be used as function arguments. :mod:`ctypes` looks for an
+You can also customize :mod:`!ctypes` argument conversion to allow instances of
+your own classes be used as function arguments. :mod:`!ctypes` looks for an
:attr:`!_as_parameter_` attribute and uses this as the function argument. The
-attribute must be an integer, string, bytes, a :mod:`ctypes` instance, or an
+attribute must be an integer, string, bytes, a :mod:`!ctypes` instance, or an
object with an :attr:`!_as_parameter_` attribute::
>>> class Bottles:
@@ -490,7 +498,7 @@ the Python object passed to the function call, it should do a typecheck or
whatever is needed to make sure this object is acceptable, and then return the
object itself, its :attr:`!_as_parameter_` attribute, or whatever you want to
pass as the C function argument in this case. Again, the result should be an
-integer, string, bytes, a :mod:`ctypes` instance, or an object with an
+integer, string, bytes, a :mod:`!ctypes` instance, or an object with an
:attr:`!_as_parameter_` attribute.
@@ -600,7 +608,7 @@ Sometimes a C api function expects a *pointer* to a data type as parameter,
probably to write into the corresponding location, or if the data is too large
to be passed by value. This is also known as *passing parameters by reference*.
-:mod:`ctypes` exports the :func:`byref` function which is used to pass parameters
+:mod:`!ctypes` exports the :func:`byref` function which is used to pass parameters
by reference. The same effect can be achieved with the :func:`pointer` function,
although :func:`pointer` does a lot more work since it constructs a real pointer
object, so it is faster to use :func:`byref` if you don't need the pointer
@@ -625,12 +633,12 @@ Structures and unions
^^^^^^^^^^^^^^^^^^^^^
Structures and unions must derive from the :class:`Structure` and :class:`Union`
-base classes which are defined in the :mod:`ctypes` module. Each subclass must
+base classes which are defined in the :mod:`!ctypes` module. Each subclass must
define a :attr:`~Structure._fields_` attribute. :attr:`!_fields_` must be a list of
*2-tuples*, containing a *field name* and a *field type*.
-The field type must be a :mod:`ctypes` type like :class:`c_int`, or any other
-derived :mod:`ctypes` type: structure, union, array, pointer.
+The field type must be a :mod:`!ctypes` type like :class:`c_int`, or any other
+derived :mod:`!ctypes` type: structure, union, array, pointer.
Here is a simple example of a POINT structure, which contains two integers named
*x* and *y*, and also shows how to initialize a structure in the constructor::
@@ -689,7 +697,7 @@ See :class:`CField`::
.. warning::
- :mod:`ctypes` does not support passing unions or structures with bit-fields
+ :mod:`!ctypes` does not support passing unions or structures with bit-fields
to functions by value. While this may work on 32-bit x86, it's not
guaranteed by the library to work in the general case. Unions and
structures with bit-fields should always be passed to functions by pointer.
@@ -707,7 +715,7 @@ structure itself by setting the class attributes :attr:`~Structure._pack_`
and/or :attr:`~Structure._align_`, respectively.
See the attribute documentation for details.
-:mod:`ctypes` uses the native byte order for Structures and Unions. To build
+:mod:`!ctypes` uses the native byte order for Structures and Unions. To build
structures with non-native byte order, you can use one of the
:class:`BigEndianStructure`, :class:`LittleEndianStructure`,
:class:`BigEndianUnion`, and :class:`LittleEndianUnion` base classes. These
@@ -796,7 +804,7 @@ Pointers
^^^^^^^^
Pointer instances are created by calling the :func:`pointer` function on a
-:mod:`ctypes` type::
+:mod:`!ctypes` type::
>>> from ctypes import *
>>> i = c_int(42)
@@ -810,7 +818,7 @@ returns the object to which the pointer points, the ``i`` object above::
c_long(42)
>>>
-Note that :mod:`ctypes` does not have OOR (original object return), it constructs a
+Note that :mod:`!ctypes` does not have OOR (original object return), it constructs a
new, equivalent object each time you retrieve an attribute::
>>> pi.contents is i
@@ -854,7 +862,7 @@ item.
Behind the scenes, the :func:`pointer` function does more than simply create
pointer instances, it has to create pointer *types* first. This is done with the
-:func:`POINTER` function, which accepts any :mod:`ctypes` type, and returns a
+:func:`POINTER` function, which accepts any :mod:`!ctypes` type, and returns a
new type::
>>> PI = POINTER(c_int)
@@ -876,7 +884,7 @@ Calling the pointer type without an argument creates a ``NULL`` pointer.
False
>>>
-:mod:`ctypes` checks for ``NULL`` when dereferencing pointers (but dereferencing
+:mod:`!ctypes` checks for ``NULL`` when dereferencing pointers (but dereferencing
invalid non-\ ``NULL`` pointers would crash Python)::
>>> null_ptr[0]
@@ -961,7 +969,7 @@ To set a POINTER type field to ``NULL``, you can assign ``None``::
.. XXX list other conversions...
Sometimes you have instances of incompatible types. In C, you can cast one type
-into another type. :mod:`ctypes` provides a :func:`cast` function which can be
+into another type. :mod:`!ctypes` provides a :func:`cast` function which can be
used in the same way. The ``Bar`` structure defined above accepts
``POINTER(c_int)`` pointers or :class:`c_int` arrays for its ``values`` field,
but not instances of other types::
@@ -1025,7 +1033,7 @@ work::
>>>
because the new ``class cell`` is not available in the class statement itself.
-In :mod:`ctypes`, we can define the ``cell`` class and set the
+In :mod:`!ctypes`, we can define the ``cell`` class and set the
:attr:`~Structure._fields_` attribute later, after the class statement::
>>> from ctypes import *
@@ -1059,7 +1067,7 @@ other, and finally follow the pointer chain a few times::
Callback functions
^^^^^^^^^^^^^^^^^^
-:mod:`ctypes` allows creating C callable function pointers from Python callables.
+:mod:`!ctypes` allows creating C callable function pointers from Python callables.
These are sometimes called *callback functions*.
First, you must create a class for the callback function. The class knows the
@@ -1158,7 +1166,7 @@ write::
.. note::
Make sure you keep references to :func:`CFUNCTYPE` objects as long as they
- are used from C code. :mod:`ctypes` doesn't, and if you don't, they may be
+ are used from C code. :mod:`!ctypes` doesn't, and if you don't, they may be
garbage collected, crashing your program when a callback is made.
Also, note that if the callback function is called in a thread created
@@ -1177,7 +1185,7 @@ Some shared libraries not only export functions, they also export variables. An
example in the Python library itself is the :c:data:`Py_Version`, Python
runtime version number encoded in a single constant integer.
-:mod:`ctypes` can access values like this with the :meth:`~_CData.in_dll` class methods of
+:mod:`!ctypes` can access values like this with the :meth:`~_CData.in_dll` class methods of
the type. *pythonapi* is a predefined symbol giving access to the Python C
api::
@@ -1196,7 +1204,7 @@ Quoting the docs for that value:
tricks with this to provide a dynamically created collection of frozen modules.
So manipulating this pointer could even prove useful. To restrict the example
-size, we show only how this table can be read with :mod:`ctypes`::
+size, we show only how this table can be read with :mod:`!ctypes`::
>>> from ctypes import *
>>>
@@ -1242,7 +1250,7 @@ for testing. Try it out with ``import __hello__`` for example.
Surprises
^^^^^^^^^
-There are some edges in :mod:`ctypes` where you might expect something other
+There are some edges in :mod:`!ctypes` where you might expect something other
than what actually happens.
Consider the following example::
@@ -1310,7 +1318,7 @@ constructs a new Python object each time!
Variable-sized data types
^^^^^^^^^^^^^^^^^^^^^^^^^
-:mod:`ctypes` provides some support for variable-sized arrays and structures.
+:mod:`!ctypes` provides some support for variable-sized arrays and structures.
The :func:`resize` function can be used to resize the memory buffer of an
existing ctypes object. The function takes the object as first argument, and
@@ -1344,7 +1352,7 @@ get errors accessing other elements::
IndexError: invalid index
>>>
-Another way to use variable-sized data types with :mod:`ctypes` is to use the
+Another way to use variable-sized data types with :mod:`!ctypes` is to use the
dynamic nature of Python, and (re-)define the data type after the required size
is already known, on a case by case basis.
@@ -1425,7 +1433,7 @@ On Windows, :func:`~ctypes.util.find_library` searches along the system search p
returns the full pathname, but since there is no predefined naming scheme a call
like ``find_library("c")`` will fail and return ``None``.
-If wrapping a shared library with :mod:`ctypes`, it *may* be better to determine
+If wrapping a shared library with :mod:`!ctypes`, it *may* be better to determine
the shared library name at development time, and hardcode that into the wrapper
module instead of using :func:`~ctypes.util.find_library` to locate the library at runtime.
@@ -1458,14 +1466,82 @@ Loading shared libraries
^^^^^^^^^^^^^^^^^^^^^^^^
There are several ways to load shared libraries into the Python process. One
-way is to instantiate one of the following classes:
+way is to instantiate :py:class:`CDLL` or one of its subclasses:
.. class:: CDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)
- Instances of this class represent loaded shared libraries. Functions in these
- libraries use the standard C calling convention, and are assumed to return
- :c:expr:`int`.
+ Represents a loaded shared library.
+
+ Functions in this library use the standard C calling convention, and are
+ assumed to return :c:expr:`int`.
+ The Python :term:`global interpreter lock` is released before calling any
+ function exported by these libraries, and reacquired afterwards.
+ For different function behavior, use a subclass: :py:class:`~ctypes.OleDLL`,
+ :py:class:`~ctypes.WinDLL`, or :py:class:`~ctypes.PyDLL`.
+
+ If you have an existing :py:attr:`handle <ctypes.CDLL._handle>` to an already
+ loaded shared library, it can be passed as the *handle* argument to wrap
+ the opened library in a new :py:class:`!CDLL` object.
+ In this case, *name* is only used to set the :py:attr:`~ctypes.CDLL._name`
+ attribute, but it may be adjusted and/or validated.
+
+ If *handle* is ``None``, the underlying platform's :manpage:`dlopen(3)` or
+ :c:func:`!LoadLibrary` function is used to load the library into
+ the process, and to get a handle to it.
+
+ *name* is the pathname of the shared library to open.
+ If *name* does not contain a path separator, the library is found
+ in a platform-specific way.
+
+ On non-Windows systems, *name* can be ``None``. In this case,
+ :c:func:`!dlopen` is called with ``NULL``, which opens the main program
+ as a "library".
+ (Some systems do the same is *name* is empty; ``None``/``NULL`` is more
+ portable.)
+
+ .. admonition:: CPython implementation detail
+
+ Since CPython is linked to ``libc``, a ``None`` *name* is often used
+ to access the C standard library::
+
+ >>> printf = ctypes.CDLL(None).printf
+ >>> printf.argtypes = [ctypes.c_char_p]
+ >>> printf(b"hello\n")
+ hello
+ 6
+
+ To access the Python C API, prefer :py:data:`ctypes.pythonapi` which
+ works across platforms.
+
+ The *mode* parameter can be used to specify how the library is loaded. For
+ details, consult the :manpage:`dlopen(3)` manpage. On Windows, *mode* is
+ ignored. On posix systems, RTLD_NOW is always added, and is not
+ configurable.
+
+ The *use_errno* parameter, when set to true, enables a ctypes mechanism that
+ allows accessing the system :data:`errno` error number in a safe way.
+ :mod:`!ctypes` maintains a thread-local copy of the system's :data:`errno`
+ variable; if you call foreign functions created with ``use_errno=True`` then the
+ :data:`errno` value before the function call is swapped with the ctypes private
+ copy, the same happens immediately after the function call.
+
+ The function :func:`ctypes.get_errno` returns the value of the ctypes private
+ copy, and the function :func:`ctypes.set_errno` changes the ctypes private copy
+ to a new value and returns the former value.
+
+ The *use_last_error* parameter, when set to true, enables the same mechanism for
+ the Windows error code which is managed by the :func:`GetLastError` and
+ :func:`!SetLastError` Windows API functions; :func:`ctypes.get_last_error` and
+ :func:`ctypes.set_last_error` are used to request and change the ctypes private
+ copy of the windows error code.
+
+ The *winmode* parameter is used on Windows to specify how the library is loaded
+ (since *mode* is ignored). It takes any value that is valid for the Win32 API
+ ``LoadLibraryEx`` flags parameter. When omitted, the default is to use the
+ flags that result in the most secure DLL load, which avoids issues such as DLL
+ hijacking. Passing the full path to the DLL is the safest way to ensure the
+ correct library and dependencies are loaded.
On Windows creating a :class:`CDLL` instance may fail even if the DLL name
exists. When a dependent DLL of the loaded DLL is not found, a
@@ -1477,20 +1553,47 @@ way is to instantiate one of the following classes:
DLLs and determine which one is not found using Windows debugging and
tracing tools.
+ .. seealso::
+
+ `Microsoft DUMPBIN tool <https://learn.microsoft.com/en-us/cpp/build/reference/dumpbin-reference?view=msvc-170>`_
+ -- A tool to find DLL dependents.
+
+ .. versionchanged:: 3.8
+ Added *winmode* parameter.
+
.. versionchanged:: 3.12
The *name* parameter can now be a :term:`path-like object`.
-.. seealso::
+ Instances of this class have no public methods. Functions exported by the
+ shared library can be accessed as attributes or by index. Please note that
+ accessing the function through an attribute caches the result and therefore
+ accessing it repeatedly returns the same object each time. On the other hand,
+ accessing it through an index returns a new object each time::
+
+ >>> from ctypes import CDLL
+ >>> libc = CDLL("libc.so.6") # On Linux
+ >>> libc.time == libc.time
+ True
+ >>> libc['time'] == libc['time']
+ False
+
+ The following public attributes are available. Their name starts with an
+ underscore to not clash with exported function names:
+
+ .. attribute:: _handle
+
+ The system handle used to access the library.
- `Microsoft DUMPBIN tool <https://docs.microsoft.com/cpp/build/reference/dependents>`_
- -- A tool to find DLL dependents.
+ .. attribute:: _name
+ The name of the library passed in the constructor.
-.. class:: OleDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)
+.. class:: OleDLL
- Instances of this class represent loaded shared libraries,
- functions in these libraries use the ``stdcall`` calling convention, and are
+ See :py:class:`~ctypes.CDLL`, the superclass, for common information.
+
+ Functions in this library use the ``stdcall`` calling convention, and are
assumed to return the windows specific :class:`HRESULT` code. :class:`HRESULT`
values contain information specifying whether the function call failed or
succeeded, together with additional error code. If the return value signals a
@@ -1502,133 +1605,51 @@ way is to instantiate one of the following classes:
:exc:`WindowsError` used to be raised,
which is now an alias of :exc:`OSError`.
- .. versionchanged:: 3.12
-
- The *name* parameter can now be a :term:`path-like object`.
+.. class:: WinDLL
-.. class:: WinDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)
+ See :py:class:`~ctypes.CDLL`, the superclass, for common information.
- Instances of this class represent loaded shared libraries,
- functions in these libraries use the ``stdcall`` calling convention, and are
+ Functions in these libraries use the ``stdcall`` calling convention, and are
assumed to return :c:expr:`int` by default.
.. availability:: Windows
- .. versionchanged:: 3.12
+.. class:: PyDLL
- The *name* parameter can now be a :term:`path-like object`.
+ See :py:class:`~ctypes.CDLL`, the superclass, for common information.
-
-The Python :term:`global interpreter lock` is released before calling any
-function exported by these libraries, and reacquired afterwards.
-
-
-.. class:: PyDLL(name, mode=DEFAULT_MODE, handle=None)
-
- Instances of this class behave like :class:`CDLL` instances, except that the
+ When functions in this library are called, the
Python GIL is *not* released during the function call, and after the function
execution the Python error flag is checked. If the error flag is set, a Python
exception is raised.
- Thus, this is only useful to call Python C api functions directly.
-
- .. versionchanged:: 3.12
-
- The *name* parameter can now be a :term:`path-like object`.
-
-All these classes can be instantiated by calling them with at least one
-argument, the pathname of the shared library. If you have an existing handle to
-an already loaded shared library, it can be passed as the ``handle`` named
-parameter, otherwise the underlying platform's :c:func:`!dlopen` or
-:c:func:`!LoadLibrary` function is used to load the library into
-the process, and to get a handle to it.
-
-The *mode* parameter can be used to specify how the library is loaded. For
-details, consult the :manpage:`dlopen(3)` manpage. On Windows, *mode* is
-ignored. On posix systems, RTLD_NOW is always added, and is not
-configurable.
-
-The *use_errno* parameter, when set to true, enables a ctypes mechanism that
-allows accessing the system :data:`errno` error number in a safe way.
-:mod:`ctypes` maintains a thread-local copy of the system's :data:`errno`
-variable; if you call foreign functions created with ``use_errno=True`` then the
-:data:`errno` value before the function call is swapped with the ctypes private
-copy, the same happens immediately after the function call.
-
-The function :func:`ctypes.get_errno` returns the value of the ctypes private
-copy, and the function :func:`ctypes.set_errno` changes the ctypes private copy
-to a new value and returns the former value.
-
-The *use_last_error* parameter, when set to true, enables the same mechanism for
-the Windows error code which is managed by the :func:`GetLastError` and
-:func:`!SetLastError` Windows API functions; :func:`ctypes.get_last_error` and
-:func:`ctypes.set_last_error` are used to request and change the ctypes private
-copy of the windows error code.
-
-The *winmode* parameter is used on Windows to specify how the library is loaded
-(since *mode* is ignored). It takes any value that is valid for the Win32 API
-``LoadLibraryEx`` flags parameter. When omitted, the default is to use the
-flags that result in the most secure DLL load, which avoids issues such as DLL
-hijacking. Passing the full path to the DLL is the safest way to ensure the
-correct library and dependencies are loaded.
-
-.. versionchanged:: 3.8
- Added *winmode* parameter.
+ Thus, this is only useful to call Python C API functions directly.
.. data:: RTLD_GLOBAL
- :noindex:
Flag to use as *mode* parameter. On platforms where this flag is not available,
it is defined as the integer zero.
.. data:: RTLD_LOCAL
- :noindex:
Flag to use as *mode* parameter. On platforms where this is not available, it
is the same as *RTLD_GLOBAL*.
.. data:: DEFAULT_MODE
- :noindex:
The default mode which is used to load shared libraries. On OSX 10.3, this is
*RTLD_GLOBAL*, otherwise it is the same as *RTLD_LOCAL*.
-Instances of these classes have no public methods. Functions exported by the
-shared library can be accessed as attributes or by index. Please note that
-accessing the function through an attribute caches the result and therefore
-accessing it repeatedly returns the same object each time. On the other hand,
-accessing it through an index returns a new object each time::
-
- >>> from ctypes import CDLL
- >>> libc = CDLL("libc.so.6") # On Linux
- >>> libc.time == libc.time
- True
- >>> libc['time'] == libc['time']
- False
-
-The following public attributes are available, their name starts with an
-underscore to not clash with exported function names:
-
-
-.. attribute:: PyDLL._handle
-
- The system handle used to access the library.
-
-
-.. attribute:: PyDLL._name
-
- The name of the library passed in the constructor.
Shared libraries can also be loaded by using one of the prefabricated objects,
which are instances of the :class:`LibraryLoader` class, either by calling the
:meth:`~LibraryLoader.LoadLibrary` method, or by retrieving the library as
attribute of the loader instance.
-
.. class:: LibraryLoader(dlltype)
Class which loads shared libraries. *dlltype* should be one of the
@@ -1647,13 +1668,11 @@ attribute of the loader instance.
These prefabricated library loaders are available:
.. data:: cdll
- :noindex:
Creates :class:`CDLL` instances.
.. data:: windll
- :noindex:
Creates :class:`WinDLL` instances.
@@ -1661,7 +1680,6 @@ These prefabricated library loaders are available:
.. data:: oledll
- :noindex:
Creates :class:`OleDLL` instances.
@@ -1669,7 +1687,6 @@ These prefabricated library loaders are available:
.. data:: pydll
- :noindex:
Creates :class:`PyDLL` instances.
@@ -1678,7 +1695,6 @@ For accessing the C Python api directly, a ready-to-use Python shared library
object is available:
.. data:: pythonapi
- :noindex:
An instance of :class:`PyDLL` that exposes Python C API functions as
attributes. Note that all these functions are assumed to return C
@@ -1929,7 +1945,7 @@ the windows header file is this::
LPCWSTR lpCaption,
UINT uType);
-Here is the wrapping with :mod:`ctypes`::
+Here is the wrapping with :mod:`!ctypes`::
>>> from ctypes import c_int, WINFUNCTYPE, windll
>>> from ctypes.wintypes import HWND, LPCWSTR, UINT
@@ -1952,7 +1968,7 @@ function retrieves the dimensions of a specified window by copying them into
HWND hWnd,
LPRECT lpRect);
-Here is the wrapping with :mod:`ctypes`::
+Here is the wrapping with :mod:`!ctypes`::
>>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError
>>> from ctypes.wintypes import BOOL, HWND, RECT
@@ -1980,7 +1996,7 @@ do the error checking, and raises an exception when the api call failed::
>>>
If the :attr:`~_CFuncPtr.errcheck` function returns the argument tuple it receives
-unchanged, :mod:`ctypes` continues the normal processing it does on the output
+unchanged, :mod:`!ctypes` continues the normal processing it does on the output
parameters. If you want to return a tuple of window coordinates instead of a
``RECT`` instance, you can retrieve the fields in the function and return them
instead, the normal processing will no longer take place::
@@ -2450,7 +2466,7 @@ Fundamental data types
Python bytes object or string.
When the ``value`` attribute is retrieved from a ctypes instance, usually
- a new object is returned each time. :mod:`ctypes` does *not* implement
+ a new object is returned each time. :mod:`!ctypes` does *not* implement
original object return, always a new object is constructed. The same is
true for all other ctypes object instances.
@@ -2749,7 +2765,7 @@ fields, or any other data types containing pointer type fields.
Abstract base class for structures in *native* byte order.
Concrete structure and union types must be created by subclassing one of these
- types, and at least define a :attr:`_fields_` class variable. :mod:`ctypes` will
+ types, and at least define a :attr:`_fields_` class variable. :mod:`!ctypes` will
create :term:`descriptor`\s which allow reading and writing the fields by direct
attribute accesses. These are the
@@ -2803,7 +2819,7 @@ fields, or any other data types containing pointer type fields.
Setting :attr:`!_pack_` to 0 is the same as not setting it at all.
Otherwise, the value must be a positive power of two.
The effect is equivalent to ``#pragma pack(N)`` in C, except
- :mod:`ctypes` may allow larger *n* than what the compiler accepts.
+ :mod:`!ctypes` may allow larger *n* than what the compiler accepts.
:attr:`!_pack_` must already be defined
when :attr:`_fields_` is assigned, otherwise it will have no effect.
@@ -2824,7 +2840,7 @@ fields, or any other data types containing pointer type fields.
The value must not be negative.
The effect is equivalent to ``__attribute__((aligned(N)))`` on GCC
- or ``#pragma align(N)`` on MSVC, except :mod:`ctypes` may allow
+ or ``#pragma align(N)`` on MSVC, except :mod:`!ctypes` may allow
values that the compiler would reject.
:attr:`!_align_` can only *increase* a structure's alignment
@@ -2873,7 +2889,7 @@ fields, or any other data types containing pointer type fields.
assigned, otherwise it will have no effect.
The fields listed in this variable must be structure or union type fields.
- :mod:`ctypes` will create descriptors in the structure type that allows
+ :mod:`!ctypes` will create descriptors in the structure type that allows
accessing the nested fields directly, without the need to create the
structure or union field.
@@ -3017,7 +3033,7 @@ Arrays and pointers
Abstract base class for arrays.
The recommended way to create concrete array types is by multiplying any
- :mod:`ctypes` data type with a non-negative integer. Alternatively, you can subclass
+ :mod:`!ctypes` data type with a non-negative integer. Alternatively, you can subclass
this type and define :attr:`_length_` and :attr:`_type_` class variables.
Array elements can be read and written using standard
subscript and slice accesses; for slice reads, the resulting object is
@@ -3043,7 +3059,7 @@ Arrays and pointers
Create an array.
Equivalent to ``type * length``, where *type* is a
- :mod:`ctypes` data type and *length* an integer.
+ :mod:`!ctypes` data type and *length* an integer.
This function is :term:`soft deprecated` in favor of multiplication.
There are no plans to remove it.
diff --git a/Doc/library/curses.ascii.rst b/Doc/library/curses.ascii.rst
index cb895664ff1..4910954b778 100644
--- a/Doc/library/curses.ascii.rst
+++ b/Doc/library/curses.ascii.rst
@@ -11,7 +11,7 @@
--------------
-The :mod:`curses.ascii` module supplies name constants for ASCII characters and
+The :mod:`!curses.ascii` module supplies name constants for ASCII characters and
functions to test membership in various ASCII character classes. The constants
supplied are names for control characters as follows:
diff --git a/Doc/library/curses.panel.rst b/Doc/library/curses.panel.rst
index 11fd841d381..e52f588c5bc 100644
--- a/Doc/library/curses.panel.rst
+++ b/Doc/library/curses.panel.rst
@@ -18,7 +18,7 @@ displayed. Panels can be added, moved up or down in the stack, and removed.
Functions
---------
-The module :mod:`curses.panel` defines the following functions:
+The module :mod:`!curses.panel` defines the following functions:
.. function:: bottom_panel()
diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst
index 057d338edda..2dc638b3d40 100644
--- a/Doc/library/curses.rst
+++ b/Doc/library/curses.rst
@@ -4,7 +4,6 @@
.. module:: curses
:synopsis: An interface to the curses library, providing portable
terminal handling.
- :platform: Unix
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
.. sectionauthor:: Eric Raymond <esr@thyrsus.com>
@@ -13,7 +12,7 @@
--------------
-The :mod:`curses` module provides an interface to the curses library, the
+The :mod:`!curses` module provides an interface to the curses library, the
de-facto standard for portable advanced terminal handling.
While curses is most widely used in the Unix environment, versions are available
@@ -25,6 +24,8 @@ Linux and the BSD variants of Unix.
.. include:: ../includes/optional-module.rst
+.. availability:: Unix.
+
.. note::
Whenever the documentation mentions a *character* it can be specified
@@ -54,7 +55,7 @@ Linux and the BSD variants of Unix.
Functions
---------
-The module :mod:`curses` defines the following exception:
+The module :mod:`!curses` defines the following exception:
.. exception:: error
@@ -67,7 +68,7 @@ The module :mod:`curses` defines the following exception:
default to the current cursor location. Whenever *attr* is optional, it defaults
to :const:`A_NORMAL`.
-The module :mod:`curses` defines the following functions:
+The module :mod:`!curses` defines the following functions:
.. function:: assume_default_colors(fg, bg, /)
@@ -581,7 +582,7 @@ The module :mod:`curses` defines the following functions:
after :func:`initscr`.
:func:`start_color` initializes eight basic colors (black, red, green, yellow,
- blue, magenta, cyan, and white), and two global variables in the :mod:`curses`
+ blue, magenta, cyan, and white), and two global variables in the :mod:`!curses`
module, :const:`COLORS` and :const:`COLOR_PAIRS`, containing the maximum number
of colors and color-pairs the terminal can support. It also restores the colors
on the terminal to the values they had when the terminal was just turned on.
@@ -1021,7 +1022,7 @@ Window Objects
.. method:: window.idlok(flag)
- If *flag* is ``True``, :mod:`curses` will try and use hardware line
+ If *flag* is ``True``, :mod:`!curses` will try and use hardware line
editing facilities. Otherwise, line insertion/deletion are disabled.
@@ -1109,7 +1110,7 @@ Window Objects
.. method:: window.keypad(flag)
If *flag* is ``True``, escape sequences generated by some keys (keypad, function keys)
- will be interpreted by :mod:`curses`. If *flag* is ``False``, escape sequences will be
+ will be interpreted by :mod:`!curses`. If *flag* is ``False``, escape sequences will be
left as is in the input stream.
@@ -1335,7 +1336,7 @@ Window Objects
Constants
---------
-The :mod:`curses` module defines the following data members:
+The :mod:`!curses` module defines the following data members:
.. data:: ERR
@@ -1824,8 +1825,8 @@ The following table lists the predefined colors:
+-------------------------+----------------------------+
-:mod:`curses.textpad` --- Text input widget for curses programs
-===============================================================
+:mod:`!curses.textpad` --- Text input widget for curses programs
+================================================================
.. module:: curses.textpad
:synopsis: Emacs-like input editing in a curses window.
@@ -1833,13 +1834,13 @@ The following table lists the predefined colors:
.. sectionauthor:: Eric Raymond <esr@thyrsus.com>
-The :mod:`curses.textpad` module provides a :class:`Textbox` class that handles
+The :mod:`!curses.textpad` module provides a :class:`Textbox` class that handles
elementary text editing in a curses window, supporting a set of keybindings
resembling those of Emacs (thus, also of Netscape Navigator, BBedit 6.x,
FrameMaker, and many other programs). The module also provides a
rectangle-drawing function useful for framing text boxes or for other purposes.
-The module :mod:`curses.textpad` defines the following function:
+The module :mod:`!curses.textpad` defines the following function:
.. function:: rectangle(win, uly, ulx, lry, lrx)
diff --git a/Doc/library/datetime-inheritance.dot b/Doc/library/datetime-inheritance.dot
new file mode 100644
index 00000000000..3c6b9b4beb7
--- /dev/null
+++ b/Doc/library/datetime-inheritance.dot
@@ -0,0 +1,31 @@
+// Used to generate datetime-inheritance.svg with Graphviz
+// (https://graphviz.org/) for the datetime documentation.
+
+digraph {
+ comment="Generated with datetime-inheritance.dot"
+ graph [
+ bgcolor="transparent"
+ fontnames="svg"
+ layout="dot"
+ ranksep=0.5
+ nodesep=0.5
+ splines=line
+ ]
+ node [
+ fontname="Courier"
+ fontsize=14.0
+ shape=box
+ style=rounded
+ margin="0.15,0.07"
+ ]
+ edge [
+ arrowhead=none
+ ]
+
+ object -> tzinfo
+ object -> timedelta
+ object -> time
+ object -> date
+ tzinfo -> timezone
+ date -> datetime
+}
diff --git a/Doc/library/datetime-inheritance.svg b/Doc/library/datetime-inheritance.svg
new file mode 100644
index 00000000000..e6b1cf877a5
--- /dev/null
+++ b/Doc/library/datetime-inheritance.svg
@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 12.2.1 (20241206.2353)
+ -->
+<!-- Title: datetime class hierarchy Pages: 1 -->
+<svg width="386pt" height="188pt"
+ viewBox="0.00 0.00 385.60 188.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 184)">
+<title>datetime class hierarchy</title>
+<!-- object -->
+<g id="node1" class="node">
+<title>object</title>
+<path fill="none" stroke="black" d="M216.85,-180C216.85,-180 178.75,-180 178.75,-180 172.75,-180 166.75,-174 166.75,-168 166.75,-168 166.75,-156 166.75,-156 166.75,-150 172.75,-144 178.75,-144 178.75,-144 216.85,-144 216.85,-144 222.85,-144 228.85,-150 228.85,-156 228.85,-156 228.85,-168 228.85,-168 228.85,-174 222.85,-180 216.85,-180"/>
+<text text-anchor="middle" x="197.8" y="-156.57" font-family="monospace,monospace" font-size="14.00">object</text>
+</g>
+<!-- tzinfo -->
+<g id="node2" class="node">
+<title>tzinfo</title>
+<path fill="none" stroke="black" d="M56.85,-108C56.85,-108 18.75,-108 18.75,-108 12.75,-108 6.75,-102 6.75,-96 6.75,-96 6.75,-84 6.75,-84 6.75,-78 12.75,-72 18.75,-72 18.75,-72 56.85,-72 56.85,-72 62.85,-72 68.85,-78 68.85,-84 68.85,-84 68.85,-96 68.85,-96 68.85,-102 62.85,-108 56.85,-108"/>
+<text text-anchor="middle" x="37.8" y="-84.58" font-family="monospace,monospace" font-size="14.00">tzinfo</text>
+</g>
+<!-- object->tzinfo -->
+<g id="edge1" class="edge">
+<title>object->tzinfo</title>
+<path fill="none" stroke="black" d="M166.57,-147.34C138.47,-135.04 97.38,-117.07 69.22,-104.75"/>
+</g>
+<!-- timedelta -->
+<g id="node3" class="node">
+<title>timedelta</title>
+<path fill="none" stroke="black" d="M174.98,-108C174.98,-108 116.63,-108 116.63,-108 110.63,-108 104.63,-102 104.63,-96 104.63,-96 104.63,-84 104.63,-84 104.63,-78 110.63,-72 116.63,-72 116.63,-72 174.98,-72 174.98,-72 180.98,-72 186.98,-78 186.98,-84 186.98,-84 186.98,-96 186.98,-96 186.98,-102 180.98,-108 174.98,-108"/>
+<text text-anchor="middle" x="145.8" y="-84.58" font-family="monospace,monospace" font-size="14.00">timedelta</text>
+</g>
+<!-- object->timedelta -->
+<g id="edge2" class="edge">
+<title>object->timedelta</title>
+<path fill="none" stroke="black" d="M184.95,-143.7C176.89,-132.85 166.54,-118.92 158.51,-108.1"/>
+</g>
+<!-- time -->
+<g id="node4" class="node">
+<title>time</title>
+<path fill="none" stroke="black" d="M264.8,-108C264.8,-108 234.8,-108 234.8,-108 228.8,-108 222.8,-102 222.8,-96 222.8,-96 222.8,-84 222.8,-84 222.8,-78 228.8,-72 234.8,-72 234.8,-72 264.8,-72 264.8,-72 270.8,-72 276.8,-78 276.8,-84 276.8,-84 276.8,-96 276.8,-96 276.8,-102 270.8,-108 264.8,-108"/>
+<text text-anchor="middle" x="249.8" y="-84.58" font-family="monospace,monospace" font-size="14.00">time</text>
+</g>
+<!-- object->time -->
+<g id="edge3" class="edge">
+<title>object->time</title>
+<path fill="none" stroke="black" d="M210.65,-143.7C218.71,-132.85 229.06,-118.92 237.09,-108.1"/>
+</g>
+<!-- date -->
+<g id="node5" class="node">
+<title>date</title>
+<path fill="none" stroke="black" d="M354.8,-108C354.8,-108 324.8,-108 324.8,-108 318.8,-108 312.8,-102 312.8,-96 312.8,-96 312.8,-84 312.8,-84 312.8,-78 318.8,-72 324.8,-72 324.8,-72 354.8,-72 354.8,-72 360.8,-72 366.8,-78 366.8,-84 366.8,-84 366.8,-96 366.8,-96 366.8,-102 360.8,-108 354.8,-108"/>
+<text text-anchor="middle" x="339.8" y="-84.58" font-family="monospace,monospace" font-size="14.00">date</text>
+</g>
+<!-- object->date -->
+<g id="edge4" class="edge">
+<title>object->date</title>
+<path fill="none" stroke="black" d="M229.31,-145.46C254.32,-133.14 288.9,-116.09 312.68,-104.37"/>
+</g>
+<!-- timezone -->
+<g id="node6" class="node">
+<title>timezone</title>
+<path fill="none" stroke="black" d="M63.6,-36C63.6,-36 12,-36 12,-36 6,-36 0,-30 0,-24 0,-24 0,-12 0,-12 0,-6 6,0 12,0 12,0 63.6,0 63.6,0 69.6,0 75.6,-6 75.6,-12 75.6,-12 75.6,-24 75.6,-24 75.6,-30 69.6,-36 63.6,-36"/>
+<text text-anchor="middle" x="37.8" y="-12.57" font-family="monospace,monospace" font-size="14.00">timezone</text>
+</g>
+<!-- tzinfo->timezone -->
+<g id="edge5" class="edge">
+<title>tzinfo->timezone</title>
+<path fill="none" stroke="black" d="M37.8,-71.7C37.8,-60.85 37.8,-46.92 37.8,-36.1"/>
+</g>
+<!-- datetime -->
+<g id="node7" class="node">
+<title>datetime</title>
+<path fill="none" stroke="black" d="M365.6,-36C365.6,-36 314,-36 314,-36 308,-36 302,-30 302,-24 302,-24 302,-12 302,-12 302,-6 308,0 314,0 314,0 365.6,0 365.6,0 371.6,0 377.6,-6 377.6,-12 377.6,-12 377.6,-24 377.6,-24 377.6,-30 371.6,-36 365.6,-36"/>
+<text text-anchor="middle" x="339.8" y="-12.57" font-family="monospace,monospace" font-size="14.00">datetime</text>
+</g>
+<!-- date->datetime -->
+<g id="edge6" class="edge">
+<title>date->datetime</title>
+<path fill="none" stroke="black" d="M339.8,-71.7C339.8,-60.85 339.8,-46.92 339.8,-36.1"/>
+</g>
+</g>
+</svg>
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index c17ff8986ab..beef4f09f02 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -12,8 +12,6 @@
--------------
-.. XXX what order should the types be discussed in?
-
The :mod:`!datetime` module supplies classes for manipulating dates and times.
While date and time arithmetic is supported, the focus of the implementation is
@@ -38,13 +36,14 @@ on efficient attribute extraction for output formatting and manipulation.
Third-party library with expanded time zone and parsing support.
Package :pypi:`DateType`
- Third-party library that introduces distinct static types to e.g. allow
- :term:`static type checkers <static type checker>`
+ Third-party library that introduces distinct static types to for example,
+ allow :term:`static type checkers <static type checker>`
to differentiate between naive and aware datetimes.
+
.. _datetime-naive-aware:
-Aware and Naive Objects
+Aware and naive objects
-----------------------
Date and time objects may be categorized as "aware" or "naive" depending on
@@ -65,7 +64,7 @@ understand and to work with, at the cost of ignoring some aspects of reality.
For applications requiring aware objects, :class:`.datetime` and :class:`.time`
objects have an optional time zone information attribute, :attr:`!tzinfo`, that
-can be set to an instance of a subclass of the abstract :class:`tzinfo` class.
+can be set to an instance of a subclass of the abstract :class:`!tzinfo` class.
These :class:`tzinfo` objects capture information about the offset from UTC
time, the time zone name, and whether daylight saving time is in effect.
@@ -77,6 +76,7 @@ detail is up to the application. The rules for time adjustment across the
world are more political than rational, change frequently, and there is no
standard suitable for every application aside from UTC.
+
Constants
---------
@@ -93,13 +93,15 @@ The :mod:`!datetime` module exports the following constants:
The largest year number allowed in a :class:`date` or :class:`.datetime` object.
:const:`MAXYEAR` is 9999.
+
.. data:: UTC
Alias for the UTC time zone singleton :attr:`datetime.timezone.utc`.
.. versionadded:: 3.11
-Available Types
+
+Available types
---------------
.. class:: date
@@ -142,6 +144,7 @@ Available Types
time adjustment (for example, to account for time zone and/or daylight saving
time).
+
.. class:: timezone
:noindex:
@@ -150,19 +153,19 @@ Available Types
.. versionadded:: 3.2
+
Objects of these types are immutable.
-Subclass relationships::
+Subclass relationships:
- object
- timedelta
- tzinfo
- timezone
- time
- date
- datetime
+.. figure:: datetime-inheritance.svg
+ :class: invert-in-dark-mode
+ :align: center
+ :alt: timedelta, tzinfo, time, and date inherit from object; timezone inherits
+ from tzinfo; and datetime inherits from date.
-Common Properties
+
+Common properties
^^^^^^^^^^^^^^^^^
The :class:`date`, :class:`.datetime`, :class:`.time`, and :class:`timezone` types
@@ -173,7 +176,8 @@ share these common features:
dictionary keys.
- Objects of these types support efficient pickling via the :mod:`pickle` module.
-Determining if an Object is Aware or Naive
+
+Determining if an object is aware or naive
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Objects of the :class:`date` type are always naive.
@@ -197,10 +201,11 @@ Otherwise, ``t`` is naive.
The distinction between aware and naive doesn't apply to :class:`timedelta`
objects.
+
.. _datetime-timedelta:
-:class:`timedelta` Objects
---------------------------
+:class:`!timedelta` objects
+---------------------------
A :class:`timedelta` object represents a duration, the difference between two
:class:`.datetime` or :class:`date` instances.
@@ -229,8 +234,8 @@ A :class:`timedelta` object represents a duration, the difference between two
*days*, *seconds* and *microseconds* are "merged" and normalized into those
three resulting attributes::
- >>> from datetime import timedelta
- >>> delta = timedelta(
+ >>> import datetime as dt
+ >>> delta = dt.timedelta(
... days=50,
... seconds=27,
... microseconds=10,
@@ -243,6 +248,12 @@ A :class:`timedelta` object represents a duration, the difference between two
>>> delta
datetime.timedelta(days=64, seconds=29156, microseconds=10)
+ .. tip::
+ ``import datetime as dt`` instead of ``import datetime`` or
+ ``from datetime import datetime`` to avoid confusion between the module
+ and the class. See `How I Import Python’s datetime Module
+ <https://adamj.eu/tech/2019/09/12/how-i-import-pythons-datetime-module/>`__.
+
If any argument is a float and there are fractional microseconds,
the fractional microseconds left over from all arguments are
combined and their sum is rounded to the nearest microsecond using
@@ -256,8 +267,8 @@ A :class:`timedelta` object represents a duration, the difference between two
Note that normalization of negative values may be surprising at first. For
example::
- >>> from datetime import timedelta
- >>> d = timedelta(microseconds=-1)
+ >>> import datetime as dt
+ >>> d = dt.timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)
@@ -296,6 +307,7 @@ Class attributes:
The smallest possible difference between non-equal :class:`timedelta` objects,
``timedelta(microseconds=1)``.
+
Note that, because of normalization, ``timedelta.max`` is greater than ``-timedelta.min``.
``-timedelta.max`` is not representable as a :class:`timedelta` object.
@@ -319,13 +331,14 @@ Instance attributes (read-only):
.. doctest::
- >>> from datetime import timedelta
- >>> duration = timedelta(seconds=11235813)
+ >>> import datetime as dt
+ >>> duration = dt.timedelta(seconds=11235813)
>>> duration.days, duration.seconds
(130, 3813)
>>> duration.total_seconds()
11235813.0
+
.. attribute:: timedelta.microseconds
Between 0 and 999,999 inclusive.
@@ -333,8 +346,6 @@ Instance attributes (read-only):
Supported operations:
-.. XXX this table is too wide!
-
+--------------------------------+-----------------------------------------------+
| Operation | Result |
+================================+===============================================+
@@ -396,7 +407,6 @@ Supported operations:
| | call with canonical attribute values. |
+--------------------------------+-----------------------------------------------+
-
Notes:
(1)
@@ -432,9 +442,9 @@ objects (see below).
.. versionchanged:: 3.2
Floor division and true division of a :class:`timedelta` object by another
- :class:`timedelta` object are now supported, as are remainder operations and
+ :class:`!timedelta` object are now supported, as are remainder operations and
the :func:`divmod` function. True division and multiplication of a
- :class:`timedelta` object by a :class:`float` object are now supported.
+ :class:`!timedelta` object by a :class:`float` object are now supported.
:class:`timedelta` objects support equality and order comparisons.
@@ -447,23 +457,24 @@ Instance methods:
Return the total number of seconds contained in the duration. Equivalent to
``td / timedelta(seconds=1)``. For interval units other than seconds, use the
- division form directly (e.g. ``td / timedelta(microseconds=1)``).
+ division form directly (for example, ``td / timedelta(microseconds=1)``).
Note that for very large time intervals (greater than 270 years on
most platforms) this method will lose microsecond accuracy.
.. versionadded:: 3.2
-Examples of usage: :class:`timedelta`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Examples of usage: :class:`!timedelta`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
An additional example of normalization::
>>> # Components of another_year add up to exactly 365 days
- >>> from datetime import timedelta
- >>> year = timedelta(days=365)
- >>> another_year = timedelta(weeks=40, days=84, hours=23,
- ... minutes=50, seconds=600)
+ >>> import datetime as dt
+ >>> year = dt.timedelta(days=365)
+ >>> another_year = dt.timedelta(weeks=40, days=84, hours=23,
+ ... minutes=50, seconds=600)
>>> year == another_year
True
>>> year.total_seconds()
@@ -471,8 +482,8 @@ An additional example of normalization::
Examples of :class:`timedelta` arithmetic::
- >>> from datetime import timedelta
- >>> year = timedelta(days=365)
+ >>> import datetime as dt
+ >>> year = dt.timedelta(days=365)
>>> ten_years = 10 * year
>>> ten_years
datetime.timedelta(days=3650)
@@ -485,10 +496,11 @@ Examples of :class:`timedelta` arithmetic::
>>> three_years, three_years.days // 365
(datetime.timedelta(days=1095), 3)
+
.. _datetime-date:
-:class:`date` Objects
----------------------
+:class:`!date` objects
+----------------------
A :class:`date` object represents a date (year, month and day) in an idealized
calendar, the current Gregorian calendar indefinitely extended in both
@@ -517,9 +529,10 @@ Other constructors, all class methods:
This is equivalent to ``date.fromtimestamp(time.time())``.
+
.. classmethod:: date.fromtimestamp(timestamp)
- Return the local date corresponding to the POSIX timestamp, such as is
+ Return the local date corresponding to the POSIX *timestamp*, such as is
returned by :func:`time.time`.
This may raise :exc:`OverflowError`, if the timestamp is out
@@ -538,7 +551,7 @@ Other constructors, all class methods:
.. classmethod:: date.fromordinal(ordinal)
- Return the date corresponding to the proleptic Gregorian ordinal, where
+ Return the date corresponding to the proleptic Gregorian *ordinal*, where
January 1 of year 1 has ordinal 1.
:exc:`ValueError` is raised unless ``1 <= ordinal <=
@@ -559,25 +572,27 @@ Other constructors, all class methods:
Examples::
- >>> from datetime import date
- >>> date.fromisoformat('2019-12-04')
+ >>> import datetime as dt
+ >>> dt.date.fromisoformat('2019-12-04')
datetime.date(2019, 12, 4)
- >>> date.fromisoformat('20191204')
+ >>> dt.date.fromisoformat('20191204')
datetime.date(2019, 12, 4)
- >>> date.fromisoformat('2021-W01-1')
+ >>> dt.date.fromisoformat('2021-W01-1')
datetime.date(2021, 1, 4)
.. versionadded:: 3.7
.. versionchanged:: 3.11
Previously, this method only supported the format ``YYYY-MM-DD``.
+
.. classmethod:: date.fromisocalendar(year, week, day)
Return a :class:`date` corresponding to the ISO calendar date specified by
- year, week and day. This is the inverse of the function :meth:`date.isocalendar`.
+ *year*, *week* and *day*. This is the inverse of the function :meth:`date.isocalendar`.
.. versionadded:: 3.8
+
.. classmethod:: date.strptime(date_string, format)
Return a :class:`.date` corresponding to *date_string*, parsed according to
@@ -603,9 +618,9 @@ Other constructors, all class methods:
.. doctest::
- >>> from datetime import date
+ >>> import datetime as dt
>>> date_string = "02/29"
- >>> when = date.strptime(f"{date_string};1984", "%m/%d;%Y") # Avoids leap year bug.
+ >>> when = dt.date.strptime(f"{date_string};1984", "%m/%d;%Y") # Avoids leap year bug.
>>> when.strftime("%B %d") # doctest: +SKIP
'February 29'
@@ -697,7 +712,7 @@ Notes:
In other words, ``date1 < date2`` if and only if ``date1.toordinal() <
date2.toordinal()``.
- Order comparison between a :class:`!date` object that is not also a
+ Order comparison between a :class:`date` object that is not also a
:class:`.datetime` instance and a :class:`!datetime` object raises
:exc:`TypeError`.
@@ -720,8 +735,8 @@ Instance methods:
Example::
- >>> from datetime import date
- >>> d = date(2002, 12, 31)
+ >>> import datetime as dt
+ >>> d = dt.date(2002, 12, 31)
>>> d.replace(day=26)
datetime.date(2002, 12, 26)
@@ -779,23 +794,25 @@ Instance methods:
For example, 2004 begins on a Thursday, so the first week of ISO year 2004
begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan 2004::
- >>> from datetime import date
- >>> date(2003, 12, 29).isocalendar()
+ >>> import datetime as dt
+ >>> dt.date(2003, 12, 29).isocalendar()
datetime.IsoCalendarDate(year=2004, week=1, weekday=1)
- >>> date(2004, 1, 4).isocalendar()
+ >>> dt.date(2004, 1, 4).isocalendar()
datetime.IsoCalendarDate(year=2004, week=1, weekday=7)
.. versionchanged:: 3.9
Result changed from a tuple to a :term:`named tuple`.
+
.. method:: date.isoformat()
Return a string representing the date in ISO 8601 format, ``YYYY-MM-DD``::
- >>> from datetime import date
- >>> date(2002, 12, 4).isoformat()
+ >>> import datetime as dt
+ >>> dt.date(2002, 12, 4).isoformat()
'2002-12-04'
+
.. method:: date.__str__()
For a date ``d``, ``str(d)`` is equivalent to ``d.isoformat()``.
@@ -805,8 +822,8 @@ Instance methods:
Return a string representing the date::
- >>> from datetime import date
- >>> date(2002, 12, 4).ctime()
+ >>> import datetime as dt
+ >>> dt.date(2002, 12, 4).ctime()
'Wed Dec 4 00:00:00 2002'
``d.ctime()`` is equivalent to::
@@ -832,19 +849,20 @@ Instance methods:
literals <f-strings>` and when using :meth:`str.format`.
See also :ref:`strftime-strptime-behavior` and :meth:`date.isoformat`.
-Examples of Usage: :class:`date`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Examples of usage: :class:`!date`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Example of counting days to an event::
>>> import time
- >>> from datetime import date
- >>> today = date.today()
+ >>> import datetime as dt
+ >>> today = dt.date.today()
>>> today
datetime.date(2007, 12, 5)
- >>> today == date.fromtimestamp(time.time())
+ >>> today == dt.date.fromtimestamp(time.time())
True
- >>> my_birthday = date(today.year, 6, 24)
+ >>> my_birthday = dt.date(today.year, 6, 24)
>>> if my_birthday < today:
... my_birthday = my_birthday.replace(year=today.year + 1)
...
@@ -858,8 +876,8 @@ More examples of working with :class:`date`:
.. doctest::
- >>> from datetime import date
- >>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001
+ >>> import datetime as dt
+ >>> d = dt.date.fromordinal(730920) # 730920th day after 1. 1. 0001
>>> d
datetime.date(2002, 3, 11)
@@ -875,7 +893,7 @@ More examples of working with :class:`date`:
>>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, "day", "month")
'The day is 11, the month is March.'
- >>> # Methods for to extracting 'components' under different calendars
+ >>> # Methods for extracting 'components' under different calendars
>>> t = d.timetuple()
>>> for i in t: # doctest: +SKIP
... print(i)
@@ -902,7 +920,7 @@ More examples of working with :class:`date`:
.. _datetime-datetime:
-:class:`.datetime` Objects
+:class:`!datetime` objects
--------------------------
A :class:`.datetime` object is a single object containing all the information
@@ -910,7 +928,7 @@ from a :class:`date` object and a :class:`.time` object.
Like a :class:`date` object, :class:`.datetime` assumes the current Gregorian
calendar extended in both directions; like a :class:`.time` object,
-:class:`.datetime` assumes there are exactly 3600\*24 seconds in every day.
+:class:`!datetime` assumes there are exactly 3600\*24 seconds in every day.
Constructor:
@@ -934,6 +952,7 @@ Constructor:
.. versionchanged:: 3.6
Added the *fold* parameter.
+
Other constructors, all class methods:
.. classmethod:: datetime.today()
@@ -949,6 +968,7 @@ Other constructors, all class methods:
This method is functionally equivalent to :meth:`now`, but without a
``tz`` parameter.
+
.. classmethod:: datetime.now(tz=None)
Return the current local date and time.
@@ -969,6 +989,7 @@ Other constructors, all class methods:
Subsequent calls to :meth:`!datetime.now` may return the same
instant depending on the precision of the underlying clock.
+
.. classmethod:: datetime.utcnow()
Return the current UTC date and time, with :attr:`.tzinfo` ``None``.
@@ -1056,6 +1077,9 @@ Other constructors, all class methods:
:c:func:`gmtime` function. Raise :exc:`OSError` instead of
:exc:`ValueError` on :c:func:`gmtime` failure.
+ .. versionchanged:: 3.15
+ Accepts any real number as *timestamp*, not only integer or float.
+
.. deprecated:: 3.12
Use :meth:`datetime.fromtimestamp` with :const:`UTC` instead.
@@ -1076,7 +1100,7 @@ Other constructors, all class methods:
are equal to the given :class:`.time` object's. If the *tzinfo*
argument is provided, its value is used to set the :attr:`.tzinfo` attribute
of the result, otherwise the :attr:`~.time.tzinfo` attribute of the *time* argument
- is used. If the *date* argument is a :class:`.datetime` object, its time components
+ is used. If the *date* argument is a :class:`!datetime` object, its time components
and :attr:`.tzinfo` attributes are ignored.
For any :class:`.datetime` object ``d``,
@@ -1102,24 +1126,24 @@ Other constructors, all class methods:
Examples::
- >>> from datetime import datetime
- >>> datetime.fromisoformat('2011-11-04')
+ >>> import datetime as dt
+ >>> dt.datetime.fromisoformat('2011-11-04')
datetime.datetime(2011, 11, 4, 0, 0)
- >>> datetime.fromisoformat('20111104')
+ >>> dt.datetime.fromisoformat('20111104')
datetime.datetime(2011, 11, 4, 0, 0)
- >>> datetime.fromisoformat('2011-11-04T00:05:23')
+ >>> dt.datetime.fromisoformat('2011-11-04T00:05:23')
datetime.datetime(2011, 11, 4, 0, 5, 23)
- >>> datetime.fromisoformat('2011-11-04T00:05:23Z')
+ >>> dt.datetime.fromisoformat('2011-11-04T00:05:23Z')
datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone.utc)
- >>> datetime.fromisoformat('20111104T000523')
+ >>> dt.datetime.fromisoformat('20111104T000523')
datetime.datetime(2011, 11, 4, 0, 5, 23)
- >>> datetime.fromisoformat('2011-W01-2T00:05:23.283')
+ >>> dt.datetime.fromisoformat('2011-W01-2T00:05:23.283')
datetime.datetime(2011, 1, 4, 0, 5, 23, 283000)
- >>> datetime.fromisoformat('2011-11-04 00:05:23.283')
+ >>> dt.datetime.fromisoformat('2011-11-04 00:05:23.283')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000)
- >>> datetime.fromisoformat('2011-11-04 00:05:23.283+00:00')
+ >>> dt.datetime.fromisoformat('2011-11-04 00:05:23.283+00:00')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone.utc)
- >>> datetime.fromisoformat('2011-11-04T00:05:23+04:00') # doctest: +NORMALIZE_WHITESPACE
+ >>> dt.datetime.fromisoformat('2011-11-04T00:05:23+04:00') # doctest: +NORMALIZE_WHITESPACE
datetime.datetime(2011, 11, 4, 0, 5, 23,
tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))
@@ -1132,12 +1156,13 @@ Other constructors, all class methods:
.. classmethod:: datetime.fromisocalendar(year, week, day)
Return a :class:`.datetime` corresponding to the ISO calendar date specified
- by year, week and day. The non-date components of the datetime are populated
+ by *year*, *week* and *day*. The non-date components of the datetime are populated
with their normal default values. This is the inverse of the function
:meth:`datetime.isocalendar`.
.. versionadded:: 3.8
+
.. classmethod:: datetime.strptime(date_string, format)
Return a :class:`.datetime` corresponding to *date_string*, parsed according to
@@ -1165,9 +1190,9 @@ Other constructors, all class methods:
.. doctest::
- >>> from datetime import datetime
+ >>> import datetime as dt
>>> date_string = "02/29"
- >>> when = datetime.strptime(f"{date_string};1984", "%m/%d;%Y") # Avoids leap year bug.
+ >>> when = dt.datetime.strptime(f"{date_string};1984", "%m/%d;%Y") # Avoids leap year bug.
>>> when.strftime("%B %d") # doctest: +SKIP
'February 29'
@@ -1245,6 +1270,7 @@ Instance attributes (read-only):
.. versionadded:: 3.6
+
Supported operations:
+---------------------------------------+--------------------------------+
@@ -1280,7 +1306,7 @@ Supported operations:
datetime, and no time zone adjustments are done even if the input is aware.
(3)
- Subtraction of a :class:`.datetime` from a :class:`.datetime` is defined only if
+ Subtraction of a :class:`.datetime` from a :class:`!datetime` is defined only if
both operands are naive, or if both are aware. If one is aware and the other is
naive, :exc:`TypeError` is raised.
@@ -1298,7 +1324,7 @@ Supported operations:
:class:`.datetime` objects are equal if they represent the same date
and time, taking into account the time zone.
- Naive and aware :class:`!datetime` objects are never equal.
+ Naive and aware :class:`.datetime` objects are never equal.
If both comparands are aware, and have the same :attr:`!tzinfo` attribute,
the :attr:`!tzinfo` and :attr:`~.datetime.fold` attributes are ignored and
@@ -1306,7 +1332,7 @@ Supported operations:
If both comparands are aware and have different :attr:`~.datetime.tzinfo`
attributes, the comparison acts as comparands were first converted to UTC
datetimes except that the implementation never overflows.
- :class:`!datetime` instances in a repeated interval are never equal to
+ :class:`.datetime` instances in a repeated interval are never equal to
:class:`!datetime` instances in other time zone.
(5)
@@ -1335,6 +1361,7 @@ Supported operations:
The default behavior can be changed by overriding the special comparison
methods in subclasses.
+
Instance methods:
.. method:: datetime.date()
@@ -1490,11 +1517,13 @@ Instance methods:
``datetime.replace(tzinfo=timezone.utc)`` to make it aware, at which point
you can use :meth:`.datetime.timetuple`.
+
.. method:: datetime.toordinal()
Return the proleptic Gregorian ordinal of the date. The same as
``self.date().toordinal()``.
+
.. method:: datetime.timestamp()
Return POSIX timestamp corresponding to the :class:`.datetime`
@@ -1503,7 +1532,7 @@ Instance methods:
Naive :class:`.datetime` instances are assumed to represent local
time and this method relies on the platform C :c:func:`mktime`
- function to perform the conversion. Since :class:`.datetime`
+ function to perform the conversion. Since :class:`!datetime`
supports wider range of values than :c:func:`mktime` on many
platforms, this method may raise :exc:`OverflowError` or :exc:`OSError`
for times far in the past or far in the future.
@@ -1513,12 +1542,6 @@ Instance methods:
(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()
- .. versionadded:: 3.3
-
- .. versionchanged:: 3.6
- The :meth:`timestamp` method uses the :attr:`.fold` attribute to
- disambiguate the times during a repeated interval.
-
.. note::
There is no method to obtain the POSIX timestamp directly from a
@@ -1533,6 +1556,13 @@ Instance methods:
timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1)
+ .. versionadded:: 3.3
+
+ .. versionchanged:: 3.6
+ The :meth:`timestamp` method uses the :attr:`.fold` attribute to
+ disambiguate the times during a repeated interval.
+
+
.. method:: datetime.weekday()
Return the day of the week as an integer, where Monday is 0 and Sunday is 6.
@@ -1568,24 +1598,24 @@ Instance methods:
Examples::
- >>> from datetime import datetime, timezone
- >>> datetime(2019, 5, 18, 15, 17, 8, 132263).isoformat()
+ >>> import datetime as dt
+ >>> dt.datetime(2019, 5, 18, 15, 17, 8, 132263).isoformat()
'2019-05-18T15:17:08.132263'
- >>> datetime(2019, 5, 18, 15, 17, tzinfo=timezone.utc).isoformat()
+ >>> dt.datetime(2019, 5, 18, 15, 17, tzinfo=dt.timezone.utc).isoformat()
'2019-05-18T15:17:00+00:00'
The optional argument *sep* (default ``'T'``) is a one-character separator,
placed between the date and time portions of the result. For example::
- >>> from datetime import tzinfo, timedelta, datetime
- >>> class TZ(tzinfo):
+ >>> import datetime as dt
+ >>> class TZ(dt.tzinfo):
... """A time zone with an arbitrary, constant -06:39 offset."""
- ... def utcoffset(self, dt):
- ... return timedelta(hours=-6, minutes=-39)
+ ... def utcoffset(self, when):
+ ... return dt.timedelta(hours=-6, minutes=-39)
...
- >>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
+ >>> dt.datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'
- >>> datetime(2009, 11, 27, microsecond=100, tzinfo=TZ()).isoformat()
+ >>> dt.datetime(2009, 11, 27, microsecond=100, tzinfo=TZ()).isoformat()
'2009-11-27T00:00:00.000100-06:39'
The optional argument *timespec* specifies the number of additional
@@ -1609,11 +1639,11 @@ Instance methods:
:exc:`ValueError` will be raised on an invalid *timespec* argument::
- >>> from datetime import datetime
- >>> datetime.now().isoformat(timespec='minutes') # doctest: +SKIP
+ >>> import datetime as dt
+ >>> dt.datetime.now().isoformat(timespec='minutes') # doctest: +SKIP
'2002-12-25T00:00'
- >>> dt = datetime(2015, 1, 1, 12, 30, 59, 0)
- >>> dt.isoformat(timespec='microseconds')
+ >>> my_datetime = dt.datetime(2015, 1, 1, 12, 30, 59, 0)
+ >>> my_datetime.isoformat(timespec='microseconds')
'2015-01-01T12:30:59.000000'
.. versionchanged:: 3.6
@@ -1630,8 +1660,8 @@ Instance methods:
Return a string representing the date and time::
- >>> from datetime import datetime
- >>> datetime(2002, 12, 4, 20, 30, 40).ctime()
+ >>> import datetime as dt
+ >>> dt.datetime(2002, 12, 4, 20, 30, 40).ctime()
'Wed Dec 4 20:30:40 2002'
The output string will *not* include time zone information, regardless
@@ -1661,34 +1691,34 @@ Instance methods:
See also :ref:`strftime-strptime-behavior` and :meth:`datetime.isoformat`.
-Examples of Usage: :class:`.datetime`
+Examples of usage: :class:`!datetime`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Examples of working with :class:`.datetime` objects:
.. doctest::
- >>> from datetime import datetime, date, time, timezone
+ >>> import datetime as dt
>>> # Using datetime.combine()
- >>> d = date(2005, 7, 14)
- >>> t = time(12, 30)
- >>> datetime.combine(d, t)
+ >>> d = dt.date(2005, 7, 14)
+ >>> t = dt.time(12, 30)
+ >>> dt.datetime.combine(d, t)
datetime.datetime(2005, 7, 14, 12, 30)
>>> # Using datetime.now()
- >>> datetime.now() # doctest: +SKIP
+ >>> dt.datetime.now() # doctest: +SKIP
datetime.datetime(2007, 12, 6, 16, 29, 43, 79043) # GMT +1
- >>> datetime.now(timezone.utc) # doctest: +SKIP
+ >>> dt.datetime.now(dt.timezone.utc) # doctest: +SKIP
datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone.utc)
>>> # Using datetime.strptime()
- >>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
- >>> dt
+ >>> my_datetime = dt.datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
+ >>> my_datetime
datetime.datetime(2006, 11, 21, 16, 30)
>>> # Using datetime.timetuple() to get tuple of all attributes
- >>> tt = dt.timetuple()
+ >>> tt = my_datetime.timetuple()
>>> for it in tt: # doctest: +SKIP
... print(it)
...
@@ -1703,7 +1733,7 @@ Examples of working with :class:`.datetime` objects:
-1 # dst - method tzinfo.dst() returned None
>>> # Date in ISO format
- >>> ic = dt.isocalendar()
+ >>> ic = my_datetime.isocalendar()
>>> for it in ic: # doctest: +SKIP
... print(it)
...
@@ -1712,55 +1742,55 @@ Examples of working with :class:`.datetime` objects:
2 # ISO weekday
>>> # Formatting a datetime
- >>> dt.strftime("%A, %d. %B %Y %I:%M%p")
+ >>> my_datetime.strftime("%A, %d. %B %Y %I:%M%p")
'Tuesday, 21. November 2006 04:30PM'
- >>> 'The {1} is {0:%d}, the {2} is {0:%B}, the {3} is {0:%I:%M%p}.'.format(dt, "day", "month", "time")
+ >>> 'The {1} is {0:%d}, the {2} is {0:%B}, the {3} is {0:%I:%M%p}.'.format(my_datetime, "day", "month", "time")
'The day is 21, the month is November, the time is 04:30PM.'
The example below defines a :class:`tzinfo` subclass capturing time zone
information for Kabul, Afghanistan, which used +4 UTC until 1945
and then +4:30 UTC thereafter::
- from datetime import timedelta, datetime, tzinfo, timezone
+ import datetime as dt
- class KabulTz(tzinfo):
+ class KabulTz(dt.tzinfo):
# Kabul used +4 until 1945, when they moved to +4:30
- UTC_MOVE_DATE = datetime(1944, 12, 31, 20, tzinfo=timezone.utc)
+ UTC_MOVE_DATE = dt.datetime(1944, 12, 31, 20, tzinfo=dt.timezone.utc)
- def utcoffset(self, dt):
- if dt.year < 1945:
- return timedelta(hours=4)
- elif (1945, 1, 1, 0, 0) <= dt.timetuple()[:5] < (1945, 1, 1, 0, 30):
+ def utcoffset(self, when):
+ if when.year < 1945:
+ return dt.timedelta(hours=4)
+ elif (1945, 1, 1, 0, 0) <= when.timetuple()[:5] < (1945, 1, 1, 0, 30):
# An ambiguous ("imaginary") half-hour range representing
# a 'fold' in time due to the shift from +4 to +4:30.
- # If dt falls in the imaginary range, use fold to decide how
- # to resolve. See PEP495.
- return timedelta(hours=4, minutes=(30 if dt.fold else 0))
+ # If when falls in the imaginary range, use fold to decide how
+ # to resolve. See PEP 495.
+ return dt.timedelta(hours=4, minutes=(30 if when.fold else 0))
else:
- return timedelta(hours=4, minutes=30)
+ return dt.timedelta(hours=4, minutes=30)
- def fromutc(self, dt):
+ def fromutc(self, when):
# Follow same validations as in datetime.tzinfo
- if not isinstance(dt, datetime):
+ if not isinstance(when, dt.datetime):
raise TypeError("fromutc() requires a datetime argument")
- if dt.tzinfo is not self:
- raise ValueError("dt.tzinfo is not self")
+ if when.tzinfo is not self:
+ raise ValueError("when.tzinfo is not self")
# A custom implementation is required for fromutc as
# the input to this function is a datetime with utc values
# but with a tzinfo set to self.
# See datetime.astimezone or fromtimestamp.
- if dt.replace(tzinfo=timezone.utc) >= self.UTC_MOVE_DATE:
- return dt + timedelta(hours=4, minutes=30)
+ if when.replace(tzinfo=dt.timezone.utc) >= self.UTC_MOVE_DATE:
+ return when + dt.timedelta(hours=4, minutes=30)
else:
- return dt + timedelta(hours=4)
+ return when + dt.timedelta(hours=4)
- def dst(self, dt):
+ def dst(self, when):
# Kabul does not observe daylight saving time.
- return timedelta(0)
+ return dt.timedelta(0)
- def tzname(self, dt):
- if dt >= self.UTC_MOVE_DATE:
+ def tzname(self, when):
+ if when >= self.UTC_MOVE_DATE:
return "+04:30"
return "+04"
@@ -1769,17 +1799,17 @@ Usage of ``KabulTz`` from above::
>>> tz1 = KabulTz()
>>> # Datetime before the change
- >>> dt1 = datetime(1900, 11, 21, 16, 30, tzinfo=tz1)
+ >>> dt1 = dt.datetime(1900, 11, 21, 16, 30, tzinfo=tz1)
>>> print(dt1.utcoffset())
4:00:00
>>> # Datetime after the change
- >>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=tz1)
+ >>> dt2 = dt.datetime(2006, 6, 14, 13, 0, tzinfo=tz1)
>>> print(dt2.utcoffset())
4:30:00
>>> # Convert datetime to another time zone
- >>> dt3 = dt2.astimezone(timezone.utc)
+ >>> dt3 = dt2.astimezone(dt.timezone.utc)
>>> dt3
datetime.datetime(2006, 6, 14, 8, 30, tzinfo=datetime.timezone.utc)
>>> dt2
@@ -1787,9 +1817,10 @@ Usage of ``KabulTz`` from above::
>>> dt2 == dt3
True
+
.. _datetime-time:
-:class:`.time` Objects
+:class:`!time` objects
----------------------
A :class:`.time` object represents a (local) time of day, independent of any particular
@@ -1810,6 +1841,7 @@ day, and subject to adjustment via a :class:`tzinfo` object.
If an argument outside those ranges is given, :exc:`ValueError` is raised. All
default to 0 except *tzinfo*, which defaults to ``None``.
+
Class attributes:
@@ -1868,6 +1900,7 @@ Instance attributes (read-only):
.. versionadded:: 3.6
+
:class:`.time` objects support equality and order comparisons,
where ``a`` is considered less than ``b`` when ``a`` precedes ``b`` in time.
@@ -1890,8 +1923,8 @@ In Boolean contexts, a :class:`.time` object is always considered to be true.
.. versionchanged:: 3.5
Before Python 3.5, a :class:`.time` object was considered to be false if it
represented midnight in UTC. This behavior was considered obscure and
- error-prone and has been removed in Python 3.5. See :issue:`13936` for full
- details.
+ error-prone and has been removed in Python 3.5. See :issue:`13936` for more
+ information.
Other constructors:
@@ -1912,22 +1945,22 @@ Other constructors:
.. doctest::
- >>> from datetime import time
- >>> time.fromisoformat('04:23:01')
+ >>> import datetime as dt
+ >>> dt.time.fromisoformat('04:23:01')
datetime.time(4, 23, 1)
- >>> time.fromisoformat('T04:23:01')
+ >>> dt.time.fromisoformat('T04:23:01')
datetime.time(4, 23, 1)
- >>> time.fromisoformat('T042301')
+ >>> dt.time.fromisoformat('T042301')
datetime.time(4, 23, 1)
- >>> time.fromisoformat('04:23:01.000384')
+ >>> dt.time.fromisoformat('04:23:01.000384')
datetime.time(4, 23, 1, 384)
- >>> time.fromisoformat('04:23:01,000384')
+ >>> dt.time.fromisoformat('04:23:01,000384')
datetime.time(4, 23, 1, 384)
- >>> time.fromisoformat('04:23:01+04:00')
+ >>> dt.time.fromisoformat('04:23:01+04:00')
datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))
- >>> time.fromisoformat('04:23:01Z')
+ >>> dt.time.fromisoformat('04:23:01Z')
datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)
- >>> time.fromisoformat('04:23:01+00:00')
+ >>> dt.time.fromisoformat('04:23:01+00:00')
datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)
@@ -1936,6 +1969,7 @@ Other constructors:
Previously, this method only supported formats that could be emitted by
:meth:`time.isoformat`.
+
.. classmethod:: time.strptime(date_string, format)
Return a :class:`.time` corresponding to *date_string*, parsed according to
@@ -1960,7 +1994,7 @@ Instance methods:
Return a new :class:`.time` with the same values, but with specified
parameters updated. Note that ``tzinfo=None`` can be specified to create a
- naive :class:`.time` from an aware :class:`.time`, without conversion of the
+ naive :class:`!time` from an aware :class:`!time`, without conversion of the
time data.
:class:`.time` objects are also supported by generic function
@@ -2001,13 +2035,13 @@ Instance methods:
Example::
- >>> from datetime import time
- >>> time(hour=12, minute=34, second=56, microsecond=123456).isoformat(timespec='minutes')
+ >>> import datetime as dt
+ >>> dt.time(hour=12, minute=34, second=56, microsecond=123456).isoformat(timespec='minutes')
'12:34'
- >>> dt = time(hour=12, minute=34, second=56, microsecond=0)
- >>> dt.isoformat(timespec='microseconds')
+ >>> my_time = dt.time(hour=12, minute=34, second=56, microsecond=0)
+ >>> my_time.isoformat(timespec='microseconds')
'12:34:56.000000'
- >>> dt.isoformat(timespec='auto')
+ >>> my_time.isoformat(timespec='auto')
'12:34:56'
.. versionchanged:: 3.6
@@ -2052,29 +2086,31 @@ Instance methods:
.. versionchanged:: 3.7
The DST offset is not restricted to a whole number of minutes.
+
.. method:: time.tzname()
If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
``self.tzinfo.tzname(None)``, or raises an exception if the latter doesn't
return ``None`` or a string object.
-Examples of Usage: :class:`.time`
+
+Examples of usage: :class:`!time`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Examples of working with a :class:`.time` object::
- >>> from datetime import time, tzinfo, timedelta
- >>> class TZ1(tzinfo):
- ... def utcoffset(self, dt):
- ... return timedelta(hours=1)
- ... def dst(self, dt):
- ... return timedelta(0)
- ... def tzname(self,dt):
+ >>> import datetime as dt
+ >>> class TZ1(dt.tzinfo):
+ ... def utcoffset(self, when):
+ ... return dt.timedelta(hours=1)
+ ... def dst(self, when):
+ ... return dt.timedelta(0)
+ ... def tzname(self, when):
... return "+01:00"
... def __repr__(self):
... return f"{self.__class__.__name__}()"
...
- >>> t = time(12, 10, 30, tzinfo=TZ1())
+ >>> t = dt.time(12, 10, 30, tzinfo=TZ1())
>>> t
datetime.time(12, 10, 30, tzinfo=TZ1())
>>> t.isoformat()
@@ -2091,25 +2127,25 @@ Examples of working with a :class:`.time` object::
.. _datetime-tzinfo:
-:class:`tzinfo` Objects
------------------------
+:class:`!tzinfo` objects
+------------------------
.. class:: tzinfo()
- This is an abstract base class, meaning that this class should not be
+ This is an :term:`abstract base class`, meaning that this class should not be
instantiated directly. Define a subclass of :class:`tzinfo` to capture
information about a particular time zone.
An instance of (a concrete subclass of) :class:`tzinfo` can be passed to the
constructors for :class:`.datetime` and :class:`.time` objects. The latter objects
- view their attributes as being in local time, and the :class:`tzinfo` object
+ view their attributes as being in local time, and the :class:`!tzinfo` object
supports methods revealing offset of local time from UTC, the name of the time
zone, and DST offset, all relative to a date or time object passed to them.
You need to derive a concrete subclass, and (at least)
supply implementations of the standard :class:`tzinfo` methods needed by the
:class:`.datetime` methods you use. The :mod:`!datetime` module provides
- :class:`timezone`, a simple concrete subclass of :class:`tzinfo` which can
+ :class:`timezone`, a simple concrete subclass of :class:`!tzinfo` which can
represent time zones with fixed offset from UTC such as UTC itself or North
American EST and EDT.
@@ -2172,31 +2208,35 @@ Examples of working with a :class:`.time` object::
``tz.utcoffset(dt) - tz.dst(dt)``
must return the same result for every :class:`.datetime` *dt* with ``dt.tzinfo ==
- tz``. For sane :class:`tzinfo` subclasses, this expression yields the time
+ tz``. For sane :class:`!tzinfo` subclasses, this expression yields the time
zone's "standard offset", which should not depend on the date or the time, but
only on geographic location. The implementation of :meth:`datetime.astimezone`
relies on this, but cannot detect violations; it's the programmer's
- responsibility to ensure it. If a :class:`tzinfo` subclass cannot guarantee
+ responsibility to ensure it. If a :class:`!tzinfo` subclass cannot guarantee
this, it may be able to override the default implementation of
:meth:`tzinfo.fromutc` to work correctly with :meth:`~.datetime.astimezone` regardless.
Most implementations of :meth:`dst` will probably look like one of these two::
- def dst(self, dt):
+ import datetime as dt
+
+ def dst(self, when):
# a fixed-offset class: doesn't account for DST
- return timedelta(0)
+ return dt.timedelta(0)
or::
- def dst(self, dt):
+ import datetime as dt
+
+ def dst(self, when):
# Code to set dston and dstoff to the time zone's DST
- # transition times based on the input dt.year, and expressed
+ # transition times based on the input when.year, and expressed
# in standard local time.
- if dston <= dt.replace(tzinfo=None) < dstoff:
- return timedelta(hours=1)
+ if dston <= when.replace(tzinfo=None) < dstoff:
+ return dt.timedelta(hours=1)
else:
- return timedelta(0)
+ return dt.timedelta(0)
The default implementation of :meth:`dst` raises :exc:`NotImplementedError`.
@@ -2213,17 +2253,17 @@ Examples of working with a :class:`.time` object::
valid replies. Return ``None`` if a string name isn't known. Note that this is
a method rather than a fixed string primarily because some :class:`tzinfo`
subclasses will wish to return different names depending on the specific value
- of *dt* passed, especially if the :class:`tzinfo` class is accounting for
+ of *dt* passed, especially if the :class:`!tzinfo` class is accounting for
daylight time.
The default implementation of :meth:`tzname` raises :exc:`NotImplementedError`.
These methods are called by a :class:`.datetime` or :class:`.time` object, in
-response to their methods of the same names. A :class:`.datetime` object passes
-itself as the argument, and a :class:`.time` object passes ``None`` as the
+response to their methods of the same names. A :class:`!datetime` object passes
+itself as the argument, and a :class:`!time` object passes ``None`` as the
argument. A :class:`tzinfo` subclass's methods should therefore be prepared to
-accept a *dt* argument of ``None``, or of class :class:`.datetime`.
+accept a *dt* argument of ``None``, or of class :class:`!datetime`.
When ``None`` is passed, it's up to the class designer to decide the best
response. For example, returning ``None`` is appropriate if the class wishes to
@@ -2231,10 +2271,10 @@ say that time objects don't participate in the :class:`tzinfo` protocols. It
may be more useful for ``utcoffset(None)`` to return the standard UTC offset, as
there is no other convention for discovering the standard offset.
-When a :class:`.datetime` object is passed in response to a :class:`.datetime`
+When a :class:`.datetime` object is passed in response to a :class:`!datetime`
method, ``dt.tzinfo`` is the same object as *self*. :class:`tzinfo` methods can
-rely on this, unless user code calls :class:`tzinfo` methods directly. The
-intent is that the :class:`tzinfo` methods interpret *dt* as being in local
+rely on this, unless user code calls :class:`!tzinfo` methods directly. The
+intent is that the :class:`!tzinfo` methods interpret *dt* as being in local
time, and not need worry about objects in other time zones.
There is one more :class:`tzinfo` method that a subclass may wish to override:
@@ -2262,20 +2302,22 @@ There is one more :class:`tzinfo` method that a subclass may wish to override:
Skipping code for error cases, the default :meth:`fromutc` implementation acts
like::
- def fromutc(self, dt):
- # raise ValueError error if dt.tzinfo is not self
- dtoff = dt.utcoffset()
- dtdst = dt.dst()
+ import datetime as dt
+
+ def fromutc(self, when):
+ # raise ValueError error if when.tzinfo is not self
+ dtoff = when.utcoffset()
+ dtdst = when.dst()
# raise ValueError if dtoff is None or dtdst is None
delta = dtoff - dtdst # this is self's standard offset
if delta:
- dt += delta # convert to standard local time
- dtdst = dt.dst()
+ when += delta # convert to standard local time
+ dtdst = when.dst()
# raise ValueError if dtdst is None
if dtdst:
- return dt + dtdst
+ return when + dtdst
else:
- return dt
+ return when
In the following :download:`tzinfo_examples.py
<../includes/tzinfo_examples.py>` file there are some examples of
@@ -2302,9 +2344,9 @@ When DST starts (the "start" line), the local wall clock leaps from 1:59 to
``astimezone(Eastern)`` won't deliver a result with ``hour == 2`` on the day DST
begins. For example, at the Spring forward transition of 2016, we get::
- >>> from datetime import datetime, timezone
+ >>> import datetime as dt
>>> from tzinfo_examples import HOUR, Eastern
- >>> u0 = datetime(2016, 3, 13, 5, tzinfo=timezone.utc)
+ >>> u0 = dt.datetime(2016, 3, 13, 5, tzinfo=dt.timezone.utc)
>>> for i in range(4):
... u = u0 + i*HOUR
... t = u.astimezone(Eastern)
@@ -2327,7 +2369,9 @@ form 5:MM and 6:MM both map to 1:MM when converted to Eastern, but earlier times
have the :attr:`~.datetime.fold` attribute set to 0 and the later times have it set to 1.
For example, at the Fall back transition of 2016, we get::
- >>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc)
+ >>> import datetime as dt
+ >>> from tzinfo_examples import HOUR, Eastern
+ >>> u0 = dt.datetime(2016, 11, 6, 4, tzinfo=dt.timezone.utc)
>>> for i in range(4):
... u = u0 + i*HOUR
... t = u.astimezone(Eastern)
@@ -2344,7 +2388,7 @@ Note that the :class:`.datetime` instances that differ only by the value of the
Applications that can't bear wall-time ambiguities should explicitly check the
value of the :attr:`~.datetime.fold` attribute or avoid using hybrid
:class:`tzinfo` subclasses; there are no ambiguities when using :class:`timezone`,
-or any other fixed-offset :class:`tzinfo` subclass (such as a class representing
+or any other fixed-offset :class:`!tzinfo` subclass (such as a class representing
only EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)).
.. seealso::
@@ -2367,8 +2411,8 @@ only EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)).
.. _datetime-timezone:
-:class:`timezone` Objects
--------------------------
+:class:`!timezone` objects
+--------------------------
The :class:`timezone` class is a subclass of :class:`tzinfo`, each
instance of which represents a time zone defined by a fixed offset from
@@ -2406,6 +2450,7 @@ where historical changes have been made to civil time.
.. versionchanged:: 3.7
The UTC offset is not restricted to a whole number of minutes.
+
.. method:: timezone.tzname(dt)
Return the fixed value specified when the :class:`timezone` instance
@@ -2426,11 +2471,13 @@ where historical changes have been made to civil time.
Always returns ``None``.
+
.. method:: timezone.fromutc(dt)
Return ``dt + offset``. The *dt* argument must be an aware
:class:`.datetime` instance, with ``tzinfo`` set to ``self``.
+
Class attributes:
.. attribute:: timezone.utc
@@ -2443,8 +2490,8 @@ Class attributes:
.. _strftime-strptime-behavior:
-:meth:`~.datetime.strftime` and :meth:`~.datetime.strptime` Behavior
---------------------------------------------------------------------
+:meth:`!strftime` and :meth:`!strptime` behavior
+------------------------------------------------
:class:`date`, :class:`.datetime`, and :class:`.time` objects all support a
``strftime(format)`` method, to create a string representing the time under the
@@ -2470,13 +2517,14 @@ versus :meth:`~.datetime.strptime`:
.. _format-codes:
-:meth:`~.datetime.strftime` and :meth:`~.datetime.strptime` Format Codes
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:meth:`!strftime` and :meth:`!strptime` format codes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These methods accept format codes that can be used to parse and format dates::
- >>> datetime.strptime('31/01/22 23:59:59.999999',
- ... '%d/%m/%y %H:%M:%S.%f')
+ >>> import datetime as dt
+ >>> dt.datetime.strptime('31/01/22 23:59:59.999999',
+ ... '%d/%m/%y %H:%M:%S.%f')
datetime.datetime(2022, 1, 31, 23, 59, 59, 999999)
>>> _.strftime('%a %d %b %Y, %I:%M%p')
'Mon 31 Jan 2022, 11:59PM'
@@ -2627,7 +2675,8 @@ differences between platforms in handling of unsupported format specifiers.
.. versionadded:: 3.12
``%:z`` was added.
-Technical Detail
+
+Technical detail
^^^^^^^^^^^^^^^^
Broadly speaking, ``d.strftime(fmt)`` acts like the :mod:`time` module's
@@ -2638,13 +2687,18 @@ For the :meth:`.datetime.strptime` and :meth:`.date.strptime` class methods,
the default value is ``1900-01-01T00:00:00.000``: any components not specified
in the format string will be pulled from the default value.
+.. note::
+ Format strings without separators can be ambiguous for parsing. For
+ example, with ``%Y%m%d``, the string ``2026111`` may be parsed either as
+ ``2026-11-01`` or as ``2026-01-11``.
+ Use separators to ensure the input is parsed as intended.
+
.. note::
When used to parse partial dates lacking a year, :meth:`.datetime.strptime`
and :meth:`.date.strptime` will raise when encountering February 29 because
the default year of 1900 is *not* a leap year. Always add a default leap
year to partial date strings before parsing.
-
.. testsetup::
# doctest seems to turn the warning into an error which makes it
@@ -2662,13 +2716,13 @@ in the format string will be pulled from the default value.
.. doctest::
- >>> from datetime import datetime
+ >>> import datetime as dt
>>> value = "2/29"
- >>> datetime.strptime(value, "%m/%d")
+ >>> dt.datetime.strptime(value, "%m/%d")
Traceback (most recent call last):
...
ValueError: day 29 must be in range 1..28 for month 2 in year 1900
- >>> datetime.strptime(f"1904 {value}", "%Y %m/%d")
+ >>> dt.datetime.strptime(f"1904 {value}", "%Y %m/%d")
datetime.datetime(1904, 2, 29, 0, 0)
Using ``datetime.strptime(date_string, format)`` is equivalent to::
@@ -2805,7 +2859,7 @@ Notes:
.. doctest::
>>> month_day = "02/29"
- >>> datetime.strptime(f"{month_day};1984", "%m/%d;%Y") # No leap year bug.
+ >>> dt.datetime.strptime(f"{month_day};1984", "%m/%d;%Y") # No leap year bug.
datetime.datetime(1984, 2, 29, 0, 0)
.. deprecated-removed:: 3.13 3.15
@@ -2816,7 +2870,7 @@ Notes:
.. rubric:: Footnotes
-.. [#] If, that is, we ignore the effects of Relativity
+.. [#] If, that is, we ignore the effects of relativity.
.. [#] This matches the definition of the "proleptic Gregorian" calendar in
Dershowitz and Reingold's book *Calendrical Calculations*,
diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst
index 628232cb631..c736ee0d705 100644
--- a/Doc/library/dbm.rst
+++ b/Doc/library/dbm.rst
@@ -8,7 +8,7 @@
--------------
-:mod:`dbm` is a generic interface to variants of the DBM database:
+:mod:`!dbm` is a generic interface to variants of the DBM database:
* :mod:`dbm.sqlite3`
* :mod:`dbm.gnu`
@@ -101,7 +101,7 @@ will automatically close them when done.
.. versionchanged:: 3.2
:meth:`!get` and :meth:`!setdefault` methods are now available for all
- :mod:`dbm` backends.
+ :mod:`!dbm` backends.
.. versionchanged:: 3.4
Added native support for the context management protocol to the objects
@@ -112,7 +112,7 @@ will automatically close them when done.
instead of :exc:`KeyError`.
.. versionchanged:: 3.13
- :meth:`!clear` methods are now available for all :mod:`dbm` backends.
+ :meth:`!clear` methods are now available for all :mod:`!dbm` backends.
The following example records some hostnames and a corresponding title, and
@@ -151,11 +151,10 @@ then prints out the contents of the database::
The individual submodules are described in the following sections.
-:mod:`dbm.sqlite3` --- SQLite backend for dbm
----------------------------------------------
+:mod:`!dbm.sqlite3` --- SQLite backend for dbm
+----------------------------------------------
.. module:: dbm.sqlite3
- :platform: All
:synopsis: SQLite backend for dbm
.. versionadded:: 3.13
@@ -165,8 +164,8 @@ The individual submodules are described in the following sections.
--------------
This module uses the standard library :mod:`sqlite3` module to provide an
-SQLite backend for the :mod:`dbm` module.
-The files created by :mod:`dbm.sqlite3` can thus be opened by :mod:`sqlite3`,
+SQLite backend for the :mod:`!dbm` module.
+The files created by :mod:`!dbm.sqlite3` can thus be opened by :mod:`sqlite3`,
or any other SQLite browser, including the SQLite CLI.
.. include:: ../includes/wasm-notavail.rst
@@ -202,31 +201,32 @@ or any other SQLite browser, including the SQLite CLI.
Close the SQLite database.
-:mod:`dbm.gnu` --- GNU database manager
----------------------------------------
+:mod:`!dbm.gnu` --- GNU database manager
+----------------------------------------
.. module:: dbm.gnu
- :platform: Unix
:synopsis: GNU database manager
**Source code:** :source:`Lib/dbm/gnu.py`
--------------
-The :mod:`dbm.gnu` module provides an interface to the :abbr:`GDBM (GNU dbm)`
+The :mod:`!dbm.gnu` module provides an interface to the :abbr:`GDBM (GNU dbm)`
library, similar to the :mod:`dbm.ndbm` module, but with additional
functionality like crash tolerance.
.. note::
- The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are incompatible
+ The file formats created by :mod:`!dbm.gnu` and :mod:`dbm.ndbm` are incompatible
and can not be used interchangeably.
.. include:: ../includes/wasm-mobile-notavail.rst
+.. availability:: Unix.
+
.. exception:: error
- Raised on :mod:`dbm.gnu`-specific errors, such as I/O errors. :exc:`KeyError` is
+ Raised on :mod:`!dbm.gnu`-specific errors, such as I/O errors. :exc:`KeyError` is
raised for general mapping errors like specifying an incorrect key.
@@ -321,25 +321,24 @@ functionality like crash tolerance.
unwritten data to be written to the disk.
-:mod:`dbm.ndbm` --- New Database Manager
-----------------------------------------
+:mod:`!dbm.ndbm` --- New Database Manager
+-----------------------------------------
.. module:: dbm.ndbm
- :platform: Unix
:synopsis: The New Database Manager
**Source code:** :source:`Lib/dbm/ndbm.py`
--------------
-The :mod:`dbm.ndbm` module provides an interface to the
+The :mod:`!dbm.ndbm` module provides an interface to the
:abbr:`NDBM (New Database Manager)` library.
This module can be used with the "classic" NDBM interface or the
:abbr:`GDBM (GNU dbm)` compatibility interface.
.. note::
- The file formats created by :mod:`dbm.gnu` and :mod:`dbm.ndbm` are incompatible
+ The file formats created by :mod:`dbm.gnu` and :mod:`!dbm.ndbm` are incompatible
and can not be used interchangeably.
.. warning::
@@ -351,9 +350,11 @@ This module can be used with the "classic" NDBM interface or the
.. include:: ../includes/wasm-mobile-notavail.rst
+.. availability:: Unix.
+
.. exception:: error
- Raised on :mod:`dbm.ndbm`-specific errors, such as I/O errors. :exc:`KeyError` is raised
+ Raised on :mod:`!dbm.ndbm`-specific errors, such as I/O errors. :exc:`KeyError` is raised
for general mapping errors like specifying an incorrect key.
@@ -403,8 +404,8 @@ This module can be used with the "classic" NDBM interface or the
Close the NDBM database.
-:mod:`dbm.dumb` --- Portable DBM implementation
------------------------------------------------
+:mod:`!dbm.dumb` --- Portable DBM implementation
+------------------------------------------------
.. module:: dbm.dumb
:synopsis: Portable implementation of the simple DBM interface.
@@ -415,23 +416,23 @@ This module can be used with the "classic" NDBM interface or the
.. note::
- The :mod:`dbm.dumb` module is intended as a last resort fallback for the
- :mod:`dbm` module when a more robust module is not available. The :mod:`dbm.dumb`
+ The :mod:`!dbm.dumb` module is intended as a last resort fallback for the
+ :mod:`!dbm` module when a more robust module is not available. The :mod:`!dbm.dumb`
module is not written for speed and is not nearly as heavily used as the other
database modules.
--------------
-The :mod:`dbm.dumb` module provides a persistent :class:`dict`-like
+The :mod:`!dbm.dumb` module provides a persistent :class:`dict`-like
interface which is written entirely in Python.
-Unlike other :mod:`dbm` backends, such as :mod:`dbm.gnu`, no
+Unlike other :mod:`!dbm` backends, such as :mod:`dbm.gnu`, no
external library is required.
The :mod:`!dbm.dumb` module defines the following:
.. exception:: error
- Raised on :mod:`dbm.dumb`-specific errors, such as I/O errors. :exc:`KeyError` is
+ Raised on :mod:`!dbm.dumb`-specific errors, such as I/O errors. :exc:`KeyError` is
raised for general mapping errors like specifying an incorrect key.
diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst
index 43f2e14f92e..d4c089f5a14 100644
--- a/Doc/library/decimal.rst
+++ b/Doc/library/decimal.rst
@@ -30,7 +30,7 @@
--------------
-The :mod:`decimal` module provides support for fast correctly rounded
+The :mod:`!decimal` module provides support for fast correctly rounded
decimal floating-point arithmetic. It offers several advantages over the
:class:`float` datatype:
@@ -289,7 +289,7 @@ For more advanced work, it may be useful to create alternate contexts using the
:meth:`Context` constructor. To make an alternate active, use the :func:`setcontext`
function.
-In accordance with the standard, the :mod:`decimal` module provides two ready to
+In accordance with the standard, the :mod:`!decimal` module provides two ready to
use standard contexts, :const:`BasicContext` and :const:`ExtendedContext`. The
former is especially useful for debugging because many of the traps are
enabled:
@@ -1838,7 +1838,7 @@ properties of addition:
>>> u * (v+w)
Decimal('0.0060000')
-The :mod:`decimal` module makes it possible to restore the identities by
+The :mod:`!decimal` module makes it possible to restore the identities by
expanding the precision sufficiently to avoid loss of significance:
.. doctest:: newcontext
@@ -1860,7 +1860,7 @@ expanding the precision sufficiently to avoid loss of significance:
Special values
^^^^^^^^^^^^^^
-The number system for the :mod:`decimal` module provides special values
+The number system for the :mod:`!decimal` module provides special values
including ``NaN``, ``sNaN``, ``-Infinity``, ``Infinity``,
and two zeros, ``+0`` and ``-0``.
diff --git a/Doc/library/dialog.rst b/Doc/library/dialog.rst
index e0693e8eb6e..5d522556235 100644
--- a/Doc/library/dialog.rst
+++ b/Doc/library/dialog.rst
@@ -1,18 +1,17 @@
Tkinter Dialogs
===============
-:mod:`tkinter.simpledialog` --- Standard Tkinter input dialogs
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:mod:`!tkinter.simpledialog` --- Standard Tkinter input dialogs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. module:: tkinter.simpledialog
- :platform: Tk
:synopsis: Simple dialog windows
**Source code:** :source:`Lib/tkinter/simpledialog.py`
--------------
-The :mod:`tkinter.simpledialog` module contains convenience classes and
+The :mod:`!tkinter.simpledialog` module contains convenience classes and
functions for creating simple modal dialogs to get a value from the user.
@@ -39,18 +38,17 @@ functions for creating simple modal dialogs to get a value from the user.
-:mod:`tkinter.filedialog` --- File selection dialogs
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:mod:`!tkinter.filedialog` --- File selection dialogs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. module:: tkinter.filedialog
- :platform: Tk
:synopsis: Dialog classes for file selection
**Source code:** :source:`Lib/tkinter/filedialog.py`
--------------
-The :mod:`tkinter.filedialog` module provides classes and factory functions for
+The :mod:`!tkinter.filedialog` module provides classes and factory functions for
creating file/directory selection windows.
Native Load/Save Dialogs
@@ -204,18 +202,17 @@ These do not emulate the native look-and-feel of the platform.
directory. Confirmation is required if an already existing file is
selected.
-:mod:`tkinter.commondialog` --- Dialog window templates
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:mod:`!tkinter.commondialog` --- Dialog window templates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. module:: tkinter.commondialog
- :platform: Tk
:synopsis: Tkinter base class for dialogs
**Source code:** :source:`Lib/tkinter/commondialog.py`
--------------
-The :mod:`tkinter.commondialog` module provides the :class:`Dialog` class that
+The :mod:`!tkinter.commondialog` module provides the :class:`Dialog` class that
is the base class for dialogs defined in other supporting modules.
.. class:: Dialog(master=None, **options)
diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index 61556fd5be3..d6b728b0848 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -14,7 +14,7 @@
--------------
-The :mod:`dis` module supports the analysis of CPython :term:`bytecode` by
+The :mod:`!dis` module supports the analysis of CPython :term:`bytecode` by
disassembling it. The CPython bytecode which this module takes as an input is
defined in the file :file:`Include/opcode.h` and used by the compiler and the
interpreter.
@@ -38,7 +38,7 @@ interpreter.
Some instructions are accompanied by one or more inline cache entries,
which take the form of :opcode:`CACHE` instructions. These instructions
are hidden by default, but can be shown by passing ``show_caches=True`` to
- any :mod:`dis` utility. Furthermore, the interpreter now adapts the
+ any :mod:`!dis` utility. Furthermore, the interpreter now adapts the
bytecode to specialize it for different runtime conditions. The
adaptive bytecode can be shown by passing ``adaptive=True``.
@@ -87,7 +87,7 @@ the following command can be used to display the disassembly of
Command-line interface
----------------------
-The :mod:`dis` module can be invoked as a script from the command line:
+The :mod:`!dis` module can be invoked as a script from the command line:
.. code-block:: sh
@@ -223,7 +223,7 @@ Example:
Analysis functions
------------------
-The :mod:`dis` module also defines the following analysis functions that convert
+The :mod:`!dis` module also defines the following analysis functions that convert
the input directly to the desired output. They can be useful if only a single
operation is being performed, so the intermediate analysis object isn't useful:
@@ -1827,7 +1827,7 @@ iterations of the loop.
ignore it. Before, only opcodes ``>= HAVE_ARGUMENT`` had an argument.
.. versionchanged:: 3.12
- Pseudo instructions were added to the :mod:`dis` module, and for them
+ Pseudo instructions were added to the :mod:`!dis` module, and for them
it is not true that comparison with ``HAVE_ARGUMENT`` indicates whether
they use their arg.
diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
index 61463d6adcd..a303afe60b7 100644
--- a/Doc/library/doctest.rst
+++ b/Doc/library/doctest.rst
@@ -13,7 +13,7 @@
--------------
-The :mod:`doctest` module searches for pieces of text that look like interactive
+The :mod:`!doctest` module searches for pieces of text that look like interactive
Python sessions, and then executes those sessions to verify that they work
exactly as shown. There are several common ways to use doctest:
@@ -85,7 +85,7 @@ Here's a complete but small example module::
import doctest
doctest.testmod()
-If you run :file:`example.py` directly from the command line, :mod:`doctest`
+If you run :file:`example.py` directly from the command line, :mod:`!doctest`
works its magic:
.. code-block:: shell-session
@@ -94,7 +94,7 @@ works its magic:
$
There's no output! That's normal, and it means all the examples worked. Pass
-``-v`` to the script, and :mod:`doctest` prints a detailed log of what
+``-v`` to the script, and :mod:`!doctest` prints a detailed log of what
it's trying, and prints a summary at the end:
.. code-block:: shell-session
@@ -130,7 +130,7 @@ And so on, eventually ending with:
Test passed.
$
-That's all you need to know to start making productive use of :mod:`doctest`!
+That's all you need to know to start making productive use of :mod:`!doctest`!
Jump in. The following sections provide full details. Note that there are many
examples of doctests in the standard Python test suite and libraries.
Especially useful examples can be found in the standard test file
@@ -252,7 +252,7 @@ For more information on :func:`testfile`, see section :ref:`doctest-basic-api`.
Command-line Usage
------------------
-The :mod:`doctest` module can be invoked as a script from the command line:
+The :mod:`!doctest` module can be invoked as a script from the command line:
.. code-block:: bash
@@ -450,7 +450,7 @@ The fine print:
What's the Execution Context?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-By default, each time :mod:`doctest` finds a docstring to test, it uses a
+By default, each time :mod:`!doctest` finds a docstring to test, it uses a
*shallow copy* of :mod:`!M`'s globals, so that running tests doesn't change the
module's real globals, and so that one test in :mod:`!M` can't leave behind
crumbs that accidentally allow another test to work. This means examples can
@@ -730,7 +730,7 @@ The second group of options controls how test failures are reported:
There is also a way to register new option flag names, though this isn't
-useful unless you intend to extend :mod:`doctest` internals via subclassing:
+useful unless you intend to extend :mod:`!doctest` internals via subclassing:
.. function:: register_optionflag(name)
@@ -833,7 +833,7 @@ disabling an option via ``-`` in a directive can be useful.
Warnings
^^^^^^^^
-:mod:`doctest` is serious about requiring exact matches in expected output. If
+:mod:`!doctest` is serious about requiring exact matches in expected output. If
even a single character doesn't match, the test fails. This will probably
surprise you a few times, as you learn exactly what Python does and doesn't
guarantee about output. For example, when printing a set, Python doesn't
@@ -1035,7 +1035,7 @@ Unittest API
------------
As your collection of doctest'ed modules grows, you'll want a way to run all
-their doctests systematically. :mod:`doctest` provides two functions that can
+their doctests systematically. :mod:`!doctest` provides two functions that can
be used to create :mod:`unittest` test suites from modules and text files
containing doctests. To integrate with :mod:`unittest` test discovery, include
a :ref:`load_tests <load_tests-protocol>` function in your test module::
@@ -1168,7 +1168,7 @@ of :class:`!DocTestCase`.
So both ways of creating a :class:`unittest.TestSuite` run instances of
:class:`!DocTestCase`. This is important for a subtle reason: when you run
-:mod:`doctest` functions yourself, you can control the :mod:`!doctest` options in
+:mod:`!doctest` functions yourself, you can control the :mod:`!doctest` options in
use directly, by passing option flags to :mod:`!doctest` functions. However, if
you're writing a :mod:`unittest` framework, :mod:`!unittest` ultimately controls
when and how tests get run. The framework author typically wants to control
@@ -1176,13 +1176,13 @@ when and how tests get run. The framework author typically wants to control
options), but there's no way to pass options through :mod:`!unittest` to
:mod:`!doctest` test runners.
-For this reason, :mod:`doctest` also supports a notion of :mod:`!doctest`
+For this reason, :mod:`!doctest` also supports a notion of :mod:`!doctest`
reporting flags specific to :mod:`unittest` support, via this function:
.. function:: set_unittest_reportflags(flags)
- Set the :mod:`doctest` reporting flags to use.
+ Set the :mod:`!doctest` reporting flags to use.
Argument *flags* takes the :ref:`bitwise OR <bitwise>` of option flags. See
section :ref:`doctest-options`. Only "reporting flags" can be used.
@@ -1899,7 +1899,7 @@ There are two exceptions that may be raised by :class:`DebugRunner` instances:
Soapbox
-------
-As mentioned in the introduction, :mod:`doctest` has grown to have three primary
+As mentioned in the introduction, :mod:`!doctest` has grown to have three primary
uses:
#. Checking examples in docstrings.
@@ -1917,7 +1917,7 @@ this that needs to be learned---it may not be natural at first. Examples should
add genuine value to the documentation. A good example can often be worth many
words. If done with care, the examples will be invaluable for your users, and
will pay back the time it takes to collect them many times over as the years go
-by and things change. I'm still amazed at how often one of my :mod:`doctest`
+by and things change. I'm still amazed at how often one of my :mod:`!doctest`
examples stops working after a "harmless" change.
Doctest also makes an excellent tool for regression testing, especially if you
diff --git a/Doc/library/email.charset.rst b/Doc/library/email.charset.rst
index 6875af2be49..76a57031862 100644
--- a/Doc/library/email.charset.rst
+++ b/Doc/library/email.charset.rst
@@ -19,7 +19,7 @@ registry and several convenience methods for manipulating this registry.
Instances of :class:`Charset` are used in several other modules within the
:mod:`email` package.
-Import this class from the :mod:`email.charset` module.
+Import this class from the :mod:`!email.charset` module.
.. class:: Charset(input_charset=DEFAULT_CHARSET)
@@ -164,7 +164,7 @@ Import this class from the :mod:`email.charset` module.
This method allows you to compare two :class:`Charset` instances for
inequality.
-The :mod:`email.charset` module also provides the following functions for adding
+The :mod:`!email.charset` module also provides the following functions for adding
new entries to the global character set, alias, and codec registries:
diff --git a/Doc/library/email.encoders.rst b/Doc/library/email.encoders.rst
index 9c8c8c9234e..1a9a1cad3a6 100644
--- a/Doc/library/email.encoders.rst
+++ b/Doc/library/email.encoders.rst
@@ -25,7 +25,7 @@ is especially true for :mimetype:`image/\*` and :mimetype:`text/\*` type message
containing binary data.
The :mod:`email` package provides some convenient encoders in its
-:mod:`~email.encoders` module. These encoders are actually used by the
+:mod:`!encoders` module. These encoders are actually used by the
:class:`~email.mime.audio.MIMEAudio` and :class:`~email.mime.image.MIMEImage`
class constructors to provide default encodings. All encoder functions take
exactly one argument, the message object to encode. They usually extract the
diff --git a/Doc/library/email.errors.rst b/Doc/library/email.errors.rst
index 689e7397cbc..2f7c9140cfc 100644
--- a/Doc/library/email.errors.rst
+++ b/Doc/library/email.errors.rst
@@ -8,7 +8,7 @@
--------------
-The following exception classes are defined in the :mod:`email.errors` module:
+The following exception classes are defined in the :mod:`!email.errors` module:
.. exception:: MessageError()
diff --git a/Doc/library/email.generator.rst b/Doc/library/email.generator.rst
index a3132d02687..6f4f813a0f8 100644
--- a/Doc/library/email.generator.rst
+++ b/Doc/library/email.generator.rst
@@ -232,7 +232,7 @@ a formatted string representation of a message object. For more detail, see
:mod:`email.message`.
-The :mod:`email.generator` module also provides a derived class,
+The :mod:`!email.generator` module also provides a derived class,
:class:`DecodedGenerator`, which is like the :class:`Generator` base class,
except that non-\ :mimetype:`text` parts are not serialized, but are instead
represented in the output stream by a string derived from a template filled
diff --git a/Doc/library/email.header.rst b/Doc/library/email.header.rst
index f49885b8785..e7e21d036e0 100644
--- a/Doc/library/email.header.rst
+++ b/Doc/library/email.header.rst
@@ -28,13 +28,13 @@ transferred using only 7-bit ASCII characters, so a slew of RFCs have been
written describing how to encode email containing non-ASCII characters into
:rfc:`2822`\ -compliant format. These RFCs include :rfc:`2045`, :rfc:`2046`,
:rfc:`2047`, and :rfc:`2231`. The :mod:`email` package supports these standards
-in its :mod:`email.header` and :mod:`email.charset` modules.
+in its :mod:`!email.header` and :mod:`email.charset` modules.
If you want to include non-ASCII characters in your email headers, say in the
:mailheader:`Subject` or :mailheader:`To` fields, you should use the
:class:`Header` class and assign the field in the :class:`~email.message.Message`
object to an instance of :class:`Header` instead of using a string for the header
-value. Import the :class:`Header` class from the :mod:`email.header` module.
+value. Import the :class:`Header` class from the :mod:`!email.header` module.
For example::
>>> from email.message import Message
@@ -170,7 +170,7 @@ Here is the :class:`Header` class description:
This method allows you to compare two :class:`Header` instances for
inequality.
-The :mod:`email.header` module also provides the following convenient functions.
+The :mod:`!email.header` module also provides the following convenient functions.
.. function:: decode_header(header)
diff --git a/Doc/library/email.iterators.rst b/Doc/library/email.iterators.rst
index 090981d84b4..ed300cdb30f 100644
--- a/Doc/library/email.iterators.rst
+++ b/Doc/library/email.iterators.rst
@@ -10,7 +10,7 @@
Iterating over a message object tree is fairly easy with the
:meth:`Message.walk <email.message.Message.walk>` method. The
-:mod:`email.iterators` module provides some useful higher level iterations over
+:mod:`!email.iterators` module provides some useful higher level iterations over
message object trees.
diff --git a/Doc/library/email.message.rst b/Doc/library/email.message.rst
index 0aa8e632c2c..f6908d2e6e9 100644
--- a/Doc/library/email.message.rst
+++ b/Doc/library/email.message.rst
@@ -14,7 +14,7 @@
.. versionadded:: 3.6 [1]_
The central class in the :mod:`email` package is the :class:`EmailMessage`
-class, imported from the :mod:`email.message` module. It is the base class for
+class, imported from the :mod:`!email.message` module. It is the base class for
the :mod:`email` object model. :class:`EmailMessage` provides the core
functionality for setting and querying header fields, for accessing message
bodies, and for creating or modifying structured messages.
diff --git a/Doc/library/email.parser.rst b/Doc/library/email.parser.rst
index 6a70714dc3e..6a67bf7c8e5 100644
--- a/Doc/library/email.parser.rst
+++ b/Doc/library/email.parser.rst
@@ -125,10 +125,10 @@ Here is the API for the :class:`BytesFeedParser`:
Parser API
^^^^^^^^^^
-The :class:`BytesParser` class, imported from the :mod:`email.parser` module,
+The :class:`BytesParser` class, imported from the :mod:`!email.parser` module,
provides an API that can be used to parse a message when the complete contents
of the message are available in a :term:`bytes-like object` or file. The
-:mod:`email.parser` module also provides :class:`Parser` for parsing strings,
+:mod:`!email.parser` module also provides :class:`Parser` for parsing strings,
and header-only parsers, :class:`BytesHeaderParser` and
:class:`HeaderParser`, which can be used if you're only interested in the
headers of the message. :class:`BytesHeaderParser` and :class:`HeaderParser`
@@ -155,7 +155,7 @@ message body, instead setting the payload to the raw body.
Read all the data from the binary file-like object *fp*, parse the
resulting bytes, and return the message object. *fp* must support
- both the :meth:`~io.IOBase.readline` and the :meth:`~io.IOBase.read`
+ both the :meth:`~io.IOBase.readline` and the :meth:`~io.BufferedIOBase.read`
methods.
The bytes contained in *fp* must be formatted as a block of :rfc:`5322`
diff --git a/Doc/library/email.policy.rst b/Doc/library/email.policy.rst
index 1ff3e2c3f8d..fef064114ec 100644
--- a/Doc/library/email.policy.rst
+++ b/Doc/library/email.policy.rst
@@ -602,7 +602,7 @@ The header objects and their attributes are described in
This concrete :class:`Policy` is the backward compatibility policy. It
replicates the behavior of the email package in Python 3.2. The
- :mod:`~email.policy` module also defines an instance of this class,
+ :mod:`!policy` module also defines an instance of this class,
:const:`compat32`, that is used as the default policy. Thus the default
behavior of the email package is to maintain compatibility with Python 3.2.
diff --git a/Doc/library/email.rst b/Doc/library/email.rst
index 66c42e4a500..03ac1783be0 100644
--- a/Doc/library/email.rst
+++ b/Doc/library/email.rst
@@ -12,10 +12,10 @@
--------------
-The :mod:`email` package is a library for managing email messages. It is
+The :mod:`!email` package is a library for managing email messages. It is
specifically *not* designed to do any sending of email messages to SMTP
(:rfc:`2821`), NNTP, or other servers; those are functions of modules such as
-:mod:`smtplib`. The :mod:`email` package attempts to be as
+:mod:`smtplib`. The :mod:`!email` package attempts to be as
RFC-compliant as possible, supporting :rfc:`5322` and :rfc:`6532`, as well as
such MIME-related RFCs as :rfc:`2045`, :rfc:`2046`, :rfc:`2047`, :rfc:`2183`,
and :rfc:`2231`.
@@ -68,7 +68,7 @@ high level structure in question, and not the details of how those structures
are represented. Since MIME content types are used widely in modern internet
software (not just email), this will be a familiar concept to many programmers.
-The following sections describe the functionality of the :mod:`email` package.
+The following sections describe the functionality of the :mod:`!email` package.
We start with the :mod:`~email.message` object model, which is the primary
interface an application will use, and follow that with the
:mod:`~email.parser` and :mod:`~email.generator` components. Then we cover the
@@ -102,7 +102,7 @@ compatibility reasons.
:class:`~email.message.EmailMessage`/:class:`~email.policy.EmailPolicy`
API.
-Contents of the :mod:`email` package documentation:
+Contents of the :mod:`!email` package documentation:
.. toctree::
diff --git a/Doc/library/email.utils.rst b/Doc/library/email.utils.rst
index 611549604fd..e0d2c19a3b0 100644
--- a/Doc/library/email.utils.rst
+++ b/Doc/library/email.utils.rst
@@ -8,7 +8,7 @@
--------------
-There are a couple of useful utilities provided in the :mod:`email.utils`
+There are a couple of useful utilities provided in the :mod:`!email.utils`
module:
.. function:: localtime(dt=None)
diff --git a/Doc/library/ensurepip.rst b/Doc/library/ensurepip.rst
index 32b92c01570..e0d77229b11 100644
--- a/Doc/library/ensurepip.rst
+++ b/Doc/library/ensurepip.rst
@@ -11,7 +11,7 @@
--------------
-The :mod:`ensurepip` package provides support for bootstrapping the ``pip``
+The :mod:`!ensurepip` package provides support for bootstrapping the ``pip``
installer into an existing Python installation or virtual environment. This
bootstrapping approach reflects the fact that ``pip`` is an independent
project with its own release cycle, and the latest available stable version
@@ -99,7 +99,7 @@ Providing both of the script selection options will trigger an exception.
Module API
----------
-:mod:`ensurepip` exposes two functions for programmatic use:
+:mod:`!ensurepip` exposes two functions for programmatic use:
.. function:: version()
diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst
index b39164e5475..ec7cbfb52b6 100644
--- a/Doc/library/enum.rst
+++ b/Doc/library/enum.rst
@@ -1053,7 +1053,7 @@ Utilities and Decorators
>>> enum.bin(~10) # ~10 is -11
'0b1 0101'
- .. versionadded:: 3.10
+ .. versionadded:: 3.11
---------------
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 3f1ec95005c..27d5caa43f8 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -221,7 +221,7 @@ The following exceptions are the exceptions that are usually raised.
.. exception:: EOFError
Raised when the :func:`input` function hits an end-of-file condition (EOF)
- without reading any data. (Note: the :meth:`!io.IOBase.read` and
+ without reading any data. (Note: the :meth:`io.TextIOBase.read` and
:meth:`io.IOBase.readline` methods return an empty string when they hit EOF.)
diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst
index c8ce86cc7af..4a08af4f90d 100644
--- a/Doc/library/fcntl.rst
+++ b/Doc/library/fcntl.rst
@@ -2,7 +2,6 @@
==========================================================
.. module:: fcntl
- :platform: Unix
:synopsis: The fcntl() and ioctl() system calls.
.. sectionauthor:: Jaap Vermeulen
@@ -53,7 +52,7 @@ descriptor.
the latter setting ``FD_CLOEXEC`` flag in addition.
.. versionchanged:: 3.12
- On Linux >= 4.5, the :mod:`fcntl` module exposes the ``FICLONE`` and
+ On Linux >= 4.5, the :mod:`!fcntl` module exposes the ``FICLONE`` and
``FICLONERANGE`` constants, which allow to share some data of one file with
another file by reflinking on some filesystems (e.g., btrfs, OCFS2, and
XFS). This behavior is commonly referred to as "copy-on-write".
@@ -91,7 +90,7 @@ The module defines the following functions:
Perform the operation *cmd* on file descriptor *fd* (file objects providing
a :meth:`~io.IOBase.fileno` method are accepted as well). The values used
for *cmd* are operating system dependent, and are available as constants
- in the :mod:`fcntl` module, using the same names as used in the relevant C
+ in the :mod:`!fcntl` module, using the same names as used in the relevant C
header files. The argument *arg* can either be an integer value, a
:term:`bytes-like object`, or a string.
The type and size of *arg* must match the type and size of
diff --git a/Doc/library/filecmp.rst b/Doc/library/filecmp.rst
index abd1b8c826d..e87a7869685 100644
--- a/Doc/library/filecmp.rst
+++ b/Doc/library/filecmp.rst
@@ -10,11 +10,11 @@
--------------
-The :mod:`filecmp` module defines functions to compare files and directories,
+The :mod:`!filecmp` module defines functions to compare files and directories,
with various optional time/correctness trade-offs. For comparing files,
see also the :mod:`difflib` module.
-The :mod:`filecmp` module defines the following functions:
+The :mod:`!filecmp` module defines the following functions:
.. function:: cmp(f1, f2, shallow=True)
diff --git a/Doc/library/fractions.rst b/Doc/library/fractions.rst
index d6d1c7a461c..575e90942d4 100644
--- a/Doc/library/fractions.rst
+++ b/Doc/library/fractions.rst
@@ -11,7 +11,7 @@
--------------
-The :mod:`fractions` module provides support for rational number arithmetic.
+The :mod:`!fractions` module provides support for rational number arithmetic.
A Fraction instance can be constructed from a pair of rational numbers, from
diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst
index bb153220672..9cbb387f40f 100644
--- a/Doc/library/ftplib.rst
+++ b/Doc/library/ftplib.rst
@@ -23,7 +23,7 @@ The default encoding is UTF-8, following :rfc:`2640`.
.. include:: ../includes/wasm-notavail.rst
-Here's a sample session using the :mod:`ftplib` module::
+Here's a sample session using the :mod:`!ftplib` module::
>>> from ftplib import FTP
>>> ftp = FTP('ftp.us.debian.org') # connect to host, default port
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 893e4f60e01..96b88b38039 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -597,17 +597,18 @@ are always available. They are listed here in alphabetical order.
.. warning::
This function executes arbitrary code. Calling it with
- user-supplied input may lead to security vulnerabilities.
+ untrusted user-supplied input will lead to security vulnerabilities.
The *source* argument is parsed and evaluated as a Python expression
(technically speaking, a condition list) using the *globals* and *locals*
mappings as global and local namespace. If the *globals* dictionary is
present and does not contain a value for the key ``__builtins__``, a
reference to the dictionary of the built-in module :mod:`builtins` is
- inserted under that key before *source* is parsed. That way you can
- control what builtins are available to the executed code by inserting your
- own ``__builtins__`` dictionary into *globals* before passing it to
- :func:`eval`. If the *locals* mapping is omitted it defaults to the
+ inserted under that key before *source* is parsed.
+ Overriding ``__builtins__`` can be used to restrict or change the available
+ names, but this is **not** a security mechanism: the executed code can
+ still access all builtins.
+ If the *locals* mapping is omitted it defaults to the
*globals* dictionary. If both mappings are omitted, the source is
executed with the *globals* and *locals* in the environment where
:func:`eval` is called. Note, *eval()* will only have access to the
@@ -658,7 +659,7 @@ are always available. They are listed here in alphabetical order.
.. warning::
This function executes arbitrary code. Calling it with
- user-supplied input may lead to security vulnerabilities.
+ untrusted user-supplied input will lead to security vulnerabilities.
This function supports dynamic execution of Python code. *source* must be
either a string or a code object. If it is a string, the string is parsed as
@@ -689,9 +690,10 @@ are always available. They are listed here in alphabetical order.
If the *globals* dictionary does not contain a value for the key
``__builtins__``, a reference to the dictionary of the built-in module
- :mod:`builtins` is inserted under that key. That way you can control what
- builtins are available to the executed code by inserting your own
- ``__builtins__`` dictionary into *globals* before passing it to :func:`exec`.
+ :mod:`builtins` is inserted under that key.
+ Overriding ``__builtins__`` can be used to restrict or change the available
+ names, but this is **not** a security mechanism: the executed code can
+ still access all builtins.
The *closure* argument specifies a closure--a tuple of cellvars.
It's only valid when the *object* is a code object containing
@@ -1843,19 +1845,19 @@ are always available. They are listed here in alphabetical order.
``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 NumPy and other third-party packages.
+ Slice objects are also generated when :ref:`slicing syntax <slicings>`
+ is used. For example: ``a[start:stop:step]`` or ``a[start:stop, i]``.
+
+ See :func:`itertools.islice` for an alternate version that returns an
+ :term:`iterator`.
.. attribute:: slice.start
- .. attribute:: slice.stop
- .. attribute:: slice.step
+ slice.stop
+ slice.step
- 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
- :term:`iterator`.
+ These read-only attributes are set to the argument values
+ (or their default). They have no other explicit functionality;
+ however, they are used by NumPy and other third-party packages.
.. versionchanged:: 3.12
Slice objects are now :term:`hashable` (provided :attr:`~slice.start`,
diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index 01db54bbb86..4babc246ea9 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -20,11 +20,11 @@
--------------
-The :mod:`functools` module is for higher-order functions: functions that act on
+The :mod:`!functools` module is for higher-order functions: functions that act on
or return other functions. In general, any callable object can be treated as a
function for the purposes of this module.
-The :mod:`functools` module defines the following functions:
+The :mod:`!functools` module defines the following functions:
.. decorator:: cache(user_function)
@@ -190,7 +190,7 @@ The :mod:`functools` module defines the following functions:
Note, type specificity applies only to the function's immediate arguments
rather than their contents. The scalar arguments, ``Decimal(42)`` and
- ``Fraction(42)`` are be treated as distinct calls with distinct results.
+ ``Fraction(42)`` are treated as distinct calls with distinct results.
In contrast, the tuple arguments ``('answer', Decimal(42))`` and
``('answer', Fraction(42))`` are treated as equivalent.
diff --git a/Doc/library/gc.rst b/Doc/library/gc.rst
index 35c5c7350cf..63dc8bce46d 100644
--- a/Doc/library/gc.rst
+++ b/Doc/library/gc.rst
@@ -20,7 +20,7 @@ can be disabled by calling ``gc.disable()``. To debug a leaking program call
``gc.DEBUG_SAVEALL``, causing garbage-collected objects to be saved in
gc.garbage for inspection.
-The :mod:`gc` module provides the following functions:
+The :mod:`!gc` module provides the following functions:
.. function:: enable()
diff --git a/Doc/library/getpass.rst b/Doc/library/getpass.rst
index a0c0c6dee2d..37ffbe1be55 100644
--- a/Doc/library/getpass.rst
+++ b/Doc/library/getpass.rst
@@ -14,7 +14,7 @@
.. include:: ../includes/wasm-notavail.rst
-The :mod:`getpass` module provides two functions:
+The :mod:`!getpass` module provides two functions:
.. function:: getpass(prompt='Password: ', stream=None, *, echo_char=None)
diff --git a/Doc/library/gettext.rst b/Doc/library/gettext.rst
index d0de83907eb..ddd0188e661 100644
--- a/Doc/library/gettext.rst
+++ b/Doc/library/gettext.rst
@@ -11,7 +11,7 @@
--------------
-The :mod:`gettext` module provides internationalization (I18N) and localization
+The :mod:`!gettext` module provides internationalization (I18N) and localization
(L10N) services for your Python modules and applications. It supports both the
GNU :program:`gettext` message catalog API and a higher level, class-based API that may
be more appropriate for Python files. The interface described below allows you
@@ -25,7 +25,7 @@ Some hints on localizing your Python modules and applications are also given.
GNU :program:`gettext` API
--------------------------
-The :mod:`gettext` module defines the following API, which is very similar to
+The :mod:`!gettext` module defines the following API, which is very similar to
the GNU :program:`gettext` API. If you use this API you will affect the
translation of your entire application globally. Often this is what you want if
your application is monolingual, with the choice of language dependent on the
@@ -37,7 +37,7 @@ class-based API instead.
.. function:: bindtextdomain(domain, localedir=None)
Bind the *domain* to the locale directory *localedir*. More concretely,
- :mod:`gettext` will look for binary :file:`.mo` files for the given domain using
+ :mod:`!gettext` will look for binary :file:`.mo` files for the given domain using
the path (on Unix): :file:`{localedir}/{language}/LC_MESSAGES/{domain}.mo`, where
*language* is searched for in the environment variables :envvar:`LANGUAGE`,
:envvar:`LC_ALL`, :envvar:`LC_MESSAGES`, and :envvar:`LANG` respectively.
@@ -114,7 +114,7 @@ Here's an example of typical usage for this API::
Class-based API
---------------
-The class-based API of the :mod:`gettext` module gives you more flexibility and
+The class-based API of the :mod:`!gettext` module gives you more flexibility and
greater convenience than the GNU :program:`gettext` API. It is the recommended
way of localizing your Python applications and modules. :mod:`!gettext` defines
a :class:`GNUTranslations` class which implements the parsing of GNU :file:`.mo` format
@@ -393,7 +393,7 @@ The Catalog constructor
.. index:: single: GNOME
-GNOME uses a version of the :mod:`gettext` module by James Henstridge, but this
+GNOME uses a version of the :mod:`!gettext` module by James Henstridge, but this
version has a slightly different API. Its documented usage was::
import gettext
@@ -425,7 +425,7 @@ take the following steps:
#. create language-specific translations of the message catalogs
-#. use the :mod:`gettext` module so that message strings are properly translated
+#. use the :mod:`!gettext` module so that message strings are properly translated
In order to prepare your code for I18N, you need to look at all the strings in
your files. Any string that needs to be translated should be marked by wrapping
@@ -473,10 +473,10 @@ supported natural language. They send back the completed
language-specific versions as a :file:`<language-name>.po` file that's
compiled into a machine-readable :file:`.mo` binary catalog file using
the :program:`msgfmt` program. The :file:`.mo` files are used by the
-:mod:`gettext` module for the actual translation processing at
+:mod:`!gettext` module for the actual translation processing at
run-time.
-How you use the :mod:`gettext` module in your code depends on whether you are
+How you use the :mod:`!gettext` module in your code depends on whether you are
internationalizing a single module or your entire application. The next two
sections will discuss each case.
diff --git a/Doc/library/graphlib.rst b/Doc/library/graphlib.rst
index 053d5f8231b..21f4d1fb938 100644
--- a/Doc/library/graphlib.rst
+++ b/Doc/library/graphlib.rst
@@ -204,7 +204,7 @@
Exceptions
----------
-The :mod:`graphlib` module defines the following exception classes:
+The :mod:`!graphlib` module defines the following exception classes:
.. exception:: CycleError
diff --git a/Doc/library/grp.rst b/Doc/library/grp.rst
index d1c7f22a209..f436970e791 100644
--- a/Doc/library/grp.rst
+++ b/Doc/library/grp.rst
@@ -2,7 +2,6 @@
==================================
.. module:: grp
- :platform: Unix
:synopsis: The group database (getgrnam() and friends).
--------------
diff --git a/Doc/library/gzip.rst b/Doc/library/gzip.rst
index 76de92b3069..a3c98d2f42b 100644
--- a/Doc/library/gzip.rst
+++ b/Doc/library/gzip.rst
@@ -15,7 +15,7 @@ like the GNU programs :program:`gzip` and :program:`gunzip` would.
The data compression is provided by the :mod:`zlib` module.
-The :mod:`gzip` module provides the :class:`GzipFile` class, as well as the
+The :mod:`!gzip` module provides the :class:`GzipFile` class, as well as the
:func:`.open`, :func:`compress` and :func:`decompress` convenience functions.
The :class:`GzipFile` class reads and writes :program:`gzip`\ -format files,
automatically compressing or decompressing the data so that it looks like an
@@ -272,10 +272,10 @@ Example of how to GZIP compress a binary string::
Command-line interface
----------------------
-The :mod:`gzip` module provides a simple command line interface to compress or
+The :mod:`!gzip` module provides a simple command line interface to compress or
decompress files.
-Once executed the :mod:`gzip` module keeps the input file(s).
+Once executed the :mod:`!gzip` module keeps the input file(s).
.. versionchanged:: 3.8
diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst
index 855a6efc9f7..84039ad2818 100644
--- a/Doc/library/hashlib.rst
+++ b/Doc/library/hashlib.rst
@@ -61,7 +61,7 @@ if you are using a rare "FIPS compliant" build of Python.
These correspond to :data:`algorithms_guaranteed`.
Additional algorithms may also be available if your Python distribution's
-:mod:`hashlib` was linked against a build of OpenSSL that provides others.
+:mod:`!hashlib` was linked against a build of OpenSSL that provides others.
Others *are not guaranteed available* on all installations and will only be
accessible by name via :func:`new`. See :data:`algorithms_available`.
@@ -390,7 +390,7 @@ BLAKE2 supports **keyed mode** (a faster and simpler replacement for HMAC_),
**salted hashing**, **personalization**, and **tree hashing**.
Hash objects from this module follow the API of standard library's
-:mod:`hashlib` objects.
+:mod:`!hashlib` objects.
Creating hash objects
diff --git a/Doc/library/http.cookiejar.rst b/Doc/library/http.cookiejar.rst
index fcb0069b760..90daaf28f8d 100644
--- a/Doc/library/http.cookiejar.rst
+++ b/Doc/library/http.cookiejar.rst
@@ -11,7 +11,7 @@
--------------
-The :mod:`http.cookiejar` module defines classes for automatic handling of HTTP
+The :mod:`!http.cookiejar` module defines classes for automatic handling of HTTP
cookies. It is useful for accessing websites that require small pieces of data
-- :dfn:`cookies` -- to be set on the client machine by an HTTP response from a
web server, and then returned to the server in later HTTP requests.
@@ -21,7 +21,7 @@ Both the regular Netscape cookie protocol and the protocol defined by
:rfc:`2109` cookies are parsed as Netscape cookies and subsequently treated
either as Netscape or RFC 2965 cookies according to the 'policy' in effect.
Note that the great majority of cookies on the internet are Netscape cookies.
-:mod:`http.cookiejar` attempts to follow the de-facto Netscape cookie protocol (which
+:mod:`!http.cookiejar` attempts to follow the de-facto Netscape cookie protocol (which
differs substantially from that set out in the original Netscape specification),
including taking note of the ``max-age`` and ``port`` cookie-attributes
introduced with RFC 2965.
@@ -109,7 +109,7 @@ The following classes are provided:
.. class:: Cookie()
This class represents Netscape, :rfc:`2109` and :rfc:`2965` cookies. It is not
- expected that users of :mod:`http.cookiejar` construct their own :class:`Cookie`
+ expected that users of :mod:`!http.cookiejar` construct their own :class:`Cookie`
instances. Instead, if necessary, call :meth:`make_cookies` on a
:class:`CookieJar` instance.
@@ -121,13 +121,13 @@ The following classes are provided:
Module :mod:`http.cookies`
HTTP cookie classes, principally useful for server-side code. The
- :mod:`http.cookiejar` and :mod:`http.cookies` modules do not depend on each
+ :mod:`!http.cookiejar` and :mod:`http.cookies` modules do not depend on each
other.
https://curl.se/rfc/cookie_spec.html
The specification of the original Netscape cookie protocol. Though this is
still the dominant protocol, the 'Netscape cookie protocol' implemented by all
- the major browsers (and :mod:`http.cookiejar`) only bears a passing resemblance to
+ the major browsers (and :mod:`!http.cookiejar`) only bears a passing resemblance to
the one sketched out in ``cookie_spec.html``.
:rfc:`2109` - HTTP State Management Mechanism
@@ -617,7 +617,7 @@ standard cookie-attributes specified in the various cookie standards. The
correspondence is not one-to-one, because there are complicated rules for
assigning default values, because the ``max-age`` and ``expires``
cookie-attributes contain equivalent information, and because :rfc:`2109` cookies
-may be 'downgraded' by :mod:`http.cookiejar` from version 1 to version 0 (Netscape)
+may be 'downgraded' by :mod:`!http.cookiejar` from version 1 to version 0 (Netscape)
cookies.
Assignment to these attributes should not be necessary other than in rare
@@ -629,7 +629,7 @@ internal consistency, so you should know what you're doing if you do that.
Integer or :const:`None`. Netscape cookies have :attr:`version` 0. :rfc:`2965` and
:rfc:`2109` cookies have a ``version`` cookie-attribute of 1. However, note that
- :mod:`http.cookiejar` may 'downgrade' RFC 2109 cookies to Netscape cookies, in which
+ :mod:`!http.cookiejar` may 'downgrade' RFC 2109 cookies to Netscape cookies, in which
case :attr:`version` is 0.
@@ -692,7 +692,7 @@ internal consistency, so you should know what you're doing if you do that.
``True`` if this cookie was received as an :rfc:`2109` cookie (ie. the cookie
arrived in a :mailheader:`Set-Cookie` header, and the value of the Version
cookie-attribute in that header was 1). This attribute is provided because
- :mod:`http.cookiejar` may 'downgrade' RFC 2109 cookies to Netscape cookies, in
+ :mod:`!http.cookiejar` may 'downgrade' RFC 2109 cookies to Netscape cookies, in
which case :attr:`version` is 0.
@@ -744,7 +744,7 @@ The :class:`Cookie` class also defines the following method:
Examples
--------
-The first example shows the most common usage of :mod:`http.cookiejar`::
+The first example shows the most common usage of :mod:`!http.cookiejar`::
import http.cookiejar, urllib.request
cj = http.cookiejar.CookieJar()
diff --git a/Doc/library/http.cookies.rst b/Doc/library/http.cookies.rst
index 0257f74706f..1b2d17975a5 100644
--- a/Doc/library/http.cookies.rst
+++ b/Doc/library/http.cookies.rst
@@ -11,7 +11,7 @@
--------------
-The :mod:`http.cookies` module defines classes for abstracting the concept of
+The :mod:`!http.cookies` module defines classes for abstracting the concept of
cookies, an HTTP state management mechanism. It supports both simple string-only
cookies, and provides an abstraction for having any serializable data-type as
cookie value.
@@ -65,7 +65,7 @@ in a cookie name (as :attr:`~Morsel.key`).
Module :mod:`http.cookiejar`
HTTP cookie handling for web *clients*. The :mod:`http.cookiejar` and
- :mod:`http.cookies` modules do not depend on each other.
+ :mod:`!http.cookies` modules do not depend on each other.
:rfc:`2109` - HTTP State Management Mechanism
This is the state management specification implemented by this module.
@@ -264,7 +264,7 @@ Morsel Objects
Example
-------
-The following example demonstrates how to use the :mod:`http.cookies` module.
+The following example demonstrates how to use the :mod:`!http.cookies` module.
.. doctest::
:options: +NORMALIZE_WHITESPACE
diff --git a/Doc/library/http.rst b/Doc/library/http.rst
index b0bdfc65e45..43a801416e2 100644
--- a/Doc/library/http.rst
+++ b/Doc/library/http.rst
@@ -12,7 +12,7 @@
--------------
-:mod:`http` is a package that collects several modules for working with the
+:mod:`!http` is a package that collects several modules for working with the
HyperText Transfer Protocol:
* :mod:`http.client` is a low-level HTTP protocol client; for high-level URL
@@ -22,7 +22,7 @@ HyperText Transfer Protocol:
* :mod:`http.cookiejar` provides persistence of cookies
-The :mod:`http` module also defines the following enums that help you work with http related code:
+The :mod:`!http` module also defines the following enums that help you work with http related code:
.. class:: HTTPStatus
diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst
index 41026e2b303..b47da97d3f2 100644
--- a/Doc/library/http.server.rst
+++ b/Doc/library/http.server.rst
@@ -19,7 +19,7 @@ This module defines classes for implementing HTTP servers.
.. warning::
- :mod:`http.server` is not recommended for production. It only implements
+ :mod:`!http.server` is not recommended for production. It only implements
:ref:`basic security checks <http.server-security>`.
.. include:: ../includes/wasm-notavail.rst
@@ -512,7 +512,7 @@ such as using different index file names by overriding the class attribute
Command-line interface
----------------------
-:mod:`http.server` can also be invoked directly using the :option:`-m`
+:mod:`!http.server` can also be invoked directly using the :option:`-m`
switch of the interpreter. The following example illustrates how to serve
files relative to the current directory::
@@ -572,7 +572,7 @@ The following options are accepted:
.. deprecated-removed:: 3.13 3.15
- :mod:`http.server` command line ``--cgi`` support is being removed
+ :mod:`!http.server` command line ``--cgi`` support is being removed
because :class:`CGIHTTPRequestHandler` is being removed.
.. warning::
diff --git a/Doc/library/imaplib.rst b/Doc/library/imaplib.rst
index 3eee2b9e607..166455bae02 100644
--- a/Doc/library/imaplib.rst
+++ b/Doc/library/imaplib.rst
@@ -29,7 +29,7 @@ note that the ``STATUS`` command is not supported in IMAP4.
.. include:: ../includes/wasm-notavail.rst
-Three classes are provided by the :mod:`imaplib` module, :class:`IMAP4` is the
+Three classes are provided by the :mod:`!imaplib` module, :class:`IMAP4` is the
base class:
diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
index bd937811f41..2e65eff83f5 100644
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -17,7 +17,7 @@
Introduction
------------
-The purpose of the :mod:`importlib` package is three-fold.
+The purpose of the :mod:`!importlib` package is three-fold.
One is to provide the
implementation of the :keyword:`import` statement (and thus, by extension, the
@@ -211,8 +211,8 @@ Functions
in unexpected behavior. It's recommended to use the :class:`threading.Lock`
or other synchronization primitives for thread-safe module reloading.
-:mod:`importlib.abc` -- Abstract base classes related to import
----------------------------------------------------------------
+:mod:`!importlib.abc` -- Abstract base classes related to import
+----------------------------------------------------------------
.. module:: importlib.abc
:synopsis: Abstract base classes related to import
@@ -222,7 +222,7 @@ Functions
--------------
-The :mod:`importlib.abc` module contains all of the core abstract base classes
+The :mod:`!importlib.abc` module contains all of the core abstract base classes
used by :keyword:`import`. Some subclasses of the core abstract base classes
are also provided to help in implementing the core ABCs.
@@ -637,8 +637,8 @@ ABC hierarchy::
itself does not end in ``__init__``.
-:mod:`importlib.machinery` -- Importers and path hooks
-------------------------------------------------------
+:mod:`!importlib.machinery` -- Importers and path hooks
+-------------------------------------------------------
.. module:: importlib.machinery
:synopsis: Importers and path hooks
@@ -1136,8 +1136,8 @@ find and load modules.
Path to the ``.fwork`` file for the extension module.
-:mod:`importlib.util` -- Utility code for importers
----------------------------------------------------
+:mod:`!importlib.util` -- Utility code for importers
+----------------------------------------------------
.. module:: importlib.util
:synopsis: Utility code for importers
diff --git a/Doc/library/index.rst b/Doc/library/index.rst
index 163e1679c65..8fc77be520d 100644
--- a/Doc/library/index.rst
+++ b/Doc/library/index.rst
@@ -43,6 +43,7 @@ the `Python Package Index <https://pypi.org>`_.
constants.rst
stdtypes.rst
exceptions.rst
+ threadsafety.rst
text.rst
binary.rst
diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index 7bfacc78988..5e3c5c1f155 100644
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -16,7 +16,7 @@
--------------
-The :mod:`inspect` module provides several useful functions to help get
+The :mod:`!inspect` module provides several useful functions to help get
information about live objects such as modules, classes, methods, functions,
tracebacks, frame objects, and code objects. For example, it can help you
examine the contents of a class, retrieve the source code of a method, extract
@@ -1755,7 +1755,7 @@ which is a bitmap of the following flags:
The flags are specific to CPython, and may not be defined in other
Python implementations. Furthermore, the flags are an implementation
detail, and can be removed or deprecated in future Python releases.
- It's recommended to use public APIs from the :mod:`inspect` module
+ It's recommended to use public APIs from the :mod:`!inspect` module
for any introspection needs.
@@ -1797,7 +1797,7 @@ Buffer flags
Command-line interface
----------------------
-The :mod:`inspect` module also provides a basic introspection capability
+The :mod:`!inspect` module also provides a basic introspection capability
from the command line.
.. program:: inspect
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index de5cab5aee6..55ec6ee5b31 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -24,7 +24,7 @@ Overview
.. index::
single: file object; io module
-The :mod:`io` module provides Python's main facilities for dealing with various
+The :mod:`!io` module provides Python's main facilities for dealing with various
types of I/O. There are three main types of I/O: *text I/O*, *binary I/O*
and *raw I/O*. These are generic categories, and various backing stores can
be used for each of them. A concrete object belonging to any of these
@@ -292,7 +292,7 @@ interface to a buffered raw stream (:class:`BufferedIOBase`). Finally,
Argument names are not part of the specification, and only the arguments of
:func:`open` are intended to be used as keyword arguments.
-The following table summarizes the ABCs provided by the :mod:`io` module:
+The following table summarizes the ABCs provided by the :mod:`!io` module:
.. tabularcolumns:: |l|l|L|L|
@@ -587,7 +587,7 @@ I/O Base Classes
When the underlying raw stream is non-blocking, implementations may
either raise :exc:`BlockingIOError` or return ``None`` if no data is
- available. :mod:`io` implementations return ``None``.
+ available. :mod:`!io` implementations return ``None``.
.. method:: read1(size=-1, /)
@@ -600,7 +600,7 @@ I/O Base Classes
When the underlying raw stream is non-blocking, implementations may
either raise :exc:`BlockingIOError` or return ``None`` if no data is
- available. :mod:`io` implementations return ``None``.
+ available. :mod:`!io` implementations return ``None``.
.. method:: readinto(b, /)
diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst
index 9e887d8e657..c546d913cbe 100644
--- a/Doc/library/ipaddress.rst
+++ b/Doc/library/ipaddress.rst
@@ -10,7 +10,7 @@
--------------
-:mod:`ipaddress` provides the capabilities to create, manipulate and
+:mod:`!ipaddress` provides the capabilities to create, manipulate and
operate on IPv4 and IPv6 addresses and networks.
The functions and classes in this module make it straightforward to handle
@@ -34,7 +34,7 @@ This is the full module API reference—for an overview and introduction, see
Convenience factory functions
-----------------------------
-The :mod:`ipaddress` module provides factory functions to conveniently create
+The :mod:`!ipaddress` module provides factory functions to conveniently create
IP addresses, networks and interfaces:
.. function:: ip_address(address)
@@ -1027,7 +1027,7 @@ The module also provides the following module level functions:
IPv4Address('192.0.2.0') <= IPv4Network('192.0.2.0/24')
doesn't make sense. There are some times however, where you may wish to
- have :mod:`ipaddress` sort these anyway. If you need to do this, you can use
+ have :mod:`!ipaddress` sort these anyway. If you need to do this, you can use
this function as the *key* argument to :func:`sorted`.
*obj* is either a network or address object.
diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
index 08dacb505f7..53f4b31e17d 100644
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -30,18 +30,7 @@ For instance, SML provides a tabulation tool: ``tabulate(f)`` which produces a
sequence ``f(0), f(1), ...``. The same effect can be achieved in Python
by combining :func:`map` and :func:`count` to form ``map(f, count())``.
-
-**Infinite iterators:**
-
-================== ================= ================================================= =========================================
-Iterator Arguments Results Example
-================== ================= ================================================= =========================================
-:func:`count` [start[, step]] start, start+step, start+2*step, ... ``count(10) → 10 11 12 13 14 ...``
-:func:`cycle` p p0, p1, ... plast, p0, p1, ... ``cycle('ABCD') → A B C D A B C D ...``
-:func:`repeat` elem [,n] elem, elem, elem, ... endlessly or up to n times ``repeat(10, 3) → 10 10 10``
-================== ================= ================================================= =========================================
-
-**Iterators terminating on the shortest input sequence:**
+**General iterators:**
============================ ============================ ================================================= =============================================================
Iterator Arguments Results Example
@@ -51,11 +40,14 @@ Iterator Arguments Results
:func:`chain` p, q, ... p0, p1, ... plast, q0, q1, ... ``chain('ABC', 'DEF') → A B C D E F``
:func:`chain.from_iterable` iterable p0, p1, ... plast, q0, q1, ... ``chain.from_iterable(['ABC', 'DEF']) → A B C D E F``
:func:`compress` data, selectors (d[0] if s[0]), (d[1] if s[1]), ... ``compress('ABCDEF', [1,0,1,0,1,1]) → A C E F``
+:func:`count` [start[, step]] start, start+step, start+2*step, ... ``count(10) → 10 11 12 13 14 ...``
+:func:`cycle` p p0, p1, ... plast, p0, p1, ... ``cycle('ABCD') → A B C D A B C D ...``
:func:`dropwhile` predicate, seq seq[n], seq[n+1], starting when predicate fails ``dropwhile(lambda x: x<5, [1,4,6,3,8]) → 6 3 8``
:func:`filterfalse` predicate, seq elements of seq where predicate(elem) fails ``filterfalse(lambda x: x<5, [1,4,6,3,8]) → 6 8``
:func:`groupby` iterable[, key] sub-iterators grouped by value of key(v) ``groupby(['A','B','DEF'], len) → (1, A B) (3, DEF)``
:func:`islice` seq, [start,] stop [, step] elements from seq[start:stop:step] ``islice('ABCDEFG', 2, None) → C D E F G``
:func:`pairwise` iterable (p[0], p[1]), (p[1], p[2]) ``pairwise('ABCDEFG') → AB BC CD DE EF FG``
+:func:`repeat` elem [,n] elem, elem, elem, ... endlessly or up to n times ``repeat(10, 3) → 10 10 10``
:func:`starmap` func, seq func(\*seq[0]), func(\*seq[1]), ... ``starmap(pow, [(2,5), (3,2), (10,3)]) → 32 9 1000``
:func:`takewhile` predicate, seq seq[0], seq[1], until predicate fails ``takewhile(lambda x: x<5, [1,4,6,3,8]) → 1 4``
:func:`tee` it, n it1, it2, ... itn splits one iterator into n ``tee('ABC', 2) → A B C, A B C``
@@ -845,7 +837,8 @@ and :term:`generators <generator>` which incur interpreter overhead.
from contextlib import suppress
from functools import reduce
from math import comb, isqrt, prod, sumprod
- from operator import getitem, is_not, itemgetter, mul, neg
+ from operator import getitem, is_not, itemgetter, mul, neg, truediv
+
# ==== Basic one liners ====
@@ -858,9 +851,10 @@ and :term:`generators <generator>` which incur interpreter overhead.
# prepend(1, [2, 3, 4]) → 1 2 3 4
return chain([value], iterable)
- def tabulate(function, start=0):
- "Return function(0), function(1), ..."
- return map(function, count(start))
+ def running_mean(iterable):
+ "Yield the average of all values seen so far."
+ # running_mean([8.5, 9.5, 7.5, 6.5]) -> 8.5 9.0 8.5 8.0
+ return map(truediv, accumulate(iterable), count(1))
def repeatfunc(function, times=None, *args):
"Repeat calls to a function with specified arguments."
@@ -913,6 +907,7 @@ and :term:`generators <generator>` which incur interpreter overhead.
# all_equal('4٤௪౪໔', key=int) → True
return len(take(2, groupby(iterable, key))) <= 1
+
# ==== Data pipelines ====
def unique_justseen(iterable, key=None):
@@ -1021,6 +1016,7 @@ and :term:`generators <generator>` which incur interpreter overhead.
while True:
yield function()
+
# ==== Mathematical operations ====
def multinomial(*counts):
@@ -1040,6 +1036,7 @@ and :term:`generators <generator>` which incur interpreter overhead.
# sum_of_squares([10, 20, 30]) → 1400
return sumprod(*tee(iterable))
+
# ==== Matrix operations ====
def reshape(matrix, columns):
@@ -1058,6 +1055,7 @@ and :term:`generators <generator>` which incur interpreter overhead.
n = len(m2[0])
return batched(starmap(sumprod, product(m1, transpose(m2))), n)
+
# ==== Polynomial arithmetic ====
def convolve(signal, kernel):
@@ -1114,6 +1112,7 @@ and :term:`generators <generator>` which incur interpreter overhead.
powers = reversed(range(1, n))
return list(map(mul, coefficients, powers))
+
# ==== Number theory ====
def sieve(n):
@@ -1230,8 +1229,8 @@ and :term:`generators <generator>` which incur interpreter overhead.
[(0, 'a'), (1, 'b'), (2, 'c')]
- >>> list(islice(tabulate(lambda x: 2*x), 4))
- [0, 2, 4, 6]
+ >>> list(running_mean([8.5, 9.5, 7.5, 6.5]))
+ [8.5, 9.0, 8.5, 8.0]
>>> for _ in loops(5):
@@ -1798,6 +1797,10 @@ and :term:`generators <generator>` which incur interpreter overhead.
# Old recipes and their tests which are guaranteed to continue to work.
+ def tabulate(function, start=0):
+ "Return function(0), function(1), ..."
+ return map(function, count(start))
+
def old_sumprod_recipe(vec1, vec2):
"Compute a sum of products."
return sum(starmap(operator.mul, zip(vec1, vec2, strict=True)))
@@ -1877,6 +1880,10 @@ and :term:`generators <generator>` which incur interpreter overhead.
.. doctest::
:hide:
+ >>> list(islice(tabulate(lambda x: 2*x), 4))
+ [0, 2, 4, 6]
+
+
>>> dotproduct([1,2,3], [4,5,6])
32
diff --git a/Doc/library/json.rst b/Doc/library/json.rst
index 8b4217c210d..57aad5ba9d1 100644
--- a/Doc/library/json.rst
+++ b/Doc/library/json.rst
@@ -121,7 +121,7 @@ Extending :class:`JSONEncoder`::
['[2.0', ', 1.0', ']']
-Using :mod:`json` from the shell to validate and pretty-print:
+Using :mod:`!json` from the shell to validate and pretty-print:
.. code-block:: shell-session
@@ -747,8 +747,8 @@ Command-line interface
--------------
-The :mod:`json` module can be invoked as a script via ``python -m json``
-to validate and pretty-print JSON objects. The :mod:`json.tool` submodule
+The :mod:`!json` module can be invoked as a script via ``python -m json``
+to validate and pretty-print JSON objects. The :mod:`!json.tool` submodule
implements this interface.
If the optional ``infile`` and ``outfile`` arguments are not
@@ -769,7 +769,7 @@ specified, :data:`sys.stdin` and :data:`sys.stdout` will be used respectively:
alphabetically by key.
.. versionchanged:: 3.14
- The :mod:`json` module may now be directly executed as
+ The :mod:`!json` module may now be directly executed as
``python -m json``. For backwards compatibility, invoking
the CLI as ``python -m json.tool`` remains supported.
diff --git a/Doc/library/linecache.rst b/Doc/library/linecache.rst
index 07305a2a39b..0a5373ec976 100644
--- a/Doc/library/linecache.rst
+++ b/Doc/library/linecache.rst
@@ -10,7 +10,7 @@
--------------
-The :mod:`linecache` module allows one to get any line from a Python source file, while
+The :mod:`!linecache` module allows one to get any line from a Python source file, while
attempting to optimize internally, using a cache, the common case where many
lines are read from a single file. This is used by the :mod:`traceback` module
to retrieve source lines for inclusion in the formatted traceback.
@@ -19,7 +19,7 @@ The :func:`tokenize.open` function is used to open files. This
function uses :func:`tokenize.detect_encoding` to get the encoding of the
file; in the absence of an encoding token, the file encoding defaults to UTF-8.
-The :mod:`linecache` module defines the following functions:
+The :mod:`!linecache` module defines the following functions:
.. function:: getline(filename, lineno, module_globals=None)
diff --git a/Doc/library/locale.rst b/Doc/library/locale.rst
index 0f49f30b9d7..81ac46eea87 100644
--- a/Doc/library/locale.rst
+++ b/Doc/library/locale.rst
@@ -11,17 +11,17 @@
--------------
-The :mod:`locale` module opens access to the POSIX locale database and
+The :mod:`!locale` module opens access to the POSIX locale database and
functionality. The POSIX locale mechanism allows programmers to deal with
certain cultural issues in an application, without requiring the programmer to
know all the specifics of each country where the software is executed.
.. index:: pair: module; _locale
-The :mod:`locale` module is implemented on top of the :mod:`!_locale` module,
+The :mod:`!locale` module is implemented on top of the :mod:`!_locale` module,
which in turn uses an ANSI C locale implementation if available.
-The :mod:`locale` module defines the following exception and functions:
+The :mod:`!locale` module defines the following exception and functions:
.. exception:: Error
@@ -535,7 +535,7 @@ The :mod:`locale` module defines the following exception and functions:
.. data:: LC_COLLATE
Locale category for sorting strings. The functions :func:`strcoll` and
- :func:`strxfrm` of the :mod:`locale` module are affected.
+ :func:`strxfrm` of the :mod:`!locale` module are affected.
.. data:: LC_TIME
@@ -564,7 +564,7 @@ The :mod:`locale` module defines the following exception and functions:
.. data:: LC_NUMERIC
Locale category for formatting numbers. The functions :func:`format_string`,
- :func:`atoi`, :func:`atof` and :func:`.str` of the :mod:`locale` module are
+ :func:`atoi`, :func:`atof` and :func:`.str` of the :mod:`!locale` module are
affected by that category. All other numeric formatting operations are not
affected.
@@ -688,7 +688,7 @@ the current locale is. But since the return value can only be used portably to
restore it, that is not very useful (except perhaps to find out whether or not
the locale is ``C``).
-When Python code uses the :mod:`locale` module to change the locale, this also
+When Python code uses the :mod:`!locale` module to change the locale, this also
affects the embedding application. If the embedding application doesn't want
this to happen, it should remove the :mod:`!_locale` extension module (which does
all the work) from the table of built-in modules in the :file:`config.c` file,
diff --git a/Doc/library/logging.config.rst b/Doc/library/logging.config.rst
index 96cca3073fe..6709062dfca 100644
--- a/Doc/library/logging.config.rst
+++ b/Doc/library/logging.config.rst
@@ -28,7 +28,7 @@ Configuration functions
^^^^^^^^^^^^^^^^^^^^^^^
The following functions configure the logging module. They are located in the
-:mod:`logging.config` module. Their use is optional --- you can configure the
+:mod:`!logging.config` module. Their use is optional --- you can configure the
logging module using these functions or by making calls to the main API (defined
in :mod:`logging` itself) and defining handlers which are declared either in
:mod:`logging` or :mod:`logging.handlers`.
@@ -55,7 +55,7 @@ in :mod:`logging` itself) and defining handlers which are declared either in
Parsing is performed by the :class:`DictConfigurator` class, whose
constructor is passed the dictionary used for configuration, and
- has a :meth:`configure` method. The :mod:`logging.config` module
+ has a :meth:`configure` method. The :mod:`!logging.config` module
has a callable attribute :attr:`dictConfigClass`
which is initially set to :class:`DictConfigurator`.
You can replace the value of :attr:`dictConfigClass` with a
diff --git a/Doc/library/logging.handlers.rst b/Doc/library/logging.handlers.rst
index c9cfbdb4126..d128f64aae7 100644
--- a/Doc/library/logging.handlers.rst
+++ b/Doc/library/logging.handlers.rst
@@ -160,7 +160,7 @@ WatchedFileHandler
.. currentmodule:: logging.handlers
-The :class:`WatchedFileHandler` class, located in the :mod:`logging.handlers`
+The :class:`WatchedFileHandler` class, located in the :mod:`!logging.handlers`
module, is a :class:`FileHandler` which watches the file it is logging to. If
the file changes, it is closed and reopened using the file name.
@@ -213,7 +213,7 @@ for this value.
BaseRotatingHandler
^^^^^^^^^^^^^^^^^^^
-The :class:`BaseRotatingHandler` class, located in the :mod:`logging.handlers`
+The :class:`BaseRotatingHandler` class, located in the :mod:`!logging.handlers`
module, is the base class for the rotating file handlers,
:class:`RotatingFileHandler` and :class:`TimedRotatingFileHandler`. You should
not need to instantiate this class, but it has attributes and methods you may
@@ -307,7 +307,7 @@ For an example, see :ref:`cookbook-rotator-namer`.
RotatingFileHandler
^^^^^^^^^^^^^^^^^^^
-The :class:`RotatingFileHandler` class, located in the :mod:`logging.handlers`
+The :class:`RotatingFileHandler` class, located in the :mod:`!logging.handlers`
module, supports rotation of disk log files.
@@ -362,7 +362,7 @@ TimedRotatingFileHandler
^^^^^^^^^^^^^^^^^^^^^^^^
The :class:`TimedRotatingFileHandler` class, located in the
-:mod:`logging.handlers` module, supports rotation of disk log files at certain
+:mod:`!logging.handlers` module, supports rotation of disk log files at certain
timed intervals.
@@ -475,7 +475,7 @@ timed intervals.
SocketHandler
^^^^^^^^^^^^^
-The :class:`SocketHandler` class, located in the :mod:`logging.handlers` module,
+The :class:`SocketHandler` class, located in the :mod:`!logging.handlers` module,
sends logging output to a network socket. The base class uses a TCP socket.
@@ -571,7 +571,7 @@ sends logging output to a network socket. The base class uses a TCP socket.
DatagramHandler
^^^^^^^^^^^^^^^
-The :class:`DatagramHandler` class, located in the :mod:`logging.handlers`
+The :class:`DatagramHandler` class, located in the :mod:`!logging.handlers`
module, inherits from :class:`SocketHandler` to support sending logging messages
over UDP sockets.
@@ -618,7 +618,7 @@ over UDP sockets.
SysLogHandler
^^^^^^^^^^^^^
-The :class:`SysLogHandler` class, located in the :mod:`logging.handlers` module,
+The :class:`SysLogHandler` class, located in the :mod:`!logging.handlers` module,
supports sending logging messages to a remote or local Unix syslog.
@@ -797,7 +797,7 @@ supports sending logging messages to a remote or local Unix syslog.
NTEventLogHandler
^^^^^^^^^^^^^^^^^
-The :class:`NTEventLogHandler` class, located in the :mod:`logging.handlers`
+The :class:`NTEventLogHandler` class, located in the :mod:`!logging.handlers`
module, supports sending logging messages to a local Windows NT, Windows 2000 or
Windows XP event log. Before you can use it, you need Mark Hammond's Win32
extensions for Python installed.
@@ -864,7 +864,7 @@ extensions for Python installed.
SMTPHandler
^^^^^^^^^^^
-The :class:`SMTPHandler` class, located in the :mod:`logging.handlers` module,
+The :class:`SMTPHandler` class, located in the :mod:`!logging.handlers` module,
supports sending logging messages to an email address via SMTP.
@@ -905,7 +905,7 @@ supports sending logging messages to an email address via SMTP.
MemoryHandler
^^^^^^^^^^^^^
-The :class:`MemoryHandler` class, located in the :mod:`logging.handlers` module,
+The :class:`MemoryHandler` class, located in the :mod:`!logging.handlers` module,
supports buffering of logging records in memory, periodically flushing them to a
:dfn:`target` handler. Flushing occurs whenever the buffer is full, or when an
event of a certain severity or greater is seen.
@@ -985,7 +985,7 @@ should, then :meth:`flush` is expected to do the flushing.
HTTPHandler
^^^^^^^^^^^
-The :class:`HTTPHandler` class, located in the :mod:`logging.handlers` module,
+The :class:`HTTPHandler` class, located in the :mod:`!logging.handlers` module,
supports sending logging messages to a web server, using either ``GET`` or
``POST`` semantics.
@@ -1037,7 +1037,7 @@ QueueHandler
.. versionadded:: 3.2
-The :class:`QueueHandler` class, located in the :mod:`logging.handlers` module,
+The :class:`QueueHandler` class, located in the :mod:`!logging.handlers` module,
supports sending logging messages to a queue, such as those implemented in the
:mod:`queue` or :mod:`multiprocessing` modules.
@@ -1130,7 +1130,7 @@ QueueListener
.. versionadded:: 3.2
-The :class:`QueueListener` class, located in the :mod:`logging.handlers`
+The :class:`QueueListener` class, located in the :mod:`!logging.handlers`
module, supports receiving logging messages from a queue, such as those
implemented in the :mod:`queue` or :mod:`multiprocessing` modules. The
messages are received from a queue in an internal thread and passed, on
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index 9d93ac110c9..6e38d45504c 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -1534,7 +1534,7 @@ Module-Level Attributes
Integration with the warnings module
------------------------------------
-The :func:`captureWarnings` function can be used to integrate :mod:`logging`
+The :func:`captureWarnings` function can be used to integrate :mod:`!logging`
with the :mod:`warnings` module.
.. function:: captureWarnings(capture)
@@ -1565,7 +1565,7 @@ with the :mod:`warnings` module.
library.
`Original Python logging package <https://old.red-dove.com/python_logging.html>`_
- This is the original source for the :mod:`logging` package. The version of the
+ This is the original source for the :mod:`!logging` package. The version of the
package available from this site is suitable for use with Python 1.5.2, 2.1.x
- and 2.2.x, which do not include the :mod:`logging` package in the standard
+ and 2.2.x, which do not include the :mod:`!logging` package in the standard
library.
diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst
index 62e289573c0..ed135bf02cb 100644
--- a/Doc/library/mailbox.rst
+++ b/Doc/library/mailbox.rst
@@ -1025,7 +1025,7 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
.. method:: remove_flag(flag)
Unset the flag(s) specified by *flag* without changing other flags. To
- remove more than one flag at a time, *flag* maybe a string of more than
+ remove more than one flag at a time, *flag* may be a string of more than
one character. If "info" contains experimental information rather than
flags, the current "info" is not modified.
@@ -1190,7 +1190,7 @@ When a :class:`!MaildirMessage` instance is created based upon a
.. method:: remove_flag(flag)
Unset the flag(s) specified by *flag* without changing other flags. To
- remove more than one flag at a time, *flag* maybe a string of more than
+ remove more than one flag at a time, *flag* may be a string of more than
one character.
When an :class:`!mboxMessage` instance is created based upon a
@@ -1562,7 +1562,7 @@ When a :class:`!BabylMessage` instance is created based upon an
.. method:: remove_flag(flag)
Unset the flag(s) specified by *flag* without changing other flags. To
- remove more than one flag at a time, *flag* maybe a string of more than
+ remove more than one flag at a time, *flag* may be a string of more than
one character.
When an :class:`!MMDFMessage` instance is created based upon a
@@ -1641,7 +1641,7 @@ The following exception classes are defined in the :mod:`!mailbox` module:
.. exception:: Error()
- The based class for all other module-specific exceptions.
+ The base class for all other module-specific exceptions.
.. exception:: NoSuchMailboxError()
@@ -1661,7 +1661,7 @@ The following exception classes are defined in the :mod:`!mailbox` module:
Raised when some mailbox-related condition beyond the control of the program
causes it to be unable to proceed, such as when failing to acquire a lock that
- another program already holds a lock, or when a uniquely generated file name
+ another program already holds, or when a uniquely generated file name
already exists.
diff --git a/Doc/library/marshal.rst b/Doc/library/marshal.rst
index e8e9071a5c9..ed182ea24e8 100644
--- a/Doc/library/marshal.rst
+++ b/Doc/library/marshal.rst
@@ -20,7 +20,7 @@ rarely does). [#]_
This is not a general "persistence" module. For general persistence and
transfer of Python objects through RPC calls, see the modules :mod:`pickle` and
-:mod:`shelve`. The :mod:`marshal` module exists mainly to support reading and
+:mod:`shelve`. The :mod:`!marshal` module exists mainly to support reading and
writing the "pseudo-compiled" code for Python modules of :file:`.pyc` files.
Therefore, the Python maintainers reserve the right to modify the marshal format
in backward incompatible ways should the need arise.
@@ -34,7 +34,7 @@ supports a substantially wider range of objects than marshal.
.. warning::
- The :mod:`marshal` module is not intended to be secure against erroneous or
+ The :mod:`!marshal` module is not intended to be secure against erroneous or
maliciously constructed data. Never unmarshal data received from an
untrusted or unauthenticated source.
diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index 8dad20bc83b..c14682f7fe5 100644
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -816,7 +816,7 @@ Constants
.. impl-detail::
- The :mod:`math` module consists mostly of thin wrappers around the platform C
+ The :mod:`!math` module consists mostly of thin wrappers around the platform C
math library functions. Behavior in exceptional cases follows Annex F of
the C99 standard where appropriate. The current implementation will raise
:exc:`ValueError` for invalid operations like ``sqrt(-1.0)`` or ``log(0.0)``
diff --git a/Doc/library/mimetypes.rst b/Doc/library/mimetypes.rst
index 13511b16a0e..f489b60af3c 100644
--- a/Doc/library/mimetypes.rst
+++ b/Doc/library/mimetypes.rst
@@ -12,7 +12,7 @@
--------------
-The :mod:`mimetypes` module converts between a filename or URL and the MIME type
+The :mod:`!mimetypes` module converts between a filename or URL and the MIME type
associated with the filename extension. Conversions are provided from filename
to MIME type and from MIME type to filename extension; encodings are not
supported for the latter conversion.
@@ -196,7 +196,7 @@ MimeTypes objects
The :class:`MimeTypes` class may be useful for applications which may want more
than one MIME-type database; it provides an interface similar to the one of the
-:mod:`mimetypes` module.
+:mod:`!mimetypes` module.
.. class:: MimeTypes(filenames=(), strict=True)
diff --git a/Doc/library/msvcrt.rst b/Doc/library/msvcrt.rst
index a2c5e375d2c..79069c136c2 100644
--- a/Doc/library/msvcrt.rst
+++ b/Doc/library/msvcrt.rst
@@ -2,7 +2,6 @@
===========================================================
.. module:: msvcrt
- :platform: Windows
:synopsis: Miscellaneous useful routines from the MS VC++ runtime.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index 88813c6f1a4..d581b73cf0b 100644
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -13,16 +13,16 @@
Introduction
------------
-:mod:`multiprocessing` is a package that supports spawning processes using an
-API similar to the :mod:`threading` module. The :mod:`multiprocessing` package
+:mod:`!multiprocessing` is a package that supports spawning processes using an
+API similar to the :mod:`threading` module. The :mod:`!multiprocessing` package
offers both local and remote concurrency, effectively side-stepping the
:term:`Global Interpreter Lock <global interpreter lock>` by using
subprocesses instead of threads. Due
-to this, the :mod:`multiprocessing` module allows the programmer to fully
+to this, the :mod:`!multiprocessing` module allows the programmer to fully
leverage multiple processors on a given machine. It runs on both POSIX and
Windows.
-The :mod:`multiprocessing` module also introduces the
+The :mod:`!multiprocessing` module also introduces the
:class:`~multiprocessing.pool.Pool` object which offers a convenient means of
parallelizing the execution of a function across multiple input values,
distributing the input data across processes (data parallelism). The following
@@ -43,7 +43,7 @@ will print to standard output ::
[1, 4, 9]
-The :mod:`multiprocessing` module also introduces APIs which do not have
+The :mod:`!multiprocessing` module also introduces APIs which do not have
analogs in the :mod:`threading` module, like the ability to :meth:`terminate
<Process.terminate>`, :meth:`interrupt <Process.interrupt>` or :meth:`kill
<Process.kill>` a running process.
@@ -61,7 +61,7 @@ analogs in the :mod:`threading` module, like the ability to :meth:`terminate
The :class:`Process` class
^^^^^^^^^^^^^^^^^^^^^^^^^^
-In :mod:`multiprocessing`, processes are spawned by creating a :class:`Process`
+In :mod:`!multiprocessing`, processes are spawned by creating a :class:`Process`
object and then calling its :meth:`~Process.start` method. :class:`Process`
follows the API of :class:`threading.Thread`. A trivial example of a
multiprocess program is ::
@@ -111,7 +111,7 @@ could lead to an :exc:`AttributeError` in the child process trying to locate the
Contexts and start methods
^^^^^^^^^^^^^^^^^^^^^^^^^^
-Depending on the platform, :mod:`multiprocessing` supports three ways
+Depending on the platform, :mod:`!multiprocessing` supports three ways
to start a process. These *start methods* are
.. _multiprocessing-start-method-spawn:
@@ -240,7 +240,7 @@ processes for a different context. In particular, locks created using
the *fork* context cannot be passed to processes started using the
*spawn* or *forkserver* start methods.
-Libraries using :mod:`multiprocessing` or
+Libraries using :mod:`!multiprocessing` or
:class:`~concurrent.futures.ProcessPoolExecutor` should be designed to allow
their users to provide their own multiprocessing context. Using a specific
context of your own within a library can lead to incompatibilities with the
@@ -258,7 +258,7 @@ requires a specific start method.
Exchanging objects between processes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-:mod:`multiprocessing` supports two types of communication channel between
+:mod:`!multiprocessing` supports two types of communication channel between
processes:
**Queues**
@@ -279,7 +279,7 @@ processes:
p.join()
Queues are thread and process safe.
- Any object put into a :mod:`~multiprocessing` queue will be serialized.
+ Any object put into a :mod:`!multiprocessing` queue will be serialized.
**Pipes**
@@ -313,7 +313,7 @@ processes:
Synchronization between processes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-:mod:`multiprocessing` contains equivalents of all the synchronization
+:mod:`!multiprocessing` contains equivalents of all the synchronization
primitives from :mod:`threading`. For instance one can use a lock to ensure
that only one process prints to standard output at a time::
@@ -344,7 +344,7 @@ avoid using shared state as far as possible. This is particularly true when
using multiple processes.
However, if you really do need to use some shared data then
-:mod:`multiprocessing` provides a couple of ways of doing so.
+:mod:`!multiprocessing` provides a couple of ways of doing so.
**Shared memory**
@@ -518,7 +518,7 @@ process which created it.
Reference
---------
-The :mod:`multiprocessing` package mostly replicates the API of the
+The :mod:`!multiprocessing` package mostly replicates the API of the
:mod:`threading` module.
.. _global-start-method:
@@ -704,7 +704,7 @@ or creating these objects.
The process's authentication key (a byte string).
- When :mod:`multiprocessing` is initialized the main process is assigned a
+ When :mod:`!multiprocessing` is initialized the main process is assigned a
random string using :func:`os.urandom`.
When a :class:`Process` object is created, it will inherit the
@@ -805,7 +805,7 @@ or creating these objects.
.. exception:: ProcessError
- The base class of all :mod:`multiprocessing` exceptions.
+ The base class of all :mod:`!multiprocessing` exceptions.
.. exception:: BufferTooShort
@@ -845,7 +845,7 @@ If you use :class:`JoinableQueue` then you **must** call
semaphore used to count the number of unfinished tasks may eventually overflow,
raising an exception.
-One difference from other Python queue implementations, is that :mod:`multiprocessing`
+One difference from other Python queue implementations, is that :mod:`!multiprocessing`
queues serializes all objects that are put into them using :mod:`pickle`.
The object returned by the get method is a re-created object that does not share
memory with the original object.
@@ -855,9 +855,9 @@ Note that one can also create a shared queue by using a manager object -- see
.. note::
- :mod:`multiprocessing` uses the usual :exc:`queue.Empty` and
+ :mod:`!multiprocessing` uses the usual :exc:`queue.Empty` and
:exc:`queue.Full` exceptions to signal a timeout. They are not available in
- the :mod:`multiprocessing` namespace so you need to import them from
+ the :mod:`!multiprocessing` namespace so you need to import them from
:mod:`queue`.
.. note::
@@ -1152,7 +1152,7 @@ Miscellaneous
.. function:: freeze_support()
- Add support for when a program which uses :mod:`multiprocessing` has been
+ Add support for when a program which uses :mod:`!multiprocessing` has been
frozen to produce an executable. (Has been tested with **py2exe**,
**PyInstaller** and **cx_Freeze**.)
@@ -1188,7 +1188,7 @@ Miscellaneous
.. function:: get_context(method=None)
Return a context object which has the same attributes as the
- :mod:`multiprocessing` module.
+ :mod:`!multiprocessing` module.
If *method* is ``None`` then the default context is returned. Note that if
the global start method has not been set, this will set it to the system default
@@ -1222,7 +1222,7 @@ Miscellaneous
Set the path of the Python interpreter to use when starting a child process.
(By default :data:`sys.executable` is used). Embedders will probably need to
- do some thing like ::
+ do something like ::
set_executable(os.path.join(sys.exec_prefix, 'pythonw.exe'))
@@ -1269,7 +1269,7 @@ Miscellaneous
.. note::
- :mod:`multiprocessing` contains no analogues of
+ :mod:`!multiprocessing` contains no analogues of
:func:`threading.active_count`, :func:`threading.enumerate`,
:func:`threading.settrace`, :func:`threading.setprofile`,
:class:`threading.Timer`, or :class:`threading.local`.
@@ -1463,7 +1463,7 @@ object -- see :ref:`multiprocessing-managers`.
A condition variable: an alias for :class:`threading.Condition`.
If *lock* is specified then it should be a :class:`Lock` or :class:`RLock`
- object from :mod:`multiprocessing`.
+ object from :mod:`!multiprocessing`.
Instantiating this class may set the global start method. See
:ref:`global-start-method` for more details.
@@ -1715,13 +1715,13 @@ inherited by child processes.
attributes which allow one to use it to store and retrieve strings.
-The :mod:`multiprocessing.sharedctypes` module
-""""""""""""""""""""""""""""""""""""""""""""""
+The :mod:`!multiprocessing.sharedctypes` module
+"""""""""""""""""""""""""""""""""""""""""""""""
.. module:: multiprocessing.sharedctypes
:synopsis: Allocate ctypes objects from shared memory.
-The :mod:`multiprocessing.sharedctypes` module provides functions for allocating
+The :mod:`!multiprocessing.sharedctypes` module provides functions for allocating
:mod:`ctypes` objects from shared memory which can be inherited by child
processes.
@@ -2321,7 +2321,7 @@ demonstrates a level of control over the synchronization.
.. note::
- The proxy types in :mod:`multiprocessing` do nothing to support comparisons
+ The proxy types in :mod:`!multiprocessing` do nothing to support comparisons
by value. So, for instance, we have:
.. doctest::
@@ -2463,7 +2463,7 @@ with the :class:`Pool` class.
duration of the Pool's work queue. A frequent pattern found in other
systems (such as Apache, mod_wsgi, etc) to free resources held by
workers is to allow a worker within a pool to complete only a set
- amount of work before being exiting, being cleaned up and a new
+ amount of work before exiting, being cleaned up and a new
process spawned to replace the old one. The *maxtasksperchild*
argument to the :class:`Pool` exposes this ability to the end user.
@@ -2648,7 +2648,7 @@ Usually message passing between processes is done using queues or by using
:class:`~Connection` objects returned by
:func:`~multiprocessing.Pipe`.
-However, the :mod:`multiprocessing.connection` module allows some extra
+However, the :mod:`!multiprocessing.connection` module allows some extra
flexibility. It basically gives a high level message oriented API for dealing
with sockets or Windows named pipes. It also has support for *digest
authentication* using the :mod:`hmac` module, and for polling
@@ -2917,7 +2917,7 @@ handler type) for messages from different processes to get mixed up.
.. currentmodule:: multiprocessing
.. function:: get_logger()
- Returns the logger used by :mod:`multiprocessing`. If necessary, a new one
+ Returns the logger used by :mod:`!multiprocessing`. If necessary, a new one
will be created.
When first created the logger has level :const:`logging.NOTSET` and no
@@ -2955,18 +2955,18 @@ Below is an example session with logging turned on::
For a full table of logging levels, see the :mod:`logging` module.
-The :mod:`multiprocessing.dummy` module
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The :mod:`!multiprocessing.dummy` module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. module:: multiprocessing.dummy
:synopsis: Dumb wrapper around threading.
-:mod:`multiprocessing.dummy` replicates the API of :mod:`multiprocessing` but is
+:mod:`!multiprocessing.dummy` replicates the API of :mod:`!multiprocessing` but is
no more than a wrapper around the :mod:`threading` module.
.. currentmodule:: multiprocessing.pool
-In particular, the ``Pool`` function provided by :mod:`multiprocessing.dummy`
+In particular, the ``Pool`` function provided by :mod:`!multiprocessing.dummy`
returns an instance of :class:`ThreadPool`, which is a subclass of
:class:`Pool` that supports all the same method calls but uses a pool of
worker threads rather than worker processes.
@@ -3011,7 +3011,7 @@ Programming guidelines
----------------------
There are certain guidelines and idioms which should be adhered to when using
-:mod:`multiprocessing`.
+:mod:`!multiprocessing`.
All start methods
@@ -3052,7 +3052,7 @@ Joining zombie processes
Better to inherit than pickle/unpickle
When using the *spawn* or *forkserver* start methods many types
- from :mod:`multiprocessing` need to be picklable so that child
+ from :mod:`!multiprocessing` need to be picklable so that child
processes can use them. However, one should generally avoid
sending shared objects to other processes using pipes or queues.
Instead you should arrange the program so that a process which
@@ -3142,7 +3142,7 @@ Explicitly pass resources to child processes
Beware of replacing :data:`sys.stdin` with a "file like object"
- :mod:`multiprocessing` originally unconditionally called::
+ :mod:`!multiprocessing` originally unconditionally called::
os.close(sys.stdin.fileno())
diff --git a/Doc/library/operator.rst b/Doc/library/operator.rst
index e8e71068dd9..c715e977cca 100644
--- a/Doc/library/operator.rst
+++ b/Doc/library/operator.rst
@@ -15,7 +15,7 @@
--------------
-The :mod:`operator` module exports a set of efficient functions corresponding to
+The :mod:`!operator` module exports a set of efficient functions corresponding to
the intrinsic operators of Python. For example, ``operator.add(x, y)`` is
equivalent to the expression ``x+y``. Many function names are those used for
special methods, without the double underscores. For backward compatibility,
@@ -275,7 +275,7 @@ The following operation works with callables:
.. versionadded:: 3.11
-The :mod:`operator` module also defines tools for generalized attribute and item
+The :mod:`!operator` module also defines tools for generalized attribute and item
lookups. These are useful for making fast field extractors as arguments for
:func:`map`, :func:`sorted`, :meth:`itertools.groupby`, or other functions that
expect a function argument.
@@ -390,7 +390,7 @@ Mapping Operators to Functions
------------------------------
This table shows how abstract operations correspond to operator symbols in the
-Python syntax and the functions in the :mod:`operator` module.
+Python syntax and the functions in the :mod:`!operator` module.
+-----------------------+-------------------------+---------------------------------------+
| Operation | Syntax | Function |
diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst
index ff327cf9162..51827e1f8da 100644
--- a/Doc/library/optparse.rst
+++ b/Doc/library/optparse.rst
@@ -20,7 +20,7 @@ The standard library includes three argument parsing libraries:
* :mod:`getopt`: a module that closely mirrors the procedural C ``getopt`` API.
Included in the standard library since before the initial Python 1.0 release.
-* :mod:`optparse`: a declarative replacement for ``getopt`` that
+* :mod:`!optparse`: a declarative replacement for ``getopt`` that
provides equivalent functionality without requiring each application
to implement its own procedural option parsing logic. Included
in the standard library since the Python 2.3 release.
@@ -37,10 +37,10 @@ the highest level of baseline functionality with the least application level cod
However, it also serves a niche use case as a tool for prototyping and testing
command line argument handling in ``getopt``-based C applications.
-:mod:`optparse` should be considered as an alternative to :mod:`argparse` in the
+:mod:`!optparse` should be considered as an alternative to :mod:`argparse` in the
following cases:
-* an application is already using :mod:`optparse` and doesn't want to risk the
+* an application is already using :mod:`!optparse` and doesn't want to risk the
subtle behavioural changes that may arise when migrating to :mod:`argparse`
* the application requires additional control over the way options and
positional parameters are interleaved on the command line (including
@@ -55,7 +55,7 @@ following cases:
behavior which ``argparse`` does not support, but which can be implemented
in terms of the lower level interface offered by ``optparse``
-These considerations also mean that :mod:`optparse` is likely to provide a
+These considerations also mean that :mod:`!optparse` is likely to provide a
better foundation for library authors writing third party command line
argument processing libraries.
@@ -126,15 +126,15 @@ application use case.
Introduction
------------
-:mod:`optparse` is a more convenient, flexible, and powerful library for parsing
+:mod:`!optparse` is a more convenient, flexible, and powerful library for parsing
command-line options than the minimalist :mod:`getopt` module.
-:mod:`optparse` uses a more declarative style of command-line parsing:
+:mod:`!optparse` uses a more declarative style of command-line parsing:
you create an instance of :class:`OptionParser`,
populate it with options, and parse the command line.
-:mod:`optparse` allows users to specify options in the conventional
+:mod:`!optparse` allows users to specify options in the conventional
GNU/POSIX syntax, and additionally generates usage and help messages for you.
-Here's an example of using :mod:`optparse` in a simple script::
+Here's an example of using :mod:`!optparse` in a simple script::
from optparse import OptionParser
...
@@ -152,11 +152,11 @@ on the command-line, for example::
<yourscript> --file=outfile -q
-As it parses the command line, :mod:`optparse` sets attributes of the
+As it parses the command line, :mod:`!optparse` sets attributes of the
``options`` object returned by :meth:`~OptionParser.parse_args` based on user-supplied
command-line values. When :meth:`~OptionParser.parse_args` returns from parsing this command
line, ``options.filename`` will be ``"outfile"`` and ``options.verbose`` will be
-``False``. :mod:`optparse` supports both long and short options, allows short
+``False``. :mod:`!optparse` supports both long and short options, allows short
options to be merged together, and allows options to be associated with their
arguments in a variety of ways. Thus, the following command lines are all
equivalent to the above example::
@@ -171,7 +171,7 @@ Additionally, users can run one of the following ::
<yourscript> -h
<yourscript> --help
-and :mod:`optparse` will print out a brief summary of your script's options:
+and :mod:`!optparse` will print out a brief summary of your script's options:
.. code-block:: text
@@ -191,7 +191,7 @@ where the value of *yourscript* is determined at runtime (normally from
Background
----------
-:mod:`optparse` was explicitly designed to encourage the creation of programs
+:mod:`!optparse` was explicitly designed to encourage the creation of programs
with straightforward command-line interfaces that follow the conventions
established by the :c:func:`!getopt` family of functions available to C developers.
To that end, it supports only the most common command-line syntax and semantics
@@ -223,7 +223,7 @@ option
options to be merged into a single argument, e.g. ``-x -F`` is equivalent
to ``-xF``. The GNU project introduced ``--`` followed by a series of
hyphen-separated words, e.g. ``--file`` or ``--dry-run``. These are the
- only two option syntaxes provided by :mod:`optparse`.
+ only two option syntaxes provided by :mod:`!optparse`.
Some other option syntaxes that the world has seen include:
@@ -240,7 +240,7 @@ option
* a slash followed by a letter, or a few letters, or a word, e.g. ``/f``,
``/file``
- These option syntaxes are not supported by :mod:`optparse`, and they never
+ These option syntaxes are not supported by :mod:`!optparse`, and they never
will be. This is deliberate: the first three are non-standard on any
environment, and the last only makes sense if you're exclusively targeting
Windows or certain legacy platforms (e.g. VMS, MS-DOS).
@@ -248,7 +248,7 @@ option
option argument
an argument that follows an option, is closely associated with that option,
and is consumed from the argument list when that option is. With
- :mod:`optparse`, option arguments may either be in a separate argument from
+ :mod:`!optparse`, option arguments may either be in a separate argument from
their option:
.. code-block:: text
@@ -268,7 +268,7 @@ option argument
will take an argument if they see it, and won't if they don't. This is
somewhat controversial, because it makes parsing ambiguous: if ``-a`` takes
an optional argument and ``-b`` is another option entirely, how do we
- interpret ``-ab``? Because of this ambiguity, :mod:`optparse` does not
+ interpret ``-ab``? Because of this ambiguity, :mod:`!optparse` does not
support this feature.
positional argument
@@ -278,7 +278,7 @@ positional argument
required option
an option that must be supplied on the command-line; note that the phrase
- "required option" is self-contradictory in English. :mod:`optparse` doesn't
+ "required option" is self-contradictory in English. :mod:`!optparse` doesn't
prevent you from implementing required options, but doesn't give you much
help at it either.
@@ -357,9 +357,9 @@ too many options can overwhelm users and make your code much harder to maintain.
Tutorial
--------
-While :mod:`optparse` is quite flexible and powerful, it's also straightforward
+While :mod:`!optparse` is quite flexible and powerful, it's also straightforward
to use in most cases. This section covers the code patterns that are common to
-any :mod:`optparse`\ -based program.
+any :mod:`!optparse`\ -based program.
First, you need to import the OptionParser class; then, early in the main
program, create an OptionParser instance::
@@ -374,7 +374,7 @@ Then you can start defining options. The basic syntax is::
attr=value, ...)
Each option has one or more option strings, such as ``-f`` or ``--file``,
-and several option attributes that tell :mod:`optparse` what to expect and what
+and several option attributes that tell :mod:`!optparse` what to expect and what
to do when it encounters that option on the command line.
Typically, each option will have one short option string and one long option
@@ -389,10 +389,10 @@ string overall.
The option strings passed to :meth:`OptionParser.add_option` are effectively
labels for the
option defined by that call. For brevity, we will frequently refer to
-*encountering an option* on the command line; in reality, :mod:`optparse`
+*encountering an option* on the command line; in reality, :mod:`!optparse`
encounters *option strings* and looks up options from them.
-Once all of your options are defined, instruct :mod:`optparse` to parse your
+Once all of your options are defined, instruct :mod:`!optparse` to parse your
program's command line::
(options, args) = parser.parse_args()
@@ -420,14 +420,14 @@ most fundamental.
Understanding option actions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Actions tell :mod:`optparse` what to do when it encounters an option on the
-command line. There is a fixed set of actions hard-coded into :mod:`optparse`;
+Actions tell :mod:`!optparse` what to do when it encounters an option on the
+command line. There is a fixed set of actions hard-coded into :mod:`!optparse`;
adding new actions is an advanced topic covered in section
-:ref:`optparse-extending-optparse`. Most actions tell :mod:`optparse` to store
+:ref:`optparse-extending-optparse`. Most actions tell :mod:`!optparse` to store
a value in some variable---for example, take a string from the command line and
store it in an attribute of ``options``.
-If you don't specify an option action, :mod:`optparse` defaults to ``store``.
+If you don't specify an option action, :mod:`!optparse` defaults to ``store``.
.. _optparse-store-action:
@@ -435,7 +435,7 @@ If you don't specify an option action, :mod:`optparse` defaults to ``store``.
The store action
^^^^^^^^^^^^^^^^
-The most common option action is ``store``, which tells :mod:`optparse` to take
+The most common option action is ``store``, which tells :mod:`!optparse` to take
the next argument (or the remainder of the current argument), ensure that it is
of the correct type, and store it to your chosen destination.
@@ -444,16 +444,16 @@ For example::
parser.add_option("-f", "--file",
action="store", type="string", dest="filename")
-Now let's make up a fake command line and ask :mod:`optparse` to parse it::
+Now let's make up a fake command line and ask :mod:`!optparse` to parse it::
args = ["-f", "foo.txt"]
(options, args) = parser.parse_args(args)
-When :mod:`optparse` sees the option string ``-f``, it consumes the next
+When :mod:`!optparse` sees the option string ``-f``, it consumes the next
argument, ``foo.txt``, and stores it in ``options.filename``. So, after this
call to :meth:`~OptionParser.parse_args`, ``options.filename`` is ``"foo.txt"``.
-Some other option types supported by :mod:`optparse` are ``int`` and ``float``.
+Some other option types supported by :mod:`!optparse` are ``int`` and ``float``.
Here's an option that expects an integer argument::
parser.add_option("-n", type="int", dest="num")
@@ -470,19 +470,19 @@ right up against the option: since ``-n42`` (one argument) is equivalent to
will print ``42``.
-If you don't specify a type, :mod:`optparse` assumes ``string``. Combined with
+If you don't specify a type, :mod:`!optparse` assumes ``string``. Combined with
the fact that the default action is ``store``, that means our first example can
be a lot shorter::
parser.add_option("-f", "--file", dest="filename")
-If you don't supply a destination, :mod:`optparse` figures out a sensible
+If you don't supply a destination, :mod:`!optparse` figures out a sensible
default from the option strings: if the first long option string is
``--foo-bar``, then the default destination is ``foo_bar``. If there are no
-long option strings, :mod:`optparse` looks at the first short option string: the
+long option strings, :mod:`!optparse` looks at the first short option string: the
default destination for ``-f`` is ``f``.
-:mod:`optparse` also includes the built-in ``complex`` type. Adding
+:mod:`!optparse` also includes the built-in ``complex`` type. Adding
types is covered in section :ref:`optparse-extending-optparse`.
@@ -492,7 +492,7 @@ Handling boolean (flag) options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Flag options---set a variable to true or false when a particular option is
-seen---are quite common. :mod:`optparse` supports them with two separate actions,
+seen---are quite common. :mod:`!optparse` supports them with two separate actions,
``store_true`` and ``store_false``. For example, you might have a ``verbose``
flag that is turned on with ``-v`` and off with ``-q``::
@@ -503,7 +503,7 @@ Here we have two different options with the same destination, which is perfectly
OK. (It just means you have to be a bit careful when setting default
values---see below.)
-When :mod:`optparse` encounters ``-v`` on the command line, it sets
+When :mod:`!optparse` encounters ``-v`` on the command line, it sets
``options.verbose`` to ``True``; when it encounters ``-q``,
``options.verbose`` is set to ``False``.
@@ -513,7 +513,7 @@ When :mod:`optparse` encounters ``-v`` on the command line, it sets
Other actions
^^^^^^^^^^^^^
-Some other actions supported by :mod:`optparse` are:
+Some other actions supported by :mod:`!optparse` are:
``"store_const"``
store a constant value, pre-set via :attr:`Option.const`
@@ -539,11 +539,11 @@ Default values
All of the above examples involve setting some variable (the "destination") when
certain command-line options are seen. What happens if those options are never
seen? Since we didn't supply any defaults, they are all set to ``None``. This
-is usually fine, but sometimes you want more control. :mod:`optparse` lets you
+is usually fine, but sometimes you want more control. :mod:`!optparse` lets you
supply a default value for each destination, which is assigned before the
command line is parsed.
-First, consider the verbose/quiet example. If we want :mod:`optparse` to set
+First, consider the verbose/quiet example. If we want :mod:`!optparse` to set
``verbose`` to ``True`` unless ``-q`` is seen, then we can do this::
parser.add_option("-v", action="store_true", dest="verbose", default=True)
@@ -582,7 +582,7 @@ values, not both.
Generating help
^^^^^^^^^^^^^^^
-:mod:`optparse`'s ability to generate help and usage text automatically is
+:mod:`!optparse`'s ability to generate help and usage text automatically is
useful for creating user-friendly command-line interfaces. All you have to do
is supply a :attr:`~Option.help` value for each option, and optionally a short
usage message for your whole program. Here's an OptionParser populated with
@@ -603,7 +603,7 @@ user-friendly (documented) options::
help="interaction mode: novice, intermediate, "
"or expert [default: %default]")
-If :mod:`optparse` encounters either ``-h`` or ``--help`` on the
+If :mod:`!optparse` encounters either ``-h`` or ``--help`` on the
command-line, or if you just call :meth:`parser.print_help`, it prints the
following to standard output:
@@ -620,26 +620,26 @@ following to standard output:
-m MODE, --mode=MODE interaction mode: novice, intermediate, or
expert [default: intermediate]
-(If the help output is triggered by a help option, :mod:`optparse` exits after
+(If the help output is triggered by a help option, :mod:`!optparse` exits after
printing the help text.)
-There's a lot going on here to help :mod:`optparse` generate the best possible
+There's a lot going on here to help :mod:`!optparse` generate the best possible
help message:
* the script defines its own usage message::
usage = "usage: %prog [options] arg1 arg2"
- :mod:`optparse` expands ``%prog`` in the usage string to the name of the
+ :mod:`!optparse` expands ``%prog`` in the usage string to the name of the
current program, i.e. ``os.path.basename(sys.argv[0])``. The expanded string
is then printed before the detailed option help.
- If you don't supply a usage string, :mod:`optparse` uses a bland but sensible
+ If you don't supply a usage string, :mod:`!optparse` uses a bland but sensible
default: ``"Usage: %prog [options]"``, which is fine if your script doesn't
take any positional arguments.
* every option defines a help string, and doesn't worry about
- line-wrapping---\ :mod:`optparse` takes care of wrapping lines and making
+ line-wrapping---\ :mod:`!optparse` takes care of wrapping lines and making
the help output look good.
* options that take a value indicate this fact in their automatically generated
@@ -649,7 +649,7 @@ help message:
Here, "MODE" is called the meta-variable: it stands for the argument that the
user is expected to supply to ``-m``/``--mode``. By default,
- :mod:`optparse` converts the destination variable name to uppercase and uses
+ :mod:`!optparse` converts the destination variable name to uppercase and uses
that for the meta-variable. Sometimes, that's not what you want---for
example, the ``--filename`` option explicitly sets ``metavar="FILE"``,
resulting in this automatically generated option description::
@@ -663,7 +663,7 @@ help message:
way to make your help text a lot clearer and more useful for end users.
* options that have a default value can include ``%default`` in the help
- string---\ :mod:`optparse` will replace it with :func:`str` of the option's
+ string---\ :mod:`!optparse` will replace it with :func:`str` of the option's
default value. If an option has no default value (or the default value is
``None``), ``%default`` expands to ``none``.
@@ -779,14 +779,14 @@ option groups is:
Printing a version string
^^^^^^^^^^^^^^^^^^^^^^^^^
-Similar to the brief usage string, :mod:`optparse` can also print a version
+Similar to the brief usage string, :mod:`!optparse` can also print a version
string for your program. You have to supply the string as the ``version``
argument to OptionParser::
parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
``%prog`` is expanded just like it is in ``usage``. Apart from that,
-``version`` can contain anything you like. When you supply it, :mod:`optparse`
+``version`` can contain anything you like. When you supply it, :mod:`!optparse`
automatically adds a ``--version`` option to your parser. If it encounters
this option on the command line, it expands your ``version`` string (by
replacing ``%prog``), prints it to stdout, and exits.
@@ -815,10 +815,10 @@ The following two methods can be used to print and get the ``version`` string:
.. _optparse-how-optparse-handles-errors:
-How :mod:`optparse` handles errors
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+How :mod:`!optparse` handles errors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-There are two broad classes of errors that :mod:`optparse` has to worry about:
+There are two broad classes of errors that :mod:`!optparse` has to worry about:
programmer errors and user errors. Programmer errors are usually erroneous
calls to :func:`OptionParser.add_option`, e.g. invalid option strings, unknown
option attributes, missing option attributes, etc. These are dealt with in the
@@ -826,7 +826,7 @@ usual way: raise an exception (either :exc:`optparse.OptionError` or
:exc:`TypeError`) and let the program crash.
Handling user errors is much more important, since they are guaranteed to happen
-no matter how stable your code is. :mod:`optparse` can automatically detect
+no matter how stable your code is. :mod:`!optparse` can automatically detect
some user errors, such as bad option arguments (passing ``-n 4x`` where
``-n`` takes an integer argument), missing arguments (``-n`` at the end
of the command line, where ``-n`` takes an argument of any type). Also,
@@ -838,7 +838,7 @@ condition::
if options.a and options.b:
parser.error("options -a and -b are mutually exclusive")
-In either case, :mod:`optparse` handles the error the same way: it prints the
+In either case, :mod:`!optparse` handles the error the same way: it prints the
program's usage message and an error message to standard error and exits with
error status 2.
@@ -861,11 +861,11 @@ Or, where the user fails to pass a value at all:
foo: error: -n option requires an argument
-:mod:`optparse`\ -generated error messages take care always to mention the
+:mod:`!optparse`\ -generated error messages take care always to mention the
option involved in the error; be sure to do the same when calling
:func:`OptionParser.error` from your application code.
-If :mod:`optparse`'s default error-handling behaviour does not suit your needs,
+If :mod:`!optparse`'s default error-handling behaviour does not suit your needs,
you'll need to subclass OptionParser and override its :meth:`~OptionParser.exit`
and/or :meth:`~OptionParser.error` methods.
@@ -875,7 +875,7 @@ and/or :meth:`~OptionParser.error` methods.
Putting it all together
^^^^^^^^^^^^^^^^^^^^^^^
-Here's what :mod:`optparse`\ -based scripts usually look like::
+Here's what :mod:`!optparse`\ -based scripts usually look like::
from optparse import OptionParser
...
@@ -911,7 +911,7 @@ Reference Guide
Creating the parser
^^^^^^^^^^^^^^^^^^^
-The first step in using :mod:`optparse` is to create an OptionParser instance.
+The first step in using :mod:`!optparse` is to create an OptionParser instance.
.. class:: OptionParser(...)
@@ -921,7 +921,7 @@ The first step in using :mod:`optparse` is to create an OptionParser instance.
``usage`` (default: ``"%prog [options]"``)
The usage summary to print when your program is run incorrectly or with a
- help option. When :mod:`optparse` prints the usage string, it expands
+ help option. When :mod:`!optparse` prints the usage string, it expands
``%prog`` to ``os.path.basename(sys.argv[0])`` (or to ``prog`` if you
passed that keyword argument). To suppress a usage message, pass the
special value :const:`optparse.SUPPRESS_USAGE`.
@@ -938,7 +938,7 @@ The first step in using :mod:`optparse` is to create an OptionParser instance.
``version`` (default: ``None``)
A version string to print when the user supplies a version option. If you
- supply a true value for ``version``, :mod:`optparse` automatically adds a
+ supply a true value for ``version``, :mod:`!optparse` automatically adds a
version option with the single option string ``--version``. The
substring ``%prog`` is expanded the same as for ``usage``.
@@ -949,17 +949,17 @@ The first step in using :mod:`optparse` is to create an OptionParser instance.
``description`` (default: ``None``)
A paragraph of text giving a brief overview of your program.
- :mod:`optparse` reformats this paragraph to fit the current terminal width
+ :mod:`!optparse` reformats this paragraph to fit the current terminal width
and prints it when the user requests help (after ``usage``, but before the
list of options).
``formatter`` (default: a new :class:`IndentedHelpFormatter`)
An instance of optparse.HelpFormatter that will be used for printing help
- text. :mod:`optparse` provides two concrete classes for this purpose:
+ text. :mod:`!optparse` provides two concrete classes for this purpose:
IndentedHelpFormatter and TitledHelpFormatter.
``add_help_option`` (default: ``True``)
- If true, :mod:`optparse` will add a help option (with option strings ``-h``
+ If true, :mod:`!optparse` will add a help option (with option strings ``-h``
and ``--help``) to the parser.
``prog``
@@ -997,7 +997,7 @@ the OptionParser constructor, as in::
(:func:`make_option` is a factory function for creating Option instances;
currently it is an alias for the Option constructor. A future version of
-:mod:`optparse` may split Option into several classes, and :func:`make_option`
+:mod:`!optparse` may split Option into several classes, and :func:`make_option`
will pick the right class to instantiate. Do not instantiate Option directly.)
@@ -1027,12 +1027,12 @@ The canonical way to create an :class:`Option` instance is with the
The keyword arguments define attributes of the new Option object. The most
important option attribute is :attr:`~Option.action`, and it largely
determines which other attributes are relevant or required. If you pass
- irrelevant option attributes, or fail to pass required ones, :mod:`optparse`
+ irrelevant option attributes, or fail to pass required ones, :mod:`!optparse`
raises an :exc:`OptionError` exception explaining your mistake.
- An option's *action* determines what :mod:`optparse` does when it encounters
+ An option's *action* determines what :mod:`!optparse` does when it encounters
this option on the command-line. The standard option actions hard-coded into
- :mod:`optparse` are:
+ :mod:`!optparse` are:
``"store"``
store this option's argument (default)
@@ -1066,7 +1066,7 @@ The canonical way to create an :class:`Option` instance is with the
attributes; see :ref:`optparse-standard-option-actions`.)
As you can see, most actions involve storing or updating a value somewhere.
-:mod:`optparse` always creates a special object for this, conventionally called
+:mod:`!optparse` always creates a special object for this, conventionally called
``options``, which is an instance of :class:`optparse.Values`.
.. class:: Values
@@ -1084,7 +1084,7 @@ For example, when you call ::
parser.parse_args()
-one of the first things :mod:`optparse` does is create the ``options`` object::
+one of the first things :mod:`!optparse` does is create the ``options`` object::
options = Values()
@@ -1099,7 +1099,7 @@ and the command-line being parsed includes any of the following::
--file=foo
--file foo
-then :mod:`optparse`, on seeing this option, will do the equivalent of ::
+then :mod:`!optparse`, on seeing this option, will do the equivalent of ::
options.filename = "foo"
@@ -1124,13 +1124,13 @@ Option attributes
The following option attributes may be passed as keyword arguments to
:meth:`OptionParser.add_option`. If you pass an option attribute that is not
relevant to a particular option, or fail to pass a required option attribute,
-:mod:`optparse` raises :exc:`OptionError`.
+:mod:`!optparse` raises :exc:`OptionError`.
.. attribute:: Option.action
(default: ``"store"``)
- Determines :mod:`optparse`'s behaviour when this option is seen on the
+ Determines :mod:`!optparse`'s behaviour when this option is seen on the
command line; the available options are documented :ref:`here
<optparse-standard-option-actions>`.
@@ -1147,8 +1147,8 @@ relevant to a particular option, or fail to pass a required option attribute,
(default: derived from option strings)
If the option's action implies writing or modifying a value somewhere, this
- tells :mod:`optparse` where to write it: :attr:`~Option.dest` names an
- attribute of the ``options`` object that :mod:`optparse` builds as it parses
+ tells :mod:`!optparse` where to write it: :attr:`~Option.dest` names an
+ attribute of the ``options`` object that :mod:`!optparse` builds as it parses
the command line.
.. attribute:: Option.default
@@ -1161,7 +1161,7 @@ relevant to a particular option, or fail to pass a required option attribute,
(default: 1)
How many arguments of type :attr:`~Option.type` should be consumed when this
- option is seen. If > 1, :mod:`optparse` will store a tuple of values to
+ option is seen. If > 1, :mod:`!optparse` will store a tuple of values to
:attr:`~Option.dest`.
.. attribute:: Option.const
@@ -1207,7 +1207,7 @@ Standard option actions
The various option actions all have slightly different requirements and effects.
Most actions have several relevant option attributes which you may specify to
-guide :mod:`optparse`'s behaviour; a few have required attributes, which you
+guide :mod:`!optparse`'s behaviour; a few have required attributes, which you
must specify for any option using that action.
* ``"store"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`,
@@ -1225,9 +1225,9 @@ must specify for any option using that action.
If :attr:`~Option.type` is not supplied, it defaults to ``"string"``.
- If :attr:`~Option.dest` is not supplied, :mod:`optparse` derives a destination
+ If :attr:`~Option.dest` is not supplied, :mod:`!optparse` derives a destination
from the first long option string (e.g., ``--foo-bar`` implies
- ``foo_bar``). If there are no long option strings, :mod:`optparse` derives a
+ ``foo_bar``). If there are no long option strings, :mod:`!optparse` derives a
destination from the first short option string (e.g., ``-f`` implies ``f``).
Example::
@@ -1239,7 +1239,7 @@ must specify for any option using that action.
-f foo.txt -p 1 -3.5 4 -fbar.txt
- :mod:`optparse` will set ::
+ :mod:`!optparse` will set ::
options.f = "foo.txt"
options.point = (1.0, -3.5, 4.0)
@@ -1259,7 +1259,7 @@ must specify for any option using that action.
parser.add_option("--noisy",
action="store_const", const=2, dest="verbose")
- If ``--noisy`` is seen, :mod:`optparse` will set ::
+ If ``--noisy`` is seen, :mod:`!optparse` will set ::
options.verbose = 2
@@ -1282,7 +1282,7 @@ must specify for any option using that action.
The option must be followed by an argument, which is appended to the list in
:attr:`~Option.dest`. If no default value for :attr:`~Option.dest` is
- supplied, an empty list is automatically created when :mod:`optparse` first
+ supplied, an empty list is automatically created when :mod:`!optparse` first
encounters this option on the command-line. If :attr:`~Option.nargs` > 1,
multiple arguments are consumed, and a tuple of length :attr:`~Option.nargs`
is appended to :attr:`~Option.dest`.
@@ -1294,7 +1294,7 @@ must specify for any option using that action.
parser.add_option("-t", "--tracks", action="append", type="int")
- If ``-t3`` is seen on the command-line, :mod:`optparse` does the equivalent
+ If ``-t3`` is seen on the command-line, :mod:`!optparse` does the equivalent
of::
options.tracks = []
@@ -1333,7 +1333,7 @@ must specify for any option using that action.
parser.add_option("-v", action="count", dest="verbosity")
- The first time ``-v`` is seen on the command line, :mod:`optparse` does the
+ The first time ``-v`` is seen on the command line, :mod:`!optparse` does the
equivalent of::
options.verbosity = 0
@@ -1364,7 +1364,7 @@ must specify for any option using that action.
listed in the help message. To omit an option entirely, use the special value
:const:`optparse.SUPPRESS_HELP`.
- :mod:`optparse` automatically adds a :attr:`~Option.help` option to all
+ :mod:`!optparse` automatically adds a :attr:`~Option.help` option to all
OptionParsers, so you do not normally need to create one.
Example::
@@ -1382,7 +1382,7 @@ must specify for any option using that action.
help="Input file to read data from")
parser.add_option("--secret", help=SUPPRESS_HELP)
- If :mod:`optparse` sees either ``-h`` or ``--help`` on the command line,
+ If :mod:`!optparse` sees either ``-h`` or ``--help`` on the command line,
it will print something like the following help message to stdout (assuming
``sys.argv[0]`` is ``"foo.py"``):
@@ -1395,7 +1395,7 @@ must specify for any option using that action.
-v Be moderately verbose
--file=FILENAME Input file to read data from
- After printing the help message, :mod:`optparse` terminates your process with
+ After printing the help message, :mod:`!optparse` terminates your process with
``sys.exit(0)``.
* ``"version"``
@@ -1405,7 +1405,7 @@ must specify for any option using that action.
``print_version()`` method of OptionParser. Generally only relevant if the
``version`` argument is supplied to the OptionParser constructor. As with
:attr:`~Option.help` options, you will rarely create ``version`` options,
- since :mod:`optparse` automatically adds them when needed.
+ since :mod:`!optparse` automatically adds them when needed.
.. _optparse-standard-option-types:
@@ -1413,7 +1413,7 @@ must specify for any option using that action.
Standard option types
^^^^^^^^^^^^^^^^^^^^^
-:mod:`optparse` has five built-in option types: ``"string"``, ``"int"``,
+:mod:`!optparse` has five built-in option types: ``"string"``, ``"int"``,
``"choice"``, ``"float"`` and ``"complex"``. If you need to add new
option types, see section :ref:`optparse-extending-optparse`.
@@ -1432,7 +1432,7 @@ Integer arguments (type ``"int"``) are parsed as follows:
The conversion is done by calling :func:`int` with the appropriate base (2, 8,
-10, or 16). If this fails, so will :mod:`optparse`, although with a more useful
+10, or 16). If this fails, so will :mod:`!optparse`, although with a more useful
error message.
``"float"`` and ``"complex"`` option arguments are converted directly with
@@ -1471,7 +1471,7 @@ The whole point of creating and populating an OptionParser is to call its
``options``
the same object that was passed in as *values*, or the ``optparse.Values``
- instance created by :mod:`optparse`
+ instance created by :mod:`!optparse`
``args``
the leftover positional arguments after all options have been processed
@@ -1499,7 +1499,7 @@ provides several methods to help you out:
.. method:: OptionParser.disable_interspersed_args()
Set parsing to stop on the first non-option. For example, if ``-a`` and
- ``-b`` are both simple options that take no arguments, :mod:`optparse`
+ ``-b`` are both simple options that take no arguments, :mod:`!optparse`
normally accepts this syntax::
prog -a arg1 -b arg2
@@ -1554,7 +1554,7 @@ strings::
(This is particularly true if you've defined your own OptionParser subclass with
some standard options.)
-Every time you add an option, :mod:`optparse` checks for conflicts with existing
+Every time you add an option, :mod:`!optparse` checks for conflicts with existing
options. If it finds any, it invokes the current conflict-handling mechanism.
You can set the conflict-handling mechanism either in the constructor::
@@ -1581,7 +1581,7 @@ intelligently and add conflicting options to it::
parser.add_option("-n", "--dry-run", ..., help="do no harm")
parser.add_option("-n", "--noisy", ..., help="be noisy")
-At this point, :mod:`optparse` detects that a previously added option is already
+At this point, :mod:`!optparse` detects that a previously added option is already
using the ``-n`` option string. Since ``conflict_handler`` is ``"resolve"``,
it resolves the situation by removing ``-n`` from the earlier option's list of
option strings. Now ``--dry-run`` is the only way for the user to activate
@@ -1594,14 +1594,14 @@ that option. If the user asks for help, the help message will reflect that::
It's possible to whittle away the option strings for a previously added option
until there are none left, and the user has no way of invoking that option from
-the command-line. In that case, :mod:`optparse` removes that option completely,
+the command-line. In that case, :mod:`!optparse` removes that option completely,
so it doesn't show up in help text or anywhere else. Carrying on with our
existing OptionParser::
parser.add_option("--dry-run", ..., help="new dry-run option")
At this point, the original ``-n``/``--dry-run`` option is no longer
-accessible, so :mod:`optparse` removes it, leaving this help text::
+accessible, so :mod:`!optparse` removes it, leaving this help text::
Options:
...
@@ -1676,9 +1676,9 @@ OptionParser supports several other public methods:
Option Callbacks
----------------
-When :mod:`optparse`'s built-in actions and types aren't quite enough for your
-needs, you have two choices: extend :mod:`optparse` or define a callback option.
-Extending :mod:`optparse` is more general, but overkill for a lot of simple
+When :mod:`!optparse`'s built-in actions and types aren't quite enough for your
+needs, you have two choices: extend :mod:`!optparse` or define a callback option.
+Extending :mod:`!optparse` is more general, but overkill for a lot of simple
cases. Quite often a simple callback is all you need.
There are two steps to defining a callback option:
@@ -1702,14 +1702,14 @@ only option attribute you must specify is ``callback``, the function to call::
``callback`` is a function (or other callable object), so you must have already
defined ``my_callback()`` when you create this callback option. In this simple
-case, :mod:`optparse` doesn't even know if ``-c`` takes any arguments,
+case, :mod:`!optparse` doesn't even know if ``-c`` takes any arguments,
which usually means that the option takes no arguments---the mere presence of
``-c`` on the command-line is all it needs to know. In some
circumstances, though, you might want your callback to consume an arbitrary
number of command-line arguments. This is where writing callbacks gets tricky;
it's covered later in this section.
-:mod:`optparse` always passes four particular arguments to your callback, and it
+:mod:`!optparse` always passes four particular arguments to your callback, and it
will only pass additional arguments if you specify them via
:attr:`~Option.callback_args` and :attr:`~Option.callback_kwargs`. Thus, the
minimal callback function signature is::
@@ -1723,12 +1723,12 @@ callback option:
:attr:`~Option.type`
has its usual meaning: as with the ``"store"`` or ``"append"`` actions, it
- instructs :mod:`optparse` to consume one argument and convert it to
+ instructs :mod:`!optparse` to consume one argument and convert it to
:attr:`~Option.type`. Rather than storing the converted value(s) anywhere,
- though, :mod:`optparse` passes it to your callback function.
+ though, :mod:`!optparse` passes it to your callback function.
:attr:`~Option.nargs`
- also has its usual meaning: if it is supplied and > 1, :mod:`optparse` will
+ also has its usual meaning: if it is supplied and > 1, :mod:`!optparse` will
consume :attr:`~Option.nargs` arguments, each of which must be convertible to
:attr:`~Option.type`. It then passes a tuple of converted values to your
callback.
@@ -1762,7 +1762,7 @@ where
``"--foobar"``.)
``value``
- is the argument to this option seen on the command-line. :mod:`optparse` will
+ is the argument to this option seen on the command-line. :mod:`!optparse` will
only expect an argument if :attr:`~Option.type` is set; the type of ``value`` will be
the type implied by the option's type. If :attr:`~Option.type` for this option is
``None`` (no argument expected), then ``value`` will be ``None``. If :attr:`~Option.nargs`
@@ -1787,7 +1787,7 @@ where
``parser.values``
the object where option values are by default stored (an instance of
optparse.OptionValues). This lets callbacks use the same mechanism as the
- rest of :mod:`optparse` for storing option values; you don't need to mess
+ rest of :mod:`!optparse` for storing option values; you don't need to mess
around with globals or closures. You can also access or modify the
value(s) of any options already encountered on the command-line.
@@ -1806,7 +1806,7 @@ Raising errors in a callback
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The callback function should raise :exc:`OptionValueError` if there are any
-problems with the option or its argument(s). :mod:`optparse` catches this and
+problems with the option or its argument(s). :mod:`!optparse` catches this and
terminates the program, printing the error message you supply to stderr. Your
message should be clear, concise, accurate, and mention the option at fault.
Otherwise, the user will have a hard time figuring out what they did wrong.
@@ -1906,7 +1906,7 @@ Here's an example that just emulates the standard ``"store"`` action::
action="callback", callback=store_value,
type="int", nargs=3, dest="foo")
-Note that :mod:`optparse` takes care of consuming 3 arguments and converting
+Note that :mod:`!optparse` takes care of consuming 3 arguments and converting
them to integers for you; all you have to do is store them. (Or whatever;
obviously you don't need a callback for this example.)
@@ -1917,9 +1917,9 @@ Callback example 6: variable arguments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Things get hairy when you want an option to take a variable number of arguments.
-For this case, you must write a callback, as :mod:`optparse` doesn't provide any
+For this case, you must write a callback, as :mod:`!optparse` doesn't provide any
built-in capabilities for it. And you have to deal with certain intricacies of
-conventional Unix command-line parsing that :mod:`optparse` normally handles for
+conventional Unix command-line parsing that :mod:`!optparse` normally handles for
you. In particular, callbacks should implement the conventional rules for bare
``--`` and ``-`` arguments:
@@ -1934,7 +1934,7 @@ you. In particular, callbacks should implement the conventional rules for bare
If you want an option that takes a variable number of arguments, there are
several subtle, tricky issues to worry about. The exact implementation you
choose will be based on which trade-offs you're willing to make for your
-application (which is why :mod:`optparse` doesn't support this sort of thing
+application (which is why :mod:`!optparse` doesn't support this sort of thing
directly).
Nevertheless, here's a stab at a callback for an option with variable
@@ -1970,10 +1970,10 @@ arguments::
.. _optparse-extending-optparse:
-Extending :mod:`optparse`
--------------------------
+Extending :mod:`!optparse`
+--------------------------
-Since the two major controlling factors in how :mod:`optparse` interprets
+Since the two major controlling factors in how :mod:`!optparse` interprets
command-line options are the action and type of each option, the most likely
direction of extension is to add new actions and new types.
@@ -1983,9 +1983,9 @@ direction of extension is to add new actions and new types.
Adding new types
^^^^^^^^^^^^^^^^
-To add new types, you need to define your own subclass of :mod:`optparse`'s
+To add new types, you need to define your own subclass of :mod:`!optparse`'s
:class:`Option` class. This class has a couple of attributes that define
-:mod:`optparse`'s types: :attr:`~Option.TYPES` and :attr:`~Option.TYPE_CHECKER`.
+:mod:`!optparse`'s types: :attr:`~Option.TYPES` and :attr:`~Option.TYPE_CHECKER`.
.. attribute:: Option.TYPES
@@ -2015,7 +2015,7 @@ To add new types, you need to define your own subclass of :mod:`optparse`'s
Here's a silly example that demonstrates adding a ``"complex"`` option type to
parse Python-style complex numbers on the command line. (This is even sillier
-than it used to be, because :mod:`optparse` 1.3 added built-in support for
+than it used to be, because :mod:`!optparse` 1.3 added built-in support for
complex numbers, but never mind.)
First, the necessary imports::
@@ -2041,12 +2041,12 @@ Finally, the Option subclass::
TYPE_CHECKER["complex"] = check_complex
(If we didn't make a :func:`copy` of :attr:`Option.TYPE_CHECKER`, we would end
-up modifying the :attr:`~Option.TYPE_CHECKER` attribute of :mod:`optparse`'s
+up modifying the :attr:`~Option.TYPE_CHECKER` attribute of :mod:`!optparse`'s
Option class. This being Python, nothing stops you from doing that except good
manners and common sense.)
That's it! Now you can write a script that uses the new option type just like
-any other :mod:`optparse`\ -based script, except you have to instruct your
+any other :mod:`!optparse`\ -based script, except you have to instruct your
OptionParser to use MyOption instead of Option::
parser = OptionParser(option_class=MyOption)
@@ -2066,10 +2066,10 @@ Adding new actions
^^^^^^^^^^^^^^^^^^
Adding new actions is a bit trickier, because you have to understand that
-:mod:`optparse` has a couple of classifications for actions:
+:mod:`!optparse` has a couple of classifications for actions:
"store" actions
- actions that result in :mod:`optparse` storing a value to an attribute of the
+ actions that result in :mod:`!optparse` storing a value to an attribute of the
current OptionValues instance; these options require a :attr:`~Option.dest`
attribute to be supplied to the Option constructor.
@@ -2101,7 +2101,7 @@ of the following class attributes of Option (all are lists of strings):
.. attribute:: Option.ALWAYS_TYPED_ACTIONS
Actions that always take a type (i.e. whose options always take a value) are
- additionally listed here. The only effect of this is that :mod:`optparse`
+ additionally listed here. The only effect of this is that :mod:`!optparse`
assigns the default type, ``"string"``, to options with no explicit type
whose action is listed in :attr:`ALWAYS_TYPED_ACTIONS`.
@@ -2144,12 +2144,12 @@ Features of note:
somewhere, so it goes in both :attr:`~Option.STORE_ACTIONS` and
:attr:`~Option.TYPED_ACTIONS`.
-* to ensure that :mod:`optparse` assigns the default type of ``"string"`` to
+* to ensure that :mod:`!optparse` assigns the default type of ``"string"`` to
``"extend"`` actions, we put the ``"extend"`` action in
:attr:`~Option.ALWAYS_TYPED_ACTIONS` as well.
* :meth:`MyOption.take_action` implements just this one new action, and passes
- control back to :meth:`Option.take_action` for the standard :mod:`optparse`
+ control back to :meth:`Option.take_action` for the standard :mod:`!optparse`
actions.
* ``values`` is an instance of the optparse_parser.Values class, which provides
diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index 0f805de0fde..48e4734cad9 100644
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -36,7 +36,7 @@ the :mod:`glob` module.)
Since different operating systems have different path name conventions, there
are several versions of this module in the standard library. The
- :mod:`os.path` module is always the path module suitable for the operating
+ :mod:`!os.path` module is always the path module suitable for the operating
system Python is running on, and therefore usable for local paths. However,
you can also import and use the individual modules if you want to manipulate
a path that is *always* in one of the different formats. They all have the
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index b1112656749..721f18e6af7 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -25,7 +25,7 @@ Notes on the availability of these functions:
with the POSIX interface).
* Extensions peculiar to a particular operating system are also available
- through the :mod:`os` module, but using them is of course a threat to
+ through the :mod:`!os` module, but using them is of course a threat to
portability.
* All functions accepting path or file names accept both bytes and string
@@ -34,7 +34,7 @@ Notes on the availability of these functions:
* On VxWorks, os.popen, os.fork, os.execv and os.spawn*p* are not supported.
-* On WebAssembly platforms, Android and iOS, large parts of the :mod:`os` module are
+* On WebAssembly platforms, Android and iOS, large parts of the :mod:`!os` module are
not available or behave differently. APIs related to processes (e.g.
:func:`~os.fork`, :func:`~os.execve`) and resources (e.g. :func:`~os.nice`)
are not available. Others like :func:`~os.getuid` and :func:`~os.getpid` are
@@ -188,7 +188,7 @@ process and user.
of your home directory (on some platforms), and is equivalent to
``getenv("HOME")`` in C.
- This mapping is captured the first time the :mod:`os` module is imported,
+ This mapping is captured the first time the :mod:`!os` module is imported,
typically during Python startup as part of processing :file:`site.py`. Changes
to the environment made after this time are not reflected in :data:`os.environ`,
except for changes made by modifying :data:`os.environ` directly.
@@ -257,7 +257,7 @@ process and user.
.. warning::
This function is not thread-safe. Calling it while the environment is
- being modified in an other thread is an undefined behavior. Reading from
+ being modified in another thread is an undefined behavior. Reading from
:data:`os.environ` or :data:`os.environb`, or calling :func:`os.getenv`
while reloading, may return an empty result.
@@ -1282,7 +1282,7 @@ as internal buffering of data.
For a description of the flag and mode values, see the C run-time documentation;
flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in
- the :mod:`os` module. In particular, on Windows adding
+ the :mod:`!os` module. In particular, on Windows adding
:const:`O_BINARY` is needed to open files in binary mode.
This function can support :ref:`paths relative to directory descriptors
@@ -1297,8 +1297,8 @@ as internal buffering of data.
This function is intended for low-level I/O. For normal usage, use the
built-in function :func:`open`, which returns a :term:`file object` with
- :meth:`~file.read` and :meth:`~file.write` methods (and many more). To
- wrap a file descriptor in a file object, use :func:`fdopen`.
+ :meth:`~io.BufferedIOBase.read` and :meth:`~io.BufferedIOBase.write` methods.
+ To wrap a file descriptor in a file object, use :func:`fdopen`.
.. versionchanged:: 3.3
Added the *dir_fd* parameter.
@@ -1652,7 +1652,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
descriptor as returned by :func:`os.open` or :func:`pipe`. To read a
"file object" returned by the built-in function :func:`open` or by
:func:`popen` or :func:`fdopen`, or :data:`sys.stdin`, use its
- :meth:`~file.read` or :meth:`~file.readline` methods.
+ :meth:`~io.TextIOBase.read` or :meth:`~io.IOBase.readline` methods.
.. versionchanged:: 3.5
If the system call is interrupted and the signal handler does not raise an
@@ -1887,7 +1887,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
descriptor as returned by :func:`os.open` or :func:`pipe`. To write a "file
object" returned by the built-in function :func:`open` or by :func:`popen` or
:func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its
- :meth:`~file.write` method.
+ :meth:`~io.TextIOBase.write` method.
.. versionchanged:: 3.5
If the system call is interrupted and the signal handler does not raise an
@@ -2006,7 +2006,7 @@ features:
.. _path_fd:
* **specifying a file descriptor:**
- Normally the *path* argument provided to functions in the :mod:`os` module
+ Normally the *path* argument provided to functions in the :mod:`!os` module
must be a string specifying a file path. However, some functions now
alternatively accept an open file descriptor for their *path* argument.
The function will then operate on the file referred to by the descriptor.
@@ -3417,7 +3417,7 @@ features:
.. data:: supports_dir_fd
- A :class:`set` object indicating which functions in the :mod:`os`
+ A :class:`set` object indicating which functions in the :mod:`!os`
module accept an open file descriptor for their *dir_fd* parameter.
Different platforms provide different features, and the underlying
functionality Python uses to implement the *dir_fd* parameter is not
@@ -3462,7 +3462,7 @@ features:
.. data:: supports_fd
A :class:`set` object indicating which functions in the
- :mod:`os` module permit specifying their *path* parameter as an open file
+ :mod:`!os` module permit specifying their *path* parameter as an open file
descriptor on the local platform. Different platforms provide different
features, and the underlying functionality Python uses to accept open file
descriptors as *path* arguments is not available on all platforms Python
@@ -3481,7 +3481,7 @@ features:
.. data:: supports_follow_symlinks
- A :class:`set` object indicating which functions in the :mod:`os` module
+ A :class:`set` object indicating which functions in the :mod:`!os` module
accept ``False`` for their *follow_symlinks* parameter on the local platform.
Different platforms provide different features, and the underlying
functionality Python uses to implement *follow_symlinks* is not available
@@ -3989,7 +3989,7 @@ Naturally, they are all only available on Linux.
except it includes any time that the system is suspended.
The file descriptor's behaviour can be modified by specifying a *flags* value.
- Any of the following variables may used, combined using bitwise OR
+ Any of the following variables may be used, combined using bitwise OR
(the ``|`` operator):
- :const:`TFD_NONBLOCK`
@@ -4021,7 +4021,7 @@ Naturally, they are all only available on Linux.
*fd* must be a valid timer file descriptor.
The timer's behaviour can be modified by specifying a *flags* value.
- Any of the following variables may used, combined using bitwise OR
+ Any of the following variables may be used, combined using bitwise OR
(the ``|`` operator):
- :const:`TFD_TIMER_ABSTIME`
@@ -4090,7 +4090,7 @@ Naturally, they are all only available on Linux.
Return a two-item tuple of floats (``next_expiration``, ``interval``).
- ``next_expiration`` denotes the relative time until next the timer next fires,
+ ``next_expiration`` denotes the relative time until the timer next fires,
regardless of if the :const:`TFD_TIMER_ABSTIME` flag is set.
``interval`` denotes the timer's interval.
@@ -4326,7 +4326,7 @@ to be ignored.
The current process is replaced immediately. Open file objects and
descriptors are not flushed, so if there may be data buffered
on these open files, you should flush them using
- :func:`sys.stdout.flush` or :func:`os.fsync` before calling an
+ :func:`~io.IOBase.flush` or :func:`os.fsync` before calling an
:func:`exec\* <execl>` function.
The "l" and "v" variants of the :func:`exec\* <execl>` functions differ in how
diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index b8876c4ca14..9484103e5ce 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -486,6 +486,10 @@ Pure paths provide the following methods and properties:
>>> PurePosixPath('my/library').stem
'library'
+ .. versionchanged:: 3.14
+
+ A single dot ("``.``") is considered a valid suffix.
+
.. method:: PurePath.as_posix()
@@ -1897,7 +1901,7 @@ Below is a table mapping various :mod:`os` functions to their corresponding
:class:`PurePath`/:class:`Path` equivalent.
===================================== ==============================================
-:mod:`os` and :mod:`os.path` :mod:`pathlib`
+:mod:`os` and :mod:`os.path` :mod:`!pathlib`
===================================== ==============================================
:func:`os.path.dirname` :attr:`PurePath.parent`
:func:`os.path.basename` :attr:`PurePath.name`
@@ -1956,7 +1960,7 @@ Protocols
:synopsis: pathlib types for static type checking
-The :mod:`pathlib.types` module provides types for static type checking.
+The :mod:`!pathlib.types` module provides types for static type checking.
.. versionadded:: 3.14
diff --git a/Doc/library/pdb.rst b/Doc/library/pdb.rst
index 0bbdc425352..e7dd2e5524a 100644
--- a/Doc/library/pdb.rst
+++ b/Doc/library/pdb.rst
@@ -1,7 +1,7 @@
.. _debugger:
-:mod:`pdb` --- The Python Debugger
-==================================
+:mod:`!pdb` --- The Python Debugger
+===================================
.. module:: pdb
:synopsis: The Python debugger for interactive interpreters.
@@ -12,7 +12,7 @@
--------------
-The module :mod:`pdb` defines an interactive source code debugger for Python
+The module :mod:`!pdb` defines an interactive source code debugger for Python
programs. It supports setting (conditional) breakpoints and single stepping at
the source line level, inspection of stack frames, source code listing, and
evaluation of arbitrary Python code in the context of any stack frame. It also
@@ -82,7 +82,7 @@ Command-line interface
.. program:: pdb
-You can also invoke :mod:`pdb` from the command line to debug other scripts. For
+You can also invoke :mod:`!pdb` from the command line to debug other scripts. For
example::
python -m pdb [-c command] (-m module | -p pid | pyfile) [args ...]
diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst
index 7b0d979d61a..02b79a9f3a7 100644
--- a/Doc/library/pickle.rst
+++ b/Doc/library/pickle.rst
@@ -19,7 +19,7 @@
--------------
-The :mod:`pickle` module implements binary protocols for serializing and
+The :mod:`!pickle` module implements binary protocols for serializing and
de-serializing a Python object structure. *"Pickling"* is the process
whereby a Python object hierarchy is converted into a byte stream, and
*"unpickling"* is the inverse operation, whereby a byte stream
@@ -50,14 +50,14 @@ Comparison with ``marshal``
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Python has a more primitive serialization module called :mod:`marshal`, but in
-general :mod:`pickle` should always be the preferred way to serialize Python
+general :mod:`!pickle` should always be the preferred way to serialize Python
objects. :mod:`marshal` exists primarily to support Python's :file:`.pyc`
files.
-The :mod:`pickle` module differs from :mod:`marshal` in several significant ways:
+The :mod:`!pickle` module differs from :mod:`marshal` in several significant ways:
* :mod:`marshal` cannot be used to serialize user-defined classes and their
- instances. :mod:`pickle` can save and restore class instances transparently,
+ instances. :mod:`!pickle` can save and restore class instances transparently,
however the class definition must be importable and live in the same module as
when the object was stored.
@@ -65,7 +65,7 @@ The :mod:`pickle` module differs from :mod:`marshal` in several significant ways
across Python versions. Because its primary job in life is to support
:file:`.pyc` files, the Python implementers reserve the right to change the
serialization format in non-backwards compatible ways should the need arise.
- The :mod:`pickle` serialization format is guaranteed to be backwards compatible
+ The :mod:`!pickle` serialization format is guaranteed to be backwards compatible
across Python releases provided a compatible pickle protocol is chosen and
pickling and unpickling code deals with Python 2 to Python 3 type differences
if your data is crossing that unique breaking change language boundary.
@@ -110,17 +110,17 @@ Data stream format
.. index::
single: External Data Representation
-The data format used by :mod:`pickle` is Python-specific. This has the
+The data format used by :mod:`!pickle` is Python-specific. This has the
advantage that there are no restrictions imposed by external standards such as
JSON (which can't represent pointer sharing); however it means that
non-Python programs may not be able to reconstruct pickled Python objects.
-By default, the :mod:`pickle` data format uses a relatively compact binary
+By default, the :mod:`!pickle` data format uses a relatively compact binary
representation. If you need optimal size characteristics, you can efficiently
:doc:`compress <archiving>` pickled data.
The module :mod:`pickletools` contains tools for analyzing data streams
-generated by :mod:`pickle`. :mod:`pickletools` source code has extensive
+generated by :mod:`!pickle`. :mod:`pickletools` source code has extensive
comments about opcodes used by pickle protocols.
There are currently 6 different protocols which can be used for pickling.
@@ -154,9 +154,9 @@ to read the pickle produced.
.. note::
Serialization is a more primitive notion than persistence; although
- :mod:`pickle` reads and writes file objects, it does not handle the issue of
+ :mod:`!pickle` reads and writes file objects, it does not handle the issue of
naming persistent objects, nor the (even more complicated) issue of concurrent
- access to persistent objects. The :mod:`pickle` module can transform a complex
+ access to persistent objects. The :mod:`!pickle` module can transform a complex
object into a byte stream and it can transform the byte stream into an object
with the same internal structure. Perhaps the most obvious thing to do with
these byte streams is to write them onto a file, but it is also conceivable to
@@ -173,7 +173,7 @@ Similarly, to de-serialize a data stream, you call the :func:`loads` function.
However, if you want more control over serialization and de-serialization,
you can create a :class:`Pickler` or an :class:`Unpickler` object, respectively.
-The :mod:`pickle` module provides the following constants:
+The :mod:`!pickle` module provides the following constants:
.. data:: HIGHEST_PROTOCOL
@@ -204,7 +204,7 @@ The :mod:`pickle` module provides the following constants:
The default protocol is 5.
-The :mod:`pickle` module provides the following functions to make the pickling
+The :mod:`!pickle` module provides the following functions to make the pickling
process more convenient:
.. function:: dump(obj, file, protocol=None, *, fix_imports=True, buffer_callback=None)
@@ -262,7 +262,7 @@ process more convenient:
The *buffers* argument was added.
-The :mod:`pickle` module defines three exceptions:
+The :mod:`!pickle` module defines three exceptions:
.. exception:: PickleError
@@ -287,7 +287,7 @@ The :mod:`pickle` module defines three exceptions:
IndexError.
-The :mod:`pickle` module exports three classes, :class:`Pickler`,
+The :mod:`!pickle` module exports three classes, :class:`Pickler`,
:class:`Unpickler` and :class:`PickleBuffer`:
.. class:: Pickler(file, protocol=None, *, fix_imports=True, buffer_callback=None)
@@ -519,7 +519,7 @@ The following types can be pickled:
* classes accessible from the top level of a module;
-* instances of such classes whose the result of calling :meth:`~object.__getstate__`
+* instances of such classes for which the result of calling :meth:`~object.__getstate__`
is picklable (see section :ref:`pickle-inst` for details).
Attempts to pickle unpicklable objects will raise the :exc:`PicklingError`
@@ -588,7 +588,7 @@ methods:
.. method:: object.__getnewargs_ex__()
- In protocols 2 and newer, classes that implements the
+ In protocols 2 and newer, classes that implement the
:meth:`__getnewargs_ex__` method can dictate the values passed to the
:meth:`__new__` method upon unpickling. The method must return a pair
``(args, kwargs)`` where *args* is a tuple of positional arguments
@@ -760,13 +760,13 @@ Persistence of External Objects
single: persistent_id (pickle protocol)
single: persistent_load (pickle protocol)
-For the benefit of object persistence, the :mod:`pickle` module supports the
+For the benefit of object persistence, the :mod:`!pickle` module supports the
notion of a reference to an object outside the pickled data stream. Such
objects are referenced by a persistent ID, which should be either a string of
alphanumeric characters (for protocol 0) [#]_ or just an arbitrary object (for
any newer protocol).
-The resolution of such persistent IDs is not defined by the :mod:`pickle`
+The resolution of such persistent IDs is not defined by the :mod:`!pickle`
module; it will delegate this resolution to the user-defined methods on the
pickler and unpickler, :meth:`~Pickler.persistent_id` and
:meth:`~Unpickler.persistent_load` respectively.
@@ -960,10 +960,10 @@ Out-of-band Buffers
.. versionadded:: 3.8
-In some contexts, the :mod:`pickle` module is used to transfer massive amounts
+In some contexts, the :mod:`!pickle` module is used to transfer massive amounts
of data. Therefore, it can be important to minimize the number of memory
copies, to preserve performance and resource consumption. However, normal
-operation of the :mod:`pickle` module, as it transforms a graph-like structure
+operation of the :mod:`!pickle` module, as it transforms a graph-like structure
of objects into a sequential stream of bytes, intrinsically involves copying
data to and from the pickle stream.
@@ -982,8 +982,8 @@ for any large data.
A :class:`PickleBuffer` object *signals* that the underlying buffer is
eligible for out-of-band data transfer. Those objects remain compatible
-with normal usage of the :mod:`pickle` module. However, consumers can also
-opt-in to tell :mod:`pickle` that they will handle those buffers by
+with normal usage of the :mod:`!pickle` module. However, consumers can also
+opt-in to tell :mod:`!pickle` that they will handle those buffers by
themselves.
Consumer API
@@ -1159,7 +1159,7 @@ Performance
Recent versions of the pickle protocol (from protocol 2 and upwards) feature
efficient binary encodings for several common features and built-in types.
-Also, the :mod:`pickle` module has a transparent optimizer written in C.
+Also, the :mod:`!pickle` module has a transparent optimizer written in C.
.. _pickle-example:
@@ -1202,7 +1202,7 @@ The following example reads the resulting pickled data. ::
Command-line interface
----------------------
-The :mod:`pickle` module can be invoked as a script from the command line,
+The :mod:`!pickle` module can be invoked as a script from the command line,
it will display contents of the pickle files. However, when the pickle file
that you want to examine comes from an untrusted source, ``-m pickletools``
is a safer option because it does not execute pickle bytecode, see
@@ -1230,7 +1230,7 @@ The following option is accepted:
Tools for working with and analyzing pickled data.
Module :mod:`shelve`
- Indexed databases of objects; uses :mod:`pickle`.
+ Indexed databases of objects; uses :mod:`!pickle`.
Module :mod:`copy`
Shallow and deep object copying.
diff --git a/Doc/library/pickletools.rst b/Doc/library/pickletools.rst
index 30fc2962e0b..7a771ea3ab9 100644
--- a/Doc/library/pickletools.rst
+++ b/Doc/library/pickletools.rst
@@ -15,7 +15,7 @@ This module contains various constants relating to the intimate details of the
few useful functions for analyzing pickled data. The contents of this module
are useful for Python core developers who are working on the :mod:`pickle`;
ordinary users of the :mod:`pickle` module probably won't find the
-:mod:`pickletools` module relevant.
+:mod:`!pickletools` module relevant.
.. _pickletools-cli:
diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst
index 256baa53ed5..ff254caa5fb 100644
--- a/Doc/library/platform.rst
+++ b/Doc/library/platform.rst
@@ -375,7 +375,7 @@ Android platform
Command-line usage
------------------
-:mod:`platform` can also be invoked directly using the :option:`-m`
+:mod:`!platform` can also be invoked directly using the :option:`-m`
switch of the interpreter::
python -m platform [--terse] [--nonaliased] [{nonaliased,terse} ...]
diff --git a/Doc/library/poplib.rst b/Doc/library/poplib.rst
index 23f20b00e6d..51ae480338d 100644
--- a/Doc/library/poplib.rst
+++ b/Doc/library/poplib.rst
@@ -30,7 +30,7 @@ mailserver supports IMAP, you would be better off using the
.. include:: ../includes/wasm-notavail.rst
-The :mod:`poplib` module provides two classes:
+The :mod:`!poplib` module provides two classes:
.. class:: POP3(host, port=POP3_PORT[, timeout])
@@ -86,7 +86,7 @@ The :mod:`poplib` module provides two classes:
.. versionchanged:: 3.12
The deprecated *keyfile* and *certfile* parameters have been removed.
-One exception is defined as an attribute of the :mod:`poplib` module:
+One exception is defined as an attribute of the :mod:`!poplib` module:
.. exception:: error_proto
diff --git a/Doc/library/posix.rst b/Doc/library/posix.rst
index 14ab3e91e8a..1f1ca03dfd6 100644
--- a/Doc/library/posix.rst
+++ b/Doc/library/posix.rst
@@ -2,7 +2,6 @@
====================================================
.. module:: posix
- :platform: Unix
:synopsis: The most common POSIX system calls (normally used via module os).
--------------
@@ -17,10 +16,10 @@ interface).
**Do not import this module directly.** Instead, import the module :mod:`os`,
which provides a *portable* version of this interface. On Unix, the :mod:`os`
-module provides a superset of the :mod:`posix` interface. On non-Unix operating
-systems the :mod:`posix` module is not available, but a subset is always
+module provides a superset of the :mod:`!posix` interface. On non-Unix operating
+systems the :mod:`!posix` module is not available, but a subset is always
available through the :mod:`os` interface. Once :mod:`os` is imported, there is
-*no* performance penalty in using it instead of :mod:`posix`. In addition,
+*no* performance penalty in using it instead of :mod:`!posix`. In addition,
:mod:`os` provides some additional functionality, such as automatically calling
:func:`~os.putenv` when an entry in ``os.environ`` is changed.
@@ -67,7 +66,7 @@ Notable Module Contents
-----------------------
In addition to many functions described in the :mod:`os` module documentation,
-:mod:`posix` defines the following data item:
+:mod:`!posix` defines the following data item:
.. data:: environ
@@ -91,4 +90,4 @@ In addition to many functions described in the :mod:`os` module documentation,
which updates the environment on modification. Note also that updating
:data:`os.environ` will render this dictionary obsolete. Use of the
:mod:`os` module version of this is recommended over direct access to the
- :mod:`posix` module.
+ :mod:`!posix` module.
diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst
index f5189245079..be942949d3e 100644
--- a/Doc/library/pprint.rst
+++ b/Doc/library/pprint.rst
@@ -11,7 +11,7 @@
--------------
-The :mod:`pprint` module provides a capability to "pretty-print" arbitrary
+The :mod:`!pprint` module provides a capability to "pretty-print" arbitrary
Python data structures in a form which can be used as input to the interpreter.
If the formatted structures include objects which are not fundamental Python
types, the representation may not be loadable. This may be the case if objects
diff --git a/Doc/library/profile.rst b/Doc/library/profile.rst
index 89433af5d87..57f997792b8 100644
--- a/Doc/library/profile.rst
+++ b/Doc/library/profile.rst
@@ -217,14 +217,14 @@ Invoked as a script, the :mod:`pstats` module is a statistics browser for
reading and examining profile dumps. It has a simple line-oriented interface
(implemented using :mod:`cmd`) and interactive help.
-:mod:`profile` and :mod:`cProfile` Module Reference
-=======================================================
+:mod:`profile` and :mod:`!cProfile` Module Reference
+====================================================
.. module:: cProfile
.. module:: profile
:synopsis: Python source profiler.
-Both the :mod:`profile` and :mod:`cProfile` modules provide the following
+Both the :mod:`profile` and :mod:`!cProfile` modules provide the following
functions:
.. function:: run(command, filename=None, sort=-1)
@@ -278,7 +278,7 @@ functions:
print(s.getvalue())
The :class:`Profile` class can also be used as a context manager (supported
- only in :mod:`cProfile` module. see :ref:`typecontextmanager`)::
+ only in :mod:`!cProfile` module. see :ref:`typecontextmanager`)::
import cProfile
@@ -292,11 +292,11 @@ functions:
.. method:: enable()
- Start collecting profiling data. Only in :mod:`cProfile`.
+ Start collecting profiling data. Only in :mod:`!cProfile`.
.. method:: disable()
- Stop collecting profiling data. Only in :mod:`cProfile`.
+ Stop collecting profiling data. Only in :mod:`!cProfile`.
.. method:: create_stats()
diff --git a/Doc/library/pty.rst b/Doc/library/pty.rst
index 1a44bb13a84..9d6036d92c4 100644
--- a/Doc/library/pty.rst
+++ b/Doc/library/pty.rst
@@ -2,7 +2,6 @@
=========================================
.. module:: pty
- :platform: Unix
:synopsis: Pseudo-Terminal Handling for Unix.
.. moduleauthor:: Steen Lumholt
@@ -12,7 +11,7 @@
--------------
-The :mod:`pty` module defines operations for handling the pseudo-terminal
+The :mod:`!pty` module defines operations for handling the pseudo-terminal
concept: starting another process and being able to write to and read from its
controlling terminal programmatically.
@@ -22,7 +21,7 @@ Pseudo-terminal handling is highly platform dependent. This code is mainly
tested on Linux, FreeBSD, and macOS (it is supposed to work on other POSIX
platforms but it's not been thoroughly tested).
-The :mod:`pty` module defines the following functions:
+The :mod:`!pty` module defines the following functions:
.. function:: fork()
diff --git a/Doc/library/pwd.rst b/Doc/library/pwd.rst
index e1ff3291213..7691fed2c7c 100644
--- a/Doc/library/pwd.rst
+++ b/Doc/library/pwd.rst
@@ -2,7 +2,6 @@
=====================================
.. module:: pwd
- :platform: Unix
:synopsis: The password database (getpwnam() and friends).
--------------
diff --git a/Doc/library/py_compile.rst b/Doc/library/py_compile.rst
index 75aa739d100..1cff16b6c1b 100644
--- a/Doc/library/py_compile.rst
+++ b/Doc/library/py_compile.rst
@@ -13,7 +13,7 @@
--------------
-The :mod:`py_compile` module provides a function to generate a byte-code file
+The :mod:`!py_compile` module provides a function to generate a byte-code file
from a source file, and another function used when the module source file is
invoked as a script.
diff --git a/Doc/library/pyclbr.rst b/Doc/library/pyclbr.rst
index 5efb11d89dd..40f93646af2 100644
--- a/Doc/library/pyclbr.rst
+++ b/Doc/library/pyclbr.rst
@@ -10,7 +10,7 @@
--------------
-The :mod:`pyclbr` module provides limited information about the
+The :mod:`!pyclbr` module provides limited information about the
functions, classes, and methods defined in a Python-coded module. The
information is sufficient to implement a module browser. The
information is extracted from the Python source code rather than by
diff --git a/Doc/library/pyexpat.rst b/Doc/library/pyexpat.rst
index b2dd92f7ba2..c448627e2bd 100644
--- a/Doc/library/pyexpat.rst
+++ b/Doc/library/pyexpat.rst
@@ -24,7 +24,7 @@
.. index:: single: Expat
-The :mod:`xml.parsers.expat` module is a Python interface to the Expat
+The :mod:`!xml.parsers.expat` module is a Python interface to the Expat
non-validating XML parser. The module provides a single extension type,
:class:`xmlparser`, that represents the current state of an XML parser. After
an :class:`xmlparser` object has been created, various attributes of the object
@@ -55,7 +55,7 @@ This module provides one exception and one type object:
The type of the return values from the :func:`ParserCreate` function.
-The :mod:`xml.parsers.expat` module contains two functions:
+The :mod:`!xml.parsers.expat` module contains two functions:
.. function:: ErrorString(errno)
@@ -409,7 +409,7 @@ otherwise stated.
...``). The *doctypeName* is provided exactly as presented. The *systemId* and
*publicId* parameters give the system and public identifiers if specified, or
``None`` if omitted. *has_internal_subset* will be true if the document
- contains and internal document declaration subset. This requires Expat version
+ contains an internal document declaration subset. This requires Expat version
1.2 or newer.
@@ -683,7 +683,7 @@ values: the type, the quantifier, the name, and a tuple of children. Children
are simply additional content model descriptions.
The values of the first two fields are constants defined in the
-:mod:`xml.parsers.expat.model` module. These constants can be collected in two
+:mod:`!xml.parsers.expat.model` module. These constants can be collected in two
groups: the model type group and the quantifier group.
The constants in the model type group are:
@@ -757,7 +757,7 @@ Expat error constants
.. module:: xml.parsers.expat.errors
-The following constants are provided in the :mod:`xml.parsers.expat.errors`
+The following constants are provided in the :mod:`!xml.parsers.expat.errors`
module. These constants are useful in interpreting some of the attributes of
the :exc:`ExpatError` exception objects raised when an error has occurred.
Since for backwards compatibility reasons, the constants' value is the error
@@ -904,7 +904,7 @@ The ``errors`` module has the following attributes:
An operation was requested that requires DTD support to be compiled in, but
Expat was configured without DTD support. This should never be reported by a
- standard build of the :mod:`xml.parsers.expat` module.
+ standard build of the :mod:`!xml.parsers.expat` module.
.. data:: XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING
diff --git a/Doc/library/queue.rst b/Doc/library/queue.rst
index 1b75582f0cf..5ac72ef7604 100644
--- a/Doc/library/queue.rst
+++ b/Doc/library/queue.rst
@@ -8,7 +8,7 @@
--------------
-The :mod:`queue` module implements multi-producer, multi-consumer queues.
+The :mod:`!queue` module implements multi-producer, multi-consumer queues.
It is especially useful in threaded programming when information must be
exchanged safely between multiple threads. The :class:`Queue` class in this
module implements all the required locking semantics.
@@ -30,7 +30,7 @@ In addition, the module implements a "simple"
specific implementation provides additional guarantees
in exchange for the smaller functionality.
-The :mod:`queue` module defines the following classes and exceptions:
+The :mod:`!queue` module defines the following classes and exceptions:
.. class:: Queue(maxsize=0)
diff --git a/Doc/library/random.rst b/Doc/library/random.rst
index fdc14cd04e2..9327e5a23d6 100644
--- a/Doc/library/random.rst
+++ b/Doc/library/random.rst
@@ -37,7 +37,7 @@ Class :class:`Random` can also be subclassed if you want to use a different
basic generator of your own devising: see the documentation on that class for
more details.
-The :mod:`random` module also provides the :class:`SystemRandom` class which
+The :mod:`!random` module also provides the :class:`SystemRandom` class which
uses the system function :func:`os.urandom` to generate random numbers
from sources provided by the operating system.
@@ -410,7 +410,7 @@ Alternative Generator
.. class:: Random([seed])
Class that implements the default pseudo-random number generator used by the
- :mod:`random` module.
+ :mod:`!random` module.
.. versionchanged:: 3.11
Formerly the *seed* could be any hashable object. Now it is limited to:
diff --git a/Doc/library/re.rst b/Doc/library/re.rst
index 75ebbf11c8e..6ee52c6927d 100644
--- a/Doc/library/re.rst
+++ b/Doc/library/re.rst
@@ -49,7 +49,7 @@ fine-tuning parameters.
.. seealso::
The third-party :pypi:`regex` module,
- which has an API compatible with the standard library :mod:`re` module,
+ which has an API compatible with the standard library :mod:`!re` module,
but offers additional functionality and a more thorough Unicode support.
@@ -1407,10 +1407,10 @@ when there is no match, you can test whether there was a match with a simple
result is a single string; if there are multiple arguments, the result is a
tuple with one item per argument. Without arguments, *group1* defaults to zero
(the whole match is returned). If a *groupN* argument is zero, the corresponding
- return value is the entire matching string; if it is in the inclusive range
- [1..99], it is the string matching the corresponding parenthesized group. If a
- group number is negative or larger than the number of groups defined in the
- pattern, an :exc:`IndexError` exception is raised. If a group is contained in a
+ return value is the entire matching string; if it is a positive integer, it is
+ the string matching the corresponding parenthesized group. If a group number is
+ negative or larger than the number of groups defined in the pattern, an
+ :exc:`IndexError` exception is raised. If a group is contained in a
part of the pattern that did not match, the corresponding result is ``None``.
If a group is contained in a part of the pattern that matched multiple times,
the last match is returned. ::
diff --git a/Doc/library/readline.rst b/Doc/library/readline.rst
index 02e0d100791..be36f7b1b6a 100644
--- a/Doc/library/readline.rst
+++ b/Doc/library/readline.rst
@@ -2,14 +2,13 @@
===========================================
.. module:: readline
- :platform: Unix
:synopsis: GNU readline support for Python.
.. sectionauthor:: Skip Montanaro <skip.montanaro@gmail.com>
--------------
-The :mod:`readline` module defines a number of functions to facilitate
+The :mod:`!readline` module defines a number of functions to facilitate
completion and reading/writing of history files from the Python interpreter.
This module can be used directly, or via the :mod:`rlcompleter` module, which
supports completion of Python identifiers at the interactive prompt. Settings
@@ -28,11 +27,13 @@ Readline library in general.
.. include:: ../includes/optional-module.rst
+.. availability:: Unix.
+
.. note::
The underlying Readline library API may be implemented by
the ``editline`` (``libedit``) library instead of GNU readline.
- On macOS the :mod:`readline` module detects which library is being used
+ On macOS the :mod:`!readline` module detects which library is being used
at run time.
The configuration file for ``editline`` is different from that
@@ -255,7 +256,7 @@ The following functions relate to implementing a custom word completion
function. This is typically operated by the Tab key, and can suggest and
automatically complete a word being typed. By default, Readline is set up
to be used by :mod:`rlcompleter` to complete Python identifiers for
-the interactive interpreter. If the :mod:`readline` module is to be used
+the interactive interpreter. If the :mod:`!readline` module is to be used
with a custom completer, a different set of word delimiters should be set.
@@ -324,7 +325,7 @@ with a custom completer, a different set of word delimiters should be set.
Example
-------
-The following example demonstrates how to use the :mod:`readline` module's
+The following example demonstrates how to use the :mod:`!readline` module's
history reading and writing functions to automatically load and save a history
file named :file:`.python_history` from the user's home directory. The code
below would normally be executed automatically during interactive sessions
diff --git a/Doc/library/resource.rst b/Doc/library/resource.rst
index 512f0852dd5..357686da00c 100644
--- a/Doc/library/resource.rst
+++ b/Doc/library/resource.rst
@@ -2,7 +2,6 @@
===============================================
.. module:: resource
- :platform: Unix
:synopsis: An interface to provide resource usage information on the current process.
.. moduleauthor:: Jeremy Hylton <jeremy@alum.mit.edu>
@@ -303,9 +302,9 @@ These functions are used to retrieve resource usage information:
print(getrusage(RUSAGE_SELF))
The fields of the return value each describe how a particular system resource
- has been used, e.g. amount of time spent running is user mode or number of times
+ has been used, e.g. amount of time spent running in user mode or number of times
the process was swapped out of main memory. Some values are dependent on the
- clock tick internal, e.g. the amount of memory the process is using.
+ clock tick interval, e.g. the amount of memory the process is using.
For backward compatibility, the return value is also accessible as a tuple of 16
elements.
diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst
index b07ec6e93f8..2e8081f3bf0 100644
--- a/Doc/library/runpy.rst
+++ b/Doc/library/runpy.rst
@@ -10,7 +10,7 @@
--------------
-The :mod:`runpy` module is used to locate and run Python modules without
+The :mod:`!runpy` module is used to locate and run Python modules without
importing them first. Its main use is to implement the :option:`-m` command
line switch that allows scripts to be located using the Python module
namespace rather than the filesystem.
@@ -20,11 +20,11 @@ current process, and any side effects (such as cached imports of other
modules) will remain in place after the functions have returned.
Furthermore, any functions and classes defined by the executed code are not
-guaranteed to work correctly after a :mod:`runpy` function has returned.
+guaranteed to work correctly after a :mod:`!runpy` function has returned.
If that limitation is not acceptable for a given use case, :mod:`importlib`
is likely to be a more suitable choice than this module.
-The :mod:`runpy` module provides two functions:
+The :mod:`!runpy` module provides two functions:
.. function:: run_module(mod_name, init_globals=None, run_name=None, alter_sys=False)
diff --git a/Doc/library/sched.rst b/Doc/library/sched.rst
index 517dbe8c321..5560478ce15 100644
--- a/Doc/library/sched.rst
+++ b/Doc/library/sched.rst
@@ -12,7 +12,7 @@
--------------
-The :mod:`sched` module defines a class which implements a general purpose event
+The :mod:`!sched` module defines a class which implements a general purpose event
scheduler:
.. class:: scheduler(timefunc=time.monotonic, delayfunc=time.sleep)
diff --git a/Doc/library/secrets.rst b/Doc/library/secrets.rst
index 75dafc54d40..e266849918a 100644
--- a/Doc/library/secrets.rst
+++ b/Doc/library/secrets.rst
@@ -17,11 +17,11 @@
-------------
-The :mod:`secrets` module is used for generating cryptographically strong
+The :mod:`!secrets` module is used for generating cryptographically strong
random numbers suitable for managing data such as passwords, account
authentication, security tokens, and related secrets.
-In particular, :mod:`secrets` should be used in preference to the
+In particular, :mod:`!secrets` should be used in preference to the
default pseudo-random number generator in the :mod:`random` module, which
is designed for modelling and simulation, not security or cryptography.
@@ -33,7 +33,7 @@ is designed for modelling and simulation, not security or cryptography.
Random numbers
--------------
-The :mod:`secrets` module provides access to the most secure source of
+The :mod:`!secrets` module provides access to the most secure source of
randomness that your operating system provides.
.. class:: SystemRandom
@@ -58,43 +58,48 @@ randomness that your operating system provides.
Generating tokens
-----------------
-The :mod:`secrets` module provides functions for generating secure
+The :mod:`!secrets` module provides functions for generating secure
tokens, suitable for applications such as password resets,
hard-to-guess URLs, and similar.
-.. function:: token_bytes([nbytes=None])
+.. function:: token_bytes(nbytes=None)
Return a random byte string containing *nbytes* number of bytes.
- If *nbytes* is ``None`` or not supplied, a reasonable default is
- used.
+
+ If *nbytes* is not specified or ``None``, :const:`DEFAULT_ENTROPY`
+ is used instead.
.. doctest::
- >>> token_bytes(16) #doctest:+SKIP
+ >>> token_bytes(16) # doctest: +SKIP
b'\xebr\x17D*t\xae\xd4\xe3S\xb6\xe2\xebP1\x8b'
-.. function:: token_hex([nbytes=None])
+.. function:: token_hex(nbytes=None)
Return a random text string, in hexadecimal. The string has *nbytes*
- random bytes, each byte converted to two hex digits. If *nbytes* is
- ``None`` or not supplied, a reasonable default is used.
+ random bytes, each byte converted to two hex digits.
+
+ If *nbytes* is not specified or ``None``, :const:`DEFAULT_ENTROPY`
+ is used instead.
.. doctest::
- >>> token_hex(16) #doctest:+SKIP
+ >>> token_hex(16) # doctest: +SKIP
'f9bf78b9a18ce6d46a0cd2b0b86df9da'
-.. function:: token_urlsafe([nbytes=None])
+.. function:: token_urlsafe(nbytes=None)
Return a random URL-safe text string, containing *nbytes* random
bytes. The text is Base64 encoded, so on average each byte results
- in approximately 1.3 characters. If *nbytes* is ``None`` or not
- supplied, a reasonable default is used.
+ in approximately 1.3 characters.
+
+ If *nbytes* is not specified or ``None``, :const:`DEFAULT_ENTROPY`
+ is used instead.
.. doctest::
- >>> token_urlsafe(16) #doctest:+SKIP
+ >>> token_urlsafe(16) # doctest: +SKIP
'Drmhze6EPcv0fN_81Bj-nA'
@@ -107,7 +112,7 @@ tokens need to have sufficient randomness. Unfortunately, what is
considered sufficient will necessarily increase as computers get more
powerful and able to make more guesses in a shorter period. As of 2015,
it is believed that 32 bytes (256 bits) of randomness is sufficient for
-the typical use-case expected for the :mod:`secrets` module.
+the typical use-case expected for the :mod:`!secrets` module.
For those who want to manage their own token length, you can explicitly
specify how much randomness is used for tokens by giving an :class:`int`
@@ -115,11 +120,13 @@ argument to the various ``token_*`` functions. That argument is taken
as the number of bytes of randomness to use.
Otherwise, if no argument is provided, or if the argument is ``None``,
-the ``token_*`` functions will use a reasonable default instead.
+the ``token_*`` functions use :const:`DEFAULT_ENTROPY` instead.
-.. note::
+.. data:: DEFAULT_ENTROPY
+
+ Default number of bytes of randomness used by the ``token_*`` functions.
- That default is subject to change at any time, including during
+ The exact value is subject to change at any time, including during
maintenance releases.
@@ -139,7 +146,7 @@ Other functions
Recipes and best practices
--------------------------
-This section shows recipes and best practices for using :mod:`secrets`
+This section shows recipes and best practices for using :mod:`!secrets`
to manage a basic level of security.
Generate an eight-character alphanumeric password:
diff --git a/Doc/library/select.rst b/Doc/library/select.rst
index 0f0c76060df..330b0a1c55a 100644
--- a/Doc/library/select.rst
+++ b/Doc/library/select.rst
@@ -18,7 +18,7 @@ it was last read.
.. note::
The :mod:`selectors` module allows high-level and efficient I/O
- multiplexing, built upon the :mod:`select` module primitives. Users are
+ multiplexing, built upon the :mod:`!select` module primitives. Users are
encouraged to use the :mod:`selectors` module instead, unless they want
precise control over the OS-level primitives used.
@@ -171,7 +171,7 @@ The module defines the following:
The minimum number of bytes which can be written without blocking to a pipe
when the pipe has been reported as ready for writing by :func:`~select.select`,
:func:`!poll` or another interface in this module. This doesn't apply
- to other kind of file-like objects such as sockets.
+ to other kinds of file-like objects such as sockets.
This value is guaranteed by POSIX to be at least 512.
@@ -223,7 +223,7 @@ object.
implement :meth:`!fileno`, so they can also be used as the argument.
*eventmask* is an optional bitmask describing the type of events you want to
- check for. The constants are the same that with :c:func:`!poll`
+ check for. The constants are the same as with :c:func:`!poll`
object. The default value is a combination of the constants :const:`POLLIN`,
:const:`POLLPRI`, and :const:`POLLOUT`.
@@ -238,7 +238,7 @@ object.
.. method:: devpoll.modify(fd[, eventmask])
This method does an :meth:`unregister` followed by a
- :meth:`register`. It is (a bit) more efficient that doing the same
+ :meth:`register`. It is (a bit) more efficient than doing the same
explicitly.
@@ -561,9 +561,9 @@ https://man.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
+---------------------------+---------------------------------------------+
| :const:`KQ_EV_DELETE` | Removes an event from the queue |
+---------------------------+---------------------------------------------+
- | :const:`KQ_EV_ENABLE` | Permitscontrol() to returns the event |
+ | :const:`KQ_EV_ENABLE` | Permits control() to return the event |
+---------------------------+---------------------------------------------+
- | :const:`KQ_EV_DISABLE` | Disablesevent |
+ | :const:`KQ_EV_DISABLE` | Disables event |
+---------------------------+---------------------------------------------+
| :const:`KQ_EV_ONESHOT` | Removes event after first occurrence |
+---------------------------+---------------------------------------------+
diff --git a/Doc/library/selectors.rst b/Doc/library/selectors.rst
index ee556f1f3ce..2d523a9d2ea 100644
--- a/Doc/library/selectors.rst
+++ b/Doc/library/selectors.rst
@@ -54,7 +54,7 @@ Classes hierarchy::
In the following, *events* is a bitwise mask indicating which I/O events should
-be waited for on a given file object. It can be a combination of the modules
+be waited for on a given file object. It can be a combination of the module's
constants below:
+-----------------------+-----------------------------------------------+
diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst
index 6e74a59b82b..a2c9065ae78 100644
--- a/Doc/library/shelve.rst
+++ b/Doc/library/shelve.rst
@@ -61,11 +61,11 @@ lots of shared sub-objects. The keys are ordinary strings.
.. warning::
- Because the :mod:`shelve` module is backed by :mod:`pickle`, it is insecure
+ Because the :mod:`!shelve` module is backed by :mod:`pickle`, it is insecure
to load a shelf from an untrusted source. Like with pickle, loading a shelf
can execute arbitrary code.
-Shelf objects support most of methods and operations supported by dictionaries
+Shelf objects support most of the methods and operations supported by dictionaries
(except copying, constructors and operators ``|`` and ``|=``). This eases the
transition from dictionary based scripts to those requiring persistent storage.
@@ -106,7 +106,7 @@ Restrictions
database should be fairly small, and in rare cases key collisions may cause
the database to refuse updates.
-* The :mod:`shelve` module does not support *concurrent* read/write access to
+* The :mod:`!shelve` module does not support *concurrent* read/write access to
shelved objects. (Multiple simultaneous read accesses are safe.) When a
program has a shelf open for writing, no other program should have it open for
reading or writing. Unix file locking can be used to solve this, but this
@@ -219,5 +219,5 @@ object)::
Generic interface to ``dbm``-style databases.
Module :mod:`pickle`
- Object serialization used by :mod:`shelve`.
+ Object serialization used by :mod:`!shelve`.
diff --git a/Doc/library/shlex.rst b/Doc/library/shlex.rst
index a96f0864dc1..0653bf2f418 100644
--- a/Doc/library/shlex.rst
+++ b/Doc/library/shlex.rst
@@ -18,7 +18,7 @@ simple syntaxes resembling that of the Unix shell. This will often be useful
for writing minilanguages, (for example, in run control files for Python
applications) or for parsing quoted strings.
-The :mod:`shlex` module defines the following functions:
+The :mod:`!shlex` module defines the following functions:
.. function:: split(s, comments=False, posix=True)
@@ -98,7 +98,7 @@ The :mod:`shlex` module defines the following functions:
.. versionadded:: 3.3
-The :mod:`shlex` module defines the following class:
+The :mod:`!shlex` module defines the following class:
.. class:: shlex(instream=None, infile=None, posix=False, punctuation_chars=False)
@@ -214,7 +214,7 @@ A :class:`~shlex.shlex` instance has the following methods:
with the name of the current source file and the ``%d`` with the current input
line number (the optional arguments can be used to override these).
- This convenience is provided to encourage :mod:`shlex` users to generate error
+ This convenience is provided to encourage :mod:`!shlex` users to generate error
messages in the standard, parseable format understood by Emacs and other Unix
tools.
@@ -343,7 +343,7 @@ variables which either control lexical analysis or can be used for debugging:
Parsing Rules
-------------
-When operating in non-POSIX mode, :class:`~shlex.shlex` will try to obey to the
+When operating in non-POSIX mode, :class:`~shlex.shlex` will try to obey the
following rules.
* Quote characters are not recognized within words (``Do"Not"Separate`` is
@@ -366,7 +366,7 @@ following rules.
* It's not possible to parse empty strings, even if quoted.
-When operating in POSIX mode, :class:`~shlex.shlex` will try to obey to the
+When operating in POSIX mode, :class:`~shlex.shlex` will try to obey the
following parsing rules.
* Quotes are stripped out, and do not separate words (``"Do"Not"Separate"`` is
@@ -382,7 +382,7 @@ following parsing rules.
* Enclosing characters in quotes which are part of
:attr:`~shlex.escapedquotes` (e.g. ``'"'``) preserves the literal value
of all characters within the quotes, with the exception of the characters
- mentioned in :attr:`~shlex.escape`. The escape characters retain its
+ mentioned in :attr:`~shlex.escape`. The escape characters retain their
special meaning only when followed by the quote in use, or the escape
character itself. Otherwise the escape character will be considered a
normal character.
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 3a4631e7c65..8564a5b72d9 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -15,7 +15,7 @@
--------------
-The :mod:`shutil` module offers a number of high-level operations on files and
+The :mod:`!shutil` module offers a number of high-level operations on files and
collections of files. In particular, functions are provided which support file
copying and removal. For operations on individual files, see also the
:mod:`os` module.
@@ -543,7 +543,7 @@ instead of 64 KiB) and a :func:`memoryview`-based variant of
:func:`shutil.copyfileobj` is used.
If the fast-copy operation fails and no data was written in the destination
-file then shutil will silently fallback on using less efficient
+file then shutil will silently fall back to less efficient
:func:`copyfileobj` function internally.
.. versionchanged:: 3.8
@@ -674,7 +674,7 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
Return a list of supported formats for archiving.
Each element of the returned sequence is a tuple ``(name, description)``.
- By default :mod:`shutil` provides these formats:
+ By default :mod:`!shutil` provides these formats:
- *zip*: ZIP file (if the :mod:`zlib` module is available).
- *tar*: Uncompressed tar file. Uses POSIX.1-2001 pax format for new archives.
@@ -791,7 +791,7 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
Each element of the returned sequence is a tuple
``(name, extensions, description)``.
- By default :mod:`shutil` provides these formats:
+ By default :mod:`!shutil` provides these formats:
- *zip*: ZIP file (unpacking compressed files works only if the corresponding
module is available).
diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst
index 1a2a555f5c0..65750638042 100644
--- a/Doc/library/signal.rst
+++ b/Doc/library/signal.rst
@@ -36,7 +36,7 @@ Execution of Python signal handlers
A Python signal handler does not get executed inside the low-level (C) signal
handler. Instead, the low-level signal handler sets a flag which tells the
:term:`virtual machine` to execute the corresponding Python signal handler
-at a later point(for example at the next :term:`bytecode` instruction).
+at a later point (for example, at the next :term:`bytecode` instruction).
This has consequences:
* It makes little sense to catch synchronous errors like :const:`SIGFPE` or
@@ -68,6 +68,11 @@ the synchronization primitives from the :mod:`threading` module instead.
Besides, only the main thread of the main interpreter is allowed to set a new signal handler.
+.. warning::
+
+ Synchronization primitives such as :class:`threading.Lock` should not be used
+ within signal handlers. Doing so can lead to unexpected deadlocks.
+
Module contents
---------------
@@ -92,13 +97,13 @@ The signal module defines three enums:
.. class:: Handlers
- :class:`enum.IntEnum` collection the constants :const:`SIG_DFL` and :const:`SIG_IGN`.
+ :class:`enum.IntEnum` collection of the constants :const:`SIG_DFL` and :const:`SIG_IGN`.
.. versionadded:: 3.5
.. class:: Sigmasks
- :class:`enum.IntEnum` collection the constants :const:`SIG_BLOCK`, :const:`SIG_UNBLOCK` and :const:`SIG_SETMASK`.
+ :class:`enum.IntEnum` collection of the constants :const:`SIG_BLOCK`, :const:`SIG_UNBLOCK` and :const:`SIG_SETMASK`.
.. availability:: Unix.
@@ -108,7 +113,7 @@ The signal module defines three enums:
.. versionadded:: 3.5
-The variables defined in the :mod:`signal` module are:
+The variables defined in the :mod:`!signal` module are:
.. data:: SIG_DFL
@@ -350,7 +355,7 @@ The variables defined in the :mod:`signal` module are:
.. versionadded:: 3.3
-The :mod:`signal` module defines one exception:
+The :mod:`!signal` module defines one exception:
.. exception:: ItimerError
@@ -364,7 +369,7 @@ The :mod:`signal` module defines one exception:
alias of :exc:`OSError`.
-The :mod:`signal` module defines the following functions:
+The :mod:`!signal` module defines the following functions:
.. function:: alarm(time)
diff --git a/Doc/library/site.rst b/Doc/library/site.rst
index ca2ac3b0098..4686c9fc92c 100644
--- a/Doc/library/site.rst
+++ b/Doc/library/site.rst
@@ -51,11 +51,11 @@ added path for configuration files.
.. versionchanged:: 3.14
- :mod:`site` is no longer responsible for updating :data:`sys.prefix` and
+ :mod:`!site` is no longer responsible for updating :data:`sys.prefix` and
:data:`sys.exec_prefix` on :ref:`sys-path-init-virtual-environments`. This is
now done during the :ref:`path initialization <sys-path-init>`. As a result,
under :ref:`sys-path-init-virtual-environments`, :data:`sys.prefix` and
- :data:`sys.exec_prefix` no longer depend on the :mod:`site` initialization,
+ :data:`sys.exec_prefix` no longer depend on the :mod:`!site` initialization,
and are therefore unaffected by :option:`-S`.
.. _site-virtual-environments-configuration:
@@ -130,38 +130,38 @@ directory precedes the :file:`foo` directory because :file:`bar.pth` comes
alphabetically before :file:`foo.pth`; and :file:`spam` is omitted because it is
not mentioned in either path configuration file.
-:mod:`sitecustomize`
---------------------
+:mod:`!sitecustomize`
+---------------------
.. module:: sitecustomize
After these path manipulations, an attempt is made to import a module named
-:mod:`sitecustomize`, which can perform arbitrary site-specific customizations.
+:mod:`!sitecustomize`, which can perform arbitrary site-specific customizations.
It is typically created by a system administrator in the site-packages
directory. If this import fails with an :exc:`ImportError` or its subclass
exception, and the exception's :attr:`~ImportError.name`
-attribute equals to ``'sitecustomize'``,
+attribute equals ``'sitecustomize'``,
it is silently ignored. If Python is started without output streams available, as
with :file:`pythonw.exe` on Windows (which is used by default to start IDLE),
-attempted output from :mod:`sitecustomize` is ignored. Any other exception
+attempted output from :mod:`!sitecustomize` is ignored. Any other exception
causes a silent and perhaps mysterious failure of the process.
-:mod:`usercustomize`
---------------------
+:mod:`!usercustomize`
+---------------------
.. module:: usercustomize
-After this, an attempt is made to import a module named :mod:`usercustomize`,
+After this, an attempt is made to import a module named :mod:`!usercustomize`,
which can perform arbitrary user-specific customizations, if
:data:`~site.ENABLE_USER_SITE` is true. This file is intended to be created in the
user site-packages directory (see below), which is part of ``sys.path`` unless
disabled by :option:`-s`. If this import fails with an :exc:`ImportError` or
its subclass exception, and the exception's :attr:`~ImportError.name`
-attribute equals to ``'usercustomize'``, it is silently ignored.
+attribute equals ``'usercustomize'``, it is silently ignored.
Note that for some non-Unix systems, ``sys.prefix`` and ``sys.exec_prefix`` are
empty, and the path manipulations are skipped; however the import of
-:mod:`sitecustomize` and :mod:`usercustomize` is still attempted.
+:mod:`sitecustomize` and :mod:`!usercustomize` is still attempted.
.. currentmodule:: site
@@ -173,7 +173,7 @@ Readline configuration
On systems that support :mod:`readline`, this module will also import and
configure the :mod:`rlcompleter` module, if Python is started in
:ref:`interactive mode <tut-interactive>` and without the :option:`-S` option.
-The default behavior is enable tab-completion and to use
+The default behavior is to enable tab completion and to use
:file:`~/.python_history` as the history save file. To disable it, delete (or
override) the :data:`sys.__interactivehook__` attribute in your
:mod:`sitecustomize` or :mod:`usercustomize` module or your
@@ -275,7 +275,7 @@ Command-line interface
.. program:: site
-The :mod:`site` module also provides a way to get the user directories from the
+The :mod:`!site` module also provides a way to get the user directories from the
command line:
.. code-block:: shell-session
diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst
index 10525c90aa9..583bc3afcad 100644
--- a/Doc/library/smtplib.rst
+++ b/Doc/library/smtplib.rst
@@ -14,7 +14,7 @@
--------------
-The :mod:`smtplib` module defines an SMTP client session object that can be used
+The :mod:`!smtplib` module defines an SMTP client session object that can be used
to send mail to any internet machine with an SMTP or ESMTP listener daemon. For
details of SMTP and ESMTP operation, consult :rfc:`821` (Simple Mail Transfer
Protocol) and :rfc:`1869` (SMTP Service Extensions).
@@ -336,7 +336,7 @@ An :class:`SMTP` instance has the following methods:
:exc:`SMTPException`
No suitable authentication method was found.
- Each of the authentication methods supported by :mod:`smtplib` are tried in
+ Each of the authentication methods supported by :mod:`!smtplib` are tried in
turn if they are advertised as supported by the server. See :meth:`auth`
for a list of supported authentication methods. *initial_response_ok* is
passed through to :meth:`auth`.
@@ -388,7 +388,7 @@ An :class:`SMTP` instance has the following methods:
call the :meth:`login` method, which will try each of the above mechanisms
in turn, in the order listed. ``auth`` is exposed to facilitate the
implementation of authentication methods not (or not yet) supported
- directly by :mod:`smtplib`.
+ directly by :mod:`!smtplib`.
.. versionadded:: 3.5
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index 782ea7d8fda..56a4f8efe71 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -83,7 +83,7 @@ created. Socket addresses are represented as follows:
- For :const:`AF_INET6` address family, a four-tuple ``(host, port, flowinfo,
scope_id)`` is used, where *flowinfo* and *scope_id* represent the ``sin6_flowinfo``
and ``sin6_scope_id`` members in :const:`struct sockaddr_in6` in C. For
- :mod:`socket` module methods, *flowinfo* and *scope_id* can be omitted just for
+ :mod:`!socket` module methods, *flowinfo* and *scope_id* can be omitted just for
backward compatibility. Note, however, omission of *scope_id* can cause problems
in manipulating scoped IPv6 addresses.
@@ -118,10 +118,10 @@ created. Socket addresses are represented as follows:
``'can0'``. The network interface name ``''`` can be used to receive packets
from all network interfaces of this family.
- - :const:`CAN_ISOTP` protocol require a tuple ``(interface, rx_addr, tx_addr)``
+ - :const:`CAN_ISOTP` protocol requires a tuple ``(interface, rx_addr, tx_addr)``
where both additional parameters are unsigned long integer that represent a
CAN identifier (standard or extended).
- - :const:`CAN_J1939` protocol require a tuple ``(interface, name, pgn, addr)``
+ - :const:`CAN_J1939` protocol requires a tuple ``(interface, name, pgn, addr)``
where additional parameters are 64-bit unsigned integer representing the
ECU name, a 32-bit unsigned integer representing the Parameter Group Number
(PGN), and an 8-bit integer representing the address.
@@ -302,7 +302,7 @@ generalization of this based on timeouts is supported through
Module contents
---------------
-The module :mod:`socket` exports the following elements.
+The module :mod:`!socket` exports the following elements.
Exceptions
@@ -1028,13 +1028,13 @@ The following functions all create :ref:`socket objects <socket-objects>`.
Other functions
'''''''''''''''
-The :mod:`socket` module also offers various network-related services:
+The :mod:`!socket` module also offers various network-related services:
.. function:: close(fd)
Close a socket file descriptor. This is like :func:`os.close`, but for
- sockets. On some platforms (most noticeable Windows) :func:`os.close`
+ sockets. On some platforms (most notably Windows) :func:`os.close`
does not work for socket file descriptors.
.. versionadded:: 3.7
@@ -1590,7 +1590,7 @@ to sockets.
address family --- see above.)
If the connection is interrupted by a signal, the method waits until the
- connection completes, or raise a :exc:`TimeoutError` on timeout, if the
+ connection completes, or raises a :exc:`TimeoutError` on timeout, if the
signal handler doesn't raise an exception and the socket is blocking or has
a timeout. For non-blocking sockets, the method raises an
:exc:`InterruptedError` exception if the connection is interrupted by a
@@ -2094,11 +2094,11 @@ to sockets.
Set the value of the given socket option (see the Unix manual page
:manpage:`setsockopt(2)`). The needed symbolic constants are defined in this
module (:ref:`!SO_\* etc. <socket-unix-constants>`). The value can be an integer,
- ``None`` or a :term:`bytes-like object` representing a buffer. In the later
+ ``None`` or a :term:`bytes-like object` representing a buffer. In the latter
case it is up to the caller to ensure that the bytestring contains the
proper bits (see the optional built-in module :mod:`struct` for a way to
encode C structures as bytestrings). When *value* is set to ``None``,
- *optlen* argument is required. It's equivalent to call :c:func:`setsockopt` C
+ *optlen* argument is required. It's equivalent to calling :c:func:`setsockopt` C
function with ``optval=NULL`` and ``optlen=optlen``.
.. versionchanged:: 3.5
@@ -2412,7 +2412,7 @@ lead to this error::
This is because the previous execution has left the socket in a ``TIME_WAIT``
state, and can't be immediately reused.
-There is a :mod:`socket` flag to set, in order to prevent this,
+There is a :mod:`!socket` flag to set, in order to prevent this,
:const:`socket.SO_REUSEADDR`::
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
diff --git a/Doc/library/socketserver.rst b/Doc/library/socketserver.rst
index 7545b5fb0a5..e1d47b69b75 100644
--- a/Doc/library/socketserver.rst
+++ b/Doc/library/socketserver.rst
@@ -8,7 +8,7 @@
--------------
-The :mod:`socketserver` module simplifies the task of writing network servers.
+The :mod:`!socketserver` module simplifies the task of writing network servers.
.. include:: ../includes/wasm-notavail.rst
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index cbc3f32d9b9..b708a50ed25 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -291,7 +291,7 @@ Module functions
Set it to any combination (using ``|``, bitwise or) of
:const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES`
to enable this.
- Column names takes precedence over declared types if both flags are set.
+ Column names take precedence over declared types if both flags are set.
By default (``0``), type detection is disabled.
:param isolation_level:
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index 93cdf6d85f0..aecc133abec 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -130,7 +130,7 @@ purposes.
cafile=None, capath=None, cadata=None)
Return a new :class:`SSLContext` object with default settings for
- the given *purpose*. The settings are chosen by the :mod:`ssl` module,
+ the given *purpose*. The settings are chosen by the :mod:`!ssl` module,
and usually represent a higher security level than when calling the
:class:`SSLContext` constructor directly.
@@ -1456,7 +1456,7 @@ to speed up repeated connections from the same clients.
TLS 1.3.
.. seealso::
- :func:`create_default_context` lets the :mod:`ssl` module choose
+ :func:`create_default_context` lets the :mod:`!ssl` module choose
security settings for a given purpose.
.. versionchanged:: 3.6
diff --git a/Doc/library/stat.rst b/Doc/library/stat.rst
index 8434b2e8c75..bcb1dc269b6 100644
--- a/Doc/library/stat.rst
+++ b/Doc/library/stat.rst
@@ -11,7 +11,7 @@
--------------
-The :mod:`stat` module defines constants and functions for interpreting the
+The :mod:`!stat` module defines constants and functions for interpreting the
results of :func:`os.stat`, :func:`os.fstat` and :func:`os.lstat` (if they
exist). For complete details about the :c:func:`stat`, :c:func:`!fstat` and
:c:func:`!lstat` calls, consult the documentation for your system.
@@ -19,7 +19,7 @@ exist). For complete details about the :c:func:`stat`, :c:func:`!fstat` and
.. versionchanged:: 3.4
The stat module is backed by a C implementation.
-The :mod:`stat` module defines the following functions to test for specific file
+The :mod:`!stat` module defines the following functions to test for specific file
types:
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 7b983f25c46..ac856152e41 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -265,9 +265,17 @@ The constructors :func:`int`, :func:`float`, and
pair: operator; % (percent)
pair: operator; **
+.. _stdtypes-mixed-arithmetic:
+
Python fully supports mixed arithmetic: when a binary arithmetic operator has
-operands of different numeric types, the operand with the "narrower" type is
-widened to that of the other, where integer is narrower than floating point.
+operands of different built-in numeric types, the operand with the "narrower"
+type is widened to that of the other:
+
+* If both arguments are complex numbers, no conversion is performed;
+* if either argument is a complex or a floating-point number, the other is
+ converted to a floating-point number;
+* otherwise, both must be integers and no conversion is necessary.
+
Arithmetic with complex and real operands is defined by the usual mathematical
formula, for example::
@@ -1441,108 +1449,10 @@ application).
list appear empty for the duration, and raises :exc:`ValueError` if it can
detect that the list has been mutated during a sort.
-.. admonition:: Thread safety
-
- Reading a single element from a :class:`list` is
- :term:`atomic <atomic operation>`:
-
- .. code-block::
- :class: green
-
- lst[i] # list.__getitem__
-
- The following methods traverse the list and use :term:`atomic <atomic operation>`
- reads of each item to perform their function. That means that they may
- return results affected by concurrent modifications:
-
- .. code-block::
- :class: maybe
-
- item in lst
- lst.index(item)
- lst.count(item)
-
- All of the above methods/operations are also lock-free. They do not block
- concurrent modifications. Other operations that hold a lock will not block
- these from observing intermediate states.
-
- All other operations from here on block using the per-object lock.
-
- Writing a single item via ``lst[i] = x`` is safe to call from multiple
- threads and will not corrupt the list.
-
- The following operations return new objects and appear
- :term:`atomic <atomic operation>` to other threads:
-
- .. code-block::
- :class: good
-
- lst1 + lst2 # concatenates two lists into a new list
- x * lst # repeats lst x times into a new list
- lst.copy() # returns a shallow copy of the list
-
- Methods that only operate on a single elements with no shifting required are
- :term:`atomic <atomic operation>`:
-
- .. code-block::
- :class: good
-
- lst.append(x) # append to the end of the list, no shifting required
- lst.pop() # pop element from the end of the list, no shifting required
-
- The :meth:`~list.clear` method is also :term:`atomic <atomic operation>`.
- Other threads cannot observe elements being removed.
-
- The :meth:`~list.sort` method is not :term:`atomic <atomic operation>`.
- Other threads cannot observe intermediate states during sorting, but the
- list appears empty for the duration of the sort.
-
- The following operations may allow lock-free operations to observe
- intermediate states since they modify multiple elements in place:
-
- .. code-block::
- :class: maybe
-
- lst.insert(idx, item) # shifts elements
- lst.pop(idx) # idx not at the end of the list, shifts elements
- lst *= x # copies elements in place
-
- The :meth:`~list.remove` method may allow concurrent modifications since
- element comparison may execute arbitrary Python code (via
- :meth:`~object.__eq__`).
-
- :meth:`~list.extend` is safe to call from multiple threads. However, its
- guarantees depend on the iterable passed to it. If it is a :class:`list`, a
- :class:`tuple`, a :class:`set`, a :class:`frozenset`, a :class:`dict` or a
- :ref:`dictionary view object <dict-views>` (but not their subclasses), the
- ``extend`` operation is safe from concurrent modifications to the iterable.
- Otherwise, an iterator is created which can be concurrently modified by
- another thread. The same applies to inplace concatenation of a list with
- other iterables when using ``lst += iterable``.
-
- Similarly, assigning to a list slice with ``lst[i:j] = iterable`` is safe
- to call from multiple threads, but ``iterable`` is only locked when it is
- also a :class:`list` (but not its subclasses).
-
- Operations that involve multiple accesses, as well as iteration, are never
- atomic. For example:
-
- .. code-block::
- :class: bad
-
- # NOT atomic: read-modify-write
- lst[i] = lst[i] + 1
-
- # NOT atomic: check-then-act
- if lst:
- item = lst.pop()
-
- # NOT thread-safe: iteration while modifying
- for item in lst:
- process(item) # another thread may modify lst
+.. seealso::
- Consider external synchronization when sharing :class:`list` instances
- across threads. See :ref:`freethreading-python-howto` for more information.
+ For detailed information on thread-safety guarantees for :class:`list`
+ objects, see :ref:`thread-safety-list`.
.. _typesseq-tuple:
@@ -2180,7 +2090,18 @@ expression support in the :mod:`re` module).
Return ``True`` if all characters in the string are alphanumeric and there is at
least one character, ``False`` otherwise. A character ``c`` is alphanumeric if one
of the following returns ``True``: ``c.isalpha()``, ``c.isdecimal()``,
- ``c.isdigit()``, or ``c.isnumeric()``.
+ ``c.isdigit()``, or ``c.isnumeric()``. For example:
+
+ .. doctest::
+
+ >>> 'abc123'.isalnum()
+ True
+ >>> 'abc123!@#'.isalnum()
+ False
+ >>> ''.isalnum()
+ False
+ >>> ' '.isalnum()
+ False
.. method:: str.isalpha()
@@ -2326,17 +2247,34 @@ expression support in the :mod:`re` module).
>>> '\t'.isprintable(), '\n'.isprintable()
(False, False)
+ See also :meth:`isspace`.
+
.. method:: str.isspace()
Return ``True`` if there are only whitespace characters in the string and there is
at least one character, ``False`` otherwise.
+ For example:
+
+ .. doctest::
+
+ >>> ''.isspace()
+ False
+ >>> ' '.isspace()
+ True
+ >>> '\t\n'.isspace() # TAB and BREAK LINE
+ True
+ >>> '\u3000'.isspace() # IDEOGRAPHIC SPACE
+ True
+
A character is *whitespace* if in the Unicode character database
(see :mod:`unicodedata`), either its general category is ``Zs``
("Separator, space"), or its bidirectional class is one of ``WS``,
``B``, or ``S``.
+ See also :meth:`isprintable`.
+
.. method:: str.istitle()
@@ -2472,6 +2410,19 @@ expression support in the :mod:`re` module).
after the separator. If the separator is not found, return a 3-tuple containing
the string itself, followed by two empty strings.
+ For example:
+
+ .. doctest::
+
+ >>> 'Monty Python'.partition(' ')
+ ('Monty', ' ', 'Python')
+ >>> "Monty Python's Flying Circus".partition(' ')
+ ('Monty', ' ', "Python's Flying Circus")
+ >>> 'Monty Python'.partition('-')
+ ('Monty Python', '', '')
+
+ See also :meth:`rpartition`.
+
.. method:: str.removeprefix(prefix, /)
@@ -2570,6 +2521,19 @@ expression support in the :mod:`re` module).
done using the specified *fillchar* (default is an ASCII space). The
original string is returned if *width* is less than or equal to ``len(s)``.
+ For example:
+
+ .. doctest::
+
+ >>> 'Python'.rjust(10)
+ ' Python'
+ >>> 'Python'.rjust(10, '.')
+ '....Python'
+ >>> 'Monty Python'.rjust(10, '.')
+ 'Monty Python'
+
+ See also :meth:`ljust` and :meth:`zfill`.
+
.. method:: str.rpartition(sep, /)
@@ -2606,14 +2570,17 @@ expression support in the :mod:`re` module).
Return a copy of the string with trailing characters removed. The *chars*
argument is a string specifying the set of characters to be removed. If omitted
or ``None``, the *chars* argument defaults to removing whitespace. The *chars*
- argument is not a suffix; rather, all combinations of its values are stripped::
+ argument is not a suffix; rather, all combinations of its values are stripped.
+ For example:
+
+ .. doctest::
>>> ' spacious '.rstrip()
' spacious'
>>> 'mississippi'.rstrip('ipz')
'mississ'
- See :meth:`str.removesuffix` for a method that will remove a single suffix
+ See :meth:`removesuffix` for a method that will remove a single suffix
string rather than all of a set of characters. For example::
>>> 'Monty Python'.rstrip(' Python')
@@ -2621,6 +2588,9 @@ expression support in the :mod:`re` module).
>>> 'Monty Python'.removesuffix(' Python')
'Monty'
+ See also :meth:`strip`.
+
+
.. method:: str.split(sep=None, maxsplit=-1)
Return a list of the words in the string, using *sep* as the delimiter
@@ -2751,6 +2721,19 @@ expression support in the :mod:`re` module).
test string beginning at that position. With optional *end*, stop comparing
string at that position.
+ For example:
+
+ .. doctest::
+
+ >>> 'Python'.startswith('Py')
+ True
+ >>> 'a tuple of prefixes'.startswith(('at', 'a'))
+ True
+ >>> 'Python is amazing'.startswith('is', 7)
+ True
+
+ See also :meth:`endswith` and :meth:`removeprefix`.
+
.. method:: str.strip(chars=None, /)
@@ -2758,7 +2741,11 @@ expression support in the :mod:`re` module).
The *chars* argument is a string specifying the set of characters to be removed.
If omitted or ``None``, the *chars* argument defaults to removing whitespace.
The *chars* argument is not a prefix or suffix; rather, all combinations of its
- values are stripped::
+ values are stripped.
+
+ For example:
+
+ .. doctest::
>>> ' spacious '.strip()
'spacious'
@@ -2769,12 +2756,17 @@ expression support in the :mod:`re` module).
from the string. Characters are removed from the leading end until
reaching a string character that is not contained in the set of
characters in *chars*. A similar action takes place on the trailing end.
- For example::
+
+ For example:
+
+ .. doctest::
>>> comment_string = '#....... Section 3.2.1 Issue #32 .......'
>>> comment_string.strip('.#! ')
'Section 3.2.1 Issue #32'
+ See also :meth:`rstrip`.
+
.. method:: str.swapcase()
@@ -2858,13 +2850,17 @@ expression support in the :mod:`re` module).
than before. The original string is returned if *width* is less than
or equal to ``len(s)``.
- For example::
+ For example:
+
+ .. doctest::
>>> "42".zfill(5)
'00042'
>>> "-42".zfill(5)
'-0042'
+ See also :meth:`rjust`.
+
.. index::
single: ! formatted string literal
@@ -3194,6 +3190,10 @@ The conversion types are:
| | character in the result. | |
+------------+-----------------------------------------------------+-------+
+For floating-point formats, the result should be correctly rounded to a given
+precision ``p`` of digits after the decimal point. The rounding mode matches
+that of the :func:`round` builtin.
+
Notes:
(1)
@@ -5506,6 +5506,12 @@ can be used interchangeably to index the same dictionary entry.
of a :class:`dict`.
+.. seealso::
+
+ For detailed information on thread-safety guarantees for :class:`dict`
+ objects, see :ref:`thread-safety-dict`.
+
+
.. _dict-views:
Dictionary view objects
diff --git a/Doc/library/string.rst b/Doc/library/string.rst
index e3ad018d1d0..8096d90317d 100644
--- a/Doc/library/string.rst
+++ b/Doc/library/string.rst
@@ -87,7 +87,7 @@ Custom String Formatting
The built-in string class provides the ability to do complex variable
substitutions and value formatting via the :meth:`~str.format` method described in
-:pep:`3101`. The :class:`Formatter` class in the :mod:`string` module allows
+:pep:`3101`. The :class:`Formatter` class in the :mod:`!string` module allows
you to create and customize your own string formatting behaviors using the same
implementation as the built-in :meth:`~str.format` method.
@@ -840,7 +840,7 @@ Template strings support ``$``-based substitutions, using the following rules:
Any other appearance of ``$`` in the string will result in a :exc:`ValueError`
being raised.
-The :mod:`string` module provides a :class:`Template` class that implements
+The :mod:`!string` module provides a :class:`Template` class that implements
these rules. The methods of :class:`Template` are:
diff --git a/Doc/library/stringprep.rst b/Doc/library/stringprep.rst
index 37d5adf0fa9..b9caa2aa830 100644
--- a/Doc/library/stringprep.rst
+++ b/Doc/library/stringprep.rst
@@ -26,14 +26,14 @@ define which tables it uses, and what other optional parts of the ``stringprep``
procedure are part of the profile. One example of a ``stringprep`` profile is
``nameprep``, which is used for internationalized domain names.
-The module :mod:`stringprep` only exposes the tables from :rfc:`3454`. As these
+The module :mod:`!stringprep` only exposes the tables from :rfc:`3454`. As these
tables would be very large to represent as dictionaries or lists, the
module uses the Unicode character database internally. The module source code
itself was generated using the ``mkstringprep.py`` utility.
As a result, these tables are exposed as functions, not as data structures.
There are two kinds of tables in the RFC: sets and mappings. For a set,
-:mod:`stringprep` provides the "characteristic function", i.e. a function that
+:mod:`!stringprep` provides the "characteristic function", i.e. a function that
returns ``True`` if the parameter is part of the set. For mappings, it provides the
mapping function: given the key, it returns the associated value. Below is a
list of all functions available in the module.
diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst
index 17fc479fd0c..c08df534128 100644
--- a/Doc/library/struct.rst
+++ b/Doc/library/struct.rst
@@ -36,7 +36,7 @@ and the C layer.
responsible for defining byte ordering and padding between elements.
See :ref:`struct-alignment` for details.
-Several :mod:`struct` functions (and methods of :class:`Struct`) take a *buffer*
+Several :mod:`!struct` functions (and methods of :class:`Struct`) take a *buffer*
argument. This refers to objects that implement the :ref:`bufferobjects` and
provide either a readable or read-writable buffer. The most common types used
for that purpose are :class:`bytes` and :class:`bytearray`, but many other types
@@ -479,7 +479,7 @@ at the end, assuming the platform's longs are aligned on 4-byte boundaries::
Applications
------------
-Two main applications for the :mod:`struct` module exist, data
+Two main applications for the :mod:`!struct` module exist, data
interchange between Python and C code within an application or another
application compiled using the same compiler (:ref:`native formats<struct-native-formats>`), and
data interchange between applications using agreed upon data layout
@@ -571,7 +571,7 @@ below were executed on a 32-bit machine::
Classes
-------
-The :mod:`struct` module also defines the following type:
+The :mod:`!struct` module also defines the following type:
.. class:: Struct(format)
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index b8dfcc31077..a0eae14aecd 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -11,14 +11,14 @@
--------------
-The :mod:`subprocess` module allows you to spawn new processes, connect to their
+The :mod:`!subprocess` module allows you to spawn new processes, connect to their
input/output/error pipes, and obtain their return codes. This module intends to
replace several older modules and functions::
os.system
os.spawn*
-Information about how the :mod:`subprocess` module can be used to replace these
+Information about how the :mod:`!subprocess` module can be used to replace these
modules and functions can be found in the following sections.
.. seealso::
@@ -27,8 +27,8 @@ modules and functions can be found in the following sections.
.. include:: ../includes/wasm-mobile-notavail.rst
-Using the :mod:`subprocess` Module
-----------------------------------
+Using the :mod:`!subprocess` Module
+-----------------------------------
The recommended approach to invoking subprocesses is to use the :func:`run`
function for all use cases it can handle. For more advanced use cases, the
@@ -1041,7 +1041,7 @@ on Windows.
Windows Constants
^^^^^^^^^^^^^^^^^
-The :mod:`subprocess` module exposes the following constants.
+The :mod:`!subprocess` module exposes the following constants.
.. data:: STD_INPUT_HANDLE
@@ -1330,8 +1330,8 @@ calls these functions.
.. _subprocess-replacements:
-Replacing Older Functions with the :mod:`subprocess` Module
------------------------------------------------------------
+Replacing Older Functions with the :mod:`!subprocess` Module
+------------------------------------------------------------
In this section, "a becomes b" means that b can be used as a replacement for a.
@@ -1347,7 +1347,7 @@ In this section, "a becomes b" means that b can be used as a replacement for a.
:attr:`~CalledProcessError.output` attribute of the raised exception.
In the following examples, we assume that the relevant functions have already
-been imported from the :mod:`subprocess` module.
+been imported from the :mod:`!subprocess` module.
Replacing :program:`/bin/sh` shell command substitution
@@ -1407,7 +1407,7 @@ Notes:
* The :func:`os.system` function ignores SIGINT and SIGQUIT signals while
the command is running, but the caller must do this separately when
- using the :mod:`subprocess` module.
+ using the :mod:`!subprocess` module.
A more realistic example would look like this::
@@ -1591,7 +1591,7 @@ runtime):
Disable use of ``posix_spawn()``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-On Linux, :mod:`subprocess` defaults to using the ``vfork()`` system call
+On Linux, :mod:`!subprocess` defaults to using the ``vfork()`` system call
internally when it is safe to do so rather than ``fork()``. This greatly
improves performance.
diff --git a/Doc/library/symtable.rst b/Doc/library/symtable.rst
index 54e19af4bd6..2f7bba2537d 100644
--- a/Doc/library/symtable.rst
+++ b/Doc/library/symtable.rst
@@ -14,7 +14,7 @@
Symbol tables are generated by the compiler from AST just before bytecode is
generated. The symbol table is responsible for calculating the scope of every
-identifier in the code. :mod:`symtable` provides an interface to examine these
+identifier in the code. :mod:`!symtable` provides an interface to examine these
tables.
@@ -355,7 +355,7 @@ Command-Line Usage
.. versionadded:: 3.13
-The :mod:`symtable` module can be executed as a script from the command line.
+The :mod:`!symtable` module can be executed as a script from the command line.
.. code-block:: sh
diff --git a/Doc/library/sys.monitoring.rst b/Doc/library/sys.monitoring.rst
index 303655fb128..4a460479e4a 100644
--- a/Doc/library/sys.monitoring.rst
+++ b/Doc/library/sys.monitoring.rst
@@ -10,7 +10,7 @@
.. note::
- :mod:`sys.monitoring` is a namespace within the :mod:`sys` module,
+ :mod:`!sys.monitoring` is a namespace within the :mod:`sys` module,
not an independent module, so there is no need to
``import sys.monitoring``, simply ``import sys`` and then use
``sys.monitoring``.
@@ -20,7 +20,7 @@ This namespace provides access to the functions and constants necessary to
activate and control event monitoring.
As programs execute, events occur that might be of interest to tools that
-monitor execution. The :mod:`sys.monitoring` namespace provides means to
+monitor execution. The :mod:`!sys.monitoring` namespace provides means to
receive callbacks when events of interest occur.
The monitoring API consists of three components:
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 136229b4c81..3420f88e36f 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -515,7 +515,7 @@ always available. Unless explicitly noted otherwise, all variables are read-only
in the range 0--127, and produce undefined results otherwise. Some systems
have a convention for assigning specific meanings to specific exit codes, but
these are generally underdeveloped; Unix programs generally use 2 for command
- line syntax errors and 1 for all other kind of errors. If another type of
+ line syntax errors and 1 for all other kinds of errors. If another type of
object is passed, ``None`` is equivalent to passing zero, and any other
object is printed to :data:`stderr` and results in an exit code of 1. In
particular, ``sys.exit("some error message")`` is a quick way to exit a
@@ -2230,7 +2230,7 @@ always available. Unless explicitly noted otherwise, all variables are read-only
The version number used to form registry keys on Windows platforms. This is
stored as string resource 1000 in the Python DLL. The value is normally the
- major and minor versions of the running Python interpreter. It is provided in the :mod:`sys`
+ major and minor versions of the running Python interpreter. It is provided in the :mod:`!sys`
module for informational purposes; modifying this value has no effect on the
registry keys used by Python.
diff --git a/Doc/library/sysconfig.rst b/Doc/library/sysconfig.rst
index 532facb45f8..138af76a66f 100644
--- a/Doc/library/sysconfig.rst
+++ b/Doc/library/sysconfig.rst
@@ -16,7 +16,7 @@
--------------
-The :mod:`sysconfig` module provides access to Python's configuration
+The :mod:`!sysconfig` module provides access to Python's configuration
information like the list of installation paths and the configuration variables
relevant for the current platform.
@@ -28,7 +28,7 @@ A Python distribution contains a :file:`Makefile` and a :file:`pyconfig.h`
header file that are necessary to build both the Python binary itself and
third-party C extensions compiled using ``setuptools``.
-:mod:`sysconfig` puts all variables found in these files in a dictionary that
+:mod:`!sysconfig` puts all variables found in these files in a dictionary that
can be accessed using :func:`get_config_vars` or :func:`get_config_var`.
Notice that on Windows, it's a much smaller set.
@@ -68,7 +68,7 @@ Installation paths
------------------
Python uses an installation scheme that differs depending on the platform and on
-the installation options. These schemes are stored in :mod:`sysconfig` under
+the installation options. These schemes are stored in :mod:`!sysconfig` under
unique identifiers based on the value returned by :const:`os.name`.
The schemes are used by package installers to determine where to copy files to.
@@ -258,12 +258,12 @@ Path Installation directory
Installation path functions
---------------------------
-:mod:`sysconfig` provides some functions to determine these installation paths.
+:mod:`!sysconfig` provides some functions to determine these installation paths.
.. function:: get_scheme_names()
Return a tuple containing all schemes currently supported in
- :mod:`sysconfig`.
+ :mod:`!sysconfig`.
.. function:: get_default_scheme()
@@ -285,7 +285,7 @@ Installation path functions
*key* must be either ``"prefix"``, ``"home"``, or ``"user"``.
The return value is a scheme name listed in :func:`get_scheme_names`. It
- can be passed to :mod:`sysconfig` functions that take a *scheme* argument,
+ can be passed to :mod:`!sysconfig` functions that take a *scheme* argument,
such as :func:`get_paths`.
.. versionadded:: 3.10
@@ -313,7 +313,7 @@ Installation path functions
.. function:: get_path_names()
Return a tuple containing all path names currently supported in
- :mod:`sysconfig`.
+ :mod:`!sysconfig`.
.. function:: get_path(name, [scheme, [vars, [expand]]])
@@ -323,7 +323,7 @@ Installation path functions
*name* has to be a value from the list returned by :func:`get_path_names`.
- :mod:`sysconfig` stores installation paths corresponding to each path name,
+ :mod:`!sysconfig` stores installation paths corresponding to each path name,
for each platform, with variables to be expanded. For instance the *stdlib*
path for the *nt* scheme is: ``{base}/Lib``.
@@ -431,7 +431,7 @@ Other functions
Command-line usage
------------------
-You can use :mod:`sysconfig` as a script with Python's *-m* option:
+You can use :mod:`!sysconfig` as a script with Python's *-m* option:
.. code-block:: shell-session
diff --git a/Doc/library/syslog.rst b/Doc/library/syslog.rst
index 548898a37bc..b6bf0124095 100644
--- a/Doc/library/syslog.rst
+++ b/Doc/library/syslog.rst
@@ -2,7 +2,6 @@
===============================================
.. module:: syslog
- :platform: Unix
:synopsis: An interface to the Unix syslog library routines.
--------------
diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst
index e57a0f121c5..a87ec10b308 100644
--- a/Doc/library/tarfile.rst
+++ b/Doc/library/tarfile.rst
@@ -11,7 +11,7 @@
--------------
-The :mod:`tarfile` module makes it possible to read and write tar
+The :mod:`!tarfile` module makes it possible to read and write tar
archives, including those using gzip, bz2 and lzma compression.
Use the :mod:`zipfile` module to read or write :file:`.zip` files, or the
higher-level functions in :ref:`shutil <archiving-operations>`.
@@ -216,25 +216,25 @@ Some facts and figures:
.. function:: is_tarfile(name)
- Return :const:`True` if *name* is a tar archive file, that the :mod:`tarfile`
+ Return :const:`True` if *name* is a tar archive file, that the :mod:`!tarfile`
module can read. *name* may be a :class:`str`, file, or file-like object.
.. versionchanged:: 3.9
Support for file and file-like objects.
-The :mod:`tarfile` module defines the following exceptions:
+The :mod:`!tarfile` module defines the following exceptions:
.. exception:: TarError
- Base class for all :mod:`tarfile` exceptions.
+ Base class for all :mod:`!tarfile` exceptions.
.. exception:: ReadError
Is raised when a tar archive is opened, that either cannot be handled by the
- :mod:`tarfile` module or is somehow invalid.
+ :mod:`!tarfile` module or is somehow invalid.
.. exception:: CompressionError
@@ -355,7 +355,7 @@ The following constants are available at the module level:
Each of the following constants defines a tar archive format that the
-:mod:`tarfile` module is able to create. See section :ref:`tar-formats` for
+:mod:`!tarfile` module is able to create. See section :ref:`tar-formats` for
details.
@@ -1285,7 +1285,7 @@ Command-Line Interface
.. versionadded:: 3.4
-The :mod:`tarfile` module provides a simple command-line interface to interact
+The :mod:`!tarfile` module provides a simple command-line interface to interact
with tar archives.
If you want to create a new tar archive, specify its name after the :option:`-c`
@@ -1446,7 +1446,7 @@ parameter in :meth:`TarFile.add`::
Supported tar formats
---------------------
-There are three tar formats that can be created with the :mod:`tarfile` module:
+There are three tar formats that can be created with the :mod:`!tarfile` module:
* The POSIX.1-1988 ustar format (:const:`USTAR_FORMAT`). It supports filenames
up to a length of at best 256 characters and linknames up to 100 characters.
@@ -1455,7 +1455,7 @@ There are three tar formats that can be created with the :mod:`tarfile` module:
* The GNU tar format (:const:`GNU_FORMAT`). It supports long filenames and
linknames, files bigger than 8 GiB and sparse files. It is the de facto
- standard on GNU/Linux systems. :mod:`tarfile` fully supports the GNU tar
+ standard on GNU/Linux systems. :mod:`!tarfile` fully supports the GNU tar
extensions for long names, sparse file support is read-only.
* The POSIX.1-2001 pax format (:const:`PAX_FORMAT`). It is the most flexible
@@ -1500,7 +1500,7 @@ Unfortunately, there is no way to autodetect the encoding of an archive. The
pax format was designed to solve this problem. It stores non-ASCII metadata
using the universal character encoding *UTF-8*.
-The details of character conversion in :mod:`tarfile` are controlled by the
+The details of character conversion in :mod:`!tarfile` are controlled by the
*encoding* and *errors* keyword arguments of the :class:`TarFile` class.
*encoding* defines the character encoding to use for the metadata in the
diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst
index 9d26f47820b..78d37d8135c 100644
--- a/Doc/library/tempfile.rst
+++ b/Doc/library/tempfile.rst
@@ -386,7 +386,7 @@ not surprise other unsuspecting code by changing global API behavior.
Examples
--------
-Here are some examples of typical usage of the :mod:`tempfile` module::
+Here are some examples of typical usage of the :mod:`!tempfile` module::
>>> import tempfile
diff --git a/Doc/library/termios.rst b/Doc/library/termios.rst
index 0c6f3059fe7..537dfcedd8c 100644
--- a/Doc/library/termios.rst
+++ b/Doc/library/termios.rst
@@ -2,7 +2,6 @@
===========================================
.. module:: termios
- :platform: Unix
:synopsis: POSIX style tty control.
.. index::
@@ -38,7 +37,7 @@ The module defines the following functions:
items with indices :const:`VMIN` and :const:`VTIME`, which are integers when
these fields are defined). The interpretation of the flags and the speeds as
well as the indexing in the *cc* array must be done using the symbolic
- constants defined in the :mod:`termios` module.
+ constants defined in the :mod:`!termios` module.
.. function:: tcsetattr(fd, when, attributes)
diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index 44b1d395a27..b5a3005f854 100644
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -7,7 +7,7 @@
.. sectionauthor:: Brett Cannon <brett@python.org>
.. note::
- The :mod:`test` package is meant for internal use by Python only. It is
+ The :mod:`!test` package is meant for internal use by Python only. It is
documented for the benefit of the core developers of Python. Any use of
this package outside of Python's standard library is discouraged as code
mentioned here can change or be removed without notice between releases of
@@ -15,12 +15,12 @@
--------------
-The :mod:`test` package contains all regression tests for Python as well as the
+The :mod:`!test` package contains all regression tests for Python as well as the
modules :mod:`test.support` and :mod:`test.regrtest`.
:mod:`test.support` is used to enhance your tests while
:mod:`test.regrtest` drives the testing suite.
-Each module in the :mod:`test` package whose name starts with ``test_`` is a
+Each module in the :mod:`!test` package whose name starts with ``test_`` is a
testing suite for a specific module or feature. All new tests should be written
using the :mod:`unittest` or :mod:`doctest` module. Some older tests are
written using a "traditional" testing style that compares output printed to
@@ -38,8 +38,8 @@ written using a "traditional" testing style that compares output printed to
.. _writing-tests:
-Writing Unit Tests for the :mod:`test` package
-----------------------------------------------
+Writing Unit Tests for the :mod:`!test` package
+-----------------------------------------------
It is preferred that tests that use the :mod:`unittest` module follow a few
guidelines. One is to name the test module by starting it with ``test_`` and end
@@ -162,12 +162,12 @@ Running tests using the command-line interface
.. module:: test.regrtest
:synopsis: Drives the regression test suite.
-The :mod:`test` package can be run as a script to drive Python's regression
+The :mod:`!test` package can be run as a script to drive Python's regression
test suite, thanks to the :option:`-m` option: :program:`python -m test`. Under
-the hood, it uses :mod:`test.regrtest`; the call :program:`python -m
+the hood, it uses :mod:`!test.regrtest`; the call :program:`python -m
test.regrtest` used in previous Python versions still works. Running the
script by itself automatically starts running all regression tests in the
-:mod:`test` package. It does this by finding all modules in the package whose
+:mod:`!test` package. It does this by finding all modules in the package whose
name starts with ``test_``, importing them, and executing the function
:func:`test_main` if present or loading the tests via
unittest.TestLoader.loadTestsFromModule if ``test_main`` does not exist. The
@@ -175,14 +175,14 @@ names of tests to execute may also be passed to the script. Specifying a single
regression test (:program:`python -m test test_spam`) will minimize output and
only print whether the test passed or failed.
-Running :mod:`test` directly allows what resources are available for
+Running :mod:`!test` directly allows what resources are available for
tests to use to be set. You do this by using the ``-u`` command-line
option. Specifying ``all`` as the value for the ``-u`` option enables all
possible resources: :program:`python -m test -uall`.
If all but one resource is desired (a more common case), a
comma-separated list of resources that are not desired may be listed after
``all``. The command :program:`python -m test -uall,-audio,-largefile`
-will run :mod:`test` with all resources except the ``audio`` and
+will run :mod:`!test` with all resources except the ``audio`` and
``largefile`` resources. For a list of all resources and more command-line
options, run :program:`python -m test -h`.
@@ -197,19 +197,19 @@ regression tests.
:ref:`controlled using environment variables <using-on-controlling-color>`.
-:mod:`test.support` --- Utilities for the Python test suite
-===========================================================
+:mod:`!test.support` --- Utilities for the Python test suite
+============================================================
.. module:: test.support
:synopsis: Support for Python's regression test suite.
-The :mod:`test.support` module provides support for Python's regression
+The :mod:`!test.support` module provides support for Python's regression
test suite.
.. note::
- :mod:`test.support` is not a public module. It is documented here to help
+ :mod:`!test.support` is not a public module. It is documented here to help
Python developers write tests. The API of this module is subject to change
without backwards compatibility concerns between releases.
@@ -230,7 +230,7 @@ This module defines the following exceptions:
function.
-The :mod:`test.support` module defines the following constants:
+The :mod:`!test.support` module defines the following constants:
.. data:: verbose
@@ -363,7 +363,7 @@ The :mod:`test.support` module defines the following constants:
.. data:: TEST_SUPPORT_DIR
- Set to the top level directory that contains :mod:`test.support`.
+ Set to the top level directory that contains :mod:`!test.support`.
.. data:: TEST_HOME_DIR
@@ -438,7 +438,7 @@ The :mod:`test.support` module defines the following constants:
Used to test mixed type comparison.
-The :mod:`test.support` module defines the following functions:
+The :mod:`!test.support` module defines the following functions:
.. function:: busy_retry(timeout, err_msg=None, /, *, error=True)
@@ -1043,7 +1043,7 @@ The :mod:`test.support` module defines the following functions:
.. versionadded:: 3.11
-The :mod:`test.support` module defines the following classes:
+The :mod:`!test.support` module defines the following classes:
.. class:: SuppressCrashReport()
@@ -1089,14 +1089,14 @@ The :mod:`test.support` module defines the following classes:
Try to match a single stored value (*dv*) with a supplied value (*v*).
-:mod:`test.support.socket_helper` --- Utilities for socket tests
-================================================================
+:mod:`!test.support.socket_helper` --- Utilities for socket tests
+=================================================================
.. module:: test.support.socket_helper
:synopsis: Support for socket tests.
-The :mod:`test.support.socket_helper` module provides support for socket tests.
+The :mod:`!test.support.socket_helper` module provides support for socket tests.
.. versionadded:: 3.9
@@ -1167,14 +1167,14 @@ The :mod:`test.support.socket_helper` module provides support for socket tests.
exceptions.
-:mod:`test.support.script_helper` --- Utilities for the Python execution tests
-==============================================================================
+:mod:`!test.support.script_helper` --- Utilities for the Python execution tests
+===============================================================================
.. module:: test.support.script_helper
:synopsis: Support for Python's script execution tests.
-The :mod:`test.support.script_helper` module provides support for Python's
+The :mod:`!test.support.script_helper` module provides support for Python's
script execution tests.
.. function:: interpreter_requires_environment()
@@ -1278,13 +1278,13 @@ script execution tests.
path and the archive name for the zip file.
-:mod:`test.support.bytecode_helper` --- Support tools for testing correct bytecode generation
-=============================================================================================
+:mod:`!test.support.bytecode_helper` --- Support tools for testing correct bytecode generation
+==============================================================================================
.. module:: test.support.bytecode_helper
:synopsis: Support tools for testing correct bytecode generation.
-The :mod:`test.support.bytecode_helper` module provides support for testing
+The :mod:`!test.support.bytecode_helper` module provides support for testing
and inspecting bytecode generation.
.. versionadded:: 3.9
@@ -1310,13 +1310,13 @@ The module defines the following class:
Throws :exc:`AssertionError` if *opname* is found.
-:mod:`test.support.threading_helper` --- Utilities for threading tests
-======================================================================
+:mod:`!test.support.threading_helper` --- Utilities for threading tests
+=======================================================================
.. module:: test.support.threading_helper
:synopsis: Support for threading tests.
-The :mod:`test.support.threading_helper` module provides support for threading tests.
+The :mod:`!test.support.threading_helper` module provides support for threading tests.
.. versionadded:: 3.10
@@ -1397,13 +1397,13 @@ The :mod:`test.support.threading_helper` module provides support for threading t
finished.
-:mod:`test.support.os_helper` --- Utilities for os tests
-========================================================================
+:mod:`!test.support.os_helper` --- Utilities for os tests
+=========================================================
.. module:: test.support.os_helper
:synopsis: Support for os tests.
-The :mod:`test.support.os_helper` module provides support for os tests.
+The :mod:`!test.support.os_helper` module provides support for os tests.
.. versionadded:: 3.10
@@ -1592,13 +1592,13 @@ The :mod:`test.support.os_helper` module provides support for os tests.
wrapped with a wait loop that checks for the existence of the file.
-:mod:`test.support.import_helper` --- Utilities for import tests
-================================================================
+:mod:`!test.support.import_helper` --- Utilities for import tests
+=================================================================
.. module:: test.support.import_helper
:synopsis: Support for import tests.
-The :mod:`test.support.import_helper` module provides support for import tests.
+The :mod:`!test.support.import_helper` module provides support for import tests.
.. versionadded:: 3.10
@@ -1706,13 +1706,13 @@ The :mod:`test.support.import_helper` module provides support for import tests.
will be reverted at the end of the block.
-:mod:`test.support.warnings_helper` --- Utilities for warnings tests
-====================================================================
+:mod:`!test.support.warnings_helper` --- Utilities for warnings tests
+=====================================================================
.. module:: test.support.warnings_helper
:synopsis: Support for warnings tests.
-The :mod:`test.support.warnings_helper` module provides support for warnings tests.
+The :mod:`!test.support.warnings_helper` module provides support for warnings tests.
.. versionadded:: 3.10
diff --git a/Doc/library/textwrap.rst b/Doc/library/textwrap.rst
index 3c96c0e9cc0..c9230f7d827 100644
--- a/Doc/library/textwrap.rst
+++ b/Doc/library/textwrap.rst
@@ -11,7 +11,7 @@
--------------
-The :mod:`textwrap` module provides some convenience functions,
+The :mod:`!textwrap` module provides some convenience functions,
as well as :class:`TextWrapper`, the class that does all the work.
If you're just wrapping or filling one or two text strings, the convenience
functions should be good enough; otherwise, you should use an instance of
diff --git a/Doc/library/threadsafety.rst b/Doc/library/threadsafety.rst
new file mode 100644
index 00000000000..5b5949d4eff
--- /dev/null
+++ b/Doc/library/threadsafety.rst
@@ -0,0 +1,262 @@
+.. _threadsafety:
+
+************************
+Thread Safety Guarantees
+************************
+
+This page documents thread-safety guarantees for built-in types in Python's
+free-threaded build. The guarantees described here apply when using Python with
+the :term:`GIL` disabled (free-threaded mode). When the GIL is enabled, most
+operations are implicitly serialized.
+
+For general guidance on writing thread-safe code in free-threaded Python, see
+:ref:`freethreading-python-howto`.
+
+
+.. _thread-safety-list:
+
+Thread safety for list objects
+==============================
+
+Reading a single element from a :class:`list` is
+:term:`atomic <atomic operation>`:
+
+.. code-block::
+ :class: good
+
+ lst[i] # list.__getitem__
+
+The following methods traverse the list and use :term:`atomic <atomic operation>`
+reads of each item to perform their function. That means that they may
+return results affected by concurrent modifications:
+
+.. code-block::
+ :class: maybe
+
+ item in lst
+ lst.index(item)
+ lst.count(item)
+
+All of the above operations avoid acquiring :term:`per-object locks
+<per-object lock>`. They do not block concurrent modifications. Other
+operations that hold a lock will not block these from observing intermediate
+states.
+
+All other operations from here on block using the :term:`per-object lock`.
+
+Writing a single item via ``lst[i] = x`` is safe to call from multiple
+threads and will not corrupt the list.
+
+The following operations return new objects and appear
+:term:`atomic <atomic operation>` to other threads:
+
+.. code-block::
+ :class: good
+
+ lst1 + lst2 # concatenates two lists into a new list
+ x * lst # repeats lst x times into a new list
+ lst.copy() # returns a shallow copy of the list
+
+The following methods that only operate on a single element with no shifting
+required are :term:`atomic <atomic operation>`:
+
+.. code-block::
+ :class: good
+
+ lst.append(x) # append to the end of the list, no shifting required
+ lst.pop() # pop element from the end of the list, no shifting required
+
+The :meth:`~list.clear` method is also :term:`atomic <atomic operation>`.
+Other threads cannot observe elements being removed.
+
+The :meth:`~list.sort` method is not :term:`atomic <atomic operation>`.
+Other threads cannot observe intermediate states during sorting, but the
+list appears empty for the duration of the sort.
+
+The following operations may allow :term:`lock-free` operations to observe
+intermediate states since they modify multiple elements in place:
+
+.. code-block::
+ :class: maybe
+
+ lst.insert(idx, item) # shifts elements
+ lst.pop(idx) # idx not at the end of the list, shifts elements
+ lst *= x # copies elements in place
+
+The :meth:`~list.remove` method may allow concurrent modifications since
+element comparison may execute arbitrary Python code (via
+:meth:`~object.__eq__`).
+
+:meth:`~list.extend` is safe to call from multiple threads. However, its
+guarantees depend on the iterable passed to it. If it is a :class:`list`, a
+:class:`tuple`, a :class:`set`, a :class:`frozenset`, a :class:`dict` or a
+:ref:`dictionary view object <dict-views>` (but not their subclasses), the
+``extend`` operation is safe from concurrent modifications to the iterable.
+Otherwise, an iterator is created which can be concurrently modified by
+another thread. The same applies to inplace concatenation of a list with
+other iterables when using ``lst += iterable``.
+
+Similarly, assigning to a list slice with ``lst[i:j] = iterable`` is safe
+to call from multiple threads, but ``iterable`` is only locked when it is
+also a :class:`list` (but not its subclasses).
+
+Operations that involve multiple accesses, as well as iteration, are never
+atomic. For example:
+
+.. code-block::
+ :class: bad
+
+ # NOT atomic: read-modify-write
+ lst[i] = lst[i] + 1
+
+ # NOT atomic: check-then-act
+ if lst:
+ item = lst.pop()
+
+ # NOT thread-safe: iteration while modifying
+ for item in lst:
+ process(item) # another thread may modify lst
+
+Consider external synchronization when sharing :class:`list` instances
+across threads.
+
+
+.. _thread-safety-dict:
+
+Thread safety for dict objects
+==============================
+
+Creating a dictionary with the :class:`dict` constructor is atomic when the
+argument to it is a :class:`dict` or a :class:`tuple`. When using the
+:meth:`dict.fromkeys` method, dictionary creation is atomic when the
+argument is a :class:`dict`, :class:`tuple`, :class:`set` or
+:class:`frozenset`.
+
+The following operations and functions are :term:`lock-free` and
+:term:`atomic <atomic operation>`.
+
+.. code-block::
+ :class: good
+
+ d[key] # dict.__getitem__
+ d.get(key) # dict.get
+ key in d # dict.__contains__
+ len(d) # dict.__len__
+
+All other operations from here on hold the :term:`per-object lock`.
+
+Writing or removing a single item is safe to call from multiple threads
+and will not corrupt the dictionary:
+
+.. code-block::
+ :class: good
+
+ d[key] = value # write
+ del d[key] # delete
+ d.pop(key) # remove and return
+ d.popitem() # remove and return last item
+ d.setdefault(key, v) # insert if missing
+
+These operations may compare keys using :meth:`~object.__eq__`, which can
+execute arbitrary Python code. During such comparisons, the dictionary may
+be modified by another thread. For built-in types like :class:`str`,
+:class:`int`, and :class:`float`, that implement :meth:`~object.__eq__` in C,
+the underlying lock is not released during comparisons and this is not a
+concern.
+
+The following operations return new objects and hold the :term:`per-object lock`
+for the duration of the operation:
+
+.. code-block::
+ :class: good
+
+ d.copy() # returns a shallow copy of the dictionary
+ d | other # merges two dicts into a new dict
+ d.keys() # returns a new dict_keys view object
+ d.values() # returns a new dict_values view object
+ d.items() # returns a new dict_items view object
+
+The :meth:`~dict.clear` method holds the lock for its duration. Other
+threads cannot observe elements being removed.
+
+The following operations lock both dictionaries. For :meth:`~dict.update`
+and ``|=``, this applies only when the other operand is a :class:`dict`
+that uses the standard dict iterator (but not subclasses that override
+iteration). For equality comparison, this applies to :class:`dict` and
+its subclasses:
+
+.. code-block::
+ :class: good
+
+ d.update(other_dict) # both locked when other_dict is a dict
+ d |= other_dict # both locked when other_dict is a dict
+ d == other_dict # both locked for dict and subclasses
+
+All comparison operations also compare values using :meth:`~object.__eq__`,
+so for non-built-in types the lock may be released during comparison.
+
+:meth:`~dict.fromkeys` locks both the new dictionary and the iterable
+when the iterable is exactly a :class:`dict`, :class:`set`, or
+:class:`frozenset` (not subclasses):
+
+.. code-block::
+ :class: good
+
+ dict.fromkeys(a_dict) # locks both
+ dict.fromkeys(a_set) # locks both
+ dict.fromkeys(a_frozenset) # locks both
+
+When updating from a non-dict iterable, only the target dictionary is
+locked. The iterable may be concurrently modified by another thread:
+
+.. code-block::
+ :class: maybe
+
+ d.update(iterable) # iterable is not a dict: only d locked
+ d |= iterable # iterable is not a dict: only d locked
+ dict.fromkeys(iterable) # iterable is not a dict/set/frozenset: only result locked
+
+Operations that involve multiple accesses, as well as iteration, are never
+atomic:
+
+.. code-block::
+ :class: bad
+
+ # NOT atomic: read-modify-write
+ d[key] = d[key] + 1
+
+ # NOT atomic: check-then-act (TOCTOU)
+ if key in d:
+ del d[key]
+
+ # NOT thread-safe: iteration while modifying
+ for key, value in d.items():
+ process(key) # another thread may modify d
+
+To avoid time-of-check to time-of-use (TOCTOU) issues, use atomic
+operations or handle exceptions:
+
+.. code-block::
+ :class: good
+
+ # Use pop() with default instead of check-then-delete
+ d.pop(key, None)
+
+ # Or handle the exception
+ try:
+ del d[key]
+ except KeyError:
+ pass
+
+To safely iterate over a dictionary that may be modified by another
+thread, iterate over a copy:
+
+.. code-block::
+ :class: good
+
+ # Make a copy to iterate safely
+ for key, value in d.copy().items():
+ process(key)
+
+Consider external synchronization when sharing :class:`dict` instances
+across threads.
diff --git a/Doc/library/timeit.rst b/Doc/library/timeit.rst
index 548a3ee0540..bc12061a2ae 100644
--- a/Doc/library/timeit.rst
+++ b/Doc/library/timeit.rst
@@ -355,7 +355,7 @@ to test for missing and present object attributes:
0.08588060699912603
-To give the :mod:`timeit` module access to functions you define, you can pass a
+To give the :mod:`!timeit` module access to functions you define, you can pass a
*setup* parameter which contains an import statement::
def test():
diff --git a/Doc/library/tkinter.colorchooser.rst b/Doc/library/tkinter.colorchooser.rst
index df2b324fd5d..73f8f76a210 100644
--- a/Doc/library/tkinter.colorchooser.rst
+++ b/Doc/library/tkinter.colorchooser.rst
@@ -2,14 +2,13 @@
======================================================
.. module:: tkinter.colorchooser
- :platform: Tk
:synopsis: Color choosing dialog
**Source code:** :source:`Lib/tkinter/colorchooser.py`
--------------
-The :mod:`tkinter.colorchooser` module provides the :class:`Chooser` class
+The :mod:`!tkinter.colorchooser` module provides the :class:`Chooser` class
as an interface to the native color picker dialog. ``Chooser`` implements
a modal color choosing dialog window. The ``Chooser`` class inherits from
the :class:`~tkinter.commondialog.Dialog` class.
diff --git a/Doc/library/tkinter.dnd.rst b/Doc/library/tkinter.dnd.rst
index 62298d96c26..48d16ccb204 100644
--- a/Doc/library/tkinter.dnd.rst
+++ b/Doc/library/tkinter.dnd.rst
@@ -2,7 +2,6 @@
=============================================
.. module:: tkinter.dnd
- :platform: Tk
:synopsis: Tkinter drag-and-drop interface
**Source code:** :source:`Lib/tkinter/dnd.py`
@@ -12,7 +11,7 @@
.. note:: This is experimental and due to be deprecated when it is replaced
with the Tk DND.
-The :mod:`tkinter.dnd` module provides drag-and-drop support for objects within
+The :mod:`!tkinter.dnd` module provides drag-and-drop support for objects within
a single application, within the same window or between windows. To enable an
object to be dragged, you must create an event binding for it that starts the
drag-and-drop process. Typically, you bind a ButtonPress event to a callback
diff --git a/Doc/library/tkinter.font.rst b/Doc/library/tkinter.font.rst
index ed01bd5f483..9eecb803c3a 100644
--- a/Doc/library/tkinter.font.rst
+++ b/Doc/library/tkinter.font.rst
@@ -2,14 +2,13 @@
=============================================
.. module:: tkinter.font
- :platform: Tk
:synopsis: Tkinter font-wrapping class
**Source code:** :source:`Lib/tkinter/font.py`
--------------
-The :mod:`tkinter.font` module provides the :class:`Font` class for creating
+The :mod:`!tkinter.font` module provides the :class:`Font` class for creating
and using named fonts.
The different font weights and slants are:
diff --git a/Doc/library/tkinter.messagebox.rst b/Doc/library/tkinter.messagebox.rst
index 0dc9632ca73..2a69d282638 100644
--- a/Doc/library/tkinter.messagebox.rst
+++ b/Doc/library/tkinter.messagebox.rst
@@ -2,14 +2,13 @@
======================================================
.. module:: tkinter.messagebox
- :platform: Tk
:synopsis: Various types of alert dialogs
**Source code:** :source:`Lib/tkinter/messagebox.py`
--------------
-The :mod:`tkinter.messagebox` module provides a template base class as well as
+The :mod:`!tkinter.messagebox` module provides a template base class as well as
a variety of convenience methods for commonly used configurations. The message
boxes are modal and will return a subset of (``True``, ``False``, ``None``,
:data:`OK`, :data:`CANCEL`, :data:`YES`, :data:`NO`) based on
diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst
index 07ce8c40577..805f619eab8 100644
--- a/Doc/library/tkinter.rst
+++ b/Doc/library/tkinter.rst
@@ -10,12 +10,12 @@
--------------
-The :mod:`tkinter` package ("Tk interface") is the standard Python interface to
-the Tcl/Tk GUI toolkit. Both Tk and :mod:`tkinter` are available on most Unix
+The :mod:`!tkinter` package ("Tk interface") is the standard Python interface to
+the Tcl/Tk GUI toolkit. Both Tk and :mod:`!tkinter` are available on most Unix
platforms, including macOS, as well as on Windows systems.
Running ``python -m tkinter`` from the command line should open a window
-demonstrating a simple Tk interface, letting you know that :mod:`tkinter` is
+demonstrating a simple Tk interface, letting you know that :mod:`!tkinter` is
properly installed on your system, and also showing what version of Tcl/Tk is
installed, so you can read the Tcl/Tk documentation specific to that version.
@@ -108,7 +108,7 @@ Internally, Tk and Ttk use facilities of the underlying operating system,
i.e., Xlib on Unix/X11, Cocoa on macOS, GDI on Windows.
When your Python application uses a class in Tkinter, e.g., to create a widget,
-the :mod:`tkinter` module first assembles a Tcl/Tk command string. It passes that
+the :mod:`!tkinter` module first assembles a Tcl/Tk command string. It passes that
Tcl command string to an internal :mod:`_tkinter` binary module, which then
calls the Tcl interpreter to evaluate it. The Tcl interpreter will then call into the
Tk and/or Ttk packages, which will in turn make calls to Xlib, Cocoa, or GDI.
@@ -118,7 +118,7 @@ Tkinter Modules
---------------
Support for Tkinter is spread across several modules. Most applications will need the
-main :mod:`tkinter` module, as well as the :mod:`tkinter.ttk` module, which provides
+main :mod:`!tkinter` module, as well as the :mod:`tkinter.ttk` module, which provides
the modern themed widget set and API::
@@ -204,7 +204,7 @@ the modern themed widget set and API::
The modules that provide Tk support include:
-:mod:`tkinter`
+:mod:`!tkinter`
Main Tkinter module.
:mod:`tkinter.colorchooser`
@@ -230,7 +230,7 @@ The modules that provide Tk support include:
:mod:`tkinter.ttk`
Themed widget set introduced in Tk 8.5, providing modern alternatives
- for many of the classic widgets in the main :mod:`tkinter` module.
+ for many of the classic widgets in the main :mod:`!tkinter` module.
Additional modules:
@@ -239,22 +239,22 @@ Additional modules:
:mod:`_tkinter`
A binary module that contains the low-level interface to Tcl/Tk.
- It is automatically imported by the main :mod:`tkinter` module,
+ It is automatically imported by the main :mod:`!tkinter` module,
and should never be used directly by application programmers.
It is usually a shared library (or DLL), but might in some cases be
statically linked with the Python interpreter.
:mod:`idlelib`
Python's Integrated Development and Learning Environment (IDLE). Based
- on :mod:`tkinter`.
+ on :mod:`!tkinter`.
:mod:`tkinter.constants`
Symbolic constants that can be used in place of strings when passing
various parameters to Tkinter calls. Automatically imported by the
- main :mod:`tkinter` module.
+ main :mod:`!tkinter` module.
:mod:`tkinter.dnd`
- (experimental) Drag-and-drop support for :mod:`tkinter`. This will
+ (experimental) Drag-and-drop support for :mod:`!tkinter`. This will
become deprecated when it is replaced with the Tk DND.
:mod:`turtle`
@@ -504,7 +504,7 @@ documentation for all of these in the
Threading model
---------------
-Python and Tcl/Tk have very different threading models, which :mod:`tkinter`
+Python and Tcl/Tk have very different threading models, which :mod:`!tkinter`
tries to bridge. If you use threads, you may need to be aware of this.
A Python interpreter may have many threads associated with it. In Tcl, multiple
@@ -512,9 +512,9 @@ threads can be created, but each thread has a separate Tcl interpreter instance
associated with it. Threads can also create more than one interpreter instance,
though each interpreter instance can be used only by the one thread that created it.
-Each :class:`Tk` object created by :mod:`tkinter` contains a Tcl interpreter.
+Each :class:`Tk` object created by :mod:`!tkinter` contains a Tcl interpreter.
It also keeps track of which thread created that interpreter. Calls to
-:mod:`tkinter` can be made from any Python thread. Internally, if a call comes
+:mod:`!tkinter` can be made from any Python thread. Internally, if a call comes
from a thread other than the one that created the :class:`Tk` object, an event
is posted to the interpreter's event queue, and when executed, the result is
returned to the calling Python thread.
@@ -529,17 +529,17 @@ toolkits where the GUI runs in a completely separate thread from all application
code including event handlers.
If the Tcl interpreter is not running the event loop and processing events, any
-:mod:`tkinter` calls made from threads other than the one running the Tcl
+:mod:`!tkinter` calls made from threads other than the one running the Tcl
interpreter will fail.
A number of special cases exist:
* Tcl/Tk libraries can be built so they are not thread-aware. In this case,
- :mod:`tkinter` calls the library from the originating Python thread, even
+ :mod:`!tkinter` calls the library from the originating Python thread, even
if this is different than the thread that created the Tcl interpreter. A global
lock ensures only one call occurs at a time.
-* While :mod:`tkinter` allows you to create more than one instance of a :class:`Tk`
+* While :mod:`!tkinter` allows you to create more than one instance of a :class:`Tk`
object (with its own interpreter), all interpreters that are part of the same
thread share a common event queue, which gets ugly fast. In practice, don't create
more than one instance of :class:`Tk` at a time. Otherwise, it's best to create
@@ -550,7 +550,7 @@ A number of special cases exist:
or abandon the event loop entirely. If you're doing anything tricky when it comes
to events or threads, be aware of these possibilities.
-* There are a few select :mod:`tkinter` functions that presently work only when
+* There are a few select :mod:`!tkinter` functions that presently work only when
called from the thread that created the Tcl interpreter.
@@ -700,11 +700,11 @@ options are ``variable``, ``textvariable``, ``onvalue``, ``offvalue``, and
``value``. This connection works both ways: if the variable changes for any
reason, the widget it's connected to will be updated to reflect the new value.
-Unfortunately, in the current implementation of :mod:`tkinter` it is not
+Unfortunately, in the current implementation of :mod:`!tkinter` it is not
possible to hand over an arbitrary Python variable to a widget through a
``variable`` or ``textvariable`` option. The only kinds of variables for which
this works are variables that are subclassed from a class called Variable,
-defined in :mod:`tkinter`.
+defined in :mod:`!tkinter`.
There are many useful subclasses of Variable already defined:
:class:`StringVar`, :class:`IntVar`, :class:`DoubleVar`, and
@@ -752,7 +752,7 @@ The Window Manager
In Tk, there is a utility command, ``wm``, for interacting with the window
manager. Options to the ``wm`` command allow you to control things like titles,
-placement, icon bitmaps, and the like. In :mod:`tkinter`, these commands have
+placement, icon bitmaps, and the like. In :mod:`!tkinter`, these commands have
been implemented as methods on the :class:`Wm` class. Toplevel widgets are
subclassed from the :class:`Wm` class, and so can call the :class:`Wm` methods
directly.
@@ -934,7 +934,7 @@ Entry widget, or to particular menu items in a Menu widget.
Entry widget indexes (index, view index, etc.)
Entry widgets have options that refer to character positions in the text being
- displayed. You can use these :mod:`tkinter` functions to access these special
+ displayed. You can use these :mod:`!tkinter` functions to access these special
points in text widgets:
Text widget indexes
diff --git a/Doc/library/tkinter.scrolledtext.rst b/Doc/library/tkinter.scrolledtext.rst
index 763e24929d7..6c3c74afd47 100644
--- a/Doc/library/tkinter.scrolledtext.rst
+++ b/Doc/library/tkinter.scrolledtext.rst
@@ -2,7 +2,6 @@
=====================================================
.. module:: tkinter.scrolledtext
- :platform: Tk
:synopsis: Text widget with a vertical scroll bar.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
@@ -11,7 +10,7 @@
--------------
-The :mod:`tkinter.scrolledtext` module provides a class of the same name which
+The :mod:`!tkinter.scrolledtext` module provides a class of the same name which
implements a basic text widget which has a vertical scroll bar configured to do
the "right thing." Using the :class:`ScrolledText` class is a lot easier than
setting up a text widget and scroll bar directly.
diff --git a/Doc/library/tkinter.ttk.rst b/Doc/library/tkinter.ttk.rst
index 628e9f945ac..7db57564699 100644
--- a/Doc/library/tkinter.ttk.rst
+++ b/Doc/library/tkinter.ttk.rst
@@ -12,12 +12,12 @@
--------------
-The :mod:`tkinter.ttk` module provides access to the Tk themed widget set,
+The :mod:`!tkinter.ttk` module provides access to the Tk themed widget set,
introduced in Tk 8.5. It provides additional benefits including anti-aliased font
rendering under X11 and window transparency (requiring a composition
window manager on X11).
-The basic idea for :mod:`tkinter.ttk` is to separate, to the extent possible,
+The basic idea for :mod:`!tkinter.ttk` is to separate, to the extent possible,
the code implementing a widget's behavior from the code implementing its
appearance.
@@ -40,7 +40,7 @@ To override the basic Tk widgets, the import should follow the Tk import::
from tkinter import *
from tkinter.ttk import *
-That code causes several :mod:`tkinter.ttk` widgets (:class:`Button`,
+That code causes several :mod:`!tkinter.ttk` widgets (:class:`Button`,
:class:`Checkbutton`, :class:`Entry`, :class:`Frame`, :class:`Label`,
:class:`LabelFrame`, :class:`Menubutton`, :class:`PanedWindow`,
:class:`Radiobutton`, :class:`Scale` and :class:`Scrollbar`) to
diff --git a/Doc/library/token.rst b/Doc/library/token.rst
index c228006d4c1..fb826f5465b 100644
--- a/Doc/library/token.rst
+++ b/Doc/library/token.rst
@@ -50,8 +50,7 @@ The token constants are:
.. data:: NAME
- Token value that indicates an :ref:`identifier <identifiers>`.
- Note that keywords are also initially tokenized as ``NAME`` tokens.
+ Token value that indicates an :ref:`identifier or keyword <identifiers>`.
.. data:: NUMBER
diff --git a/Doc/library/tokenize.rst b/Doc/library/tokenize.rst
index b80917eae66..cf638f0b095 100644
--- a/Doc/library/tokenize.rst
+++ b/Doc/library/tokenize.rst
@@ -11,7 +11,7 @@
--------------
-The :mod:`tokenize` module provides a lexical scanner for Python source code,
+The :mod:`!tokenize` module provides a lexical scanner for Python source code,
implemented in Python. The scanner in this module returns comments as tokens
as well, making it useful for implementing "pretty-printers", including
colorizers for on-screen displays.
@@ -78,7 +78,7 @@ The primary entry point is a :term:`generator`:
:func:`.tokenize`. It does not yield an :data:`~token.ENCODING` token.
All constants from the :mod:`token` module are also exported from
-:mod:`tokenize`.
+:mod:`!tokenize`.
Another function is provided to reverse the tokenization process. This is
useful for creating tools that tokenize a script, modify the token stream, and
@@ -154,7 +154,7 @@ Command-Line Usage
.. versionadded:: 3.3
-The :mod:`tokenize` module can be executed as a script from the command line.
+The :mod:`!tokenize` module can be executed as a script from the command line.
It is as simple as:
.. code-block:: sh
diff --git a/Doc/library/trace.rst b/Doc/library/trace.rst
index cae94ea08e1..57b8fa29eb3 100644
--- a/Doc/library/trace.rst
+++ b/Doc/library/trace.rst
@@ -8,7 +8,7 @@
--------------
-The :mod:`trace` module allows you to trace program execution, generate
+The :mod:`!trace` module allows you to trace program execution, generate
annotated statement coverage listings, print caller/callee relationships and
list functions executed during a program run. It can be used in another program
or from the command line.
@@ -24,7 +24,7 @@ or from the command line.
Command-Line Usage
------------------
-The :mod:`trace` module can be invoked from the command line. It can be as
+The :mod:`!trace` module can be invoked from the command line. It can be as
simple as ::
python -m trace --count -C . somefile.py ...
@@ -43,13 +43,13 @@ all Python modules imported during the execution into the current directory.
Display the version of the module and exit.
.. versionadded:: 3.8
- Added ``--module`` option that allows to run an executable module.
+ Added ``--module`` option that allows running an executable module.
Main options
^^^^^^^^^^^^
At least one of the following options must be specified when invoking
-:mod:`trace`. The :option:`--listfuncs <-l>` option is mutually exclusive with
+:mod:`!trace`. The :option:`--listfuncs <-l>` option is mutually exclusive with
the :option:`--trace <-t>` and :option:`--count <-c>` options. When
:option:`--listfuncs <-l>` is provided, neither :option:`--count <-c>` nor
:option:`--trace <-t>` are accepted, and vice versa.
diff --git a/Doc/library/tracemalloc.rst b/Doc/library/tracemalloc.rst
index 2370d927292..0fa70389f1f 100644
--- a/Doc/library/tracemalloc.rst
+++ b/Doc/library/tracemalloc.rst
@@ -307,7 +307,7 @@ Functions
.. function:: get_object_traceback(obj)
Get the traceback where the Python object *obj* was allocated.
- Return a :class:`Traceback` instance, or ``None`` if the :mod:`tracemalloc`
+ Return a :class:`Traceback` instance, or ``None`` if the :mod:`!tracemalloc`
module is not tracing memory allocations or did not trace the allocation of
the object.
@@ -318,7 +318,7 @@ Functions
Get the maximum number of frames stored in the traceback of a trace.
- The :mod:`tracemalloc` module must be tracing memory allocations to
+ The :mod:`!tracemalloc` module must be tracing memory allocations to
get the limit, otherwise an exception is raised.
The limit is set by the :func:`start` function.
@@ -327,15 +327,15 @@ Functions
.. function:: get_traced_memory()
Get the current size and peak size of memory blocks traced by the
- :mod:`tracemalloc` module as a tuple: ``(current: int, peak: int)``.
+ :mod:`!tracemalloc` module as a tuple: ``(current: int, peak: int)``.
.. function:: reset_peak()
- Set the peak size of memory blocks traced by the :mod:`tracemalloc` module
+ Set the peak size of memory blocks traced by the :mod:`!tracemalloc` module
to the current size.
- Do nothing if the :mod:`tracemalloc` module is not tracing memory
+ Do nothing if the :mod:`!tracemalloc` module is not tracing memory
allocations.
This function only modifies the recorded peak size, and does not modify or
@@ -350,14 +350,14 @@ Functions
.. function:: get_tracemalloc_memory()
- Get the memory usage in bytes of the :mod:`tracemalloc` module used to store
+ Get the memory usage in bytes of the :mod:`!tracemalloc` module used to store
traces of memory blocks.
Return an :class:`int`.
.. function:: is_tracing()
- ``True`` if the :mod:`tracemalloc` module is tracing Python memory
+ ``True`` if the :mod:`!tracemalloc` module is tracing Python memory
allocations, ``False`` otherwise.
See also :func:`start` and :func:`stop` functions.
@@ -378,8 +378,8 @@ Functions
:meth:`Snapshot.compare_to` and :meth:`Snapshot.statistics` methods.
Storing more frames increases the memory and CPU overhead of the
- :mod:`tracemalloc` module. Use the :func:`get_tracemalloc_memory` function
- to measure how much memory is used by the :mod:`tracemalloc` module.
+ :mod:`!tracemalloc` module. Use the :func:`get_tracemalloc_memory` function
+ to measure how much memory is used by the :mod:`!tracemalloc` module.
The :envvar:`PYTHONTRACEMALLOC` environment variable
(``PYTHONTRACEMALLOC=NFRAME``) and the :option:`-X` ``tracemalloc=NFRAME``
@@ -408,12 +408,12 @@ Functions
:class:`Snapshot` instance.
The snapshot does not include memory blocks allocated before the
- :mod:`tracemalloc` module started to trace memory allocations.
+ :mod:`!tracemalloc` module started to trace memory allocations.
Tracebacks of traces are limited to :func:`get_traceback_limit` frames. Use
the *nframe* parameter of the :func:`start` function to store more frames.
- The :mod:`tracemalloc` module must be tracing memory allocations to take a
+ The :mod:`!tracemalloc` module must be tracing memory allocations to take a
snapshot, see the :func:`start` function.
See also the :func:`get_object_traceback` function.
@@ -457,7 +457,7 @@ Filter
* ``Filter(True, subprocess.__file__)`` only includes traces of the
:mod:`subprocess` module
* ``Filter(False, tracemalloc.__file__)`` excludes traces of the
- :mod:`tracemalloc` module
+ :mod:`!tracemalloc` module
* ``Filter(False, "<unknown>")`` excludes empty tracebacks
@@ -589,7 +589,7 @@ Snapshot
If *cumulative* is ``True``, cumulate size and count of memory blocks of
all frames of the traceback of a trace, not only the most recent frame.
- The cumulative mode can only be used with *key_type* equals to
+ The cumulative mode can only be used with *key_type* equal to
``'filename'`` and ``'lineno'``.
The result is sorted from the biggest to the smallest by:
@@ -720,11 +720,10 @@ Traceback
When a snapshot is taken, tracebacks of traces are limited to
:func:`get_traceback_limit` frames. See the :func:`take_snapshot` function.
The original number of frames of the traceback is stored in the
- :attr:`Traceback.total_nframe` attribute. That allows to know if a traceback
+ :attr:`Traceback.total_nframe` attribute. That allows one to know if a traceback
has been truncated by the traceback limit.
- The :attr:`Trace.traceback` attribute is an instance of :class:`Traceback`
- instance.
+ The :attr:`Trace.traceback` attribute is a :class:`Traceback` instance.
.. versionchanged:: 3.7
Frames are now sorted from the oldest to the most recent, instead of most recent to oldest.
diff --git a/Doc/library/tty.rst b/Doc/library/tty.rst
index 37778bf20bd..fe46be8b321 100644
--- a/Doc/library/tty.rst
+++ b/Doc/library/tty.rst
@@ -2,7 +2,6 @@
==========================================
.. module:: tty
- :platform: Unix
:synopsis: Utility functions that perform common terminal control operations.
.. moduleauthor:: Steen Lumholt
@@ -12,14 +11,14 @@
--------------
-The :mod:`tty` module defines functions for putting the tty into cbreak and raw
+The :mod:`!tty` module defines functions for putting the tty into cbreak and raw
modes.
.. availability:: Unix.
Because it requires the :mod:`termios` module, it will work only on Unix.
-The :mod:`tty` module defines the following functions:
+The :mod:`!tty` module defines the following functions:
.. function:: cfmakeraw(mode)
diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst
index 95a57c57e71..bfe93bc253d 100644
--- a/Doc/library/turtle.rst
+++ b/Doc/library/turtle.rst
@@ -2248,7 +2248,7 @@ Settings and special methods
Set turtle mode ("standard", "logo" or "world") and perform reset. If mode
is not given, current mode is returned.
- Mode "standard" is compatible with old :mod:`turtle`. Mode "logo" is
+ Mode "standard" is compatible with old :mod:`!turtle`. Mode "logo" is
compatible with most Logo turtle graphics. Mode "world" uses user-defined
"world coordinates". **Attention**: in this mode angles appear distorted if
``x/y`` unit-ratio doesn't equal 1.
@@ -2689,7 +2689,7 @@ Screen and Turtle.
Python script :file:`{filename}.py`. It is intended to serve as a template
for translation of the docstrings into different languages.
-If you (or your students) want to use :mod:`turtle` with online help in your
+If you (or your students) want to use :mod:`!turtle` with online help in your
native language, you have to translate the docstrings and save the resulting
file as e.g. :file:`turtle_docstringdict_german.py`.
@@ -2752,7 +2752,7 @@ Short explanation of selected entries:
auto``.
- If you set e.g. ``language = italian`` the docstringdict
:file:`turtle_docstringdict_italian.py` will be loaded at import time (if
- present on the import path, e.g. in the same directory as :mod:`turtle`).
+ present on the import path, e.g. in the same directory as :mod:`!turtle`).
- The entries *exampleturtle* and *examplescreen* define the names of these
objects as they occur in the docstrings. The transformation of
method-docstrings to function-docstrings will delete these names from the
@@ -2761,7 +2761,7 @@ Short explanation of selected entries:
switch ("no subprocess"). This will prevent :func:`exitonclick` to enter the
mainloop.
-There can be a :file:`turtle.cfg` file in the directory where :mod:`turtle` is
+There can be a :file:`turtle.cfg` file in the directory where :mod:`!turtle` is
stored and an additional one in the current working directory. The latter will
override the settings of the first one.
@@ -2770,13 +2770,13 @@ study it as an example and see its effects when running the demos (preferably
not from within the demo-viewer).
-:mod:`turtledemo` --- Demo scripts
-==================================
+:mod:`!turtledemo` --- Demo scripts
+===================================
.. module:: turtledemo
:synopsis: A viewer for example turtle scripts
-The :mod:`turtledemo` package includes a set of demo scripts. These
+The :mod:`!turtledemo` package includes a set of demo scripts. These
scripts can be run and viewed using the supplied demo viewer as follows::
python -m turtledemo
@@ -2785,11 +2785,11 @@ Alternatively, you can run the demo scripts individually. For example, ::
python -m turtledemo.bytedesign
-The :mod:`turtledemo` package directory contains:
+The :mod:`!turtledemo` package directory contains:
- A demo viewer :file:`__main__.py` which can be used to view the sourcecode
of the scripts and run them at the same time.
-- Multiple scripts demonstrating different features of the :mod:`turtle`
+- Multiple scripts demonstrating different features of the :mod:`!turtle`
module. Examples can be accessed via the Examples menu. They can also
be run standalone.
- A :file:`turtle.cfg` file which serves as an example of how to write
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 886b230d171..a2625ab2a37 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -813,7 +813,7 @@ For example, this conforms to :pep:`484`::
def __len__(self) -> int: ...
def __iter__(self) -> Iterator[int]: ...
-:pep:`544` allows to solve this problem by allowing users to write
+:pep:`544` solves this problem by allowing users to write
the above code without explicit base classes in the class definition,
allowing ``Bucket`` to be implicitly considered a subtype of both ``Sized``
and ``Iterable[int]`` by static type checkers. This is known as
@@ -3347,8 +3347,8 @@ Introspection helpers
.. function:: get_type_hints(obj, globalns=None, localns=None, include_extras=False)
- Return a dictionary containing type hints for a function, method, module
- or class object.
+ Return a dictionary containing type hints for a function, method, module,
+ class object, or other callable object.
This is often the same as ``obj.__annotations__``, but this function makes
the following changes to the annotations dictionary:
@@ -3389,6 +3389,13 @@ Introspection helpers
:ref:`type aliases <type-aliases>` that include forward references,
or with names imported under :data:`if TYPE_CHECKING <TYPE_CHECKING>`.
+ .. note::
+
+ Calling :func:`get_type_hints` on an instance is not supported.
+ To retrieve annotations for an instance, call
+ :func:`get_type_hints` on the instance's class instead
+ (for example, ``get_type_hints(type(obj))``).
+
.. versionchanged:: 3.9
Added ``include_extras`` parameter as part of :pep:`593`.
See the documentation on :data:`Annotated` for more information.
@@ -3398,6 +3405,11 @@ Introspection helpers
if a default value equal to ``None`` was set.
Now the annotation is returned unchanged.
+ .. versionchanged:: 3.14
+ Calling :func:`get_type_hints` on instances is no longer supported.
+ Some instances were accepted in earlier versions as an undocumented
+ implementation detail.
+
.. function:: get_origin(tp)
Get the unsubscripted version of a type: for a typing object of the form
diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index 91f90a0726a..549b0499788 100644
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -13,11 +13,11 @@
--------------
-:mod:`unittest.mock` is a library for testing in Python. It allows you to
+:mod:`!unittest.mock` is a library for testing in Python. It allows you to
replace parts of your system under test with mock objects and make assertions
about how they have been used.
-:mod:`unittest.mock` provides a core :class:`Mock` class removing the need to
+:mod:`!unittest.mock` provides a core :class:`Mock` class removing the need to
create a host of stubs throughout your test suite. After performing an
action, you can make assertions about which methods / attributes were used
and arguments they were called with. You can also specify return values and
@@ -33,7 +33,7 @@ Mock is designed for use with :mod:`unittest` and
is based on the 'action -> assertion' pattern instead of 'record -> replay'
used by many mocking frameworks.
-There is a backport of :mod:`unittest.mock` for earlier versions of Python,
+There is a backport of :mod:`!unittest.mock` for earlier versions of Python,
available as :pypi:`mock` on PyPI.
@@ -2638,7 +2638,7 @@ unit tests. Testing everything in isolation is all fine and dandy, but if you
don't test how your units are "wired together" there is still lots of room
for bugs that tests might have caught.
-:mod:`unittest.mock` already provides a feature to help with this, called speccing. If you
+:mod:`!unittest.mock` already provides a feature to help with this, called speccing. If you
use a class or instance as the :attr:`!spec` for a mock then you can only access
attributes on the mock that exist on the real class:
diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
index d2ac5eedbbc..67ae1d91573 100644
--- a/Doc/library/unittest.rst
+++ b/Doc/library/unittest.rst
@@ -16,13 +16,13 @@
(If you are already familiar with the basic concepts of testing, you might want
to skip to :ref:`the list of assert methods <assert-methods>`.)
-The :mod:`unittest` unit testing framework was originally inspired by JUnit
+The :mod:`!unittest` unit testing framework was originally inspired by JUnit
and has a similar flavor as major unit testing frameworks in other
languages. It supports test automation, sharing of setup and shutdown code
for tests, aggregation of tests into collections, and independence of the
tests from the reporting framework.
-To achieve this, :mod:`unittest` supports some important concepts in an
+To achieve this, :mod:`!unittest` supports some important concepts in an
object-oriented way:
test fixture
@@ -33,7 +33,7 @@ test fixture
test case
A :dfn:`test case` is the individual unit of testing. It checks for a specific
- response to a particular set of inputs. :mod:`unittest` provides a base class,
+ response to a particular set of inputs. :mod:`!unittest` provides a base class,
:class:`TestCase`, which may be used to create new test cases.
test suite
@@ -53,7 +53,7 @@ test runner
`Simple Smalltalk Testing: With Patterns <https://web.archive.org/web/20150315073817/http://www.xprogramming.com/testfram.htm>`_
Kent Beck's original paper on testing frameworks using the pattern shared
- by :mod:`unittest`.
+ by :mod:`!unittest`.
`pytest <https://docs.pytest.org/>`_
Third-party unittest framework with a lighter-weight syntax for writing
@@ -81,7 +81,7 @@ test runner
Basic example
-------------
-The :mod:`unittest` module provides a rich set of tools for constructing and
+The :mod:`!unittest` module provides a rich set of tools for constructing and
running tests. This section demonstrates that a small subset of the tools
suffice to meet the needs of most users.
@@ -147,7 +147,7 @@ to enable a higher level of verbosity, and produce the following output::
OK
-The above examples show the most commonly used :mod:`unittest` features which
+The above examples show the most commonly used :mod:`!unittest` features which
are sufficient to meet many everyday testing needs. The remainder of the
documentation explores the full feature set from first principles.
@@ -365,7 +365,7 @@ Organizing test code
--------------------
The basic building blocks of unit testing are :dfn:`test cases` --- single
-scenarios that must be set up and checked for correctness. In :mod:`unittest`,
+scenarios that must be set up and checked for correctness. In :mod:`!unittest`,
test cases are represented by :class:`unittest.TestCase` instances.
To make your own test cases you must write subclasses of
:class:`TestCase` or use :class:`FunctionTestCase`.
@@ -387,7 +387,7 @@ testing code::
Note that in order to test something, we use one of the :ref:`assert\* methods <assert-methods>`
provided by the :class:`TestCase` base class. If the test fails, an
-exception will be raised with an explanatory message, and :mod:`unittest`
+exception will be raised with an explanatory message, and :mod:`!unittest`
will identify the test case as a :dfn:`failure`. Any other exceptions will be
treated as :dfn:`errors`.
@@ -442,8 +442,8 @@ test fixture used to execute each individual test method. Thus
will be called once per test.
It is recommended that you use TestCase implementations to group tests together
-according to the features they test. :mod:`unittest` provides a mechanism for
-this: the :dfn:`test suite`, represented by :mod:`unittest`'s
+according to the features they test. :mod:`!unittest` provides a mechanism for
+this: the :dfn:`test suite`, represented by :mod:`!unittest`'s
:class:`TestSuite` class. In most cases, calling :func:`unittest.main` will do
the right thing and collect all the module's test cases for you and execute
them.
@@ -489,10 +489,10 @@ Re-using old test code
----------------------
Some users will find that they have existing test code that they would like to
-run from :mod:`unittest`, without converting every old test function to a
+run from :mod:`!unittest`, without converting every old test function to a
:class:`TestCase` subclass.
-For this reason, :mod:`unittest` provides a :class:`FunctionTestCase` class.
+For this reason, :mod:`!unittest` provides a :class:`FunctionTestCase` class.
This subclass of :class:`TestCase` can be used to wrap an existing test
function. Set-up and tear-down functions can also be provided.
@@ -513,7 +513,7 @@ set-up and tear-down methods::
.. note::
Even though :class:`FunctionTestCase` can be used to quickly convert an
- existing test base over to a :mod:`unittest`\ -based system, this approach is
+ existing test base over to a :mod:`!unittest`\ -based system, this approach is
not recommended. Taking the time to set up proper :class:`TestCase`
subclasses will make future test refactorings infinitely easier.
@@ -709,7 +709,7 @@ wouldn't be displayed::
Classes and functions
---------------------
-This section describes in depth the API of :mod:`unittest`.
+This section describes in depth the API of :mod:`!unittest`.
.. _testcase-objects:
@@ -720,7 +720,7 @@ Test cases
.. class:: TestCase(methodName='runTest')
Instances of the :class:`TestCase` class represent the logical test units
- in the :mod:`unittest` universe. This class is intended to be used as a base
+ in the :mod:`!unittest` universe. This class is intended to be used as a base
class, with specific tests being implemented by concrete subclasses. This class
implements the interface needed by the test runner to allow it to drive the
tests, and methods that the test code can use to check for and report various
@@ -1727,7 +1727,7 @@ Test cases
allows the test runner to drive the test, but does not provide the methods
which test code can use to check and report errors. This is used to create
test cases using legacy test code, allowing it to be integrated into a
- :mod:`unittest`-based test framework.
+ :mod:`!unittest`-based test framework.
.. _testsuite-objects:
@@ -1822,7 +1822,7 @@ Loading and running tests
The :class:`TestLoader` class is used to create test suites from classes and
modules. Normally, there is no need to create an instance of this class; the
- :mod:`unittest` module provides an instance that can be shared as
+ :mod:`!unittest` module provides an instance that can be shared as
:data:`unittest.defaultTestLoader`. Using a subclass or instance, however,
allows customization of some configurable properties.
@@ -2048,7 +2048,7 @@ Loading and running tests
properly recorded; test authors do not need to worry about recording the
outcome of tests.
- Testing frameworks built on top of :mod:`unittest` may want access to the
+ Testing frameworks built on top of :mod:`!unittest` may want access to the
:class:`TestResult` object generated by running a set of tests for reporting
purposes; a :class:`TestResult` instance is returned by the
:meth:`!TestRunner.run` method for this purpose.
diff --git a/Doc/library/urllib.error.rst b/Doc/library/urllib.error.rst
index 1686ddd09ca..dd2c9858eaa 100644
--- a/Doc/library/urllib.error.rst
+++ b/Doc/library/urllib.error.rst
@@ -11,10 +11,10 @@
--------------
-The :mod:`urllib.error` module defines the exception classes for exceptions
+The :mod:`!urllib.error` module defines the exception classes for exceptions
raised by :mod:`urllib.request`. The base exception class is :exc:`URLError`.
-The following exceptions are raised by :mod:`urllib.error` as appropriate:
+The following exceptions are raised by :mod:`!urllib.error` as appropriate:
.. exception:: URLError
diff --git a/Doc/library/urllib.parse.rst b/Doc/library/urllib.parse.rst
index 44a9c79cba2..f893039c9ac 100644
--- a/Doc/library/urllib.parse.rst
+++ b/Doc/library/urllib.parse.rst
@@ -35,7 +35,7 @@ Resource Locators. It supports the following URL schemes: ``file``, ``ftp``,
macOS, it *may* be removed if CPython has been built with the
:option:`--with-app-store-compliance` option.
-The :mod:`urllib.parse` module defines functions that fall into two broad
+The :mod:`!urllib.parse` module defines functions that fall into two broad
categories: URL parsing and URL quoting. These are covered in detail in
the following sections.
@@ -50,11 +50,12 @@ URL Parsing
The URL parsing functions focus on splitting a URL string into its components,
or on combining URL components into a URL string.
-.. function:: urlparse(urlstring, scheme='', allow_fragments=True)
+.. function:: urlsplit(urlstring, scheme=None, allow_fragments=True)
- Parse a URL into six components, returning a 6-item :term:`named tuple`. This
- corresponds to the general structure of a URL:
- ``scheme://netloc/path;parameters?query#fragment``.
+ Parse a URL into five components, returning a 5-item :term:`named tuple`
+ :class:`SplitResult` or :class:`SplitResultBytes`.
+ This corresponds to the general structure of a URL:
+ ``scheme://netloc/path?query#fragment``.
Each tuple item is a string, possibly empty. The components are not broken up
into smaller parts (for example, the network location is a single string), and %
escapes are not expanded. The delimiters as shown above are not part of the
@@ -64,15 +65,15 @@ or on combining URL components into a URL string.
.. doctest::
:options: +NORMALIZE_WHITESPACE
- >>> from urllib.parse import urlparse
- >>> urlparse("scheme://netloc/path;parameters?query#fragment")
- ParseResult(scheme='scheme', netloc='netloc', path='/path;parameters', params='',
+ >>> from urllib.parse import urlsplit
+ >>> urlsplit("scheme://netloc/path?query#fragment")
+ SplitResult(scheme='scheme', netloc='netloc', path='/path',
query='query', fragment='fragment')
- >>> o = urlparse("http://docs.python.org:80/3/library/urllib.parse.html?"
+ >>> o = urlsplit("http://docs.python.org:80/3/library/urllib.parse.html?"
... "highlight=params#url-parsing")
>>> o
- ParseResult(scheme='http', netloc='docs.python.org:80',
- path='/3/library/urllib.parse.html', params='',
+ SplitResult(scheme='http', netloc='docs.python.org:80',
+ path='/3/library/urllib.parse.html',
query='highlight=params', fragment='url-parsing')
>>> o.scheme
'http'
@@ -85,7 +86,7 @@ or on combining URL components into a URL string.
>>> o._replace(fragment="").geturl()
'http://docs.python.org:80/3/library/urllib.parse.html?highlight=params'
- Following the syntax specifications in :rfc:`1808`, urlparse recognizes
+ Following the syntax specifications in :rfc:`1808`, :func:`!urlsplit` recognizes
a netloc only if it is properly introduced by '//'. Otherwise the
input is presumed to be a relative URL and thus to start with
a path component.
@@ -93,15 +94,15 @@ or on combining URL components into a URL string.
.. doctest::
:options: +NORMALIZE_WHITESPACE
- >>> from urllib.parse import urlparse
- >>> urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
- ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
- params='', query='', fragment='')
- >>> urlparse('www.cwi.nl/%7Eguido/Python.html')
- ParseResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html',
- params='', query='', fragment='')
- >>> urlparse('help/Python.html')
- ParseResult(scheme='', netloc='', path='help/Python.html', params='',
+ >>> from urllib.parse import urlsplit
+ >>> urlsplit('//www.cwi.nl:80/%7Eguido/Python.html')
+ SplitResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
+ query='', fragment='')
+ >>> urlsplit('www.cwi.nl/%7Eguido/Python.html')
+ SplitResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html',
+ query='', fragment='')
+ >>> urlsplit('help/Python.html')
+ SplitResult(scheme='', netloc='', path='help/Python.html',
query='', fragment='')
The *scheme* argument gives the default addressing scheme, to be
@@ -126,12 +127,9 @@ or on combining URL components into a URL string.
+------------------+-------+-------------------------+------------------------+
| :attr:`path` | 2 | Hierarchical path | empty string |
+------------------+-------+-------------------------+------------------------+
- | :attr:`params` | 3 | Parameters for last | empty string |
- | | | path element | |
- +------------------+-------+-------------------------+------------------------+
- | :attr:`query` | 4 | Query component | empty string |
+ | :attr:`query` | 3 | Query component | empty string |
+------------------+-------+-------------------------+------------------------+
- | :attr:`fragment` | 5 | Fragment identifier | empty string |
+ | :attr:`fragment` | 4 | Fragment identifier | empty string |
+------------------+-------+-------------------------+------------------------+
| :attr:`username` | | User name | :const:`None` |
+------------------+-------+-------------------------+------------------------+
@@ -155,26 +153,30 @@ or on combining URL components into a URL string.
``#``, ``@``, or ``:`` will raise a :exc:`ValueError`. If the URL is
decomposed before parsing, no error will be raised.
+ Following some of the `WHATWG spec`_ that updates :rfc:`3986`, leading C0
+ control and space characters are stripped from the URL. ``\n``,
+ ``\r`` and tab ``\t`` characters are removed from the URL at any position.
+
As is the case with all named tuples, the subclass has a few additional methods
and attributes that are particularly useful. One such method is :meth:`_replace`.
- The :meth:`_replace` method will return a new ParseResult object replacing specified
- fields with new values.
+ The :meth:`_replace` method will return a new :class:`SplitResult` object
+ replacing specified fields with new values.
.. doctest::
:options: +NORMALIZE_WHITESPACE
- >>> from urllib.parse import urlparse
- >>> u = urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
+ >>> from urllib.parse import urlsplit
+ >>> u = urlsplit('//www.cwi.nl:80/%7Eguido/Python.html')
>>> u
- ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
- params='', query='', fragment='')
+ SplitResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
+ query='', fragment='')
>>> u._replace(scheme='http')
- ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
- params='', query='', fragment='')
+ SplitResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
+ query='', fragment='')
.. warning::
- :func:`urlparse` does not perform validation. See :ref:`URL parsing
+ :func:`urlsplit` does not perform validation. See :ref:`URL parsing
security <url-parsing-security>` for details.
.. versionchanged:: 3.2
@@ -193,6 +195,14 @@ or on combining URL components into a URL string.
Characters that affect netloc parsing under NFKC normalization will
now raise :exc:`ValueError`.
+ .. versionchanged:: 3.10
+ ASCII newline and tab characters are stripped from the URL.
+
+ .. versionchanged:: 3.12
+ Leading WHATWG C0 control and space characters are stripped from the URL.
+
+.. _WHATWG spec: https://url.spec.whatwg.org/#concept-basic-url-parser
+
.. function:: parse_qs(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')
@@ -287,93 +297,35 @@ or on combining URL components into a URL string.
separator key, with ``&`` as the default separator.
-.. function:: urlunparse(parts)
+.. function:: urlunsplit(parts)
- Construct a URL from a tuple as returned by ``urlparse()``. The *parts*
- argument can be any six-item iterable. This may result in a slightly
+ Construct a URL from a tuple as returned by ``urlsplit()``. The *parts*
+ argument can be any five-item iterable. This may result in a slightly
different, but equivalent URL, if the URL that was parsed originally had
unnecessary delimiters (for example, a ``?`` with an empty query; the RFC
states that these are equivalent).
-.. function:: urlsplit(urlstring, scheme='', allow_fragments=True)
-
- This is similar to :func:`urlparse`, but does not split the params from the URL.
- This should generally be used instead of :func:`urlparse` if the more recent URL
- syntax allowing parameters to be applied to each segment of the *path* portion
- of the URL (see :rfc:`2396`) is wanted. A separate function is needed to
- separate the path segments and parameters. This function returns a 5-item
- :term:`named tuple`::
-
- (addressing scheme, network location, path, query, fragment identifier).
-
- The return value is a :term:`named tuple`, its items can be accessed by index
- or as named attributes:
-
- +------------------+-------+-------------------------+----------------------+
- | Attribute | Index | Value | Value if not present |
- +==================+=======+=========================+======================+
- | :attr:`scheme` | 0 | URL scheme specifier | *scheme* parameter |
- +------------------+-------+-------------------------+----------------------+
- | :attr:`netloc` | 1 | Network location part | empty string |
- +------------------+-------+-------------------------+----------------------+
- | :attr:`path` | 2 | Hierarchical path | empty string |
- +------------------+-------+-------------------------+----------------------+
- | :attr:`query` | 3 | Query component | empty string |
- +------------------+-------+-------------------------+----------------------+
- | :attr:`fragment` | 4 | Fragment identifier | empty string |
- +------------------+-------+-------------------------+----------------------+
- | :attr:`username` | | User name | :const:`None` |
- +------------------+-------+-------------------------+----------------------+
- | :attr:`password` | | Password | :const:`None` |
- +------------------+-------+-------------------------+----------------------+
- | :attr:`hostname` | | Host name (lower case) | :const:`None` |
- +------------------+-------+-------------------------+----------------------+
- | :attr:`port` | | Port number as integer, | :const:`None` |
- | | | if present | |
- +------------------+-------+-------------------------+----------------------+
-
- Reading the :attr:`port` attribute will raise a :exc:`ValueError` if
- an invalid port is specified in the URL. See section
- :ref:`urlparse-result-object` for more information on the result object.
-
- Unmatched square brackets in the :attr:`netloc` attribute will raise a
- :exc:`ValueError`.
-
- Characters in the :attr:`netloc` attribute that decompose under NFKC
- normalization (as used by the IDNA encoding) into any of ``/``, ``?``,
- ``#``, ``@``, or ``:`` will raise a :exc:`ValueError`. If the URL is
- decomposed before parsing, no error will be raised.
-
- Following some of the `WHATWG spec`_ that updates RFC 3986, leading C0
- control and space characters are stripped from the URL. ``\n``,
- ``\r`` and tab ``\t`` characters are removed from the URL at any position.
-
- .. warning::
-
- :func:`urlsplit` does not perform validation. See :ref:`URL parsing
- security <url-parsing-security>` for details.
+.. function:: urlparse(urlstring, scheme=None, allow_fragments=True)
- .. versionchanged:: 3.6
- Out-of-range port numbers now raise :exc:`ValueError`, instead of
- returning :const:`None`.
+ This is similar to :func:`urlsplit`, but additionally splits the *path*
+ component on *path* and *params*.
+ This function returns a 6-item :term:`named tuple` :class:`ParseResult`
+ or :class:`ParseResultBytes`.
+ Its items are the same as for the :func:`!urlsplit` result, except that
+ *params* is inserted at index 3, between *path* and *query*.
- .. versionchanged:: 3.8
- Characters that affect netloc parsing under NFKC normalization will
- now raise :exc:`ValueError`.
+ This function is based on obsoleted :rfc:`1738` and :rfc:`1808`, which
+ listed *params* as the main URL component.
+ The more recent URL syntax allows parameters to be applied to each segment
+ of the *path* portion of the URL (see :rfc:`3986`).
+ :func:`urlsplit` should generally be used instead of :func:`urlparse`.
+ A separate function is needed to separate the path segments and parameters.
- .. versionchanged:: 3.10
- ASCII newline and tab characters are stripped from the URL.
-
- .. versionchanged:: 3.12
- Leading WHATWG C0 control and space characters are stripped from the URL.
-
-.. _WHATWG spec: https://url.spec.whatwg.org/#concept-basic-url-parser
-
-.. function:: urlunsplit(parts)
+.. function:: urlunparse(parts)
- Combine the elements of a tuple as returned by :func:`urlsplit` into a
- complete URL as a string. The *parts* argument can be any five-item
+ Combine the elements of a tuple as returned by :func:`urlparse` into a
+ complete URL as a string. The *parts* argument can be any six-item
iterable. This may result in a slightly different, but equivalent URL, if the
URL that was parsed originally had unnecessary delimiters (for example, a ?
with an empty query; the RFC states that these are equivalent).
@@ -391,7 +343,7 @@ or on combining URL components into a URL string.
'http://www.cwi.nl/%7Eguido/FAQ.html'
The *allow_fragments* argument has the same meaning and default as for
- :func:`urlparse`.
+ :func:`urlsplit`.
.. note::
@@ -531,7 +483,7 @@ individual URL quoting functions.
Structured Parse Results
------------------------
-The result objects from the :func:`urlparse`, :func:`urlsplit` and
+The result objects from the :func:`urlsplit`, :func:`urlparse` and
:func:`urldefrag` functions are subclasses of the :class:`tuple` type.
These subclasses add the attributes listed in the documentation for
those functions, the encoding and decoding support described in the
diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst
index 5f796578eaa..b857b2a235e 100644
--- a/Doc/library/urllib.request.rst
+++ b/Doc/library/urllib.request.rst
@@ -12,7 +12,7 @@
--------------
-The :mod:`urllib.request` module defines functions and classes which help in
+The :mod:`!urllib.request` module defines functions and classes which help in
opening URLs (mostly HTTP) in a complex world --- basic and digest
authentication, redirections, cookies and more.
@@ -31,7 +31,7 @@ authentication, redirections, cookies and more.
.. include:: ../includes/wasm-notavail.rst
-The :mod:`urllib.request` module defines the following functions:
+The :mod:`!urllib.request` module defines the following functions:
.. function:: urlopen(url, data=None[, timeout], *, context=None)
@@ -1485,8 +1485,8 @@ some point in the future.
calls to :func:`urlretrieve`.
-:mod:`urllib.request` Restrictions
-----------------------------------
+:mod:`!urllib.request` Restrictions
+-----------------------------------
.. index::
pair: HTTP; protocol
@@ -1539,15 +1539,15 @@ some point in the future.
-:mod:`urllib.response` --- Response classes used by urllib
-==========================================================
+:mod:`!urllib.response` --- Response classes used by urllib
+===========================================================
.. module:: urllib.response
:synopsis: Response classes used by urllib.
-The :mod:`urllib.response` module defines functions and classes which define a
+The :mod:`!urllib.response` module defines functions and classes which define a
minimal file-like interface, including ``read()`` and ``readline()``.
-Functions defined by this module are used internally by the :mod:`urllib.request` module.
+Functions defined by this module are used internally by the :mod:`!urllib.request` module.
The typical response object is a :class:`urllib.response.addinfourl` instance:
.. class:: addinfourl
diff --git a/Doc/library/urllib.robotparser.rst b/Doc/library/urllib.robotparser.rst
index 674f646c633..ba719ae084e 100644
--- a/Doc/library/urllib.robotparser.rst
+++ b/Doc/library/urllib.robotparser.rst
@@ -91,16 +91,16 @@ class::
>>> import urllib.robotparser
>>> rp = urllib.robotparser.RobotFileParser()
- >>> rp.set_url("http://www.musi-cal.com/robots.txt")
+ >>> rp.set_url("http://www.pythontest.net/robots.txt")
>>> rp.read()
>>> rrate = rp.request_rate("*")
>>> rrate.requests
- 3
+ 1
>>> rrate.seconds
- 20
+ 1
>>> rp.crawl_delay("*")
6
- >>> rp.can_fetch("*", "http://www.musi-cal.com/cgi-bin/search?city=San+Francisco")
- False
- >>> rp.can_fetch("*", "http://www.musi-cal.com/")
+ >>> rp.can_fetch("*", "http://www.pythontest.net/")
True
+ >>> rp.can_fetch("*", "http://www.pythontest.net/no-robots-here/")
+ False
diff --git a/Doc/library/uuid.rst b/Doc/library/uuid.rst
index aa4f1bf940b..fe3a3a8e510 100644
--- a/Doc/library/uuid.rst
+++ b/Doc/library/uuid.rst
@@ -168,7 +168,7 @@ which relays any information about the UUID's safety, using this enumeration:
.. versionadded:: 3.7
-The :mod:`uuid` module defines the following functions:
+The :mod:`!uuid` module defines the following functions:
.. function:: getnode()
@@ -273,7 +273,7 @@ The :mod:`uuid` module defines the following functions:
.. versionadded:: 3.14
-The :mod:`uuid` module defines the following namespace identifiers for use with
+The :mod:`!uuid` module defines the following namespace identifiers for use with
:func:`uuid3` or :func:`uuid5`.
@@ -298,7 +298,7 @@ The :mod:`uuid` module defines the following namespace identifiers for use with
When this namespace is specified, the *name* string is an X.500 DN in DER or a
text output format.
-The :mod:`uuid` module defines the following constants for the possible values
+The :mod:`!uuid` module defines the following constants for the possible values
of the :attr:`~UUID.variant` attribute:
@@ -324,7 +324,7 @@ of the :attr:`~UUID.variant` attribute:
Reserved for future definition.
-The :mod:`uuid` module defines the special Nil and Max UUID values:
+The :mod:`!uuid` module defines the special Nil and Max UUID values:
.. data:: NIL
@@ -357,7 +357,7 @@ Command-Line Usage
.. versionadded:: 3.12
-The :mod:`uuid` module can be executed as a script from the command line.
+The :mod:`!uuid` module can be executed as a script from the command line.
.. code-block:: sh
@@ -406,7 +406,7 @@ The following options are accepted:
Example
-------
-Here are some examples of typical usage of the :mod:`uuid` module::
+Here are some examples of typical usage of the :mod:`!uuid` module::
>>> import uuid
@@ -473,7 +473,7 @@ Here are some examples of typical usage of the :mod:`uuid` module::
Command-Line Example
--------------------
-Here are some examples of typical usage of the :mod:`uuid` command-line interface:
+Here are some examples of typical usage of the :mod:`!uuid` command-line interface:
.. code-block:: shell
diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst
index b0eb8ee18fa..59ec863c14f 100644
--- a/Doc/library/venv.rst
+++ b/Doc/library/venv.rst
@@ -545,7 +545,7 @@ subclass which installs setuptools and pip into a created virtual environment::
from subprocess import Popen, PIPE
import sys
from threading import Thread
- from urllib.parse import urlparse
+ from urllib.parse import urlsplit
from urllib.request import urlretrieve
import venv
@@ -616,7 +616,7 @@ subclass which installs setuptools and pip into a created virtual environment::
stream.close()
def install_script(self, context, name, url):
- _, _, path, _, _, _ = urlparse(url)
+ _, _, path, _, _ = urlsplit(url)
fn = os.path.split(path)[-1]
binpath = context.bin_path
distpath = os.path.join(binpath, fn)
diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst
index 15b62a0653d..01c316bbfd3 100644
--- a/Doc/library/warnings.rst
+++ b/Doc/library/warnings.rst
@@ -203,7 +203,7 @@ Describing Warning Filters
The warnings filter is initialized by :option:`-W` options passed to the Python
interpreter command line and the :envvar:`PYTHONWARNINGS` environment variable.
The interpreter saves the arguments for all supplied entries without
-interpretation in :data:`sys.warnoptions`; the :mod:`warnings` module parses these
+interpretation in :data:`sys.warnoptions`; the :mod:`!warnings` module parses these
when it is first imported (invalid options are ignored, after printing a
message to :data:`sys.stderr`).
@@ -616,8 +616,8 @@ Available Context Managers
:func:`showwarning`.
The *module* argument takes a module that will be used instead of the
- module returned when you import :mod:`warnings` whose filter will be
- protected. This argument exists primarily for testing the :mod:`warnings`
+ module returned when you import :mod:`!warnings` whose filter will be
+ protected. This argument exists primarily for testing the :mod:`!warnings`
module itself.
If the *action* argument is not ``None``, the remaining arguments are
@@ -654,7 +654,7 @@ to true for free-threaded builds and false otherwise.
If the :data:`~sys.flags.context_aware_warnings` flag is false, then
:class:`catch_warnings` will modify the global attributes of the
-:mod:`warnings` module. This is not safe if used within a concurrent program
+:mod:`!warnings` module. This is not safe if used within a concurrent program
(using multiple threads or using asyncio coroutines). For example, if two
or more threads use the :class:`catch_warnings` class at the same time, the
behavior is undefined.
diff --git a/Doc/library/wave.rst b/Doc/library/wave.rst
index 36c2bde87fb..38b05f0b4fd 100644
--- a/Doc/library/wave.rst
+++ b/Doc/library/wave.rst
@@ -11,7 +11,7 @@
--------------
-The :mod:`wave` module provides a convenient interface to the Waveform Audio
+The :mod:`!wave` module provides a convenient interface to the Waveform Audio
"WAVE" (or "WAV") file format. Only uncompressed PCM encoded wave files are
supported.
@@ -20,7 +20,7 @@ supported.
Support for ``WAVE_FORMAT_EXTENSIBLE`` headers was added, provided that the
extended format is ``KSDATAFORMAT_SUBTYPE_PCM``.
-The :mod:`wave` module defines the following function and exception:
+The :mod:`!wave` module defines the following function and exception:
.. function:: open(file, mode=None)
@@ -72,7 +72,7 @@ Wave_read Objects
.. method:: close()
- Close the stream if it was opened by :mod:`wave`, and make the instance
+ Close the stream if it was opened by :mod:`!wave`, and make the instance
unusable. This is called automatically on object collection.
@@ -189,7 +189,7 @@ Wave_write Objects
.. method:: close()
Make sure *nframes* is correct, and close the file if it was opened by
- :mod:`wave`. This method is called upon object collection. It will raise
+ :mod:`!wave`. This method is called upon object collection. It will raise
an exception if the output stream is not seekable and *nframes* does not
match the number of frames actually written.
@@ -199,11 +199,21 @@ Wave_write Objects
Set the number of channels.
+ .. method:: getnchannels()
+
+ Return the number of channels.
+
+
.. method:: setsampwidth(n)
Set the sample width to *n* bytes.
+ .. method:: getsampwidth()
+
+ Return the sample width in bytes.
+
+
.. method:: setframerate(n)
Set the frame rate to *n*.
@@ -213,6 +223,11 @@ Wave_write Objects
integer.
+ .. method:: getframerate()
+
+ Return the frame rate.
+
+
.. method:: setnframes(n)
Set the number of frames to *n*. This will be changed later if the number
@@ -220,12 +235,27 @@ Wave_write Objects
raise an error if the output stream is not seekable).
+ .. method:: getnframes()
+
+ Return the number of audio frames written so far.
+
+
.. method:: setcomptype(type, name)
Set the compression type and description. At the moment, only compression type
``NONE`` is supported, meaning no compression.
+ .. method:: getcomptype()
+
+ Return the compression type (``'NONE'``).
+
+
+ .. method:: getcompname()
+
+ Return the human-readable compression type name.
+
+
.. method:: setparams(tuple)
The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype,
@@ -233,6 +263,13 @@ Wave_write Objects
parameters.
+ .. method:: getparams()
+
+ Return a :func:`~collections.namedtuple`
+ ``(nchannels, sampwidth, framerate, nframes, comptype, compname)``
+ containing the current output parameters.
+
+
.. method:: tell()
Return current position in the file, with the same disclaimer for the
diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst
index 2a25ed045c6..6dc5f90686c 100644
--- a/Doc/library/weakref.rst
+++ b/Doc/library/weakref.rst
@@ -1,7 +1,7 @@
.. _mod-weakref:
-:mod:`weakref` --- Weak references
-==================================
+:mod:`!weakref` --- Weak references
+===================================
.. module:: weakref
:synopsis: Support for weak references and weak dictionaries.
@@ -15,7 +15,7 @@
--------------
-The :mod:`weakref` module allows the Python programmer to create :dfn:`weak
+The :mod:`!weakref` module allows the Python programmer to create :dfn:`weak
references` to objects.
.. When making changes to the examples in this file, be sure to update
@@ -39,7 +39,7 @@ associate a name with each. If you used a Python dictionary to map names to
images, or images to names, the image objects would remain alive just because
they appeared as values or keys in the dictionaries. The
:class:`WeakKeyDictionary` and :class:`WeakValueDictionary` classes supplied by
-the :mod:`weakref` module are an alternative, using weak references to construct
+the :mod:`!weakref` module are an alternative, using weak references to construct
mappings that don't keep objects alive solely because they appear in the mapping
objects. If, for example, an image object is a value in a
:class:`WeakValueDictionary`, then when the last remaining references to that
@@ -63,7 +63,7 @@ remains alive until the object is collected.
Most programs should find that using one of these weak container types
or :class:`finalize` is all they need -- it's not usually necessary to
create your own weak references directly. The low-level machinery is
-exposed by the :mod:`weakref` module for the benefit of advanced uses.
+exposed by the :mod:`!weakref` module for the benefit of advanced uses.
Not all objects can be weakly referenced. Objects which support weak references
include class instances, functions written in Python (but not in C), instance methods,
diff --git a/Doc/library/webbrowser.rst b/Doc/library/webbrowser.rst
index a2103d8fdd8..7b37b270e75 100644
--- a/Doc/library/webbrowser.rst
+++ b/Doc/library/webbrowser.rst
@@ -11,7 +11,7 @@
--------------
-The :mod:`webbrowser` module provides a high-level interface to allow displaying
+The :mod:`!webbrowser` module provides a high-level interface to allow displaying
web-based documents to users. Under most circumstances, simply calling the
:func:`.open` function from this module will do the right thing.
@@ -46,7 +46,7 @@ On iOS, the :envvar:`BROWSER` environment variable, as well as any arguments
controlling autoraise, browser preference, and new tab/window creation will be
ignored. Web pages will *always* be opened in the user's preferred browser, in
a new tab, with the browser being brought to the foreground. The use of the
-:mod:`webbrowser` module on iOS requires the :mod:`ctypes` module. If
+:mod:`!webbrowser` module on iOS requires the :mod:`ctypes` module. If
:mod:`ctypes` isn't available, calls to :func:`.open` will fail.
.. _webbrowser-cli:
diff --git a/Doc/library/winreg.rst b/Doc/library/winreg.rst
index 6d1e8ecfc17..086f5fcf968 100644
--- a/Doc/library/winreg.rst
+++ b/Doc/library/winreg.rst
@@ -2,7 +2,6 @@
==========================================
.. module:: winreg
- :platform: Windows
:synopsis: Routines and objects for manipulating the Windows registry.
.. sectionauthor:: Mark Hammond <MarkH@ActiveState.com>
@@ -538,7 +537,7 @@ This module offers the following functions:
Constants
------------------
-The following constants are defined for use in many :mod:`winreg` functions.
+The following constants are defined for use in many :mod:`!winreg` functions.
.. _hkey-constants:
diff --git a/Doc/library/winsound.rst b/Doc/library/winsound.rst
index 93c0c025982..70ddfe3bae0 100644
--- a/Doc/library/winsound.rst
+++ b/Doc/library/winsound.rst
@@ -2,7 +2,6 @@
========================================================
.. module:: winsound
- :platform: Windows
:synopsis: Access to the sound-playing machinery for Windows.
.. moduleauthor:: Toby Dickenson <htrd90@zepler.org>
@@ -10,7 +9,7 @@
--------------
-The :mod:`winsound` module provides access to the basic sound-playing machinery
+The :mod:`!winsound` module provides access to the basic sound-playing machinery
provided by Windows platforms. It includes functions and several constants.
.. availability:: Windows.
diff --git a/Doc/library/wsgiref.rst b/Doc/library/wsgiref.rst
index 381c9938347..0ace7b72d32 100644
--- a/Doc/library/wsgiref.rst
+++ b/Doc/library/wsgiref.rst
@@ -11,6 +11,11 @@
--------------
+.. warning::
+
+ :mod:`!wsgiref` is a reference implementation and is not recommended for
+ production. The module only implements basic security checks.
+
The Web Server Gateway Interface (WSGI) is a standard interface between web
server software and web applications written in Python. Having a standard
interface makes it easy to use an application that supports WSGI with a number
@@ -21,7 +26,7 @@ and corner case of the WSGI design. You don't need to understand every detail
of WSGI just to install a WSGI application or to write a web application using
an existing framework.
-:mod:`wsgiref` is a reference implementation of the WSGI specification that can
+:mod:`!wsgiref` is a reference implementation of the WSGI specification that can
be used to add WSGI support to a web server or framework. It provides utilities
for manipulating WSGI environment variables and response headers, base classes
for implementing WSGI servers, a demo HTTP server that serves WSGI applications,
@@ -35,8 +40,8 @@ to tutorials and other resources.
.. XXX If you're just trying to write a web application...
-:mod:`wsgiref.util` -- WSGI environment utilities
--------------------------------------------------
+:mod:`!wsgiref.util` -- WSGI environment utilities
+--------------------------------------------------
.. module:: wsgiref.util
:synopsis: WSGI environment utilities.
@@ -144,7 +149,7 @@ in type annotations.
httpd.serve_forever()
-In addition to the environment functions above, the :mod:`wsgiref.util` module
+In addition to the environment functions above, the :mod:`!wsgiref.util` module
also provides these miscellaneous utilities:
@@ -184,8 +189,8 @@ also provides these miscellaneous utilities:
Support for :meth:`~object.__getitem__` method has been removed.
-:mod:`wsgiref.headers` -- WSGI response header tools
-----------------------------------------------------
+:mod:`!wsgiref.headers` -- WSGI response header tools
+-----------------------------------------------------
.. module:: wsgiref.headers
:synopsis: WSGI response header tools.
@@ -268,8 +273,8 @@ manipulation of WSGI response headers using a mapping-like interface.
*headers* parameter is optional.
-:mod:`wsgiref.simple_server` -- a simple WSGI HTTP server
----------------------------------------------------------
+:mod:`!wsgiref.simple_server` -- a simple WSGI HTTP server
+----------------------------------------------------------
.. module:: wsgiref.simple_server
:synopsis: A simple WSGI HTTP server.
@@ -310,7 +315,7 @@ request. (E.g., using the :func:`shift_path_info` function from
This function is a small but complete WSGI application that returns a text page
containing the message "Hello world!" and a list of the key/value pairs provided
in the *environ* parameter. It's useful for verifying that a WSGI server (such
- as :mod:`wsgiref.simple_server`) is able to run a simple WSGI application
+ as :mod:`!wsgiref.simple_server`) is able to run a simple WSGI application
correctly.
The *start_response* callable should follow the :class:`.StartResponse` protocol.
@@ -382,8 +387,8 @@ request. (E.g., using the :func:`shift_path_info` function from
interface.
-:mod:`wsgiref.validate` --- WSGI conformance checker
-----------------------------------------------------
+:mod:`!wsgiref.validate` --- WSGI conformance checker
+-----------------------------------------------------
.. module:: wsgiref.validate
:synopsis: WSGI conformance checker.
@@ -391,7 +396,7 @@ request. (E.g., using the :func:`shift_path_info` function from
When creating new WSGI application objects, frameworks, servers, or middleware,
it can be useful to validate the new code's conformance using
-:mod:`wsgiref.validate`. This module provides a function that creates WSGI
+:mod:`!wsgiref.validate`. This module provides a function that creates WSGI
application objects that validate communications between a WSGI server or
gateway and a WSGI application object, to check both sides for protocol
conformance.
@@ -450,8 +455,8 @@ Paste" library.
httpd.serve_forever()
-:mod:`wsgiref.handlers` -- server/gateway base classes
-------------------------------------------------------
+:mod:`!wsgiref.handlers` -- server/gateway base classes
+-------------------------------------------------------
.. module:: wsgiref.handlers
:synopsis: WSGI server/gateway base classes.
@@ -622,7 +627,7 @@ input, output, and error streams.
The default environment variables to be included in every request's WSGI
environment. By default, this is a copy of ``os.environ`` at the time that
- :mod:`wsgiref.handlers` was imported, but subclasses can either create their own
+ :mod:`!wsgiref.handlers` was imported, but subclasses can either create their own
at the class or instance level. Note that the dictionary should be considered
read-only, since the default value is shared between multiple classes and
instances.
@@ -773,8 +778,8 @@ input, output, and error streams.
.. versionadded:: 3.2
-:mod:`wsgiref.types` -- WSGI types for static type checking
------------------------------------------------------------
+:mod:`!wsgiref.types` -- WSGI types for static type checking
+------------------------------------------------------------
.. module:: wsgiref.types
:synopsis: WSGI types for static type checking
diff --git a/Doc/library/xml.dom.minidom.rst b/Doc/library/xml.dom.minidom.rst
index 9ffedf7366a..321d93079bc 100644
--- a/Doc/library/xml.dom.minidom.rst
+++ b/Doc/library/xml.dom.minidom.rst
@@ -12,7 +12,7 @@
--------------
-:mod:`xml.dom.minidom` is a minimal implementation of the Document Object
+:mod:`!xml.dom.minidom` is a minimal implementation of the Document Object
Model interface, with an API similar to that in other languages. It is intended
to be simpler than the full DOM and also significantly smaller. Users who are
not already proficient with the DOM should consider using the
@@ -26,7 +26,7 @@ not already proficient with the DOM should consider using the
DOM applications typically start by parsing some XML into a DOM. With
-:mod:`xml.dom.minidom`, this is done through the parse functions::
+:mod:`!xml.dom.minidom`, this is done through the parse functions::
from xml.dom.minidom import parse, parseString
@@ -62,7 +62,7 @@ document.
What the :func:`parse` and :func:`parseString` functions do is connect an XML
parser with a "DOM builder" that can accept parse events from any SAX parser and
-convert them into a DOM tree. The name of the functions are perhaps misleading,
+convert them into a DOM tree. The names of the functions are perhaps misleading,
but are easy to grasp when learning the interfaces. The parsing of the document
will be completed before these functions return; it's simply that these
functions do not provide a parser implementation themselves.
@@ -70,7 +70,7 @@ functions do not provide a parser implementation themselves.
You can also create a :class:`Document` by calling a method on a "DOM
Implementation" object. You can get this object either by calling the
:func:`getDOMImplementation` function in the :mod:`xml.dom` package or the
-:mod:`xml.dom.minidom` module. Once you have a :class:`Document`, you
+:mod:`!xml.dom.minidom` module. Once you have a :class:`Document`, you
can add child nodes to it to populate the DOM::
from xml.dom.minidom import getDOMImplementation
@@ -93,7 +93,7 @@ document: the one that holds all others. Here is an example program::
When you are finished with a DOM tree, you may optionally call the
:meth:`unlink` method to encourage early cleanup of the now-unneeded
-objects. :meth:`unlink` is an :mod:`xml.dom.minidom`\ -specific
+objects. :meth:`unlink` is an :mod:`!xml.dom.minidom`\ -specific
extension to the DOM API that renders the node and its descendants
essentially useless. Otherwise, Python's garbage collector will
eventually take care of the objects in the tree.
@@ -101,7 +101,7 @@ eventually take care of the objects in the tree.
.. seealso::
`Document Object Model (DOM) Level 1 Specification <https://www.w3.org/TR/REC-DOM-Level-1/>`_
- The W3C recommendation for the DOM supported by :mod:`xml.dom.minidom`.
+ The W3C recommendation for the DOM supported by :mod:`!xml.dom.minidom`.
.. _minidom-objects:
@@ -111,7 +111,7 @@ DOM Objects
The definition of the DOM API for Python is given as part of the :mod:`xml.dom`
module documentation. This section lists the differences between the API and
-:mod:`xml.dom.minidom`.
+:mod:`!xml.dom.minidom`.
.. method:: Node.unlink()
@@ -214,7 +214,7 @@ particular case, we do not take much advantage of the flexibility of the DOM.
minidom and the DOM standard
----------------------------
-The :mod:`xml.dom.minidom` module is essentially a DOM 1.0-compatible DOM with
+The :mod:`!xml.dom.minidom` module is essentially a DOM 1.0-compatible DOM with
some DOM 2 features (primarily namespace features).
Usage of the DOM interface in Python is straight-forward. The following mapping
@@ -237,7 +237,7 @@ rules apply:
* The types ``short int``, ``unsigned int``, ``unsigned long long``, and
``boolean`` all map to Python integer objects.
-* The type ``DOMString`` maps to Python strings. :mod:`xml.dom.minidom` supports
+* The type ``DOMString`` maps to Python strings. :mod:`!xml.dom.minidom` supports
either bytes or strings, but will normally produce strings.
Values of type ``DOMString`` may also be ``None`` where allowed to have the IDL
``null`` value by the DOM specification from the W3C.
@@ -245,8 +245,8 @@ rules apply:
* ``const`` declarations map to variables in their respective scope (e.g.
``xml.dom.minidom.Node.PROCESSING_INSTRUCTION_NODE``); they must not be changed.
-* ``DOMException`` is currently not supported in :mod:`xml.dom.minidom`.
- Instead, :mod:`xml.dom.minidom` uses standard Python exceptions such as
+* ``DOMException`` is currently not supported in :mod:`!xml.dom.minidom`.
+ Instead, :mod:`!xml.dom.minidom` uses standard Python exceptions such as
:exc:`TypeError` and :exc:`AttributeError`.
* :class:`NodeList` objects are implemented using Python's built-in list type.
@@ -255,7 +255,7 @@ rules apply:
however, much more "Pythonic" than the interface defined in the W3C
recommendations.
-The following interfaces have no implementation in :mod:`xml.dom.minidom`:
+The following interfaces have no implementation in :mod:`!xml.dom.minidom`:
* :class:`DOMTimeStamp`
diff --git a/Doc/library/xml.dom.pulldom.rst b/Doc/library/xml.dom.pulldom.rst
index a21cfaa4645..5027596ed96 100644
--- a/Doc/library/xml.dom.pulldom.rst
+++ b/Doc/library/xml.dom.pulldom.rst
@@ -10,7 +10,7 @@
--------------
-The :mod:`xml.dom.pulldom` module provides a "pull parser" which can also be
+The :mod:`!xml.dom.pulldom` module provides a "pull parser" which can also be
asked to produce DOM-accessible fragments of the document where necessary. The
basic concept involves pulling "events" from a stream of incoming XML and
processing them. In contrast to SAX which also employs an event-driven
diff --git a/Doc/library/xml.dom.rst b/Doc/library/xml.dom.rst
index f33b19bc272..8e5a3c13cfd 100644
--- a/Doc/library/xml.dom.rst
+++ b/Doc/library/xml.dom.rst
@@ -80,7 +80,7 @@ implementations are free to support the strict mapping from IDL). See section
Module Contents
---------------
-The :mod:`xml.dom` contains the following functions:
+The :mod:`!xml.dom` contains the following functions:
.. function:: registerDOMImplementation(name, factory)
@@ -135,7 +135,7 @@ Some convenience constants are also provided:
HyperText Markup Language <https://www.w3.org/TR/xhtml1/>`_ (section 3.1.1).
-In addition, :mod:`xml.dom` contains a base :class:`Node` class and the DOM
+In addition, :mod:`!xml.dom` contains a base :class:`Node` class and the DOM
exception classes. The :class:`Node` class provided by this module does not
implement any of the methods or attributes defined by the DOM specification;
concrete DOM implementations must provide those. The :class:`Node` class
diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst
index 00075ac2a23..bdd5fd564ee 100644
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -10,7 +10,7 @@
--------------
-The :mod:`xml.etree.ElementTree` module implements a simple and efficient API
+The :mod:`!xml.etree.ElementTree` module implements a simple and efficient API
for parsing and creating XML data.
.. versionchanged:: 3.3
@@ -28,7 +28,7 @@ for parsing and creating XML data.
Tutorial
--------
-This is a short tutorial for using :mod:`xml.etree.ElementTree` (``ET`` in
+This is a short tutorial for using :mod:`!xml.etree.ElementTree` (``ET`` in
short). The goal is to demonstrate some of the building blocks and basic
concepts of the module.
@@ -791,7 +791,7 @@ Here's an example that demonstrates use of the XInclude module. To include an XM
By default, the **href** attribute is treated as a file name. You can use custom loaders to override this behaviour. Also note that the standard helper does not support XPointer syntax.
-To process this file, load it as usual, and pass the root element to the :mod:`xml.etree.ElementTree` module:
+To process this file, load it as usual, and pass the root element to the :mod:`!xml.etree.ElementTree` module:
.. code-block:: python
diff --git a/Doc/library/xml.rst b/Doc/library/xml.rst
index acd8d399fe3..81d47147f33 100644
--- a/Doc/library/xml.rst
+++ b/Doc/library/xml.rst
@@ -20,7 +20,7 @@ Python's interfaces for processing XML are grouped in the ``xml`` package.
If you need to parse untrusted or unauthenticated data, see
:ref:`xml-security`.
-It is important to note that modules in the :mod:`xml` package require that
+It is important to note that modules in the :mod:`!xml` package require that
there be at least one SAX-compliant XML parser available. The Expat parser is
included with Python, so the :mod:`xml.parsers.expat` module will always be
available.
diff --git a/Doc/library/xml.sax.handler.rst b/Doc/library/xml.sax.handler.rst
index f1af7253e43..5079fc0f19e 100644
--- a/Doc/library/xml.sax.handler.rst
+++ b/Doc/library/xml.sax.handler.rst
@@ -16,7 +16,7 @@ error handlers, entity resolvers and lexical handlers. Applications normally
only need to implement those interfaces whose events they are interested in;
they can implement the interfaces in a single object or in multiple objects.
Handler implementations should inherit from the base classes provided in the
-module :mod:`xml.sax.handler`, so that all methods get default implementations.
+module :mod:`!xml.sax.handler`, so that all methods get default implementations.
.. class:: ContentHandler
@@ -53,7 +53,7 @@ module :mod:`xml.sax.handler`, so that all methods get default implementations.
Interface used by the parser to represent low frequency events which may not
be of interest to many applications.
-In addition to these classes, :mod:`xml.sax.handler` provides symbolic constants
+In addition to these classes, :mod:`!xml.sax.handler` provides symbolic constants
for the feature and property names.
diff --git a/Doc/library/xml.sax.rst b/Doc/library/xml.sax.rst
index 5fa92645a44..148cb863aca 100644
--- a/Doc/library/xml.sax.rst
+++ b/Doc/library/xml.sax.rst
@@ -12,7 +12,7 @@
--------------
-The :mod:`xml.sax` package provides a number of modules which implement the
+The :mod:`!xml.sax` package provides a number of modules which implement the
Simple API for XML (SAX) interface for Python. The package itself provides the
SAX exceptions and the convenience functions which will be most used by users of
the SAX API.
@@ -89,9 +89,9 @@ module :mod:`xml.sax.xmlreader`. The handler interfaces are defined in
:mod:`xml.sax.handler`. For convenience,
:class:`~xml.sax.xmlreader.InputSource` (which is often
instantiated directly) and the handler classes are also available from
-:mod:`xml.sax`. These interfaces are described below.
+:mod:`!xml.sax`. These interfaces are described below.
-In addition to these classes, :mod:`xml.sax` provides the following exception
+In addition to these classes, :mod:`!xml.sax` provides the following exception
classes.
diff --git a/Doc/library/xml.sax.utils.rst b/Doc/library/xml.sax.utils.rst
index 7731f03d875..f93fe374e1c 100644
--- a/Doc/library/xml.sax.utils.rst
+++ b/Doc/library/xml.sax.utils.rst
@@ -11,7 +11,7 @@
--------------
-The module :mod:`xml.sax.saxutils` contains a number of classes and functions
+The module :mod:`!xml.sax.saxutils` contains a number of classes and functions
that are commonly useful when creating SAX applications, either in direct use,
or as base classes.
diff --git a/Doc/library/xmlrpc.client.rst b/Doc/library/xmlrpc.client.rst
index a21c7d3e4e3..8f87a2f52cd 100644
--- a/Doc/library/xmlrpc.client.rst
+++ b/Doc/library/xmlrpc.client.rst
@@ -23,13 +23,13 @@ between conformable Python objects and XML on the wire.
.. warning::
- The :mod:`xmlrpc.client` module is not secure against maliciously
+ The :mod:`!xmlrpc.client` module is not secure against maliciously
constructed data. If you need to parse untrusted or unauthenticated data,
see :ref:`xml-security`.
.. versionchanged:: 3.5
- For HTTPS URIs, :mod:`xmlrpc.client` now performs all the necessary
+ For HTTPS URIs, :mod:`!xmlrpc.client` now performs all the necessary
certificate and hostname checks by default.
.. include:: ../includes/wasm-notavail.rst
diff --git a/Doc/library/xmlrpc.server.rst b/Doc/library/xmlrpc.server.rst
index 2a8f6f8d5fc..9f16c470567 100644
--- a/Doc/library/xmlrpc.server.rst
+++ b/Doc/library/xmlrpc.server.rst
@@ -11,7 +11,7 @@
--------------
-The :mod:`xmlrpc.server` module provides a basic server framework for XML-RPC
+The :mod:`!xmlrpc.server` module provides a basic server framework for XML-RPC
servers written in Python. Servers can either be free standing, using
:class:`SimpleXMLRPCServer`, or embedded in a CGI environment, using
:class:`CGIXMLRPCRequestHandler`.
@@ -19,7 +19,7 @@ servers written in Python. Servers can either be free standing, using
.. warning::
- The :mod:`xmlrpc.server` module is not secure against maliciously
+ The :mod:`!xmlrpc.server` module is not secure against maliciously
constructed data. If you need to parse untrusted or unauthenticated data,
see :ref:`xml-security`.
@@ -230,7 +230,7 @@ a server allowing dotted names and registering a multicall function.
Enabling the *allow_dotted_names* option allows intruders to access your
module's global variables and may allow intruders to execute arbitrary code on
- your machine. Only use this example only within a secure, closed network.
+ your machine. Only use this example within a secure, closed network.
::
diff --git a/Doc/library/zipapp.rst b/Doc/library/zipapp.rst
index cdaba07ab46..2083857312f 100644
--- a/Doc/library/zipapp.rst
+++ b/Doc/library/zipapp.rst
@@ -258,7 +258,7 @@ depending on whether your code is written for Python 2 or 3.
Creating Standalone Applications with zipapp
--------------------------------------------
-Using the :mod:`zipapp` module, it is possible to create self-contained Python
+Using the :mod:`!zipapp` module, it is possible to create self-contained Python
programs, which can be distributed to end users who only need to have a
suitable version of Python installed on their system. The key to doing this
is to bundle all of the application's dependencies into the archive, along
diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst
index ae4e25b13b9..082c4f8d3b4 100644
--- a/Doc/library/zipfile.rst
+++ b/Doc/library/zipfile.rst
@@ -82,7 +82,7 @@ The module defines the following items:
Class used to represent information about a member of an archive. Instances
of this class are returned by the :meth:`.getinfo` and :meth:`.infolist`
- methods of :class:`ZipFile` objects. Most users of the :mod:`zipfile` module
+ methods of :class:`ZipFile` objects. Most users of the :mod:`!zipfile` module
will not need to create these, but only use those created by this
module. *filename* should be the full name of the archive member, and
*date_time* should be a tuple containing six fields which describe the time
@@ -209,7 +209,7 @@ ZipFile objects
If *allowZip64* is ``True`` (the default) zipfile will create ZIP files that
use the ZIP64 extensions when the zipfile is larger than 4 GiB. If it is
- ``false`` :mod:`zipfile` will raise an exception when the ZIP file would
+ ``false`` :mod:`!zipfile` will raise an exception when the ZIP file would
require ZIP64 extensions.
The *compresslevel* parameter controls the compression level to use when
@@ -957,7 +957,7 @@ Instances have the following methods and attributes:
Command-line interface
----------------------
-The :mod:`zipfile` module provides a simple command-line interface to interact
+The :mod:`!zipfile` module provides a simple command-line interface to interact
with ZIP archives.
If you want to create a new ZIP archive, specify its name after the :option:`-c`
diff --git a/Doc/library/zipimport.rst b/Doc/library/zipimport.rst
index ead87c2d6ad..7c33db6848a 100644
--- a/Doc/library/zipimport.rst
+++ b/Doc/library/zipimport.rst
@@ -12,7 +12,7 @@
This module adds the ability to import Python modules (:file:`\*.py`,
:file:`\*.pyc`) and packages from ZIP-format archives. It is usually not
-needed to use the :mod:`zipimport` module explicitly; it is automatically used
+needed to use the :mod:`!zipimport` module explicitly; it is automatically used
by the built-in :keyword:`import` mechanism for :data:`sys.path` items that are paths
to ZIP archives.
@@ -184,7 +184,7 @@ Examples
--------
Here is an example that imports a module from a ZIP archive - note that the
-:mod:`zipimport` module is not explicitly used.
+:mod:`!zipimport` module is not explicitly used.
.. code-block:: shell-session
diff --git a/Doc/library/zoneinfo.rst b/Doc/library/zoneinfo.rst
index efd28b31ef2..6f0b84012f0 100644
--- a/Doc/library/zoneinfo.rst
+++ b/Doc/library/zoneinfo.rst
@@ -13,9 +13,9 @@
--------------
-The :mod:`zoneinfo` module provides a concrete time zone implementation to
+The :mod:`!zoneinfo` module provides a concrete time zone implementation to
support the IANA time zone database as originally specified in :pep:`615`. By
-default, :mod:`zoneinfo` uses the system's time zone data if available; if no
+default, :mod:`!zoneinfo` uses the system's time zone data if available; if no
system time zone data is available, the library will fall back to using the
first-party :pypi:`tzdata` package available on PyPI.
diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
index 52bae88607a..ed73f6c068c 100644
--- a/Doc/reference/compound_stmts.rst
+++ b/Doc/reference/compound_stmts.rst
@@ -544,9 +544,9 @@ The following code::
is semantically equivalent to::
manager = (EXPRESSION)
- enter = type(manager).__enter__
- exit = type(manager).__exit__
- value = enter(manager)
+ enter = manager.__enter__
+ exit = manager.__exit__
+ value = enter()
hit_except = False
try:
@@ -554,11 +554,14 @@ is semantically equivalent to::
SUITE
except:
hit_except = True
- if not exit(manager, *sys.exc_info()):
+ if not exit(*sys.exc_info()):
raise
finally:
if not hit_except:
- exit(manager, None, None, None)
+ exit(None, None, None)
+
+except that implicit :ref:`special method lookup <special-lookup>` is used
+for :meth:`~object.__enter__` and :meth:`~object.__exit__`.
With more than one item, the context managers are processed as if multiple
:keyword:`with` statements were nested::
@@ -1563,13 +1566,12 @@ The following code::
Is semantically equivalent to::
- iter = (ITER)
- iter = type(iter).__aiter__(iter)
+ iter = (ITER).__aiter__()
running = True
while running:
try:
- TARGET = await type(iter).__anext__(iter)
+ TARGET = await iter.__anext__()
except StopAsyncIteration:
running = False
else:
@@ -1577,7 +1579,8 @@ Is semantically equivalent to::
else:
SUITE2
-See also :meth:`~object.__aiter__` and :meth:`~object.__anext__` for details.
+except that implicit :ref:`special method lookup <special-lookup>` is used
+for :meth:`~object.__aiter__` and :meth:`~object.__anext__`.
It is a :exc:`SyntaxError` to use an ``async for`` statement outside the
body of a coroutine function.
@@ -1603,9 +1606,9 @@ The following code::
is semantically equivalent to::
manager = (EXPRESSION)
- aenter = type(manager).__aenter__
- aexit = type(manager).__aexit__
- value = await aenter(manager)
+ aenter = manager.__aenter__
+ aexit = manager.__aexit__
+ value = await aenter()
hit_except = False
try:
@@ -1613,13 +1616,14 @@ is semantically equivalent to::
SUITE
except:
hit_except = True
- if not await aexit(manager, *sys.exc_info()):
+ if not await aexit(*sys.exc_info()):
raise
finally:
if not hit_except:
- await aexit(manager, None, None, None)
+ await aexit(None, None, None)
-See also :meth:`~object.__aenter__` and :meth:`~object.__aexit__` for details.
+except that implicit :ref:`special method lookup <special-lookup>` is used
+for :meth:`~object.__aenter__` and :meth:`~object.__aexit__`.
It is a :exc:`SyntaxError` to use an ``async with`` statement outside the
body of a coroutine function.
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index ed9389a0d90..e085acded93 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -290,6 +290,7 @@ floating-point numbers. The same caveats apply as for floating-point numbers.
The real and imaginary parts of a complex number ``z`` can be retrieved through
the read-only attributes ``z.real`` and ``z.imag``.
+.. _datamodel-sequences:
Sequences
---------
@@ -309,12 +310,25 @@ including built-in sequences, interpret negative subscripts by adding the
sequence length. For example, ``a[-2]`` equals ``a[n-2]``, the second to last
item of sequence a with length ``n``.
-.. index:: single: slicing
+The resulting value must be a nonnegative integer less than the number of items
+in the sequence. If it is not, an :exc:`IndexError` is raised.
-Sequences also support slicing: ``a[i:j]`` selects all items with index *k* such
-that *i* ``<=`` *k* ``<`` *j*. When used as an expression, a slice is a
-sequence of the same type. The comment above about negative indexes also applies
+.. index::
+ single: slicing
+ single: start (slice object attribute)
+ single: stop (slice object attribute)
+ single: step (slice object attribute)
+
+Sequences also support slicing: ``a[start:stop]`` selects all items with index *k* such
+that *start* ``<=`` *k* ``<`` *stop*. When used as an expression, a slice is a
+sequence of the same type. The comment above about negative subscripts also applies
to negative slice positions.
+Note that no error is raised if a slice position is less than zero or larger
+than the length of the sequence.
+
+If *start* is missing or :data:`None`, slicing behaves as if *start* was zero.
+If *stop* is missing or ``None``, slicing behaves as if *stop* was equal to
+the length of the sequence.
Some sequences also support "extended slicing" with a third "step" parameter:
``a[i:j:k]`` selects all items of *a* with index *x* where ``x = i + n*k``, *n*
@@ -345,17 +359,22 @@ Strings
pair: built-in function; chr
pair: built-in function; ord
single: character
- single: integer
+ pair: string; item
single: Unicode
- A string is a sequence of values that represent Unicode code points.
- All the code points in the range ``U+0000 - U+10FFFF`` can be
- represented in a string. Python doesn't have a :c:expr:`char` type;
- instead, every code point in the string is represented as a string
- object with length ``1``. The built-in function :func:`ord`
+ A string (:class:`str`) is a sequence of values that represent
+ :dfn:`characters`, or more formally, *Unicode code points*.
+ All the code points in the range ``0`` to ``0x10FFFF`` can be
+ represented in a string.
+
+ Python doesn't have a dedicated *character* type.
+ Instead, every code point in the string is represented as a string
+ object with length ``1``.
+
+ The built-in function :func:`ord`
converts a code point from its string form to an integer in the
- range ``0 - 10FFFF``; :func:`chr` converts an integer in the range
- ``0 - 10FFFF`` to the corresponding length ``1`` string object.
+ range ``0`` to ``0x10FFFF``; :func:`chr` converts an integer in the range
+ ``0`` to ``0x10FFFF`` to the corresponding length ``1`` string object.
:meth:`str.encode` can be used to convert a :class:`str` to
:class:`bytes` using the given text encoding, and
:meth:`bytes.decode` can be used to achieve the opposite.
@@ -366,7 +385,7 @@ Tuples
pair: singleton; tuple
pair: empty; tuple
- The items of a tuple are arbitrary Python objects. Tuples of two or
+ The items of a :class:`tuple` are arbitrary Python objects. Tuples of two or
more items are formed by comma-separated lists of expressions. A tuple
of one item (a 'singleton') can be formed by affixing a comma to an
expression (an expression by itself does not create a tuple, since
@@ -376,7 +395,7 @@ Tuples
Bytes
.. index:: bytes, byte
- A bytes object is an immutable array. The items are 8-bit bytes,
+ A :class:`bytes` object is an immutable array. The items are 8-bit bytes,
represented by integers in the range 0 <= x < 256. Bytes literals
(like ``b'abc'``) and the built-in :func:`bytes` constructor
can be used to create bytes objects. Also, bytes objects can be
@@ -461,6 +480,8 @@ Frozen sets
a dictionary key.
+.. _datamodel-mappings:
+
Mappings
--------
@@ -1396,12 +1417,28 @@ also :func:`os.popen`, :func:`os.fdopen`, and the
:meth:`~socket.socket.makefile` method of socket objects (and perhaps by
other functions or methods provided by extension modules).
+File objects implement common methods, listed below, to simplify usage in
+generic code. They are expected to be :ref:`context-managers`.
+
The objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are
initialized to file objects corresponding to the interpreter's standard
input, output and error streams; they are all open in text mode and
therefore follow the interface defined by the :class:`io.TextIOBase`
abstract class.
+.. method:: file.read(size=-1, /)
+
+ Retrieve up to *size* data from the file. As a convenience if *size* is
+ unspecified or -1 retrieve all data available.
+
+.. method:: file.write(data, /)
+
+ Store *data* to the file.
+
+.. method:: file.close()
+
+ Flush any buffers and close the underlying file.
+
Internal types
--------------
@@ -3205,43 +3242,55 @@ through the object's keys; for sequences, it should iterate through the values.
.. versionadded:: 3.4
-.. index:: pair: object; slice
+.. method:: object.__getitem__(self, subscript)
-.. note::
+ Called to implement *subscription*, that is, ``self[subscript]``.
+ See :ref:`subscriptions` for details on the syntax.
+
+ There are two types of built-in objects that support subscription
+ via :meth:`!__getitem__`:
- Slicing is done exclusively with the following three methods. A call like ::
+ - **sequences**, where *subscript* (also called
+ :term:`index`) should be an integer or a :class:`slice` object.
+ See the :ref:`sequence documentation <datamodel-sequences>` for the expected
+ behavior, including handling :class:`slice` objects and negative indices.
+ - **mappings**, where *subscript* is also called the :term:`key`.
+ See :ref:`mapping documentation <datamodel-mappings>` for the expected
+ behavior.
- a[1:2] = b
+ If *subscript* is of an inappropriate type, :meth:`!__getitem__`
+ should raise :exc:`TypeError`.
+ If *subscript* has an inappropriate value, :meth:`!__getitem__`
+ should raise an :exc:`LookupError` or one of its subclasses
+ (:exc:`IndexError` for sequences; :exc:`KeyError` for mappings).
- is translated to ::
+ .. index:: pair: object; slice
+
+ .. note::
- a[slice(1, 2, None)] = b
+ Slicing is handled by :meth:`!__getitem__`, :meth:`~object.__setitem__`,
+ and :meth:`~object.__delitem__`.
+ A call like ::
- and so forth. Missing slice items are always filled in with ``None``.
+ a[1:2] = b
+ is translated to ::
-.. method:: object.__getitem__(self, key)
+ a[slice(1, 2, None)] = b
- Called to implement evaluation of ``self[key]``. For :term:`sequence` types,
- the accepted keys should be integers. Optionally, they may support
- :class:`slice` objects as well. Negative index support is also optional.
- If *key* is
- of an inappropriate type, :exc:`TypeError` may be raised; if *key* is a value
- outside the set of indexes for the sequence (after any special
- interpretation of negative values), :exc:`IndexError` should be raised. For
- :term:`mapping` types, if *key* is missing (not in the container),
- :exc:`KeyError` should be raised.
+ and so forth. Missing slice items are always filled in with ``None``.
.. note::
- :keyword:`for` loops expect that an :exc:`IndexError` will be raised for
- illegal indexes to allow proper detection of the end of the sequence.
+ The sequence iteration protocol (used, for example, in :keyword:`for`
+ loops), expects that an :exc:`IndexError` will be raised for illegal
+ indexes to allow proper detection of the end of a sequence.
.. note::
- When :ref:`subscripting<subscriptions>` a *class*, the special
+ When :ref:`subscripting <subscriptions>` a *class*, the special
class method :meth:`~object.__class_getitem__` may be called instead of
- ``__getitem__()``. See :ref:`classgetitem-versus-getitem` for more
+ :meth:`!__getitem__`. See :ref:`classgetitem-versus-getitem` for more
details.
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index 165dfa69f88..42b13b61e53 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -9,9 +9,11 @@ Expressions
This chapter explains the meaning of the elements of expressions in Python.
-**Syntax Notes:** In this and the following chapters, extended BNF notation will
-be used to describe syntax, not lexical analysis. When (one alternative of) a
-syntax rule has the form
+**Syntax Notes:** In this and the following chapters,
+:ref:`grammar notation <notation>` will be used to describe syntax,
+not lexical analysis.
+
+When (one alternative of) a syntax rule has the form:
.. productionlist:: python-grammar
name: othername
@@ -29,17 +31,13 @@ Arithmetic conversions
When a description of an arithmetic operator below uses the phrase "the numeric
arguments are converted to a common real type", this means that the operator
-implementation for built-in types works as follows:
-
-* If both arguments are complex numbers, no conversion is performed;
-
-* if either argument is a complex or a floating-point number, the other is converted to a floating-point number;
+implementation for built-in numeric types works as described in the
+:ref:`Numeric Types <stdtypes-mixed-arithmetic>` section of the standard
+library documentation.
-* otherwise, both must be integers and no conversion is necessary.
-
-Some additional rules apply for certain operators (e.g., a string as a left
-argument to the '%' operator). Extensions must define their own conversion
-behavior.
+Some additional rules apply for certain operators and non-numeric operands
+(for example, a string as a left argument to the ``%`` operator).
+Extensions must define their own conversion behavior.
.. _atoms:
@@ -49,15 +47,57 @@ Atoms
.. index:: atom
-Atoms are the most basic elements of expressions. The simplest atoms are
-identifiers or literals. Forms enclosed in parentheses, brackets or braces are
-also categorized syntactically as atoms. The syntax for atoms is:
+Atoms are the most basic elements of expressions.
+The simplest atoms are :ref:`names <identifiers>` or literals.
+Forms enclosed in parentheses, brackets or braces are also categorized
+syntactically as atoms.
-.. productionlist:: python-grammar
- atom: `identifier` | `literal` | `enclosure`
- enclosure: `parenth_form` | `list_display` | `dict_display` | `set_display`
- : | `generator_expression` | `yield_atom`
+Formally, the syntax for atoms is:
+
+.. grammar-snippet::
+ :group: python-grammar
+
+ atom:
+ | 'True'
+ | 'False'
+ | 'None'
+ | '...'
+ | `identifier`
+ | `literal`
+ | `enclosure`
+ enclosure:
+ | `parenth_form`
+ | `list_display`
+ | `dict_display`
+ | `set_display`
+ | `generator_expression`
+ | `yield_atom`
+
+
+.. _atom-singletons:
+Built-in constants
+------------------
+
+The keywords ``True``, ``False``, and ``None`` name
+:ref:`built-in constants <built-in-consts>`.
+The token ``...`` names the :py:data:`Ellipsis` constant.
+
+Evaluation of these atoms yields the corresponding value.
+
+.. note::
+
+ Several more built-in constants are available as global variables,
+ but only the ones mentioned here are :ref:`keywords <keywords>`.
+ In particular, these names cannot be reassigned or used as attributes:
+
+ .. code-block:: pycon
+
+ >>> False = 123
+ File "<input>", line 1
+ False = 123
+ ^^^^^
+ SyntaxError: cannot assign to False
.. _atom-identifiers:
@@ -131,51 +171,104 @@ Literals
.. index:: single: literal
-Python supports string and bytes literals and various numeric literals:
+A :dfn:`literal` is a textual representation of a value.
+Python supports numeric, string and bytes literals.
+:ref:`Format strings <f-strings>` and :ref:`template strings <t-strings>`
+are treated as string literals.
+
+Numeric literals consist of a single :token:`NUMBER <python-grammar:NUMBER>`
+token, which names an integer, floating-point number, or an imaginary number.
+See the :ref:`numbers` section in Lexical analysis documentation for details.
+
+String and bytes literals may consist of several tokens.
+See section :ref:`string-concatenation` for details.
+
+Note that negative and complex numbers, like ``-3`` or ``3+4.2j``,
+are syntactically not literals, but :ref:`unary <unary>` or
+:ref:`binary <binary>` arithmetic operations involving the ``-`` or ``+``
+operator.
+
+Evaluation of a literal yields an object of the given type
+(:class:`int`, :class:`float`, :class:`complex`, :class:`str`,
+:class:`bytes`, or :class:`~string.templatelib.Template`) with the given value.
+The value may be approximated in the case of floating-point
+and imaginary literals.
+
+The formal grammar for literals is:
.. grammar-snippet::
:group: python-grammar
literal: `strings` | `NUMBER`
-Evaluation of a literal yields an object of the given type (string, bytes,
-integer, floating-point number, complex number) with the given value. The value
-may be approximated in the case of floating-point and imaginary (complex)
-literals.
-See section :ref:`literals` for details.
-See section :ref:`string-concatenation` for details on ``strings``.
-
.. index::
triple: immutable; data; type
pair: immutable; object
+Literals and object identity
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
All literals correspond to immutable data types, and hence the object's identity
is less important than its value. Multiple evaluations of literals with the
same value (either the same occurrence in the program text or a different
occurrence) may obtain the same object or a different object with the same
value.
+.. admonition:: CPython implementation detail
+
+ For example, in CPython, *small* integers with the same value evaluate
+ to the same object::
+
+ >>> x = 7
+ >>> y = 7
+ >>> x is y
+ True
+
+ However, large integers evaluate to different objects::
+
+ >>> x = 123456789
+ >>> y = 123456789
+ >>> x is y
+ False
+
+ This behavior may change in future versions of CPython.
+ In particular, the boundary between "small" and "large" integers has
+ already changed in the past.
+
+ CPython will emit a :py:exc:`SyntaxWarning` when you compare literals
+ using ``is``::
+
+ >>> x = 7
+ >>> x is 7
+ <input>:1: SyntaxWarning: "is" with 'int' literal. Did you mean "=="?
+ True
+
+ See :ref:`faq-identity-with-is` for more information.
+
+:ref:`Template strings <t-strings>` are immutable but may reference mutable
+objects as :class:`~string.templatelib.Interpolation` values.
+For the purposes of this section, two t-strings have the "same value" if
+both their structure and the *identity* of the values match.
+
+.. impl-detail::
+
+ Currently, each evaluation of a template string results in
+ a different object.
+
.. _string-concatenation:
String literal concatenation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Multiple adjacent string or bytes literals (delimited by whitespace), possibly
+Multiple adjacent string or bytes literals, possibly
using different quoting conventions, are allowed, and their meaning is the same
as their concatenation::
>>> "hello" 'world'
"helloworld"
-Formally:
-
-.. grammar-snippet::
- :group: python-grammar
-
- strings: ( `STRING` | `fstring`)+ | `tstring`+
-
This feature is defined at the syntactical level, so it only works with literals.
To concatenate string expressions at run time, the '+' operator may be used::
@@ -208,6 +301,13 @@ string literals::
>>> t"Hello" t"{name}!"
Template(strings=('Hello', '!'), interpolations=(...))
+Formally:
+
+.. grammar-snippet::
+ :group: python-grammar
+
+ strings: (`STRING` | `fstring`)+ | `tstring`+
+
.. _parenthesized:
@@ -893,7 +993,7 @@ Primaries represent the most tightly bound operations of the language. Their
syntax is:
.. productionlist:: python-grammar
- primary: `atom` | `attributeref` | `subscription` | `slicing` | `call`
+ primary: `atom` | `attributeref` | `subscription` | `call`
.. _attribute-references:
@@ -932,8 +1032,8 @@ method, that method is called as a fallback.
.. _subscriptions:
-Subscriptions
--------------
+Subscriptions and slicings
+--------------------------
.. index::
single: subscription
@@ -948,67 +1048,74 @@ Subscriptions
pair: object; dictionary
pair: sequence; item
-The subscription of an instance of a :ref:`container class <sequence-types>`
-will generally select an element from the container. The subscription of a
-:term:`generic class <generic type>` will generally return a
-:ref:`GenericAlias <types-genericalias>` object.
-
-.. productionlist:: python-grammar
- subscription: `primary` "[" `flexible_expression_list` "]"
-
-When an object is subscripted, the interpreter will evaluate the primary and
-the expression list.
+The :dfn:`subscription` syntax is usually used for selecting an element from a
+:ref:`container <sequence-types>` -- for example, to get a value from
+a :class:`dict`::
-The primary must evaluate to an object that supports subscription. An object
-may support subscription through defining one or both of
-:meth:`~object.__getitem__` and :meth:`~object.__class_getitem__`. When the
-primary is subscripted, the evaluated result of the expression list will be
-passed to one of these methods. For more details on when ``__class_getitem__``
-is called instead of ``__getitem__``, see :ref:`classgetitem-versus-getitem`.
+ >>> digits_by_name = {'one': 1, 'two': 2}
+ >>> digits_by_name['two'] # Subscripting a dictionary using the key 'two'
+ 2
-If the expression list contains at least one comma, or if any of the expressions
-are starred, the expression list will evaluate to a :class:`tuple` containing
-the items of the expression list. Otherwise, the expression list will evaluate
-to the value of the list's sole member.
+In the subscription syntax, the object being subscribed -- a
+:ref:`primary <primaries>` -- is followed by a :dfn:`subscript` in
+square brackets.
+In the simplest case, the subscript is a single expression.
+
+Depending on the type of the object being subscribed, the subscript is
+sometimes called a :term:`key` (for mappings), :term:`index` (for sequences),
+or *type argument* (for :term:`generic types <generic type>`).
+Syntactically, these are all equivalent::
+
+ >>> colors = ['red', 'blue', 'green', 'black']
+ >>> colors[3] # Subscripting a list using the index 3
+ 'black'
+
+ >>> list[str] # Parameterizing the list type using the type argument str
+ list[str]
+
+At runtime, the interpreter will evaluate the primary and
+the subscript, and call the primary's :meth:`~object.__getitem__` or
+:meth:`~object.__class_getitem__` :term:`special method` with the subscript
+as argument.
+For more details on which of these methods is called, see
+:ref:`classgetitem-versus-getitem`.
+
+To show how subscription works, we can define a custom object that
+implements :meth:`~object.__getitem__` and prints out the value of
+the subscript::
+
+ >>> class SubscriptionDemo:
+ ... def __getitem__(self, key):
+ ... print(f'subscripted with: {key!r}')
+ ...
+ >>> demo = SubscriptionDemo()
+ >>> demo[1]
+ subscripted with: 1
+ >>> demo['a' * 3]
+ subscripted with: 'aaa'
-.. versionchanged:: 3.11
- Expressions in an expression list may be starred. See :pep:`646`.
-
-For built-in objects, there are two types of objects that support subscription
-via :meth:`~object.__getitem__`:
-
-1. Mappings. If the primary is a :term:`mapping`, the expression list must
- evaluate to an object whose value is one of the keys of the mapping, and the
- subscription selects the value in the mapping that corresponds to that key.
- An example of a builtin mapping class is the :class:`dict` class.
-2. Sequences. If the primary is a :term:`sequence`, the expression list must
- evaluate to an :class:`int` or a :class:`slice` (as discussed in the
- following section). Examples of builtin sequence classes include the
- :class:`str`, :class:`list` and :class:`tuple` classes.
-
-The formal syntax makes no special provision for negative indices in
-:term:`sequences <sequence>`. However, built-in sequences all provide a :meth:`~object.__getitem__`
-method that interprets negative indices by adding the length of the sequence
-to the index so that, for example, ``x[-1]`` selects the last item of ``x``. The
-resulting value must be a nonnegative integer less than the number of items in
-the sequence, and the subscription selects the item whose index is that value
-(counting from zero). Since the support for negative indices and slicing
-occurs in the object's :meth:`~object.__getitem__` method, subclasses overriding
-this method will need to explicitly add that support.
+See :meth:`~object.__getitem__` documentation for how built-in types handle
+subscription.
-.. index::
- single: character
- pair: string; item
+Subscriptions may also be used as targets in :ref:`assignment <assignment>` or
+:ref:`deletion <del>` statements.
+In these cases, the interpreter will call the subscripted object's
+:meth:`~object.__setitem__` or :meth:`~object.__delitem__`
+:term:`special method`, respectively, instead of :meth:`~object.__getitem__`.
-A :class:`string <str>` is a special kind of sequence whose items are
-*characters*. A character is not a separate data type but a
-string of exactly one character.
+.. code-block::
+ >>> colors = ['red', 'blue', 'green', 'black']
+ >>> colors[3] = 'white' # Setting item at index
+ >>> colors
+ ['red', 'blue', 'green', 'white']
+ >>> del colors[3] # Deleting item at index 3
+ >>> colors
+ ['red', 'blue', 'green']
-.. _slicings:
+All advanced forms of *subscript* documented in the following sections
+are also usable for assignment and deletion.
-Slicings
---------
.. index::
single: slicing
@@ -1022,43 +1129,111 @@ Slicings
pair: object; tuple
pair: object; list
-A slicing selects a range of items in a sequence object (e.g., a string, tuple
-or list). Slicings may be used as expressions or as targets in assignment or
-:keyword:`del` statements. The syntax for a slicing:
+.. _slicings:
-.. productionlist:: python-grammar
- slicing: `primary` "[" `slice_list` "]"
- slice_list: `slice_item` ("," `slice_item`)* [","]
- slice_item: `expression` | `proper_slice`
- proper_slice: [`lower_bound`] ":" [`upper_bound`] [ ":" [`stride`] ]
- lower_bound: `expression`
- upper_bound: `expression`
- stride: `expression`
-
-There is ambiguity in the formal syntax here: anything that looks like an
-expression list also looks like a slice list, so any subscription can be
-interpreted as a slicing. Rather than further complicating the syntax, this is
-disambiguated by defining that in this case the interpretation as a subscription
-takes priority over the interpretation as a slicing (this is the case if the
-slice list contains no proper slice).
+Slicings
+^^^^^^^^
-.. index::
- single: start (slice object attribute)
- single: stop (slice object attribute)
- single: step (slice object attribute)
-
-The semantics for a slicing are as follows. The primary is indexed (using the
-same :meth:`~object.__getitem__` method as
-normal subscription) with a key that is constructed from the slice list, as
-follows. If the slice list contains at least one comma, the key is a tuple
-containing the conversion of the slice items; otherwise, the conversion of the
-lone slice item is the key. The conversion of a slice item that is an
-expression is that expression. The conversion of a proper slice is a slice
-object (see section :ref:`types`) whose :attr:`~slice.start`,
-:attr:`~slice.stop` and :attr:`~slice.step` attributes are the values of the
-expressions given as lower bound, upper bound and stride, respectively,
-substituting ``None`` for missing expressions.
+A more advanced form of subscription, :dfn:`slicing`, is commonly used
+to extract a portion of a :ref:`sequence <datamodel-sequences>`.
+In this form, the subscript is a :term:`slice`: up to three
+expressions separated by colons.
+Any of the expressions may be omitted, but a slice must contain at least one
+colon::
+
+ >>> number_names = ['zero', 'one', 'two', 'three', 'four', 'five']
+ >>> number_names[1:3]
+ ['one', 'two']
+ >>> number_names[1:]
+ ['one', 'two', 'three', 'four', 'five']
+ >>> number_names[:3]
+ ['zero', 'one', 'two']
+ >>> number_names[:]
+ ['zero', 'one', 'two', 'three', 'four', 'five']
+ >>> number_names[::2]
+ ['zero', 'two', 'four']
+ >>> number_names[:-3]
+ ['zero', 'one', 'two']
+ >>> del number_names[4:]
+ >>> number_names
+ ['zero', 'one', 'two', 'three']
+
+When a slice is evaluated, the interpreter constructs a :class:`slice` object
+whose :attr:`~slice.start`, :attr:`~slice.stop` and
+:attr:`~slice.step` attributes, respectively, are the results of the
+expressions between the colons.
+Any missing expression evaluates to :const:`None`.
+This :class:`!slice` object is then passed to the :meth:`~object.__getitem__`
+or :meth:`~object.__class_getitem__` :term:`special method`, as above. ::
+
+ # continuing with the SubscriptionDemo instance defined above:
+ >>> demo[2:3]
+ subscripted with: slice(2, 3, None)
+ >>> demo[::'spam']
+ subscripted with: slice(None, None, 'spam')
+
+
+Comma-separated subscripts
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The subscript can also be given as two or more comma-separated expressions
+or slices::
+
+ # continuing with the SubscriptionDemo instance defined above:
+ >>> demo[1, 2, 3]
+ subscripted with: (1, 2, 3)
+ >>> demo[1:2, 3]
+ subscripted with: (slice(1, 2, None), 3)
+
+This form is commonly used with numerical libraries for slicing
+multi-dimensional data.
+In this case, the interpreter constructs a :class:`tuple` of the results of the
+expressions or slices, and passes this tuple to the :meth:`~object.__getitem__`
+or :meth:`~object.__class_getitem__` :term:`special method`, as above.
+
+The subscript may also be given as a single expression or slice followed
+by a comma, to specify a one-element tuple::
+
+ >>> demo['spam',]
+ subscripted with: ('spam',)
+
+
+"Starred" subscriptions
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 3.11
+ Expressions in *tuple_slices* may be starred. See :pep:`646`.
+
+The subscript can also contain a starred expression.
+In this case, the interpreter unpacks the result into a tuple, and passes
+this tuple to :meth:`~object.__getitem__` or :meth:`~object.__class_getitem__`::
+
+ # continuing with the SubscriptionDemo instance defined above:
+ >>> demo[*range(10)]
+ subscripted with: (0, 1, 2, 3, 4, 5, 6, 7, 8, 9)
+
+Starred expressions may be combined with comma-separated expressions
+and slices::
+
+ >>> demo['a', 'b', *range(3), 'c']
+ subscripted with: ('a', 'b', 0, 1, 2, 'c')
+
+
+Formal subscription grammar
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. grammar-snippet::
+ :group: python-grammar
+
+ subscription: `primary` '[' `subscript` ']'
+ subscript: `single_subscript` | `tuple_subscript`
+ single_subscript: `proper_slice` | `assignment_expression`
+ proper_slice: [`expression`] ":" [`expression`] [ ":" [`expression`] ]
+ tuple_subscript: ','.(`single_subscript` | `starred_expression`)+ [',']
+Recall that the ``|`` operator :ref:`denotes ordered choice <notation>`.
+Specifically, in :token:`!subscript`, if both alternatives would match, the
+first (:token:`!single_subscript`) has priority.
.. index::
pair: object; callable
@@ -1297,8 +1472,9 @@ for the operands): ``-1**2`` results in ``-1``.
The power operator has the same semantics as the built-in :func:`pow` function,
when called with two arguments: it yields its left argument raised to the power
-of its right argument. The numeric arguments are first converted to a common
-type, and the result is of that type.
+of its right argument.
+Numeric arguments are first :ref:`converted to a common type <stdtypes-mixed-arithmetic>`,
+and the result is of that type.
For int operands, the result has the same type as the operands unless the second
argument is negative; in that case, all arguments are converted to float and a
@@ -1384,9 +1560,10 @@ operators and one for additive operators:
The ``*`` (multiplication) operator yields the product of its arguments. The
arguments must either both be numbers, or one argument must be an integer and
-the other must be a sequence. In the former case, the numbers are converted to a
-common real type and then multiplied together. In the latter case, sequence
-repetition is performed; a negative repetition factor yields an empty sequence.
+the other must be a sequence. In the former case, the numbers are
+:ref:`converted to a common real type <stdtypes-mixed-arithmetic>` and then
+multiplied together. In the latter case, sequence repetition is performed;
+a negative repetition factor yields an empty sequence.
This operation can be customized using the special :meth:`~object.__mul__` and
:meth:`~object.__rmul__` methods.
@@ -1414,7 +1591,8 @@ This operation can be customized using the special :meth:`~object.__matmul__` an
pair: operator; //
The ``/`` (division) and ``//`` (floor division) operators yield the quotient of
-their arguments. The numeric arguments are first converted to a common type.
+their arguments. The numeric arguments are first
+:ref:`converted to a common type <stdtypes-mixed-arithmetic>`.
Division of integers yields a float, while floor division of integers results in an
integer; the result is that of mathematical division with the 'floor' function
applied to the result. Division by zero raises the :exc:`ZeroDivisionError`
@@ -1430,8 +1608,9 @@ The floor division operation can be customized using the special
pair: operator; % (percent)
The ``%`` (modulo) operator yields the remainder from the division of the first
-argument by the second. The numeric arguments are first converted to a common
-type. A zero right argument raises the :exc:`ZeroDivisionError` exception. The
+argument by the second. The numeric arguments are first
+:ref:`converted to a common type <stdtypes-mixed-arithmetic>`.
+A zero right argument raises the :exc:`ZeroDivisionError` exception. The
arguments may be floating-point numbers, e.g., ``3.14%0.7`` equals ``0.34``
(since ``3.14`` equals ``4*0.7 + 0.34``.) The modulo operator always yields a
result with the same sign as its second operand (or zero); the absolute value of
@@ -1462,7 +1641,9 @@ floating-point number using the :func:`abs` function if appropriate.
The ``+`` (addition) operator yields the sum of its arguments. The arguments
must either both be numbers or both be sequences of the same type. In the
-former case, the numbers are converted to a common real type and then added together.
+former case, the numbers are
+:ref:`converted to a common real type <stdtypes-mixed-arithmetic>` and then
+added together.
In the latter case, the sequences are concatenated.
This operation can be customized using the special :meth:`~object.__add__` and
@@ -1477,8 +1658,9 @@ This operation can be customized using the special :meth:`~object.__add__` and
single: operator; - (minus)
single: - (minus); binary operator
-The ``-`` (subtraction) operator yields the difference of its arguments. The
-numeric arguments are first converted to a common real type.
+The ``-`` (subtraction) operator yields the difference of its arguments.
+The numeric arguments are first
+:ref:`converted to a common real type <stdtypes-mixed-arithmetic>`.
This operation can be customized using the special :meth:`~object.__sub__` and
:meth:`~object.__rsub__` methods.
@@ -2076,7 +2258,7 @@ precedence and have a left-to-right chaining feature as described in the
| ``{key: value...}``, | dictionary display, |
| ``{expressions...}`` | set display |
+-----------------------------------------------+-------------------------------------+
-| ``x[index]``, ``x[index:index]``, | Subscription, slicing, |
+| ``x[index]``, ``x[index:index]`` | Subscription (including slicing), |
| ``x(arguments...)``, ``x.attribute`` | call, attribute reference |
+-----------------------------------------------+-------------------------------------+
| :keyword:`await x <await>` | Await expression |
diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index 9c022570e7e..36b30c9b16b 100644
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -91,11 +91,10 @@ attributes or items of mutable objects:
: | "[" [`target_list`] "]"
: | `attributeref`
: | `subscription`
- : | `slicing`
: | "*" `target`
-(See section :ref:`primaries` for the syntax definitions for *attributeref*,
-*subscription*, and *slicing*.)
+(See section :ref:`primaries` for the syntax definitions for *attributeref*
+and *subscription*.)
An assignment statement evaluates the expression list (remember that this can be
a single expression or a comma-separated list, the latter yielding a tuple) and
@@ -107,8 +106,8 @@ right.
pair: target; list
Assignment is defined recursively depending on the form of the target (list).
-When a target is part of a mutable object (an attribute reference, subscription
-or slicing), the mutable object must ultimately perform the assignment and
+When a target is part of a mutable object (an attribute reference or
+subscription), the mutable object must ultimately perform the assignment and
decide about its validity, and may raise an exception if the assignment is
unacceptable. The rules observed by various types and the exceptions raised are
given with the definition of the object types (see section :ref:`types`).
@@ -189,9 +188,14 @@ Assignment of an object to a single target is recursively defined as follows.
pair: object; mutable
* If the target is a subscription: The primary expression in the reference is
- evaluated. It should yield either a mutable sequence object (such as a list)
- or a mapping object (such as a dictionary). Next, the subscript expression is
evaluated.
+ Next, the subscript expression is evaluated.
+ Then, the primary's :meth:`~object.__setitem__` method is called with
+ two arguments: the subscript and the assigned object.
+
+ Typically, :meth:`~object.__setitem__` is defined on mutable sequence objects
+ (such as lists) and mapping objects (such as dictionaries), and behaves as
+ follows.
.. index::
pair: object; sequence
@@ -214,16 +218,13 @@ Assignment of an object to a single target is recursively defined as follows.
object. This can either replace an existing key/value pair with the same key
value, or insert a new key/value pair (if no key with the same value existed).
- For user-defined objects, the :meth:`~object.__setitem__` method is called with
- appropriate arguments.
-
.. index:: pair: slicing; assignment
-* If the target is a slicing: The primary expression in the reference is
- evaluated. It should yield a mutable sequence object (such as a list). The
- assigned object should be a sequence object of the same type. Next, the lower
- and upper bound expressions are evaluated, insofar they are present; defaults
- are zero and the sequence's length. The bounds should evaluate to integers.
+ If the target is a slicing: The primary expression should evaluate to
+ a mutable sequence object (such as a list).
+ The assigned object should be :term:`iterable`.
+ The slicing's lower and upper bounds should be integers; if they are ``None``
+ (or not present), the defaults are zero and the sequence's length.
If either bound is negative, the sequence's length is added to it. The
resulting bounds are clipped to lie between zero and the sequence's length,
inclusive. Finally, the sequence object is asked to replace the slice with
@@ -231,12 +232,6 @@ Assignment of an object to a single target is recursively defined as follows.
from the length of the assigned sequence, thus changing the length of the
target sequence, if the target sequence allows it.
-.. impl-detail::
-
- In the current implementation, the syntax for targets is taken to be the same
- as for expressions, and invalid syntax is rejected during the code generation
- phase, causing less detailed error messages.
-
Although the definition of assignment implies that overlaps between the
left-hand side and the right-hand side are 'simultaneous' (for example ``a, b =
b, a`` swaps two variables), overlaps *within* the collection of assigned-to
@@ -281,7 +276,7 @@ operation and an assignment statement:
.. productionlist:: python-grammar
augmented_assignment_stmt: `augtarget` `augop` (`expression_list` | `yield_expression`)
- augtarget: `identifier` | `attributeref` | `subscription` | `slicing`
+ augtarget: `identifier` | `attributeref` | `subscription`
augop: "+=" | "-=" | "*=" | "@=" | "/=" | "//=" | "%=" | "**="
: | ">>=" | "<<=" | "&=" | "^=" | "|="
@@ -470,7 +465,7 @@ in the same code block. Trying to delete an unbound name raises a
.. index:: pair: attribute; deletion
-Deletion of attribute references, subscriptions and slicings is passed to the
+Deletion of attribute references and subscriptions is passed to the
primary object involved; deletion of a slicing is in general equivalent to
assignment of an empty slice of the right type (but even this is determined by
the sliced object).
@@ -836,7 +831,9 @@ where the :keyword:`import` statement occurs.
The *public names* defined by a module are determined by checking the module's
namespace for a variable named ``__all__``; if defined, it must be a sequence
-of strings which are names defined or imported by that module. The names
+of strings which are names defined or imported by that module.
+Names containing non-ASCII characters must be in the `normalization form`_
+NFKC; see :ref:`lexical-names-nonascii` for details. The names
given in ``__all__`` are all considered public and are required to exist. If
``__all__`` is not defined, the set of public names includes all names found
in the module's namespace which do not begin with an underscore character
@@ -870,6 +867,8 @@ determine dynamically the modules to be loaded.
.. audit-event:: import module,filename,sys.path,sys.meta_path,sys.path_hooks import
+.. _normalization form: https://www.unicode.org/reports/tr15/#Norm_Forms
+
.. _future:
Future statements
diff --git a/Doc/requirements.txt b/Doc/requirements.txt
index d0107744ecb..536ae57e4ef 100644
--- a/Doc/requirements.txt
+++ b/Doc/requirements.txt
@@ -18,4 +18,6 @@ sphinx-notfound-page~=1.0.0
# to install that as well.
python-docs-theme>=2023.3.1,!=2023.7
+linklint
+
-c constraints.txt
diff --git a/Doc/tools/check-html-ids.py b/Doc/tools/check-html-ids.py
new file mode 100644
index 00000000000..8e8e0a581df
--- /dev/null
+++ b/Doc/tools/check-html-ids.py
@@ -0,0 +1,181 @@
+from compression import gzip
+import concurrent.futures
+from pathlib import Path
+import html.parser
+import functools
+import argparse
+import json
+import sys
+import re
+
+
+IGNORED_ID_RE = re.compile(
+ r"""
+ index-\d+
+ | id\d+
+ | [_a-z]+_\d+
+""",
+ re.VERBOSE,
+)
+
+
+class IDGatherer(html.parser.HTMLParser):
+ def __init__(self, ids):
+ super().__init__()
+ self.__ids = ids
+
+ def handle_starttag(self, tag, attrs):
+ for name, value in attrs:
+ if name == 'id':
+ if not IGNORED_ID_RE.fullmatch(value):
+ self.__ids.add(value)
+
+
+def get_ids_from_file(path):
+ ids = set()
+ gatherer = IDGatherer(ids)
+ with path.open(encoding='utf-8') as file:
+ while chunk := file.read(4096):
+ gatherer.feed(chunk)
+ return ids
+
+
+def gather_ids(htmldir, *, verbose_print):
+ if not htmldir.joinpath('objects.inv').exists():
+ raise ValueError(f'{htmldir!r} is not a Sphinx HTML output directory')
+
+ if sys._is_gil_enabled:
+ pool = concurrent.futures.ProcessPoolExecutor()
+ else:
+ pool = concurrent.futures.ThreadPoolExecutor()
+ tasks = {}
+ for path in htmldir.glob('**/*.html'):
+ relative_path = path.relative_to(htmldir)
+ if '_static' in relative_path.parts:
+ continue
+ if 'whatsnew' in relative_path.parts:
+ continue
+ tasks[relative_path] = pool.submit(get_ids_from_file, path=path)
+
+ ids_by_page = {}
+ for relative_path, future in tasks.items():
+ verbose_print(relative_path)
+ ids = future.result()
+ ids_by_page[str(relative_path)] = ids
+ verbose_print(f' - {len(ids)} ids found')
+
+ common = set.intersection(*ids_by_page.values())
+ verbose_print(f'Filtering out {len(common)} common ids')
+ for key, page_ids in ids_by_page.items():
+ ids_by_page[key] = sorted(page_ids - common)
+
+ return ids_by_page
+
+
+def do_check(baseline, checked, excluded, *, verbose_print):
+ successful = True
+ for name, baseline_ids in sorted(baseline.items()):
+ try:
+ checked_ids = checked[name]
+ except KeyError:
+ successful = False
+ print(f'{name}: (page missing)')
+ print()
+ else:
+ missing_ids = set(baseline_ids) - set(checked_ids)
+ if missing_ids:
+ missing_ids = {
+ a
+ for a in missing_ids
+ if not IGNORED_ID_RE.fullmatch(a)
+ and (name, a) not in excluded
+ }
+ if missing_ids:
+ successful = False
+ for missing_id in sorted(missing_ids):
+ print(f'{name}: {missing_id}')
+ print()
+ return successful
+
+
+def main(argv):
+ parser = argparse.ArgumentParser()
+ parser.add_argument(
+ '-v',
+ '--verbose',
+ action='store_true',
+ help='print out more information',
+ )
+ subparsers = parser.add_subparsers(dest='command', required=True)
+
+ collect = subparsers.add_parser(
+ 'collect', help='collect IDs from a set of HTML files'
+ )
+ collect.add_argument(
+ 'htmldir', type=Path, help='directory with HTML documentation'
+ )
+ collect.add_argument(
+ '-o',
+ '--outfile',
+ help='File to save the result in; default <htmldir>/html-ids.json.gz',
+ )
+
+ check = subparsers.add_parser('check', help='check two archives of IDs')
+ check.add_argument(
+ 'baseline_file', type=Path, help='file with baseline IDs'
+ )
+ check.add_argument('checked_file', type=Path, help='file with checked IDs')
+ check.add_argument(
+ '-x',
+ '--exclude-file',
+ type=Path,
+ help='file with IDs to exclude from the check',
+ )
+
+ args = parser.parse_args(argv[1:])
+
+ if args.verbose:
+ verbose_print = functools.partial(print, file=sys.stderr)
+ else:
+
+ def verbose_print(*args, **kwargs):
+ """do nothing"""
+
+ if args.command == 'collect':
+ ids = gather_ids(args.htmldir, verbose_print=verbose_print)
+ if args.outfile is None:
+ args.outfile = args.htmldir / 'html-ids.json.gz'
+ with gzip.open(args.outfile, 'wt', encoding='utf-8') as zfile:
+ json.dump({'ids_by_page': ids}, zfile)
+
+ if args.command == 'check':
+ with gzip.open(args.baseline_file) as zfile:
+ baseline = json.load(zfile)['ids_by_page']
+ with gzip.open(args.checked_file) as zfile:
+ checked = json.load(zfile)['ids_by_page']
+ excluded = set()
+ if args.exclude_file:
+ with open(args.exclude_file, encoding='utf-8') as file:
+ for line in file:
+ line = line.strip()
+ if line and not line.startswith('#'):
+ name, sep, excluded_id = line.partition(':')
+ if sep:
+ excluded.add((name.strip(), excluded_id.strip()))
+ if do_check(baseline, checked, excluded, verbose_print=verbose_print):
+ verbose_print('All OK')
+ else:
+ sys.stdout.flush()
+ print(
+ 'ERROR: Removed IDs found',
+ 'The above HTML IDs were removed from the documentation, '
+ + 'resulting in broken links. Please add them back.',
+ sep='\n',
+ file=sys.stderr,
+ )
+ if args.exclude_file:
+ print(f'Alternatively, add them to {args.exclude_file}.')
+
+
+if __name__ == '__main__':
+ main(sys.argv)
diff --git a/Doc/tools/templates/customsourcelink.html b/Doc/tools/templates/customsourcelink.html
index 0d83ac9f78a..8feeed2fee3 100644
--- a/Doc/tools/templates/customsourcelink.html
+++ b/Doc/tools/templates/customsourcelink.html
@@ -1,10 +1,25 @@
{%- if show_source and has_source and sourcename %}
+ <script>
+ document.addEventListener('DOMContentLoaded', () => {
+ const title = document.querySelector('meta[property="og:title"]').content;
+ const elements = document.querySelectorAll('.improvepage');
+ const pageurl = window.location.href.split('?')[0];
+ elements.forEach(element => {
+ const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
+ url.searchParams.set('pagetitle', title);
+ url.searchParams.set('pageurl', pageurl);
+ url.searchParams.set('pagesource', "{{ pagename }}.rst");
+ element.href = url.toString();
+ });
+ });
+ </script>
<div role="note" aria-label="source link">
<h3>{{ _('This page') }}</h3>
<ul class="this-page-menu">
<li><a href="{{ pathto('bugs') }}">{% trans %}Report a bug{% endtrans %}</a></li>
+ <li><a class="improvepage" href="{{ pathto('improve-page-nojs') }}">{% trans %}Improve this page{% endtrans %}</a></li>
<li>
- <a href="https://github.com/python/cpython/blob/main/Doc/{{ sourcename|replace('.rst.txt', '.rst') }}?plain=1"
+ <a href="https://github.com/python/cpython/blob/main/Doc/{{ pagename }}.rst?plain=1"
rel="nofollow">{{ _('Show source') }}
</a>
</li>
diff --git a/Doc/tutorial/classes.rst b/Doc/tutorial/classes.rst
index 645acdf20fb..3c690343022 100644
--- a/Doc/tutorial/classes.rst
+++ b/Doc/tutorial/classes.rst
@@ -420,7 +420,7 @@ of the class::
'Buddy'
As discussed in :ref:`tut-object`, shared data can have possibly surprising
-effects with involving :term:`mutable` objects such as lists and dictionaries.
+effects involving :term:`mutable` objects such as lists and dictionaries.
For example, the *tricks* list in the following code should not be used as a
class variable because just a single list would be shared by all *Dog*
instances::
diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst
index f3e69756401..bee6cc39faf 100644
--- a/Doc/tutorial/controlflow.rst
+++ b/Doc/tutorial/controlflow.rst
@@ -155,8 +155,8 @@ that takes an iterable is :func:`sum`::
6
Later we will see more functions that return iterables and take iterables as
-arguments. In chapter :ref:`tut-structures`, we will discuss in more detail about
-:func:`list`.
+arguments. In chapter :ref:`tut-structures`, we will discuss :func:`list` in more
+detail.
.. _tut-break:
@@ -441,7 +441,7 @@ Several other key features of this statement:
``False`` and ``None`` are compared by identity.
- Patterns may use named constants. These must be dotted names
- to prevent them from being interpreted as capture variable::
+ to prevent them from being interpreted as capture variables::
from enum import Enum
class Color(Enum):
@@ -1107,7 +1107,7 @@ Intermezzo: Coding Style
Now that you are about to write longer, more complex pieces of Python, it is a
good time to talk about *coding style*. Most languages can be written (or more
-concise, *formatted*) in different styles; some are more readable than others.
+concisely, *formatted*) in different styles; some are more readable than others.
Making it easy for others to read your code is always a good idea, and adopting
a nice coding style helps tremendously for that.
diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst
index deabac52530..7778e37a9ad 100644
--- a/Doc/tutorial/introduction.rst
+++ b/Doc/tutorial/introduction.rst
@@ -184,11 +184,11 @@ If you don't want characters prefaced by ``\`` to be interpreted as
special characters, you can use *raw strings* by adding an ``r`` before
the first quote::
- >>> print('C:\some\name') # here \n means newline!
- C:\some
+ >>> print('C:\this\name') # here \t means tab, \n means newline
+ C: his
ame
- >>> print(r'C:\some\name') # note the r before the quote
- C:\some\name
+ >>> print(r'C:\this\name') # note the r before the quote
+ C:\this\name
There is one subtle aspect to raw strings: a raw string may not end in
an odd number of ``\`` characters; see
diff --git a/Doc/tutorial/whatnow.rst b/Doc/tutorial/whatnow.rst
index 359cf80a7b2..aae8f29b007 100644
--- a/Doc/tutorial/whatnow.rst
+++ b/Doc/tutorial/whatnow.rst
@@ -68,6 +68,6 @@ already contain the solution for your problem.
.. rubric:: Footnotes
-.. [#] "Cheese Shop" is a Monty Python's sketch: a customer enters a cheese shop,
+.. [#] "Cheese Shop" is a Monty Python sketch: a customer enters a cheese shop,
but whatever cheese he asks for, the clerk says it's missing.
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 24541e84732..09be3af0abe 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -1045,6 +1045,13 @@ conflict.
* ``pymalloc_debug``: same as ``pymalloc`` but also install debug hooks.
* ``mimalloc_debug``: same as ``mimalloc`` but also install debug hooks.
+ .. note::
+
+ In the :term:`free-threaded <free threading>` build, the ``malloc``,
+ ``malloc_debug``, ``pymalloc``, and ``pymalloc_debug`` values are not
+ supported. Only ``default``, ``debug``, ``mimalloc``, and
+ ``mimalloc_debug`` are accepted.
+
.. versionadded:: 3.6
.. versionchanged:: 3.7
@@ -1054,12 +1061,13 @@ conflict.
.. envvar:: PYTHONMALLOCSTATS
If set to a non-empty string, Python will print statistics of the
- :ref:`pymalloc memory allocator <pymalloc>` every time a new pymalloc object
- arena is created, and on shutdown.
+ :ref:`pymalloc memory allocator <pymalloc>` or the
+ :ref:`mimalloc memory allocator <mimalloc>` (whichever is in use)
+ every time a new object arena is created, and on shutdown.
This variable is ignored if the :envvar:`PYTHONMALLOC` environment variable
is used to force the :c:func:`malloc` allocator of the C library, or if
- Python is configured without ``pymalloc`` support.
+ Python is configured without both ``pymalloc`` and ``mimalloc`` support.
.. versionchanged:: 3.6
This variable can now also be used on Python compiled in release mode.
diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst
index 61e21fba74c..7372ae71a4b 100644
--- a/Doc/using/configure.rst
+++ b/Doc/using/configure.rst
@@ -747,6 +747,9 @@ also be used to improve performance.
Disable the fast :ref:`mimalloc <mimalloc>` allocator
(enabled by default).
+ This option cannot be used together with :option:`--disable-gil`
+ because the :term:`free-threaded <free threading>` build requires mimalloc.
+
See also :envvar:`PYTHONMALLOC` environment variable.
.. option:: --without-pymalloc
diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst
index 0e728e5dd9c..38e6111c765 100644
--- a/Doc/using/windows.rst
+++ b/Doc/using/windows.rst
@@ -287,6 +287,12 @@ work.
Passing ``--dry-run`` will generate output and logs, but will not modify any
installs.
+Passing ``--refresh`` will update all registrations for installed runtimes. This
+will recreate Start menu shortcuts, registry keys, and global aliases (such as
+``python3.14.exe`` or for any installed scripts). These are automatically
+refreshed on installation of any runtime, but may need to be manually refreshed
+after installing packages.
+
In addition to the above options, the ``--target`` option will extract the
runtime to the specified directory instead of doing a normal install.
This is useful for embedding runtimes into larger applications.
@@ -469,6 +475,14 @@ customization.
- ``PYTHON_MANAGER_SOURCE_URL``
- Override the index feed to obtain new installs from.
+ * - ``install.enable_entrypoints``
+ - (none)
+ - True to generate global commands for installed packages (such as
+ ``pip.exe``). These are defined by the packages themselves.
+ If set to false, only the Python interpreter has global commands created.
+ By default, true. You should run ``py install --refresh`` after changing
+ this setting.
+
* - ``list.format``
- ``PYTHON_MANAGER_LIST_FORMAT``
- Specify the default format used by the ``py list`` command.
@@ -482,8 +496,8 @@ customization.
* - ``global_dir``
- (none)
- - Specify the directory where global commands (such as ``python3.14.exe``)
- are stored.
+ - Specify the directory where global commands (such as ``python3.14.exe``
+ and ``pip.exe``) are stored.
This directory should be added to your :envvar:`PATH` to make the
commands available from your terminal.
@@ -493,6 +507,7 @@ customization.
This directory is a temporary cache, and can be cleaned up from time to
time.
+
Dotted names should be nested inside JSON objects, for example, ``list.format``
would be specified as ``{"list": {"format": "table"}}``.
@@ -739,6 +754,14 @@ directory containing the configuration file that specified them.
(e.g. ``"pep514,start"``).
Disabled shortcuts are not reactivated by ``enable_shortcut_kinds``.
+ * - ``install.hard_link_entrypoints``
+ - True to use hard links for global shortcuts to save disk space. If false,
+ each shortcut executable is copied instead. After changing this setting,
+ you must run ``py install --refresh --force`` to update existing
+ commands.
+ By default, true. Disabling this may be necessary for troubleshooting or
+ systems that have issues with file links.
+
* - ``pep514_root``
- Registry location to read and write PEP 514 entries into.
By default, :file:`HKEY_CURRENT_USER\\Software\\Python`.
@@ -878,12 +901,22 @@ default).
* -
- The package may be available but missing the generated executable.
- We recommend using the ``python -m pip`` command instead,
- or alternatively the ``python -m pip install --force pip`` command
- will recreate the executables and show you the path to
- add to :envvar:`PATH`.
- These scripts are separated for each runtime, and so you may need to
- add multiple paths.
+ We recommend using the ``python -m pip`` command instead.
+ Running ``py install --refresh`` and ensuring that the global shortcuts
+ directory is on :envvar:`PATH` (it will be shown in the command output if
+ it is not) should make commands such as ``pip`` (and other installed
+ packages) available.
+
+ * - I installed a package with ``pip`` but its command is not found.
+ - Have you activated a virtual environment?
+ Run the ``.venv\Scripts\activate`` script in your terminal to activate.
+
+ * -
+ - New packages do not automatically have global shortcuts created by the
+ Python install manager. Similarly, uninstalled packages do not have their
+ shortcuts removed.
+ Run ``py install --refresh`` to update the global shortcuts for newly
+ installed packages.
* - Typing ``script-name.py`` in the terminal opens in a new window.
- This is a known limitation of the operating system. Either specify ``py``
diff --git a/Include/internal/pycore_cell.h b/Include/internal/pycore_cell.h
index cef01e80514..d0d45a23436 100644
--- a/Include/internal/pycore_cell.h
+++ b/Include/internal/pycore_cell.h
@@ -53,7 +53,7 @@ _PyCell_GetStackRef(PyCellObject *cell)
{
PyObject *value;
#ifdef Py_GIL_DISABLED
- value = _Py_atomic_load_ptr(&cell->ob_ref);
+ value = _PyObject_CAST(_Py_atomic_load_ptr(&cell->ob_ref));
if (value == NULL) {
return PyStackRef_NULL;
}
diff --git a/Include/internal/pycore_emscripten_trampoline.h b/Include/internal/pycore_emscripten_trampoline.h
index 16916f1a8eb..e37c53a64f4 100644
--- a/Include/internal/pycore_emscripten_trampoline.h
+++ b/Include/internal/pycore_emscripten_trampoline.h
@@ -27,9 +27,6 @@
#if defined(__EMSCRIPTEN__) && defined(PY_CALL_TRAMPOLINE)
-void
-_Py_EmscriptenTrampoline_Init(_PyRuntimeState *runtime);
-
PyObject*
_PyEM_TrampolineCall(PyCFunctionWithKeywords func,
PyObject* self,
diff --git a/Include/internal/pycore_pyatomic_ft_wrappers.h b/Include/internal/pycore_pyatomic_ft_wrappers.h
index 4187f46995e..f4c699616a1 100644
--- a/Include/internal/pycore_pyatomic_ft_wrappers.h
+++ b/Include/internal/pycore_pyatomic_ft_wrappers.h
@@ -99,6 +99,8 @@ extern "C" {
_Py_atomic_store_ulong_relaxed(&value, new_value)
#define FT_ATOMIC_STORE_SSIZE_RELAXED(value, new_value) \
_Py_atomic_store_ssize_relaxed(&value, new_value)
+#define FT_ATOMIC_STORE_SSIZE_RELEASE(value, new_value) \
+ _Py_atomic_store_ssize_release(&value, new_value)
#define FT_ATOMIC_STORE_FLOAT_RELAXED(value, new_value) \
_Py_atomic_store_float_relaxed(&value, new_value)
#define FT_ATOMIC_LOAD_FLOAT_RELAXED(value) \
@@ -117,6 +119,8 @@ extern "C" {
_Py_atomic_load_ullong_relaxed(&value)
#define FT_ATOMIC_ADD_SSIZE(value, new_value) \
(void)_Py_atomic_add_ssize(&value, new_value)
+#define FT_MUTEX_LOCK(lock) PyMutex_Lock(lock)
+#define FT_MUTEX_UNLOCK(lock) PyMutex_Unlock(lock)
#else
#define FT_ATOMIC_LOAD_PTR(value) value
@@ -138,6 +142,7 @@ extern "C" {
#define FT_ATOMIC_STORE_PTR_RELEASE(value, new_value) value = new_value
#define FT_ATOMIC_STORE_UINTPTR_RELEASE(value, new_value) value = new_value
#define FT_ATOMIC_STORE_SSIZE_RELAXED(value, new_value) value = new_value
+#define FT_ATOMIC_STORE_SSIZE_RELEASE(value, new_value) value = new_value
#define FT_ATOMIC_STORE_UINT8_RELAXED(value, new_value) value = new_value
#define FT_ATOMIC_STORE_UINT16_RELAXED(value, new_value) value = new_value
#define FT_ATOMIC_STORE_UINT32_RELAXED(value, new_value) value = new_value
@@ -168,6 +173,8 @@ extern "C" {
#define FT_ATOMIC_LOAD_ULLONG_RELAXED(value) value
#define FT_ATOMIC_STORE_ULLONG_RELAXED(value, new_value) value = new_value
#define FT_ATOMIC_ADD_SSIZE(value, new_value) (void)(value += new_value)
+#define FT_MUTEX_LOCK(lock) do {} while (0)
+#define FT_MUTEX_UNLOCK(lock) do {} while (0)
#endif
diff --git a/Include/internal/pycore_runtime_structs.h b/Include/internal/pycore_runtime_structs.h
index c34d7e7edc0..78f236a51a1 100644
--- a/Include/internal/pycore_runtime_structs.h
+++ b/Include/internal/pycore_runtime_structs.h
@@ -279,6 +279,16 @@ struct pyruntimestate {
struct _types_runtime_state types;
struct _Py_time_runtime_state time;
+#if defined(__EMSCRIPTEN__) && defined(PY_CALL_TRAMPOLINE)
+ // Used in "Python/emscripten_trampoline.c" to choose between wasm-gc
+ // trampoline and JavaScript trampoline.
+ PyObject* (*emscripten_trampoline)(int* success,
+ PyCFunctionWithKeywords func,
+ PyObject* self,
+ PyObject* args,
+ PyObject* kw);
+#endif
+
/* All the objects that are shared by the runtime's interpreters. */
struct _Py_cached_objects cached_objects;
struct _Py_static_objects static_objects;
diff --git a/Include/internal/pycore_stackref.h b/Include/internal/pycore_stackref.h
index 52acd918c9b..76f6333739d 100644
--- a/Include/internal/pycore_stackref.h
+++ b/Include/internal/pycore_stackref.h
@@ -735,6 +735,13 @@ _PyThreadState_PushCStackRef(PyThreadState *tstate, _PyCStackRef *ref)
ref->ref = PyStackRef_NULL;
}
+static inline void
+_PyThreadState_PushCStackRefNew(PyThreadState *tstate, _PyCStackRef *ref, PyObject *obj)
+{
+ _PyThreadState_PushCStackRef(tstate, ref);
+ ref->ref = PyStackRef_FromPyObjectNew(obj);
+}
+
static inline void
_PyThreadState_PopCStackRef(PyThreadState *tstate, _PyCStackRef *ref)
{
diff --git a/Include/object.h b/Include/object.h
index 4d577d0e32d..50a41e355ed 100644
--- a/Include/object.h
+++ b/Include/object.h
@@ -199,11 +199,11 @@ _Py_ThreadId(void)
#elif defined(__MINGW32__) && defined(_M_ARM64)
tid = __getReg(18);
#elif defined(__i386__)
- __asm__("movl %%gs:0, %0" : "=r" (tid)); // 32-bit always uses GS
+ __asm__("{movl %%gs:0, %0|mov %0, dword ptr gs:[0]}" : "=r" (tid)); // 32-bit always uses GS
#elif defined(__MACH__) && defined(__x86_64__)
- __asm__("movq %%gs:0, %0" : "=r" (tid)); // x86_64 macOSX uses GS
+ __asm__("{movq %%gs:0, %0|mov %0, qword ptr gs:[0]}" : "=r" (tid)); // x86_64 macOSX uses GS
#elif defined(__x86_64__)
- __asm__("movq %%fs:0, %0" : "=r" (tid)); // x86_64 Linux, BSD uses FS
+ __asm__("{movq %%fs:0, %0|mov %0, qword ptr fs:[0]}" : "=r" (tid)); // x86_64 Linux, BSD uses FS
#elif defined(__arm__) && __ARM_ARCH >= 7
__asm__ ("mrc p15, 0, %0, c13, c0, 3\nbic %0, %0, #3" : "=r" (tid));
#elif defined(__aarch64__) && defined(__APPLE__)
diff --git a/Include/patchlevel.h b/Include/patchlevel.h
index 8ad65ac59f4..786157e4eac 100644
--- a/Include/patchlevel.h
+++ b/Include/patchlevel.h
@@ -24,7 +24,7 @@
#define PY_RELEASE_SERIAL 0
/* Version as a string */
-#define PY_VERSION "3.14.3"
+#define PY_VERSION "3.14.3+"
/*--end constants--*/
diff --git a/Lib/argparse.py b/Lib/argparse.py
index 1d7d34f9924..8cf85694300 100644
--- a/Lib/argparse.py
+++ b/Lib/argparse.py
@@ -149,6 +149,10 @@ def _copy_items(items):
return copy.copy(items)
+def _identity(value):
+ return value
+
+
# ===============
# Formatting Help
# ===============
@@ -200,7 +204,7 @@ def _set_color(self, color):
self._decolor = decolor
else:
self._theme = get_theme(force_no_color=True).argparse
- self._decolor = lambda text: text
+ self._decolor = _identity
# ===============================
# Section and indentation methods
@@ -1903,9 +1907,7 @@ def __init__(self,
self._subparsers = None
# register types
- def identity(string):
- return string
- self.register('type', None, identity)
+ self.register('type', None, _identity)
# add help argument if necessary
# (using explicit default to override global argument_default)
diff --git a/Lib/asyncio/base_events.py b/Lib/asyncio/base_events.py
index 8cbb71f7085..b83b84181fd 100644
--- a/Lib/asyncio/base_events.py
+++ b/Lib/asyncio/base_events.py
@@ -1345,6 +1345,17 @@ async def start_tls(self, transport, protocol, sslcontext, *,
# have a chance to get called before "ssl_protocol.connection_made()".
transport.pause_reading()
+ # gh-142352: move buffered StreamReader data to SSLProtocol
+ if server_side:
+ from .streams import StreamReaderProtocol
+ if isinstance(protocol, StreamReaderProtocol):
+ stream_reader = getattr(protocol, '_stream_reader', None)
+ if stream_reader is not None:
+ buffer = stream_reader._buffer
+ if buffer:
+ ssl_protocol._incoming.write(buffer)
+ buffer.clear()
+
transport.set_protocol(ssl_protocol)
conmade_cb = self.call_soon(ssl_protocol.connection_made, transport)
resume_cb = self.call_soon(transport.resume_reading)
diff --git a/Lib/asyncio/base_subprocess.py b/Lib/asyncio/base_subprocess.py
index 321a4e5d5d1..224b1883808 100644
--- a/Lib/asyncio/base_subprocess.py
+++ b/Lib/asyncio/base_subprocess.py
@@ -265,7 +265,7 @@ def _try_finish(self):
# to avoid hanging forever in self._wait as otherwise _exit_waiters
# would never be woken up, we wake them up here.
for waiter in self._exit_waiters:
- if not waiter.cancelled():
+ if not waiter.done():
waiter.set_result(self._returncode)
if all(p is not None and p.disconnected
for p in self._pipes.values()):
@@ -278,7 +278,7 @@ def _call_connection_lost(self, exc):
finally:
# wake up futures waiting for wait()
for waiter in self._exit_waiters:
- if not waiter.cancelled():
+ if not waiter.done():
waiter.set_result(self._returncode)
self._exit_waiters = None
self._loop = None
diff --git a/Lib/asyncio/windows_utils.py b/Lib/asyncio/windows_utils.py
index ef277fac3e2..acd49441131 100644
--- a/Lib/asyncio/windows_utils.py
+++ b/Lib/asyncio/windows_utils.py
@@ -10,7 +10,6 @@
import msvcrt
import os
import subprocess
-import tempfile
import warnings
@@ -24,6 +23,7 @@
PIPE = subprocess.PIPE
STDOUT = subprocess.STDOUT
_mmap_counter = itertools.count()
+_MAX_PIPE_ATTEMPTS = 20
# Replacement for os.pipe() using handles instead of fds
@@ -31,10 +31,6 @@
def pipe(*, duplex=False, overlapped=(True, True), bufsize=BUFSIZE):
"""Like os.pipe() but with overlapped support and using handles not fds."""
- address = tempfile.mktemp(
- prefix=r'\\.\pipe\python-pipe-{:d}-{:d}-'.format(
- os.getpid(), next(_mmap_counter)))
-
if duplex:
openmode = _winapi.PIPE_ACCESS_DUPLEX
access = _winapi.GENERIC_READ | _winapi.GENERIC_WRITE
@@ -56,9 +52,20 @@ def pipe(*, duplex=False, overlapped=(True, True), bufsize=BUFSIZE):
h1 = h2 = None
try:
- h1 = _winapi.CreateNamedPipe(
- address, openmode, _winapi.PIPE_WAIT,
- 1, obsize, ibsize, _winapi.NMPWAIT_WAIT_FOREVER, _winapi.NULL)
+ for attempts in itertools.count():
+ address = r'\\.\pipe\python-pipe-{:d}-{:d}-{}'.format(
+ os.getpid(), next(_mmap_counter), os.urandom(8).hex())
+ try:
+ h1 = _winapi.CreateNamedPipe(
+ address, openmode, _winapi.PIPE_WAIT,
+ 1, obsize, ibsize, _winapi.NMPWAIT_WAIT_FOREVER, _winapi.NULL)
+ break
+ except OSError as e:
+ if attempts >= _MAX_PIPE_ATTEMPTS:
+ raise
+ if e.winerror not in (_winapi.ERROR_PIPE_BUSY,
+ _winapi.ERROR_ACCESS_DENIED):
+ raise
h2 = _winapi.CreateFile(
address, access, 0, _winapi.NULL, _winapi.OPEN_EXISTING,
diff --git a/Lib/ctypes/__init__.py b/Lib/ctypes/__init__.py
index 04ec0270148..7223fc49977 100644
--- a/Lib/ctypes/__init__.py
+++ b/Lib/ctypes/__init__.py
@@ -470,6 +470,8 @@ def _load_library(self, name, mode, handle, winmode):
if name and name.endswith(")") and ".a(" in name:
mode |= _os.RTLD_MEMBER | _os.RTLD_NOW
self._name = name
+ if handle is not None:
+ return handle
return _dlopen(name, mode)
def __repr__(self):
diff --git a/Lib/ctypes/util.py b/Lib/ctypes/util.py
index 378f12167c6..3b21658433b 100644
--- a/Lib/ctypes/util.py
+++ b/Lib/ctypes/util.py
@@ -85,15 +85,10 @@ def find_library(name):
wintypes.DWORD,
)
- _psapi = ctypes.WinDLL('psapi', use_last_error=True)
- _enum_process_modules = _psapi["EnumProcessModules"]
- _enum_process_modules.restype = wintypes.BOOL
- _enum_process_modules.argtypes = (
- wintypes.HANDLE,
- ctypes.POINTER(wintypes.HMODULE),
- wintypes.DWORD,
- wintypes.LPDWORD,
- )
+ # gh-145307: We defer loading psapi.dll until _get_module_handles is called.
+ # Loading additional DLLs at startup for functionality that may never be
+ # used is wasteful.
+ _enum_process_modules = None
def _get_module_filename(module: wintypes.HMODULE):
name = (wintypes.WCHAR * 32767)() # UNICODE_STRING_MAX_CHARS
@@ -101,8 +96,19 @@ def _get_module_filename(module: wintypes.HMODULE):
return name.value
return None
-
def _get_module_handles():
+ global _enum_process_modules
+ if _enum_process_modules is None:
+ _psapi = ctypes.WinDLL('psapi', use_last_error=True)
+ _enum_process_modules = _psapi["EnumProcessModules"]
+ _enum_process_modules.restype = wintypes.BOOL
+ _enum_process_modules.argtypes = (
+ wintypes.HANDLE,
+ ctypes.POINTER(wintypes.HMODULE),
+ wintypes.DWORD,
+ wintypes.LPDWORD,
+ )
+
process = _get_current_process()
space_needed = wintypes.DWORD()
n = 1024
diff --git a/Lib/email/_header_value_parser.py b/Lib/email/_header_value_parser.py
index 51727688c05..03fedd99539 100644
--- a/Lib/email/_header_value_parser.py
+++ b/Lib/email/_header_value_parser.py
@@ -80,7 +80,8 @@
# Useful constants and functions
#
-WSP = set(' \t')
+_WSP = ' \t'
+WSP = set(_WSP)
CFWS_LEADER = WSP | set('(')
SPECIALS = set(r'()<>@,:;.\"[]')
ATOM_ENDS = SPECIALS | WSP
@@ -2831,6 +2832,7 @@ def _steal_trailing_WSP_if_exists(lines):
lines.pop()
return wsp
+
def _refold_parse_tree(parse_tree, *, policy):
"""Return string of contents of parse_tree folded according to RFC rules.
@@ -2839,11 +2841,9 @@ def _refold_parse_tree(parse_tree, *, policy):
maxlen = policy.max_line_length or sys.maxsize
encoding = 'utf-8' if policy.utf8 else 'us-ascii'
lines = [''] # Folded lines to be output
- leading_whitespace = '' # When we have whitespace between two encoded
- # words, we may need to encode the whitespace
- # at the beginning of the second word.
- last_ew = None # Points to the last encoded character if there's an ew on
- # the line
+ last_word_is_ew = False
+ last_ew = None # if there is an encoded word in the last line of lines,
+ # points to the encoded word's first character
last_charset = None
wrap_as_ew_blocked = 0
want_encoding = False # This is set to True if we need to encode this part
@@ -2878,6 +2878,7 @@ def _refold_parse_tree(parse_tree, *, policy):
if part.token_type == 'mime-parameters':
# Mime parameter folding (using RFC2231) is extra special.
_fold_mime_parameters(part, lines, maxlen, encoding)
+ last_word_is_ew = False
continue
if want_encoding and not wrap_as_ew_blocked:
@@ -2894,6 +2895,7 @@ def _refold_parse_tree(parse_tree, *, policy):
# XXX what if encoded_part has no leading FWS?
lines.append(newline)
lines[-1] += encoded_part
+ last_word_is_ew = False
continue
# Either this is not a major syntactic break, so we don't
# want it on a line by itself even if it fits, or it
@@ -2912,11 +2914,16 @@ def _refold_parse_tree(parse_tree, *, policy):
(last_charset == 'unknown-8bit' or
last_charset == 'utf-8' and charset != 'us-ascii')):
last_ew = None
- last_ew = _fold_as_ew(tstr, lines, maxlen, last_ew,
- part.ew_combine_allowed, charset, leading_whitespace)
- # This whitespace has been added to the lines in _fold_as_ew()
- # so clear it now.
- leading_whitespace = ''
+ last_ew = _fold_as_ew(
+ tstr,
+ lines,
+ maxlen,
+ last_ew,
+ part.ew_combine_allowed,
+ charset,
+ last_word_is_ew,
+ )
+ last_word_is_ew = True
last_charset = charset
want_encoding = False
continue
@@ -2929,28 +2936,19 @@ def _refold_parse_tree(parse_tree, *, policy):
if len(tstr) <= maxlen - len(lines[-1]):
lines[-1] += tstr
+ last_word_is_ew = last_word_is_ew and not bool(tstr.strip(_WSP))
continue
# This part is too long to fit. The RFC wants us to break at
# "major syntactic breaks", so unless we don't consider this
# to be one, check if it will fit on the next line by itself.
- leading_whitespace = ''
if (part.syntactic_break and
len(tstr) + 1 <= maxlen):
newline = _steal_trailing_WSP_if_exists(lines)
if newline or part.startswith_fws():
- # We're going to fold the data onto a new line here. Due to
- # the way encoded strings handle continuation lines, we need to
- # be prepared to encode any whitespace if the next line turns
- # out to start with an encoded word.
lines.append(newline + tstr)
-
- whitespace_accumulator = []
- for char in lines[-1]:
- if char not in WSP:
- break
- whitespace_accumulator.append(char)
- leading_whitespace = ''.join(whitespace_accumulator)
+ last_word_is_ew = (last_word_is_ew
+ and not bool(lines[-1].strip(_WSP)))
last_ew = None
continue
if not hasattr(part, 'encode'):
@@ -2990,10 +2988,11 @@ def _refold_parse_tree(parse_tree, *, policy):
else:
# We can't fold it onto the next line either...
lines[-1] += tstr
+ last_word_is_ew = last_word_is_ew and not bool(tstr.strip(_WSP))
return policy.linesep.join(lines) + policy.linesep
-def _fold_as_ew(to_encode, lines, maxlen, last_ew, ew_combine_allowed, charset, leading_whitespace):
+def _fold_as_ew(to_encode, lines, maxlen, last_ew, ew_combine_allowed, charset, last_word_is_ew):
"""Fold string to_encode into lines as encoded word, combining if allowed.
Return the new value for last_ew, or None if ew_combine_allowed is False.
@@ -3008,6 +3007,16 @@ def _fold_as_ew(to_encode, lines, maxlen, last_ew, ew_combine_allowed, charset,
to_encode = str(
get_unstructured(lines[-1][last_ew:] + to_encode))
lines[-1] = lines[-1][:last_ew]
+ elif last_word_is_ew:
+ # If we are following up an encoded word with another encoded word,
+ # any white space between the two will be ignored when decoded.
+ # Therefore, we encode all to-be-displayed whitespace in the second
+ # encoded word.
+ len_without_wsp = len(lines[-1].rstrip(_WSP))
+ leading_whitespace = lines[-1][len_without_wsp:]
+ lines[-1] = (lines[-1][:len_without_wsp]
+ + (' ' if leading_whitespace else ''))
+ to_encode = leading_whitespace + to_encode
elif to_encode[0] in WSP:
# We're joining this to non-encoded text, so don't encode
# the leading blank.
@@ -3036,20 +3045,13 @@ def _fold_as_ew(to_encode, lines, maxlen, last_ew, ew_combine_allowed, charset,
while to_encode:
remaining_space = maxlen - len(lines[-1])
- text_space = remaining_space - chrome_len - len(leading_whitespace)
+ text_space = remaining_space - chrome_len
if text_space <= 0:
- lines.append(' ')
+ newline = _steal_trailing_WSP_if_exists(lines)
+ lines.append(newline or ' ')
+ new_last_ew = len(lines[-1])
continue
- # If we are at the start of a continuation line, prepend whitespace
- # (we only want to do this when the line starts with an encoded word
- # but if we're folding in this helper function, then we know that we
- # are going to be writing out an encoded word.)
- if len(lines) > 1 and len(lines[-1]) == 1 and leading_whitespace:
- encoded_word = _ew.encode(leading_whitespace, charset=encode_as)
- lines[-1] += encoded_word
- leading_whitespace = ''
-
to_encode_word = to_encode[:text_space]
encoded_word = _ew.encode(to_encode_word, charset=encode_as)
excess = len(encoded_word) - remaining_space
@@ -3061,7 +3063,6 @@ def _fold_as_ew(to_encode, lines, maxlen, last_ew, ew_combine_allowed, charset,
excess = len(encoded_word) - remaining_space
lines[-1] += encoded_word
to_encode = to_encode[len(to_encode_word):]
- leading_whitespace = ''
if to_encode:
lines.append(' ')
diff --git a/Lib/ensurepip/__init__.py b/Lib/ensurepip/__init__.py
index 21bbfad0fe6..3d5641e3576 100644
--- a/Lib/ensurepip/__init__.py
+++ b/Lib/ensurepip/__init__.py
@@ -10,7 +10,7 @@
__all__ = ["version", "bootstrap"]
-_PIP_VERSION = "25.3"
+_PIP_VERSION = "26.0.1"
# Directory of system wheel packages. Some Linux distribution packaging
# policies recommend against bundling dependencies. For example, Fedora
diff --git a/Lib/glob.py b/Lib/glob.py
index f1a87c82fc5..7ce3998c27c 100644
--- a/Lib/glob.py
+++ b/Lib/glob.py
@@ -15,7 +15,7 @@
def glob(pathname, *, root_dir=None, dir_fd=None, recursive=False,
include_hidden=False):
- """Return a list of paths matching a pathname pattern.
+ """Return a list of paths matching a `pathname` pattern.
The pattern may contain simple shell-style wildcards a la
fnmatch. Unlike fnmatch, filenames starting with a
@@ -25,6 +25,15 @@ def glob(pathname, *, root_dir=None, dir_fd=None, recursive=False,
The order of the returned list is undefined. Sort it if you need a
particular order.
+ If `root_dir` is not None, it should be a path-like object specifying the
+ root directory for searching. It has the same effect as changing the
+ current directory before calling it (without actually
+ changing it). If pathname is relative, the result will contain
+ paths relative to `root_dir`.
+
+ If `dir_fd` is not None, it should be a file descriptor referring to a
+ directory, and paths will then be relative to that directory.
+
If `include_hidden` is true, the patterns '*', '?', '**' will match hidden
directories.
@@ -36,7 +45,7 @@ def glob(pathname, *, root_dir=None, dir_fd=None, recursive=False,
def iglob(pathname, *, root_dir=None, dir_fd=None, recursive=False,
include_hidden=False):
- """Return an iterator which yields the paths matching a pathname pattern.
+ """Return an iterator which yields the paths matching a `pathname` pattern.
The pattern may contain simple shell-style wildcards a la
fnmatch. However, unlike fnmatch, filenames starting with a
@@ -46,7 +55,19 @@ def iglob(pathname, *, root_dir=None, dir_fd=None, recursive=False,
The order of the returned paths is undefined. Sort them if you need a
particular order.
- If recursive is true, the pattern '**' will match any files and
+ If `root_dir` is not None, it should be a path-like object specifying
+ the root directory for searching. It has the same effect as changing
+ the current directory before calling it (without actually
+ changing it). If pathname is relative, the result will contain
+ paths relative to `root_dir`.
+
+ If `dir_fd` is not None, it should be a file descriptor referring to a
+ directory, and paths will then be relative to that directory.
+
+ If `include_hidden` is true, the patterns '*', '?', '**' will match hidden
+ directories.
+
+ If `recursive` is true, the pattern '**' will match any files and
zero or more directories and subdirectories.
"""
sys.audit("glob.glob", pathname, recursive)
diff --git a/Lib/importlib/_bootstrap.py b/Lib/importlib/_bootstrap.py
index 499da1e04ef..9d911e1dcab 100644
--- a/Lib/importlib/_bootstrap.py
+++ b/Lib/importlib/_bootstrap.py
@@ -1375,6 +1375,14 @@ def _find_and_load(name, import_):
# NOTE: because of this, initializing must be set *before*
# putting the new module in sys.modules.
_lock_unlock_module(name)
+ else:
+ # Verify the module is still in sys.modules. Another thread may have
+ # removed it (due to import failure) between our sys.modules.get()
+ # above and the _initializing check. If removed, we retry the import
+ # to preserve normal semantics: the caller gets the exception from
+ # the actual import failure rather than a synthetic error.
+ if sys.modules.get(name) is not module:
+ return _find_and_load(name, import_)
if module is None:
message = f'import of {name} halted; None in sys.modules'
diff --git a/Lib/importlib/_bootstrap_external.py b/Lib/importlib/_bootstrap_external.py
index 95ce14b2c39..6a828ae75ed 100644
--- a/Lib/importlib/_bootstrap_external.py
+++ b/Lib/importlib/_bootstrap_external.py
@@ -946,7 +946,7 @@ def get_filename(self, fullname):
def get_data(self, path):
"""Return the data from path as raw bytes."""
- if isinstance(self, (SourceLoader, ExtensionFileLoader)):
+ if isinstance(self, (SourceLoader, SourcelessFileLoader, ExtensionFileLoader)):
with _io.open_code(str(path)) as file:
return file.read()
else:
diff --git a/Lib/inspect.py b/Lib/inspect.py
index 3cee85f39a6..2d229051b4d 100644
--- a/Lib/inspect.py
+++ b/Lib/inspect.py
@@ -2660,11 +2660,12 @@ class Parameter:
The annotation for the parameter if specified. If the
parameter has no annotation, this attribute is set to
`Parameter.empty`.
- * kind : str
+ * kind
Describes how argument values are bound to the parameter.
Possible values: `Parameter.POSITIONAL_ONLY`,
`Parameter.POSITIONAL_OR_KEYWORD`, `Parameter.VAR_POSITIONAL`,
`Parameter.KEYWORD_ONLY`, `Parameter.VAR_KEYWORD`.
+ Every value has a `description` attribute describing meaning.
"""
__slots__ = ('_name', '_kind', '_default', '_annotation')
diff --git a/Lib/multiprocessing/connection.py b/Lib/multiprocessing/connection.py
index fc00d286126..a6e1b0c7862 100644
--- a/Lib/multiprocessing/connection.py
+++ b/Lib/multiprocessing/connection.py
@@ -46,6 +46,7 @@
CONNECTION_TIMEOUT = 20.
_mmap_counter = itertools.count()
+_MAX_PIPE_ATTEMPTS = 100
default_family = 'AF_INET'
families = ['AF_INET']
@@ -78,8 +79,8 @@ def arbitrary_address(family):
elif family == 'AF_UNIX':
return tempfile.mktemp(prefix='sock-', dir=util.get_temp_dir())
elif family == 'AF_PIPE':
- return tempfile.mktemp(prefix=r'\\.\pipe\pyc-%d-%d-' %
- (os.getpid(), next(_mmap_counter)), dir="")
+ return (r'\\.\pipe\pyc-%d-%d-%s' %
+ (os.getpid(), next(_mmap_counter), os.urandom(8).hex()))
else:
raise ValueError('unrecognized family')
@@ -472,17 +473,29 @@ class Listener(object):
def __init__(self, address=None, family=None, backlog=1, authkey=None):
family = family or (address and address_type(address)) \
or default_family
- address = address or arbitrary_address(family)
-
_validate_family(family)
+ if authkey is not None and not isinstance(authkey, bytes):
+ raise TypeError('authkey should be a byte string')
+
if family == 'AF_PIPE':
- self._listener = PipeListener(address, backlog)
+ if address:
+ self._listener = PipeListener(address, backlog)
+ else:
+ for attempts in itertools.count():
+ address = arbitrary_address(family)
+ try:
+ self._listener = PipeListener(address, backlog)
+ break
+ except OSError as e:
+ if attempts >= _MAX_PIPE_ATTEMPTS:
+ raise
+ if e.winerror not in (_winapi.ERROR_PIPE_BUSY,
+ _winapi.ERROR_ACCESS_DENIED):
+ raise
else:
+ address = address or arbitrary_address(family)
self._listener = SocketListener(address, family, backlog)
- if authkey is not None and not isinstance(authkey, bytes):
- raise TypeError('authkey should be a byte string')
-
self._authkey = authkey
def accept(self):
@@ -570,7 +583,6 @@ def Pipe(duplex=True):
'''
Returns pair of connection objects at either end of a pipe
'''
- address = arbitrary_address('AF_PIPE')
if duplex:
openmode = _winapi.PIPE_ACCESS_DUPLEX
access = _winapi.GENERIC_READ | _winapi.GENERIC_WRITE
@@ -580,15 +592,25 @@ def Pipe(duplex=True):
access = _winapi.GENERIC_WRITE
obsize, ibsize = 0, BUFSIZE
- h1 = _winapi.CreateNamedPipe(
- address, openmode | _winapi.FILE_FLAG_OVERLAPPED |
- _winapi.FILE_FLAG_FIRST_PIPE_INSTANCE,
- _winapi.PIPE_TYPE_MESSAGE | _winapi.PIPE_READMODE_MESSAGE |
- _winapi.PIPE_WAIT,
- 1, obsize, ibsize, _winapi.NMPWAIT_WAIT_FOREVER,
- # default security descriptor: the handle cannot be inherited
- _winapi.NULL
- )
+ for attempts in itertools.count():
+ address = arbitrary_address('AF_PIPE')
+ try:
+ h1 = _winapi.CreateNamedPipe(
+ address, openmode | _winapi.FILE_FLAG_OVERLAPPED |
+ _winapi.FILE_FLAG_FIRST_PIPE_INSTANCE,
+ _winapi.PIPE_TYPE_MESSAGE | _winapi.PIPE_READMODE_MESSAGE |
+ _winapi.PIPE_WAIT,
+ 1, obsize, ibsize, _winapi.NMPWAIT_WAIT_FOREVER,
+ # default security descriptor: the handle cannot be inherited
+ _winapi.NULL
+ )
+ break
+ except OSError as e:
+ if attempts >= _MAX_PIPE_ATTEMPTS:
+ raise
+ if e.winerror not in (_winapi.ERROR_PIPE_BUSY,
+ _winapi.ERROR_ACCESS_DENIED):
+ raise
h2 = _winapi.CreateFile(
address, access, 0, _winapi.NULL, _winapi.OPEN_EXISTING,
_winapi.FILE_FLAG_OVERLAPPED, _winapi.NULL
diff --git a/Lib/tempfile.py b/Lib/tempfile.py
index 5e3ccab5f48..a34e062f839 100644
--- a/Lib/tempfile.py
+++ b/Lib/tempfile.py
@@ -57,10 +57,11 @@
if hasattr(_os, 'O_BINARY'):
_bin_openflags |= _os.O_BINARY
-if hasattr(_os, 'TMP_MAX'):
- TMP_MAX = _os.TMP_MAX
-else:
- TMP_MAX = 10000
+# This is more than enough.
+# Each name contains over 40 random bits. Even with a million temporary
+# files, the chance of a conflict is less than 1 in a million, and with
+# 20 attempts, it is less than 1e-120.
+TMP_MAX = 20
# This variable _was_ unused for legacy reasons, see issue 10354.
# But as of 3.5 we actually use it at runtime so changing it would
@@ -196,8 +197,7 @@ def _get_default_tempdir(dirlist=None):
for dir in dirlist:
if dir != _os.curdir:
dir = _os.path.abspath(dir)
- # Try only a few names per directory.
- for seq in range(100):
+ for seq in range(TMP_MAX):
name = next(namer)
filename = _os.path.join(dir, name)
try:
@@ -213,10 +213,8 @@ def _get_default_tempdir(dirlist=None):
except FileExistsError:
pass
except PermissionError:
- # This exception is thrown when a directory with the chosen name
- # already exists on windows.
- if (_os.name == 'nt' and _os.path.isdir(dir) and
- _os.access(dir, _os.W_OK)):
+ # See the comment in mkdtemp().
+ if _os.name == 'nt' and _os.path.isdir(dir):
continue
break # no point trying more names in this directory
except OSError:
@@ -258,10 +256,8 @@ def _mkstemp_inner(dir, pre, suf, flags, output_type):
except FileExistsError:
continue # try again
except PermissionError:
- # This exception is thrown when a directory with the chosen name
- # already exists on windows.
- if (_os.name == 'nt' and _os.path.isdir(dir) and
- _os.access(dir, _os.W_OK)):
+ # See the comment in mkdtemp().
+ if _os.name == 'nt' and _os.path.isdir(dir) and seq < TMP_MAX - 1:
continue
else:
raise
@@ -386,10 +382,14 @@ def mkdtemp(suffix=None, prefix=None, dir=None):
except FileExistsError:
continue # try again
except PermissionError:
- # This exception is thrown when a directory with the chosen name
- # already exists on windows.
- if (_os.name == 'nt' and _os.path.isdir(dir) and
- _os.access(dir, _os.W_OK)):
+ # On Posix, this exception is raised when the user has no
+ # write access to the parent directory.
+ # On Windows, it is also raised when a directory with
+ # the chosen name already exists, or if the parent directory
+ # is not a directory.
+ # We cannot distinguish between "directory-exists-error" and
+ # "access-denied-error".
+ if _os.name == 'nt' and _os.path.isdir(dir) and seq < TMP_MAX - 1:
continue
else:
raise
diff --git a/Lib/test/.ruff.toml b/Lib/test/.ruff.toml
index f800dc03dce..f6a4dc631c7 100644
--- a/Lib/test/.ruff.toml
+++ b/Lib/test/.ruff.toml
@@ -1,6 +1,7 @@
extend = "../../.ruff.toml" # Inherit the project-wide settings
-target-version = "py312"
+# Unlike Tools/, tests can use newer syntax than PYTHON_FOR_REGEN
+target-version = "py314"
extend-exclude = [
# Excluded (run with the other AC files in its own separate ruff job in pre-commit)
@@ -15,15 +16,6 @@ extend-exclude = [
"test_grammar.py",
]
-[per-file-target-version]
-# Type parameter defaults
-"test_type_params.py" = "py313"
-
-# Template string literals
-"test_annotationlib.py" = "py314"
-"test_string/test_templatelib.py" = "py314"
-"test_tstring.py" = "py314"
-
[lint]
select = [
"F811", # Redefinition of unused variable (useful for finding test methods with the same name)
diff --git a/Lib/test/pythoninfo.py b/Lib/test/pythoninfo.py
index 6f6e0903d86..0d537c0b2cc 100644
--- a/Lib/test/pythoninfo.py
+++ b/Lib/test/pythoninfo.py
@@ -739,6 +739,10 @@ def collect_test_socket(info_add):
if name.startswith('HAVE_')]
copy_attributes(info_add, test_socket, 'test_socket.%s', attributes)
+ # Get IOCTL_VM_SOCKETS_GET_LOCAL_CID of /dev/vsock
+ cid = test_socket.get_cid()
+ info_add('test_socket.get_cid', cid)
+
def collect_support(info_add):
try:
diff --git a/Lib/test/support/__init__.py b/Lib/test/support/__init__.py
index 2d14cade188..6635ec3474e 100644
--- a/Lib/test/support/__init__.py
+++ b/Lib/test/support/__init__.py
@@ -3034,6 +3034,10 @@ def get_signal_name(exitcode):
except KeyError:
pass
+ # Format Windows exit status as hexadecimal
+ if 0xC0000000 <= exitcode:
+ return f"0x{exitcode:X}"
+
return None
class BrokenIter:
diff --git a/Lib/test/support/threading_helper.py b/Lib/test/support/threading_helper.py
index 3e04c344a0d..cf87233f0e2 100644
--- a/Lib/test/support/threading_helper.py
+++ b/Lib/test/support/threading_helper.py
@@ -250,21 +250,32 @@ def requires_working_threading(*, module=False):
return unittest.skipUnless(can_start_thread, msg)
-def run_concurrently(worker_func, nthreads, args=(), kwargs={}):
+def run_concurrently(worker_func, nthreads=None, args=(), kwargs={}):
"""
- Run the worker function concurrently in multiple threads.
+ Run the worker function(s) concurrently in multiple threads.
+
+ If `worker_func` is a single callable, it is used for all threads.
+ If it is a list of callables, each callable is used for one thread.
"""
+ from collections.abc import Iterable
+
+ if nthreads is None:
+ nthreads = len(worker_func)
+ if not isinstance(worker_func, Iterable):
+ worker_func = [worker_func] * nthreads
+ assert len(worker_func) == nthreads
+
barrier = threading.Barrier(nthreads)
- def wrapper_func(*args, **kwargs):
+ def wrapper_func(func, *args, **kwargs):
# Wait for all threads to reach this point before proceeding.
barrier.wait()
- worker_func(*args, **kwargs)
+ func(*args, **kwargs)
with catch_threading_exception() as cm:
workers = [
- threading.Thread(target=wrapper_func, args=args, kwargs=kwargs)
- for _ in range(nthreads)
+ threading.Thread(target=wrapper_func, args=(func, *args), kwargs=kwargs)
+ for func in worker_func
]
with start_threads(workers):
pass
diff --git a/Lib/test/test__interpchannels.py b/Lib/test/test__interpchannels.py
index d7cf77368ef..2b0aba42896 100644
--- a/Lib/test/test__interpchannels.py
+++ b/Lib/test/test__interpchannels.py
@@ -382,6 +382,38 @@ def test_sequential_ids(self):
self.assertEqual(id3, int(id2) + 1)
self.assertEqual(set(after) - set(before), {id1, id2, id3})
+ def test_channel_list_all_closed(self):
+ id1 = _channels.create()
+ id2 = _channels.create()
+ id3 = _channels.create()
+ before = _channels.list_all()
+ expected = [info for info in before if info[0] != id2]
+ _channels.close(id2, force=True)
+ after = _channels.list_all()
+ self.assertEqual(set(after), set(expected))
+ self.assertEqual(len(after), len(before) - 1)
+
+ def test_channel_list_all_destroyed(self):
+ id1 = _channels.create()
+ id2 = _channels.create()
+ id3 = _channels.create()
+ before = _channels.list_all()
+ expected = [info for info in before if info[0] != id2]
+ _channels.destroy(id2)
+ after = _channels.list_all()
+ self.assertEqual(set(after), set(expected))
+ self.assertEqual(len(after), len(before) - 1)
+
+ def test_channel_list_all_released(self):
+ id1 = _channels.create()
+ id2 = _channels.create()
+ id3 = _channels.create()
+ before = _channels.list_all()
+ _channels.release(id2, send=True, recv=True)
+ after = _channels.list_all()
+ self.assertEqual(set(after), set(before))
+ self.assertEqual(len(after), len(before))
+
def test_ids_global(self):
id1 = _interpreters.create()
out = _run_output(id1, dedent("""
diff --git a/Lib/test/test_argparse.py b/Lib/test/test_argparse.py
index f48fb765bb3..8331d021813 100644
--- a/Lib/test/test_argparse.py
+++ b/Lib/test/test_argparse.py
@@ -81,6 +81,27 @@ def test_skip_invalid_stdout(self):
self.assertRegex(mocked_stderr.getvalue(), r'usage:')
+class TestArgumentParserPickleable(unittest.TestCase):
+
+ @force_not_colorized
+ def test_pickle_roundtrip(self):
+ import pickle
+ parser = argparse.ArgumentParser(exit_on_error=False)
+ parser.add_argument('--foo', type=int, default=42)
+ parser.add_argument('bar', nargs='?', default='baz')
+ for proto in range(pickle.HIGHEST_PROTOCOL + 1):
+ with self.subTest(protocol=proto):
+ # Try to pickle and unpickle the parser
+ parser2 = pickle.loads(pickle.dumps(parser, protocol=proto))
+ # Check that the round-tripped parser still works
+ ns = parser2.parse_args(['--foo', '123', 'quux'])
+ self.assertEqual(ns.foo, 123)
+ self.assertEqual(ns.bar, 'quux')
+ ns2 = parser2.parse_args([])
+ self.assertEqual(ns2.foo, 42)
+ self.assertEqual(ns2.bar, 'baz')
+
+
class TestCase(unittest.TestCase):
def setUp(self):
diff --git a/Lib/test/test_asyncio/test_streams.py b/Lib/test/test_asyncio/test_streams.py
index f93ee54abc6..cae8c7c6f7c 100644
--- a/Lib/test/test_asyncio/test_streams.py
+++ b/Lib/test/test_asyncio/test_streams.py
@@ -819,6 +819,48 @@ async def client(addr):
self.assertEqual(msg1, b"hello world 1!\n")
self.assertEqual(msg2, b"hello world 2!\n")
+ @unittest.skipIf(ssl is None, 'No ssl module')
+ def test_start_tls_buffered_data(self):
+ # gh-142352: test start_tls() with buffered data
+
+ async def server_handler(client_reader, client_writer):
+ # Wait for TLS ClientHello to be buffered before start_tls().
+ await client_reader._wait_for_data('test_start_tls_buffered_data'),
+ self.assertTrue(client_reader._buffer)
+ await client_writer.start_tls(test_utils.simple_server_sslcontext())
+
+ line = await client_reader.readline()
+ self.assertEqual(line, b"ping\n")
+ client_writer.write(b"pong\n")
+ await client_writer.drain()
+ client_writer.close()
+ await client_writer.wait_closed()
+
+ async def client(addr):
+ reader, writer = await asyncio.open_connection(*addr)
+ await writer.start_tls(test_utils.simple_client_sslcontext())
+
+ writer.write(b"ping\n")
+ await writer.drain()
+ line = await reader.readline()
+ self.assertEqual(line, b"pong\n")
+ writer.close()
+ await writer.wait_closed()
+
+ async def run_test():
+ server = await asyncio.start_server(
+ server_handler, socket_helper.HOSTv4, 0)
+ server_addr = server.sockets[0].getsockname()
+
+ await client(server_addr)
+ server.close()
+ await server.wait_closed()
+
+ messages = []
+ self.loop.set_exception_handler(lambda loop, ctx: messages.append(ctx))
+ self.loop.run_until_complete(run_test())
+ self.assertEqual(messages, [])
+
def test_streamreader_constructor_without_loop(self):
with self.assertRaisesRegex(RuntimeError, 'no current event loop'):
asyncio.StreamReader()
diff --git a/Lib/test/test_asyncio/test_subprocess.py b/Lib/test/test_asyncio/test_subprocess.py
index bf301740741..c08eb7cf261 100644
--- a/Lib/test/test_asyncio/test_subprocess.py
+++ b/Lib/test/test_asyncio/test_subprocess.py
@@ -111,6 +111,37 @@ def test_subprocess_repr(self):
)
transport.close()
+ def test_proc_exited_no_invalid_state_error_on_exit_waiters(self):
+ # gh-145541: when _connect_pipes hasn't completed (so
+ # _pipes_connected is False) and the process exits, _try_finish()
+ # sets the result on exit waiters. Then _call_connection_lost() must
+ # not call set_result() again on the same waiters.
+ self.loop.set_exception_handler(
+ lambda loop, context: self.fail(
+ f"unexpected exception: {context}")
+ )
+ waiter = self.loop.create_future()
+ transport, protocol = self.create_transport(waiter)
+
+ # Simulate a waiter registered via _wait() before the process exits.
+ exit_waiter = self.loop.create_future()
+ transport._exit_waiters.append(exit_waiter)
+
+ # _connect_pipes hasn't completed, so _pipes_connected is False.
+ self.assertFalse(transport._pipes_connected)
+
+ # Simulate process exit. _try_finish() will set the result on
+ # exit_waiter because _pipes_connected is False, and then schedule
+ # _call_connection_lost() because _pipes is empty (vacuously all
+ # disconnected). _call_connection_lost() must skip exit_waiter
+ # because it's already done.
+ transport._process_exited(6)
+ self.loop.run_until_complete(waiter)
+
+ self.assertEqual(exit_waiter.result(), 6)
+
+ transport.close()
+
class SubprocessMixin:
diff --git a/Lib/test/test_bisect.py b/Lib/test/test_bisect.py
index 97204d4cad3..a7e1f533ff2 100644
--- a/Lib/test/test_bisect.py
+++ b/Lib/test/test_bisect.py
@@ -391,9 +391,9 @@ class TestErrorHandlingC(TestErrorHandling, unittest.TestCase):
class TestDocExample:
def test_grades(self):
- def grade(score, breakpoints=[60, 70, 80, 90], grades='FDCBA'):
- i = self.module.bisect(breakpoints, score)
- return grades[i]
+ def grade(score):
+ i = self.module.bisect([60, 70, 80, 90], score)
+ return "FDCBA"[i]
result = [grade(score) for score in [33, 99, 77, 70, 89, 90, 100]]
self.assertEqual(result, ['F', 'A', 'C', 'C', 'B', 'A', 'A'])
diff --git a/Lib/test/test_bz2.py b/Lib/test/test_bz2.py
index 3b7897b8a88..d8e3b671ec2 100644
--- a/Lib/test/test_bz2.py
+++ b/Lib/test/test_bz2.py
@@ -66,18 +66,28 @@ class BaseTest(unittest.TestCase):
EMPTY_DATA = b'BZh9\x17rE8P\x90\x00\x00\x00\x00'
BAD_DATA = b'this is not a valid bzip2 file'
- # Some tests need more than one block of uncompressed data. Since one block
- # is at least 100,000 bytes, we gather some data dynamically and compress it.
- # Note that this assumes that compression works correctly, so we cannot
- # simply use the bigger test data for all tests.
+ # Some tests need more than one block of data. The bz2 module does not
+ # support flushing a block during compression, so we must read in data until
+ # there are at least 2 blocks. Since different orderings of Python files may
+ # be compressed differently, we need to check the compression output for
+ # more than one bzip2 block header magic, a hex encoding of Pi
+ # (0x314159265359)
+ bz2_block_magic = bytes.fromhex('314159265359')
test_size = 0
- BIG_TEXT = bytearray(128*1024)
+ BIG_TEXT = b''
+ BIG_DATA = b''
+ compressor = BZ2Compressor(1)
for fname in glob.glob(os.path.join(glob.escape(os.path.dirname(__file__)), '*.py')):
with open(fname, 'rb') as fh:
- test_size += fh.readinto(memoryview(BIG_TEXT)[test_size:])
- if test_size > 128*1024:
+ data = fh.read()
+ BIG_DATA += compressor.compress(data)
+ BIG_TEXT += data
+ # TODO(emmatyping): if it is impossible for a block header to cross
+ # multiple outputs, we can just search the output of each compress call
+ # which should be more efficient
+ if BIG_DATA.count(bz2_block_magic) > 1:
+ BIG_DATA += compressor.flush()
break
- BIG_DATA = bz2.compress(BIG_TEXT, compresslevel=1)
def setUp(self):
fd, self.filename = tempfile.mkstemp()
diff --git a/Lib/test/test_capi/test_function.py b/Lib/test/test_capi/test_function.py
index 9dca377e28b..c1a278e5d4d 100644
--- a/Lib/test/test_capi/test_function.py
+++ b/Lib/test/test_capi/test_function.py
@@ -307,10 +307,27 @@ def function_without_closure(): ...
_testcapi.function_get_closure(function_without_closure), (1, 2))
self.assertEqual(function_without_closure.__closure__, (1, 2))
+ def test_function_get_annotations(self):
+ # Test PyFunction_GetAnnotations()
+ def normal():
+ pass
+
+ def annofn(arg: int) -> str:
+ return f'arg = {arg}'
+
+ annotations = _testcapi.function_get_annotations(normal)
+ self.assertIsNone(annotations)
+
+ annotations = _testcapi.function_get_annotations(annofn)
+ self.assertIsInstance(annotations, dict)
+ self.assertEqual(annotations, annofn.__annotations__)
+
+ with self.assertRaises(SystemError):
+ _testcapi.function_get_annotations(None)
+
# TODO: test PyFunction_New()
# TODO: test PyFunction_NewWithQualName()
# TODO: test PyFunction_SetVectorcall()
- # TODO: test PyFunction_GetAnnotations()
# TODO: test PyFunction_SetAnnotations()
# TODO: test PyClassMethod_New()
# TODO: test PyStaticMethod_New()
diff --git a/Lib/test/test_cext/__init__.py b/Lib/test/test_cext/__init__.py
index 46fde541494..f75257f3d88 100644
--- a/Lib/test/test_cext/__init__.py
+++ b/Lib/test/test_cext/__init__.py
@@ -12,7 +12,9 @@
from test import support
-SOURCE = os.path.join(os.path.dirname(__file__), 'extension.c')
+SOURCES = [
+ os.path.join(os.path.dirname(__file__), 'extension.c'),
+]
SETUP = os.path.join(os.path.dirname(__file__), 'setup.py')
@@ -28,29 +30,13 @@
@support.requires_venv_with_pip()
@support.requires_subprocess()
@support.requires_resource('cpu')
-class TestExt(unittest.TestCase):
+class BaseTests:
+ TEST_INTERNAL_C_API = False
+
# Default build with no options
def test_build(self):
self.check_build('_test_cext')
- def test_build_c11(self):
- self.check_build('_test_c11_cext', std='c11')
-
- @unittest.skipIf(support.MS_WINDOWS, "MSVC doesn't support /std:c99")
- def test_build_c99(self):
- # In public docs, we say C API is compatible with C11. However,
- # in practice we do maintain C99 compatibility in public headers.
- # Please ask the C API WG before adding a new C11-only feature.
- self.check_build('_test_c99_cext', std='c99')
-
- @support.requires_gil_enabled('incompatible with Free Threading')
- def test_build_limited(self):
- self.check_build('_test_limited_cext', limited=True)
-
- @support.requires_gil_enabled('broken for now with Free Threading')
- def test_build_limited_c11(self):
- self.check_build('_test_limited_c11_cext', limited=True, std='c11')
-
def check_build(self, extension_name, std=None, limited=False):
venv_dir = 'env'
with support.setup_venv_with_pip_setuptools(venv_dir) as python_exe:
@@ -61,7 +47,9 @@ def _check_build(self, extension_name, python_exe, std, limited):
pkg_dir = 'pkg'
os.mkdir(pkg_dir)
shutil.copy(SETUP, os.path.join(pkg_dir, os.path.basename(SETUP)))
- shutil.copy(SOURCE, os.path.join(pkg_dir, os.path.basename(SOURCE)))
+ for source in SOURCES:
+ dest = os.path.join(pkg_dir, os.path.basename(source))
+ shutil.copy(source, dest)
def run_cmd(operation, cmd):
env = os.environ.copy()
@@ -70,6 +58,7 @@ def run_cmd(operation, cmd):
if limited:
env['CPYTHON_TEST_LIMITED'] = '1'
env['CPYTHON_TEST_EXT_NAME'] = extension_name
+ env['TEST_INTERNAL_C_API'] = str(int(self.TEST_INTERNAL_C_API))
if support.verbose:
print('Run:', ' '.join(map(shlex.quote, cmd)))
subprocess.run(cmd, check=True, env=env)
@@ -110,5 +99,29 @@ def run_cmd(operation, cmd):
run_cmd('Import', cmd)
+class TestPublicCAPI(BaseTests, unittest.TestCase):
+ @support.requires_gil_enabled('incompatible with Free Threading')
+ def test_build_limited(self):
+ self.check_build('_test_limited_cext', limited=True)
+
+ @support.requires_gil_enabled('broken for now with Free Threading')
+ def test_build_limited_c11(self):
+ self.check_build('_test_limited_c11_cext', limited=True, std='c11')
+
+ def test_build_c11(self):
+ self.check_build('_test_c11_cext', std='c11')
+
+ @unittest.skipIf(support.MS_WINDOWS, "MSVC doesn't support /std:c99")
+ def test_build_c99(self):
+ # In public docs, we say C API is compatible with C11. However,
+ # in practice we do maintain C99 compatibility in public headers.
+ # Please ask the C API WG before adding a new C11-only feature.
+ self.check_build('_test_c99_cext', std='c99')
+
+
+class TestInteralCAPI(BaseTests, unittest.TestCase):
+ TEST_INTERNAL_C_API = True
+
+
if __name__ == "__main__":
unittest.main()
diff --git a/Lib/test/test_cext/extension.c b/Lib/test/test_cext/extension.c
index 64629c5a6da..56f40b354c6 100644
--- a/Lib/test/test_cext/extension.c
+++ b/Lib/test/test_cext/extension.c
@@ -1,10 +1,34 @@
// gh-116869: Basic C test extension to check that the Python C API
// does not emit C compiler warnings.
+//
+// Test also the internal C API if the TEST_INTERNAL_C_API macro is defined.
// Always enable assertions
#undef NDEBUG
+#ifdef TEST_INTERNAL_C_API
+# define Py_BUILD_CORE_MODULE 1
+#endif
+
#include "Python.h"
+#include "datetime.h"
+
+#ifdef TEST_INTERNAL_C_API
+ // gh-135906: Check for compiler warnings in the internal C API.
+ // - Cython uses pycore_critical_section.h, pycore_frame.h and
+ // pycore_template.h.
+ // - greenlet uses pycore_frame.h, pycore_interpframe_structs.h and
+ // pycore_interpframe.h.
+# include "internal/pycore_critical_section.h"
+# include "internal/pycore_frame.h"
+# include "internal/pycore_gc.h"
+# include "internal/pycore_interp.h"
+# include "internal/pycore_interpframe.h"
+# include "internal/pycore_interpframe_structs.h"
+# include "internal/pycore_object.h"
+# include "internal/pycore_pystate.h"
+# include "internal/pycore_template.h"
+#endif
#ifndef MODULE_NAME
# error "MODULE_NAME macro must be defined"
@@ -30,27 +54,43 @@ _testcext_add(PyObject *Py_UNUSED(module), PyObject *args)
}
+static PyObject *
+test_datetime(PyObject *Py_UNUSED(module), PyObject *Py_UNUSED(args))
+{
+ // datetime.h is excluded from the limited C API
+#ifndef Py_LIMITED_API
+ PyDateTime_IMPORT;
+ if (PyErr_Occurred()) {
+ return NULL;
+ }
+#endif
+
+ Py_RETURN_NONE;
+}
+
+
static PyMethodDef _testcext_methods[] = {
{"add", _testcext_add, METH_VARARGS, _testcext_add_doc},
+ {"test_datetime", test_datetime, METH_NOARGS, NULL},
{NULL, NULL, 0, NULL} // sentinel
};
static int
-_testcext_exec(
-#ifdef __STDC_VERSION__
- PyObject *module
-#else
- PyObject *Py_UNUSED(module)
-#endif
- )
+_testcext_exec(PyObject *module)
{
+ PyObject *result;
+
#ifdef __STDC_VERSION__
if (PyModule_AddIntMacro(module, __STDC_VERSION__) < 0) {
return -1;
}
#endif
+ result = PyObject_CallMethod(module, "test_datetime", "");
+ if (!result) return -1;
+ Py_DECREF(result);
+
// test Py_BUILD_ASSERT() and Py_BUILD_ASSERT_EXPR()
Py_BUILD_ASSERT(sizeof(int) == sizeof(unsigned int));
assert(Py_BUILD_ASSERT_EXPR(sizeof(int) == sizeof(unsigned int)) == 0);
diff --git a/Lib/test/test_cext/setup.py b/Lib/test/test_cext/setup.py
index 1275282983f..f2a8c9f9381 100644
--- a/Lib/test/test_cext/setup.py
+++ b/Lib/test/test_cext/setup.py
@@ -14,10 +14,15 @@
if not support.MS_WINDOWS:
# C compiler flags for GCC and clang
- CFLAGS = [
+ BASE_CFLAGS = [
# The purpose of test_cext extension is to check that building a C
# extension using the Python C API does not emit C compiler warnings.
'-Werror',
+ ]
+
+ # C compiler flags for GCC and clang
+ PUBLIC_CFLAGS = [
+ *BASE_CFLAGS,
# gh-120593: Check the 'const' qualifier
'-Wcast-qual',
@@ -26,27 +31,42 @@
'-pedantic-errors',
]
if not support.Py_GIL_DISABLED:
- CFLAGS.append(
+ PUBLIC_CFLAGS.append(
# gh-116869: The Python C API must be compatible with building
# with the -Werror=declaration-after-statement compiler flag.
'-Werror=declaration-after-statement',
)
+ INTERNAL_CFLAGS = [*BASE_CFLAGS]
else:
# MSVC compiler flags
- CFLAGS = [
- # Display warnings level 1 to 4
- '/W4',
+ BASE_CFLAGS = [
# Treat all compiler warnings as compiler errors
'/WX',
]
+ PUBLIC_CFLAGS = [
+ *BASE_CFLAGS,
+ # Display warnings level 1 to 4
+ '/W4',
+ ]
+ INTERNAL_CFLAGS = [
+ *BASE_CFLAGS,
+ # Display warnings level 1 to 3
+ '/W3',
+ ]
def main():
std = os.environ.get("CPYTHON_TEST_STD", "")
module_name = os.environ["CPYTHON_TEST_EXT_NAME"]
limited = bool(os.environ.get("CPYTHON_TEST_LIMITED", ""))
+ internal = bool(int(os.environ.get("TEST_INTERNAL_C_API", "0")))
- cflags = list(CFLAGS)
+ sources = [SOURCE]
+
+ if not internal:
+ cflags = list(PUBLIC_CFLAGS)
+ else:
+ cflags = list(INTERNAL_CFLAGS)
cflags.append(f'-DMODULE_NAME={module_name}')
# Add -std=STD or /std:STD (MSVC) compiler flag
@@ -75,6 +95,9 @@ def main():
version = sys.hexversion
cflags.append(f'-DPy_LIMITED_API={version:#x}')
+ if internal:
+ cflags.append('-DTEST_INTERNAL_C_API=1')
+
# On Windows, add PCbuild\amd64\ to include and library directories
include_dirs = []
library_dirs = []
@@ -90,7 +113,7 @@ def main():
print(f"Add PCbuild directory: {pcbuild}")
# Display information to help debugging
- for env_name in ('CC', 'CFLAGS'):
+ for env_name in ('CC', 'CFLAGS', 'CPPFLAGS'):
if env_name in os.environ:
print(f"{env_name} env var: {os.environ[env_name]!r}")
else:
@@ -99,7 +122,7 @@ def main():
ext = Extension(
module_name,
- sources=[SOURCE],
+ sources=sources,
extra_compile_args=cflags,
include_dirs=include_dirs,
library_dirs=library_dirs)
diff --git a/Lib/test/test_cmd_line.py b/Lib/test/test_cmd_line.py
index c17d749d4a1..ab65342f620 100644
--- a/Lib/test/test_cmd_line.py
+++ b/Lib/test/test_cmd_line.py
@@ -9,7 +9,6 @@
import tempfile
import textwrap
import unittest
-import warnings
from test import support
from test.support import os_helper
from test.support import force_not_colorized
@@ -937,21 +936,15 @@ def test_python_asyncio_debug(self):
@unittest.skipUnless(sysconfig.get_config_var('Py_TRACE_REFS'), "Requires --with-trace-refs build option")
def test_python_dump_refs(self):
- code = 'import sys; sys._clear_type_cache()'
- # TODO: Remove warnings context manager once sys._clear_type_cache is removed
- with warnings.catch_warnings():
- warnings.simplefilter("ignore", DeprecationWarning)
- rc, out, err = assert_python_ok('-c', code, PYTHONDUMPREFS='1')
+ code = 'import sys; sys._clear_internal_caches()'
+ rc, out, err = assert_python_ok('-c', code, PYTHONDUMPREFS='1')
self.assertEqual(rc, 0)
@unittest.skipUnless(sysconfig.get_config_var('Py_TRACE_REFS'), "Requires --with-trace-refs build option")
def test_python_dump_refs_file(self):
with tempfile.NamedTemporaryFile() as dump_file:
- code = 'import sys; sys._clear_type_cache()'
- # TODO: Remove warnings context manager once sys._clear_type_cache is removed
- with warnings.catch_warnings():
- warnings.simplefilter("ignore", DeprecationWarning)
- rc, out, err = assert_python_ok('-c', code, PYTHONDUMPREFSFILE=dump_file.name)
+ code = 'import sys; sys._clear_internal_caches()'
+ rc, out, err = assert_python_ok('-c', code, PYTHONDUMPREFSFILE=dump_file.name)
self.assertEqual(rc, 0)
with open(dump_file.name, 'r') as file:
contents = file.read()
diff --git a/Lib/test/test_compile.py b/Lib/test/test_compile.py
index d37a9db8c83..a6542b396cc 100644
--- a/Lib/test/test_compile.py
+++ b/Lib/test/test_compile.py
@@ -249,8 +249,8 @@ def test_32_63_bit_values(self):
d = -281474976710656 # 1 << 48
e = +4611686018427387904 # 1 << 62
f = -4611686018427387904 # 1 << 62
- g = +9223372036854775807 # 1 << 63 - 1
- h = -9223372036854775807 # 1 << 63 - 1
+ g = +9223372036854775807 # (1 << 63) - 1
+ h = -9223372036854775807 # (1 << 63) - 1
for variable in self.test_32_63_bit_values.__code__.co_consts:
if variable is not None:
diff --git a/Lib/test/test_complex.py b/Lib/test/test_complex.py
index 0c7e7341f13..bee2aceb187 100644
--- a/Lib/test/test_complex.py
+++ b/Lib/test/test_complex.py
@@ -72,8 +72,8 @@ def assertAlmostEqual(self, a, b):
else:
unittest.TestCase.assertAlmostEqual(self, a, b)
- def assertCloseAbs(self, x, y, eps=1e-9):
- """Return true iff floats x and y "are close"."""
+ def assertClose(self, x, y, eps=1e-9):
+ """Return true iff complexes x and y "are close"."""
# put the one with larger magnitude second
if abs(x) > abs(y):
x, y = y, x
@@ -82,26 +82,15 @@ def assertCloseAbs(self, x, y, eps=1e-9):
if x == 0:
return abs(y) < eps
# check that relative difference < eps
- self.assertTrue(abs((x-y)/y) < eps)
-
- def assertClose(self, x, y, eps=1e-9):
- """Return true iff complexes x and y "are close"."""
- self.assertCloseAbs(x.real, y.real, eps)
- self.assertCloseAbs(x.imag, y.imag, eps)
+ self.assertTrue(abs(x-y)/abs(y) < eps)
def check_div(self, x, y):
"""Compute complex z=x*y, and check that z/x==y and z/y==x."""
z = x * y
- if x != 0:
- q = z / x
- self.assertClose(q, y)
- q = z.__truediv__(x)
- self.assertClose(q, y)
- if y != 0:
- q = z / y
- self.assertClose(q, x)
- q = z.__truediv__(y)
- self.assertClose(q, x)
+ if x:
+ self.assertClose(z / x, y)
+ if y:
+ self.assertClose(z / y, x)
def test_truediv(self):
simple_real = [float(i) for i in range(-5, 6)]
@@ -115,10 +104,20 @@ def test_truediv(self):
self.check_div(complex(1e200, 1e200), 1+0j)
self.check_div(complex(1e-200, 1e-200), 1+0j)
+ # Smith's algorithm has several sources of inaccuracy
+ # for components of the result. In examples below,
+ # it's cancellation of digits in computation of sum.
+ self.check_div(1e-09+1j, 1+1j)
+ self.check_div(8.289760544677449e-09+0.13257307440728516j,
+ 0.9059966714925808+0.5054864708672686j)
+
# Just for fun.
for i in range(100):
- self.check_div(complex(random(), random()),
- complex(random(), random()))
+ x = complex(random(), random())
+ y = complex(random(), random())
+ self.check_div(x, y)
+ y = complex(1e10*y.real, y.imag)
+ self.check_div(x, y)
self.assertAlmostEqual(complex.__truediv__(2+0j, 1+1j), 1-1j)
self.assertRaises(TypeError, operator.truediv, 1j, None)
@@ -454,7 +453,7 @@ def test_boolcontext(self):
self.assertTrue(1j)
def test_conjugate(self):
- self.assertClose(complex(5.3, 9.8).conjugate(), 5.3-9.8j)
+ self.assertEqual(complex(5.3, 9.8).conjugate(), 5.3-9.8j)
def test_constructor(self):
def check(z, x, y):
diff --git a/Lib/test/test_cppext/__init__.py b/Lib/test/test_cppext/__init__.py
index 2b7adac4bcc..5b4c97c181b 100644
--- a/Lib/test/test_cppext/__init__.py
+++ b/Lib/test/test_cppext/__init__.py
@@ -1,9 +1,11 @@
# gh-91321: Build a basic C++ test extension to check that the Python C API is
# compatible with C++ and does not emit C++ compiler warnings.
import os.path
+import platform
import shlex
import shutil
import subprocess
+import sys
import unittest
from test import support
@@ -24,41 +26,19 @@
@support.requires_venv_with_pip()
@support.requires_subprocess()
@support.requires_resource('cpu')
-class TestCPPExt(unittest.TestCase):
- def test_build(self):
- self.check_build('_testcppext')
-
- def test_build_cpp03(self):
- # In public docs, we say C API is compatible with C++11. However,
- # in practice we do maintain C++03 compatibility in public headers.
- # Please ask the C API WG before adding a new C++11-only feature.
- self.check_build('_testcpp03ext', std='c++03')
-
- @support.requires_gil_enabled('incompatible with Free Threading')
- def test_build_limited_cpp03(self):
- self.check_build('_test_limited_cpp03ext', std='c++03', limited=True)
-
- @unittest.skipIf(support.MS_WINDOWS, "MSVC doesn't support /std:c++11")
- def test_build_cpp11(self):
- self.check_build('_testcpp11ext', std='c++11')
-
- # Only test C++14 on MSVC.
- # On s390x RHEL7, GCC 4.8.5 doesn't support C++14.
- @unittest.skipIf(not support.MS_WINDOWS, "need Windows")
- def test_build_cpp14(self):
- self.check_build('_testcpp14ext', std='c++14')
+class BaseTests:
+ TEST_INTERNAL_C_API = False
- @support.requires_gil_enabled('incompatible with Free Threading')
- def test_build_limited(self):
- self.check_build('_testcppext_limited', limited=True)
-
- def check_build(self, extension_name, std=None, limited=False):
+ def check_build(self, extension_name, std=None, limited=False,
+ extra_cflags=None):
venv_dir = 'env'
with support.setup_venv_with_pip_setuptools(venv_dir) as python_exe:
self._check_build(extension_name, python_exe,
- std=std, limited=limited)
+ std=std, limited=limited,
+ extra_cflags=extra_cflags)
- def _check_build(self, extension_name, python_exe, std, limited):
+ def _check_build(self, extension_name, python_exe, std, limited,
+ extra_cflags=None):
pkg_dir = 'pkg'
os.mkdir(pkg_dir)
shutil.copy(SETUP, os.path.join(pkg_dir, os.path.basename(SETUP)))
@@ -71,6 +51,9 @@ def run_cmd(operation, cmd):
if limited:
env['CPYTHON_TEST_LIMITED'] = '1'
env['CPYTHON_TEST_EXT_NAME'] = extension_name
+ env['TEST_INTERNAL_C_API'] = str(int(self.TEST_INTERNAL_C_API))
+ if extra_cflags:
+ env['CPYTHON_TEST_EXTRA_CFLAGS'] = extra_cflags
if support.verbose:
print('Run:', ' '.join(map(shlex.quote, cmd)))
subprocess.run(cmd, check=True, env=env)
@@ -111,5 +94,53 @@ def run_cmd(operation, cmd):
run_cmd('Import', cmd)
+class TestPublicCAPI(BaseTests, unittest.TestCase):
+ def test_build(self):
+ self.check_build('_testcppext')
+
+ @support.requires_gil_enabled('incompatible with Free Threading')
+ def test_build_limited_cpp03(self):
+ self.check_build('_test_limited_cpp03ext', std='c++03', limited=True)
+
+ @support.requires_gil_enabled('incompatible with Free Threading')
+ def test_build_limited(self):
+ self.check_build('_testcppext_limited', limited=True)
+
+ def test_build_cpp03(self):
+ # In public docs, we say C API is compatible with C++11. However,
+ # in practice we do maintain C++03 compatibility in public headers.
+ # Please ask the C API WG before adding a new C++11-only feature.
+ self.check_build('_testcpp03ext', std='c++03')
+
+ @unittest.skipIf(support.MS_WINDOWS, "MSVC doesn't support /std:c++11")
+ def test_build_cpp11(self):
+ self.check_build('_testcpp11ext', std='c++11')
+
+ # Only test C++14 on MSVC.
+ # On s390x RHEL7, GCC 4.8.5 doesn't support C++14.
+ @unittest.skipIf(not support.MS_WINDOWS, "need Windows")
+ def test_build_cpp14(self):
+ self.check_build('_testcpp14ext', std='c++14')
+
+ # Test that headers compile with Intel asm syntax, which may conflict
+ # with inline assembly in free-threading headers that use AT&T syntax.
+ @unittest.skipIf(support.MS_WINDOWS, "MSVC doesn't support -masm=intel")
+ @unittest.skipUnless(platform.machine() in ('x86_64', 'i686', 'AMD64'),
+ "x86-specific flag")
+ def test_build_intel_asm(self):
+ self.check_build('_testcppext_asm', extra_cflags='-masm=intel')
+
+
+class TestInteralCAPI(BaseTests, unittest.TestCase):
+ TEST_INTERNAL_C_API = True
+
+ def test_build(self):
+ kwargs = {}
+ if sys.platform == 'darwin':
+ # Old Apple clang++ default C++ std is gnu++98
+ kwargs['std'] = 'c++11'
+ self.check_build('_testcppext_internal', **kwargs)
+
+
if __name__ == "__main__":
unittest.main()
diff --git a/Lib/test/test_cppext/extension.cpp b/Lib/test/test_cppext/extension.cpp
index 5b3571b295b..4db63df94f5 100644
--- a/Lib/test/test_cppext/extension.cpp
+++ b/Lib/test/test_cppext/extension.cpp
@@ -6,7 +6,31 @@
// Always enable assertions
#undef NDEBUG
+#ifdef TEST_INTERNAL_C_API
+# define Py_BUILD_CORE_MODULE 1
+#endif
+
#include "Python.h"
+#include "datetime.h"
+
+#ifdef TEST_INTERNAL_C_API
+ // gh-135906: Check for compiler warnings in the internal C API
+ // - Cython uses pycore_critical_section.h, pycore_frame.h and
+ // pycore_template.h.
+ // - greenlet uses pycore_frame.h, pycore_interpframe_structs.h and
+ // pycore_interpframe.h.
+# include "internal/pycore_frame.h"
+# include "internal/pycore_interpframe_structs.h"
+# include "internal/pycore_template.h"
+
+ // mimalloc emits compiler warnings on Windows.
+# if !defined(MS_WINDOWS)
+# include "internal/pycore_backoff.h"
+# include "internal/pycore_cell.h"
+# include "internal/pycore_critical_section.h"
+# include "internal/pycore_interpframe.h"
+# endif
+#endif
#ifndef MODULE_NAME
# error "MODULE_NAME macro must be defined"
@@ -214,11 +238,26 @@ test_virtual_object(PyObject *Py_UNUSED(module), PyObject *Py_UNUSED(args))
Py_RETURN_NONE;
}
+static PyObject *
+test_datetime(PyObject *Py_UNUSED(module), PyObject *Py_UNUSED(args))
+{
+ // datetime.h is excluded from the limited C API
+#ifndef Py_LIMITED_API
+ PyDateTime_IMPORT;
+ if (PyErr_Occurred()) {
+ return NULL;
+ }
+#endif
+
+ Py_RETURN_NONE;
+}
+
static PyMethodDef _testcppext_methods[] = {
{"add", _testcppext_add, METH_VARARGS, _testcppext_add_doc},
{"test_api_casts", test_api_casts, METH_NOARGS, _Py_NULL},
{"test_unicode", test_unicode, METH_NOARGS, _Py_NULL},
{"test_virtual_object", test_virtual_object, METH_NOARGS, _Py_NULL},
+ {"test_datetime", test_datetime, METH_NOARGS, _Py_NULL},
// Note: _testcppext_exec currently runs all test functions directly.
// When adding a new one, add a call there.
@@ -247,6 +286,10 @@ _testcppext_exec(PyObject *module)
if (!result) return -1;
Py_DECREF(result);
+ result = PyObject_CallMethod(module, "test_datetime", "");
+ if (!result) return -1;
+ Py_DECREF(result);
+
// test Py_BUILD_ASSERT() and Py_BUILD_ASSERT_EXPR()
Py_BUILD_ASSERT(sizeof(int) == sizeof(unsigned int));
assert(Py_BUILD_ASSERT_EXPR(sizeof(int) == sizeof(unsigned int)) == 0);
diff --git a/Lib/test/test_cppext/setup.py b/Lib/test/test_cppext/setup.py
index ea1ed64bf7a..14aeafefcaa 100644
--- a/Lib/test/test_cppext/setup.py
+++ b/Lib/test/test_cppext/setup.py
@@ -47,6 +47,7 @@ def main():
std = os.environ.get("CPYTHON_TEST_CPP_STD", "")
module_name = os.environ["CPYTHON_TEST_EXT_NAME"]
limited = bool(os.environ.get("CPYTHON_TEST_LIMITED", ""))
+ internal = bool(int(os.environ.get("TEST_INTERNAL_C_API", "0")))
cppflags = list(CPPFLAGS)
cppflags.append(f'-DMODULE_NAME={module_name}')
@@ -58,7 +59,7 @@ def main():
else:
cppflags.append(f'-std={std}')
- if limited or (std != 'c++03'):
+ if limited or (std != 'c++03') and not internal:
# See CPPFLAGS_PEDANTIC docstring
cppflags.extend(CPPFLAGS_PEDANTIC)
@@ -82,6 +83,13 @@ def main():
version = sys.hexversion
cppflags.append(f'-DPy_LIMITED_API={version:#x}')
+ if internal:
+ cppflags.append('-DTEST_INTERNAL_C_API=1')
+
+ extra_cflags = os.environ.get("CPYTHON_TEST_EXTRA_CFLAGS", "")
+ if extra_cflags:
+ cppflags.extend(shlex.split(extra_cflags))
+
# On Windows, add PCbuild\amd64\ to include and library directories
include_dirs = []
library_dirs = []
@@ -97,7 +105,7 @@ def main():
print(f"Add PCbuild directory: {pcbuild}")
# Display information to help debugging
- for env_name in ('CC', 'CFLAGS', 'CPPFLAGS'):
+ for env_name in ('CC', 'CXX', 'CFLAGS', 'CPPFLAGS', 'CXXFLAGS'):
if env_name in os.environ:
print(f"{env_name} env var: {os.environ[env_name]!r}")
else:
diff --git a/Lib/test/test_ctypes/test_loading.py b/Lib/test/test_ctypes/test_loading.py
index 3b8332fbb30..343f6a07c0a 100644
--- a/Lib/test/test_ctypes/test_loading.py
+++ b/Lib/test/test_ctypes/test_loading.py
@@ -106,6 +106,14 @@ def test_load_without_name_and_with_handle(self):
lib = ctypes.WinDLL(name=None, handle=handle)
self.assertIs(handle, lib._handle)
+ @unittest.skipIf(os.name == "nt", 'POSIX-specific test')
+ @unittest.skipIf(libc_name is None, 'could not find libc')
+ def test_load_without_name_and_with_handle_posix(self):
+ lib1 = CDLL(libc_name)
+ handle = lib1._handle
+ lib2 = CDLL(name=None, handle=handle)
+ self.assertIs(lib2._handle, handle)
+
@unittest.skipUnless(os.name == "nt", 'Windows-specific test')
def test_1703286_A(self):
# On winXP 64-bit, advapi32 loads at an address that does
diff --git a/Lib/test/test_descr.py b/Lib/test/test_descr.py
index d420f097e74..99f3f1ba999 100644
--- a/Lib/test/test_descr.py
+++ b/Lib/test/test_descr.py
@@ -5138,6 +5138,26 @@ def foo(self):
with self.assertRaisesRegex(NotImplementedError, "BAR"):
B().foo
+ def test_staticmethod_new(self):
+ class MyStaticMethod(staticmethod):
+ def __init__(self, func):
+ pass
+ def func(): pass
+ sm = MyStaticMethod(func)
+ self.assertEqual(repr(sm), '<staticmethod(None)>')
+ self.assertIsNone(sm.__func__)
+ self.assertIsNone(sm.__wrapped__)
+
+ def test_classmethod_new(self):
+ class MyClassMethod(classmethod):
+ def __init__(self, func):
+ pass
+ def func(): pass
+ cm = MyClassMethod(func)
+ self.assertEqual(repr(cm), '<classmethod(None)>')
+ self.assertIsNone(cm.__func__)
+ self.assertIsNone(cm.__wrapped__)
+
class DictProxyTests(unittest.TestCase):
def setUp(self):
diff --git a/Lib/test/test_dict.py b/Lib/test/test_dict.py
index 1c5a1d20daf..c1e64a5d99b 100644
--- a/Lib/test/test_dict.py
+++ b/Lib/test/test_dict.py
@@ -1569,6 +1569,26 @@ def make_pairs():
self.assertEqual(d.get(key3_3), 44)
self.assertGreaterEqual(eq_count, 1)
+ def test_overwrite_managed_dict(self):
+ # GH-130327: Overwriting an object's managed dictionary with another object's
+ # skipped traversal in favor of inline values, causing the GC to believe that
+ # the __dict__ wasn't reachable.
+ import gc
+
+ class Shenanigans:
+ pass
+
+ to_be_deleted = Shenanigans()
+ to_be_deleted.attr = "whatever"
+ holds_reference = Shenanigans()
+ holds_reference.__dict__ = to_be_deleted.__dict__
+ holds_reference.ref = {"circular": to_be_deleted, "data": 42}
+
+ del to_be_deleted
+ gc.collect()
+ self.assertEqual(holds_reference.ref['data'], 42)
+ self.assertEqual(holds_reference.attr, "whatever")
+
def test_unhashable_key(self):
d = {'a': 1}
key = [1, 2, 3]
@@ -1680,6 +1700,69 @@ def test_hash_collision_remove_add(self):
self.assertEqual(len(d), len(items), d)
self.assertEqual(d, dict(items))
+ def test_clear_reentrant_embedded(self):
+ # gh-130555: dict.clear() must be safe when values are embedded
+ # in an object and a destructor mutates the dict.
+ class MyObj: pass
+ class ClearOnDelete:
+ def __del__(self):
+ nonlocal x
+ del x
+
+ x = MyObj()
+ x.a = ClearOnDelete()
+
+ d = x.__dict__
+ d.clear()
+
+ def test_clear_reentrant_cycle(self):
+ # gh-130555: dict.clear() must be safe for embedded dicts when the
+ # object is part of a reference cycle and the last reference to the
+ # dict is via the cycle.
+ class MyObj: pass
+ obj = MyObj()
+ obj.f = obj
+ obj.attr = "attr"
+
+ d = obj.__dict__
+ del obj
+
+ d.clear()
+
+ def test_clear_reentrant_force_combined(self):
+ # gh-130555: dict.clear() must be safe when a destructor forces the
+ # dict from embedded/split to combined (setting ma_values to NULL).
+ class MyObj: pass
+ class ForceConvert:
+ def __del__(self):
+ d[1] = "trigger"
+
+ x = MyObj()
+ x.a = ForceConvert()
+ x.b = "other"
+
+ d = x.__dict__
+ d.clear()
+
+ def test_clear_reentrant_delete(self):
+ # gh-130555: dict.clear() must be safe when a destructor deletes
+ # a key from the same embedded dict.
+ class MyObj: pass
+ class DelKey:
+ def __del__(self):
+ try:
+ del d['b']
+ except KeyError:
+ pass
+
+ x = MyObj()
+ x.a = DelKey()
+ x.b = "value_b"
+ x.c = "value_c"
+
+ d = x.__dict__
+ d.clear()
+
class CAPITest(unittest.TestCase):
diff --git a/Lib/test/test_dtrace.py b/Lib/test/test_dtrace.py
index e1adf8e9748..ba2fa99707c 100644
--- a/Lib/test/test_dtrace.py
+++ b/Lib/test/test_dtrace.py
@@ -8,7 +8,7 @@
import unittest
from test import support
-from test.support import findfile
+from test.support import findfile, MS_WINDOWS
if not support.has_subprocess_support:
@@ -103,6 +103,7 @@ class SystemTapBackend(TraceBackend):
COMMAND = ["stap", "-g"]
+@unittest.skipIf(MS_WINDOWS, "Tests not compliant with trace on Windows.")
class TraceTests:
# unittest.TestCase options
maxDiff = None
diff --git a/Lib/test/test_email/test_generator.py b/Lib/test/test_email/test_generator.py
index 3ca79edf6a6..c2d7d09d591 100644
--- a/Lib/test/test_email/test_generator.py
+++ b/Lib/test/test_email/test_generator.py
@@ -393,6 +393,50 @@ def test_defaults_handle_spaces_at_start_of_continuation_line(self):
g.flatten(msg)
self.assertEqual(s.getvalue(), expected)
+ # gh-144156: fold between non-encoded and encoded words don't need to encoded
+ # the separating space
+ def test_defaults_handle_spaces_at_start_of_continuation_line_2(self):
+ source = ("Re: [SOS-1495488] Commande et livraison - Demande de retour - "
+ "bibijolie - 251210-AABBCC - Abo actualités digitales 20 semaines "
+ "d’abonnement à 24 heures, Bilan, Tribune de Genève et tous les titres Tamedia")
+ expected = (
+ b"Subject: "
+ b"Re: [SOS-1495488] Commande et livraison - Demande de retour -\n"
+ b" bibijolie - 251210-AABBCC - Abo =?utf-8?q?actualit=C3=A9s?= digitales 20\n"
+ b" semaines =?utf-8?q?d=E2=80=99abonnement_=C3=A0?= 24 heures, Bilan, Tribune de\n"
+ b" =?utf-8?q?Gen=C3=A8ve?= et tous les titres Tamedia\n\n"
+ )
+ msg = EmailMessage()
+ msg['Subject'] = source
+ s = io.BytesIO()
+ g = BytesGenerator(s)
+ g.flatten(msg)
+ self.assertEqual(s.getvalue(), expected)
+
+ def test_ew_folding_round_trip_1(self):
+ print()
+ source = "aaaaaaaaa фффффффф "
+ msg = EmailMessage()
+ msg['Subject'] = source
+ s = io.BytesIO()
+ g = BytesGenerator(s, maxheaderlen=30)
+ g.flatten(msg)
+ flat = s.getvalue()
+ reparsed = message_from_bytes(flat, policy=policy.default)['Subject']
+ self.assertMultiLineEqual(reparsed, source)
+
+ def test_ew_folding_round_trip_2(self):
+ print()
+ source = "aaa aaaaaaa aaa ффф фффф "
+ msg = EmailMessage()
+ msg['Subject'] = source
+ s = io.BytesIO()
+ g = BytesGenerator(s, maxheaderlen=30)
+ g.flatten(msg)
+ flat = s.getvalue()
+ reparsed = message_from_bytes(flat, policy=policy.default)['Subject']
+ self.assertMultiLineEqual(reparsed, source)
+
def test_cte_type_7bit_handles_unknown_8bit(self):
source = ("Subject: Maintenant je vous présente mon "
"collègue\n\n").encode('utf-8')
diff --git a/Lib/test/test_email/test_headerregistry.py b/Lib/test/test_email/test_headerregistry.py
index df34ec70504..52be7bdbb12 100644
--- a/Lib/test/test_email/test_headerregistry.py
+++ b/Lib/test/test_email/test_headerregistry.py
@@ -1702,7 +1702,7 @@ def test_fold_unstructured_with_overlong_word(self):
'singlewordthatwontfit')
self.assertEqual(
h.fold(policy=policy.default.clone(max_line_length=20)),
- 'Subject: \n'
+ 'Subject:\n'
' =?utf-8?q?thisisa?=\n'
' =?utf-8?q?verylon?=\n'
' =?utf-8?q?glineco?=\n'
@@ -1718,7 +1718,7 @@ def test_fold_unstructured_with_two_overlong_words(self):
'singlewordthatwontfit plusanotherverylongwordthatwontfit')
self.assertEqual(
h.fold(policy=policy.default.clone(max_line_length=20)),
- 'Subject: \n'
+ 'Subject:\n'
' =?utf-8?q?thisisa?=\n'
' =?utf-8?q?verylon?=\n'
' =?utf-8?q?glineco?=\n'
diff --git a/Lib/test/test_email/test_policy.py b/Lib/test/test_email/test_policy.py
index 71ec0febb0f..90e8e558029 100644
--- a/Lib/test/test_email/test_policy.py
+++ b/Lib/test/test_email/test_policy.py
@@ -273,7 +273,7 @@ def test_non_ascii_chars_do_not_cause_inf_loop(self):
actual = policy.fold('Subject', 'ą' * 12)
self.assertEqual(
actual,
- 'Subject: \n' +
+ 'Subject:\n' +
12 * ' =?utf-8?q?=C4=85?=\n')
def test_short_maxlen_error(self):
diff --git a/Lib/test/test_external_inspection.py b/Lib/test/test_external_inspection.py
index a709b837161..08779bdb008 100644
--- a/Lib/test/test_external_inspection.py
+++ b/Lib/test/test_external_inspection.py
@@ -14,6 +14,7 @@
busy_retry,
requires_gil_enabled,
)
+from test.support.import_helper import import_module
from test.support.script_helper import make_script
from test.support.socket_helper import find_unused_port
@@ -150,6 +151,48 @@ def foo():
else:
self.fail("Main thread stack trace not found in result")
+ @skip_if_not_supported
+ @unittest.skipIf(
+ sys.platform == "linux" and not PROCESS_VM_READV_SUPPORTED,
+ "Test only runs on Linux with process_vm_readv support",
+ )
+ def test_self_trace_after_ctypes_import(self):
+ """Test that RemoteUnwinder works on the same process after _ctypes import.
+
+ When _ctypes is imported, it may call dlopen on the libpython shared
+ library, creating a duplicate mapping in the process address space.
+ The remote debugging code must skip these uninitialized duplicate
+ mappings and find the real PyRuntime. See gh-144563.
+ """
+
+ # Skip the test if the _ctypes module is missing.
+ import_module("_ctypes")
+
+ # Run the test in a subprocess to avoid side effects
+ script = textwrap.dedent("""\
+ import os
+ import _remote_debugging
+
+ # Should work before _ctypes import
+ unwinder = _remote_debugging.RemoteUnwinder(os.getpid())
+
+ import _ctypes
+
+ # Should still work after _ctypes import (gh-144563)
+ unwinder = _remote_debugging.RemoteUnwinder(os.getpid())
+ """)
+
+ result = subprocess.run(
+ [sys.executable, "-c", script],
+ capture_output=True,
+ text=True,
+ timeout=SHORT_TIMEOUT,
+ )
+ self.assertEqual(
+ result.returncode, 0,
+ f"stdout: {result.stdout}\nstderr: {result.stderr}"
+ )
+
@skip_if_not_supported
@unittest.skipIf(
sys.platform == "linux" and not PROCESS_VM_READV_SUPPORTED,
diff --git a/Lib/test/test_free_threading/test_code.py b/Lib/test/test_free_threading/test_code.py
index a5136a3ba4e..2fc5eea3773 100644
--- a/Lib/test/test_free_threading/test_code.py
+++ b/Lib/test/test_free_threading/test_code.py
@@ -1,9 +1,41 @@
import unittest
+try:
+ import ctypes
+except ImportError:
+ ctypes = None
+
from threading import Thread
from unittest import TestCase
from test.support import threading_helper
+from test.support.threading_helper import run_concurrently
+
+if ctypes is not None:
+ capi = ctypes.pythonapi
+
+ freefunc = ctypes.CFUNCTYPE(None, ctypes.c_voidp)
+
+ RequestCodeExtraIndex = capi.PyUnstable_Eval_RequestCodeExtraIndex
+ RequestCodeExtraIndex.argtypes = (freefunc,)
+ RequestCodeExtraIndex.restype = ctypes.c_ssize_t
+
+ SetExtra = capi.PyUnstable_Code_SetExtra
+ SetExtra.argtypes = (ctypes.py_object, ctypes.c_ssize_t, ctypes.c_voidp)
+ SetExtra.restype = ctypes.c_int
+
+ GetExtra = capi.PyUnstable_Code_GetExtra
+ GetExtra.argtypes = (
+ ctypes.py_object,
+ ctypes.c_ssize_t,
+ ctypes.POINTER(ctypes.c_voidp),
+ )
+ GetExtra.restype = ctypes.c_int
+
+# Note: each call to RequestCodeExtraIndex permanently allocates a slot
+# (the counter is monotonically increasing), up to MAX_CO_EXTRA_USERS (255).
+NTHREADS = 20
+
@threading_helper.requires_working_threading()
class TestCode(TestCase):
@@ -25,6 +57,83 @@ def run_in_thread():
for thread in threads:
thread.join()
+ @unittest.skipUnless(ctypes, "ctypes is required")
+ def test_request_code_extra_index_concurrent(self):
+ """Test concurrent calls to RequestCodeExtraIndex"""
+ results = []
+
+ def worker():
+ idx = RequestCodeExtraIndex(freefunc(0))
+ self.assertGreaterEqual(idx, 0)
+ results.append(idx)
+
+ run_concurrently(worker_func=worker, nthreads=NTHREADS)
+
+ # Every thread must get a unique index.
+ self.assertEqual(len(results), NTHREADS)
+ self.assertEqual(len(set(results)), NTHREADS)
+
+ @unittest.skipUnless(ctypes, "ctypes is required")
+ def test_code_extra_all_ops_concurrent(self):
+ """Test concurrent RequestCodeExtraIndex + SetExtra + GetExtra"""
+ LOOP = 100
+
+ def f():
+ pass
+
+ code = f.__code__
+
+ def worker():
+ idx = RequestCodeExtraIndex(freefunc(0))
+ self.assertGreaterEqual(idx, 0)
+
+ for i in range(LOOP):
+ ret = SetExtra(code, idx, ctypes.c_voidp(i + 1))
+ self.assertEqual(ret, 0)
+
+ for _ in range(LOOP):
+ extra = ctypes.c_voidp()
+ ret = GetExtra(code, idx, extra)
+ self.assertEqual(ret, 0)
+ # The slot was set by this thread, so the value must
+ # be the last one written.
+ self.assertEqual(extra.value, LOOP)
+
+ run_concurrently(worker_func=worker, nthreads=NTHREADS)
+
+ @unittest.skipUnless(ctypes, "ctypes is required")
+ def test_code_extra_set_get_concurrent(self):
+ """Test concurrent SetExtra + GetExtra on a shared index"""
+ LOOP = 100
+
+ def f():
+ pass
+
+ code = f.__code__
+
+ idx = RequestCodeExtraIndex(freefunc(0))
+ self.assertGreaterEqual(idx, 0)
+
+ def worker():
+ for i in range(LOOP):
+ ret = SetExtra(code, idx, ctypes.c_voidp(i + 1))
+ self.assertEqual(ret, 0)
+
+ for _ in range(LOOP):
+ extra = ctypes.c_voidp()
+ ret = GetExtra(code, idx, extra)
+ self.assertEqual(ret, 0)
+ # Value is set by any writer thread.
+ self.assertTrue(1 <= extra.value <= LOOP)
+
+ run_concurrently(worker_func=worker, nthreads=NTHREADS)
+
+ # Every thread's last write is LOOP, so the final value must be LOOP.
+ extra = ctypes.c_voidp()
+ ret = GetExtra(code, idx, extra)
+ self.assertEqual(ret, 0)
+ self.assertEqual(extra.value, LOOP)
+
if __name__ == "__main__":
unittest.main()
diff --git a/Lib/test/test_free_threading/test_collections.py b/Lib/test/test_free_threading/test_collections.py
new file mode 100644
index 00000000000..3a413ccf396
--- /dev/null
+++ b/Lib/test/test_free_threading/test_collections.py
@@ -0,0 +1,29 @@
+import unittest
+from collections import deque
+from copy import copy
+from test.support import threading_helper
+
+threading_helper.requires_working_threading(module=True)
+
+
+class TestDeque(unittest.TestCase):
+ def test_copy_race(self):
+ # gh-144809: Test that deque copy is thread safe. It previously
+ # could raise a "deque mutated during iteration" error.
+ d = deque(range(100))
+
+ def mutate():
+ for i in range(1000):
+ d.append(i)
+ if len(d) > 200:
+ d.popleft()
+
+ def copy_loop():
+ for _ in range(1000):
+ copy(d)
+
+ threading_helper.run_concurrently([mutate, copy_loop])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/Lib/test/test_free_threading/test_frame.py b/Lib/test/test_free_threading/test_frame.py
new file mode 100644
index 00000000000..bea49df557a
--- /dev/null
+++ b/Lib/test/test_free_threading/test_frame.py
@@ -0,0 +1,151 @@
+import functools
+import sys
+import threading
+import unittest
+
+from test.support import threading_helper
+
+threading_helper.requires_working_threading(module=True)
+
+
+def run_with_frame(funcs, runner=None, iters=10):
+ """Run funcs with a frame from another thread that is currently executing.
+
+ Args:
+ funcs: A function or list of functions that take a frame argument
+ runner: Optional function to run in the executor thread. If provided,
+ it will be called and should return eventually. The frame
+ passed to funcs will be the runner's frame.
+ iters: Number of iterations each func should run
+ """
+ if not isinstance(funcs, list):
+ funcs = [funcs]
+
+ frame_var = None
+ e = threading.Event()
+ b = threading.Barrier(len(funcs) + 1)
+
+ if runner is None:
+ def runner():
+ j = 0
+ for i in range(100):
+ j += i
+
+ def executor():
+ nonlocal frame_var
+ frame_var = sys._getframe()
+ e.set()
+ b.wait()
+ runner()
+
+ def func_wrapper(func):
+ e.wait()
+ frame = frame_var
+ b.wait()
+ for _ in range(iters):
+ func(frame)
+
+ test_funcs = [functools.partial(func_wrapper, f) for f in funcs]
+ threading_helper.run_concurrently([executor] + test_funcs)
+
+
+class TestFrameRaces(unittest.TestCase):
+ def test_concurrent_f_lasti(self):
+ run_with_frame(lambda frame: frame.f_lasti)
+
+ def test_concurrent_f_lineno(self):
+ run_with_frame(lambda frame: frame.f_lineno)
+
+ def test_concurrent_f_code(self):
+ run_with_frame(lambda frame: frame.f_code)
+
+ def test_concurrent_f_back(self):
+ run_with_frame(lambda frame: frame.f_back)
+
+ def test_concurrent_f_globals(self):
+ run_with_frame(lambda frame: frame.f_globals)
+
+ def test_concurrent_f_builtins(self):
+ run_with_frame(lambda frame: frame.f_builtins)
+
+ def test_concurrent_f_locals(self):
+ run_with_frame(lambda frame: frame.f_locals)
+
+ def test_concurrent_f_trace_read(self):
+ run_with_frame(lambda frame: frame.f_trace)
+
+ def test_concurrent_f_trace_opcodes_read(self):
+ run_with_frame(lambda frame: frame.f_trace_opcodes)
+
+ def test_concurrent_repr(self):
+ run_with_frame(lambda frame: repr(frame))
+
+ def test_concurrent_f_trace_write(self):
+ def trace_func(frame, event, arg):
+ return trace_func
+
+ def writer(frame):
+ frame.f_trace = trace_func
+ frame.f_trace = None
+
+ run_with_frame(writer)
+
+ def test_concurrent_f_trace_read_write(self):
+ # Test concurrent reads and writes of f_trace on a live frame.
+ def trace_func(frame, event, arg):
+ return trace_func
+
+ def reader(frame):
+ _ = frame.f_trace
+
+ def writer(frame):
+ frame.f_trace = trace_func
+ frame.f_trace = None
+
+ run_with_frame([reader, writer, reader, writer])
+
+ def test_concurrent_f_trace_opcodes_write(self):
+ def writer(frame):
+ frame.f_trace_opcodes = True
+ frame.f_trace_opcodes = False
+
+ run_with_frame(writer)
+
+ def test_concurrent_f_trace_opcodes_read_write(self):
+ # Test concurrent reads and writes of f_trace_opcodes on a live frame.
+ def reader(frame):
+ _ = frame.f_trace_opcodes
+
+ def writer(frame):
+ frame.f_trace_opcodes = True
+ frame.f_trace_opcodes = False
+
+ run_with_frame([reader, writer, reader, writer])
+
+ def test_concurrent_frame_clear(self):
+ # Test race between frame.clear() and attribute reads.
+ def create_frame():
+ x = 1
+ y = 2
+ return sys._getframe()
+
+ frame = create_frame()
+
+ def reader():
+ for _ in range(10):
+ try:
+ _ = frame.f_locals
+ _ = frame.f_code
+ _ = frame.f_lineno
+ except ValueError:
+ # Frame may be cleared
+ pass
+
+ def clearer():
+ frame.clear()
+
+ threading_helper.run_concurrently([reader, reader, clearer])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/Lib/test/test_free_threading/test_io.py b/Lib/test/test_free_threading/test_io.py
index 4e903928b49..6c98e500658 100644
--- a/Lib/test/test_free_threading/test_io.py
+++ b/Lib/test/test_free_threading/test_io.py
@@ -1,10 +1,15 @@
+import codecs
+import io
import threading
from unittest import TestCase
from test.support import threading_helper
+from test.support.threading_helper import run_concurrently
from random import randint
from io import BytesIO
from sys import getsizeof
+threading_helper.requires_working_threading(module=True)
+
class TestBytesIO(TestCase):
# Test pretty much everything that can break under free-threading.
@@ -107,3 +112,54 @@ def sizeof(barrier, b, *ignore):
self.check([truncate] + [sizeof] * 10, BytesIO(b'0\n'*204800))
# no tests for seek or tell because they don't break anything
+
+
+class IncrementalNewlineDecoderTest(TestCase):
+ def make_decoder(self):
+ utf8_decoder = codecs.getincrementaldecoder('utf-8')()
+ return io.IncrementalNewlineDecoder(utf8_decoder, translate=True)
+
+ def test_concurrent_reset(self):
+ decoder = self.make_decoder()
+
+ def worker():
+ for _ in range(100):
+ decoder.reset()
+
+ run_concurrently(worker_func=worker, nthreads=2)
+
+ def test_concurrent_decode(self):
+ decoder = self.make_decoder()
+
+ def worker():
+ for _ in range(100):
+ decoder.decode(b"line\r\n", final=False)
+
+ run_concurrently(worker_func=worker, nthreads=2)
+
+ def test_concurrent_getstate_setstate(self):
+ decoder = self.make_decoder()
+ state = decoder.getstate()
+
+ def getstate_worker():
+ for _ in range(100):
+ decoder.getstate()
+
+ def setstate_worker():
+ for _ in range(100):
+ decoder.setstate(state)
+
+ run_concurrently([getstate_worker] * 2 + [setstate_worker] * 2)
+
+ def test_concurrent_decode_and_reset(self):
+ decoder = self.make_decoder()
+
+ def decode_worker():
+ for _ in range(100):
+ decoder.decode(b"line\r\n", final=False)
+
+ def reset_worker():
+ for _ in range(100):
+ decoder.reset()
+
+ run_concurrently([decode_worker] * 2 + [reset_worker] * 2)
diff --git a/Lib/test/test_free_threading/test_str.py b/Lib/test/test_free_threading/test_str.py
index 72044e979b0..9a1ce3620ac 100644
--- a/Lib/test/test_free_threading/test_str.py
+++ b/Lib/test/test_free_threading/test_str.py
@@ -69,6 +69,22 @@ def reader_func():
for reader in readers:
reader.join()
+ def test_maketrans_dict_concurrent_modification(self):
+ for _ in range(5):
+ d = {2000: 'a'}
+
+ def work(dct):
+ for i in range(100):
+ str.maketrans(dct)
+ dct[2000 + i] = chr(i % 16)
+ dct.pop(2000 + i, None)
+
+ threading_helper.run_concurrently(
+ work,
+ nthreads=5,
+ args=(d,),
+ )
+
if __name__ == "__main__":
unittest.main()
diff --git a/Lib/test/test_functools.py b/Lib/test/test_functools.py
index 9d0cebd62ba..16adb8dad7d 100644
--- a/Lib/test/test_functools.py
+++ b/Lib/test/test_functools.py
@@ -514,6 +514,58 @@ def test_partial_genericalias(self):
self.assertEqual(alias.__args__, (int,))
self.assertEqual(alias.__parameters__, ())
+ # GH-144475: Tests that the partial object does not change until repr finishes
+ def test_repr_safety_against_reentrant_mutation(self):
+ g_partial = None
+
+ class Function:
+ def __init__(self, name):
+ self.name = name
+
+ def __call__(self):
+ return None
+
+ def __repr__(self):
+ return f"Function({self.name})"
+
+ class EvilObject:
+ def __init__(self):
+ self.triggered = False
+
+ def __repr__(self):
+ if not self.triggered and g_partial is not None:
+ self.triggered = True
+ new_args_tuple = (None,)
+ new_keywords_dict = {"keyword": None}
+ new_tuple_state = (Function("new_function"), new_args_tuple, new_keywords_dict, None)
+ g_partial.__setstate__(new_tuple_state)
+ gc.collect()
+ return f"EvilObject"
+
+ trigger = EvilObject()
+ func = Function("old_function")
+
+ g_partial = functools.partial(func, None, trigger=trigger)
+ self.assertEqual(repr(g_partial),"functools.partial(Function(old_function), None, trigger=EvilObject)")
+
+ trigger.triggered = False
+ g_partial = functools.partial(func, trigger, arg=None)
+ self.assertEqual(repr(g_partial),"functools.partial(Function(old_function), EvilObject, arg=None)")
+
+
+ trigger.triggered = False
+ g_partial = functools.partial(func, trigger, None)
+ self.assertEqual(repr(g_partial),"functools.partial(Function(old_function), EvilObject, None)")
+
+ trigger.triggered = False
+ g_partial = functools.partial(func, trigger=trigger, arg=None)
+ self.assertEqual(repr(g_partial),"functools.partial(Function(old_function), trigger=EvilObject, arg=None)")
+
+ trigger.triggered = False
+ g_partial = functools.partial(func, trigger, None, None, None, None, arg=None)
+ self.assertEqual(repr(g_partial),"functools.partial(Function(old_function), EvilObject, None, None, None, None, arg=None)")
+
+
@unittest.skipUnless(c_functools, 'requires the C _functools module')
class TestPartialC(TestPartial, unittest.TestCase):
diff --git a/Lib/test/test_hashlib.py b/Lib/test/test_hashlib.py
index 14a79a1c698..c7d7b801ac7 100644
--- a/Lib/test/test_hashlib.py
+++ b/Lib/test/test_hashlib.py
@@ -127,8 +127,11 @@ def __init__(self, *args, **kwargs):
algorithms.add(algorithm.lower())
_blake2 = self._conditional_import_module('_blake2')
+ blake2_hashes = {'blake2b', 'blake2s'}
if _blake2:
- algorithms.update({'blake2b', 'blake2s'})
+ algorithms.update(blake2_hashes)
+ else:
+ algorithms.difference_update(blake2_hashes)
self.constructors_to_test = {}
for algorithm in algorithms:
@@ -220,7 +223,12 @@ def test_algorithms_available(self):
# all available algorithms must be loadable, bpo-47101
self.assertNotIn("undefined", hashlib.algorithms_available)
for name in hashlib.algorithms_available:
- digest = hashlib.new(name, usedforsecurity=False)
+ with self.subTest(name):
+ try:
+ _ = hashlib.new(name, usedforsecurity=False)
+ except ValueError as exc:
+ self.skip_if_blake2_not_builtin(name, exc)
+ raise
def test_usedforsecurity_true(self):
hashlib.new("sha256", usedforsecurity=True)
@@ -443,6 +451,7 @@ def test_sha3_256_update_over_4gb(self):
self.assertEqual(h.hexdigest(), "e2d4535e3b613135c14f2fe4e026d7ad8d569db44901740beffa30d430acb038")
@requires_resource('cpu')
+ @requires_blake2
def test_blake2_update_over_4gb(self):
# blake2s or blake2b doesn't matter based on how our C code is structured, this tests the
# common loop macro logic.
@@ -733,6 +742,12 @@ def test_case_sha512_3(self):
"e718483d0ce769644e2e42c7bc15b4638e1f98b13b2044285632a803afa973eb"+
"de0ff244877ea60a4cb0432ce577c31beb009c5c2c49aa2e4eadb217ad8cc09b")
+ def skip_if_blake2_not_builtin(self, name, skip_reason):
+ # blake2 builtins may be absent if python built with
+ # a subset of --with-builtin-hashlib-hashes or none.
+ if "blake2" in name and "blake2" not in builtin_hashes:
+ self.skipTest(skip_reason)
+
def check_blake2(self, constructor, salt_size, person_size, key_size,
digest_size, max_offset):
self.assertEqual(constructor.SALT_SIZE, salt_size)
diff --git a/Lib/test/test_import/__init__.py b/Lib/test/test_import/__init__.py
index 95121debbbf..2e1c6d72f54 100644
--- a/Lib/test/test_import/__init__.py
+++ b/Lib/test/test_import/__init__.py
@@ -43,6 +43,7 @@
Py_GIL_DISABLED,
no_rerun,
force_not_colorized_test_class,
+ catch_unraisable_exception
)
from test.support.import_helper import (
forget, make_legacy_pyc, unlink, unload, ready_to_import,
@@ -2540,6 +2541,32 @@ def test_disallowed_reimport(self):
excsnap = _interpreters.run_string(interpid, script)
self.assertIsNot(excsnap, None)
+ @requires_subinterpreters
+ def test_pyinit_function_raises_exception(self):
+ # gh-144601: PyInit functions that raised exceptions would cause a
+ # crash when imported from a subinterpreter.
+ import _testsinglephase
+ filename = _testsinglephase.__file__
+ script = f"""if True:
+ from test.test_import import import_extension_from_file
+
+ import_extension_from_file('_testsinglephase_raise_exception', {filename!r})"""
+
+ interp = _interpreters.create()
+ try:
+ with catch_unraisable_exception() as cm:
+ exception = _interpreters.run_string(interp, script)
+ unraisable = cm.unraisable
+ finally:
+ _interpreters.destroy(interp)
+
+ self.assertIsNotNone(exception)
+ self.assertIsNotNone(exception.type.__name__, "ImportError")
+ self.assertIsNotNone(exception.msg, "failed to import from subinterpreter due to exception")
+ self.assertIsNotNone(unraisable)
+ self.assertIs(unraisable.exc_type, RuntimeError)
+ self.assertEqual(str(unraisable.exc_value), "evil")
+
class TestSinglePhaseSnapshot(ModuleSnapshot):
"""A representation of a single-phase init module for testing.
diff --git a/Lib/test/test_importlib/test_threaded_import.py b/Lib/test/test_importlib/test_threaded_import.py
index f78dc399720..8b793ebf29b 100644
--- a/Lib/test/test_importlib/test_threaded_import.py
+++ b/Lib/test/test_importlib/test_threaded_import.py
@@ -259,6 +259,71 @@ def test_multiprocessing_pool_circular_import(self, size):
'partial', 'pool_in_threads.py')
script_helper.assert_python_ok(fn)
+ def test_import_failure_race_condition(self):
+ # Regression test for race condition where a thread could receive
+ # a partially-initialized module when another thread's import fails.
+ # The race occurs when:
+ # 1. Thread 1 starts importing, adds module to sys.modules
+ # 2. Thread 2 sees the module in sys.modules
+ # 3. Thread 1's import fails, removes module from sys.modules
+ # 4. Thread 2 should NOT return the stale module reference
+ os.mkdir(TESTFN)
+ self.addCleanup(shutil.rmtree, TESTFN)
+ sys.path.insert(0, TESTFN)
+ self.addCleanup(sys.path.remove, TESTFN)
+
+ # Create a module that partially initializes then fails
+ modname = 'failing_import_module'
+ with open(os.path.join(TESTFN, modname + '.py'), 'w') as f:
+ f.write('''
+import time
+PARTIAL_ATTR = 'initialized'
+time.sleep(0.05) # Widen race window
+raise RuntimeError("Intentional import failure")
+''')
+ self.addCleanup(forget, modname)
+ importlib.invalidate_caches()
+
+ errors = []
+ results = []
+
+ def do_import(delay=0):
+ time.sleep(delay)
+ try:
+ mod = __import__(modname)
+ # If we got a module, verify it's in sys.modules
+ if modname not in sys.modules:
+ errors.append(
+ f"Got module {mod!r} but {modname!r} not in sys.modules"
+ )
+ elif sys.modules[modname] is not mod:
+ errors.append(
+ f"Got different module than sys.modules[{modname!r}]"
+ )
+ else:
+ results.append(('success', mod))
+ except RuntimeError:
+ results.append(('RuntimeError',))
+ except Exception as e:
+ errors.append(f"Unexpected exception: {e}")
+
+ # Run multiple iterations to increase chance of hitting the race
+ for _ in range(10):
+ errors.clear()
+ results.clear()
+ if modname in sys.modules:
+ del sys.modules[modname]
+
+ t1 = threading.Thread(target=do_import, args=(0,))
+ t2 = threading.Thread(target=do_import, args=(0.01,))
+ t1.start()
+ t2.start()
+ t1.join()
+ t2.join()
+
+ # Neither thread should have errors about stale modules
+ self.assertEqual(errors, [], f"Race condition detected: {errors}")
+
def setUpModule():
thread_info = threading_helper.threading_setup()
diff --git a/Lib/test/test_importlib/util.py b/Lib/test/test_importlib/util.py
index edbe78545a2..bd64b03b75f 100644
--- a/Lib/test/test_importlib/util.py
+++ b/Lib/test/test_importlib/util.py
@@ -15,7 +15,7 @@
import tempfile
import types
-_testsinglephase = import_helper.import_module("_testsinglephase")
+import_helper.import_module("_testmultiphase")
BUILTINS = types.SimpleNamespace()
diff --git a/Lib/test/test_inspect/test_inspect.py b/Lib/test/test_inspect/test_inspect.py
index 35e31cd5ed1..28acb2a45a3 100644
--- a/Lib/test/test_inspect/test_inspect.py
+++ b/Lib/test/test_inspect/test_inspect.py
@@ -6203,8 +6203,7 @@ def test_operator_module_has_signatures(self):
def test_os_module_has_signatures(self):
unsupported_signature = {'chmod', 'utime'}
unsupported_signature |= {name for name in
- ['get_terminal_size', 'link', 'posix_spawn', 'posix_spawnp',
- 'register_at_fork', 'startfile']
+ ['get_terminal_size', 'link', 'register_at_fork', 'startfile']
if hasattr(os, name)}
self._test_module_has_signatures(os, unsupported_signature=unsupported_signature)
diff --git a/Lib/test/test_interpreters/test_channels.py b/Lib/test/test_interpreters/test_channels.py
index 52827357078..5437792b5a7 100644
--- a/Lib/test/test_interpreters/test_channels.py
+++ b/Lib/test/test_interpreters/test_channels.py
@@ -47,6 +47,12 @@ def test_list_all(self):
after = set(channels.list_all())
self.assertEqual(after, created)
+ def test_list_all_closed(self):
+ created = [channels.create() for _ in range(3)]
+ rch, sch = created.pop(1)
+ rch.close()
+ self.assertEqual(set(channels.list_all()), set(created))
+
def test_shareable(self):
interp = interpreters.create()
rch, sch = channels.create()
diff --git a/Lib/test/test_itertools.py b/Lib/test/test_itertools.py
index 61bea9dba07..dc64288085f 100644
--- a/Lib/test/test_itertools.py
+++ b/Lib/test/test_itertools.py
@@ -733,6 +733,27 @@ def keyfunc(obj):
keyfunc.skip = 1
self.assertRaises(ExpectedError, gulp, [None, None], keyfunc)
+ def test_groupby_reentrant_eq_does_not_crash(self):
+ # regression test for gh-143543
+ class Key:
+ def __init__(self, do_advance):
+ self.do_advance = do_advance
+
+ def __eq__(self, other):
+ if self.do_advance:
+ self.do_advance = False
+ next(g)
+ return NotImplemented
+ return False
+
+ def keys():
+ yield Key(True)
+ yield Key(False)
+
+ g = itertools.groupby([None, None], keys().send)
+ next(g)
+ next(g) # must pass with address sanitizer
+
def test_filter(self):
self.assertEqual(list(filter(isEven, range(6))), [0,2,4])
self.assertEqual(list(filter(None, [0,1,0,2,0])), [1,2])
diff --git a/Lib/test/test_launcher.py b/Lib/test/test_launcher.py
index caa1603c78e..c522bc1c2c0 100644
--- a/Lib/test/test_launcher.py
+++ b/Lib/test/test_launcher.py
@@ -227,6 +227,8 @@ def run_py(self, args, env=None, allow_fail=False, expect_returncode=0, argv=Non
"PYLAUNCHER_LIMIT_TO_COMPANY": "",
**{k.upper(): v for k, v in (env or {}).items()},
}
+ if ini_dir := getattr(self, '_ini_dir', None):
+ env.setdefault("_PYLAUNCHER_INIDIR", ini_dir)
if not argv:
argv = [self.py_exe, *args]
with subprocess.Popen(
@@ -262,11 +264,14 @@ def run_py(self, args, env=None, allow_fail=False, expect_returncode=0, argv=Non
return data
def py_ini(self, content):
- local_appdata = os.environ.get("LOCALAPPDATA")
- if not local_appdata:
- raise unittest.SkipTest("LOCALAPPDATA environment variable is "
- "missing or empty")
- return PreservePyIni(Path(local_appdata) / "py.ini", content)
+ ini_dir = getattr(self, '_ini_dir', None)
+ if not ini_dir:
+ local_appdata = os.environ.get("LOCALAPPDATA")
+ if not local_appdata:
+ raise unittest.SkipTest("LOCALAPPDATA environment variable is "
+ "missing or empty")
+ ini_dir = local_appdata
+ return PreservePyIni(Path(ini_dir) / "py.ini", content)
@contextlib.contextmanager
def script(self, content, encoding="utf-8"):
@@ -302,6 +307,8 @@ def setUpClass(cls):
p = subprocess.check_output("reg query HKCU\\Software\\Python /s")
#print(p.decode('mbcs'))
+ cls._ini_dir = tempfile.mkdtemp()
+ cls.addClassCleanup(shutil.rmtree, cls._ini_dir, ignore_errors=True)
@classmethod
def tearDownClass(cls):
diff --git a/Lib/test/test_listcomps.py b/Lib/test/test_listcomps.py
index ad7f62fbf78..442075b47c8 100644
--- a/Lib/test/test_listcomps.py
+++ b/Lib/test/test_listcomps.py
@@ -180,6 +180,18 @@ def test_references___class___defined(self):
code, outputs={"res": [2]}, scopes=["module", "function"])
self._check_in_scopes(code, raises=NameError, scopes=["class"])
+ def test_references___classdict__(self):
+ code = """
+ class i: [__classdict__ for x in y]
+ """
+ self._check_in_scopes(code, raises=NameError)
+
+ def test_references___conditional_annotations__(self):
+ code = """
+ class i: [__conditional_annotations__ for x in y]
+ """
+ self._check_in_scopes(code, raises=NameError)
+
def test_references___class___enclosing(self):
code = """
__class__ = 2
diff --git a/Lib/test/test_os.py b/Lib/test/test_os.py
index 7a28e7b4598..555c85f4857 100644
--- a/Lib/test/test_os.py
+++ b/Lib/test/test_os.py
@@ -2607,6 +2607,16 @@ def test_fpathconf_bad_fd(self):
self.check(os.pathconf, "PC_NAME_MAX")
self.check(os.fpathconf, "PC_NAME_MAX")
+ @unittest.skipUnless(hasattr(os, 'pathconf'), 'test needs os.pathconf()')
+ @unittest.skipIf(
+ support.linked_to_musl(),
+ 'musl fpathconf ignores the file descriptor and returns a constant',
+ )
+ def test_pathconf_negative_fd_uses_fd_semantics(self):
+ with self.assertRaises(OSError) as ctx:
+ os.pathconf(-1, 1)
+ self.assertEqual(ctx.exception.errno, errno.EBADF)
+
@unittest.skipUnless(hasattr(os, 'ftruncate'), 'test needs os.ftruncate()')
def test_ftruncate(self):
self.check(os.truncate, 0)
diff --git a/Lib/test/test_perf_profiler.py b/Lib/test/test_perf_profiler.py
index 1e1b0522787..7824897dd29 100644
--- a/Lib/test/test_perf_profiler.py
+++ b/Lib/test/test_perf_profiler.py
@@ -170,6 +170,47 @@ def baz():
self.assertNotIn(f"py::bar:{script}", child_perf_file_contents)
self.assertNotIn(f"py::baz:{script}", child_perf_file_contents)
+ @unittest.skipIf(support.check_bolt_optimized(), "fails on BOLT instrumented binaries")
+ def test_trampoline_works_after_fork_with_many_code_objects(self):
+ code = """if 1:
+ import gc, os, sys, signal
+
+ # Create many code objects so trampoline_refcount > 1
+ for i in range(50):
+ exec(compile(f"def _dummy_{i}(): pass", f"<test{i}>", "exec"))
+
+ pid = os.fork()
+ if pid == 0:
+ # Child: create and destroy new code objects,
+ # then collect garbage. If the old code watcher
+ # survived the fork, the double-decrement of
+ # trampoline_refcount will cause a SIGSEGV.
+ for i in range(50):
+ exec(compile(f"def _child_{i}(): pass", f"<child{i}>", "exec"))
+ gc.collect()
+ os._exit(0)
+ else:
+ _, status = os.waitpid(pid, 0)
+ if os.WIFSIGNALED(status):
+ print(f"FAIL: child killed by signal {os.WTERMSIG(status)}", file=sys.stderr)
+ sys.exit(1)
+ sys.exit(os.WEXITSTATUS(status))
+ """
+ with temp_dir() as script_dir:
+ script = make_script(script_dir, "perftest", code)
+ env = {**os.environ, "PYTHON_JIT": "0"}
+ with subprocess.Popen(
+ [sys.executable, "-Xperf", script],
+ text=True,
+ stderr=subprocess.PIPE,
+ stdout=subprocess.PIPE,
+ env=env,
+ ) as process:
+ stdout, stderr = process.communicate()
+
+ self.assertEqual(process.returncode, 0, stderr)
+ self.assertEqual(stderr, "")
+
@unittest.skipIf(support.check_bolt_optimized(), "fails on BOLT instrumented binaries")
def test_sys_api(self):
code = """if 1:
diff --git a/Lib/test/test_posix.py b/Lib/test/test_posix.py
index f51cdd26df7..a895d57d1ff 100644
--- a/Lib/test/test_posix.py
+++ b/Lib/test/test_posix.py
@@ -1933,6 +1933,11 @@ def test_setpgroup(self):
)
support.wait_process(pid, exitcode=0)
+ def test_setpgroup_allow_none(self):
+ path, args = self.NOOP_PROGRAM[0], self.NOOP_PROGRAM
+ pid = self.spawn_func(path, args, os.environ, setpgroup=None)
+ support.wait_process(pid, exitcode=0)
+
def test_setpgroup_wrong_type(self):
with self.assertRaises(TypeError):
self.spawn_func(sys.executable,
@@ -2033,6 +2038,20 @@ def test_setsigdef_wrong_type(self):
[sys.executable, "-c", "pass"],
os.environ, setsigdef=[signal.NSIG, signal.NSIG+1])
+ def test_scheduler_allow_none(self):
+ path, args = self.NOOP_PROGRAM[0], self.NOOP_PROGRAM
+ pid = self.spawn_func(path, args, os.environ, scheduler=None)
+ support.wait_process(pid, exitcode=0)
+
+ @support.subTests("scheduler", [object(), 1, [1, 2]])
+ def test_scheduler_wrong_type(self, scheduler):
+ path, args = self.NOOP_PROGRAM[0], self.NOOP_PROGRAM
+ with self.assertRaisesRegex(
+ TypeError,
+ "scheduler must be a tuple or None",
+ ):
+ self.spawn_func(path, args, os.environ, scheduler=scheduler)
+
@requires_sched
@unittest.skipIf(sys.platform.startswith(('freebsd', 'netbsd')),
"bpo-34685: test can fail on BSD")
diff --git a/Lib/test/test_py_compile.py b/Lib/test/test_py_compile.py
index 64387296e84..749a877d013 100644
--- a/Lib/test/test_py_compile.py
+++ b/Lib/test/test_py_compile.py
@@ -207,6 +207,14 @@ def test_quiet(self):
with self.assertRaises(py_compile.PyCompileError):
py_compile.compile(bad_coding, doraise=True, quiet=1)
+ def test_utf7_decoded_cr_compiles(self):
+ with open(self.source_path, 'wb') as file:
+ file.write(b"#coding=U7+AA0''\n")
+
+ pyc_path = py_compile.compile(self.source_path, self.pyc_path, doraise=True)
+ self.assertEqual(pyc_path, self.pyc_path)
+ self.assertTrue(os.path.exists(self.pyc_path))
+
class PyCompileTestsWithSourceEpoch(PyCompileTestsBase,
unittest.TestCase,
diff --git a/Lib/test/test_pyexpat.py b/Lib/test/test_pyexpat.py
index daeaa38a3c5..3e9015910e0 100644
--- a/Lib/test/test_pyexpat.py
+++ b/Lib/test/test_pyexpat.py
@@ -999,7 +999,9 @@ def test_set_maximum_amplification__fail_for_subparser(self):
self.assert_root_parser_failure(setter, 123.45)
-@unittest.skipIf(expat.version_info < (2, 7, 2), "requires Expat >= 2.7.2")
+@unittest.skipIf(not hasattr(expat.XMLParserType,
+ "SetAllocTrackerMaximumAmplification"),
+ "requires Python compiled with Expat >= 2.7.2")
class MemoryProtectionTest(AttackProtectionTestBase, unittest.TestCase):
# NOTE: with the default Expat configuration, the billion laughs protection
diff --git a/Lib/test/test_repl.py b/Lib/test/test_repl.py
index b55a5180c67..855dca2258d 100644
--- a/Lib/test/test_repl.py
+++ b/Lib/test/test_repl.py
@@ -143,6 +143,22 @@ def test_multiline_string_parsing(self):
output = kill_python(p)
self.assertEqual(p.returncode, 0)
+ @cpython_only
+ def test_lexer_buffer_realloc_with_null_start(self):
+ # gh-144759: NULL pointer arithmetic in the lexer when start and
+ # multi_line_start are NULL (uninitialized in tok_mode_stack[0])
+ # and the lexer buffer is reallocated while parsing long input.
+ long_value = "a" * 2000
+ user_input = dedent(f"""\
+ x = f'{{{long_value!r}}}'
+ print(x)
+ """)
+ p = spawn_repl()
+ p.stdin.write(user_input)
+ output = kill_python(p)
+ self.assertEqual(p.returncode, 0)
+ self.assertIn(long_value, output)
+
def test_close_stdin(self):
user_input = dedent('''
import os
diff --git a/Lib/test/test_socket.py b/Lib/test/test_socket.py
index e66160c5236..249bfeaa14c 100644
--- a/Lib/test/test_socket.py
+++ b/Lib/test/test_socket.py
@@ -561,8 +561,8 @@ def clientTearDown(self):
@unittest.skipIf(WSL, 'VSOCK does not work on Microsoft WSL')
@unittest.skipUnless(HAVE_SOCKET_VSOCK,
'VSOCK sockets required for this test.')
-@unittest.skipUnless(get_cid() != 2, # VMADDR_CID_HOST
- "This test can only be run on a virtual guest.")
+@unittest.skipIf(get_cid() == getattr(socket, 'VMADDR_CID_HOST', 2),
+ "This test can only be run on a virtual guest.")
class ThreadedVSOCKSocketStreamTest(unittest.TestCase, ThreadableTest):
def __init__(self, methodName='runTest'):
@@ -572,7 +572,16 @@ def __init__(self, methodName='runTest'):
def setUp(self):
self.serv = socket.socket(socket.AF_VSOCK, socket.SOCK_STREAM)
self.addCleanup(self.serv.close)
- self.serv.bind((socket.VMADDR_CID_ANY, VSOCKPORT))
+ cid = get_cid()
+ if cid in (socket.VMADDR_CID_HOST, socket.VMADDR_CID_ANY):
+ cid = socket.VMADDR_CID_LOCAL
+ try:
+ self.serv.bind((cid, VSOCKPORT))
+ except OSError as exc:
+ if exc.errno == errno.EADDRNOTAVAIL:
+ self.skipTest(f"bind() failed with {exc!r}")
+ else:
+ raise
self.serv.listen()
self.serverExplicitReady()
self.serv.settimeout(support.LOOPBACK_TIMEOUT)
@@ -2176,6 +2185,24 @@ def test_addressinfo_enum(self):
source=_socket)
enum._test_simple_enum(CheckedAddressInfo, socket.AddressInfo)
+ @unittest.skipUnless(hasattr(socket.socket, "sendmsg"),"sendmsg not supported")
+ def test_sendmsg_reentrant_ancillary_mutation(self):
+
+ class Mut:
+ def __index__(self):
+ seq.clear()
+ return socket.SCM_RIGHTS
+
+ seq = [
+ (socket.SOL_SOCKET, Mut(), b'xxxx'),
+ (socket.SOL_SOCKET, socket.SCM_RIGHTS, b'xxxx'),
+ ]
+
+ left, right = socket.socketpair()
+ self.addCleanup(left.close)
+ self.addCleanup(right.close)
+ self.assertRaises(OSError, left.sendmsg, [b'x'], seq)
+
@unittest.skipUnless(HAVE_SOCKET_CAN, 'SocketCan required for this test.')
class BasicCANTest(unittest.TestCase):
diff --git a/Lib/test/test_source_encoding.py b/Lib/test/test_source_encoding.py
index 36c8d87182d..5fae8a7c5bf 100644
--- a/Lib/test/test_source_encoding.py
+++ b/Lib/test/test_source_encoding.py
@@ -65,6 +65,23 @@ def test_issue7820(self):
# two bytes in common with the UTF-8 BOM
self.assertRaises(SyntaxError, eval, b'\xef\xbb\x20')
+ def test_truncated_utf8_at_eof(self):
+ # Regression test for https://issues.oss-fuzz.com/issues/451112368
+ # Truncated multi-byte UTF-8 sequences at end of input caused an
+ # out-of-bounds read in Parser/tokenizer/helpers.c:valid_utf8().
+ truncated = [
+ b'\xc2', # 2-byte lead, missing 1 continuation
+ b'\xdf', # 2-byte lead, missing 1 continuation
+ b'\xe0', # 3-byte lead, missing 2 continuations
+ b'\xe0\xa0', # 3-byte lead, missing 1 continuation
+ b'\xf0\x90', # 4-byte lead, missing 2 continuations
+ b'\xf0\x90\x80', # 4-byte lead, missing 1 continuation
+ b'\xf3', # 4-byte lead, missing 3 (the oss-fuzz reproducer)
+ ]
+ for seq in truncated:
+ with self.subTest(seq=seq):
+ self.assertRaises(SyntaxError, compile, seq, '<test>', 'exec')
+
@support.requires_subprocess()
def test_20731(self):
sub = subprocess.Popen([sys.executable,
diff --git a/Lib/test/test_sqlite3/test_dbapi.py b/Lib/test/test_sqlite3/test_dbapi.py
index 1e595bdbd64..7e55785bd4a 100644
--- a/Lib/test/test_sqlite3/test_dbapi.py
+++ b/Lib/test/test_sqlite3/test_dbapi.py
@@ -1387,6 +1387,11 @@ def test_blob_get_slice(self):
def test_blob_get_empty_slice(self):
self.assertEqual(self.blob[5:5], b"")
+ def test_blob_get_empty_slice_oob_indices(self):
+ self.cx.execute("insert into test(b) values (?)", (b"abc",))
+ with self.cx.blobopen("test", "b", 2) as blob:
+ self.assertEqual(blob[5:-5], b"")
+
def test_blob_get_slice_negative_index(self):
self.assertEqual(self.blob[5:-5], self.data[5:-5])
diff --git a/Lib/test/test_ssl.py b/Lib/test/test_ssl.py
index 67a63907293..423d0292b4e 100644
--- a/Lib/test/test_ssl.py
+++ b/Lib/test/test_ssl.py
@@ -50,6 +50,16 @@
IS_OPENSSL_3_0_0 = ssl.OPENSSL_VERSION_INFO >= (3, 0, 0)
PY_SSL_DEFAULT_CIPHERS = sysconfig.get_config_var('PY_SSL_DEFAULT_CIPHERS')
+HAS_KEYLOG = hasattr(ssl.SSLContext, 'keylog_filename')
+requires_keylog = unittest.skipUnless(
+ HAS_KEYLOG, 'test requires OpenSSL 1.1.1 with keylog callback')
+CAN_SET_KEYLOG = HAS_KEYLOG and os.name != "nt"
+requires_keylog_setter = unittest.skipUnless(
+ CAN_SET_KEYLOG,
+ "cannot set 'keylog_filename' on Windows"
+)
+
+
PROTOCOL_TO_TLS_VERSION = {}
for proto, ver in (
("PROTOCOL_SSLv3", "SSLv3"),
@@ -258,26 +268,67 @@ def utc_offset(): #NOTE: ignore issues like #1647654
)
-def test_wrap_socket(sock, *,
- cert_reqs=ssl.CERT_NONE, ca_certs=None,
- ciphers=None, certfile=None, keyfile=None,
- **kwargs):
- if not kwargs.get("server_side"):
- kwargs["server_hostname"] = SIGNED_CERTFILE_HOSTNAME
- context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
- else:
+def make_test_context(
+ *,
+ server_side=False,
+ check_hostname=None,
+ cert_reqs=ssl.CERT_NONE,
+ ca_certs=None, certfile=None, keyfile=None,
+ ciphers=None,
+ min_version=None, max_version=None,
+):
+ if server_side:
context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
- if cert_reqs is not None:
+ else:
+ context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+
+ if check_hostname is None:
if cert_reqs == ssl.CERT_NONE:
context.check_hostname = False
+ else:
+ context.check_hostname = check_hostname
+
+ if cert_reqs is not None:
context.verify_mode = cert_reqs
+
if ca_certs is not None:
context.load_verify_locations(ca_certs)
if certfile is not None or keyfile is not None:
context.load_cert_chain(certfile, keyfile)
+
if ciphers is not None:
context.set_ciphers(ciphers)
- return context.wrap_socket(sock, **kwargs)
+
+ if min_version is not None:
+ context.minimum_version = min_version
+ if max_version is not None:
+ context.maximum_version = max_version
+
+ return context
+
+
+def test_wrap_socket(
+ sock,
+ *,
+ server_side=False,
+ check_hostname=None,
+ cert_reqs=ssl.CERT_NONE,
+ ca_certs=None, certfile=None, keyfile=None,
+ ciphers=None,
+ min_version=None, max_version=None,
+ **kwargs,
+):
+ context = make_test_context(
+ server_side=server_side,
+ check_hostname=check_hostname,
+ cert_reqs=cert_reqs,
+ ca_certs=ca_certs, certfile=certfile, keyfile=keyfile,
+ ciphers=ciphers,
+ min_version=min_version, max_version=max_version,
+ )
+ if not server_side:
+ kwargs.setdefault("server_hostname", SIGNED_CERTFILE_HOSTNAME)
+ return context.wrap_socket(sock, server_side=server_side, **kwargs)
USE_SAME_TEST_CONTEXT = False
@@ -1085,7 +1136,12 @@ def test_min_max_version(self):
ctx.maximum_version = ssl.TLSVersion.MINIMUM_SUPPORTED
self.assertIn(
ctx.maximum_version,
- {ssl.TLSVersion.TLSv1, ssl.TLSVersion.TLSv1_1, ssl.TLSVersion.SSLv3}
+ {
+ ssl.TLSVersion.TLSv1,
+ ssl.TLSVersion.TLSv1_1,
+ ssl.TLSVersion.TLSv1_2,
+ ssl.TLSVersion.SSLv3,
+ }
)
ctx.minimum_version = ssl.TLSVersion.MAXIMUM_SUPPORTED
@@ -1660,6 +1716,39 @@ def test_num_tickest(self):
with self.assertRaises(ValueError):
ctx.num_tickets = 1
+ @support.cpython_only
+ def test_refcycle_msg_callback(self):
+ # See https://github.com/python/cpython/issues/142516.
+ ctx = make_test_context()
+ def msg_callback(*args, _=ctx, **kwargs): ...
+ ctx._msg_callback = msg_callback
+
+ @support.cpython_only
+ @requires_keylog_setter
+ def test_refcycle_keylog_filename(self):
+ # See https://github.com/python/cpython/issues/142516.
+ self.addCleanup(os_helper.unlink, os_helper.TESTFN)
+ ctx = make_test_context()
+ class KeylogFilename(str): ...
+ ctx.keylog_filename = KeylogFilename(os_helper.TESTFN)
+ ctx.keylog_filename._ = ctx
+
+ @support.cpython_only
+ @unittest.skipUnless(ssl.HAS_PSK, 'requires TLS-PSK')
+ def test_refcycle_psk_client_callback(self):
+ # See https://github.com/python/cpython/issues/142516.
+ ctx = make_test_context()
+ def psk_client_callback(*args, _=ctx, **kwargs): ...
+ ctx.set_psk_client_callback(psk_client_callback)
+
+ @support.cpython_only
+ @unittest.skipUnless(ssl.HAS_PSK, 'requires TLS-PSK')
+ def test_refcycle_psk_server_callback(self):
+ # See https://github.com/python/cpython/issues/142516.
+ ctx = make_test_context(server_side=True)
+ def psk_server_callback(*args, _=ctx, **kwargs): ...
+ ctx.set_psk_server_callback(psk_server_callback)
+
class SSLErrorTests(unittest.TestCase):
@@ -4909,10 +4998,6 @@ def test_internal_chain_server(self):
self.assertEqual(res, b'\x02\n')
-HAS_KEYLOG = hasattr(ssl.SSLContext, 'keylog_filename')
-requires_keylog = unittest.skipUnless(
- HAS_KEYLOG, 'test requires OpenSSL 1.1.1 with keylog callback')
-
class TestSSLDebug(unittest.TestCase):
def keylog_lines(self, fname=os_helper.TESTFN):
diff --git a/Lib/test/test_struct.py b/Lib/test/test_struct.py
index 59133e24e64..598f10b1862 100644
--- a/Lib/test/test_struct.py
+++ b/Lib/test/test_struct.py
@@ -552,6 +552,15 @@ def test_count_overflow(self):
hugecount2 = '{}b{}H'.format(sys.maxsize//2, sys.maxsize//2)
self.assertRaises(struct.error, struct.calcsize, hugecount2)
+ hugecount3 = '{}i{}q'.format(sys.maxsize // 4, sys.maxsize // 8)
+ self.assertRaises(struct.error, struct.calcsize, hugecount3)
+
+ hugecount4 = '{}?s'.format(sys.maxsize)
+ self.assertRaises(struct.error, struct.calcsize, hugecount4)
+
+ hugecount5 = '{}?p'.format(sys.maxsize)
+ self.assertRaises(struct.error, struct.calcsize, hugecount5)
+
def test_trailing_counter(self):
store = array.array('b', b' '*100)
@@ -581,8 +590,24 @@ def test_Struct_reinitialization(self):
# Issue 9422: there was a memory leak when reinitializing a
# Struct instance. This test can be used to detect the leak
# when running with regrtest -L.
- s = struct.Struct('i')
- s.__init__('ii')
+ s = struct.Struct('>h')
+ s.__init__('>hh')
+ self.assertEqual(s.format, '>hh')
+ packed = b'\x00\x01\x00\x02'
+ self.assertEqual(s.pack(1, 2), packed)
+ self.assertEqual(s.unpack(packed), (1, 2))
+
+ with self.assertRaises(UnicodeEncodeError):
+ s.__init__('\udc00')
+ self.assertEqual(s.format, '>hh')
+ self.assertEqual(s.pack(1, 2), packed)
+ self.assertEqual(s.unpack(packed), (1, 2))
+
+ with self.assertRaises(struct.error):
+ s.__init__('$')
+ self.assertEqual(s.format, '>hh')
+ self.assertEqual(s.pack(1, 2), packed)
+ self.assertEqual(s.unpack(packed), (1, 2))
def check_sizeof(self, format_str, number_of_codes):
# The size of 'PyStructObject'
@@ -833,6 +858,8 @@ def test_operations_on_half_initialized_Struct(self):
self.assertRaises(RuntimeError, S.unpack, spam)
self.assertRaises(RuntimeError, S.unpack_from, spam)
self.assertRaises(RuntimeError, getattr, S, 'format')
+ self.assertRaises(RuntimeError, S.__sizeof__)
+ self.assertRaises(RuntimeError, repr, S)
self.assertEqual(S.size, -1)
diff --git a/Lib/test/test_support.py b/Lib/test/test_support.py
index 27cd5afb390..79f0e2eb29f 100644
--- a/Lib/test/test_support.py
+++ b/Lib/test/test_support.py
@@ -778,6 +778,7 @@ def test_get_signal_name(self):
(128 + int(signal.SIGABRT), 'SIGABRT'),
(3221225477, "STATUS_ACCESS_VIOLATION"),
(0xC00000FD, "STATUS_STACK_OVERFLOW"),
+ (0xC0000906, "0xC0000906"),
):
self.assertEqual(support.get_signal_name(exitcode), expected,
exitcode)
diff --git a/Lib/test/test_tempfile.py b/Lib/test/test_tempfile.py
index 52b13b98cbc..2c524635b57 100644
--- a/Lib/test/test_tempfile.py
+++ b/Lib/test/test_tempfile.py
@@ -330,17 +330,36 @@ def _mock_candidate_names(*names):
class TestBadTempdir:
def test_read_only_directory(self):
with _inside_empty_temp_dir():
- oldmode = mode = os.stat(tempfile.tempdir).st_mode
- mode &= ~(stat.S_IWUSR | stat.S_IWGRP | stat.S_IWOTH)
- os.chmod(tempfile.tempdir, mode)
+ probe = os.path.join(tempfile.tempdir, 'probe')
+ if os.name == 'nt':
+ cmd = ['icacls', tempfile.tempdir, '/deny', 'Everyone:(W)']
+ stdout = None if support.verbose > 1 else subprocess.DEVNULL
+ subprocess.run(cmd, check=True, stdout=stdout)
+ else:
+ oldmode = mode = os.stat(tempfile.tempdir).st_mode
+ mode &= ~(stat.S_IWUSR | stat.S_IWGRP | stat.S_IWOTH)
+ mode = stat.S_IREAD
+ os.chmod(tempfile.tempdir, mode)
try:
- if os.access(tempfile.tempdir, os.W_OK):
+ # Check that the directory is read-only.
+ try:
+ os.mkdir(probe)
+ except PermissionError:
+ pass
+ else:
+ os.rmdir(probe)
self.skipTest("can't set the directory read-only")
+ # gh-66305: Now it takes a split second, but previously
+ # it took about 10 days on Windows.
with self.assertRaises(PermissionError):
self.make_temp()
- self.assertEqual(os.listdir(tempfile.tempdir), [])
finally:
- os.chmod(tempfile.tempdir, oldmode)
+ if os.name == 'nt':
+ cmd = ['icacls', tempfile.tempdir, '/grant:r', 'Everyone:(M)']
+ subprocess.run(cmd, check=True, stdout=stdout)
+ else:
+ os.chmod(tempfile.tempdir, oldmode)
+ self.assertEqual(os.listdir(tempfile.tempdir), [])
def test_nonexisting_directory(self):
with _inside_empty_temp_dir():
diff --git a/Lib/test/test_tools/test_compute_changes.py b/Lib/test/test_tools/test_compute_changes.py
new file mode 100644
index 00000000000..b20ff975fc2
--- /dev/null
+++ b/Lib/test/test_tools/test_compute_changes.py
@@ -0,0 +1,144 @@
+"""Tests to cover the Tools/build/compute-changes.py script."""
+
+import importlib
+import os
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from test.test_tools import skip_if_missing, imports_under_tool
+
+skip_if_missing("build")
+
+with patch.dict(os.environ, {"GITHUB_DEFAULT_BRANCH": "main"}):
+ with imports_under_tool("build"):
+ compute_changes = importlib.import_module("compute-changes")
+
+process_changed_files = compute_changes.process_changed_files
+Outputs = compute_changes.Outputs
+ANDROID_DIRS = compute_changes.ANDROID_DIRS
+IOS_DIRS = compute_changes.IOS_DIRS
+MACOS_DIRS = compute_changes.MACOS_DIRS
+WASI_DIRS = compute_changes.WASI_DIRS
+RUN_TESTS_IGNORE = compute_changes.RUN_TESTS_IGNORE
+UNIX_BUILD_SYSTEM_FILE_NAMES = compute_changes.UNIX_BUILD_SYSTEM_FILE_NAMES
+LIBRARY_FUZZER_PATHS = compute_changes.LIBRARY_FUZZER_PATHS
+
+
+class TestProcessChangedFiles(unittest.TestCase):
+
+ def test_windows(self):
+ f = {Path(".github/workflows/reusable-windows.yml")}
+ result = process_changed_files(f)
+ self.assertTrue(result.run_tests)
+ self.assertTrue(result.run_windows_tests)
+
+ def test_docs(self):
+ for f in (
+ ".github/workflows/reusable-docs.yml",
+ "Doc/library/datetime.rst",
+ "Doc/Makefile",
+ ):
+ with self.subTest(f=f):
+ result = process_changed_files({Path(f)})
+ self.assertTrue(result.run_docs)
+ self.assertFalse(result.run_tests)
+
+ def test_ci_fuzz_stdlib(self):
+ for p in LIBRARY_FUZZER_PATHS:
+ with self.subTest(p=p):
+ if p.is_dir():
+ f = p / "file"
+ elif p.is_file():
+ f = p
+ else:
+ continue
+ result = process_changed_files({f})
+ self.assertTrue(result.run_ci_fuzz_stdlib)
+
+ def test_android(self):
+ for d in ANDROID_DIRS:
+ with self.subTest(d=d):
+ result = process_changed_files({Path(d) / "file"})
+ self.assertTrue(result.run_tests)
+ self.assertTrue(result.run_android)
+ self.assertFalse(result.run_windows_tests)
+
+ def test_ios(self):
+ for d in IOS_DIRS:
+ with self.subTest(d=d):
+ result = process_changed_files({Path(d) / "file"})
+ self.assertTrue(result.run_tests)
+ self.assertTrue(result.run_ios)
+ self.assertFalse(result.run_windows_tests)
+
+ def test_macos(self):
+ f = {Path(".github/workflows/reusable-macos.yml")}
+ result = process_changed_files(f)
+ self.assertTrue(result.run_tests)
+ self.assertTrue(result.run_macos)
+
+ for d in MACOS_DIRS:
+ with self.subTest(d=d):
+ result = process_changed_files({Path(d) / "file"})
+ self.assertTrue(result.run_tests)
+ self.assertTrue(result.run_macos)
+ self.assertFalse(result.run_windows_tests)
+
+ def test_wasi(self):
+ f = {Path(".github/workflows/reusable-wasi.yml")}
+ result = process_changed_files(f)
+ self.assertTrue(result.run_tests)
+ self.assertTrue(result.run_wasi)
+
+ for d in WASI_DIRS:
+ with self.subTest(d=d):
+ result = process_changed_files({d / "file"})
+ self.assertTrue(result.run_tests)
+ self.assertTrue(result.run_wasi)
+ self.assertFalse(result.run_windows_tests)
+
+ def test_unix(self):
+ for f in UNIX_BUILD_SYSTEM_FILE_NAMES:
+ with self.subTest(f=f):
+ result = process_changed_files({f})
+ self.assertTrue(result.run_tests)
+ self.assertFalse(result.run_windows_tests)
+
+ def test_msi(self):
+ for f in (
+ ".github/workflows/reusable-windows-msi.yml",
+ "Tools/msi/build.bat",
+ ):
+ with self.subTest(f=f):
+ result = process_changed_files({Path(f)})
+ self.assertTrue(result.run_windows_msi)
+
+ def test_all_run(self):
+ for f in (
+ ".github/workflows/some-new-workflow.yml",
+ ".github/workflows/build.yml",
+ ):
+ with self.subTest(f=f):
+ result = process_changed_files({Path(f)})
+ self.assertTrue(result.run_tests)
+ self.assertTrue(result.run_android)
+ self.assertTrue(result.run_ios)
+ self.assertTrue(result.run_macos)
+ self.assertTrue(result.run_ubuntu)
+ self.assertTrue(result.run_wasi)
+
+ def test_all_ignored(self):
+ for f in RUN_TESTS_IGNORE:
+ with self.subTest(f=f):
+ self.assertEqual(process_changed_files({Path(f)}), Outputs())
+
+ def test_wasi_and_android(self):
+ f = {Path(".github/workflows/reusable-wasi.yml"), Path("Android/file")}
+ result = process_changed_files(f)
+ self.assertTrue(result.run_tests)
+ self.assertTrue(result.run_wasi)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/Lib/test/test_traceback.py b/Lib/test/test_traceback.py
index c87ad67ed05..db6063b8650 100644
--- a/Lib/test/test_traceback.py
+++ b/Lib/test/test_traceback.py
@@ -4168,6 +4168,27 @@ def method(self, name):
self.assertIn("'_bluch'", self.get_suggestion(partial(B().method, '_luch')))
self.assertIn("'_bluch'", self.get_suggestion(partial(B().method, 'bluch')))
+ def test_getattr_suggestions_with_custom___dir__(self):
+ class M(type):
+ def __dir__(cls):
+ return [None, "fox"]
+
+ class C0:
+ def __dir__(self):
+ return [..., "bluch"]
+
+ class C1(C0, metaclass=M):
+ pass
+
+ self.assertNotIn("'bluch'", self.get_suggestion(C0, "blach"))
+ self.assertIn("'bluch'", self.get_suggestion(C0(), "blach"))
+
+ self.assertIn("'fox'", self.get_suggestion(C1, "foo"))
+ self.assertNotIn("'fox'", self.get_suggestion(C1(), "foo"))
+
+ self.assertNotIn("'bluch'", self.get_suggestion(C1, "blach"))
+ self.assertIn("'bluch'", self.get_suggestion(C1(), "blach"))
+
def test_getattr_suggestions_do_not_trigger_for_long_attributes(self):
class A:
blech = None
diff --git a/Lib/test/test_type_params.py b/Lib/test/test_type_params.py
index 0f393def827..84c1b954136 100644
--- a/Lib/test/test_type_params.py
+++ b/Lib/test/test_type_params.py
@@ -152,6 +152,13 @@ def test_incorrect_mro_explicit_object(self):
with self.assertRaisesRegex(TypeError, r"\(MRO\) for bases object, Generic"):
class My[X](object): ...
+ def test_compile_error_in_type_param_bound(self):
+ # This should not crash, see gh-145187
+ check_syntax_error(
+ self,
+ "if True:\n class h[l:{7for*()in 0}]:2"
+ )
+
class TypeParamsNonlocalTest(unittest.TestCase):
def test_nonlocal_disallowed_01(self):
diff --git a/Lib/test/test_ucn.py b/Lib/test/test_ucn.py
index 0e2c25aaff2..fb8e98af25b 100644
--- a/Lib/test/test_ucn.py
+++ b/Lib/test/test_ucn.py
@@ -88,6 +88,9 @@ def test_hangul_syllables(self):
self.checkletter("HANGUL SYLLABLE HWEOK", "\ud6f8")
self.checkletter("HANGUL SYLLABLE HIH", "\ud7a3")
+ self.checkletter("haNGul SYllABle WAe", '\uc65c')
+ self.checkletter("HAngUL syLLabLE waE", '\uc65c')
+
self.assertRaises(ValueError, unicodedata.name, "\ud7a4")
def test_cjk_unified_ideographs(self):
@@ -103,6 +106,35 @@ def test_cjk_unified_ideographs(self):
self.checkletter("CJK UNIFIED IDEOGRAPH-2B81D", "\U0002B81D")
self.checkletter("CJK UNIFIED IDEOGRAPH-3134A", "\U0003134A")
+ self.checkletter("cjK UniFIeD idEogRAph-3aBc", "\u3abc")
+ self.checkletter("CJk uNIfiEd IDeOGraPH-3AbC", "\u3abc")
+ self.checkletter("cjK UniFIeD idEogRAph-2aBcD", "\U0002abcd")
+ self.checkletter("CJk uNIfiEd IDeOGraPH-2AbCd", "\U0002abcd")
+
+ def test_tangut_ideographs(self):
+ self.checkletter("TANGUT IDEOGRAPH-17000", "\U00017000")
+ self.checkletter("TANGUT IDEOGRAPH-187F7", "\U000187f7")
+ self.checkletter("TANGUT IDEOGRAPH-18D00", "\U00018D00")
+ self.checkletter("TANGUT IDEOGRAPH-18D08", "\U00018d08")
+ self.checkletter("tangut ideograph-18d08", "\U00018d08")
+
+ def test_egyptian_hieroglyphs(self):
+ self.checkletter("EGYPTIAN HIEROGLYPH-13460", "\U00013460")
+ self.checkletter("EGYPTIAN HIEROGLYPH-143FA", "\U000143fa")
+ self.checkletter("egyptian hieroglyph-143fa", "\U000143fa")
+
+ def test_khitan_small_script_characters(self):
+ self.checkletter("KHITAN SMALL SCRIPT CHARACTER-18B00", "\U00018b00")
+ self.checkletter("KHITAN SMALL SCRIPT CHARACTER-18CD5", "\U00018cd5")
+ self.checkletter("KHITAN SMALL SCRIPT CHARACTER-18CFF", "\U00018cff")
+ self.checkletter("KHITAN SMALL SCRIPT CHARACTER-18CFF", "\U00018cff")
+ self.checkletter("khitan small script character-18cff", "\U00018cff")
+
+ def test_nushu_characters(self):
+ self.checkletter("NUSHU CHARACTER-1B170", "\U0001b170")
+ self.checkletter("NUSHU CHARACTER-1B2FB", "\U0001b2fb")
+ self.checkletter("nushu character-1b2fb", "\U0001b2fb")
+
def test_bmp_characters(self):
for code in range(0x10000):
char = chr(code)
diff --git a/Lib/test/test_unicodedata.py b/Lib/test/test_unicodedata.py
index e98539deb99..93d57399640 100644
--- a/Lib/test/test_unicodedata.py
+++ b/Lib/test/test_unicodedata.py
@@ -89,9 +89,9 @@ class UnicodeFunctionsTest(unittest.TestCase):
# Update this if the database changes. Make sure to do a full rebuild
# (e.g. 'make distclean && make') to get the correct checksum.
- expectedchecksum = ('35e842600fa7ae2db93739db08ef201b726a2374'
+ expectedchecksum = ('1ba453ec456896f1190d849b6e9b7c2e1a4128e0'
if quicktest else
- '23ab09ed4abdf93db23b97359108ed630dd8311d')
+ '46ca89d9fe34881d0be3a4a4b29f5aa8c019640c')
def test_function_checksum(self):
db = self.db
@@ -116,6 +116,56 @@ def test_function_checksum(self):
result = h.hexdigest()
self.assertEqual(result, self.expectedchecksum)
+ def test_name(self):
+ name = self.db.name
+ self.assertRaises(ValueError, name, '\0')
+ self.assertRaises(ValueError, name, '\n')
+ self.assertRaises(ValueError, name, '\x1F')
+ self.assertRaises(ValueError, name, '\x7F')
+ self.assertRaises(ValueError, name, '\x9F')
+ self.assertRaises(ValueError, name, '\uFFFE')
+ self.assertRaises(ValueError, name, '\uFFFF')
+ self.assertRaises(ValueError, name, '\U0010FFFF')
+ self.assertEqual(name('\U0010FFFF', 42), 42)
+
+ self.assertEqual(name(' '), 'SPACE')
+ self.assertEqual(name('1'), 'DIGIT ONE')
+ self.assertEqual(name('A'), 'LATIN CAPITAL LETTER A')
+ self.assertEqual(name('\xA0'), 'NO-BREAK SPACE')
+ self.assertEqual(name('\u0221', None), None if self.old else
+ 'LATIN SMALL LETTER D WITH CURL')
+ self.assertEqual(name('\u3400'), 'CJK UNIFIED IDEOGRAPH-3400')
+ self.assertEqual(name('\u9FA5'), 'CJK UNIFIED IDEOGRAPH-9FA5')
+ self.assertEqual(name('\uAC00'), 'HANGUL SYLLABLE GA')
+ self.assertEqual(name('\uD7A3'), 'HANGUL SYLLABLE HIH')
+ self.assertEqual(name('\uF900'), 'CJK COMPATIBILITY IDEOGRAPH-F900')
+ self.assertEqual(name('\uFA6A'), 'CJK COMPATIBILITY IDEOGRAPH-FA6A')
+ self.assertEqual(name('\uFBF9'),
+ 'ARABIC LIGATURE UIGHUR KIRGHIZ YEH WITH HAMZA '
+ 'ABOVE WITH ALEF MAKSURA ISOLATED FORM')
+ self.assertEqual(name('\U00013460', None), None if self.old else
+ 'EGYPTIAN HIEROGLYPH-13460')
+ self.assertEqual(name('\U000143FA', None), None if self.old else
+ 'EGYPTIAN HIEROGLYPH-143FA')
+ self.assertEqual(name('\U00018B00', None), None if self.old else
+ 'KHITAN SMALL SCRIPT CHARACTER-18B00')
+ self.assertEqual(name('\U00018CD5', None), None if self.old else
+ 'KHITAN SMALL SCRIPT CHARACTER-18CD5')
+ self.assertEqual(name('\U00018CFF', None), None if self.old else
+ 'KHITAN SMALL SCRIPT CHARACTER-18CFF')
+ self.assertEqual(name('\U0001B170', None), None if self.old else
+ 'NUSHU CHARACTER-1B170')
+ self.assertEqual(name('\U0001B2FB', None), None if self.old else
+ 'NUSHU CHARACTER-1B2FB')
+ self.assertEqual(name('\U0001FBA8', None), None if self.old else
+ 'BOX DRAWINGS LIGHT DIAGONAL UPPER CENTRE TO '
+ 'MIDDLE LEFT AND MIDDLE RIGHT TO LOWER CENTRE')
+ self.assertEqual(name('\U0002A6D6'), 'CJK UNIFIED IDEOGRAPH-2A6D6')
+ self.assertEqual(name('\U0002FA1D'), 'CJK COMPATIBILITY IDEOGRAPH-2FA1D')
+ self.assertEqual(name('\U000323AF', None), None if self.old else
+ 'CJK UNIFIED IDEOGRAPH-323AF')
+
+ @requires_resource('cpu')
def test_name_inverse_lookup(self):
for char in iterallchars():
looked_name = self.db.name(char, None)
@@ -139,6 +189,17 @@ def test_lookup_nonexistant(self):
"HANDBUG",
"MODIFIER LETTER CYRILLIC SMALL QUESTION MARK",
"???",
+ "CJK UNIFIED IDEOGRAPH-03400",
+ "CJK UNIFIED IDEOGRAPH-020000",
+ "CJK UNIFIED IDEOGRAPH-33FF",
+ "CJK UNIFIED IDEOGRAPH-F900",
+ "CJK UNIFIED IDEOGRAPH-13460",
+ "CJK UNIFIED IDEOGRAPH-17000",
+ "CJK UNIFIED IDEOGRAPH-18B00",
+ "CJK UNIFIED IDEOGRAPH-1B170",
+ "CJK COMPATIBILITY IDEOGRAPH-3400",
+ "TANGUT IDEOGRAPH-3400",
+ "HANGUL SYLLABLE AC00",
]:
self.assertRaises(KeyError, self.db.lookup, nonexistent)
@@ -170,10 +231,14 @@ def test_numeric(self):
# New in 4.1.0
self.assertEqual(self.db.numeric('\U0001012A', None), None if self.old else 9000)
+ # Changed in 4.1.0
+ self.assertEqual(self.db.numeric('\u5793', None), 1e20 if self.old else None)
# New in 5.0.0
self.assertEqual(self.db.numeric('\u07c0', None), None if self.old else 0.0)
# New in 5.1.0
self.assertEqual(self.db.numeric('\ua627', None), None if self.old else 7.0)
+ # Changed in 5.2.0
+ self.assertEqual(self.db.numeric('\u09f6'), 3.0 if self.old else 3/16)
# New in 6.0.0
self.assertEqual(self.db.numeric('\u0b72', None), None if self.old else 0.25)
# New in 12.0.0
@@ -281,6 +346,12 @@ def test_decomposition(self):
# New in 16.0.0
self.assertEqual(self.db.decomposition('\U0001CCD6'), '' if self.old else '<font> 0041')
+ # Hangul characters
+ self.assertEqual(self.db.decomposition('\uAC00'), '1100 1161')
+ self.assertEqual(self.db.decomposition('\uD4DB'), '1111 1171 11B6')
+ self.assertEqual(self.db.decomposition('\uC2F8'), '110A 1161')
+ self.assertEqual(self.db.decomposition('\uD7A3'), '1112 1175 11C2')
+
self.assertRaises(TypeError, self.db.decomposition)
self.assertRaises(TypeError, self.db.decomposition, 'xx')
@@ -584,9 +655,9 @@ def test_east_asian_width_unassigned(self):
class Unicode_3_2_0_FunctionsTest(UnicodeFunctionsTest):
db = unicodedata.ucd_3_2_0
old = True
- expectedchecksum = ('76b126d719d52ba11788a627d058163106da7d56'
+ expectedchecksum = ('883824cb6c0ccf994e4451ebf281e2d6d479af47'
if quicktest else
- 'ed843cb7ab5aaf149466498db27fefce81c4214c')
+ 'caf1a7f2f380f927461837f1901ef20683f98683')
class UnicodeMiscTest(unittest.TestCase):
diff --git a/Lib/test/test_unpack_ex.py b/Lib/test/test_unpack_ex.py
index 9e2d54bd3a8..c948d51452d 100644
--- a/Lib/test/test_unpack_ex.py
+++ b/Lib/test/test_unpack_ex.py
@@ -383,13 +383,13 @@
Some size constraints (all fail.)
- >>> s = ", ".join("a%d" % i for i in range(1<<8)) + ", *rest = range(1<<8 + 1)"
+ >>> s = ", ".join("a%d" % i for i in range(1<<8)) + ", *rest = range((1<<8) + 1)"
>>> compile(s, 'test', 'exec') # doctest:+ELLIPSIS
Traceback (most recent call last):
...
SyntaxError: too many expressions in star-unpacking assignment
- >>> s = ", ".join("a%d" % i for i in range(1<<8 + 1)) + ", *rest = range(1<<8 + 2)"
+ >>> s = ", ".join("a%d" % i for i in range((1<<8) + 1)) + ", *rest = range((1<<8) + 2)"
>>> compile(s, 'test', 'exec') # doctest:+ELLIPSIS
Traceback (most recent call last):
...
diff --git a/Lib/test/test_venv.py b/Lib/test/test_venv.py
index d108165be51..e63b9dfc182 100644
--- a/Lib/test/test_venv.py
+++ b/Lib/test/test_venv.py
@@ -11,13 +11,13 @@
import os.path
import pathlib
import re
+import shlex
import shutil
import struct
import subprocess
import sys
import sysconfig
import tempfile
-import shlex
from test.support import (captured_stdout, captured_stderr,
skip_if_broken_multiprocessing_synchronize, verbose,
requires_subprocess, is_android, is_apple_mobile,
@@ -379,6 +379,16 @@ def create_contents(self, paths, filename):
with open(fn, 'wb') as f:
f.write(b'Still here?')
+ @unittest.skipUnless(hasattr(os, 'listxattr'), 'test requires os.listxattr')
+ def test_install_scripts_selinux(self):
+ """
+ gh-145417: Test that install_scripts does not copy SELinux context
+ when copying scripts.
+ """
+ with patch('os.listxattr') as listxattr_mock:
+ venv.create(self.env_dir)
+ listxattr_mock.assert_not_called()
+
def test_overwrite_existing(self):
"""
Test creating environment in an existing directory.
diff --git a/Lib/test/test_wsgiref.py b/Lib/test/test_wsgiref.py
index 0bf9e947b5e..0b33db93780 100644
--- a/Lib/test/test_wsgiref.py
+++ b/Lib/test/test_wsgiref.py
@@ -504,14 +504,20 @@ def testExtras(self):
)
def testRaisesControlCharacters(self):
- headers = Headers()
for c0 in control_characters_c0():
- self.assertRaises(ValueError, headers.__setitem__, f"key{c0}", "val")
- self.assertRaises(ValueError, headers.__setitem__, "key", f"val{c0}")
- self.assertRaises(ValueError, headers.add_header, f"key{c0}", "val", param="param")
- self.assertRaises(ValueError, headers.add_header, "key", f"val{c0}", param="param")
- self.assertRaises(ValueError, headers.add_header, "key", "val", param=f"param{c0}")
-
+ with self.subTest(c0):
+ headers = Headers()
+ self.assertRaises(ValueError, headers.__setitem__, f"key{c0}", "val")
+ self.assertRaises(ValueError, headers.add_header, f"key{c0}", "val", param="param")
+ # HTAB (\x09) is allowed in values, not names.
+ if c0 == "\t":
+ headers["key"] = f"val{c0}"
+ headers.add_header("key", f"val{c0}")
+ headers.setdefault(f"key", f"val{c0}")
+ else:
+ self.assertRaises(ValueError, headers.__setitem__, "key", f"val{c0}")
+ self.assertRaises(ValueError, headers.add_header, "key", f"val{c0}", param="param")
+ self.assertRaises(ValueError, headers.add_header, "key", "val", param=f"param{c0}")
class ErrorHandler(BaseCGIHandler):
"""Simple handler subclass for testing BaseHandler"""
@@ -849,6 +855,25 @@ def write(self, b):
self.assertIsNotNone(h.status)
self.assertIsNotNone(h.environ)
+ def testRaisesControlCharacters(self):
+ for c0 in control_characters_c0():
+ with self.subTest(c0):
+ base = BaseHandler()
+ with self.assertRaises(ValueError):
+ base.start_response(c0, [('x', 'y')])
+
+ base = BaseHandler()
+ with self.assertRaises(ValueError):
+ base.start_response('200 OK', [(c0, 'y')])
+
+ # HTAB (\x09) is allowed in header values, but not in names.
+ base = BaseHandler()
+ if c0 != "\t":
+ with self.assertRaises(ValueError):
+ base.start_response('200 OK', [('x', c0)])
+ else:
+ base.start_response('200 OK', [('x', c0)])
+
if __name__ == "__main__":
unittest.main()
diff --git a/Lib/test/test_zoneinfo/test_zoneinfo.py b/Lib/test/test_zoneinfo/test_zoneinfo.py
index 88d79b258cd..8a58c7d68ac 100644
--- a/Lib/test/test_zoneinfo/test_zoneinfo.py
+++ b/Lib/test/test_zoneinfo/test_zoneinfo.py
@@ -1577,6 +1577,44 @@ class EvilZoneInfo(self.klass):
class CZoneInfoCacheTest(ZoneInfoCacheTest):
module = c_zoneinfo
+ def test_inconsistent_weak_cache_get(self):
+ class Cache:
+ def get(self, key, default=None):
+ return 1337
+
+ class ZI(self.klass):
+ pass
+ # Class attribute must be set after class creation
+ # to override zoneinfo.ZoneInfo.__init_subclass__.
+ ZI._weak_cache = Cache()
+
+ with self.assertRaises(RuntimeError) as te:
+ ZI("America/Los_Angeles")
+ self.assertEqual(
+ str(te.exception),
+ "Unexpected instance of int in ZI weak cache for key 'America/Los_Angeles'"
+ )
+
+ def test_inconsistent_weak_cache_setdefault(self):
+ class Cache:
+ def get(self, key, default=None):
+ return default
+ def setdefault(self, key, value):
+ return 1337
+
+ class ZI(self.klass):
+ pass
+ # Class attribute must be set after class creation
+ # to override zoneinfo.ZoneInfo.__init_subclass__.
+ ZI._weak_cache = Cache()
+
+ with self.assertRaises(RuntimeError) as te:
+ ZI("America/Los_Angeles")
+ self.assertEqual(
+ str(te.exception),
+ "Unexpected instance of int in ZI weak cache for key 'America/Los_Angeles'"
+ )
+
class ZoneInfoPickleTest(TzPathUserMixin, ZoneInfoTestBase):
module = py_zoneinfo
diff --git a/Lib/traceback.py b/Lib/traceback.py
index 5a34a2b87b6..79f67b9878b 100644
--- a/Lib/traceback.py
+++ b/Lib/traceback.py
@@ -1589,17 +1589,23 @@ def _substitution_cost(ch_a, ch_b):
return _MOVE_COST
+def _get_safe___dir__(obj):
+ # Use obj.__dir__() to avoid a TypeError when calling dir(obj).
+ # See gh-131001 and gh-139933.
+ try:
+ d = obj.__dir__()
+ except TypeError: # when obj is a class
+ d = type(obj).__dir__(obj)
+ return sorted(x for x in d if isinstance(x, str))
+
+
def _compute_suggestion_error(exc_value, tb, wrong_name):
if wrong_name is None or not isinstance(wrong_name, str):
return None
if isinstance(exc_value, AttributeError):
obj = exc_value.obj
try:
- try:
- d = dir(obj)
- except TypeError: # Attributes are unsortable, e.g. int and str
- d = list(obj.__class__.__dict__.keys()) + list(obj.__dict__.keys())
- d = sorted([x for x in d if isinstance(x, str)])
+ d = _get_safe___dir__(obj)
hide_underscored = (wrong_name[:1] != '_')
if hide_underscored and tb is not None:
while tb.tb_next is not None:
@@ -1614,11 +1620,7 @@ def _compute_suggestion_error(exc_value, tb, wrong_name):
elif isinstance(exc_value, ImportError):
try:
mod = __import__(exc_value.name)
- try:
- d = dir(mod)
- except TypeError: # Attributes are unsortable, e.g. int and str
- d = list(mod.__dict__.keys())
- d = sorted([x for x in d if isinstance(x, str)])
+ d = _get_safe___dir__(mod)
if wrong_name[:1] != '_':
d = [x for x in d if x[:1] != '_']
except Exception:
diff --git a/Lib/unittest/mock.py b/Lib/unittest/mock.py
index feb9730d6e9..545b0730d2e 100644
--- a/Lib/unittest/mock.py
+++ b/Lib/unittest/mock.py
@@ -1184,10 +1184,16 @@ def _increment_mock_call(self, /, *args, **kwargs):
# handle call_args
# needs to be set here so assertions on call arguments pass before
# execution in the case of awaited calls
- _call = _Call((args, kwargs), two=True)
- self.call_args = _call
- self.call_args_list.append(_call)
- self.call_count = len(self.call_args_list)
+ with NonCallableMock._lock:
+ # Lock is used here so that call_args_list and call_count are
+ # set atomically otherwise it is possible that by the time call_count
+ # is set another thread may have appended to call_args_list.
+ # The rest of this function relies on list.append being atomic and
+ # skips locking.
+ _call = _Call((args, kwargs), two=True)
+ self.call_args = _call
+ self.call_args_list.append(_call)
+ self.call_count = len(self.call_args_list)
# initial stuff for method_calls:
do_method_calls = self._mock_parent is not None
diff --git a/Lib/urllib/parse.py b/Lib/urllib/parse.py
index 67d9bbea0d3..a651e815ddc 100644
--- a/Lib/urllib/parse.py
+++ b/Lib/urllib/parse.py
@@ -1,6 +1,6 @@
"""Parse (absolute and relative) URLs.
-urlparse module is based upon the following RFC specifications.
+urllib.parse module is based upon the following RFC specifications.
RFC 3986 (STD66): "Uniform Resource Identifiers" by T. Berners-Lee, R. Fielding
and L. Masinter, January 2005.
@@ -20,7 +20,7 @@
McCahill, December 1994
RFC 3986 is considered the current standard and any future changes to
-urlparse module should conform with it. The urlparse module is
+urllib.parse module should conform with it. The urllib.parse module is
currently not entirely compliant with this RFC due to defacto
scenarios for parsing, and for backward compatibility purposes, some
parsing quirks from older RFCs are retained. The testcases in
@@ -390,6 +390,8 @@ def urlparse(url, scheme='', allow_fragments=True):
path or query.
Note that % escapes are not expanded.
+
+ urlsplit() should generally be used instead of urlparse().
"""
url, scheme, _coerce_result = _coerce_args(url, scheme)
scheme, netloc, url, params, query, fragment = _urlparse(url, scheme, allow_fragments)
diff --git a/Lib/venv/__init__.py b/Lib/venv/__init__.py
index 17ee28e826d..88f3340af41 100644
--- a/Lib/venv/__init__.py
+++ b/Lib/venv/__init__.py
@@ -588,7 +588,7 @@ def skip_file(f):
'may be binary: %s', srcfile, e)
continue
if new_data == data:
- shutil.copy2(srcfile, dstfile)
+ shutil.copy(srcfile, dstfile)
else:
with open(dstfile, 'wb') as f:
f.write(new_data)
diff --git a/Lib/wsgiref/handlers.py b/Lib/wsgiref/handlers.py
index cafe872c7aa..f8fe89f6e13 100644
--- a/Lib/wsgiref/handlers.py
+++ b/Lib/wsgiref/handlers.py
@@ -1,7 +1,7 @@
"""Base classes for server/gateway implementations"""
from .util import FileWrapper, guess_scheme, is_hop_by_hop
-from .headers import Headers
+from .headers import Headers, _name_disallowed_re
import sys, os, time
@@ -249,6 +249,8 @@ def start_response(self, status, headers,exc_info=None):
return self.write
def _validate_status(self, status):
+ if _name_disallowed_re.search(status):
+ raise ValueError("Control characters are not allowed in status")
if len(status) < 4:
raise AssertionError("Status must be at least 4 characters")
if not status[:3].isdigit():
diff --git a/Lib/wsgiref/headers.py b/Lib/wsgiref/headers.py
index e180a623cb2..eb6ea6a412d 100644
--- a/Lib/wsgiref/headers.py
+++ b/Lib/wsgiref/headers.py
@@ -9,7 +9,11 @@
# existence of which force quoting of the parameter value.
import re
tspecials = re.compile(r'[ \(\)<>@,;:\\"/\[\]\?=]')
-_control_chars_re = re.compile(r'[\x00-\x1F\x7F]')
+# Disallowed characters for headers and values.
+# HTAB (\x09) is allowed in header values, but
+# not in header names. (RFC 9110 Section 5.5)
+_name_disallowed_re = re.compile(r'[\x00-\x1F\x7F]')
+_value_disallowed_re = re.compile(r'[\x00-\x08\x0A-\x1F\x7F]')
def _formatparam(param, value=None, quote=1):
"""Convenience function to format and return a key=value pair.
@@ -36,13 +40,14 @@ def __init__(self, headers=None):
self._headers = headers
if __debug__:
for k, v in headers:
- self._convert_string_type(k)
- self._convert_string_type(v)
+ self._convert_string_type(k, name=True)
+ self._convert_string_type(v, name=False)
- def _convert_string_type(self, value):
+ def _convert_string_type(self, value, *, name):
"""Convert/check value type."""
if type(value) is str:
- if _control_chars_re.search(value):
+ regex = (_name_disallowed_re if name else _value_disallowed_re)
+ if regex.search(value):
raise ValueError("Control characters not allowed in headers")
return value
raise AssertionError("Header names/values must be"
@@ -56,14 +61,14 @@ def __setitem__(self, name, val):
"""Set the value of a header."""
del self[name]
self._headers.append(
- (self._convert_string_type(name), self._convert_string_type(val)))
+ (self._convert_string_type(name, name=True), self._convert_string_type(val, name=False)))
def __delitem__(self,name):
"""Delete all occurrences of a header, if present.
Does *not* raise an exception if the header is missing.
"""
- name = self._convert_string_type(name.lower())
+ name = self._convert_string_type(name.lower(), name=True)
self._headers[:] = [kv for kv in self._headers if kv[0].lower() != name]
def __getitem__(self,name):
@@ -90,13 +95,13 @@ def get_all(self, name):
fields deleted and re-inserted are always appended to the header list.
If no fields exist with the given name, returns an empty list.
"""
- name = self._convert_string_type(name.lower())
+ name = self._convert_string_type(name.lower(), name=True)
return [kv[1] for kv in self._headers if kv[0].lower()==name]
def get(self,name,default=None):
"""Get the first header value for 'name', or return 'default'"""
- name = self._convert_string_type(name.lower())
+ name = self._convert_string_type(name.lower(), name=True)
for k,v in self._headers:
if k.lower()==name:
return v
@@ -151,8 +156,8 @@ def setdefault(self,name,value):
and value 'value'."""
result = self.get(name)
if result is None:
- self._headers.append((self._convert_string_type(name),
- self._convert_string_type(value)))
+ self._headers.append((self._convert_string_type(name, name=True),
+ self._convert_string_type(value, name=False)))
return value
else:
return result
@@ -175,13 +180,13 @@ def add_header(self, _name, _value, **_params):
"""
parts = []
if _value is not None:
- _value = self._convert_string_type(_value)
+ _value = self._convert_string_type(_value, name=False)
parts.append(_value)
for k, v in _params.items():
- k = self._convert_string_type(k)
+ k = self._convert_string_type(k, name=True)
if v is None:
parts.append(k.replace('_', '-'))
else:
- v = self._convert_string_type(v)
+ v = self._convert_string_type(v, name=False)
parts.append(_formatparam(k.replace('_', '-'), v))
- self._headers.append((self._convert_string_type(_name), "; ".join(parts)))
+ self._headers.append((self._convert_string_type(_name, name=True), "; ".join(parts)))
diff --git a/Lib/zipfile/__init__.py b/Lib/zipfile/__init__.py
index ac2332e5846..19aea290b58 100644
--- a/Lib/zipfile/__init__.py
+++ b/Lib/zipfile/__init__.py
@@ -950,7 +950,7 @@ class ZipExtFile(io.BufferedIOBase):
"""
# Max size supported by decompressor.
- MAX_N = 1 << 31 - 1
+ MAX_N = (1 << 31) - 1
# Read from compressed files in 4k blocks.
MIN_READ_SIZE = 4096
diff --git a/Lib/zoneinfo/_zoneinfo.py b/Lib/zoneinfo/_zoneinfo.py
index 3ffdb4c8371..bd3fefc6c9d 100644
--- a/Lib/zoneinfo/_zoneinfo.py
+++ b/Lib/zoneinfo/_zoneinfo.py
@@ -47,7 +47,11 @@ def __new__(cls, key):
cls._strong_cache[key] = cls._strong_cache.pop(key, instance)
if len(cls._strong_cache) > cls._strong_cache_size:
- cls._strong_cache.popitem(last=False)
+ try:
+ cls._strong_cache.popitem(last=False)
+ except KeyError:
+ # another thread may have already emptied the cache
+ pass
return instance
diff --git a/Mac/BuildScript/build-installer.py b/Mac/BuildScript/build-installer.py
index 4fd8d55f35a..e7732981d38 100755
--- a/Mac/BuildScript/build-installer.py
+++ b/Mac/BuildScript/build-installer.py
@@ -246,9 +246,9 @@ def library_recipes():
result.extend([
dict(
- name="OpenSSL 3.0.18",
- url="https://github.com/openssl/openssl/releases/download/openssl-3.0.18/openssl-3.0.18.tar.gz",
- checksum='d80c34f5cf902dccf1f1b5df5ebb86d0392e37049e5d73df1b3abae72e4ffe8b',
+ name="OpenSSL 3.0.19",
+ url="https://github.com/openssl/openssl/releases/download/openssl-3.0.19/openssl-3.0.19.tar.gz",
+ checksum='fa5a4143b8aae18be53ef2f3caf29a2e0747430b8bc74d32d88335b94ab63072',
buildrecipe=build_universal_openssl,
configure=None,
install=None,
diff --git a/Mac/BuildScript/resources/install_certificates.command b/Mac/BuildScript/resources/install_certificates.command
index 19b4adac07b..700eb462b68 100755
--- a/Mac/BuildScript/resources/install_certificates.command
+++ b/Mac/BuildScript/resources/install_certificates.command
@@ -25,7 +25,8 @@ def main():
print(" -- pip install --upgrade certifi")
subprocess.check_call([sys.executable,
- "-E", "-s", "-m", "pip", "install", "--upgrade", "certifi"])
+ "-E", "-s", "-m", "pip", "install", "--upgrade", "certifi",
+ "--disable-pip-version-check"])
import certifi
diff --git a/Misc/ACKS b/Misc/ACKS
index 949df55ea39..e17b83ae973 100644
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -1071,6 +1071,7 @@ Wolfgang Langner
Detlef Lannert
Rémi Lapeyre
Soren Larsen
+Seth Michael Larson
Amos Latteier
Keenan Lau
Piers Lauder
diff --git a/Misc/externals.spdx.json b/Misc/externals.spdx.json
index 59aceedb94d..3b37e125cae 100644
--- a/Misc/externals.spdx.json
+++ b/Misc/externals.spdx.json
@@ -70,21 +70,21 @@
"checksums": [
{
"algorithm": "SHA256",
- "checksumValue": "9b07560b6c1afa666bd78b8d3aa5c83fdda02149afdf048596d5b0e0dac1ee55"
+ "checksumValue": "c6ea8a5423f3966923060db2089f869017dfb10bcf2037394146e7a74caec0a8"
}
],
- "downloadLocation": "https://github.com/python/cpython-source-deps/archive/refs/tags/openssl-3.0.18.tar.gz",
+ "downloadLocation": "https://github.com/python/cpython-source-deps/archive/refs/tags/openssl-3.0.19.tar.gz",
"externalRefs": [
{
"referenceCategory": "SECURITY",
- "referenceLocator": "cpe:2.3:a:openssl:openssl:3.0.18:*:*:*:*:*:*:*",
+ "referenceLocator": "cpe:2.3:a:openssl:openssl:3.0.19:*:*:*:*:*:*:*",
"referenceType": "cpe23Type"
}
],
"licenseConcluded": "NOASSERTION",
"name": "openssl",
"primaryPackagePurpose": "SOURCE",
- "versionInfo": "3.0.18"
+ "versionInfo": "3.0.19"
},
{
"SPDXID": "SPDXRef-PACKAGE-sqlite",
diff --git a/Misc/sbom.spdx.json b/Misc/sbom.spdx.json
index d64857ce233..2c06a7d3745 100644
--- a/Misc/sbom.spdx.json
+++ b/Misc/sbom.spdx.json
@@ -6,11 +6,11 @@
"checksums": [
{
"algorithm": "SHA1",
- "checksumValue": "39e6f567a10e36b2e77727e98e60bbcb3eb3af0b"
+ "checksumValue": "f1b1126ed7da8f2068302e7a692b0600e6f94b07"
},
{
"algorithm": "SHA256",
- "checksumValue": "122f2c27000472a201d337b9b31f7eb2b52d091b02857061a8880371612d9534"
+ "checksumValue": "31b15de82aa19a845156169a17a5488bf597e561b2c318d159ed583139b25e87"
}
],
"fileName": "Modules/expat/COPYING"
@@ -48,11 +48,11 @@
"checksums": [
{
"algorithm": "SHA1",
- "checksumValue": "a4395dd0589a97aab0904f7a5f5dc5781a086aa2"
+ "checksumValue": "9bd33bd279c0d7ea37b0f2d7e07c7c53b7053507"
},
{
"algorithm": "SHA256",
- "checksumValue": "610b844bbfa3ec955772cc825db4d4db470827d57adcb214ad372d0eaf00e591"
+ "checksumValue": "d20997001462356b5ce3810ebf5256c8205f58462c64f21eb9bf80f8d1822b08"
}
],
"fileName": "Modules/expat/expat.h"
@@ -62,11 +62,11 @@
"checksums": [
{
"algorithm": "SHA1",
- "checksumValue": "c22196e3d8bee88fcdda715623b3b9d2119d2fb3"
+ "checksumValue": "e658ee5d638ab326109282ff09f1541e27fff8c2"
},
{
"algorithm": "SHA256",
- "checksumValue": "f2c2283ba03b057e92beefc7f81ba901ebb6dfc1a45b036c8a7d65808eb77a84"
+ "checksumValue": "dbe0582b8f8a8140aca97009e8760105ceed9e7df01ea9d8b3fe47cebf2e5b2d"
}
],
"fileName": "Modules/expat/expat_external.h"
@@ -90,11 +90,11 @@
"checksums": [
{
"algorithm": "SHA1",
- "checksumValue": "7dce7d98943c5db33ae05e54801dcafb4547b9dd"
+ "checksumValue": "6a4a232233ba1034c3f2b459159d502e9b2d413b"
},
{
"algorithm": "SHA256",
- "checksumValue": "6bfe307d52e7e4c71dbc30d3bd902a4905cdd83bbe4226a7e8dfa8e4c462a157"
+ "checksumValue": "c803935722f0dbdeeede7f040028fb119135e96dfad949479f8a5304b885bdd6"
}
],
"fileName": "Modules/expat/internal.h"
@@ -174,11 +174,11 @@
"checksums": [
{
"algorithm": "SHA1",
- "checksumValue": "4c81a1f04fc653877c63c834145c18f93cd95f3e"
+ "checksumValue": "7d3d7d72aa56c53fb5b9e10c0e74e161381f0255"
},
{
"algorithm": "SHA256",
- "checksumValue": "04a379615f476d55f95ca1853107e20627b48ca4afe8d0fd5981ac77188bf0a6"
+ "checksumValue": "f4f87aa0268d92f2b8f5e663788bfadd2e926477d0b061ed4463c02ad29a3e25"
}
],
"fileName": "Modules/expat/xmlparse.c"
@@ -188,11 +188,11 @@
"checksums": [
{
"algorithm": "SHA1",
- "checksumValue": "ef767128d2dda99436712dcf3465dde5dbaab876"
+ "checksumValue": "c8769fcb93f00272a6e6ca560be633649c817ff7"
},
{
"algorithm": "SHA256",
- "checksumValue": "71fb52aa302cf6f56e41943009965804f49ff2210d9bd15b258f70aaf70db772"
+ "checksumValue": "5b81f0eb0e144b611dbd1bc9e6037075a16bff94f823d57a81eb2a3e4999e91a"
}
],
"fileName": "Modules/expat/xmlrole.c"
@@ -216,11 +216,11 @@
"checksums": [
{
"algorithm": "SHA1",
- "checksumValue": "1e2d35d90a1c269217f83d3bdf3c71cc22cb4c3f"
+ "checksumValue": "63e4766a09e63760c6518670509198f8d638f4ad"
},
{
"algorithm": "SHA256",
- "checksumValue": "98d0fc735041956cc2e7bbbe2fb8f03130859410e0aee5e8015f406a37c02a3c"
+ "checksumValue": "0ad3f915f2748dc91bf4e4b4a50cf40bf2c95769d0eca7e3b293a230d82bb779"
}
],
"fileName": "Modules/expat/xmltok.c"
@@ -272,11 +272,11 @@
"checksums": [
{
"algorithm": "SHA1",
- "checksumValue": "2d82d0a1201f78d478b30d108ff8fc27ee3e2672"
+ "checksumValue": "41b8c8fc275882c76d4210b7d40a18e506b07147"
},
{
"algorithm": "SHA256",
- "checksumValue": "6ce6d03193279078d55280150fe91e7370370b504a6c123a79182f28341f3e90"
+ "checksumValue": "b2188c7e5fa5b33e355cf6cf342dfb8f6e23859f2a6b1ddf79841d7f84f7b196"
}
],
"fileName": "Modules/expat/xmltok_ns.c"
@@ -1730,14 +1730,14 @@
"checksums": [
{
"algorithm": "SHA256",
- "checksumValue": "821ac9710d2c073eaf13e1b1895a9c9aa66c1157a99635c639fbff65cdbdd732"
+ "checksumValue": "461ecc8aa98ab1a68c2db788175665d1a4db640dc05bf0e289b6ea17122144ec"
}
],
- "downloadLocation": "https://github.com/libexpat/libexpat/releases/download/R_2_7_3/expat-2.7.3.tar.gz",
+ "downloadLocation": "https://github.com/libexpat/libexpat/releases/download/R_2_7_4/expat-2.7.4.tar.gz",
"externalRefs": [
{
"referenceCategory": "SECURITY",
- "referenceLocator": "cpe:2.3:a:libexpat_project:libexpat:2.7.3:*:*:*:*:*:*:*",
+ "referenceLocator": "cpe:2.3:a:libexpat_project:libexpat:2.7.4:*:*:*:*:*:*:*",
"referenceType": "cpe23Type"
}
],
@@ -1745,7 +1745,7 @@
"name": "expat",
"originator": "Organization: Expat development team",
"primaryPackagePurpose": "SOURCE",
- "versionInfo": "2.7.3"
+ "versionInfo": "2.7.4"
},
{
"SPDXID": "SPDXRef-PACKAGE-hacl-star",
diff --git a/Modules/_asynciomodule.c b/Modules/_asynciomodule.c
index 7ff3aeff2c7..6ec50b15200 100644
--- a/Modules/_asynciomodule.c
+++ b/Modules/_asynciomodule.c
@@ -4075,30 +4075,44 @@ _asyncio_all_tasks_impl(PyObject *module, PyObject *loop)
return NULL;
}
- PyInterpreterState *interp = PyInterpreterState_Get();
- // Stop the world and traverse the per-thread linked list
- // of asyncio tasks for every thread, as well as the
- // interpreter's linked list, and add them to `tasks`.
- // The interpreter linked list is used for any lingering tasks
- // whose thread state has been deallocated while the task was
- // still alive. This can happen if a task is referenced by
- // a different thread, in which case the task is moved to
- // the interpreter's linked list from the thread's linked
- // list before deallocation. See PyThreadState_Clear.
- //
- // The stop-the-world pause is required so that no thread
- // modifies its linked list while being iterated here
- // in parallel. This design allows for lock-free
- // register_task/unregister_task for loops running in parallel
- // in different threads (the general case).
- _PyEval_StopTheWorld(interp);
- int ret = add_tasks_interp(interp, (PyListObject *)tasks);
- _PyEval_StartTheWorld(interp);
- if (ret < 0) {
- // call any escaping calls after starting the world to avoid any deadlocks.
- Py_DECREF(tasks);
- Py_DECREF(loop);
- return NULL;
+ _PyThreadStateImpl *ts = (_PyThreadStateImpl *)_PyThreadState_GET();
+ if (ts->asyncio_running_loop == loop) {
+ // Fast path for the current running loop of current thread
+ // no locking or stop the world pause is required
+ struct llist_node *head = &ts->asyncio_tasks_head;
+ if (add_tasks_llist(head, (PyListObject *)tasks) < 0) {
+ Py_DECREF(tasks);
+ Py_DECREF(loop);
+ return NULL;
+ }
+ }
+ else {
+ // Slow path for loop running in different thread
+ PyInterpreterState *interp = ts->base.interp;
+ // Stop the world and traverse the per-thread linked list
+ // of asyncio tasks for every thread, as well as the
+ // interpreter's linked list, and add them to `tasks`.
+ // The interpreter linked list is used for any lingering tasks
+ // whose thread state has been deallocated while the task was
+ // still alive. This can happen if a task is referenced by
+ // a different thread, in which case the task is moved to
+ // the interpreter's linked list from the thread's linked
+ // list before deallocation. See PyThreadState_Clear.
+ //
+ // The stop-the-world pause is required so that no thread
+ // modifies its linked list while being iterated here
+ // in parallel. This design allows for lock-free
+ // register_task/unregister_task for loops running in parallel
+ // in different threads (the general case).
+ _PyEval_StopTheWorld(interp);
+ int ret = add_tasks_interp(interp, (PyListObject *)tasks);
+ _PyEval_StartTheWorld(interp);
+ if (ret < 0) {
+ // call any escaping calls after starting the world to avoid any deadlocks.
+ Py_DECREF(tasks);
+ Py_DECREF(loop);
+ return NULL;
+ }
}
// All the tasks are now in the list, now filter the tasks which are done
diff --git a/Modules/_collectionsmodule.c b/Modules/_collectionsmodule.c
index 45ca63e6d7c..72865f87fc4 100644
--- a/Modules/_collectionsmodule.c
+++ b/Modules/_collectionsmodule.c
@@ -605,29 +605,42 @@ deque_copy_impl(dequeobject *deque)
collections_state *state = find_module_state_by_def(Py_TYPE(deque));
if (Py_IS_TYPE(deque, state->deque_type)) {
dequeobject *new_deque;
- PyObject *rv;
+ Py_ssize_t n = Py_SIZE(deque);
new_deque = (dequeobject *)deque_new(state->deque_type, NULL, NULL);
if (new_deque == NULL)
return NULL;
new_deque->maxlen = old_deque->maxlen;
- /* Fast path for the deque_repeat() common case where len(deque) == 1
- *
- * It's safe to not acquire the per-object lock for new_deque; it's
- * invisible to other threads.
+
+ /* Copy elements directly by walking the block structure.
+ * This is safe because the caller holds the deque lock and
+ * the new deque is not yet visible to other threads.
*/
- if (Py_SIZE(deque) == 1) {
- PyObject *item = old_deque->leftblock->data[old_deque->leftindex];
- rv = deque_append_impl(new_deque, item);
- } else {
- rv = deque_extend_impl(new_deque, (PyObject *)deque);
- }
- if (rv != NULL) {
- Py_DECREF(rv);
- return (PyObject *)new_deque;
+ if (n > 0) {
+ block *b = old_deque->leftblock;
+ Py_ssize_t index = old_deque->leftindex;
+
+ /* Space saving heuristic. Start filling from the left */
+ assert(new_deque->leftblock == new_deque->rightblock);
+ assert(new_deque->leftindex == new_deque->rightindex + 1);
+ new_deque->leftindex = 1;
+ new_deque->rightindex = 0;
+
+ for (Py_ssize_t i = 0; i < n; i++) {
+ PyObject *item = b->data[index];
+ if (deque_append_lock_held(new_deque, Py_NewRef(item),
+ new_deque->maxlen) < 0) {
+ Py_DECREF(new_deque);
+ return NULL;
+ }
+ index++;
+ if (index == BLOCKLEN) {
+ b = b->rightlink;
+ index = 0;
+ }
+ }
}
- Py_DECREF(new_deque);
- return NULL;
+ return (PyObject *)new_deque;
}
if (old_deque->maxlen < 0)
result = PyObject_CallOneArg((PyObject *)(Py_TYPE(deque)),
diff --git a/Modules/_functoolsmodule.c b/Modules/_functoolsmodule.c
index 490c6b83d21..d779376b191 100644
--- a/Modules/_functoolsmodule.c
+++ b/Modules/_functoolsmodule.c
@@ -611,65 +611,72 @@ partial_repr(PyObject *self)
{
partialobject *pto = partialobject_CAST(self);
PyObject *result = NULL;
- PyObject *arglist;
- PyObject *mod;
- PyObject *name;
+ PyObject *arglist = NULL;
+ PyObject *mod = NULL;
+ PyObject *name = NULL;
Py_ssize_t i, n;
PyObject *key, *value;
int status;
status = Py_ReprEnter(self);
if (status != 0) {
- if (status < 0)
+ if (status < 0) {
return NULL;
+ }
return PyUnicode_FromString("...");
}
+ /* Reference arguments in case they change */
+ PyObject *fn = Py_NewRef(pto->fn);
+ PyObject *args = Py_NewRef(pto->args);
+ PyObject *kw = Py_NewRef(pto->kw);
+ assert(PyTuple_Check(args));
+ assert(PyDict_Check(kw));
arglist = Py_GetConstant(Py_CONSTANT_EMPTY_STR);
- if (arglist == NULL)
+ if (arglist == NULL) {
goto done;
+ }
/* Pack positional arguments */
- assert(PyTuple_Check(pto->args));
- n = PyTuple_GET_SIZE(pto->args);
+ n = PyTuple_GET_SIZE(args);
for (i = 0; i < n; i++) {
Py_SETREF(arglist, PyUnicode_FromFormat("%U, %R", arglist,
- PyTuple_GET_ITEM(pto->args, i)));
- if (arglist == NULL)
+ PyTuple_GET_ITEM(args, i)));
+ if (arglist == NULL) {
goto done;
+ }
}
/* Pack keyword arguments */
- assert (PyDict_Check(pto->kw));
- for (i = 0; PyDict_Next(pto->kw, &i, &key, &value);) {
+ for (i = 0; PyDict_Next(kw, &i, &key, &value);) {
/* Prevent key.__str__ from deleting the value. */
Py_INCREF(value);
Py_SETREF(arglist, PyUnicode_FromFormat("%U, %S=%R", arglist,
key, value));
Py_DECREF(value);
- if (arglist == NULL)
+ if (arglist == NULL) {
goto done;
+ }
}
mod = PyType_GetModuleName(Py_TYPE(pto));
if (mod == NULL) {
- goto error;
+ goto done;
}
+
name = PyType_GetQualName(Py_TYPE(pto));
if (name == NULL) {
- Py_DECREF(mod);
- goto error;
+ goto done;
}
- result = PyUnicode_FromFormat("%S.%S(%R%U)", mod, name, pto->fn, arglist);
- Py_DECREF(mod);
- Py_DECREF(name);
- Py_DECREF(arglist);
- done:
+ result = PyUnicode_FromFormat("%S.%S(%R%U)", mod, name, fn, arglist);
+done:
+ Py_XDECREF(name);
+ Py_XDECREF(mod);
+ Py_XDECREF(arglist);
+ Py_DECREF(fn);
+ Py_DECREF(args);
+ Py_DECREF(kw);
Py_ReprLeave(self);
return result;
- error:
- Py_DECREF(arglist);
- Py_ReprLeave(self);
- return NULL;
}
/* Pickle strategy:
diff --git a/Modules/_hashopenssl.c b/Modules/_hashopenssl.c
index c8a76e14990..e7cb315f160 100644
--- a/Modules/_hashopenssl.c
+++ b/Modules/_hashopenssl.c
@@ -238,7 +238,7 @@ py_hashentry_table_new(void) {
if (h->py_alias != NULL) {
if (_Py_hashtable_set(ht, (const void*)entry->py_alias, (void*)entry) < 0) {
- PyMem_Free(entry);
+ /* entry is already in ht, will be freed by _Py_hashtable_destroy() */
goto error;
}
entry->refcnt++;
diff --git a/Modules/_interpchannelsmodule.c b/Modules/_interpchannelsmodule.c
index ef9cf01ecbe..2933332ad46 100644
--- a/Modules/_interpchannelsmodule.c
+++ b/Modules/_interpchannelsmodule.c
@@ -1644,14 +1644,16 @@ _channels_list_all(_channels *channels, int64_t *count)
if (ids == NULL) {
goto done;
}
- _channelref *ref = channels->head;
- for (int64_t i=0; ref != NULL; ref = ref->next, i++) {
- ids[i] = (struct channel_id_and_info){
- .id = ref->cid,
- .defaults = ref->chan->defaults,
- };
+ int64_t i = 0;
+ for (_channelref *ref = channels->head; ref != NULL; ref = ref->next) {
+ if (ref->chan != NULL) {
+ ids[i++] = (struct channel_id_and_info){
+ .id = ref->cid,
+ .defaults = ref->chan->defaults,
+ };
+ }
}
- *count = channels->numopen;
+ *count = i;
cids = ids;
done:
diff --git a/Modules/_io/clinic/textio.c.h b/Modules/_io/clinic/textio.c.h
index 128a5ad1678..3898a9c2982 100644
--- a/Modules/_io/clinic/textio.c.h
+++ b/Modules/_io/clinic/textio.c.h
@@ -430,7 +430,9 @@ _io_IncrementalNewlineDecoder_decode(PyObject *self, PyObject *const *args, Py_s
goto exit;
}
skip_optional_pos:
+ Py_BEGIN_CRITICAL_SECTION(self);
return_value = _io_IncrementalNewlineDecoder_decode_impl((nldecoder_object *)self, input, final);
+ Py_END_CRITICAL_SECTION();
exit:
return return_value;
@@ -450,7 +452,13 @@ _io_IncrementalNewlineDecoder_getstate_impl(nldecoder_object *self);
static PyObject *
_io_IncrementalNewlineDecoder_getstate(PyObject *self, PyObject *Py_UNUSED(ignored))
{
- return _io_IncrementalNewlineDecoder_getstate_impl((nldecoder_object *)self);
+ PyObject *return_value = NULL;
+
+ Py_BEGIN_CRITICAL_SECTION(self);
+ return_value = _io_IncrementalNewlineDecoder_getstate_impl((nldecoder_object *)self);
+ Py_END_CRITICAL_SECTION();
+
+ return return_value;
}
PyDoc_STRVAR(_io_IncrementalNewlineDecoder_setstate__doc__,
@@ -470,7 +478,9 @@ _io_IncrementalNewlineDecoder_setstate(PyObject *self, PyObject *state)
{
PyObject *return_value = NULL;
+ Py_BEGIN_CRITICAL_SECTION(self);
return_value = _io_IncrementalNewlineDecoder_setstate_impl((nldecoder_object *)self, state);
+ Py_END_CRITICAL_SECTION();
return return_value;
}
@@ -489,7 +499,13 @@ _io_IncrementalNewlineDecoder_reset_impl(nldecoder_object *self);
static PyObject *
_io_IncrementalNewlineDecoder_reset(PyObject *self, PyObject *Py_UNUSED(ignored))
{
- return _io_IncrementalNewlineDecoder_reset_impl((nldecoder_object *)self);
+ PyObject *return_value = NULL;
+
+ Py_BEGIN_CRITICAL_SECTION(self);
+ return_value = _io_IncrementalNewlineDecoder_reset_impl((nldecoder_object *)self);
+ Py_END_CRITICAL_SECTION();
+
+ return return_value;
}
PyDoc_STRVAR(_io_TextIOWrapper___init____doc__,
@@ -1312,4 +1328,4 @@ _io_TextIOWrapper__CHUNK_SIZE_set(PyObject *self, PyObject *value, void *Py_UNUS
return return_value;
}
-/*[clinic end generated code: output=30404271a1151056 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=c38e6cd5ff4b7eea input=a9049054013a1b77]*/
diff --git a/Modules/_io/textio.c b/Modules/_io/textio.c
index 9945febea80..99180017a3c 100644
--- a/Modules/_io/textio.c
+++ b/Modules/_io/textio.c
@@ -518,6 +518,7 @@ _PyIncrementalNewlineDecoder_decode(PyObject *myself,
}
/*[clinic input]
+@critical_section
_io.IncrementalNewlineDecoder.decode
input: object
final: bool = False
@@ -526,18 +527,19 @@ _io.IncrementalNewlineDecoder.decode
static PyObject *
_io_IncrementalNewlineDecoder_decode_impl(nldecoder_object *self,
PyObject *input, int final)
-/*[clinic end generated code: output=0d486755bb37a66e input=90e223c70322c5cd]*/
+/*[clinic end generated code: output=0d486755bb37a66e input=9475d16a73168504]*/
{
return _PyIncrementalNewlineDecoder_decode((PyObject *) self, input, final);
}
/*[clinic input]
+@critical_section
_io.IncrementalNewlineDecoder.getstate
[clinic start generated code]*/
static PyObject *
_io_IncrementalNewlineDecoder_getstate_impl(nldecoder_object *self)
-/*[clinic end generated code: output=f0d2c9c136f4e0d0 input=f8ff101825e32e7f]*/
+/*[clinic end generated code: output=f0d2c9c136f4e0d0 input=dc3e1f27aa850f12]*/
{
PyObject *buffer;
unsigned long long flag;
@@ -575,6 +577,7 @@ _io_IncrementalNewlineDecoder_getstate_impl(nldecoder_object *self)
}
/*[clinic input]
+@critical_section
_io.IncrementalNewlineDecoder.setstate
state: object
/
@@ -583,7 +586,7 @@ _io.IncrementalNewlineDecoder.setstate
static PyObject *
_io_IncrementalNewlineDecoder_setstate_impl(nldecoder_object *self,
PyObject *state)
-/*[clinic end generated code: output=09135cb6e78a1dc8 input=c53fb505a76dbbe2]*/
+/*[clinic end generated code: output=09135cb6e78a1dc8 input=275fd3982d2b08cb]*/
{
PyObject *buffer;
unsigned long long flag;
@@ -613,12 +616,13 @@ _io_IncrementalNewlineDecoder_setstate_impl(nldecoder_object *self,
}
/*[clinic input]
+@critical_section
_io.IncrementalNewlineDecoder.reset
[clinic start generated code]*/
static PyObject *
_io_IncrementalNewlineDecoder_reset_impl(nldecoder_object *self)
-/*[clinic end generated code: output=32fa40c7462aa8ff input=728678ddaea776df]*/
+/*[clinic end generated code: output=32fa40c7462aa8ff input=31bd8ae4e36cec83]*/
{
CHECK_INITIALIZED_DECODER(self);
diff --git a/Modules/_localemodule.c b/Modules/_localemodule.c
index cb448b14d8c..b1d9e74db62 100644
--- a/Modules/_localemodule.c
+++ b/Modules/_localemodule.c
@@ -579,7 +579,6 @@ _locale__getdefaultlocale_impl(PyObject *module)
}
/* cannot determine the language code (very unlikely) */
- Py_INCREF(Py_None);
return Py_BuildValue("Os", Py_None, encoding);
}
#endif
diff --git a/Modules/_queuemodule.c b/Modules/_queuemodule.c
index 01235c77bd7..9e3e5d251aa 100644
--- a/Modules/_queuemodule.c
+++ b/Modules/_queuemodule.c
@@ -165,6 +165,7 @@ RingBuf_Put(RingBuf *buf, PyObject *item)
// Buffer is full, grow it.
if (resize_ringbuf(buf, buf->items_cap * 2) < 0) {
PyErr_NoMemory();
+ Py_DECREF(item);
return -1;
}
}
diff --git a/Modules/_remote_debugging_module.c b/Modules/_remote_debugging_module.c
index b46538b76df..a26e6820f55 100644
--- a/Modules/_remote_debugging_module.c
+++ b/Modules/_remote_debugging_module.c
@@ -77,6 +77,8 @@
offsetof(PyInterpreterState, _gil.last_holder) + sizeof(PyThreadState*))
#endif
#define INTERP_STATE_BUFFER_SIZE MAX(INTERP_STATE_MIN_SIZE, 256)
+#define MAX_STACK_CHUNK_SIZE (16 * 1024 * 1024) /* 16 MB max for stack chunks */
+#define MAX_SET_TABLE_SIZE (1 << 20) /* 1 million entries max for set iteration */
@@ -318,10 +320,13 @@ static int append_awaited_by(RemoteUnwinderObject *unwinder, unsigned long tid,
* UTILITY FUNCTIONS AND HELPERS
* ============================================================================ */
-#define set_exception_cause(unwinder, exc_type, message) \
- if (unwinder->debug) { \
- _set_debug_exception_cause(exc_type, message); \
- }
+#define set_exception_cause(unwinder, exc_type, message) \
+ do { \
+ assert(PyErr_Occurred() && "function returned -1 without setting exception"); \
+ if (unwinder->debug) { \
+ _set_debug_exception_cause(exc_type, message); \
+ } \
+ } while (0)
static void
cached_code_metadata_destroy(void *ptr)
@@ -498,8 +503,15 @@ iterate_set_entries(
}
Py_ssize_t num_els = GET_MEMBER(Py_ssize_t, set_object, unwinder->debug_offsets.set_object.used);
- Py_ssize_t set_len = GET_MEMBER(Py_ssize_t, set_object, unwinder->debug_offsets.set_object.mask) + 1;
+ Py_ssize_t mask = GET_MEMBER(Py_ssize_t, set_object, unwinder->debug_offsets.set_object.mask);
uintptr_t table_ptr = GET_MEMBER(uintptr_t, set_object, unwinder->debug_offsets.set_object.table);
+ if (mask < 0 || mask >= MAX_SET_TABLE_SIZE || num_els < 0 || num_els > mask + 1) {
+ PyErr_SetString(PyExc_RuntimeError, "Invalid set object (corrupted remote memory)");
+ set_exception_cause(unwinder, PyExc_RuntimeError,
+ "Invalid set object (corrupted remote memory)");
+ return -1;
+ }
+ Py_ssize_t set_len = mask + 1;
Py_ssize_t i = 0;
Py_ssize_t els = 0;
@@ -805,7 +817,7 @@ _Py_RemoteDebug_GetAsyncioDebugAddress(proc_handle_t* handle)
#ifdef MS_WINDOWS
// On Windows, search for asyncio debug in executable or DLL
- address = search_windows_map_for_section(handle, "AsyncioD", L"_asyncio");
+ address = search_windows_map_for_section(handle, "AsyncioD", L"_asyncio", NULL);
if (address == 0) {
// Error out: 'python' substring covers both executable and DLL
PyObject *exc = PyErr_GetRaisedException();
@@ -814,7 +826,7 @@ _Py_RemoteDebug_GetAsyncioDebugAddress(proc_handle_t* handle)
}
#elif defined(__linux__)
// On Linux, search for asyncio debug in executable or DLL
- address = search_linux_map_for_section(handle, "AsyncioDebug", "_asyncio.cpython");
+ address = search_linux_map_for_section(handle, "AsyncioDebug", "_asyncio.cpython", NULL);
if (address == 0) {
// Error out: 'python' substring covers both executable and DLL
PyObject *exc = PyErr_GetRaisedException();
@@ -823,10 +835,10 @@ _Py_RemoteDebug_GetAsyncioDebugAddress(proc_handle_t* handle)
}
#elif defined(__APPLE__) && TARGET_OS_OSX
// On macOS, try libpython first, then fall back to python
- address = search_map_for_section(handle, "AsyncioDebug", "_asyncio.cpython");
+ address = search_map_for_section(handle, "AsyncioDebug", "_asyncio.cpython", NULL);
if (address == 0) {
PyErr_Clear();
- address = search_map_for_section(handle, "AsyncioDebug", "_asyncio.cpython");
+ address = search_map_for_section(handle, "AsyncioDebug", "_asyncio.cpython", NULL);
}
if (address == 0) {
// Error out: 'python' substring covers both executable and DLL
@@ -1825,7 +1837,15 @@ parse_code_object(RemoteUnwinderObject *unwinder,
tlbc_entry = get_tlbc_cache_entry(unwinder, real_address, unwinder->tlbc_generation);
}
- if (tlbc_entry && tlbc_index < tlbc_entry->tlbc_array_size) {
+ if (tlbc_entry) {
+ if (tlbc_index < 0 || tlbc_index >= tlbc_entry->tlbc_array_size) {
+ PyErr_Format(PyExc_RuntimeError,
+ "Invalid tlbc_index %d (array size %zd, corrupted remote memory)",
+ tlbc_index, tlbc_entry->tlbc_array_size);
+ set_exception_cause(unwinder, PyExc_RuntimeError,
+ "Invalid tlbc_index (corrupted remote memory)");
+ goto error;
+ }
// Use cached TLBC data
uintptr_t *entries = (uintptr_t *)((char *)tlbc_entry->tlbc_array + sizeof(Py_ssize_t));
uintptr_t tlbc_bytecode_addr = entries[tlbc_index];
@@ -1924,6 +1944,15 @@ process_single_stack_chunk(
// Check actual size and reread if necessary
size_t actual_size = GET_MEMBER(size_t, this_chunk, offsetof(_PyStackChunk, size));
if (actual_size != current_size) {
+ if (actual_size <= offsetof(_PyStackChunk, data) || actual_size > MAX_STACK_CHUNK_SIZE) {
+ PyMem_RawFree(this_chunk);
+ PyErr_Format(PyExc_RuntimeError,
+ "Invalid stack chunk size %zu (corrupted remote memory)", actual_size);
+ set_exception_cause(unwinder, PyExc_RuntimeError,
+ "Invalid stack chunk size (corrupted remote memory)");
+ return -1;
+ }
+
this_chunk = PyMem_RawRealloc(this_chunk, actual_size);
if (!this_chunk) {
PyErr_NoMemory();
@@ -2027,6 +2056,7 @@ parse_frame_from_chunks(
) {
void *frame_ptr = find_frame_in_chunks(chunks, address);
if (!frame_ptr) {
+ PyErr_Format(PyExc_RuntimeError, "Frame at address 0x%lx not found in stack chunks", address);
set_exception_cause(unwinder, PyExc_RuntimeError, "Frame not found in stack chunks");
return -1;
}
@@ -2736,6 +2766,7 @@ _remote_debugging_RemoteUnwinder_get_stack_trace_impl(RemoteUnwinderObject *self
}
while (current_tstate != 0) {
+ uintptr_t prev_tstate = current_tstate;
PyObject* frame_info = unwind_stack_for_thread(self, ¤t_tstate);
if (!frame_info) {
Py_CLEAR(result);
@@ -2751,6 +2782,16 @@ _remote_debugging_RemoteUnwinder_get_stack_trace_impl(RemoteUnwinderObject *self
}
Py_DECREF(frame_info);
+ if (current_tstate == prev_tstate) {
+ PyErr_Format(PyExc_RuntimeError,
+ "Thread list cycle detected at address 0x%lx (corrupted remote memory)",
+ current_tstate);
+ set_exception_cause(self, PyExc_RuntimeError,
+ "Thread list cycle detected (corrupted remote memory)");
+ Py_CLEAR(result);
+ goto exit;
+ }
+
// We are targeting a single tstate, break here
if (self->tstate_addr) {
break;
diff --git a/Modules/_sqlite/blob.c b/Modules/_sqlite/blob.c
index aafefbf316e..16143106953 100644
--- a/Modules/_sqlite/blob.c
+++ b/Modules/_sqlite/blob.c
@@ -434,6 +434,10 @@ subscript_slice(pysqlite_Blob *self, PyObject *item)
return NULL;
}
+ if (len == 0) {
+ return PyBytes_FromStringAndSize(NULL, 0);
+ }
+
if (step == 1) {
return read_multiple(self, len, start);
}
diff --git a/Modules/_ssl.c b/Modules/_ssl.c
index 417d5ca5931..a24b6b30b2f 100644
--- a/Modules/_ssl.c
+++ b/Modules/_ssl.c
@@ -301,7 +301,7 @@ typedef struct {
int post_handshake_auth;
#endif
PyObject *msg_cb;
- PyObject *keylog_filename;
+ PyObject *keylog_filename; // can be anything accepted by Py_fopen()
BIO *keylog_bio;
/* Cached module state, also used in SSLSocket and SSLSession code. */
_sslmodulestate *state;
@@ -331,7 +331,7 @@ typedef struct {
PySSLContext *ctx; /* weakref to SSL context */
char shutdown_seen_zero;
enum py_ssl_server_or_client socket_type;
- PyObject *owner; /* Python level "owner" passed to servername callback */
+ PyObject *owner; /* weakref to Python level "owner" passed to servername callback */
PyObject *server_hostname;
_PySSLError err; /* last seen error from various sources */
/* Some SSL callbacks don't have error reporting. Callback wrappers
@@ -896,8 +896,8 @@ newPySSLSocket(PySSLContext *sslctx, PySocketSockObject *sock,
self->ssl = SSL_new(ctx);
PySSL_END_ALLOW_THREADS(sslctx)
if (self->ssl == NULL) {
+ _setSSLError(get_state_ctx(sslctx), NULL, 0, __FILE__, __LINE__);
Py_DECREF(self);
- _setSSLError(get_state_ctx(self), NULL, 0, __FILE__, __LINE__);
return NULL;
}
@@ -2345,6 +2345,10 @@ static int
PySSL_clear(PyObject *op)
{
PySSLSocket *self = PySSLSocket_CAST(op);
+ Py_CLEAR(self->Socket);
+ Py_CLEAR(self->ctx);
+ Py_CLEAR(self->owner);
+ Py_CLEAR(self->server_hostname);
Py_CLEAR(self->exc);
return 0;
}
@@ -2369,10 +2373,7 @@ PySSL_dealloc(PyObject *op)
SSL_set_shutdown(self->ssl, SSL_SENT_SHUTDOWN | SSL_get_shutdown(self->ssl));
SSL_free(self->ssl);
}
- Py_XDECREF(self->Socket);
- Py_XDECREF(self->ctx);
- Py_XDECREF(self->server_hostname);
- Py_XDECREF(self->owner);
+ (void)PySSL_clear(op);
PyObject_GC_Del(self);
Py_DECREF(tp);
}
@@ -3309,6 +3310,11 @@ context_traverse(PyObject *op, visitproc visit, void *arg)
PySSLContext *self = PySSLContext_CAST(op);
Py_VISIT(self->set_sni_cb);
Py_VISIT(self->msg_cb);
+ Py_VISIT(self->keylog_filename);
+#ifndef OPENSSL_NO_PSK
+ Py_VISIT(self->psk_client_callback);
+ Py_VISIT(self->psk_server_callback);
+#endif
Py_VISIT(Py_TYPE(self));
return 0;
}
diff --git a/Modules/_ssl_data_35.h b/Modules/_ssl_data_35.h
index e4919b550e3..8a9fef87b2a 100644
--- a/Modules/_ssl_data_35.h
+++ b/Modules/_ssl_data_35.h
@@ -1,6 +1,6 @@
/* File generated by Tools/ssl/make_ssl_data.py */
-/* Generated on 2025-10-04T17:49:19.148321+00:00 */
-/* Generated from Git commit openssl-3.5.4-0-gc1eeb9406 */
+/* Generated on 2026-02-13T19:18:20.130102+00:00 */
+/* Generated from Git commit openssl-3.5.5-0-g67b5686b4 */
/* generated from args.lib2errnum */
static struct py_ssl_library_code library_codes[] = {
@@ -1668,6 +1668,11 @@ static struct py_ssl_error_code error_codes[] = {
#else
{"CERTIFICATE_VERIFY_ERROR", 46, 100},
#endif
+ #ifdef CMS_R_CIPHER_AEAD_IN_ENVELOPED_DATA
+ {"CIPHER_AEAD_IN_ENVELOPED_DATA", ERR_LIB_CMS, CMS_R_CIPHER_AEAD_IN_ENVELOPED_DATA},
+ #else
+ {"CIPHER_AEAD_IN_ENVELOPED_DATA", 46, 200},
+ #endif
#ifdef CMS_R_CIPHER_AEAD_SET_TAG_ERROR
{"CIPHER_AEAD_SET_TAG_ERROR", ERR_LIB_CMS, CMS_R_CIPHER_AEAD_SET_TAG_ERROR},
#else
diff --git a/Modules/_struct.c b/Modules/_struct.c
index 87014a4a1e3..fe8c689b629 100644
--- a/Modules/_struct.c
+++ b/Modules/_struct.c
@@ -1620,11 +1620,11 @@ align(Py_ssize_t size, char c, const formatdef *e)
/* calculate the size of a format string */
static int
-prepare_s(PyStructObject *self)
+prepare_s(PyStructObject *self, PyObject *format)
{
const formatdef *f;
const formatdef *e;
- formatcode *codes;
+ formatcode *codes, *codes0;
const char *s;
const char *fmt;
@@ -1634,8 +1634,8 @@ prepare_s(PyStructObject *self)
_structmodulestate *state = get_struct_state_structinst(self);
- fmt = PyBytes_AS_STRING(self->s_format);
- if (strlen(fmt) != (size_t)PyBytes_GET_SIZE(self->s_format)) {
+ fmt = PyBytes_AS_STRING(format);
+ if (strlen(fmt) != (size_t)PyBytes_GET_SIZE(format)) {
PyErr_SetString(state->StructError,
"embedded null character");
return -1;
@@ -1676,9 +1676,23 @@ prepare_s(PyStructObject *self)
switch (c) {
case 's': _Py_FALLTHROUGH;
- case 'p': len++; ncodes++; break;
+ case 'p':
+ if (len == PY_SSIZE_T_MAX) {
+ goto overflow;
+ }
+ len++;
+ ncodes++;
+ break;
case 'x': break;
- default: len += num; if (num) ncodes++; break;
+ default:
+ if (num > PY_SSIZE_T_MAX - len) {
+ goto overflow;
+ }
+ len += num;
+ if (num) {
+ ncodes++;
+ }
+ break;
}
itemsize = e->size;
@@ -1703,13 +1717,7 @@ prepare_s(PyStructObject *self)
PyErr_NoMemory();
return -1;
}
- /* Free any s_codes value left over from a previous initialization. */
- if (self->s_codes != NULL)
- PyMem_Free(self->s_codes);
- self->s_codes = codes;
- self->s_size = size;
- self->s_len = len;
-
+ codes0 = codes;
s = fmt;
size = 0;
while ((c = *s++) != '\0') {
@@ -1749,6 +1757,14 @@ prepare_s(PyStructObject *self)
codes->size = 0;
codes->repeat = 0;
+ /* Free any s_codes value left over from a previous initialization. */
+ if (self->s_codes != NULL)
+ PyMem_Free(self->s_codes);
+ self->s_codes = codes0;
+ self->s_size = size;
+ self->s_len = len;
+ Py_XSETREF(self->s_format, Py_NewRef(format));
+
return 0;
overflow:
@@ -1814,9 +1830,8 @@ Struct___init___impl(PyStructObject *self, PyObject *format)
return -1;
}
- Py_SETREF(self->s_format, format);
-
- ret = prepare_s(self);
+ ret = prepare_s(self, format);
+ Py_DECREF(format);
return ret;
}
@@ -2402,6 +2417,7 @@ static PyObject *
s_sizeof(PyObject *op, PyObject *Py_UNUSED(dummy))
{
PyStructObject *self = PyStructObject_CAST(op);
+ ENSURE_STRUCT_IS_READY(self);
size_t size = _PyObject_SIZE(Py_TYPE(self)) + sizeof(formatcode);
for (formatcode *code = self->s_codes; code->fmtdef != NULL; code++) {
size += sizeof(formatcode);
@@ -2413,6 +2429,7 @@ static PyObject *
s_repr(PyObject *op)
{
PyStructObject *self = PyStructObject_CAST(op);
+ ENSURE_STRUCT_IS_READY(self);
PyObject* fmt = PyUnicode_FromStringAndSize(
PyBytes_AS_STRING(self->s_format), PyBytes_GET_SIZE(self->s_format));
if (fmt == NULL) {
diff --git a/Modules/_testcapi/function.c b/Modules/_testcapi/function.c
index ec1ba508df2..40767adbd3f 100644
--- a/Modules/_testcapi/function.c
+++ b/Modules/_testcapi/function.c
@@ -123,6 +123,13 @@ function_set_closure(PyObject *self, PyObject *args)
}
+static PyObject *
+function_get_annotations(PyObject *self, PyObject *func)
+{
+ return Py_XNewRef(PyFunction_GetAnnotations(func));
+}
+
+
static PyMethodDef test_methods[] = {
{"function_get_code", function_get_code, METH_O, NULL},
{"function_get_globals", function_get_globals, METH_O, NULL},
@@ -133,6 +140,7 @@ static PyMethodDef test_methods[] = {
{"function_set_kw_defaults", function_set_kw_defaults, METH_VARARGS, NULL},
{"function_get_closure", function_get_closure, METH_O, NULL},
{"function_set_closure", function_set_closure, METH_VARARGS, NULL},
+ {"function_get_annotations", function_get_annotations, METH_O, NULL},
{NULL},
};
diff --git a/Modules/_testinternalcapi/test_critical_sections.c b/Modules/_testinternalcapi/test_critical_sections.c
index e3b2fe716d4..72a1fa2cdc7 100644
--- a/Modules/_testinternalcapi/test_critical_sections.c
+++ b/Modules/_testinternalcapi/test_critical_sections.c
@@ -4,6 +4,8 @@
#include "parts.h"
#include "pycore_critical_section.h"
+#include "pycore_pystate.h"
+#include "pycore_pythread.h"
#ifdef MS_WINDOWS
# include <windows.h> // Sleep()
@@ -381,6 +383,87 @@ test_critical_section2_reacquisition(PyObject *self, PyObject *Py_UNUSED(args))
#endif // Py_GIL_DISABLED
+#ifdef Py_CAN_START_THREADS
+
+// gh-144513: Test that critical sections don't deadlock with stop-the-world.
+// This test is designed to deadlock (timeout) on builds without the fix.
+struct test_data_stw {
+ PyObject *obj;
+ Py_ssize_t num_threads;
+ Py_ssize_t started;
+ PyEvent ready;
+};
+
+static void
+thread_stw(void *arg)
+{
+ struct test_data_stw *test_data = arg;
+ PyGILState_STATE gil = PyGILState_Ensure();
+
+ if (_Py_atomic_add_ssize(&test_data->started, 1) == test_data->num_threads - 1) {
+ _PyEvent_Notify(&test_data->ready);
+ }
+
+ // All threads: acquire critical section and hold it long enough to
+ // trigger TIME_TO_BE_FAIR_NS (1 ms), which causes direct handoff on unlock.
+ Py_BEGIN_CRITICAL_SECTION(test_data->obj);
+ pysleep(10); // 10 ms = 10 x TIME_TO_BE_FAIR_NS
+ Py_END_CRITICAL_SECTION();
+
+ PyGILState_Release(gil);
+}
+
+static PyObject *
+test_critical_sections_stw(PyObject *self, PyObject *Py_UNUSED(args))
+{
+ // gh-144513: Test that critical sections don't deadlock during STW.
+ //
+ // The deadlock occurs when lock ownership is handed off (due to fairness
+ // after TIME_TO_BE_FAIR_NS) to a thread that has already suspended for
+ // stop-the-world. The STW requester then cannot acquire the lock.
+ //
+ // With the fix, the STW requester detects world_stopped and skips locking.
+
+ #define STW_NUM_THREADS 2
+ struct test_data_stw test_data = {
+ .obj = PyDict_New(),
+ .num_threads = STW_NUM_THREADS,
+ };
+ if (test_data.obj == NULL) {
+ return NULL;
+ }
+
+ PyThread_handle_t handles[STW_NUM_THREADS];
+ PyThread_ident_t idents[STW_NUM_THREADS];
+ for (Py_ssize_t i = 0; i < STW_NUM_THREADS; i++) {
+ PyThread_start_joinable_thread(&thread_stw, &test_data,
+ &idents[i], &handles[i]);
+ }
+
+ // Wait for threads to start, then let them compete for the lock
+ PyEvent_Wait(&test_data.ready);
+ pysleep(5);
+
+ // Request stop-the-world and try to acquire the critical section.
+ // Without the fix, this may deadlock.
+ PyInterpreterState *interp = PyInterpreterState_Get();
+ _PyEval_StopTheWorld(interp);
+
+ Py_BEGIN_CRITICAL_SECTION(test_data.obj);
+ Py_END_CRITICAL_SECTION();
+
+ _PyEval_StartTheWorld(interp);
+
+ for (Py_ssize_t i = 0; i < STW_NUM_THREADS; i++) {
+ PyThread_join_thread(handles[i]);
+ }
+ #undef STW_NUM_THREADS
+ Py_DECREF(test_data.obj);
+ Py_RETURN_NONE;
+}
+
+#endif // Py_CAN_START_THREADS
+
static PyMethodDef test_methods[] = {
{"test_critical_sections", test_critical_sections, METH_NOARGS},
{"test_critical_sections_nest", test_critical_sections_nest, METH_NOARGS},
@@ -392,6 +475,7 @@ static PyMethodDef test_methods[] = {
#ifdef Py_CAN_START_THREADS
{"test_critical_sections_threads", test_critical_sections_threads, METH_NOARGS},
{"test_critical_sections_gc", test_critical_sections_gc, METH_NOARGS},
+ {"test_critical_sections_stw", test_critical_sections_stw, METH_NOARGS},
#endif
{NULL, NULL} /* sentinel */
};
diff --git a/Modules/_testsinglephase.c b/Modules/_testsinglephase.c
index 2c59085d15b..f74b964faf3 100644
--- a/Modules/_testsinglephase.c
+++ b/Modules/_testsinglephase.c
@@ -799,3 +799,11 @@ PyInit__testsinglephase_circular(void)
}
return Py_NewRef(static_module_circular);
}
+
+
+PyMODINIT_FUNC
+PyInit__testsinglephase_raise_exception(void)
+{
+ PyErr_SetString(PyExc_RuntimeError, "evil");
+ return NULL;
+}
diff --git a/Modules/_zoneinfo.c b/Modules/_zoneinfo.c
index bfb86bdbf1a..25f7eb7a44d 100644
--- a/Modules/_zoneinfo.c
+++ b/Modules/_zoneinfo.c
@@ -335,6 +335,7 @@ zoneinfo_ZoneInfo_impl(PyTypeObject *type, PyObject *key)
return NULL;
}
+ ((PyZoneInfo_ZoneInfo *)tmp)->source = SOURCE_CACHE;
instance =
PyObject_CallMethod(weak_cache, "setdefault", "OO", key, tmp);
Py_DECREF(tmp);
@@ -342,7 +343,15 @@ zoneinfo_ZoneInfo_impl(PyTypeObject *type, PyObject *key)
Py_DECREF(weak_cache);
return NULL;
}
- ((PyZoneInfo_ZoneInfo *)instance)->source = SOURCE_CACHE;
+ }
+
+ if (!PyObject_TypeCheck(instance, type)) {
+ PyErr_Format(PyExc_RuntimeError,
+ "Unexpected instance of %T in %s weak cache for key %R",
+ instance, _PyType_Name(type), key);
+ Py_DECREF(instance);
+ Py_DECREF(weak_cache);
+ return NULL;
}
update_strong_cache(state, type, key, instance);
diff --git a/Modules/clinic/posixmodule.c.h b/Modules/clinic/posixmodule.c.h
index 87a17935507..1c7a860e1ec 100644
--- a/Modules/clinic/posixmodule.c.h
+++ b/Modules/clinic/posixmodule.c.h
@@ -3845,8 +3845,8 @@ exit:
PyDoc_STRVAR(os_posix_spawn__doc__,
"posix_spawn($module, path, argv, env, /, *, file_actions=(),\n"
-" setpgroup=<unrepresentable>, resetids=False, setsid=False,\n"
-" setsigmask=(), setsigdef=(), scheduler=<unrepresentable>)\n"
+" setpgroup=None, resetids=False, setsid=False,\n"
+" setsigmask=(), setsigdef=(), scheduler=None)\n"
"--\n"
"\n"
"Execute the program specified by path in a new process.\n"
@@ -3998,8 +3998,8 @@ exit:
PyDoc_STRVAR(os_posix_spawnp__doc__,
"posix_spawnp($module, path, argv, env, /, *, file_actions=(),\n"
-" setpgroup=<unrepresentable>, resetids=False, setsid=False,\n"
-" setsigmask=(), setsigdef=(), scheduler=<unrepresentable>)\n"
+" setpgroup=None, resetids=False, setsid=False,\n"
+" setsigmask=(), setsigdef=(), scheduler=None)\n"
"--\n"
"\n"
"Execute the program specified by path in a new process.\n"
@@ -13476,4 +13476,4 @@ exit:
#ifndef OS__EMSCRIPTEN_LOG_METHODDEF
#define OS__EMSCRIPTEN_LOG_METHODDEF
#endif /* !defined(OS__EMSCRIPTEN_LOG_METHODDEF) */
-/*[clinic end generated code: output=9e5f9b9ce732a534 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=291f607b7a26ca5e input=a9049054013a1b77]*/
diff --git a/Modules/expat/COPYING b/Modules/expat/COPYING
index ce9e5939291..c6d184a8aae 100644
--- a/Modules/expat/COPYING
+++ b/Modules/expat/COPYING
@@ -1,5 +1,5 @@
Copyright (c) 1998-2000 Thai Open Source Software Center Ltd and Clark Cooper
-Copyright (c) 2001-2022 Expat maintainers
+Copyright (c) 2001-2025 Expat maintainers
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
diff --git a/Modules/expat/expat.h b/Modules/expat/expat.h
index 290dfeb0f6d..6c7c4186927 100644
--- a/Modules/expat/expat.h
+++ b/Modules/expat/expat.h
@@ -11,7 +11,7 @@
Copyright (c) 2000-2005 Fred L. Drake, Jr. <fdrake@users.sourceforge.net>
Copyright (c) 2001-2002 Greg Stein <gstein@users.sourceforge.net>
Copyright (c) 2002-2016 Karl Waclawek <karl@waclawek.net>
- Copyright (c) 2016-2025 Sebastian Pipping <sebastian@pipping.org>
+ Copyright (c) 2016-2026 Sebastian Pipping <sebastian@pipping.org>
Copyright (c) 2016 Cristian Rodríguez <crrodriguez@opensuse.org>
Copyright (c) 2016 Thomas Beutlich <tc@tbeu.de>
Copyright (c) 2017 Rhodri James <rhodri@wildebeest.org.uk>
@@ -1082,7 +1082,7 @@ XML_SetReparseDeferralEnabled(XML_Parser parser, XML_Bool enabled);
*/
# define XML_MAJOR_VERSION 2
# define XML_MINOR_VERSION 7
-# define XML_MICRO_VERSION 3
+# define XML_MICRO_VERSION 4
# ifdef __cplusplus
}
diff --git a/Modules/expat/expat_config.h b/Modules/expat/expat_config.h
index e7d9499d907..09d3161dbc0 100644
--- a/Modules/expat/expat_config.h
+++ b/Modules/expat/expat_config.h
@@ -3,7 +3,7 @@
* distribution.
*/
#ifndef EXPAT_CONFIG_H
-#define EXPAT_CONFIG_H
+#define EXPAT_CONFIG_H 1
#include <pyconfig.h>
#ifdef WORDS_BIGENDIAN
diff --git a/Modules/expat/expat_external.h b/Modules/expat/expat_external.h
index 0f01a05d0e9..6f3f3c48ce9 100644
--- a/Modules/expat/expat_external.h
+++ b/Modules/expat/expat_external.h
@@ -12,7 +12,7 @@
Copyright (c) 2001-2002 Greg Stein <gstein@users.sourceforge.net>
Copyright (c) 2002-2006 Karl Waclawek <karl@waclawek.net>
Copyright (c) 2016 Cristian Rodríguez <crrodriguez@opensuse.org>
- Copyright (c) 2016-2019 Sebastian Pipping <sebastian@pipping.org>
+ Copyright (c) 2016-2025 Sebastian Pipping <sebastian@pipping.org>
Copyright (c) 2017 Rhodri James <rhodri@wildebeest.org.uk>
Copyright (c) 2018 Yury Gribov <tetra2005@gmail.com>
Licensed under the MIT license:
@@ -91,8 +91,7 @@
# ifndef XML_BUILDING_EXPAT
/* using Expat from an application */
-# if defined(_MSC_EXTENSIONS) && ! defined(__BEOS__) \
- && ! defined(__CYGWIN__)
+# if defined(_MSC_VER) && ! defined(__BEOS__) && ! defined(__CYGWIN__)
# define XMLIMPORT __declspec(dllimport)
# endif
diff --git a/Modules/expat/internal.h b/Modules/expat/internal.h
index 8f5edf48ef7..61266ebb772 100644
--- a/Modules/expat/internal.h
+++ b/Modules/expat/internal.h
@@ -128,7 +128,7 @@
# elif ULONG_MAX == 18446744073709551615u // 2^64-1
# define EXPAT_FMT_PTRDIFF_T(midpart) "%" midpart "ld"
# define EXPAT_FMT_SIZE_T(midpart) "%" midpart "lu"
-# elif defined(EMSCRIPTEN) // 32bit mode Emscripten
+# elif defined(__wasm32__) // 32bit mode Emscripten or WASI SDK
# define EXPAT_FMT_PTRDIFF_T(midpart) "%" midpart "ld"
# define EXPAT_FMT_SIZE_T(midpart) "%" midpart "zu"
# else
diff --git a/Modules/expat/refresh.sh b/Modules/expat/refresh.sh
index bb1a805277c..54d58d09b90 100755
--- a/Modules/expat/refresh.sh
+++ b/Modules/expat/refresh.sh
@@ -12,9 +12,9 @@ fi
# Update this when updating to a new version after verifying that the changes
# the update brings in are good. These values are used for verifying the SBOM, too.
-expected_libexpat_tag="R_2_7_3"
-expected_libexpat_version="2.7.3"
-expected_libexpat_sha256="821ac9710d2c073eaf13e1b1895a9c9aa66c1157a99635c639fbff65cdbdd732"
+expected_libexpat_tag="R_2_7_4"
+expected_libexpat_version="2.7.4"
+expected_libexpat_sha256="461ecc8aa98ab1a68c2db788175665d1a4db640dc05bf0e289b6ea17122144ec"
expat_dir="$(realpath "$(dirname -- "${BASH_SOURCE[0]}")")"
cd ${expat_dir}
@@ -24,6 +24,9 @@ curl --location "https://github.com/libexpat/libexpat/releases/download/${expect
echo "${expected_libexpat_sha256} libexpat.tar.gz" | sha256sum --check
# Step 2: Pull files from the libexpat distribution
+
+tar xzvf libexpat.tar.gz "expat-${expected_libexpat_version}/COPYING" --strip-components 2
+
declare -a lib_files
lib_files=(
ascii.h
diff --git a/Modules/expat/xmlparse.c b/Modules/expat/xmlparse.c
index a187a3a18f1..086fca59112 100644
--- a/Modules/expat/xmlparse.c
+++ b/Modules/expat/xmlparse.c
@@ -1,4 +1,4 @@
-/* 28bcd8b1ba7eb595d82822908257fd9c3589b4243e3c922d0369f35bfcd7b506 (2.7.3+)
+/* fab937ab8b186d7d296013669c332e6dfce2f99567882cff1f8eb24223c524a7 (2.7.4+)
__ __ _
___\ \/ /_ __ __ _| |_
/ _ \\ /| '_ \ / _` | __|
@@ -13,7 +13,7 @@
Copyright (c) 2002-2016 Karl Waclawek <karl@waclawek.net>
Copyright (c) 2005-2009 Steven Solie <steven@solie.ca>
Copyright (c) 2016 Eric Rahm <erahm@mozilla.com>
- Copyright (c) 2016-2025 Sebastian Pipping <sebastian@pipping.org>
+ Copyright (c) 2016-2026 Sebastian Pipping <sebastian@pipping.org>
Copyright (c) 2016 Gaurav <g.gupta@samsung.com>
Copyright (c) 2016 Thomas Beutlich <tc@tbeu.de>
Copyright (c) 2016 Gustavo Grieco <gustavo.grieco@imag.fr>
@@ -42,6 +42,9 @@
Copyright (c) 2024-2025 Berkay Eren Ürün <berkay.ueruen@siemens.com>
Copyright (c) 2024 Hanno Böck <hanno@gentoo.org>
Copyright (c) 2025 Matthew Fernandez <matthew.fernandez@gmail.com>
+ Copyright (c) 2025 Atrem Borovik <polzovatellllk@gmail.com>
+ Copyright (c) 2025 Alfonso Gregory <gfunni234@gmail.com>
+ Copyright (c) 2026 Rosen Penev <rosenp@gmail.com>
Licensed under the MIT license:
Permission is hereby granted, free of charge, to any person obtaining
@@ -101,7 +104,7 @@
#include <limits.h> /* INT_MAX, UINT_MAX */
#include <stdio.h> /* fprintf */
#include <stdlib.h> /* getenv, rand_s */
-#include <stdint.h> /* uintptr_t */
+#include <stdint.h> /* SIZE_MAX, uintptr_t */
#include <math.h> /* isnan */
#ifdef _WIN32
@@ -134,11 +137,6 @@
# endif /* defined(GRND_NONBLOCK) */
#endif /* defined(HAVE_GETRANDOM) || defined(HAVE_SYSCALL_GETRANDOM) */
-#if defined(HAVE_LIBBSD) \
- && (defined(HAVE_ARC4RANDOM_BUF) || defined(HAVE_ARC4RANDOM))
-# include <bsd/stdlib.h>
-#endif
-
#if defined(_WIN32) && ! defined(LOAD_LIBRARY_SEARCH_SYSTEM32)
# define LOAD_LIBRARY_SEARCH_SYSTEM32 0x00000800
#endif
@@ -155,8 +153,6 @@
* Linux >=3.17 + glibc (including <2.25) (syscall SYS_getrandom): HAVE_SYSCALL_GETRANDOM, \
* BSD / macOS >=10.7 / glibc >=2.36 (arc4random_buf): HAVE_ARC4RANDOM_BUF, \
* BSD / macOS (including <10.7) / glibc >=2.36 (arc4random): HAVE_ARC4RANDOM, \
- * libbsd (arc4random_buf): HAVE_ARC4RANDOM_BUF + HAVE_LIBBSD, \
- * libbsd (arc4random): HAVE_ARC4RANDOM + HAVE_LIBBSD, \
* Linux (including <3.17) / BSD / macOS (including <10.7) / Solaris >=8 (/dev/urandom): XML_DEV_URANDOM, \
* Windows >=Vista (rand_s): _WIN32. \
\
@@ -311,8 +307,11 @@ typedef struct tag {
const char *rawName; /* tagName in the original encoding */
int rawNameLength;
TAG_NAME name; /* tagName in the API encoding */
- char *buf; /* buffer for name components */
- char *bufEnd; /* end of the buffer */
+ union {
+ char *raw; /* for byte-level access (rawName storage) */
+ XML_Char *str; /* for character-level access (converted name) */
+ } buf; /* buffer for name components */
+ char *bufEnd; /* end of the buffer */
BINDING *bindings;
} TAG;
@@ -349,7 +348,7 @@ typedef struct {
typedef struct block {
struct block *next;
int size;
- XML_Char s[1];
+ XML_Char s[];
} BLOCK;
typedef struct {
@@ -1230,8 +1229,11 @@ generate_hash_secret_salt(XML_Parser parser) {
# endif /* ! defined(_WIN32) && defined(XML_DEV_URANDOM) */
/* .. and self-made low quality for backup: */
+ entropy = gather_time_entropy();
+# if ! defined(__wasi__)
/* Process ID is 0 bits entropy if attacker has local access */
- entropy = gather_time_entropy() ^ getpid();
+ entropy ^= getpid();
+# endif
/* Factors are 2^31-1 and 2^61-1 (Mersenne primes M31 and M61) */
if (sizeof(unsigned long) == 4) {
@@ -1754,6 +1756,7 @@ XML_ExternalEntityParserCreate(XML_Parser oldParser, const XML_Char *context,
XML_ExternalEntityRefHandler oldExternalEntityRefHandler;
XML_SkippedEntityHandler oldSkippedEntityHandler;
XML_UnknownEncodingHandler oldUnknownEncodingHandler;
+ void *oldUnknownEncodingHandlerData;
XML_ElementDeclHandler oldElementDeclHandler;
XML_AttlistDeclHandler oldAttlistDeclHandler;
XML_EntityDeclHandler oldEntityDeclHandler;
@@ -1799,6 +1802,7 @@ XML_ExternalEntityParserCreate(XML_Parser oldParser, const XML_Char *context,
oldExternalEntityRefHandler = parser->m_externalEntityRefHandler;
oldSkippedEntityHandler = parser->m_skippedEntityHandler;
oldUnknownEncodingHandler = parser->m_unknownEncodingHandler;
+ oldUnknownEncodingHandlerData = parser->m_unknownEncodingHandlerData;
oldElementDeclHandler = parser->m_elementDeclHandler;
oldAttlistDeclHandler = parser->m_attlistDeclHandler;
oldEntityDeclHandler = parser->m_entityDeclHandler;
@@ -1859,6 +1863,7 @@ XML_ExternalEntityParserCreate(XML_Parser oldParser, const XML_Char *context,
parser->m_externalEntityRefHandler = oldExternalEntityRefHandler;
parser->m_skippedEntityHandler = oldSkippedEntityHandler;
parser->m_unknownEncodingHandler = oldUnknownEncodingHandler;
+ parser->m_unknownEncodingHandlerData = oldUnknownEncodingHandlerData;
parser->m_elementDeclHandler = oldElementDeclHandler;
parser->m_attlistDeclHandler = oldAttlistDeclHandler;
parser->m_entityDeclHandler = oldEntityDeclHandler;
@@ -1934,7 +1939,7 @@ XML_ParserFree(XML_Parser parser) {
}
p = tagList;
tagList = tagList->parent;
- FREE(parser, p->buf);
+ FREE(parser, p->buf.raw);
destroyBindings(p->bindings, parser);
FREE(parser, p);
}
@@ -2599,7 +2604,7 @@ XML_GetBuffer(XML_Parser parser, int len) {
// NOTE: We are avoiding MALLOC(..) here to leave limiting
// the input size to the application using Expat.
newBuf = parser->m_mem.malloc_fcn(bufferSize);
- if (newBuf == 0) {
+ if (newBuf == NULL) {
parser->m_errorCode = XML_ERROR_NO_MEMORY;
return NULL;
}
@@ -3126,7 +3131,7 @@ storeRawNames(XML_Parser parser) {
size_t bufSize;
size_t nameLen = sizeof(XML_Char) * (tag->name.strLen + 1);
size_t rawNameLen;
- char *rawNameBuf = tag->buf + nameLen;
+ char *rawNameBuf = tag->buf.raw + nameLen;
/* Stop if already stored. Since m_tagStack is a stack, we can stop
at the first entry that has already been copied; everything
below it in the stack is already been accounted for in a
@@ -3142,22 +3147,22 @@ storeRawNames(XML_Parser parser) {
if (rawNameLen > (size_t)INT_MAX - nameLen)
return XML_FALSE;
bufSize = nameLen + rawNameLen;
- if (bufSize > (size_t)(tag->bufEnd - tag->buf)) {
- char *temp = REALLOC(parser, tag->buf, bufSize);
+ if (bufSize > (size_t)(tag->bufEnd - tag->buf.raw)) {
+ char *temp = REALLOC(parser, tag->buf.raw, bufSize);
if (temp == NULL)
return XML_FALSE;
- /* if tag->name.str points to tag->buf (only when namespace
+ /* if tag->name.str points to tag->buf.str (only when namespace
processing is off) then we have to update it
*/
- if (tag->name.str == (XML_Char *)tag->buf)
+ if (tag->name.str == tag->buf.str)
tag->name.str = (XML_Char *)temp;
/* if tag->name.localPart is set (when namespace processing is on)
then update it as well, since it will always point into tag->buf
*/
if (tag->name.localPart)
tag->name.localPart
- = (XML_Char *)temp + (tag->name.localPart - (XML_Char *)tag->buf);
- tag->buf = temp;
+ = (XML_Char *)temp + (tag->name.localPart - tag->buf.str);
+ tag->buf.raw = temp;
tag->bufEnd = temp + bufSize;
rawNameBuf = temp + nameLen;
}
@@ -3472,12 +3477,12 @@ doContent(XML_Parser parser, int startTagLevel, const ENCODING *enc,
tag = MALLOC(parser, sizeof(TAG));
if (! tag)
return XML_ERROR_NO_MEMORY;
- tag->buf = MALLOC(parser, INIT_TAG_BUF_SIZE);
- if (! tag->buf) {
+ tag->buf.raw = MALLOC(parser, INIT_TAG_BUF_SIZE);
+ if (! tag->buf.raw) {
FREE(parser, tag);
return XML_ERROR_NO_MEMORY;
}
- tag->bufEnd = tag->buf + INIT_TAG_BUF_SIZE;
+ tag->bufEnd = tag->buf.raw + INIT_TAG_BUF_SIZE;
}
tag->bindings = NULL;
tag->parent = parser->m_tagStack;
@@ -3490,31 +3495,32 @@ doContent(XML_Parser parser, int startTagLevel, const ENCODING *enc,
{
const char *rawNameEnd = tag->rawName + tag->rawNameLength;
const char *fromPtr = tag->rawName;
- toPtr = (XML_Char *)tag->buf;
+ toPtr = tag->buf.str;
for (;;) {
- int bufSize;
int convLen;
const enum XML_Convert_Result convert_res
= XmlConvert(enc, &fromPtr, rawNameEnd, (ICHAR **)&toPtr,
(ICHAR *)tag->bufEnd - 1);
- convLen = (int)(toPtr - (XML_Char *)tag->buf);
+ convLen = (int)(toPtr - tag->buf.str);
if ((fromPtr >= rawNameEnd)
|| (convert_res == XML_CONVERT_INPUT_INCOMPLETE)) {
tag->name.strLen = convLen;
break;
}
- bufSize = (int)(tag->bufEnd - tag->buf) << 1;
+ if (SIZE_MAX / 2 < (size_t)(tag->bufEnd - tag->buf.raw))
+ return XML_ERROR_NO_MEMORY;
+ const size_t bufSize = (size_t)(tag->bufEnd - tag->buf.raw) * 2;
{
- char *temp = REALLOC(parser, tag->buf, bufSize);
+ char *temp = REALLOC(parser, tag->buf.raw, bufSize);
if (temp == NULL)
return XML_ERROR_NO_MEMORY;
- tag->buf = temp;
+ tag->buf.raw = temp;
tag->bufEnd = temp + bufSize;
toPtr = (XML_Char *)temp + convLen;
}
}
}
- tag->name.str = (XML_Char *)tag->buf;
+ tag->name.str = tag->buf.str;
*toPtr = XML_T('\0');
result
= storeAtts(parser, enc, s, &(tag->name), &(tag->bindings), account);
@@ -3878,7 +3884,7 @@ storeAtts(XML_Parser parser, const ENCODING *enc, const char *attStr,
* from -Wtype-limits on platforms where
* sizeof(unsigned int) < sizeof(size_t), e.g. on x86_64. */
#if UINT_MAX >= SIZE_MAX
- if ((unsigned)parser->m_attsSize > (size_t)(-1) / sizeof(ATTRIBUTE)) {
+ if ((unsigned)parser->m_attsSize > SIZE_MAX / sizeof(ATTRIBUTE)) {
parser->m_attsSize = oldAttsSize;
return XML_ERROR_NO_MEMORY;
}
@@ -3897,7 +3903,7 @@ storeAtts(XML_Parser parser, const ENCODING *enc, const char *attStr,
* from -Wtype-limits on platforms where
* sizeof(unsigned int) < sizeof(size_t), e.g. on x86_64. */
# if UINT_MAX >= SIZE_MAX
- if ((unsigned)parser->m_attsSize > (size_t)(-1) / sizeof(XML_AttrInfo)) {
+ if ((unsigned)parser->m_attsSize > SIZE_MAX / sizeof(XML_AttrInfo)) {
parser->m_attsSize = oldAttsSize;
return XML_ERROR_NO_MEMORY;
}
@@ -4073,7 +4079,7 @@ storeAtts(XML_Parser parser, const ENCODING *enc, const char *attStr,
* from -Wtype-limits on platforms where
* sizeof(unsigned int) < sizeof(size_t), e.g. on x86_64. */
#if UINT_MAX >= SIZE_MAX
- if (nsAttsSize > (size_t)(-1) / sizeof(NS_ATT)) {
+ if (nsAttsSize > SIZE_MAX / sizeof(NS_ATT)) {
/* Restore actual size of memory in m_nsAtts */
parser->m_nsAttsPower = oldNsAttsPower;
return XML_ERROR_NO_MEMORY;
@@ -4256,7 +4262,7 @@ storeAtts(XML_Parser parser, const ENCODING *enc, const char *attStr,
* from -Wtype-limits on platforms where
* sizeof(unsigned int) < sizeof(size_t), e.g. on x86_64. */
#if UINT_MAX >= SIZE_MAX
- if ((unsigned)(n + EXPAND_SPARE) > (size_t)(-1) / sizeof(XML_Char)) {
+ if ((unsigned)(n + EXPAND_SPARE) > SIZE_MAX / sizeof(XML_Char)) {
return XML_ERROR_NO_MEMORY;
}
#endif
@@ -4502,7 +4508,7 @@ addBinding(XML_Parser parser, PREFIX *prefix, const ATTRIBUTE_ID *attId,
* from -Wtype-limits on platforms where
* sizeof(unsigned int) < sizeof(size_t), e.g. on x86_64. */
#if UINT_MAX >= SIZE_MAX
- if ((unsigned)(len + EXPAND_SPARE) > (size_t)(-1) / sizeof(XML_Char)) {
+ if ((unsigned)(len + EXPAND_SPARE) > SIZE_MAX / sizeof(XML_Char)) {
return XML_ERROR_NO_MEMORY;
}
#endif
@@ -4529,7 +4535,7 @@ addBinding(XML_Parser parser, PREFIX *prefix, const ATTRIBUTE_ID *attId,
* from -Wtype-limits on platforms where
* sizeof(unsigned int) < sizeof(size_t), e.g. on x86_64. */
#if UINT_MAX >= SIZE_MAX
- if ((unsigned)(len + EXPAND_SPARE) > (size_t)(-1) / sizeof(XML_Char)) {
+ if ((unsigned)(len + EXPAND_SPARE) > SIZE_MAX / sizeof(XML_Char)) {
return XML_ERROR_NO_MEMORY;
}
#endif
@@ -5920,15 +5926,18 @@ doProlog(XML_Parser parser, const ENCODING *enc, const char *s, const char *end,
* from -Wtype-limits on platforms where
* sizeof(unsigned int) < sizeof(size_t), e.g. on x86_64. */
#if UINT_MAX >= SIZE_MAX
- if (parser->m_groupSize > (size_t)(-1) / sizeof(int)) {
+ if (parser->m_groupSize > SIZE_MAX / sizeof(int)) {
+ parser->m_groupSize /= 2;
return XML_ERROR_NO_MEMORY;
}
#endif
int *const new_scaff_index = REALLOC(
parser, dtd->scaffIndex, parser->m_groupSize * sizeof(int));
- if (new_scaff_index == NULL)
+ if (new_scaff_index == NULL) {
+ parser->m_groupSize /= 2;
return XML_ERROR_NO_MEMORY;
+ }
dtd->scaffIndex = new_scaff_index;
}
} else {
@@ -7190,7 +7199,7 @@ defineAttribute(ELEMENT_TYPE *type, ATTRIBUTE_ID *attId, XML_Bool isCdata,
* from -Wtype-limits on platforms where
* sizeof(unsigned int) < sizeof(size_t), e.g. on x86_64. */
#if UINT_MAX >= SIZE_MAX
- if ((unsigned)count > (size_t)(-1) / sizeof(DEFAULT_ATTRIBUTE)) {
+ if ((unsigned)count > SIZE_MAX / sizeof(DEFAULT_ATTRIBUTE)) {
return 0;
}
#endif
@@ -7666,8 +7675,7 @@ dtdCopy(XML_Parser oldParser, DTD *newDtd, const DTD *oldDtd,
* from -Wtype-limits on platforms where
* sizeof(int) < sizeof(size_t), e.g. on x86_64. */
#if UINT_MAX >= SIZE_MAX
- if ((size_t)oldE->nDefaultAtts
- > ((size_t)(-1) / sizeof(DEFAULT_ATTRIBUTE))) {
+ if ((size_t)oldE->nDefaultAtts > SIZE_MAX / sizeof(DEFAULT_ATTRIBUTE)) {
return 0;
}
#endif
@@ -7869,7 +7877,7 @@ lookup(XML_Parser parser, HASH_TABLE *table, KEY name, size_t createSize) {
unsigned long newMask = (unsigned long)newSize - 1;
/* Detect and prevent integer overflow */
- if (newSize > (size_t)(-1) / sizeof(NAMED *)) {
+ if (newSize > SIZE_MAX / sizeof(NAMED *)) {
return NULL;
}
@@ -8105,7 +8113,7 @@ poolBytesToAllocateFor(int blockSize) {
static XML_Bool FASTCALL
poolGrow(STRING_POOL *pool) {
if (pool->freeBlocks) {
- if (pool->start == 0) {
+ if (pool->start == NULL) {
pool->blocks = pool->freeBlocks;
pool->freeBlocks = pool->freeBlocks->next;
pool->blocks->next = NULL;
@@ -8217,7 +8225,7 @@ nextScaffoldPart(XML_Parser parser) {
* from -Wtype-limits on platforms where
* sizeof(unsigned int) < sizeof(size_t), e.g. on x86_64. */
#if UINT_MAX >= SIZE_MAX
- if (parser->m_groupSize > ((size_t)(-1) / sizeof(int))) {
+ if (parser->m_groupSize > SIZE_MAX / sizeof(int)) {
return -1;
}
#endif
@@ -8244,7 +8252,7 @@ nextScaffoldPart(XML_Parser parser) {
* from -Wtype-limits on platforms where
* sizeof(unsigned int) < sizeof(size_t), e.g. on x86_64. */
#if UINT_MAX >= SIZE_MAX
- if (dtd->scaffSize > (size_t)(-1) / 2u / sizeof(CONTENT_SCAFFOLD)) {
+ if (dtd->scaffSize > SIZE_MAX / 2u / sizeof(CONTENT_SCAFFOLD)) {
return -1;
}
#endif
@@ -8294,15 +8302,15 @@ build_model(XML_Parser parser) {
* from -Wtype-limits on platforms where
* sizeof(unsigned int) < sizeof(size_t), e.g. on x86_64. */
#if UINT_MAX >= SIZE_MAX
- if (dtd->scaffCount > (size_t)(-1) / sizeof(XML_Content)) {
+ if (dtd->scaffCount > SIZE_MAX / sizeof(XML_Content)) {
return NULL;
}
- if (dtd->contentStringLen > (size_t)(-1) / sizeof(XML_Char)) {
+ if (dtd->contentStringLen > SIZE_MAX / sizeof(XML_Char)) {
return NULL;
}
#endif
if (dtd->scaffCount * sizeof(XML_Content)
- > (size_t)(-1) - dtd->contentStringLen * sizeof(XML_Char)) {
+ > SIZE_MAX - dtd->contentStringLen * sizeof(XML_Char)) {
return NULL;
}
diff --git a/Modules/expat/xmlrole.c b/Modules/expat/xmlrole.c
index 2c48bf40867..d56bee82dd2 100644
--- a/Modules/expat/xmlrole.c
+++ b/Modules/expat/xmlrole.c
@@ -16,6 +16,7 @@
Copyright (c) 2017 Rhodri James <rhodri@wildebeest.org.uk>
Copyright (c) 2019 David Loffredo <loffredo@steptools.com>
Copyright (c) 2021 Donghee Na <donghee.na@python.org>
+ Copyright (c) 2025 Alfonso Gregory <gfunni234@gmail.com>
Licensed under the MIT license:
Permission is hereby granted, free of charge, to any person obtaining
@@ -46,7 +47,6 @@
# include "winconfig.h"
#endif
-#include "expat_external.h"
#include "internal.h"
#include "xmlrole.h"
#include "ascii.h"
diff --git a/Modules/expat/xmltok.c b/Modules/expat/xmltok.c
index 95d5e84b67f..32cd5f147e9 100644
--- a/Modules/expat/xmltok.c
+++ b/Modules/expat/xmltok.c
@@ -24,6 +24,7 @@
Copyright (c) 2022 Martin Ettl <ettl.martin78@googlemail.com>
Copyright (c) 2022 Sean McBride <sean@rogue-research.com>
Copyright (c) 2023 Hanno Böck <hanno@gentoo.org>
+ Copyright (c) 2025 Alfonso Gregory <gfunni234@gmail.com>
Licensed under the MIT license:
Permission is hereby granted, free of charge, to any person obtaining
@@ -56,7 +57,6 @@
# include "winconfig.h"
#endif
-#include "expat_external.h"
#include "internal.h"
#include "xmltok.h"
#include "nametab.h"
diff --git a/Modules/expat/xmltok_ns.c b/Modules/expat/xmltok_ns.c
index fbdd3e3c7b7..810ca2c6d04 100644
--- a/Modules/expat/xmltok_ns.c
+++ b/Modules/expat/xmltok_ns.c
@@ -12,6 +12,7 @@
Copyright (c) 2002 Fred L. Drake, Jr. <fdrake@users.sourceforge.net>
Copyright (c) 2002-2006 Karl Waclawek <karl@waclawek.net>
Copyright (c) 2017-2021 Sebastian Pipping <sebastian@pipping.org>
+ Copyright (c) 2025 Alfonso Gregory <gfunni234@gmail.com>
Licensed under the MIT license:
Permission is hereby granted, free of charge, to any person obtaining
@@ -98,13 +99,13 @@ NS(findEncoding)(const ENCODING *enc, const char *ptr, const char *end) {
int i;
XmlUtf8Convert(enc, &ptr, end, &p, p + ENCODING_MAX - 1);
if (ptr != end)
- return 0;
+ return NULL;
*p = 0;
if (streqci(buf, KW_UTF_16) && enc->minBytesPerChar == 2)
return enc;
i = getEncodingIndex(buf);
if (i == UNKNOWN_ENC)
- return 0;
+ return NULL;
return NS(encodings)[i];
}
diff --git a/Modules/hmacmodule.c b/Modules/hmacmodule.c
index 8cd470f4f80..8a0b3496b1a 100644
--- a/Modules/hmacmodule.c
+++ b/Modules/hmacmodule.c
@@ -1529,7 +1529,6 @@ static void
py_hmac_hinfo_ht_free(void *hinfo)
{
py_hmac_hinfo *entry = (py_hmac_hinfo *)hinfo;
- assert(entry->display_name != NULL);
if (--(entry->refcnt) == 0) {
Py_CLEAR(entry->display_name);
PyMem_Free(hinfo);
@@ -1604,16 +1603,19 @@ py_hmac_hinfo_ht_new(void)
assert(value->display_name == NULL);
value->refcnt = 0;
-#define Py_HMAC_HINFO_LINK(KEY) \
- do { \
- int rc = py_hmac_hinfo_ht_add(table, KEY, value); \
- if (rc < 0) { \
- PyMem_Free(value); \
- goto error; \
- } \
- else if (rc == 1) { \
- value->refcnt++; \
- } \
+#define Py_HMAC_HINFO_LINK(KEY) \
+ do { \
+ int rc = py_hmac_hinfo_ht_add(table, (KEY), value); \
+ if (rc < 0) { \
+ /* entry may already be in ht, freed upon exit */ \
+ if (value->refcnt == 0) { \
+ PyMem_Free(value); \
+ } \
+ goto error; \
+ } \
+ else if (rc == 1) { \
+ value->refcnt++; \
+ } \
} while (0)
Py_HMAC_HINFO_LINK(e->name);
Py_HMAC_HINFO_LINK(e->hashlib_name);
@@ -1625,7 +1627,8 @@ py_hmac_hinfo_ht_new(void)
e->hashlib_name == NULL ? e->name : e->hashlib_name
);
if (value->display_name == NULL) {
- PyMem_Free(value);
+ /* 'value' is owned by the table (refcnt > 0),
+ so _Py_hashtable_destroy() will free it. */
goto error;
}
}
diff --git a/Modules/itertoolsmodule.c b/Modules/itertoolsmodule.c
index a48d2fe76d0..fd03fae03f9 100644
--- a/Modules/itertoolsmodule.c
+++ b/Modules/itertoolsmodule.c
@@ -544,9 +544,19 @@ groupby_next(PyObject *op)
else if (gbo->tgtkey == NULL)
break;
else {
- int rcmp;
+ /* A user-defined __eq__ can re-enter groupby and advance the iterator,
+ mutating gbo->tgtkey / gbo->currkey while we are comparing them.
+ Take local snapshots and hold strong references so INCREF/DECREF
+ apply to the same objects even under re-entrancy. */
+ PyObject *tgtkey = gbo->tgtkey;
+ PyObject *currkey = gbo->currkey;
+
+ Py_INCREF(tgtkey);
+ Py_INCREF(currkey);
+ int rcmp = PyObject_RichCompareBool(tgtkey, currkey, Py_EQ);
+ Py_DECREF(tgtkey);
+ Py_DECREF(currkey);
- rcmp = PyObject_RichCompareBool(gbo->tgtkey, gbo->currkey, Py_EQ);
if (rcmp == -1)
return NULL;
else if (rcmp == 0)
diff --git a/Modules/main.c b/Modules/main.c
index 9b2ee103d52..15f51acbcf5 100644
--- a/Modules/main.c
+++ b/Modules/main.c
@@ -509,6 +509,7 @@ pymain_run_interactive_hook(int *exitcode)
}
if (PySys_Audit("cpython.run_interactivehook", "O", hook) < 0) {
+ Py_DECREF(hook);
goto error;
}
diff --git a/Modules/md5module.c b/Modules/md5module.c
index 9b5ea2d6e02..f3855ec3f37 100644
--- a/Modules/md5module.c
+++ b/Modules/md5module.c
@@ -87,7 +87,10 @@ static void
MD5_dealloc(PyObject *op)
{
MD5object *ptr = _MD5object_CAST(op);
- Hacl_Hash_MD5_free(ptr->hash_state);
+ if (ptr->hash_state != NULL) {
+ Hacl_Hash_MD5_free(ptr->hash_state);
+ ptr->hash_state = NULL;
+ }
PyTypeObject *tp = Py_TYPE(op);
PyObject_GC_UnTrack(ptr);
PyObject_GC_Del(ptr);
diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c
index cb3a62d211a..bb9ef0e6da6 100644
--- a/Modules/posixmodule.c
+++ b/Modules/posixmodule.c
@@ -1251,6 +1251,8 @@ get_posix_state(PyObject *module)
* Contains a file descriptor if path.accept_fd was true
* and the caller provided a signed integer instead of any
* sort of string.
+ * path.is_fd
+ * True if path was provided as a file descriptor.
*
* WARNING: if your "path" parameter is optional, and is
* unspecified, path_converter will never get called.
@@ -1303,6 +1305,7 @@ typedef struct {
const wchar_t *wide;
const char *narrow;
int fd;
+ bool is_fd;
int value_error;
Py_ssize_t length;
PyObject *object;
@@ -1312,7 +1315,7 @@ typedef struct {
#define PATH_T_INITIALIZE(function_name, argument_name, nullable, nonstrict, \
make_wide, suppress_value_error, allow_fd) \
{function_name, argument_name, nullable, nonstrict, make_wide, \
- suppress_value_error, allow_fd, NULL, NULL, -1, 0, 0, NULL, NULL}
+ suppress_value_error, allow_fd, NULL, NULL, -1, false, 0, 0, NULL, NULL}
#ifdef MS_WINDOWS
#define PATH_T_INITIALIZE_P(function_name, argument_name, nullable, \
nonstrict, suppress_value_error, allow_fd) \
@@ -1446,6 +1449,7 @@ path_converter(PyObject *o, void *p)
}
path->wide = NULL;
path->narrow = NULL;
+ path->is_fd = true;
goto success_exit;
}
else {
@@ -7155,6 +7159,7 @@ parse_posix_spawn_flags(PyObject *module, const char *func_name, PyObject *setpg
PyObject *setsigdef, PyObject *scheduler,
posix_spawnattr_t *attrp)
{
+ assert(scheduler == NULL || scheduler == Py_None || PyTuple_Check(scheduler));
long all_flags = 0;
errno = posix_spawnattr_init(attrp);
@@ -7163,7 +7168,7 @@ parse_posix_spawn_flags(PyObject *module, const char *func_name, PyObject *setpg
return -1;
}
- if (setpgroup) {
+ if (setpgroup && setpgroup != Py_None) {
pid_t pgid = PyLong_AsPid(setpgroup);
if (pgid == (pid_t)-1 && PyErr_Occurred()) {
goto fail;
@@ -7236,7 +7241,7 @@ parse_posix_spawn_flags(PyObject *module, const char *func_name, PyObject *setpg
}
#endif
- if (scheduler) {
+ if (scheduler && scheduler != Py_None) {
#ifdef POSIX_SPAWN_SETSCHEDULER
PyObject *py_schedpolicy;
PyObject *schedparam_obj;
@@ -7461,6 +7466,12 @@ py_posix_spawn(int use_posix_spawnp, PyObject *module, path_t *path, PyObject *a
goto exit;
}
+ if (scheduler && !PyTuple_Check(scheduler) && scheduler != Py_None) {
+ PyErr_Format(PyExc_TypeError,
+ "%s: scheduler must be a tuple or None", func_name);
+ goto exit;
+ }
+
argvlist = parse_arglist(argv, &argc);
if (argvlist == NULL) {
goto exit;
@@ -7572,7 +7583,7 @@ os.posix_spawn
*
file_actions: object(c_default='NULL') = ()
A sequence of file action tuples.
- setpgroup: object = NULL
+ setpgroup: object(c_default='NULL') = None
The pgroup to use with the POSIX_SPAWN_SETPGROUP flag.
resetids: bool = False
If the value is `true` the POSIX_SPAWN_RESETIDS will be activated.
@@ -7582,7 +7593,7 @@ os.posix_spawn
The sigmask to use with the POSIX_SPAWN_SETSIGMASK flag.
setsigdef: object(c_default='NULL') = ()
The sigmask to use with the POSIX_SPAWN_SETSIGDEF flag.
- scheduler: object = NULL
+ scheduler: object(c_default='NULL') = None
A tuple with the scheduler policy (optional) and parameters.
Execute the program specified by path in a new process.
@@ -7594,7 +7605,7 @@ os_posix_spawn_impl(PyObject *module, path_t *path, PyObject *argv,
PyObject *setpgroup, int resetids, int setsid,
PyObject *setsigmask, PyObject *setsigdef,
PyObject *scheduler)
-/*[clinic end generated code: output=14a1098c566bc675 input=808aed1090d84e33]*/
+/*[clinic end generated code: output=14a1098c566bc675 input=69e7c9ebbdcf94a5]*/
{
return py_posix_spawn(0, module, path, argv, env, file_actions,
setpgroup, resetids, setsid, setsigmask, setsigdef,
@@ -7618,7 +7629,7 @@ os.posix_spawnp
*
file_actions: object(c_default='NULL') = ()
A sequence of file action tuples.
- setpgroup: object = NULL
+ setpgroup: object(c_default='NULL') = None
The pgroup to use with the POSIX_SPAWN_SETPGROUP flag.
resetids: bool = False
If the value is `True` the POSIX_SPAWN_RESETIDS will be activated.
@@ -7628,7 +7639,7 @@ os.posix_spawnp
The sigmask to use with the POSIX_SPAWN_SETSIGMASK flag.
setsigdef: object(c_default='NULL') = ()
The sigmask to use with the POSIX_SPAWN_SETSIGDEF flag.
- scheduler: object = NULL
+ scheduler: object(c_default='NULL') = None
A tuple with the scheduler policy (optional) and parameters.
Execute the program specified by path in a new process.
@@ -7640,7 +7651,7 @@ os_posix_spawnp_impl(PyObject *module, path_t *path, PyObject *argv,
PyObject *setpgroup, int resetids, int setsid,
PyObject *setsigmask, PyObject *setsigdef,
PyObject *scheduler)
-/*[clinic end generated code: output=7b9aaefe3031238d input=9e89e616116752a1]*/
+/*[clinic end generated code: output=7b9aaefe3031238d input=a5c057527c6881a5]*/
{
return py_posix_spawn(1, module, path, argv, env, file_actions,
setpgroup, resetids, setsid, setsigmask, setsigdef,
@@ -13834,8 +13845,9 @@ os_pathconf_impl(PyObject *module, path_t *path, int name)
errno = 0;
#ifdef HAVE_FPATHCONF
- if (path->fd != -1)
+ if (path->is_fd) {
limit = fpathconf(path->fd, name);
+ }
else
#endif
limit = pathconf(path->narrow, name);
diff --git a/Modules/socketmodule.c b/Modules/socketmodule.c
index 8c8a5efa8c9..563a930bbcd 100644
--- a/Modules/socketmodule.c
+++ b/Modules/socketmodule.c
@@ -4952,11 +4952,13 @@ sock_sendmsg(PyObject *self, PyObject *args)
if (cmsg_arg == NULL)
ncmsgs = 0;
else {
- if ((cmsg_fast = PySequence_Fast(cmsg_arg,
- "sendmsg() argument 2 must be an "
- "iterable")) == NULL)
+ cmsg_fast = PySequence_Tuple(cmsg_arg);
+ if (cmsg_fast == NULL) {
+ PyErr_SetString(PyExc_TypeError,
+ "sendmsg() argument 2 must be an iterable");
goto finally;
- ncmsgs = PySequence_Fast_GET_SIZE(cmsg_fast);
+ }
+ ncmsgs = PyTuple_GET_SIZE(cmsg_fast);
}
#ifndef CMSG_SPACE
@@ -4976,8 +4978,9 @@ sock_sendmsg(PyObject *self, PyObject *args)
controllen = controllen_last = 0;
while (ncmsgbufs < ncmsgs) {
size_t bufsize, space;
+ PyObject *item = PyTuple_GET_ITEM(cmsg_fast, ncmsgbufs);
- if (!PyArg_Parse(PySequence_Fast_GET_ITEM(cmsg_fast, ncmsgbufs),
+ if (!PyArg_Parse(item,
"(iiy*):[sendmsg() ancillary data items]",
&cmsgs[ncmsgbufs].level,
&cmsgs[ncmsgbufs].type,
diff --git a/Modules/unicodedata.c b/Modules/unicodedata.c
index ef8cf3d0d27..83de1be56a7 100644
--- a/Modules/unicodedata.c
+++ b/Modules/unicodedata.c
@@ -230,9 +230,9 @@ unicodedata_UCD_numeric_impl(PyObject *self, int chr,
have_old = 1;
rc = -1.0;
}
- else if (old->decimal_changed != 0xFF) {
+ else if (old->numeric_changed != 0.0) {
have_old = 1;
- rc = old->decimal_changed;
+ rc = old->numeric_changed;
}
}
@@ -388,6 +388,17 @@ unicodedata_UCD_east_asian_width_impl(PyObject *self, int chr)
return PyUnicode_FromString(_PyUnicode_EastAsianWidthNames[index]);
}
+// For Hangul decomposition
+#define SBase 0xAC00
+#define LBase 0x1100
+#define VBase 0x1161
+#define TBase 0x11A7
+#define LCount 19
+#define VCount 21
+#define TCount 28
+#define NCount (VCount*TCount)
+#define SCount (LCount*NCount)
+
/*[clinic input]
unicodedata.UCD.decomposition
@@ -418,6 +429,25 @@ unicodedata_UCD_decomposition_impl(PyObject *self, int chr)
return Py_GetConstant(Py_CONSTANT_EMPTY_STR); /* unassigned */
}
+ // Hangul Decomposition.
+ // See section 3.12.2, "Hangul Syllable Decomposition"
+ // https://www.unicode.org/versions/latest/core-spec/chapter-3/#G56669
+ if (SBase <= code && code < (SBase + SCount)) {
+ int SIndex = code - SBase;
+ int L = LBase + SIndex / NCount;
+ int V = VBase + (SIndex % NCount) / TCount;
+ int T = TBase + SIndex % TCount;
+ if (T != TBase) {
+ PyOS_snprintf(decomp, sizeof(decomp),
+ "%04X %04X %04X", L, V, T);
+ }
+ else {
+ PyOS_snprintf(decomp, sizeof(decomp),
+ "%04X %04X", L, V);
+ }
+ return PyUnicode_FromString(decomp);
+ }
+
if (code < 0 || code >= 0x110000)
index = 0;
else {
@@ -480,16 +510,6 @@ get_decomp_record(PyObject *self, Py_UCS4 code,
(*index)++;
}
-#define SBase 0xAC00
-#define LBase 0x1100
-#define VBase 0x1161
-#define TBase 0x11A7
-#define LCount 19
-#define VCount 21
-#define TCount 28
-#define NCount (VCount*TCount)
-#define SCount (LCount*NCount)
-
static PyObject*
nfd_nfkd(PyObject *self, PyObject *input, int k)
{
@@ -543,7 +563,9 @@ nfd_nfkd(PyObject *self, PyObject *input, int k)
}
output = new_output;
}
- /* Hangul Decomposition. */
+ // Hangul Decomposition.
+ // See section 3.12.2, "Hangul Syllable Decomposition"
+ // https://www.unicode.org/versions/latest/core-spec/chapter-3/#G56669
if (SBase <= code && code < (SBase+SCount)) {
int SIndex = code - SBase;
int L = LBase + SIndex / NCount;
@@ -1010,21 +1032,18 @@ static const char * const hangul_syllables[][3] = {
{ 0, 0, "H" }
};
-/* These ranges need to match makeunicodedata.py:cjk_ranges. */
static int
-is_unified_ideograph(Py_UCS4 code)
+find_prefix_id(Py_UCS4 code)
{
- return
- (0x3400 <= code && code <= 0x4DBF) || /* CJK Ideograph Extension A */
- (0x4E00 <= code && code <= 0x9FFF) || /* CJK Ideograph */
- (0x20000 <= code && code <= 0x2A6DF) || /* CJK Ideograph Extension B */
- (0x2A700 <= code && code <= 0x2B739) || /* CJK Ideograph Extension C */
- (0x2B740 <= code && code <= 0x2B81D) || /* CJK Ideograph Extension D */
- (0x2B820 <= code && code <= 0x2CEA1) || /* CJK Ideograph Extension E */
- (0x2CEB0 <= code && code <= 0x2EBE0) || /* CJK Ideograph Extension F */
- (0x2EBF0 <= code && code <= 0x2EE5D) || /* CJK Ideograph Extension I */
- (0x30000 <= code && code <= 0x3134A) || /* CJK Ideograph Extension G */
- (0x31350 <= code && code <= 0x323AF); /* CJK Ideograph Extension H */
+ for (int i = 0; i < (int)Py_ARRAY_LENGTH(derived_name_ranges); i++) {
+ if (code < derived_name_ranges[i].first) {
+ return -1;
+ }
+ if (code <= derived_name_ranges[i].last) {
+ return derived_name_ranges[i].prefixid;
+ }
+ }
+ return -1;
}
/* macros used to determine if the given code point is in the PUA range that
@@ -1302,7 +1321,9 @@ _getucname(PyObject *self,
}
}
- if (SBase <= code && code < SBase+SCount) {
+ int prefixid = find_prefix_id(code);
+ if (prefixid == 0) {
+ assert(SBase <= code && code < SBase+SCount);
/* Hangul syllable. */
int SIndex = code - SBase;
int L = SIndex / NCount;
@@ -1324,11 +1345,13 @@ _getucname(PyObject *self,
return 1;
}
- if (is_unified_ideograph(code)) {
- if (buflen < 28)
- /* Worst case: CJK UNIFIED IDEOGRAPH-20000 */
+ /* Only support CJK unified ideographs.
+ * Support for Tangut ideographs is a new feature in 3.15. */
+ if (prefixid == 1) {
+ const char *prefix = derived_name_prefixes[prefixid];
+ if (snprintf(buffer, buflen, "%s%04X", prefix, code) >= buflen) {
return 0;
- sprintf(buffer, "CJK UNIFIED IDEOGRAPH-%X", code);
+ }
return 1;
}
@@ -1362,7 +1385,7 @@ find_syllable(const char *str, int *len, int *pos, int count, int column)
len1 = Py_SAFE_DOWNCAST(strlen(s), size_t, int);
if (len1 <= *len)
continue;
- if (strncmp(str, s, len1) == 0) {
+ if (PyOS_strnicmp(str, s, len1) == 0) {
*len = len1;
*pos = i;
}
@@ -1385,6 +1408,35 @@ _check_alias_and_seq(Py_UCS4* code, int with_named_seq)
return 1;
}
+static Py_UCS4
+parse_hex_code(const char *name, int namelen)
+{
+ if (namelen < 4 || namelen > 6) {
+ return (Py_UCS4)-1;
+ }
+ if (*name == '0') {
+ return (Py_UCS4)-1;
+ }
+ int v = 0;
+ while (namelen--) {
+ v *= 16;
+ Py_UCS1 c = Py_TOUPPER(*name);
+ if (c >= '0' && c <= '9') {
+ v += c - '0';
+ }
+ else if (c >= 'A' && c <= 'F') {
+ v += c - 'A' + 10;
+ }
+ else {
+ return (Py_UCS4)-1;
+ }
+ name++;
+ }
+ if (v > 0x10ffff) {
+ return (Py_UCS4)-1;
+ }
+ return v;
+}
static int
_getcode(const char* name, int namelen, Py_UCS4* code)
@@ -1393,8 +1445,19 @@ _getcode(const char* name, int namelen, Py_UCS4* code)
* Named aliases are not resolved, they are returned as a code point in the
* PUA */
- /* Check for hangul syllables. */
- if (strncmp(name, "HANGUL SYLLABLE ", 16) == 0) {
+ int i = 0;
+ size_t prefixlen;
+ for (; i < (int)Py_ARRAY_LENGTH(derived_name_prefixes); i++) {
+ const char *prefix = derived_name_prefixes[i];
+ prefixlen = strlen(derived_name_prefixes[i]);
+ if (PyOS_strnicmp(name, prefix, prefixlen) == 0) {
+ break;
+ }
+ }
+
+ if (i == 0) {
+ /* Hangul syllables. */
+ assert(PyOS_strnicmp(name, "HANGUL SYLLABLE ", 16) == 0);
int len, L = -1, V = -1, T = -1;
const char *pos = name + 16;
find_syllable(pos, &len, &L, LCount, 0);
@@ -1411,27 +1474,11 @@ _getcode(const char* name, int namelen, Py_UCS4* code)
return 0;
}
- /* Check for unified ideographs. */
- if (strncmp(name, "CJK UNIFIED IDEOGRAPH-", 22) == 0) {
- /* Four or five hexdigits must follow. */
- unsigned int v;
- v = 0;
- name += 22;
- namelen -= 22;
- if (namelen != 4 && namelen != 5)
+ if (i < (int)Py_ARRAY_LENGTH(derived_name_prefixes)) {
+ Py_UCS4 v = parse_hex_code(name + prefixlen, namelen - prefixlen);
+ if (find_prefix_id(v) != i) {
return 0;
- while (namelen--) {
- v *= 16;
- if (*name >= '0' && *name <= '9')
- v += *name - '0';
- else if (*name >= 'A' && *name <= 'F')
- v += *name - 'A' + 10;
- else
- return 0;
- name++;
}
- if (!is_unified_ideograph(v))
- return 0;
*code = v;
return 1;
}
diff --git a/Modules/unicodename_db.h b/Modules/unicodename_db.h
index 0697e259b39..acc85cb0b4e 100644
--- a/Modules/unicodename_db.h
+++ b/Modules/unicodename_db.h
@@ -19473,3 +19473,30 @@ static const named_sequence named_sequences[] = {
{2, {0x02E5, 0x02E9}},
{2, {0x02E9, 0x02E5}},
};
+
+typedef struct {
+ Py_UCS4 first;
+ Py_UCS4 last;
+ int prefixid;
+} derived_name_range;
+
+static const derived_name_range derived_name_ranges[] = {
+ {0x3400, 0x4DBF, 1},
+ {0x4E00, 0x9FFF, 1},
+ {0xAC00, 0xD7A3, 0},
+ {0x17000, 0x187F7, 2},
+ {0x18D00, 0x18D08, 2},
+ {0x20000, 0x2A6DF, 1},
+ {0x2A700, 0x2B739, 1},
+ {0x2B740, 0x2B81D, 1},
+ {0x2B820, 0x2CEA1, 1},
+ {0x2CEB0, 0x2EBE0, 1},
+ {0x2EBF0, 0x2EE5D, 1},
+ {0x30000, 0x3134A, 1},
+ {0x31350, 0x323AF, 1},
+};
+static const char * const derived_name_prefixes[] = {
+ "HANGUL SYLLABLE ",
+ "CJK UNIFIED IDEOGRAPH-",
+ "TANGUT IDEOGRAPH-",
+};
diff --git a/Objects/codeobject.c b/Objects/codeobject.c
index 287558302aa..f0b2e5f36c6 100644
--- a/Objects/codeobject.c
+++ b/Objects/codeobject.c
@@ -1582,6 +1582,67 @@ typedef struct {
} _PyCodeObjectExtra;
+static inline size_t
+code_extra_size(Py_ssize_t n)
+{
+ return sizeof(_PyCodeObjectExtra) + (n - 1) * sizeof(void *);
+}
+
+#ifdef Py_GIL_DISABLED
+static int
+code_extra_grow_ft(PyCodeObject *co, _PyCodeObjectExtra *old_co_extra,
+ Py_ssize_t old_ce_size, Py_ssize_t new_ce_size,
+ Py_ssize_t index, void *extra)
+{
+ _Py_CRITICAL_SECTION_ASSERT_OBJECT_LOCKED(co);
+ _PyCodeObjectExtra *new_co_extra = PyMem_Malloc(
+ code_extra_size(new_ce_size));
+ if (new_co_extra == NULL) {
+ PyErr_NoMemory();
+ return -1;
+ }
+
+ if (old_ce_size > 0) {
+ memcpy(new_co_extra->ce_extras, old_co_extra->ce_extras,
+ old_ce_size * sizeof(void *));
+ }
+ for (Py_ssize_t i = old_ce_size; i < new_ce_size; i++) {
+ new_co_extra->ce_extras[i] = NULL;
+ }
+ new_co_extra->ce_size = new_ce_size;
+ new_co_extra->ce_extras[index] = extra;
+
+ // Publish new buffer and its contents to lock-free readers.
+ FT_ATOMIC_STORE_PTR_RELEASE(co->co_extra, new_co_extra);
+ if (old_co_extra != NULL) {
+ // QSBR: defer old-buffer free until lock-free readers quiesce.
+ _PyMem_FreeDelayed(old_co_extra, code_extra_size(old_ce_size));
+ }
+ return 0;
+}
+#else
+static int
+code_extra_grow_gil(PyCodeObject *co, _PyCodeObjectExtra *old_co_extra,
+ Py_ssize_t old_ce_size, Py_ssize_t new_ce_size,
+ Py_ssize_t index, void *extra)
+{
+ _PyCodeObjectExtra *new_co_extra = PyMem_Realloc(
+ old_co_extra, code_extra_size(new_ce_size));
+ if (new_co_extra == NULL) {
+ PyErr_NoMemory();
+ return -1;
+ }
+
+ for (Py_ssize_t i = old_ce_size; i < new_ce_size; i++) {
+ new_co_extra->ce_extras[i] = NULL;
+ }
+ new_co_extra->ce_size = new_ce_size;
+ new_co_extra->ce_extras[index] = extra;
+ co->co_extra = new_co_extra;
+ return 0;
+}
+#endif
+
int
PyUnstable_Code_GetExtra(PyObject *code, Py_ssize_t index, void **extra)
{
@@ -1590,15 +1651,19 @@ PyUnstable_Code_GetExtra(PyObject *code, Py_ssize_t index, void **extra)
return -1;
}
- PyCodeObject *o = (PyCodeObject*) code;
- _PyCodeObjectExtra *co_extra = (_PyCodeObjectExtra*) o->co_extra;
+ PyCodeObject *co = (PyCodeObject *)code;
+ *extra = NULL;
- if (co_extra == NULL || index < 0 || co_extra->ce_size <= index) {
- *extra = NULL;
+ if (index < 0) {
return 0;
}
- *extra = co_extra->ce_extras[index];
+ // Lock-free read; pairs with release stores in SetExtra.
+ _PyCodeObjectExtra *co_extra = FT_ATOMIC_LOAD_PTR_ACQUIRE(co->co_extra);
+ if (co_extra != NULL && index < co_extra->ce_size) {
+ *extra = FT_ATOMIC_LOAD_PTR_ACQUIRE(co_extra->ce_extras[index]);
+ }
+
return 0;
}
@@ -1608,40 +1673,59 @@ PyUnstable_Code_SetExtra(PyObject *code, Py_ssize_t index, void *extra)
{
PyInterpreterState *interp = _PyInterpreterState_GET();
- if (!PyCode_Check(code) || index < 0 ||
- index >= interp->co_extra_user_count) {
+ // co_extra_user_count is monotonically increasing and published with
+ // release store in RequestCodeExtraIndex, so once an index is valid
+ // it stays valid.
+ Py_ssize_t user_count = FT_ATOMIC_LOAD_SSIZE_ACQUIRE(
+ interp->co_extra_user_count);
+
+ if (!PyCode_Check(code) || index < 0 || index >= user_count) {
PyErr_BadInternalCall();
return -1;
}
- PyCodeObject *o = (PyCodeObject*) code;
- _PyCodeObjectExtra *co_extra = (_PyCodeObjectExtra *) o->co_extra;
+ PyCodeObject *co = (PyCodeObject *)code;
+ int result = 0;
+ void *old_slot_value = NULL;
- if (co_extra == NULL || co_extra->ce_size <= index) {
- Py_ssize_t i = (co_extra == NULL ? 0 : co_extra->ce_size);
- co_extra = PyMem_Realloc(
- co_extra,
- sizeof(_PyCodeObjectExtra) +
- (interp->co_extra_user_count-1) * sizeof(void*));
- if (co_extra == NULL) {
- return -1;
- }
- for (; i < interp->co_extra_user_count; i++) {
- co_extra->ce_extras[i] = NULL;
- }
- co_extra->ce_size = interp->co_extra_user_count;
- o->co_extra = co_extra;
+ Py_BEGIN_CRITICAL_SECTION(co);
+
+ _PyCodeObjectExtra *old_co_extra = (_PyCodeObjectExtra *)co->co_extra;
+ Py_ssize_t old_ce_size = (old_co_extra == NULL)
+ ? 0 : old_co_extra->ce_size;
+
+ // Fast path: slot already exists, update in place.
+ if (index < old_ce_size) {
+ old_slot_value = old_co_extra->ce_extras[index];
+ FT_ATOMIC_STORE_PTR_RELEASE(old_co_extra->ce_extras[index], extra);
+ goto done;
}
- if (co_extra->ce_extras[index] != NULL) {
- freefunc free = interp->co_extra_freefuncs[index];
- if (free != NULL) {
- free(co_extra->ce_extras[index]);
+ // Slow path: buffer needs to grow.
+ Py_ssize_t new_ce_size = user_count;
+#ifdef Py_GIL_DISABLED
+ // FT build: allocate new buffer and swap; QSBR reclaims the old one.
+ result = code_extra_grow_ft(
+ co, old_co_extra, old_ce_size, new_ce_size, index, extra);
+#else
+ // GIL build: grow with realloc.
+ result = code_extra_grow_gil(
+ co, old_co_extra, old_ce_size, new_ce_size, index, extra);
+#endif
+
+done:;
+ Py_END_CRITICAL_SECTION();
+ if (old_slot_value != NULL) {
+ // Free the old slot value if a free function was registered.
+ // The caller must ensure no other thread can still access the old
+ // value after this overwrite.
+ freefunc free_extra = interp->co_extra_freefuncs[index];
+ if (free_extra != NULL) {
+ free_extra(old_slot_value);
}
}
- co_extra->ce_extras[index] = extra;
- return 0;
+ return result;
}
diff --git a/Objects/dictobject.c b/Objects/dictobject.c
index c2223af9500..b41d2548bec 100644
--- a/Objects/dictobject.c
+++ b/Objects/dictobject.c
@@ -2878,6 +2878,21 @@ _PyDict_DelItemIf(PyObject *op, PyObject *key,
return res;
}
+static void
+clear_embedded_values(PyDictValues *values, Py_ssize_t nentries)
+{
+ PyObject *refs[SHARED_KEYS_MAX_SIZE];
+ assert(nentries <= SHARED_KEYS_MAX_SIZE);
+ for (Py_ssize_t i = 0; i < nentries; i++) {
+ refs[i] = values->values[i];
+ values->values[i] = NULL;
+ }
+ values->size = 0;
+ for (Py_ssize_t i = 0; i < nentries; i++) {
+ Py_XDECREF(refs[i]);
+ }
+}
+
static void
clear_lock_held(PyObject *op)
{
@@ -2907,20 +2922,18 @@ clear_lock_held(PyObject *op)
assert(oldkeys->dk_refcnt == 1);
dictkeys_decref(interp, oldkeys, IS_DICT_SHARED(mp));
}
+ else if (oldvalues->embedded) {
+ clear_embedded_values(oldvalues, oldkeys->dk_nentries);
+ }
else {
+ set_values(mp, NULL);
+ set_keys(mp, Py_EMPTY_KEYS);
n = oldkeys->dk_nentries;
for (i = 0; i < n; i++) {
Py_CLEAR(oldvalues->values[i]);
}
- if (oldvalues->embedded) {
- oldvalues->size = 0;
- }
- else {
- set_values(mp, NULL);
- set_keys(mp, Py_EMPTY_KEYS);
- free_values(oldvalues, IS_DICT_SHARED(mp));
- dictkeys_decref(interp, oldkeys, false);
- }
+ free_values(oldvalues, IS_DICT_SHARED(mp));
+ dictkeys_decref(interp, oldkeys, false);
}
ASSERT_CONSISTENT(mp);
}
@@ -4611,10 +4624,8 @@ dict_traverse(PyObject *op, visitproc visit, void *arg)
if (DK_IS_UNICODE(keys)) {
if (_PyDict_HasSplitTable(mp)) {
- if (!mp->ma_values->embedded) {
- for (i = 0; i < n; i++) {
- Py_VISIT(mp->ma_values->values[i]);
- }
+ for (i = 0; i < n; i++) {
+ Py_VISIT(mp->ma_values->values[i]);
}
}
else {
@@ -7175,16 +7186,21 @@ PyObject_VisitManagedDict(PyObject *obj, visitproc visit, void *arg)
if((tp->tp_flags & Py_TPFLAGS_MANAGED_DICT) == 0) {
return 0;
}
- if (tp->tp_flags & Py_TPFLAGS_INLINE_VALUES) {
+ PyDictObject *dict = _PyObject_ManagedDictPointer(obj)->dict;
+ if (dict != NULL) {
+ // GH-130327: If there's a managed dictionary available, we should
+ // *always* traverse it. The dict is responsible for traversing the
+ // inline values if it points to them.
+ Py_VISIT(dict);
+ }
+ else if (tp->tp_flags & Py_TPFLAGS_INLINE_VALUES) {
PyDictValues *values = _PyObject_InlineValues(obj);
if (values->valid) {
for (Py_ssize_t i = 0; i < values->capacity; i++) {
Py_VISIT(values->values[i]);
}
- return 0;
}
}
- Py_VISIT(_PyObject_ManagedDictPointer(obj)->dict);
return 0;
}
diff --git a/Objects/frameobject.c b/Objects/frameobject.c
index 944e98e062d..7c2773085f4 100644
--- a/Objects/frameobject.c
+++ b/Objects/frameobject.c
@@ -1036,11 +1036,11 @@ static PyObject *
frame_lasti_get_impl(PyFrameObject *self)
/*[clinic end generated code: output=03275b4f0327d1a2 input=0225ed49cb1fbeeb]*/
{
- int lasti = _PyInterpreterFrame_LASTI(self->f_frame);
+ int lasti = PyUnstable_InterpreterFrame_GetLasti(self->f_frame);
if (lasti < 0) {
return PyLong_FromLong(-1);
}
- return PyLong_FromLong(lasti * sizeof(_Py_CODEUNIT));
+ return PyLong_FromLong(lasti);
}
/*[clinic input]
@@ -2044,11 +2044,15 @@ static PyObject *
frame_repr(PyObject *op)
{
PyFrameObject *f = PyFrameObject_CAST(op);
+ PyObject *result;
+ Py_BEGIN_CRITICAL_SECTION(f);
int lineno = PyFrame_GetLineNumber(f);
PyCodeObject *code = _PyFrame_GetCode(f->f_frame);
- return PyUnicode_FromFormat(
+ result = PyUnicode_FromFormat(
"<frame at %p, file %R, line %d, code %S>",
f, code->co_filename, lineno, code->co_name);
+ Py_END_CRITICAL_SECTION();
+ return result;
}
static PyMethodDef frame_methods[] = {
diff --git a/Objects/funcobject.c b/Objects/funcobject.c
index 9532c21fc70..b870106479a 100644
--- a/Objects/funcobject.c
+++ b/Objects/funcobject.c
@@ -1470,6 +1470,18 @@ cm_descr_get(PyObject *self, PyObject *obj, PyObject *type)
return PyMethod_New(cm->cm_callable, type);
}
+static PyObject *
+cm_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
+{
+ classmethod *cm = (classmethod *)PyType_GenericAlloc(type, 0);
+ if (cm == NULL) {
+ return NULL;
+ }
+ cm->cm_callable = Py_None;
+ cm->cm_dict = NULL;
+ return (PyObject *)cm;
+}
+
static int
cm_init(PyObject *self, PyObject *args, PyObject *kwds)
{
@@ -1616,7 +1628,7 @@ PyTypeObject PyClassMethod_Type = {
offsetof(classmethod, cm_dict), /* tp_dictoffset */
cm_init, /* tp_init */
PyType_GenericAlloc, /* tp_alloc */
- PyType_GenericNew, /* tp_new */
+ cm_new, /* tp_new */
PyObject_GC_Del, /* tp_free */
};
@@ -1701,6 +1713,18 @@ sm_descr_get(PyObject *self, PyObject *obj, PyObject *type)
return Py_NewRef(sm->sm_callable);
}
+static PyObject *
+sm_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
+{
+ staticmethod *sm = (staticmethod *)PyType_GenericAlloc(type, 0);
+ if (sm == NULL) {
+ return NULL;
+ }
+ sm->sm_callable = Py_None;
+ sm->sm_dict = NULL;
+ return (PyObject *)sm;
+}
+
static int
sm_init(PyObject *self, PyObject *args, PyObject *kwds)
{
@@ -1851,7 +1875,7 @@ PyTypeObject PyStaticMethod_Type = {
offsetof(staticmethod, sm_dict), /* tp_dictoffset */
sm_init, /* tp_init */
PyType_GenericAlloc, /* tp_alloc */
- PyType_GenericNew, /* tp_new */
+ sm_new, /* tp_new */
PyObject_GC_Del, /* tp_free */
};
diff --git a/Objects/mimalloc/heap.c b/Objects/mimalloc/heap.c
index d92dc768e5e..5fbfb82baa0 100644
--- a/Objects/mimalloc/heap.c
+++ b/Objects/mimalloc/heap.c
@@ -100,7 +100,10 @@ static bool mi_heap_page_collect(mi_heap_t* heap, mi_page_queue_t* pq, mi_page_t
// note: this will free retired pages as well.
bool freed = _PyMem_mi_page_maybe_free(page, pq, collect >= MI_FORCE);
if (!freed && collect == MI_ABANDON) {
- _mi_page_abandon(page, pq);
+ // _PyMem_mi_page_maybe_free may have moved the page to a different
+ // page queue, so we need to re-fetch the correct queue.
+ uint8_t bin = (mi_page_is_in_full(page) ? MI_BIN_FULL : _mi_bin(page->xblock_size));
+ _mi_page_abandon(page, &heap->pages[bin]);
}
}
else if (collect == MI_ABANDON) {
diff --git a/Objects/mimalloc/page.c b/Objects/mimalloc/page.c
index ff7444cce10..ded59f8eb1c 100644
--- a/Objects/mimalloc/page.c
+++ b/Objects/mimalloc/page.c
@@ -213,6 +213,13 @@ static void _mi_page_thread_free_collect(mi_page_t* page)
// update counts now
page->used -= count;
+
+ if (page->used == 0) {
+ // The page may have had a QSBR goal set from a previous point when it
+ // was all-free. That goal is no longer valid because the page was
+ // allocated from and then freed again by other threads.
+ _PyMem_mi_page_clear_qsbr(page);
+ }
}
void _mi_page_free_collect(mi_page_t* page, bool force) {
@@ -225,9 +232,6 @@ void _mi_page_free_collect(mi_page_t* page, bool force) {
// and the local free list
if (page->local_free != NULL) {
- // any previous QSBR goals are no longer valid because we reused the page
- _PyMem_mi_page_clear_qsbr(page);
-
if mi_likely(page->free == NULL) {
// usual case
page->free = page->local_free;
diff --git a/Objects/mimalloc/segment.c b/Objects/mimalloc/segment.c
index 9b092b9b734..9dad69c995e 100644
--- a/Objects/mimalloc/segment.c
+++ b/Objects/mimalloc/segment.c
@@ -1286,6 +1286,7 @@ static bool mi_segment_check_free(mi_segment_t* segment, size_t slices_needed, s
_mi_stat_decrease(&tld->stats->pages_abandoned, 1);
#ifdef Py_GIL_DISABLED
page->qsbr_goal = 0;
+ mi_assert_internal(page->qsbr_node.next == NULL);
#endif
segment->abandoned--;
slice = mi_segment_page_clear(page, tld); // re-assign slice due to coalesce!
@@ -1361,6 +1362,7 @@ static mi_segment_t* mi_segment_reclaim(mi_segment_t* segment, mi_heap_t* heap,
// if everything free by now, free the page
#ifdef Py_GIL_DISABLED
page->qsbr_goal = 0;
+ mi_assert_internal(page->qsbr_node.next == NULL);
#endif
slice = mi_segment_page_clear(page, tld); // set slice again due to coalesceing
}
diff --git a/Objects/obmalloc.c b/Objects/obmalloc.c
index 092be84d2b9..9af59f13dc8 100644
--- a/Objects/obmalloc.c
+++ b/Objects/obmalloc.c
@@ -149,6 +149,12 @@ should_advance_qsbr_for_page(struct _qsbr_thread_state *qsbr, mi_page_t *page)
}
return false;
}
+
+static _PyThreadStateImpl *
+tstate_from_heap(mi_heap_t *heap)
+{
+ return _Py_CONTAINER_OF(heap->tld, _PyThreadStateImpl, mimalloc.tld);
+}
#endif
static bool
@@ -157,23 +163,35 @@ _PyMem_mi_page_maybe_free(mi_page_t *page, mi_page_queue_t *pq, bool force)
#ifdef Py_GIL_DISABLED
assert(mi_page_all_free(page));
if (page->use_qsbr) {
- _PyThreadStateImpl *tstate = (_PyThreadStateImpl *)PyThreadState_GET();
- if (page->qsbr_goal != 0 && _Py_qbsr_goal_reached(tstate->qsbr, page->qsbr_goal)) {
+ struct _qsbr_thread_state *qsbr = ((_PyThreadStateImpl *)PyThreadState_GET())->qsbr;
+ if (page->qsbr_goal != 0 && _Py_qbsr_goal_reached(qsbr, page->qsbr_goal)) {
_PyMem_mi_page_clear_qsbr(page);
_mi_page_free(page, pq, force);
return true;
}
+ // gh-145615: since we are not freeing this page yet, we want to
+ // make it available for allocations. Note that the QSBR goal and
+ // linked list node remain set even if the page is later used for
+ // an allocation. We only detect and clear the QSBR goal when the
+ // page becomes empty again (used == 0).
+ if (mi_page_is_in_full(page)) {
+ _mi_page_unfull(page);
+ }
+
_PyMem_mi_page_clear_qsbr(page);
page->retire_expire = 0;
- if (should_advance_qsbr_for_page(tstate->qsbr, page)) {
- page->qsbr_goal = _Py_qsbr_advance(tstate->qsbr->shared);
+ if (should_advance_qsbr_for_page(qsbr, page)) {
+ page->qsbr_goal = _Py_qsbr_advance(qsbr->shared);
}
else {
- page->qsbr_goal = _Py_qsbr_shared_next(tstate->qsbr->shared);
+ page->qsbr_goal = _Py_qsbr_shared_next(qsbr->shared);
}
+ // We may be freeing a page belonging to a different thread during a
+ // stop-the-world event. Find the _PyThreadStateImpl for the page.
+ _PyThreadStateImpl *tstate = tstate_from_heap(mi_page_heap(page));
llist_insert_tail(&tstate->mimalloc.page_list, &page->qsbr_node);
return false;
}
@@ -190,7 +208,8 @@ _PyMem_mi_page_reclaimed(mi_page_t *page)
if (page->qsbr_goal != 0) {
if (mi_page_all_free(page)) {
assert(page->qsbr_node.next == NULL);
- _PyThreadStateImpl *tstate = (_PyThreadStateImpl *)PyThreadState_GET();
+ _PyThreadStateImpl *tstate = tstate_from_heap(mi_page_heap(page));
+ assert(tstate == (_PyThreadStateImpl *)_PyThreadState_GET());
page->retire_expire = 0;
llist_insert_tail(&tstate->mimalloc.page_list, &page->qsbr_node);
}
diff --git a/Objects/stringlib/fastsearch.h b/Objects/stringlib/fastsearch.h
index b447865c986..26bb0555ca9 100644
--- a/Objects/stringlib/fastsearch.h
+++ b/Objects/stringlib/fastsearch.h
@@ -69,8 +69,8 @@ STRINGLIB(find_char)(const STRINGLIB_CHAR* s, Py_ssize_t n, STRINGLIB_CHAR ch)
and UCS4 representations. */
if (needle != 0) {
do {
- void *candidate = memchr(p, needle,
- (e - p) * sizeof(STRINGLIB_CHAR));
+ const void *candidate = memchr(p, needle,
+ (e - p) * sizeof(STRINGLIB_CHAR));
if (candidate == NULL)
return -1;
s1 = p;
diff --git a/Objects/typeobject.c b/Objects/typeobject.c
index 03d5cfa4ca5..9777055c5f2 100644
--- a/Objects/typeobject.c
+++ b/Objects/typeobject.c
@@ -76,6 +76,62 @@ class object "PyObject *" "&PyBaseObject_Type"
#define ASSERT_TYPE_LOCK_HELD() \
_Py_CRITICAL_SECTION_ASSERT_MUTEX_LOCKED(TYPE_LOCK)
+static void
+types_stop_world(void)
+{
+ PyInterpreterState *interp = _PyInterpreterState_GET();
+ _PyEval_StopTheWorld(interp);
+}
+
+static void
+types_start_world(void)
+{
+ PyInterpreterState *interp = _PyInterpreterState_GET();
+ _PyEval_StartTheWorld(interp);
+}
+
+// This is used to temporarily prevent the TYPE_LOCK from being suspended
+// when held by the topmost critical section.
+static void
+type_lock_prevent_release(void)
+{
+ PyThreadState *tstate = _PyThreadState_GET();
+ uintptr_t *tagptr = &tstate->critical_section;
+ PyCriticalSection *c = (PyCriticalSection *)(*tagptr & ~_Py_CRITICAL_SECTION_MASK);
+ if (!(*tagptr & _Py_CRITICAL_SECTION_TWO_MUTEXES)) {
+ assert(c->_cs_mutex == TYPE_LOCK);
+ c->_cs_mutex = NULL;
+ }
+ else {
+ PyCriticalSection2 *c2 = (PyCriticalSection2 *)c;
+ if (c->_cs_mutex == TYPE_LOCK) {
+ c->_cs_mutex = c2->_cs_mutex2;
+ c2->_cs_mutex2 = NULL;
+ }
+ else {
+ assert(c2->_cs_mutex2 == TYPE_LOCK);
+ c2->_cs_mutex2 = NULL;
+ }
+ }
+}
+
+static void
+type_lock_allow_release(void)
+{
+ PyThreadState *tstate = _PyThreadState_GET();
+ uintptr_t *tagptr = &tstate->critical_section;
+ PyCriticalSection *c = (PyCriticalSection *)(*tagptr & ~_Py_CRITICAL_SECTION_MASK);
+ if (!(*tagptr & _Py_CRITICAL_SECTION_TWO_MUTEXES)) {
+ assert(c->_cs_mutex == NULL);
+ c->_cs_mutex = TYPE_LOCK;
+ }
+ else {
+ PyCriticalSection2 *c2 = (PyCriticalSection2 *)c;
+ assert(c2->_cs_mutex2 == NULL);
+ c2->_cs_mutex2 = TYPE_LOCK;
+ }
+}
+
#else
#define BEGIN_TYPE_LOCK()
@@ -83,6 +139,10 @@ class object "PyObject *" "&PyBaseObject_Type"
#define BEGIN_TYPE_DICT_LOCK(d)
#define END_TYPE_DICT_LOCK()
#define ASSERT_TYPE_LOCK_HELD()
+#define types_stop_world()
+#define types_start_world()
+#define type_lock_prevent_release()
+#define type_lock_allow_release()
#endif
@@ -541,7 +601,6 @@ clear_tp_bases(PyTypeObject *self, int final)
static inline PyObject *
lookup_tp_mro(PyTypeObject *self)
{
- ASSERT_TYPE_LOCK_HELD();
return self->tp_mro;
}
@@ -580,8 +639,19 @@ set_tp_mro(PyTypeObject *self, PyObject *mro, int initial)
/* Other checks are done via set_tp_bases. */
_Py_SetImmortal(mro);
}
+ else {
+ PyUnstable_Object_EnableDeferredRefcount(mro);
+ }
+ }
+ if (!initial) {
+ type_lock_prevent_release();
+ types_stop_world();
}
self->tp_mro = mro;
+ if (!initial) {
+ types_start_world();
+ type_lock_allow_release();
+ }
}
static inline void
@@ -1627,18 +1697,11 @@ static PyObject *
type_get_mro(PyObject *tp, void *Py_UNUSED(closure))
{
PyTypeObject *type = PyTypeObject_CAST(tp);
- PyObject *mro;
-
- BEGIN_TYPE_LOCK();
- mro = lookup_tp_mro(type);
+ PyObject *mro = lookup_tp_mro(type);
if (mro == NULL) {
- mro = Py_None;
- } else {
- Py_INCREF(mro);
+ Py_RETURN_NONE;
}
-
- END_TYPE_LOCK();
- return mro;
+ return Py_NewRef(mro);
}
static PyTypeObject *best_base(PyObject *);
@@ -5639,17 +5702,18 @@ PyObject_GetItemData(PyObject *obj)
}
/* Internal API to look for a name through the MRO, bypassing the method cache.
- This returns a borrowed reference, and might set an exception.
- 'error' is set to: -1: error with exception; 1: error without exception; 0: ok */
-static PyObject *
-find_name_in_mro(PyTypeObject *type, PyObject *name, int *error)
+ The result is stored as a _PyStackRef in `out`. It never set an exception.
+ Returns -1 if there was an error, 0 if the name was not found, and 1 if
+ the name was found. */
+static int
+find_name_in_mro(PyTypeObject *type, PyObject *name, _PyStackRef *out)
{
ASSERT_TYPE_LOCK_HELD();
Py_hash_t hash = _PyObject_HashFast(name);
if (hash == -1) {
- *error = -1;
- return NULL;
+ PyErr_Clear();
+ return -1;
}
/* Look in tp_dict of types in MRO */
@@ -5657,37 +5721,42 @@ find_name_in_mro(PyTypeObject *type, PyObject *name, int *error)
if (mro == NULL) {
if (!is_readying(type)) {
if (PyType_Ready(type) < 0) {
- *error = -1;
- return NULL;
+ PyErr_Clear();
+ return -1;
}
mro = lookup_tp_mro(type);
}
if (mro == NULL) {
- *error = 1;
- return NULL;
+ return -1;
}
}
- PyObject *res = NULL;
+ int res = 0;
+ PyThreadState *tstate = _PyThreadState_GET();
/* Keep a strong reference to mro because type->tp_mro can be replaced
during dict lookup, e.g. when comparing to non-string keys. */
- Py_INCREF(mro);
+ _PyCStackRef mro_ref;
+ _PyThreadState_PushCStackRef(tstate, &mro_ref);
+ mro_ref.ref = PyStackRef_FromPyObjectNew(mro);
Py_ssize_t n = PyTuple_GET_SIZE(mro);
for (Py_ssize_t i = 0; i < n; i++) {
PyObject *base = PyTuple_GET_ITEM(mro, i);
PyObject *dict = lookup_tp_dict(_PyType_CAST(base));
assert(dict && PyDict_Check(dict));
- if (_PyDict_GetItemRef_KnownHash((PyDictObject *)dict, name, hash, &res) < 0) {
- *error = -1;
+ Py_ssize_t ix = _Py_dict_lookup_threadsafe_stackref(
+ (PyDictObject *)dict, name, hash, out);
+ if (ix == DKIX_ERROR) {
+ PyErr_Clear();
+ res = -1;
goto done;
}
- if (res != NULL) {
+ if (!PyStackRef_IsNull(*out)) {
+ res = 1;
break;
}
}
- *error = 0;
done:
- Py_DECREF(mro);
+ _PyThreadState_PopCStackRef(tstate, &mro_ref);
return res;
}
@@ -5842,11 +5911,11 @@ _PyType_LookupStackRefAndVersion(PyTypeObject *type, PyObject *name, _PyStackRef
// We need to atomically do the lookup and capture the version before
// anyone else can modify our mro or mutate the type.
- PyObject *res;
- int error;
+ int res;
PyInterpreterState *interp = _PyInterpreterState_GET();
int has_version = 0;
unsigned int assigned_version = 0;
+
BEGIN_TYPE_LOCK();
// We must assign the version before doing the lookup. If
// find_name_in_mro() blocks and releases the critical section
@@ -5855,35 +5924,24 @@ _PyType_LookupStackRefAndVersion(PyTypeObject *type, PyObject *name, _PyStackRef
has_version = assign_version_tag(interp, type);
assigned_version = type->tp_version_tag;
}
- res = find_name_in_mro(type, name, &error);
+ res = find_name_in_mro(type, name, out);
END_TYPE_LOCK();
/* Only put NULL results into cache if there was no error. */
- if (error) {
- /* It's not ideal to clear the error condition,
- but this function is documented as not setting
- an exception, and I don't want to change that.
- E.g., when PyType_Ready() can't proceed, it won't
- set the "ready" flag, so future attempts to ready
- the same type will call it again -- hopefully
- in a context that propagates the exception out.
- */
- if (error == -1) {
- PyErr_Clear();
- }
+ if (res < 0) {
*out = PyStackRef_NULL;
return 0;
}
if (has_version) {
+ PyObject *res_obj = PyStackRef_AsPyObjectBorrow(*out);
#if Py_GIL_DISABLED
- update_cache_gil_disabled(entry, name, assigned_version, res);
+ update_cache_gil_disabled(entry, name, assigned_version, res_obj);
#else
- PyObject *old_value = update_cache(entry, name, assigned_version, res);
+ PyObject *old_value = update_cache(entry, name, assigned_version, res_obj);
Py_DECREF(old_value);
#endif
}
- *out = res ? PyStackRef_FromPyObjectSteal(res) : PyStackRef_NULL;
return has_version ? assigned_version : 0;
}
@@ -7120,7 +7178,11 @@ object_set_class_world_stopped(PyObject *self, PyTypeObject *newto)
assert(_PyObject_GetManagedDict(self) == dict);
- if (_PyDict_DetachFromObject(dict, self) < 0) {
+ int err;
+ Py_BEGIN_CRITICAL_SECTION(dict);
+ err = _PyDict_DetachFromObject(dict, self);
+ Py_END_CRITICAL_SECTION();
+ if (err < 0) {
return -1;
}
@@ -7162,12 +7224,17 @@ object_set_class(PyObject *self, PyObject *value, void *closure)
#ifdef Py_GIL_DISABLED
PyInterpreterState *interp = _PyInterpreterState_GET();
- _PyEval_StopTheWorld(interp);
+ int unique = _PyObject_IsUniquelyReferenced(self);
+ if (!unique) {
+ _PyEval_StopTheWorld(interp);
+ }
#endif
PyTypeObject *oldto = Py_TYPE(self);
int res = object_set_class_world_stopped(self, newto);
#ifdef Py_GIL_DISABLED
- _PyEval_StartTheWorld(interp);
+ if (!unique) {
+ _PyEval_StartTheWorld(interp);
+ }
#endif
if (res == 0) {
if (oldto->tp_flags & Py_TPFLAGS_HEAPTYPE) {
@@ -11234,7 +11301,6 @@ update_one_slot(PyTypeObject *type, pytype_slotdef *p)
int use_generic = 0;
int offset = p->offset;
- int error;
void **ptr = slotptr(type, offset);
if (ptr == NULL) {
@@ -11247,19 +11313,15 @@ update_one_slot(PyTypeObject *type, pytype_slotdef *p)
assert(!PyErr_Occurred());
do {
/* Use faster uncached lookup as we won't get any cache hits during type setup. */
- descr = find_name_in_mro(type, p->name_strobj, &error);
- if (descr == NULL) {
- if (error == -1) {
- /* It is unlikely but not impossible that there has been an exception
- during lookup. Since this function originally expected no errors,
- we ignore them here in order to keep up the interface. */
- PyErr_Clear();
- }
+ _PyStackRef descr_ref;
+ int res = find_name_in_mro(type, p->name_strobj, &descr_ref);
+ if (res <= 0) {
if (ptr == (void**)&type->tp_iternext) {
specific = (void *)_PyObject_NextNotImplemented;
}
continue;
}
+ descr = PyStackRef_AsPyObjectBorrow(descr_ref);
if (Py_IS_TYPE(descr, &PyWrapperDescr_Type) &&
((PyWrapperDescrObject *)descr)->d_base->name_strobj == p->name_strobj) {
void **tptr = resolve_slotdups(type, p->name_strobj);
@@ -11327,7 +11389,7 @@ update_one_slot(PyTypeObject *type, pytype_slotdef *p)
type_clear_flags(type, Py_TPFLAGS_HAVE_VECTORCALL);
}
}
- Py_DECREF(descr);
+ PyStackRef_CLOSE(descr_ref);
} while ((++p)->offset == offset);
if (specific && !use_generic)
*ptr = specific;
@@ -11758,18 +11820,16 @@ _super_lookup_descr(PyTypeObject *su_type, PyTypeObject *su_obj_type, PyObject *
PyObject *mro, *res;
Py_ssize_t i, n;
- BEGIN_TYPE_LOCK();
mro = lookup_tp_mro(su_obj_type);
- /* keep a strong reference to mro because su_obj_type->tp_mro can be
- replaced during PyDict_GetItemRef(dict, name, &res) and because
- another thread can modify it after we end the critical section
- below */
- Py_XINCREF(mro);
- END_TYPE_LOCK();
-
if (mro == NULL)
return NULL;
+ /* Keep a strong reference to mro because su_obj_type->tp_mro can be
+ replaced during PyDict_GetItemRef(dict, name, &res). */
+ PyThreadState *tstate = _PyThreadState_GET();
+ _PyCStackRef mro_ref;
+ _PyThreadState_PushCStackRefNew(tstate, &mro_ref, mro);
+
assert(PyTuple_Check(mro));
n = PyTuple_GET_SIZE(mro);
@@ -11780,7 +11840,7 @@ _super_lookup_descr(PyTypeObject *su_type, PyTypeObject *su_obj_type, PyObject *
}
i++; /* skip su->type (if any) */
if (i >= n) {
- Py_DECREF(mro);
+ _PyThreadState_PopCStackRef(tstate, &mro_ref);
return NULL;
}
@@ -11791,13 +11851,13 @@ _super_lookup_descr(PyTypeObject *su_type, PyTypeObject *su_obj_type, PyObject *
if (PyDict_GetItemRef(dict, name, &res) != 0) {
// found or error
- Py_DECREF(mro);
+ _PyThreadState_PopCStackRef(tstate, &mro_ref);
return res;
}
i++;
} while (i < n);
- Py_DECREF(mro);
+ _PyThreadState_PopCStackRef(tstate, &mro_ref);
return NULL;
}
diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c
index c71c5720ea0..3835b8d462a 100644
--- a/Objects/unicodeobject.c
+++ b/Objects/unicodeobject.c
@@ -13366,6 +13366,45 @@ unicode_swapcase_impl(PyObject *self)
return case_operation(self, do_swapcase);
}
+static int
+unicode_maketrans_from_dict(PyObject *x, PyObject *newdict)
+{
+ PyObject *key, *value;
+ Py_ssize_t i = 0;
+ int res;
+ while (PyDict_Next(x, &i, &key, &value)) {
+ if (PyUnicode_Check(key)) {
+ PyObject *newkey;
+ int kind;
+ const void *data;
+ if (PyUnicode_GET_LENGTH(key) != 1) {
+ PyErr_SetString(PyExc_ValueError, "string keys in translate"
+ "table must be of length 1");
+ return -1;
+ }
+ kind = PyUnicode_KIND(key);
+ data = PyUnicode_DATA(key);
+ newkey = PyLong_FromLong(PyUnicode_READ(kind, data, 0));
+ if (!newkey)
+ return -1;
+ res = PyDict_SetItem(newdict, newkey, value);
+ Py_DECREF(newkey);
+ if (res < 0)
+ return -1;
+ }
+ else if (PyLong_Check(key)) {
+ if (PyDict_SetItem(newdict, key, value) < 0)
+ return -1;
+ }
+ else {
+ PyErr_SetString(PyExc_TypeError, "keys in translate table must"
+ "be strings or integers");
+ return -1;
+ }
+ }
+ return 0;
+}
+
/*[clinic input]
@staticmethod
@@ -13451,9 +13490,6 @@ unicode_maketrans_impl(PyObject *x, PyObject *y, PyObject *z)
}
}
} else {
- int kind;
- const void *data;
-
/* x must be a dict */
if (!PyDict_CheckExact(x)) {
PyErr_SetString(PyExc_TypeError, "if you give only one argument "
@@ -13461,34 +13497,12 @@ unicode_maketrans_impl(PyObject *x, PyObject *y, PyObject *z)
goto err;
}
/* copy entries into the new dict, converting string keys to int keys */
- while (PyDict_Next(x, &i, &key, &value)) {
- if (PyUnicode_Check(key)) {
- /* convert string keys to integer keys */
- PyObject *newkey;
- if (PyUnicode_GET_LENGTH(key) != 1) {
- PyErr_SetString(PyExc_ValueError, "string keys in translate "
- "table must be of length 1");
- goto err;
- }
- kind = PyUnicode_KIND(key);
- data = PyUnicode_DATA(key);
- newkey = PyLong_FromLong(PyUnicode_READ(kind, data, 0));
- if (!newkey)
- goto err;
- res = PyDict_SetItem(new, newkey, value);
- Py_DECREF(newkey);
- if (res < 0)
- goto err;
- } else if (PyLong_Check(key)) {
- /* just keep integer keys */
- if (PyDict_SetItem(new, key, value) < 0)
- goto err;
- } else {
- PyErr_SetString(PyExc_TypeError, "keys in translate table must "
- "be strings or integers");
- goto err;
- }
- }
+ int errcode;
+ Py_BEGIN_CRITICAL_SECTION(x);
+ errcode = unicode_maketrans_from_dict(x, new);
+ Py_END_CRITICAL_SECTION();
+ if (errcode < 0)
+ goto err;
}
return new;
err:
diff --git a/PC/launcher2.c b/PC/launcher2.c
index 832935c5cc6..4dd18c8eb54 100644
--- a/PC/launcher2.c
+++ b/PC/launcher2.c
@@ -922,6 +922,20 @@ _readIni(const wchar_t *section, const wchar_t *settingName, wchar_t *buffer, in
{
wchar_t iniPath[MAXLEN];
int n;
+ // Check for _PYLAUNCHER_INIDIR override (used for test isolation)
+ DWORD len = GetEnvironmentVariableW(L"_PYLAUNCHER_INIDIR", iniPath, MAXLEN);
+ if (len && len < MAXLEN) {
+ if (join(iniPath, MAXLEN, L"py.ini")) {
+ debug(L"# Reading from %s for %s/%s\n", iniPath, section, settingName);
+ n = GetPrivateProfileStringW(section, settingName, NULL, buffer, bufferLength, iniPath);
+ if (n) {
+ debug(L"# Found %s in %s\n", settingName, iniPath);
+ return n;
+ }
+ }
+ // When _PYLAUNCHER_INIDIR is set, skip the default locations
+ return 0;
+ }
if (SUCCEEDED(SHGetFolderPathW(NULL, CSIDL_LOCAL_APPDATA, NULL, 0, iniPath)) &&
join(iniPath, MAXLEN, L"py.ini")) {
debug(L"# Reading from %s for %s/%s\n", iniPath, section, settingName);
diff --git a/Parser/lexer/buffer.c b/Parser/lexer/buffer.c
index 63aa1ea2ad4..e122fd0d987 100644
--- a/Parser/lexer/buffer.c
+++ b/Parser/lexer/buffer.c
@@ -13,8 +13,8 @@ _PyLexer_remember_fstring_buffers(struct tok_state *tok)
for (index = tok->tok_mode_stack_index; index >= 0; --index) {
mode = &(tok->tok_mode_stack[index]);
- mode->start_offset = mode->start - tok->buf;
- mode->multi_line_start_offset = mode->multi_line_start - tok->buf;
+ mode->start_offset = mode->start == NULL ? -1 : mode->start - tok->buf;
+ mode->multi_line_start_offset = mode->multi_line_start == NULL ? -1 : mode->multi_line_start - tok->buf;
}
}
@@ -27,8 +27,8 @@ _PyLexer_restore_fstring_buffers(struct tok_state *tok)
for (index = tok->tok_mode_stack_index; index >= 0; --index) {
mode = &(tok->tok_mode_stack[index]);
- mode->start = tok->buf + mode->start_offset;
- mode->multi_line_start = tok->buf + mode->multi_line_start_offset;
+ mode->start = mode->start_offset < 0 ? NULL : tok->buf + mode->start_offset;
+ mode->multi_line_start = mode->multi_line_start_offset < 0 ? NULL : tok->buf + mode->multi_line_start_offset;
}
}
diff --git a/Parser/tokenizer/helpers.c b/Parser/tokenizer/helpers.c
index e5e2eed2d34..7bdf6367671 100644
--- a/Parser/tokenizer/helpers.c
+++ b/Parser/tokenizer/helpers.c
@@ -494,9 +494,11 @@ valid_utf8(const unsigned char* s)
return 0;
}
length = expected + 1;
- for (; expected; expected--)
- if (s[expected] < 0x80 || s[expected] >= 0xC0)
+ for (int i = 1; i <= expected; i++) {
+ if (s[i] < 0x80 || s[i] >= 0xC0) {
return 0;
+ }
+ }
return length;
}
diff --git a/Parser/tokenizer/string_tokenizer.c b/Parser/tokenizer/string_tokenizer.c
index 7299ecf483c..7f07cca37ee 100644
--- a/Parser/tokenizer/string_tokenizer.c
+++ b/Parser/tokenizer/string_tokenizer.c
@@ -108,6 +108,19 @@ decode_str(const char *input, int single, struct tok_state *tok, int preserve_cr
else if (!_PyTokenizer_ensure_utf8(str, tok, 1)) {
return _PyTokenizer_error_ret(tok);
}
+ if (utf8 != NULL) {
+ char *translated = _PyTokenizer_translate_newlines(
+ str, single, preserve_crlf, tok);
+ if (translated == NULL) {
+ Py_DECREF(utf8);
+ return _PyTokenizer_error_ret(tok);
+ }
+ PyMem_Free(tok->input);
+ tok->input = translated;
+ str = translated;
+ Py_CLEAR(utf8);
+ }
+ tok->str = str;
assert(tok->decoding_buffer == NULL);
tok->decoding_buffer = utf8; /* CAUTION */
return str;
diff --git a/Python/ceval.c b/Python/ceval.c
index 87cf01730b4..e6d82f249ef 100644
--- a/Python/ceval.c
+++ b/Python/ceval.c
@@ -3486,11 +3486,27 @@ PyUnstable_Eval_RequestCodeExtraIndex(freefunc free)
PyInterpreterState *interp = _PyInterpreterState_GET();
Py_ssize_t new_index;
- if (interp->co_extra_user_count == MAX_CO_EXTRA_USERS - 1) {
+#ifdef Py_GIL_DISABLED
+ struct _py_code_state *state = &interp->code_state;
+ FT_MUTEX_LOCK(&state->mutex);
+#endif
+
+ if (interp->co_extra_user_count >= MAX_CO_EXTRA_USERS - 1) {
+#ifdef Py_GIL_DISABLED
+ FT_MUTEX_UNLOCK(&state->mutex);
+#endif
return -1;
}
- new_index = interp->co_extra_user_count++;
+
+ new_index = interp->co_extra_user_count;
interp->co_extra_freefuncs[new_index] = free;
+
+ // Publish freefuncs[new_index] before making the index visible.
+ FT_ATOMIC_STORE_SSIZE_RELEASE(interp->co_extra_user_count, new_index + 1);
+
+#ifdef Py_GIL_DISABLED
+ FT_MUTEX_UNLOCK(&state->mutex);
+#endif
return new_index;
}
diff --git a/Python/codegen.c b/Python/codegen.c
index bacd3460f2f..085ebc391a1 100644
--- a/Python/codegen.c
+++ b/Python/codegen.c
@@ -1200,11 +1200,11 @@ codegen_type_param_bound_or_default(compiler *c, expr_ty e,
ADDOP_LOAD_CONST_NEW(c, LOC(e), defaults);
RETURN_IF_ERROR(codegen_setup_annotations_scope(c, LOC(e), key, name));
if (allow_starred && e->kind == Starred_kind) {
- VISIT(c, expr, e->v.Starred.value);
- ADDOP_I(c, LOC(e), UNPACK_SEQUENCE, (Py_ssize_t)1);
+ VISIT_IN_SCOPE(c, expr, e->v.Starred.value);
+ ADDOP_I_IN_SCOPE(c, LOC(e), UNPACK_SEQUENCE, (Py_ssize_t)1);
}
else {
- VISIT(c, expr, e);
+ VISIT_IN_SCOPE(c, expr, e);
}
ADDOP_IN_SCOPE(c, LOC(e), RETURN_VALUE);
PyCodeObject *co = _PyCompile_OptimizeAndAssemble(c, 1);
diff --git a/Python/critical_section.c b/Python/critical_section.c
index 218b580e951..11a3f027547 100644
--- a/Python/critical_section.c
+++ b/Python/critical_section.c
@@ -1,7 +1,8 @@
#include "Python.h"
-#include "pycore_lock.h"
#include "pycore_critical_section.h"
+#include "pycore_interp.h"
+#include "pycore_lock.h"
#ifdef Py_GIL_DISABLED
static_assert(_Alignof(PyCriticalSection) >= 4,
@@ -43,6 +44,15 @@ _PyCriticalSection_BeginSlow(PyCriticalSection *c, PyMutex *m)
}
}
}
+ // If the world is stopped, we don't need to acquire the lock because
+ // there are no other threads that could be accessing the object.
+ // Without this check, acquiring a critical section while the world is
+ // stopped could lead to a deadlock.
+ if (tstate->interp->stoptheworld.world_stopped) {
+ c->_cs_mutex = NULL;
+ c->_cs_prev = 0;
+ return;
+ }
c->_cs_mutex = NULL;
c->_cs_prev = (uintptr_t)tstate->critical_section;
tstate->critical_section = (uintptr_t)c;
@@ -58,6 +68,12 @@ _PyCriticalSection2_BeginSlow(PyCriticalSection2 *c, PyMutex *m1, PyMutex *m2,
{
#ifdef Py_GIL_DISABLED
PyThreadState *tstate = _PyThreadState_GET();
+ if (tstate->interp->stoptheworld.world_stopped) {
+ c->_cs_base._cs_mutex = NULL;
+ c->_cs_mutex2 = NULL;
+ c->_cs_base._cs_prev = 0;
+ return;
+ }
c->_cs_base._cs_mutex = NULL;
c->_cs_mutex2 = NULL;
c->_cs_base._cs_prev = tstate->critical_section;
diff --git a/Python/crossinterp.c b/Python/crossinterp.c
index 80772fcedb4..3b6c0c6e1ed 100644
--- a/Python/crossinterp.c
+++ b/Python/crossinterp.c
@@ -609,6 +609,7 @@ check_missing___main___attr(PyObject *exc)
// Get the error message.
PyObject *args = PyException_GetArgs(exc);
if (args == NULL || args == Py_None || PyObject_Size(args) < 1) {
+ Py_XDECREF(args);
assert(!PyErr_Occurred());
return 0;
}
diff --git a/Python/emscripten_trampoline.c b/Python/emscripten_trampoline.c
index d61146504d0..1833311ca74 100644
--- a/Python/emscripten_trampoline.c
+++ b/Python/emscripten_trampoline.c
@@ -2,20 +2,59 @@
#include <emscripten.h> // EM_JS, EM_JS_DEPS
#include <Python.h>
+#include "pycore_runtime.h" // _PyRuntime
-EM_JS(
-PyObject*,
-_PyEM_TrampolineCall_inner, (int* success,
- PyCFunctionWithKeywords func,
- PyObject *arg1,
- PyObject *arg2,
- PyObject *arg3), {
- // JavaScript fallback trampoline
+// We use the _PyRuntime.emscripten_trampoline field to store a function pointer
+// for a wasm-gc based trampoline if it works. Otherwise fall back to JS
+// trampoline. The JS trampoline breaks stack switching but every runtime that
+// supports stack switching also supports wasm-gc.
+//
+// We'd like to make the trampoline call into a direct call but currently we
+// need to import the wasmTable to compile trampolineModule. emcc >= 4.0.19
+// defines the table in WebAssembly and exports it so we won't have access to it
+// until after the main module is compiled.
+//
+// To fix this, one natural solution would be to pass a funcref to the
+// trampoline instead of a table index. Several PRs would be needed to fix
+// things in llvm and emscripten in order to make this possible.
+//
+// The performance costs of an extra call_indirect aren't that large anyways.
+// The JIT should notice that the target is always the same and turn into a
+// check
+//
+// if (call_target != expected) deoptimize;
+// direct_call(call_target, args);
+
+// Offset of emscripten_trampoline in _PyRuntimeState. There's a couple of
+// alternatives:
+//
+// 1. Just make emscripten_trampoline a real C global variable instead of a
+// field of _PyRuntimeState. This would violate our rule against mutable
+// globals.
+//
+// 2. #define a preprocessor constant equal to a hard coded number and make a
+// _Static_assert(offsetof(_PyRuntimeState, emscripten_trampoline) == OURCONSTANT)
+// This has the disadvantage that we have to update the hard coded constant
+// when _PyRuntimeState changes
+//
+// So putting the mutable constant in _PyRuntime and using a immutable global to
+// record the offset so we can access it from JS is probably the best way.
+EMSCRIPTEN_KEEPALIVE const int _PyEM_EMSCRIPTEN_TRAMPOLINE_OFFSET = offsetof(_PyRuntimeState, emscripten_trampoline);
+
+typedef PyObject* (*TrampolineFunc)(int* success,
+ PyCFunctionWithKeywords func,
+ PyObject* self,
+ PyObject* args,
+ PyObject* kw);
+
+/**
+ * Backwards compatible trampoline works with all JS runtimes
+ */
+EM_JS(PyObject*, _PyEM_TrampolineCall_JS, (PyCFunctionWithKeywords func, PyObject *arg1, PyObject *arg2, PyObject *arg3), {
return wasmTable.get(func)(arg1, arg2, arg3);
}
-// Try to replace the JS definition of _PyEM_TrampolineCall_inner with a wasm
-// version.
-(function () {
+// Try to compile wasm-gc trampoline if possible.
+function getPyEMTrampolinePtr() {
// Starting with iOS 18.3.1, WebKit on iOS has an issue with the garbage
// collector that breaks the call trampoline. See #130418 and
// https://bugs.webkit.org/show_bug.cgi?id=293113 for details.
@@ -27,19 +66,32 @@ _PyEM_TrampolineCall_inner, (int* success,
(navigator.platform === 'MacIntel' && typeof navigator.maxTouchPoints !== 'undefined' && navigator.maxTouchPoints > 1)
);
if (isIOS) {
- return;
+ return 0;
}
+ let trampolineModule;
try {
- const trampolineModule = getWasmTrampolineModule();
- const trampolineInstance = new WebAssembly.Instance(trampolineModule, {
- env: { __indirect_function_table: wasmTable, memory: wasmMemory },
- });
- _PyEM_TrampolineCall_inner = trampolineInstance.exports.trampoline_call;
+ trampolineModule = getWasmTrampolineModule();
} catch (e) {
// Compilation error due to missing wasm-gc support, fall back to JS
// trampoline
+ return 0;
}
-})();
+ const trampolineInstance = new WebAssembly.Instance(trampolineModule, {
+ env: { __indirect_function_table: wasmTable, memory: wasmMemory },
+ });
+ return addFunction(trampolineInstance.exports.trampoline_call);
+}
+// We have to be careful to work correctly with memory snapshots -- the value of
+// _PyRuntimeState.emscripten_trampoline needs to reflect whether wasm-gc is
+// available in the current runtime, not in the runtime the snapshot was taken
+// in. This writes the appropriate value to
+// _PyRuntimeState.emscripten_trampoline from JS startup code that runs every
+// time, whether we are restoring a snapshot or not.
+addOnPreRun(function setEmscriptenTrampoline() {
+ const ptr = getPyEMTrampolinePtr();
+ const offset = HEAP32[__PyEM_EMSCRIPTEN_TRAMPOLINE_OFFSET / 4];
+ HEAP32[(__PyRuntime + offset) / 4] = ptr;
+});
);
PyObject*
@@ -48,12 +100,19 @@ _PyEM_TrampolineCall(PyCFunctionWithKeywords func,
PyObject* args,
PyObject* kw)
{
+ TrampolineFunc trampoline = _PyRuntime.emscripten_trampoline;
+ if (trampoline == 0) {
+ return _PyEM_TrampolineCall_JS(func, self, args, kw);
+ }
int success = 1;
- PyObject *result = _PyEM_TrampolineCall_inner(&success, func, self, args, kw);
+ PyObject *result = trampoline(&success, func, self, args, kw);
if (!success) {
PyErr_SetString(PyExc_SystemError, "Handler takes too many arguments");
}
return result;
}
+#else
+// This is exported so we need to define it even when it isn't used
+__attribute__((used)) const int _PyEM_EMSCRIPTEN_TRAMPOLINE_OFFSET = 0;
#endif
diff --git a/Python/frame.c b/Python/frame.c
index ce216797e47..1196154d894 100644
--- a/Python/frame.c
+++ b/Python/frame.c
@@ -54,7 +54,7 @@ take_ownership(PyFrameObject *f, _PyInterpreterFrame *frame)
_PyFrame_Copy(frame, new_frame);
// _PyFrame_Copy takes the reference to the executable,
// so we need to restore it.
- frame->f_executable = PyStackRef_DUP(new_frame->f_executable);
+ new_frame->f_executable = PyStackRef_DUP(new_frame->f_executable);
f->f_frame = new_frame;
new_frame->owner = FRAME_OWNED_BY_FRAME_OBJECT;
if (_PyFrame_IsIncomplete(new_frame)) {
@@ -135,14 +135,14 @@ PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame)
return PyStackRef_AsPyObjectNew(frame->f_executable);
}
-int
+// NOTE: We allow racy accesses to the instruction pointer from other threads
+// for sys._current_frames() and similar APIs.
+int _Py_NO_SANITIZE_THREAD
PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame)
{
return _PyInterpreterFrame_LASTI(frame) * sizeof(_Py_CODEUNIT);
}
-// NOTE: We allow racy accesses to the instruction pointer from other threads
-// for sys._current_frames() and similar APIs.
int _Py_NO_SANITIZE_THREAD
PyUnstable_InterpreterFrame_GetLine(_PyInterpreterFrame *frame)
{
diff --git a/Python/import.c b/Python/import.c
index 23b4bf51912..5914722c8f7 100644
--- a/Python/import.c
+++ b/Python/import.c
@@ -297,12 +297,32 @@ PyImport_GetModule(PyObject *name)
mod = import_get_module(tstate, name);
if (mod != NULL && mod != Py_None) {
if (import_ensure_initialized(tstate->interp, mod, name) < 0) {
+ goto error;
+ }
+ /* Verify the module is still in sys.modules. Another thread may have
+ removed it (due to import failure) between our import_get_module()
+ call and the _initializing check in import_ensure_initialized(). */
+ PyObject *mod_check = import_get_module(tstate, name);
+ if (mod_check != mod) {
+ Py_XDECREF(mod_check);
+ if (_PyErr_Occurred(tstate)) {
+ goto error;
+ }
+ /* The module was removed or replaced. Return NULL to report
+ "not found" rather than trying to keep up with racing
+ modifications to sys.modules; returning the new value would
+ require looping to redo the ensure_initialized check. */
Py_DECREF(mod);
- remove_importlib_frames(tstate);
return NULL;
}
+ Py_DECREF(mod_check);
}
return mod;
+
+error:
+ Py_DECREF(mod);
+ remove_importlib_frames(tstate);
+ return NULL;
}
/* Get the module object corresponding to a module name.
@@ -2127,13 +2147,29 @@ import_run_extension(PyThreadState *tstate, PyModInitFunction p0,
}
main_finally:
+ if (rc < 0) {
+ _Py_ext_module_loader_result_apply_error(&res, name_buf);
+ }
+
/* Switch back to the subinterpreter. */
if (switched) {
+ // gh-144601: The exception object can't be transferred across
+ // interpreters. Instead, we print out an unraisable exception, and
+ // then raise a different exception for the calling interpreter.
+ if (rc < 0) {
+ assert(PyErr_Occurred());
+ PyErr_FormatUnraisable("Exception while importing from subinterpreter");
+ }
assert(main_tstate != tstate);
switch_back_from_main_interpreter(tstate, main_tstate, mod);
/* Any module we got from the init function will have to be
* reloaded in the subinterpreter. */
mod = NULL;
+ if (rc < 0) {
+ PyErr_SetString(PyExc_ImportError,
+ "failed to import from subinterpreter due to exception");
+ goto error;
+ }
}
/*****************************************************************/
@@ -2142,7 +2178,6 @@ import_run_extension(PyThreadState *tstate, PyModInitFunction p0,
/* Finally we handle the error return from _PyImport_RunModInitFunc(). */
if (rc < 0) {
- _Py_ext_module_loader_result_apply_error(&res, name_buf);
goto error;
}
@@ -3813,6 +3848,27 @@ PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals,
if (import_ensure_initialized(tstate->interp, mod, abs_name) < 0) {
goto error;
}
+ /* Verify the module is still in sys.modules. Another thread may have
+ removed it (due to import failure) between our import_get_module()
+ call and the _initializing check in import_ensure_initialized().
+ If removed, we retry the import to preserve normal semantics: the
+ caller gets the exception from the actual import failure rather
+ than a synthetic error. */
+ PyObject *mod_check = import_get_module(tstate, abs_name);
+ if (mod_check != mod) {
+ Py_XDECREF(mod_check);
+ if (_PyErr_Occurred(tstate)) {
+ goto error;
+ }
+ Py_DECREF(mod);
+ mod = import_find_and_load(tstate, abs_name);
+ if (mod == NULL) {
+ goto error;
+ }
+ }
+ else {
+ Py_DECREF(mod_check);
+ }
}
else {
Py_XDECREF(mod);
diff --git a/Python/perf_trampoline.c b/Python/perf_trampoline.c
index 8feb259a63a..40136054221 100644
--- a/Python/perf_trampoline.c
+++ b/Python/perf_trampoline.c
@@ -620,6 +620,12 @@ _PyPerfTrampoline_AfterFork_Child(void)
int was_active = _PyIsPerfTrampolineActive();
_PyPerfTrampoline_Fini();
if (was_active) {
+ // After fork, Fini may leave the old code watcher registered
+ // if trampolined code objects from the parent still exist
+ // (trampoline_refcount > 0). Clear it unconditionally before
+ // Init registers a new one, to prevent two watchers sharing
+ // the same globals and double-decrementing trampoline_refcount.
+ perf_trampoline_reset_state();
_PyPerfTrampoline_Init(1);
}
}
diff --git a/Python/preconfig.c b/Python/preconfig.c
index 5b26c75de8b..7b4168c4667 100644
--- a/Python/preconfig.c
+++ b/Python/preconfig.c
@@ -584,7 +584,7 @@ _Py_get_xoption(const PyWideStringList *xoptions, const wchar_t *name)
for (Py_ssize_t i=0; i < xoptions->length; i++) {
const wchar_t *option = xoptions->items[i];
size_t len;
- wchar_t *sep = wcschr(option, L'=');
+ const wchar_t *sep = wcschr(option, L'=');
if (sep != NULL) {
len = (sep - option);
}
@@ -615,7 +615,7 @@ preconfig_init_utf8_mode(PyPreConfig *config, const _PyPreCmdline *cmdline)
const wchar_t *xopt;
xopt = _Py_get_xoption(&cmdline->xoptions, L"utf8");
if (xopt) {
- wchar_t *sep = wcschr(xopt, L'=');
+ const wchar_t *sep = wcschr(xopt, L'=');
if (sep) {
xopt = sep + 1;
if (wcscmp(xopt, L"1") == 0) {
diff --git a/Python/pythonrun.c b/Python/pythonrun.c
index e005a509f6f..91c81ac0d8d 100644
--- a/Python/pythonrun.c
+++ b/Python/pythonrun.c
@@ -1151,6 +1151,7 @@ _PyErr_Display(PyObject *file, PyObject *unused, PyObject *value, PyObject *tb)
"traceback",
"_print_exception_bltin");
if (print_exception_fn == NULL || !PyCallable_Check(print_exception_fn)) {
+ Py_XDECREF(print_exception_fn);
goto fallback;
}
diff --git a/Python/remote_debug.h b/Python/remote_debug.h
index ed213859a8a..df1225f2eda 100644
--- a/Python/remote_debug.h
+++ b/Python/remote_debug.h
@@ -133,6 +133,31 @@ typedef struct {
Py_ssize_t page_size;
} proc_handle_t;
+// Forward declaration for use in validation function
+static int
+_Py_RemoteDebug_ReadRemoteMemory(proc_handle_t *handle, uintptr_t remote_address, size_t len, void* dst);
+
+// Optional callback to validate a candidate section address found during
+// memory map searches. Returns 1 if the address is valid, 0 to skip it.
+// This allows callers to filter out duplicate/stale mappings (e.g. from
+// ctypes dlopen) whose sections were never initialized.
+typedef int (*section_validator_t)(proc_handle_t *handle, uintptr_t address);
+
+// Validate that a candidate address starts with _Py_Debug_Cookie.
+static int
+_Py_RemoteDebug_ValidatePyRuntimeCookie(proc_handle_t *handle, uintptr_t address)
+{
+ if (address == 0) {
+ return 0;
+ }
+ char buf[sizeof(_Py_Debug_Cookie) - 1];
+ if (_Py_RemoteDebug_ReadRemoteMemory(handle, address, sizeof(buf), buf) != 0) {
+ PyErr_Clear();
+ return 0;
+ }
+ return memcmp(buf, _Py_Debug_Cookie, sizeof(buf)) == 0;
+}
+
static void
_Py_RemoteDebug_FreePageCache(proc_handle_t *handle)
{
@@ -490,7 +515,8 @@ pid_to_task(pid_t pid)
}
static uintptr_t
-search_map_for_section(proc_handle_t *handle, const char* secname, const char* substr) {
+search_map_for_section(proc_handle_t *handle, const char* secname, const char* substr,
+ section_validator_t validator) {
mach_vm_address_t address = 0;
mach_vm_size_t size = 0;
mach_msg_type_number_t count = sizeof(vm_region_basic_info_data_64_t);
@@ -542,7 +568,9 @@ search_map_for_section(proc_handle_t *handle, const char* secname, const char* s
if (strncmp(filename, substr, strlen(substr)) == 0) {
uintptr_t result = search_section_in_file(
secname, map_filename, address, size, proc_ref);
- if (result != 0) {
+ if (result != 0
+ && (validator == NULL || validator(handle, result)))
+ {
return result;
}
}
@@ -659,7 +687,8 @@ search_elf_file_for_section(
}
static uintptr_t
-search_linux_map_for_section(proc_handle_t *handle, const char* secname, const char* substr)
+search_linux_map_for_section(proc_handle_t *handle, const char* secname, const char* substr,
+ section_validator_t validator)
{
char maps_file_path[64];
sprintf(maps_file_path, "/proc/%d/maps", handle->pid);
@@ -734,9 +763,12 @@ search_linux_map_for_section(proc_handle_t *handle, const char* secname, const c
if (strstr(filename, substr)) {
retval = search_elf_file_for_section(handle, secname, start, path);
- if (retval) {
+ if (retval
+ && (validator == NULL || validator(handle, retval)))
+ {
break;
}
+ retval = 0;
}
}
@@ -832,7 +864,8 @@ static void* analyze_pe(const wchar_t* mod_path, BYTE* remote_base, const char*
static uintptr_t
-search_windows_map_for_section(proc_handle_t* handle, const char* secname, const wchar_t* substr) {
+search_windows_map_for_section(proc_handle_t* handle, const char* secname, const wchar_t* substr,
+ section_validator_t validator) {
HANDLE hProcSnap;
do {
hProcSnap = CreateToolhelp32Snapshot(TH32CS_SNAPMODULE, handle->pid);
@@ -855,8 +888,11 @@ search_windows_map_for_section(proc_handle_t* handle, const char* secname, const
for (BOOL hasModule = Module32FirstW(hProcSnap, &moduleEntry); hasModule; hasModule = Module32NextW(hProcSnap, &moduleEntry)) {
// Look for either python executable or DLL
if (wcsstr(moduleEntry.szModule, substr)) {
- runtime_addr = analyze_pe(moduleEntry.szExePath, moduleEntry.modBaseAddr, secname);
- if (runtime_addr != NULL) {
+ void *candidate = analyze_pe(moduleEntry.szExePath, moduleEntry.modBaseAddr, secname);
+ if (candidate != NULL
+ && (validator == NULL || validator(handle, (uintptr_t)candidate)))
+ {
+ runtime_addr = candidate;
break;
}
}
@@ -877,7 +913,8 @@ _Py_RemoteDebug_GetPyRuntimeAddress(proc_handle_t* handle)
#ifdef MS_WINDOWS
// On Windows, search for 'python' in executable or DLL
- address = search_windows_map_for_section(handle, "PyRuntime", L"python");
+ address = search_windows_map_for_section(handle, "PyRuntime", L"python",
+ _Py_RemoteDebug_ValidatePyRuntimeCookie);
if (address == 0) {
// Error out: 'python' substring covers both executable and DLL
PyObject *exc = PyErr_GetRaisedException();
@@ -888,7 +925,8 @@ _Py_RemoteDebug_GetPyRuntimeAddress(proc_handle_t* handle)
}
#elif defined(__linux__)
// On Linux, search for 'python' in executable or DLL
- address = search_linux_map_for_section(handle, "PyRuntime", "python");
+ address = search_linux_map_for_section(handle, "PyRuntime", "python",
+ _Py_RemoteDebug_ValidatePyRuntimeCookie);
if (address == 0) {
// Error out: 'python' substring covers both executable and DLL
PyObject *exc = PyErr_GetRaisedException();
@@ -902,7 +940,8 @@ _Py_RemoteDebug_GetPyRuntimeAddress(proc_handle_t* handle)
const char* candidates[] = {"libpython", "python", "Python", NULL};
for (const char** candidate = candidates; *candidate; candidate++) {
PyErr_Clear();
- address = search_map_for_section(handle, "PyRuntime", *candidate);
+ address = search_map_for_section(handle, "PyRuntime", *candidate,
+ _Py_RemoteDebug_ValidatePyRuntimeCookie);
if (address != 0) {
break;
}
@@ -1095,6 +1134,7 @@ _Py_RemoteDebug_PagedReadRemoteMemory(proc_handle_t *handle,
if (entry->data == NULL) {
entry->data = PyMem_RawMalloc(page_size);
if (entry->data == NULL) {
+ PyErr_NoMemory();
_set_debug_exception_cause(PyExc_MemoryError,
"Cannot allocate %zu bytes for page cache entry "
"during read from PID %d at address 0x%lx",
@@ -1104,7 +1144,7 @@ _Py_RemoteDebug_PagedReadRemoteMemory(proc_handle_t *handle,
}
if (_Py_RemoteDebug_ReadRemoteMemory(handle, page_base, page_size, entry->data) < 0) {
- // Try to just copy the exact ammount as a fallback
+ // Try to just copy the exact amount as a fallback
PyErr_Clear();
goto fallback;
}
diff --git a/Python/symtable.c b/Python/symtable.c
index f633e281019..549ef131388 100644
--- a/Python/symtable.c
+++ b/Python/symtable.c
@@ -806,6 +806,8 @@ inline_comprehension(PySTEntryObject *ste, PySTEntryObject *comp,
PyObject *k, *v;
Py_ssize_t pos = 0;
int remove_dunder_class = 0;
+ int remove_dunder_classdict = 0;
+ int remove_dunder_cond_annotations = 0;
while (PyDict_Next(comp->ste_symbols, &pos, &k, &v)) {
// skip comprehension parameter
@@ -828,15 +830,27 @@ inline_comprehension(PySTEntryObject *ste, PySTEntryObject *comp,
if (existing == NULL && PyErr_Occurred()) {
return 0;
}
- // __class__ is never allowed to be free through a class scope (see
+ // __class__, __classdict__ and __conditional_annotations__ are
+ // never allowed to be free through a class scope (see
// drop_class_free)
if (scope == FREE && ste->ste_type == ClassBlock &&
- _PyUnicode_EqualToASCIIString(k, "__class__")) {
+ (_PyUnicode_EqualToASCIIString(k, "__class__") ||
+ _PyUnicode_EqualToASCIIString(k, "__classdict__") ||
+ _PyUnicode_EqualToASCIIString(k, "__conditional_annotations__"))) {
scope = GLOBAL_IMPLICIT;
if (PySet_Discard(comp_free, k) < 0) {
return 0;
}
- remove_dunder_class = 1;
+
+ if (_PyUnicode_EqualToASCIIString(k, "__class__")) {
+ remove_dunder_class = 1;
+ }
+ else if (_PyUnicode_EqualToASCIIString(k, "__conditional_annotations__")) {
+ remove_dunder_cond_annotations = 1;
+ }
+ else {
+ remove_dunder_classdict = 1;
+ }
}
if (!existing) {
// name does not exist in scope, copy from comprehension
@@ -876,6 +890,12 @@ inline_comprehension(PySTEntryObject *ste, PySTEntryObject *comp,
if (remove_dunder_class && PyDict_DelItemString(comp->ste_symbols, "__class__") < 0) {
return 0;
}
+ if (remove_dunder_classdict && PyDict_DelItemString(comp->ste_symbols, "__classdict__") < 0) {
+ return 0;
+ }
+ if (remove_dunder_cond_annotations && PyDict_DelItemString(comp->ste_symbols, "__conditional_annotations__") < 0) {
+ return 0;
+ }
return 1;
}
diff --git a/Python/sysmodule.c b/Python/sysmodule.c
index 545b130836e..c97042c99fa 100644
--- a/Python/sysmodule.c
+++ b/Python/sysmodule.c
@@ -1759,7 +1759,7 @@ sys_getwindowsversion_impl(PyObject *module)
PyObject *realVersion = _sys_getwindowsversion_from_kernel32();
if (!realVersion) {
if (!PyErr_ExceptionMatches(PyExc_WindowsError)) {
- return NULL;
+ goto error;
}
PyErr_Clear();
diff --git a/Python/tracemalloc.c b/Python/tracemalloc.c
index 8ae12e54576..4795068d0a0 100644
--- a/Python/tracemalloc.c
+++ b/Python/tracemalloc.c
@@ -224,13 +224,20 @@ tracemalloc_get_frame(_PyInterpreterFrame *pyframe, frame_t *frame)
assert(PyStackRef_CodeCheck(pyframe->f_executable));
frame->filename = &_Py_STR(anon_unknown);
- int lineno = PyUnstable_InterpreterFrame_GetLine(pyframe);
+ int lineno = -1;
+ PyCodeObject *code = _PyFrame_GetCode(pyframe);
+ // PyUnstable_InterpreterFrame_GetLine() cannot but used, since it uses
+ // a critical section which can trigger a deadlock.
+ int lasti = _PyFrame_SafeGetLasti(pyframe);
+ if (lasti >= 0) {
+ lineno = _PyCode_SafeAddr2Line(code, lasti);
+ }
if (lineno < 0) {
lineno = 0;
}
frame->lineno = (unsigned int)lineno;
- PyObject *filename = filename = _PyFrame_GetCode(pyframe)->co_filename;
+ PyObject *filename = code->co_filename;
if (filename == NULL) {
#ifdef TRACE_DEBUG
tracemalloc_error("failed to get the filename of the code object");
@@ -853,7 +860,8 @@ _PyTraceMalloc_Stop(void)
TABLES_LOCK();
if (!tracemalloc_config.tracing) {
- goto done;
+ TABLES_UNLOCK();
+ return;
}
/* stop tracing Python memory allocations */
@@ -870,10 +878,12 @@ _PyTraceMalloc_Stop(void)
raw_free(tracemalloc_traceback);
tracemalloc_traceback = NULL;
- (void)PyRefTracer_SetTracer(NULL, NULL);
-
-done:
TABLES_UNLOCK();
+
+ // Call it after TABLES_UNLOCK() since it calls _PyEval_StopTheWorldAll()
+ // which would lead to a deadlock with TABLES_LOCK() which doesn't detach
+ // the thread state.
+ (void)PyRefTracer_SetTracer(NULL, NULL);
}
diff --git a/Tools/build/compute-changes.py b/Tools/build/compute-changes.py
index 88b7856b9c7..090fd759224 100644
--- a/Tools/build/compute-changes.py
+++ b/Tools/build/compute-changes.py
@@ -225,16 +225,27 @@ def process_changed_files(changed_files: Set[Path]) -> Outputs:
if file.parent == GITHUB_WORKFLOWS_PATH:
if file.name in ("build.yml", "reusable-cifuzz.yml"):
- run_tests = run_ci_fuzz = run_ci_fuzz_stdlib = True
+ run_tests = run_ci_fuzz = run_ci_fuzz_stdlib = run_windows_tests = True
has_platform_specific_change = False
+ continue
if file.name == "reusable-docs.yml":
run_docs = True
+ continue
+ if file.name == "reusable-windows.yml":
+ run_tests = True
+ run_windows_tests = True
+ continue
if file.name == "reusable-windows-msi.yml":
run_windows_msi = True
+ continue
if file.name == "reusable-macos.yml":
+ run_tests = True
platforms_changed.add("macos")
+ continue
if file.name == "reusable-wasi.yml":
+ run_tests = True
platforms_changed.add("wasi")
+ continue
if not doc_file and file not in RUN_TESTS_IGNORE:
run_tests = True
diff --git a/Tools/check-c-api-docs/ignored_c_api.txt b/Tools/check-c-api-docs/ignored_c_api.txt
index c23784d7e11..1477774a6d2 100644
--- a/Tools/check-c-api-docs/ignored_c_api.txt
+++ b/Tools/check-c-api-docs/ignored_c_api.txt
@@ -20,26 +20,12 @@ Py_UTF8Mode
Py_HASH_EXTERNAL
# modsupport.h
PyABIInfo_FREETHREADING_AGNOSTIC
-# moduleobject.h
-PyModuleDef_Type
# object.h
Py_INVALID_SIZE
-Py_TPFLAGS_HAVE_VERSION_TAG
-Py_TPFLAGS_INLINE_VALUES
-Py_TPFLAGS_IS_ABSTRACT
# pyexpat.h
PyExpat_CAPI_MAGIC
PyExpat_CAPSULE_NAME
# pyport.h
-Py_ALIGNED
-Py_ARITHMETIC_RIGHT_SHIFT
-Py_CAN_START_THREADS
-Py_FORCE_EXPANSION
-Py_GCC_ATTRIBUTE
-Py_LL
-Py_SAFE_DOWNCAST
-Py_ULL
-Py_VA_COPY
PYLONG_BITS_IN_DIGIT
PY_DWORD_MAX
PY_FORMAT_SIZE_T
diff --git a/Tools/ftscalingbench/ftscalingbench.py b/Tools/ftscalingbench/ftscalingbench.py
index b815376b7ed..cc7d8575f5c 100644
--- a/Tools/ftscalingbench/ftscalingbench.py
+++ b/Tools/ftscalingbench/ftscalingbench.py
@@ -201,6 +201,23 @@ def instantiate_dataclass():
for _ in range(1000 * WORK_SCALE):
obj = MyDataClass(x=1, y=2, z=3)
+@register_benchmark
+def super_call():
+ # TODO: super() on the same class from multiple threads still doesn't
+ # scale well, so use a class per-thread here for now.
+ class Base:
+ def method(self):
+ return 1
+
+ class Derived(Base):
+ def method(self):
+ return super().method()
+
+ obj = Derived()
+ for _ in range(1000 * WORK_SCALE):
+ obj.method()
+
+
def bench_one_thread(func):
t0 = time.perf_counter_ns()
func()
diff --git a/Tools/ssl/multissltests.py b/Tools/ssl/multissltests.py
index ab9840c1c52..86baf8a3a74 100755
--- a/Tools/ssl/multissltests.py
+++ b/Tools/ssl/multissltests.py
@@ -45,14 +45,15 @@
OPENSSL_OLD_VERSIONS = [
"1.1.1w",
"3.1.8",
+ "3.2.6",
]
OPENSSL_RECENT_VERSIONS = [
- "3.0.18",
- "3.2.6",
- "3.3.5",
- "3.4.3",
- "3.5.4",
+ "3.0.19",
+ "3.3.6",
+ "3.4.4",
+ "3.5.5",
+ "3.6.1",
# See make_ssl_data.py for notes on adding a new version.
]
diff --git a/Tools/unicode/makeunicodedata.py b/Tools/unicode/makeunicodedata.py
index d4cca68c3e3..6b1d7da26e2 100644
--- a/Tools/unicode/makeunicodedata.py
+++ b/Tools/unicode/makeunicodedata.py
@@ -99,18 +99,13 @@
CASED_MASK = 0x2000
EXTENDED_CASE_MASK = 0x4000
-# these ranges need to match unicodedata.c:is_unified_ideograph
-cjk_ranges = [
- ('3400', '4DBF'), # CJK Ideograph Extension A CJK
- ('4E00', '9FFF'), # CJK Ideograph
- ('20000', '2A6DF'), # CJK Ideograph Extension B
- ('2A700', '2B739'), # CJK Ideograph Extension C
- ('2B740', '2B81D'), # CJK Ideograph Extension D
- ('2B820', '2CEA1'), # CJK Ideograph Extension E
- ('2CEB0', '2EBE0'), # CJK Ideograph Extension F
- ('2EBF0', '2EE5D'), # CJK Ideograph Extension I
- ('30000', '3134A'), # CJK Ideograph Extension G
- ('31350', '323AF'), # CJK Ideograph Extension H
+# Maps the range names in UnicodeData.txt to prefixes for
+# derived names specified by rule NR2.
+# Hangul should always be at index 0, since it uses special format.
+derived_name_range_names = [
+ ("Hangul Syllable", "HANGUL SYLLABLE "),
+ ("CJK Ideograph", "CJK UNIFIED IDEOGRAPH-"),
+ ("Tangut Ideograph", "TANGUT IDEOGRAPH-"),
]
@@ -124,7 +119,7 @@ def maketables(trace=0):
for version in old_versions:
print("--- Reading", UNICODE_DATA % ("-"+version), "...")
- old_unicode = UnicodeData(version, cjk_check=False)
+ old_unicode = UnicodeData(version, ideograph_check=False)
print(len(list(filter(None, old_unicode.table))), "characters")
merge_old_version(version, unicode, old_unicode)
@@ -698,6 +693,23 @@ def makeunicodename(unicode, trace):
fprint(' {%d, {%s}},' % (len(sequence), seq_str))
fprint('};')
+ fprint(dedent("""
+ typedef struct {
+ Py_UCS4 first;
+ Py_UCS4 last;
+ int prefixid;
+ } derived_name_range;
+ """))
+
+ fprint('static const derived_name_range derived_name_ranges[] = {')
+ for name_range in unicode.derived_name_ranges:
+ fprint(' {0x%s, 0x%s, %d},' % name_range)
+ fprint('};')
+
+ fprint('static const char * const derived_name_prefixes[] = {')
+ for _, prefix in derived_name_range_names:
+ fprint(' "%s",' % prefix)
+ fprint('};')
def merge_old_version(version, new, old):
# Changes to exclusion file not implemented yet
@@ -905,14 +917,14 @@ def from_row(row: List[str]) -> UcdRecord:
class UnicodeData:
# table: List[Optional[UcdRecord]] # index is codepoint; None means unassigned
- def __init__(self, version, cjk_check=True):
+ def __init__(self, version, ideograph_check=True):
self.changed = []
table = [None] * 0x110000
for s in UcdFile(UNICODE_DATA, version):
char = int(s[0], 16)
table[char] = from_row(s)
- cjk_ranges_found = []
+ self.derived_name_ranges = []
# expand first-last ranges
field = None
@@ -926,15 +938,15 @@ def __init__(self, version, cjk_check=True):
s.name = ""
field = dataclasses.astuple(s)[:15]
elif s.name[-5:] == "Last>":
- if s.name.startswith("<CJK Ideograph"):
- cjk_ranges_found.append((field[0],
- s.codepoint))
+ for j, (rangename, _) in enumerate(derived_name_range_names):
+ if s.name.startswith("<" + rangename):
+ self.derived_name_ranges.append(
+ (field[0], s.codepoint, j))
+ break
s.name = ""
field = None
elif field:
table[i] = from_row(('%X' % i,) + field[1:])
- if cjk_check and cjk_ranges != cjk_ranges_found:
- raise ValueError("CJK ranges deviate: have %r" % cjk_ranges_found)
# public attributes
self.filename = UNICODE_DATA % ''
diff --git a/Tools/wasm/emscripten/__main__.py b/Tools/wasm/emscripten/__main__.py
index c88e9edba6d..b1a779777ae 100644
--- a/Tools/wasm/emscripten/__main__.py
+++ b/Tools/wasm/emscripten/__main__.py
@@ -4,6 +4,7 @@
import contextlib
import functools
import hashlib
+import json
import os
import shutil
import subprocess
@@ -14,6 +15,8 @@
from textwrap import dedent
from urllib.request import urlopen
+import tomllib
+
try:
from os import process_cpu_count as cpu_count
except ImportError:
@@ -22,21 +25,96 @@
EMSCRIPTEN_DIR = Path(__file__).parent
CHECKOUT = EMSCRIPTEN_DIR.parent.parent.parent
+CONFIG_FILE = EMSCRIPTEN_DIR / "config.toml"
-CROSS_BUILD_DIR = CHECKOUT / "cross-build"
-NATIVE_BUILD_DIR = CROSS_BUILD_DIR / "build"
+DEFAULT_CROSS_BUILD_DIR = CHECKOUT / "cross-build"
HOST_TRIPLE = "wasm32-emscripten"
-DOWNLOAD_DIR = CROSS_BUILD_DIR / HOST_TRIPLE / "build"
-HOST_BUILD_DIR = CROSS_BUILD_DIR / HOST_TRIPLE / "build"
-HOST_DIR = HOST_BUILD_DIR / "python"
-PREFIX_DIR = CROSS_BUILD_DIR / HOST_TRIPLE / "prefix"
+
+@functools.cache
+def load_config_toml():
+ with CONFIG_FILE.open("rb") as file:
+ return tomllib.load(file)
+
+
+@functools.cache
+def required_emscripten_version():
+ return load_config_toml()["emscripten-version"]
+
+
+@functools.cache
+def emsdk_cache_root(emsdk_cache):
+ required_version = required_emscripten_version()
+ return Path(emsdk_cache).absolute() / required_version
+
+
+@functools.cache
+def emsdk_activate_path(emsdk_cache):
+ return emsdk_cache_root(emsdk_cache) / "emsdk/emsdk_env.sh"
+
+
+def get_build_paths(cross_build_dir=None, emsdk_cache=None):
+ """Compute all build paths from the given cross-build directory."""
+ if cross_build_dir is None:
+ cross_build_dir = DEFAULT_CROSS_BUILD_DIR
+ cross_build_dir = Path(cross_build_dir).absolute()
+ host_triple_dir = cross_build_dir / HOST_TRIPLE
+ prefix_dir = host_triple_dir / "prefix"
+ if emsdk_cache:
+ prefix_dir = emsdk_cache_root(emsdk_cache) / "prefix"
+
+ return {
+ "cross_build_dir": cross_build_dir,
+ "native_build_dir": cross_build_dir / "build",
+ "host_triple_dir": host_triple_dir,
+ "host_build_dir": host_triple_dir / "build",
+ "host_dir": host_triple_dir / "build" / "python",
+ "prefix_dir": prefix_dir,
+ }
+
LOCAL_SETUP = CHECKOUT / "Modules" / "Setup.local"
LOCAL_SETUP_MARKER = b"# Generated by Tools/wasm/emscripten.py\n"
-def updated_env(updates={}):
+def validate_emsdk_version(emsdk_cache):
+ """Validate that the emsdk cache contains the required emscripten version."""
+ required_version = required_emscripten_version()
+ emsdk_env = emsdk_activate_path(emsdk_cache)
+ if not emsdk_env.is_file():
+ print(
+ f"Required emscripten version {required_version} not found in {emsdk_cache}",
+ file=sys.stderr,
+ )
+ sys.exit(1)
+ print(f"✅ Emscripten version {required_version} found in {emsdk_cache}")
+
+
+def parse_env(text):
+ result = {}
+ for line in text.splitlines():
+ key, val = line.split("=", 1)
+ result[key] = val
+ return result
+
+
+@functools.cache
+def get_emsdk_environ(emsdk_cache):
+ """Returns os.environ updated by sourcing emsdk_env.sh"""
+ if not emsdk_cache:
+ return os.environ
+ env_text = subprocess.check_output(
+ [
+ "bash",
+ "-c",
+ f"EMSDK_QUIET=1 source {emsdk_activate_path(emsdk_cache)} && env",
+ ],
+ text=True,
+ )
+ return parse_env(env_text)
+
+
+def updated_env(updates, emsdk_cache):
"""Create a new dict representing the environment to use.
The changes made to the execution environment are printed out.
@@ -52,8 +130,7 @@ def updated_env(updates={}):
except subprocess.CalledProcessError:
pass # Might be building from a tarball.
# This layering lets SOURCE_DATE_EPOCH from os.environ takes precedence.
- environment = env_defaults | os.environ | updates
-
+ environment = env_defaults | get_emsdk_environ(emsdk_cache) | updates
env_diff = {}
for key, value in environment.items():
if os.environ.get(key) != value:
@@ -66,12 +143,17 @@ def updated_env(updates={}):
return environment
-def subdir(working_dir, *, clean_ok=False):
- """Decorator to change to a working directory."""
+def subdir(path_key, *, clean_ok=False):
+ """Decorator to change to a working directory.
+
+ path_key is a key into context.build_paths, used to resolve the working
+ directory at call time.
+ """
def decorator(func):
@functools.wraps(func)
def wrapper(context):
+ working_dir = context.build_paths[path_key]
try:
tput_output = subprocess.check_output(
["tput", "cols"], encoding="utf-8"
@@ -128,20 +210,50 @@ def build_platform():
return sysconfig.get_config_var("BUILD_GNU_TYPE")
-def build_python_path():
+def build_python_path(context):
"""The path to the build Python binary."""
- binary = NATIVE_BUILD_DIR / "python"
+ native_build_dir = context.build_paths["native_build_dir"]
+ binary = native_build_dir / "python"
if not binary.is_file():
binary = binary.with_suffix(".exe")
if not binary.is_file():
raise FileNotFoundError(
- f"Unable to find `python(.exe)` in {NATIVE_BUILD_DIR}"
+ f"Unable to find `python(.exe)` in {native_build_dir}"
)
return binary
-@subdir(NATIVE_BUILD_DIR, clean_ok=True)
+def install_emscripten(context):
+ emsdk_cache = context.emsdk_cache
+ if emsdk_cache is None:
+ print("install-emscripten requires --emsdk-cache", file=sys.stderr)
+ sys.exit(1)
+ version = required_emscripten_version()
+ emsdk_target = emsdk_cache_root(emsdk_cache) / "emsdk"
+ if emsdk_target.exists():
+ if not context.quiet:
+ print(f"Emscripten version {version} already installed")
+ return
+ if not context.quiet:
+ print(f"Installing emscripten version {version}")
+ emsdk_target.mkdir(parents=True)
+ call(
+ [
+ "git",
+ "clone",
+ "https://github.com/emscripten-core/emsdk.git",
+ emsdk_target,
+ ],
+ quiet=context.quiet,
+ )
+ call([emsdk_target / "emsdk", "install", version], quiet=context.quiet)
+ call([emsdk_target / "emsdk", "activate", version], quiet=context.quiet)
+ if not context.quiet:
+ print(f"Installed emscripten version {version}")
+
+
+@subdir("native_build_dir", clean_ok=True)
def configure_build_python(context, working_dir):
"""Configure the build/host Python."""
if LOCAL_SETUP.exists():
@@ -157,12 +269,12 @@ def configure_build_python(context, working_dir):
call(configure, quiet=context.quiet)
-@subdir(NATIVE_BUILD_DIR)
+@subdir("native_build_dir")
def make_build_python(context, working_dir):
"""Make/build the build Python."""
call(["make", "--jobs", str(cpu_count()), "all"], quiet=context.quiet)
- binary = build_python_path()
+ binary = build_python_path(context)
cmd = [
binary,
"-c",
@@ -192,33 +304,87 @@ def download_and_unpack(working_dir: Path, url: str, expected_shasum: str):
shutil.unpack_archive(tmp_file.name, working_dir)
-@subdir(HOST_BUILD_DIR, clean_ok=True)
+def should_build_library(prefix, name, config, quiet):
+ cached_config = prefix / (name + ".json")
+ if not cached_config.exists():
+ if not quiet:
+ print(
+ f"No cached build of {name} version {config['version']} found, building"
+ )
+ return True
+
+ try:
+ with cached_config.open("rb") as f:
+ cached_config = json.load(f)
+ except json.JSONDecodeError:
+ if not quiet:
+ print(f"Cached data for {name} invalid, rebuilding")
+ return True
+ if config == cached_config:
+ if not quiet:
+ print(
+ f"Found cached build of {name} version {config['version']}, not rebuilding"
+ )
+ return False
+
+ if not quiet:
+ print(
+ f"Found cached build of {name} version {config['version']} but it's out of date, rebuilding"
+ )
+ return True
+
+
+def write_library_config(prefix, name, config, quiet):
+ cached_config = prefix / (name + ".json")
+ with cached_config.open("w") as f:
+ json.dump(config, f)
+ if not quiet:
+ print(f"Succeded building {name}, wrote config to {cached_config}")
+
+
+@subdir("host_build_dir", clean_ok=True)
def make_emscripten_libffi(context, working_dir):
- ver = "3.4.6"
- libffi_dir = working_dir / f"libffi-{ver}"
+ prefix = context.build_paths["prefix_dir"]
+ libffi_config = load_config_toml()["libffi"]
+ if not should_build_library(
+ prefix, "libffi", libffi_config, context.quiet
+ ):
+ return
+ url = libffi_config["url"]
+ version = libffi_config["version"]
+ shasum = libffi_config["shasum"]
+ libffi_dir = working_dir / f"libffi-{version}"
shutil.rmtree(libffi_dir, ignore_errors=True)
download_and_unpack(
working_dir,
- f"https://github.com/libffi/libffi/releases/download/v{ver}/libffi-{ver}.tar.gz",
- "b0dea9df23c863a7a50e825440f3ebffabd65df1497108e5d437747843895a4e",
+ url.format(version=version),
+ shasum,
)
call(
[EMSCRIPTEN_DIR / "make_libffi.sh"],
- env=updated_env({"PREFIX": PREFIX_DIR}),
+ env=updated_env({"PREFIX": prefix}, context.emsdk_cache),
cwd=libffi_dir,
quiet=context.quiet,
)
+ write_library_config(prefix, "libffi", libffi_config, context.quiet)
-@subdir(HOST_BUILD_DIR, clean_ok=True)
+@subdir("host_build_dir", clean_ok=True)
def make_mpdec(context, working_dir):
- ver = "4.0.1"
- mpdec_dir = working_dir / f"mpdecimal-{ver}"
+ prefix = context.build_paths["prefix_dir"]
+ mpdec_config = load_config_toml()["mpdec"]
+ if not should_build_library(prefix, "mpdec", mpdec_config, context.quiet):
+ return
+
+ url = mpdec_config["url"]
+ version = mpdec_config["version"]
+ shasum = mpdec_config["shasum"]
+ mpdec_dir = working_dir / f"mpdecimal-{version}"
shutil.rmtree(mpdec_dir, ignore_errors=True)
download_and_unpack(
working_dir,
- f"https://www.bytereef.org/software/mpdecimal/releases/mpdecimal-{ver}.tar.gz",
- "96d33abb4bb0070c7be0fed4246cd38416188325f820468214471938545b1ac8",
+ url.format(version=version),
+ shasum,
)
call(
[
@@ -226,27 +392,30 @@ def make_mpdec(context, working_dir):
mpdec_dir / "configure",
"CFLAGS=-fPIC",
"--prefix",
- PREFIX_DIR,
+ prefix,
"--disable-shared",
],
cwd=mpdec_dir,
quiet=context.quiet,
+ env=updated_env({}, context.emsdk_cache),
)
call(
["make", "install"],
cwd=mpdec_dir,
quiet=context.quiet,
)
+ write_library_config(prefix, "mpdec", mpdec_config, context.quiet)
-@subdir(HOST_DIR, clean_ok=True)
+@subdir("host_dir", clean_ok=True)
def configure_emscripten_python(context, working_dir):
"""Configure the emscripten/host build."""
+ paths = context.build_paths
config_site = os.fsdecode(EMSCRIPTEN_DIR / "config.site-wasm32-emscripten")
emscripten_build_dir = working_dir.relative_to(CHECKOUT)
- python_build_dir = NATIVE_BUILD_DIR / "build"
+ python_build_dir = paths["native_build_dir"] / "build"
lib_dirs = list(python_build_dir.glob("lib.*"))
assert len(lib_dirs) == 1, (
f"Expected a single lib.* directory in {python_build_dir}"
@@ -272,13 +441,13 @@ def configure_emscripten_python(context, working_dir):
capture_output=True,
)
host_runner = res.stdout.strip()
- pkg_config_path_dir = (PREFIX_DIR / "lib/pkgconfig/").resolve()
+ pkg_config_path_dir = (paths["prefix_dir"] / "lib/pkgconfig/").resolve()
env_additions = {
"CONFIG_SITE": config_site,
"HOSTRUNNER": host_runner,
"EM_PKG_CONFIG_PATH": str(pkg_config_path_dir),
}
- build_python = os.fsdecode(build_python_path())
+ build_python = os.fsdecode(build_python_path(context))
configure = [
"emconfigure",
os.path.relpath(CHECKOUT / "configure", working_dir),
@@ -292,7 +461,7 @@ def configure_emscripten_python(context, working_dir):
"--disable-ipv6",
"--enable-big-digits=30",
"--enable-wasm-dynamic-linking",
- f"--prefix={PREFIX_DIR}",
+ f"--prefix={paths['prefix_dir']}",
]
if pydebug:
configure.append("--with-pydebug")
@@ -300,7 +469,7 @@ def configure_emscripten_python(context, working_dir):
configure.extend(context.args)
call(
configure,
- env=updated_env(env_additions),
+ env=updated_env(env_additions, context.emsdk_cache),
quiet=context.quiet,
)
@@ -353,12 +522,12 @@ def configure_emscripten_python(context, working_dir):
sys.stdout.flush()
-@subdir(HOST_DIR)
+@subdir("host_dir")
def make_emscripten_python(context, working_dir):
"""Run `make` for the emscripten/host build."""
call(
["make", "--jobs", str(cpu_count()), "all"],
- env=updated_env(),
+ env=updated_env({}, context.emsdk_cache),
quiet=context.quiet,
)
@@ -366,25 +535,41 @@ def make_emscripten_python(context, working_dir):
subprocess.check_call([exec_script, "--version"])
-def build_all(context):
- """Build everything."""
- steps = [
- configure_build_python,
- make_build_python,
- make_emscripten_libffi,
- make_mpdec,
- configure_emscripten_python,
- make_emscripten_python,
- ]
+def build_target(context):
+ """Build one or more targets."""
+ steps = []
+ if context.target in {"all"}:
+ steps.append(install_emscripten)
+ if context.target in {"build", "all"}:
+ steps.extend([
+ configure_build_python,
+ make_build_python,
+ ])
+ if context.target in {"host", "all"}:
+ steps.extend([
+ make_emscripten_libffi,
+ make_mpdec,
+ configure_emscripten_python,
+ make_emscripten_python,
+ ])
+
for step in steps:
step(context)
def clean_contents(context):
"""Delete all files created by this script."""
- if CROSS_BUILD_DIR.exists():
- print(f"🧹 Deleting {CROSS_BUILD_DIR} ...")
- shutil.rmtree(CROSS_BUILD_DIR)
+ if context.target in {"all", "build"}:
+ build_dir = context.build_paths["native_build_dir"]
+ if build_dir.exists():
+ print(f"🧹 Deleting {build_dir} ...")
+ shutil.rmtree(build_dir)
+
+ if context.target in {"all", "host"}:
+ host_triple_dir = context.build_paths["host_triple_dir"]
+ if host_triple_dir.exists():
+ print(f"🧹 Deleting {host_triple_dir} ...")
+ shutil.rmtree(host_triple_dir)
if LOCAL_SETUP.exists():
with LOCAL_SETUP.open("rb") as file:
@@ -397,7 +582,22 @@ def main():
parser = argparse.ArgumentParser()
subcommands = parser.add_subparsers(dest="subcommand")
+ install_emscripten_cmd = subcommands.add_parser(
+ "install-emscripten",
+ help="Install the appropriate version of Emscripten",
+ )
build = subcommands.add_parser("build", help="Build everything")
+ build.add_argument(
+ "target",
+ nargs="?",
+ default="all",
+ choices=["all", "host", "build"],
+ help=(
+ "What should be built. 'build' for just the build platform, or "
+ "'host' for the host platform, or 'all' for both. Defaults to 'all'."
+ ),
+ )
+
configure_build = subcommands.add_parser(
"configure-build-python", help="Run `configure` for the build Python"
)
@@ -422,7 +622,19 @@ def main():
clean = subcommands.add_parser(
"clean", help="Delete files and directories created by this script"
)
+ clean.add_argument(
+ "target",
+ nargs="?",
+ default="host",
+ choices=["all", "host", "build"],
+ help=(
+ "What should be cleaned. 'build' for just the build platform, or "
+ "'host' for the host platform, or 'all' for both. Defaults to 'host'."
+ ),
+ )
+
for subcommand in (
+ install_emscripten_cmd,
build,
configure_build,
make_libffi_cmd,
@@ -439,6 +651,22 @@ def main():
dest="quiet",
help="Redirect output from subprocesses to a log file",
)
+ subcommand.add_argument(
+ "--cross-build-dir",
+ action="store",
+ default=None,
+ dest="cross_build_dir",
+ help="Path to the cross-build directory "
+ f"(default: {DEFAULT_CROSS_BUILD_DIR})",
+ )
+ subcommand.add_argument(
+ "--emsdk-cache",
+ action="store",
+ default=None,
+ dest="emsdk_cache",
+ help="Path to emsdk cache directory. If provided, validates that "
+ "the required emscripten version is installed.",
+ )
for subcommand in configure_build, configure_host:
subcommand.add_argument(
"--clean",
@@ -463,14 +691,25 @@ def main():
context = parser.parse_args()
+ if context.emsdk_cache and context.subcommand != "install-emscripten":
+ validate_emsdk_version(context.emsdk_cache)
+ context.emsdk_cache = Path(context.emsdk_cache).absolute()
+ else:
+ print("Build will use EMSDK from current environment.")
+
+ context.build_paths = get_build_paths(
+ context.cross_build_dir, context.emsdk_cache
+ )
+
dispatch = {
+ "install-emscripten": install_emscripten,
"make-libffi": make_emscripten_libffi,
"make-mpdec": make_mpdec,
"configure-build-python": configure_build_python,
"make-build-python": make_build_python,
"configure-host": configure_emscripten_python,
"make-host": make_emscripten_python,
- "build": build_all,
+ "build": build_target,
"clean": clean_contents,
}
diff --git a/Tools/wasm/emscripten/config.toml b/Tools/wasm/emscripten/config.toml
new file mode 100644
index 00000000000..98edaebe992
--- /dev/null
+++ b/Tools/wasm/emscripten/config.toml
@@ -0,0 +1,14 @@
+# Any data that can vary between Python versions is to be kept in this file.
+# This allows for blanket copying of the Emscripten build code between supported
+# Python versions.
+emscripten-version = "4.0.12"
+
+[libffi]
+url = "https://github.com/libffi/libffi/releases/download/v{version}/libffi-{version}.tar.gz"
+version = "3.4.6"
+shasum = "b0dea9df23c863a7a50e825440f3ebffabd65df1497108e5d437747843895a4e"
+
+[mpdec]
+url = "https://www.bytereef.org/software/mpdecimal/releases/mpdecimal-{version}.tar.gz"
+version = "4.0.1"
+shasum = "96d33abb4bb0070c7be0fed4246cd38416188325f820468214471938545b1ac8"
diff --git a/configure.ac b/configure.ac
index d81c76fc122..ec93a743817 100644
--- a/configure.ac
+++ b/configure.ac
@@ -2344,7 +2344,7 @@ AS_CASE([$ac_sys_system],
dnl Include file system support
AS_VAR_APPEND([LINKFORSHARED], [" -sFORCE_FILESYSTEM -lidbfs.js -lnodefs.js -lproxyfs.js -lworkerfs.js"])
AS_VAR_APPEND([LINKFORSHARED], [" -sEXPORTED_RUNTIME_METHODS=FS,callMain,ENV,HEAPU32,TTY"])
- AS_VAR_APPEND([LINKFORSHARED], [" -sEXPORTED_FUNCTIONS=_main,_Py_Version,__PyRuntime,_PyGILState_GetThisThreadState,__Py_DumpTraceback"])
+ AS_VAR_APPEND([LINKFORSHARED], [" -sEXPORTED_FUNCTIONS=_main,_Py_Version,__PyRuntime,_PyGILState_GetThisThreadState,__Py_DumpTraceback,__PyEM_EMSCRIPTEN_TRAMPOLINE_OFFSET"])
AS_VAR_APPEND([LINKFORSHARED], [" -sSTACK_SIZE=5MB"])
dnl Avoid bugs in JS fallback string decoding path
AS_VAR_APPEND([LINKFORSHARED], [" -sTEXTDECODER=2"])
|