This file is indexed.

/usr/share/doc/python-setuptools-doc/html/setuptools.html is in python-setuptools-doc 33.1.1-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

   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
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Building and Distributing Packages with Setuptools &#8212; Setuptools documentation</title>
    
    <link rel="stylesheet" href="_static/nature.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '33.1.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="search" title="Search" href="search.html" />
    <link rel="top" title="Setuptools documentation" href="index.html" />
    <link rel="next" title="Easy Install" href="easy_install.html" />
    <link rel="prev" title="Welcome to Setuptools’ documentation!" href="index.html" /> 
  </head>
  <body role="document">
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="easy_install.html" title="Easy Install"
             accesskey="N">next</a></li>
        <li class="right" >
          <a href="index.html" title="Welcome to Setuptools’ documentation!"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">Setuptools</a> &#187;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="building-and-distributing-packages-with-setuptools">
<h1><a class="toc-backref" href="#id3">Building and Distributing Packages with Setuptools</a><a class="headerlink" href="#building-and-distributing-packages-with-setuptools" title="Permalink to this headline"></a></h1>
<p><code class="docutils literal"><span class="pre">Setuptools</span></code> is a collection of enhancements to the Python <code class="docutils literal"><span class="pre">distutils</span></code>
(for Python 2.6 and up) that allow developers to more easily build and
distribute Python packages, especially ones that have dependencies on other
packages.</p>
<p>Packages built and distributed using <code class="docutils literal"><span class="pre">setuptools</span></code> look to the user like
ordinary Python packages based on the <code class="docutils literal"><span class="pre">distutils</span></code>.  Your users don&#8217;t need to
install or even know about setuptools in order to use them, and you don&#8217;t
have to include the entire setuptools package in your distributions.  By
including just a single <a class="reference external" href="https://bootstrap.pypa.io/ez_setup.py">bootstrap module</a> (a 12K .py file), your package will
automatically download and install <code class="docutils literal"><span class="pre">setuptools</span></code> if the user is building your
package from source and doesn&#8217;t have a suitable version already installed.</p>
<p>Feature Highlights:</p>
<ul class="simple">
<li>Automatically find/download/install/upgrade dependencies at build time using
the <a class="reference external" href="easy_install.html">EasyInstall tool</a>,
which supports downloading via HTTP, FTP, Subversion, and SourceForge, and
automatically scans web pages linked from PyPI to find download links.  (It&#8217;s
the closest thing to CPAN currently available for Python.)</li>
<li>Create <a class="reference external" href="http://peak.telecommunity.com/DevCenter/PythonEggs">Python Eggs</a> -
a single-file importable distribution format</li>
<li>Enhanced support for accessing data files hosted in zipped packages.</li>
<li>Automatically include all packages in your source tree, without listing them
individually in setup.py</li>
<li>Automatically include all relevant files in your source distributions,
without needing to create a <code class="docutils literal"><span class="pre">MANIFEST.in</span></code> file, and without having to force
regeneration of the <code class="docutils literal"><span class="pre">MANIFEST</span></code> file when your source tree changes.</li>
<li>Automatically generate wrapper scripts or Windows (console and GUI) .exe
files for any number of &#8220;main&#8221; functions in your project.  (Note: this is not
a py2exe replacement; the .exe files rely on the local Python installation.)</li>
<li>Transparent Pyrex support, so that your setup.py can list <code class="docutils literal"><span class="pre">.pyx</span></code> files and
still work even when the end-user doesn&#8217;t have Pyrex installed (as long as
you include the Pyrex-generated C in your source distribution)</li>
<li>Command aliases - create project-specific, per-user, or site-wide shortcut
names for commonly used commands and options</li>
<li>PyPI upload support - upload your source distributions and eggs to PyPI</li>
<li>Deploy your project in &#8220;development mode&#8221;, such that it&#8217;s available on
<code class="docutils literal"><span class="pre">sys.path</span></code>, yet can still be edited directly from its source checkout.</li>
<li>Easily extend the distutils with new commands or <code class="docutils literal"><span class="pre">setup()</span></code> arguments, and
distribute/reuse your extensions for multiple projects, without copying code.</li>
<li>Create extensible applications and frameworks that automatically discover
extensions, using simple &#8220;entry points&#8221; declared in a project&#8217;s setup script.</li>
</ul>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first"><strong>Table of Contents</strong></p>
<ul class="simple">
<li><a class="reference internal" href="#building-and-distributing-packages-with-setuptools" id="id3">Building and Distributing Packages with Setuptools</a><ul>
<li><a class="reference internal" href="#developer-s-guide" id="id4">Developer&#8217;s Guide</a><ul>
<li><a class="reference internal" href="#installing-setuptools" id="id5">Installing <code class="docutils literal"><span class="pre">setuptools</span></code></a></li>
<li><a class="reference internal" href="#basic-use" id="id6">Basic Use</a><ul>
<li><a class="reference internal" href="#specifying-your-project-s-version" id="id7">Specifying Your Project&#8217;s Version</a></li>
</ul>
</li>
<li><a class="reference internal" href="#new-and-changed-setup-keywords" id="id8">New and Changed <code class="docutils literal"><span class="pre">setup()</span></code> Keywords</a><ul>
<li><a class="reference internal" href="#using-find-packages" id="id9">Using <code class="docutils literal"><span class="pre">find_packages()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#automatic-script-creation" id="id10">Automatic Script Creation</a><ul>
<li><a class="reference internal" href="#eggsecutable-scripts" id="id11">&#8220;Eggsecutable&#8221; Scripts</a></li>
</ul>
</li>
<li><a class="reference internal" href="#declaring-dependencies" id="id12">Declaring Dependencies</a><ul>
<li><a class="reference internal" href="#dependencies-that-aren-t-in-pypi" id="id13">Dependencies that aren&#8217;t in PyPI</a></li>
<li><a class="reference internal" href="#declaring-extras-optional-features-with-their-own-dependencies" id="id14">Declaring &#8220;Extras&#8221; (optional features with their own dependencies)</a></li>
<li><a class="reference internal" href="#declaring-platform-specific-dependencies" id="id15">Declaring platform specific dependencies</a></li>
</ul>
</li>
<li><a class="reference internal" href="#including-data-files" id="id16">Including Data Files</a><ul>
<li><a class="reference internal" href="#accessing-data-files-at-runtime" id="id17">Accessing Data Files at Runtime</a></li>
<li><a class="reference internal" href="#non-package-data-files" id="id18">Non-Package Data Files</a></li>
<li><a class="reference internal" href="#automatic-resource-extraction" id="id19">Automatic Resource Extraction</a></li>
</ul>
</li>
<li><a class="reference internal" href="#extensible-applications-and-frameworks" id="id20">Extensible Applications and Frameworks</a><ul>
<li><a class="reference internal" href="#dynamic-discovery-of-services-and-plugins" id="id21">Dynamic Discovery of Services and Plugins</a></li>
<li><a class="reference internal" href="#defining-additional-metadata" id="id22">Defining Additional Metadata</a></li>
</ul>
</li>
<li><a class="reference internal" href="#development-mode" id="id23">&#8220;Development Mode&#8221;</a></li>
<li><a class="reference internal" href="#distributing-a-setuptools-based-project" id="id24">Distributing a <code class="docutils literal"><span class="pre">setuptools</span></code>-based project</a><ul>
<li><a class="reference internal" href="#using-setuptools-without-bundling-it" id="id25">Using <code class="docutils literal"><span class="pre">setuptools</span></code>...  Without bundling it!</a></li>
<li><a class="reference internal" href="#what-your-users-should-know" id="id26">What Your Users Should Know</a></li>
<li><a class="reference internal" href="#setting-the-zip-safe-flag" id="id27">Setting the <code class="docutils literal"><span class="pre">zip_safe</span></code> flag</a></li>
<li><a class="reference internal" href="#namespace-packages" id="id28">Namespace Packages</a><ul>
<li><a class="reference internal" href="#transitional-note" id="id29">TRANSITIONAL NOTE</a></li>
</ul>
</li>
<li><a class="reference internal" href="#tagging-and-daily-build-or-snapshot-releases" id="id30">Tagging and &#8220;Daily Build&#8221; or &#8220;Snapshot&#8221; Releases</a></li>
<li><a class="reference internal" href="#generating-source-distributions" id="id31">Generating Source Distributions</a></li>
<li><a class="reference internal" href="#making-your-package-available-for-easyinstall" id="id32">Making your package available for EasyInstall</a><ul>
<li><a class="reference internal" href="#making-official-non-snapshot-releases" id="id33">Making &#8220;Official&#8221; (Non-Snapshot) Releases</a></li>
</ul>
</li>
<li><a class="reference internal" href="#distributing-extensions-compiled-with-pyrex" id="id34">Distributing Extensions compiled with Pyrex</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#command-reference" id="id35">Command Reference</a><ul>
<li><a class="reference internal" href="#alias-define-shortcuts-for-commonly-used-commands" id="id36"><code class="docutils literal"><span class="pre">alias</span></code> - Define shortcuts for commonly used commands</a></li>
<li><a class="reference internal" href="#bdist-egg-create-a-python-egg-for-the-project" id="id37"><code class="docutils literal"><span class="pre">bdist_egg</span></code> - Create a Python Egg for the project</a></li>
<li><a class="reference internal" href="#develop-deploy-the-project-source-in-development-mode" id="id38"><code class="docutils literal"><span class="pre">develop</span></code> - Deploy the project source in &#8220;Development Mode&#8221;</a></li>
<li><a class="reference internal" href="#easy-install-find-and-install-packages" id="id39"><code class="docutils literal"><span class="pre">easy_install</span></code> - Find and install packages</a></li>
<li><a class="reference internal" href="#egg-info-create-egg-metadata-and-set-build-tags" id="id40"><code class="docutils literal"><span class="pre">egg_info</span></code> - Create egg metadata and set build tags</a><ul>
<li><a class="reference internal" href="#release-tagging-options" id="id41">Release Tagging Options</a></li>
<li><a class="reference internal" href="#other-egg-info-options" id="id42">Other <code class="docutils literal"><span class="pre">egg_info</span></code> Options</a></li>
<li><a class="reference internal" href="#egg-info-examples" id="id43"><code class="docutils literal"><span class="pre">egg_info</span></code> Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#install-run-easy-install-or-old-style-installation" id="id44"><code class="docutils literal"><span class="pre">install</span></code> - Run <code class="docutils literal"><span class="pre">easy_install</span></code> or old-style installation</a></li>
<li><a class="reference internal" href="#install-egg-info-install-an-egg-info-directory-in-site-packages" id="id45"><code class="docutils literal"><span class="pre">install_egg_info</span></code> - Install an <code class="docutils literal"><span class="pre">.egg-info</span></code> directory in <code class="docutils literal"><span class="pre">site-packages</span></code></a></li>
<li><a class="reference internal" href="#rotate-delete-outdated-distribution-files" id="id46"><code class="docutils literal"><span class="pre">rotate</span></code> - Delete outdated distribution files</a></li>
<li><a class="reference internal" href="#saveopts-save-used-options-to-a-configuration-file" id="id47"><code class="docutils literal"><span class="pre">saveopts</span></code> - Save used options to a configuration file</a><ul>
<li><a class="reference internal" href="#configuration-file-options" id="id48">Configuration File Options</a></li>
</ul>
</li>
<li><a class="reference internal" href="#setopt-set-a-distutils-or-setuptools-option-in-a-config-file" id="id49"><code class="docutils literal"><span class="pre">setopt</span></code> - Set a distutils or setuptools option in a config file</a></li>
<li><a class="reference internal" href="#test-build-package-and-run-a-unittest-suite" id="id50"><code class="docutils literal"><span class="pre">test</span></code> - Build package and run a unittest suite</a></li>
<li><a class="reference internal" href="#upload-upload-source-and-or-egg-distributions-to-pypi" id="id51"><code class="docutils literal"><span class="pre">upload</span></code> - Upload source and/or egg distributions to PyPI</a></li>
</ul>
</li>
<li><a class="reference internal" href="#configuring-setup-using-setup-cfg-files" id="id52">Configuring setup() using setup.cfg files</a><ul>
<li><a class="reference internal" href="#specifying-values" id="id53">Specifying values</a><ul>
<li><a class="reference internal" href="#metadata" id="id54">Metadata</a></li>
<li><a class="reference internal" href="#options" id="id55">Options</a></li>
</ul>
</li>
<li><a class="reference internal" href="#configuration-api" id="id56">Configuration API</a></li>
</ul>
</li>
<li><a class="reference internal" href="#extending-and-reusing-setuptools" id="id57">Extending and Reusing Setuptools</a><ul>
<li><a class="reference internal" href="#creating-distutils-extensions" id="id58">Creating <code class="docutils literal"><span class="pre">distutils</span></code> Extensions</a><ul>
<li><a class="reference internal" href="#adding-commands" id="id59">Adding Commands</a></li>
<li><a class="reference internal" href="#adding-setup-arguments" id="id60">Adding <code class="docutils literal"><span class="pre">setup()</span></code> Arguments</a></li>
<li><a class="reference internal" href="#adding-new-egg-info-files" id="id61">Adding new EGG-INFO Files</a></li>
<li><a class="reference internal" href="#adding-support-for-revision-control-systems" id="id62">Adding Support for Revision Control Systems</a></li>
<li><a class="reference internal" href="#subclassing-command" id="id63">Subclassing <code class="docutils literal"><span class="pre">Command</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#reusing-setuptools-code" id="id64">Reusing <code class="docutils literal"><span class="pre">setuptools</span></code> Code</a><ul>
<li><a class="reference internal" href="#ez-setup" id="id65"><code class="docutils literal"><span class="pre">ez_setup</span></code></a></li>
<li><a class="reference internal" href="#setuptools-archive-util" id="id66"><code class="docutils literal"><span class="pre">setuptools.archive_util</span></code></a></li>
<li><a class="reference internal" href="#setuptools-sandbox" id="id67"><code class="docutils literal"><span class="pre">setuptools.sandbox</span></code></a></li>
<li><a class="reference internal" href="#setuptools-package-index" id="id68"><code class="docutils literal"><span class="pre">setuptools.package_index</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#mailing-list-and-bug-tracker" id="id69">Mailing List and Bug Tracker</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="developer-s-guide">
<h2><a class="toc-backref" href="#id4">Developer&#8217;s Guide</a><a class="headerlink" href="#developer-s-guide" title="Permalink to this headline"></a></h2>
<div class="section" id="installing-setuptools">
<h3><a class="toc-backref" href="#id5">Installing <code class="docutils literal"><span class="pre">setuptools</span></code></a><a class="headerlink" href="#installing-setuptools" title="Permalink to this headline"></a></h3>
<p>Please follow the <a class="reference external" href="easy_install.html#installation-instructions">EasyInstall Installation Instructions</a> to install the
current stable version of setuptools.  In particular, be sure to read the
section on <a class="reference external" href="easy_install.html#custom-installation-locations">Custom Installation Locations</a> if you are installing anywhere
other than Python&#8217;s <code class="docutils literal"><span class="pre">site-packages</span></code> directory.</p>
<p>If you want the current in-development version of setuptools, you should first
install a stable version, and then run:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">ez_setup</span><span class="o">.</span><span class="n">py</span> <span class="n">setuptools</span><span class="o">==</span><span class="n">dev</span>
</pre></div>
</div>
<p>This will download and install the latest development (i.e. unstable) version
of setuptools from the Python Subversion sandbox.</p>
</div>
<div class="section" id="basic-use">
<h3><a class="toc-backref" href="#id6">Basic Use</a><a class="headerlink" href="#basic-use" title="Permalink to this headline"></a></h3>
<p>For basic use of setuptools, just import things from setuptools instead of
the distutils.  Here&#8217;s a minimal setup script using setuptools:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">setuptools</span> <span class="k">import</span> <span class="n">setup</span><span class="p">,</span> <span class="n">find_packages</span>
<span class="n">setup</span><span class="p">(</span>
    <span class="n">name</span><span class="o">=</span><span class="s2">&quot;HelloWorld&quot;</span><span class="p">,</span>
    <span class="n">version</span><span class="o">=</span><span class="s2">&quot;0.1&quot;</span><span class="p">,</span>
    <span class="n">packages</span><span class="o">=</span><span class="n">find_packages</span><span class="p">(),</span>
<span class="p">)</span>
</pre></div>
</div>
<p>As you can see, it doesn&#8217;t take much to use setuptools in a project.
Run that script in your project folder, alongside the Python packages
you have developed.</p>
<p>Invoke that script to produce eggs, upload to
PyPI, and automatically include all packages in the directory where the
setup.py lives.  See the <a class="reference internal" href="#command-reference">Command Reference</a> section below to see what
commands you can give to this setup script. For example,
to produce a source distribution, simply invoke:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">sdist</span>
</pre></div>
</div>
<p>Of course, before you release your project to PyPI, you&#8217;ll want to add a bit
more information to your setup script to help people find or learn about your
project.  And maybe your project will have grown by then to include a few
dependencies, and perhaps some data files and scripts:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">setuptools</span> <span class="k">import</span> <span class="n">setup</span><span class="p">,</span> <span class="n">find_packages</span>
<span class="n">setup</span><span class="p">(</span>
    <span class="n">name</span><span class="o">=</span><span class="s2">&quot;HelloWorld&quot;</span><span class="p">,</span>
    <span class="n">version</span><span class="o">=</span><span class="s2">&quot;0.1&quot;</span><span class="p">,</span>
    <span class="n">packages</span><span class="o">=</span><span class="n">find_packages</span><span class="p">(),</span>
    <span class="n">scripts</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;say_hello.py&#39;</span><span class="p">],</span>

    <span class="c1"># Project uses reStructuredText, so ensure that the docutils get</span>
    <span class="c1"># installed or upgraded on the target machine</span>
    <span class="n">install_requires</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;docutils&gt;=0.3&#39;</span><span class="p">],</span>

    <span class="n">package_data</span><span class="o">=</span><span class="p">{</span>
        <span class="c1"># If any package contains *.txt or *.rst files, include them:</span>
        <span class="s1">&#39;&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;*.txt&#39;</span><span class="p">,</span> <span class="s1">&#39;*.rst&#39;</span><span class="p">],</span>
        <span class="c1"># And include any *.msg files found in the &#39;hello&#39; package, too:</span>
        <span class="s1">&#39;hello&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;*.msg&#39;</span><span class="p">],</span>
    <span class="p">},</span>

    <span class="c1"># metadata for upload to PyPI</span>
    <span class="n">author</span><span class="o">=</span><span class="s2">&quot;Me&quot;</span><span class="p">,</span>
    <span class="n">author_email</span><span class="o">=</span><span class="s2">&quot;me@example.com&quot;</span><span class="p">,</span>
    <span class="n">description</span><span class="o">=</span><span class="s2">&quot;This is an Example Package&quot;</span><span class="p">,</span>
    <span class="n">license</span><span class="o">=</span><span class="s2">&quot;PSF&quot;</span><span class="p">,</span>
    <span class="n">keywords</span><span class="o">=</span><span class="s2">&quot;hello world example examples&quot;</span><span class="p">,</span>
    <span class="n">url</span><span class="o">=</span><span class="s2">&quot;http://example.com/HelloWorld/&quot;</span><span class="p">,</span>   <span class="c1"># project home page, if any</span>

    <span class="c1"># could also include long_description, download_url, classifiers, etc.</span>
<span class="p">)</span>
</pre></div>
</div>
<p>In the sections that follow, we&#8217;ll explain what most of these <code class="docutils literal"><span class="pre">setup()</span></code>
arguments do (except for the metadata ones), and the various ways you might use
them in your own project(s).</p>
<div class="section" id="specifying-your-project-s-version">
<h4><a class="toc-backref" href="#id7">Specifying Your Project&#8217;s Version</a><a class="headerlink" href="#specifying-your-project-s-version" title="Permalink to this headline"></a></h4>
<p>Setuptools can work well with most versioning schemes; there are, however, a
few special things to watch out for, in order to ensure that setuptools and
EasyInstall can always tell what version of your package is newer than another
version.  Knowing these things will also help you correctly specify what
versions of other projects your project depends on.</p>
<p>A version consists of an alternating series of release numbers and pre-release
or post-release tags.  A release number is a series of digits punctuated by
dots, such as <code class="docutils literal"><span class="pre">2.4</span></code> or <code class="docutils literal"><span class="pre">0.5</span></code>.  Each series of digits is treated
numerically, so releases <code class="docutils literal"><span class="pre">2.1</span></code> and <code class="docutils literal"><span class="pre">2.1.0</span></code> are different ways to spell the
same release number, denoting the first subrelease of release 2.  But  <code class="docutils literal"><span class="pre">2.10</span></code>
is the <em>tenth</em> subrelease of release 2, and so is a different and newer release
from <code class="docutils literal"><span class="pre">2.1</span></code> or <code class="docutils literal"><span class="pre">2.1.0</span></code>.  Leading zeros within a series of digits are also
ignored, so <code class="docutils literal"><span class="pre">2.01</span></code> is the same as <code class="docutils literal"><span class="pre">2.1</span></code>, and different from <code class="docutils literal"><span class="pre">2.0.1</span></code>.</p>
<p>Following a release number, you can have either a pre-release or post-release
tag.  Pre-release tags make a version be considered <em>older</em> than the version
they are appended to.  So, revision <code class="docutils literal"><span class="pre">2.4</span></code> is <em>newer</em> than revision <code class="docutils literal"><span class="pre">2.4c1</span></code>,
which in turn is newer than <code class="docutils literal"><span class="pre">2.4b1</span></code> or <code class="docutils literal"><span class="pre">2.4a1</span></code>.  Postrelease tags make
a version be considered <em>newer</em> than the version they are appended to.  So,
revisions like <code class="docutils literal"><span class="pre">2.4-1</span></code> and <code class="docutils literal"><span class="pre">2.4pl3</span></code> are newer than <code class="docutils literal"><span class="pre">2.4</span></code>, but are <em>older</em>
than <code class="docutils literal"><span class="pre">2.4.1</span></code> (which has a higher release number).</p>
<p>A pre-release tag is a series of letters that are alphabetically before
&#8220;final&#8221;.  Some examples of prerelease tags would include <code class="docutils literal"><span class="pre">alpha</span></code>, <code class="docutils literal"><span class="pre">beta</span></code>,
<code class="docutils literal"><span class="pre">a</span></code>, <code class="docutils literal"><span class="pre">c</span></code>, <code class="docutils literal"><span class="pre">dev</span></code>, and so on.  You do not have to place a dot or dash
before the prerelease tag if it&#8217;s immediately after a number, but it&#8217;s okay to
do so if you prefer.  Thus, <code class="docutils literal"><span class="pre">2.4c1</span></code> and <code class="docutils literal"><span class="pre">2.4.c1</span></code> and <code class="docutils literal"><span class="pre">2.4-c1</span></code> all
represent release candidate 1 of version <code class="docutils literal"><span class="pre">2.4</span></code>, and are treated as identical
by setuptools.</p>
<p>In addition, there are three special prerelease tags that are treated as if
they were the letter <code class="docutils literal"><span class="pre">c</span></code>: <code class="docutils literal"><span class="pre">pre</span></code>, <code class="docutils literal"><span class="pre">preview</span></code>, and <code class="docutils literal"><span class="pre">rc</span></code>.  So, version
<code class="docutils literal"><span class="pre">2.4rc1</span></code>, <code class="docutils literal"><span class="pre">2.4pre1</span></code> and <code class="docutils literal"><span class="pre">2.4preview1</span></code> are all the exact same version as
<code class="docutils literal"><span class="pre">2.4c1</span></code>, and are treated as identical by setuptools.</p>
<p>A post-release tag is either a series of letters that are alphabetically
greater than or equal to &#8220;final&#8221;, or a dash (<code class="docutils literal"><span class="pre">-</span></code>).  Post-release tags are
generally used to separate patch numbers, port numbers, build numbers, revision
numbers, or date stamps from the release number.  For example, the version
<code class="docutils literal"><span class="pre">2.4-r1263</span></code> might denote Subversion revision 1263 of a post-release patch of
version <code class="docutils literal"><span class="pre">2.4</span></code>.  Or you might use <code class="docutils literal"><span class="pre">2.4-20051127</span></code> to denote a date-stamped
post-release.</p>
<p>Notice that after each pre or post-release tag, you are free to place another
release number, followed again by more pre- or post-release tags.  For example,
<code class="docutils literal"><span class="pre">0.6a9.dev-r41475</span></code> could denote Subversion revision 41475 of the in-
development version of the ninth alpha of release 0.6.  Notice that <code class="docutils literal"><span class="pre">dev</span></code> is
a pre-release tag, so this version is a <em>lower</em> version number than <code class="docutils literal"><span class="pre">0.6a9</span></code>,
which would be the actual ninth alpha of release 0.6.  But the <code class="docutils literal"><span class="pre">-r41475</span></code> is
a post-release tag, so this version is <em>newer</em> than <code class="docutils literal"><span class="pre">0.6a9.dev</span></code>.</p>
<p>For the most part, setuptools&#8217; interpretation of version numbers is intuitive,
but here are a few tips that will keep you out of trouble in the corner cases:</p>
<ul>
<li><p class="first">Don&#8217;t stick adjoining pre-release tags together without a dot or number
between them.  Version <code class="docutils literal"><span class="pre">1.9adev</span></code> is the <code class="docutils literal"><span class="pre">adev</span></code> prerelease of <code class="docutils literal"><span class="pre">1.9</span></code>,
<em>not</em> a development pre-release of <code class="docutils literal"><span class="pre">1.9a</span></code>.  Use <code class="docutils literal"><span class="pre">.dev</span></code> instead, as in
<code class="docutils literal"><span class="pre">1.9a.dev</span></code>, or separate the prerelease tags with a number, as in
<code class="docutils literal"><span class="pre">1.9a0dev</span></code>.  <code class="docutils literal"><span class="pre">1.9a.dev</span></code>, <code class="docutils literal"><span class="pre">1.9a0dev</span></code>, and even <code class="docutils literal"><span class="pre">1.9.a.dev</span></code> are
identical versions from setuptools&#8217; point of view, so you can use whatever
scheme you prefer.</p>
</li>
<li><p class="first">If you want to be certain that your chosen numbering scheme works the way
you think it will, you can use the <code class="docutils literal"><span class="pre">pkg_resources.parse_version()</span></code> function
to compare different version numbers:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">pkg_resources</span> <span class="k">import</span> <span class="n">parse_version</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parse_version</span><span class="p">(</span><span class="s1">&#39;1.9.a.dev&#39;</span><span class="p">)</span> <span class="o">==</span> <span class="n">parse_version</span><span class="p">(</span><span class="s1">&#39;1.9a0dev&#39;</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parse_version</span><span class="p">(</span><span class="s1">&#39;2.1-rc2&#39;</span><span class="p">)</span> <span class="o">&lt;</span> <span class="n">parse_version</span><span class="p">(</span><span class="s1">&#39;2.1&#39;</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parse_version</span><span class="p">(</span><span class="s1">&#39;0.6a9dev-r41475&#39;</span><span class="p">)</span> <span class="o">&lt;</span> <span class="n">parse_version</span><span class="p">(</span><span class="s1">&#39;0.6a9&#39;</span><span class="p">)</span>
<span class="go">True</span>
</pre></div>
</div>
</li>
</ul>
<p>Once you&#8217;ve decided on a version numbering scheme for your project, you can
have setuptools automatically tag your in-development releases with various
pre- or post-release tags.  See the following sections for more details:</p>
<ul class="simple">
<li><a class="reference internal" href="#tagging-and-daily-build-or-snapshot-releases">Tagging and &#8220;Daily Build&#8221; or &#8220;Snapshot&#8221; Releases</a></li>
<li><a href="#id70"><span class="problematic" id="id71">`Managing &#8220;Continuous Releases&#8221; Using Subversion`_</span></a></li>
<li>The <a class="reference internal" href="#egg-info">egg_info</a> command</li>
</ul>
</div>
</div>
<div class="section" id="new-and-changed-setup-keywords">
<h3><a class="toc-backref" href="#id8">New and Changed <code class="docutils literal"><span class="pre">setup()</span></code> Keywords</a><a class="headerlink" href="#new-and-changed-setup-keywords" title="Permalink to this headline"></a></h3>
<p>The following keyword arguments to <code class="docutils literal"><span class="pre">setup()</span></code> are added or changed by
<code class="docutils literal"><span class="pre">setuptools</span></code>.  All of them are optional; you do not have to supply them
unless you need the associated <code class="docutils literal"><span class="pre">setuptools</span></code> feature.</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">include_package_data</span></code></dt>
<dd>If set to <code class="docutils literal"><span class="pre">True</span></code>, this tells <code class="docutils literal"><span class="pre">setuptools</span></code> to automatically include any
data files it finds inside your package directories that are specified by
your <code class="docutils literal"><span class="pre">MANIFEST.in</span></code> file.  For more information, see the section below on
<a class="reference internal" href="#including-data-files">Including Data Files</a>.</dd>
<dt><code class="docutils literal"><span class="pre">exclude_package_data</span></code></dt>
<dd>A dictionary mapping package names to lists of glob patterns that should
be <em>excluded</em> from your package directories.  You can use this to trim back
any excess files included by <code class="docutils literal"><span class="pre">include_package_data</span></code>.  For a complete
description and examples, see the section below on <a class="reference internal" href="#including-data-files">Including Data Files</a>.</dd>
<dt><code class="docutils literal"><span class="pre">package_data</span></code></dt>
<dd>A dictionary mapping package names to lists of glob patterns.  For a
complete description and examples, see the section below on <a class="reference internal" href="#including-data-files">Including
Data Files</a>.  You do not need to use this option if you are using
<code class="docutils literal"><span class="pre">include_package_data</span></code>, unless you need to add e.g. files that are
generated by your setup script and build process.  (And are therefore not
in source control or are files that you don&#8217;t want to include in your
source distribution.)</dd>
<dt><code class="docutils literal"><span class="pre">zip_safe</span></code></dt>
<dd>A boolean (True or False) flag specifying whether the project can be
safely installed and run from a zip file.  If this argument is not
supplied, the <code class="docutils literal"><span class="pre">bdist_egg</span></code> command will have to analyze all of your
project&#8217;s contents for possible problems each time it builds an egg.</dd>
<dt><code class="docutils literal"><span class="pre">install_requires</span></code></dt>
<dd>A string or list of strings specifying what other distributions need to
be installed when this one is.  See the section below on <a class="reference internal" href="#declaring-dependencies">Declaring
Dependencies</a> for details and examples of the format of this argument.</dd>
<dt><code class="docutils literal"><span class="pre">entry_points</span></code></dt>
<dd>A dictionary mapping entry point group names to strings or lists of strings
defining the entry points.  Entry points are used to support dynamic
discovery of services or plugins provided by a project.  See <a class="reference internal" href="#dynamic-discovery-of-services-and-plugins">Dynamic
Discovery of Services and Plugins</a> for details and examples of the format
of this argument.  In addition, this keyword is used to support <a class="reference internal" href="#automatic-script-creation">Automatic
Script Creation</a>.</dd>
<dt><code class="docutils literal"><span class="pre">extras_require</span></code></dt>
<dd>A dictionary mapping names of &#8220;extras&#8221; (optional features of your project)
to strings or lists of strings specifying what other distributions must be
installed to support those features.  See the section below on <a class="reference internal" href="#declaring-dependencies">Declaring
Dependencies</a> for details and examples of the format of this argument.</dd>
<dt><code class="docutils literal"><span class="pre">python_requires</span></code></dt>
<dd>A string corresponding to a version specifier (as defined in PEP 440) for
the Python version, used to specify the Requires-Python defined in PEP 345.</dd>
<dt><code class="docutils literal"><span class="pre">setup_requires</span></code></dt>
<dd><p class="first">A string or list of strings specifying what other distributions need to
be present in order for the <em>setup script</em> to run.  <code class="docutils literal"><span class="pre">setuptools</span></code> will
attempt to obtain these (even going so far as to download them using
<code class="docutils literal"><span class="pre">EasyInstall</span></code>) before processing the rest of the setup script or commands.
This argument is needed if you are using distutils extensions as part of
your build process; for example, extensions that process setup() arguments
and turn them into EGG-INFO metadata files.</p>
<p class="last">(Note: projects listed in <code class="docutils literal"><span class="pre">setup_requires</span></code> will NOT be automatically
installed on the system where the setup script is being run.  They are
simply downloaded to the ./.eggs directory if they&#8217;re not locally available
already.  If you want them to be installed, as well as being available
when the setup script is run, you should add them to <code class="docutils literal"><span class="pre">install_requires</span></code>
<strong>and</strong> <code class="docutils literal"><span class="pre">setup_requires</span></code>.)</p>
</dd>
<dt><code class="docutils literal"><span class="pre">dependency_links</span></code></dt>
<dd>A list of strings naming URLs to be searched when satisfying dependencies.
These links will be used if needed to install packages specified by
<code class="docutils literal"><span class="pre">setup_requires</span></code> or <code class="docutils literal"><span class="pre">tests_require</span></code>.  They will also be written into
the egg&#8217;s metadata for use by tools like EasyInstall to use when installing
an <code class="docutils literal"><span class="pre">.egg</span></code> file.</dd>
<dt><code class="docutils literal"><span class="pre">namespace_packages</span></code></dt>
<dd>A list of strings naming the project&#8217;s &#8220;namespace packages&#8221;.  A namespace
package is a package that may be split across multiple project
distributions.  For example, Zope 3&#8217;s <code class="docutils literal"><span class="pre">zope</span></code> package is a namespace
package, because subpackages like <code class="docutils literal"><span class="pre">zope.interface</span></code> and <code class="docutils literal"><span class="pre">zope.publisher</span></code>
may be distributed separately.  The egg runtime system can automatically
merge such subpackages into a single parent package at runtime, as long
as you declare them in each project that contains any subpackages of the
namespace package, and as long as the namespace package&#8217;s <code class="docutils literal"><span class="pre">__init__.py</span></code>
does not contain any code other than a namespace declaration.  See the
section below on <a class="reference internal" href="#namespace-packages">Namespace Packages</a> for more information.</dd>
<dt><code class="docutils literal"><span class="pre">test_suite</span></code></dt>
<dd><p class="first">A string naming a <code class="docutils literal"><span class="pre">unittest.TestCase</span></code> subclass (or a package or module
containing one or more of them, or a method of such a subclass), or naming
a function that can be called with no arguments and returns a
<code class="docutils literal"><span class="pre">unittest.TestSuite</span></code>.  If the named suite is a module, and the module
has an <code class="docutils literal"><span class="pre">additional_tests()</span></code> function, it is called and the results are
added to the tests to be run.  If the named suite is a package, any
submodules and subpackages are recursively added to the overall test suite.</p>
<p class="last">Specifying this argument enables use of the <a class="reference internal" href="#test">test</a> command to run the
specified test suite, e.g. via <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">test</span></code>.  See the section on the
<a class="reference internal" href="#test">test</a> command below for more details.</p>
</dd>
<dt><code class="docutils literal"><span class="pre">tests_require</span></code></dt>
<dd>If your project&#8217;s tests need one or more additional packages besides those
needed to install it, you can use this option to specify them.  It should
be a string or list of strings specifying what other distributions need to
be present for the package&#8217;s tests to run.  When you run the <code class="docutils literal"><span class="pre">test</span></code>
command, <code class="docutils literal"><span class="pre">setuptools</span></code> will  attempt to obtain these (even going
so far as to download them using <code class="docutils literal"><span class="pre">EasyInstall</span></code>).  Note that these
required projects will <em>not</em> be installed on the system where the tests
are run, but only downloaded to the project&#8217;s setup directory if they&#8217;re
not already installed locally.</dd>
</dl>
<dl class="docutils" id="test-loader">
<dt><code class="docutils literal"><span class="pre">test_loader</span></code></dt>
<dd><p class="first">If you would like to use a different way of finding tests to run than what
setuptools normally uses, you can specify a module name and class name in
this argument.  The named class must be instantiable with no arguments, and
its instances must support the <code class="docutils literal"><span class="pre">loadTestsFromNames()</span></code> method as defined
in the Python <code class="docutils literal"><span class="pre">unittest</span></code> module&#8217;s <code class="docutils literal"><span class="pre">TestLoader</span></code> class.  Setuptools will
pass only one test &#8220;name&#8221; in the <cite>names</cite> argument: the value supplied for
the <code class="docutils literal"><span class="pre">test_suite</span></code> argument.  The loader you specify may interpret this
string in any way it likes, as there are no restrictions on what may be
contained in a <code class="docutils literal"><span class="pre">test_suite</span></code> string.</p>
<p>The module name and class name must be separated by a <code class="docutils literal"><span class="pre">:</span></code>.  The default
value of this argument is <code class="docutils literal"><span class="pre">&quot;setuptools.command.test:ScanningLoader&quot;</span></code>.  If
you want to use the default <code class="docutils literal"><span class="pre">unittest</span></code> behavior, you can specify
<code class="docutils literal"><span class="pre">&quot;unittest:TestLoader&quot;</span></code> as your <code class="docutils literal"><span class="pre">test_loader</span></code> argument instead.  This
will prevent automatic scanning of submodules and subpackages.</p>
<p class="last">The module and class you specify here may be contained in another package,
as long as you use the <code class="docutils literal"><span class="pre">tests_require</span></code> option to ensure that the package
containing the loader class is available when the <code class="docutils literal"><span class="pre">test</span></code> command is run.</p>
</dd>
<dt><code class="docutils literal"><span class="pre">eager_resources</span></code></dt>
<dd><p class="first">A list of strings naming resources that should be extracted together, if
any of them is needed, or if any C extensions included in the project are
imported.  This argument is only useful if the project will be installed as
a zipfile, and there is a need to have all of the listed resources be
extracted to the filesystem <em>as a unit</em>.  Resources listed here
should be &#8216;/&#8217;-separated paths, relative to the source root, so to list a
resource <code class="docutils literal"><span class="pre">foo.png</span></code> in package <code class="docutils literal"><span class="pre">bar.baz</span></code>, you would include the string
<code class="docutils literal"><span class="pre">bar/baz/foo.png</span></code> in this argument.</p>
<p class="last">If you only need to obtain resources one at a time, or you don&#8217;t have any C
extensions that access other files in the project (such as data files or
shared libraries), you probably do NOT need this argument and shouldn&#8217;t
mess with it.  For more details on how this argument works, see the section
below on <a class="reference internal" href="#automatic-resource-extraction">Automatic Resource Extraction</a>.</p>
</dd>
<dt><code class="docutils literal"><span class="pre">use_2to3</span></code></dt>
<dd>Convert the source code from Python 2 to Python 3 with 2to3 during the
build process. See <a class="reference internal" href="python3.html"><span class="doc">Supporting both Python 2 and Python 3 with Setuptools</span></a> for more details.</dd>
<dt><code class="docutils literal"><span class="pre">convert_2to3_doctests</span></code></dt>
<dd>List of doctest source files that need to be converted with 2to3.
See <a class="reference internal" href="python3.html"><span class="doc">Supporting both Python 2 and Python 3 with Setuptools</span></a> for more details.</dd>
<dt><code class="docutils literal"><span class="pre">use_2to3_fixers</span></code></dt>
<dd>A list of modules to search for additional fixers to be used during
the 2to3 conversion. See <a class="reference internal" href="python3.html"><span class="doc">Supporting both Python 2 and Python 3 with Setuptools</span></a> for more details.</dd>
</dl>
<div class="section" id="using-find-packages">
<h4><a class="toc-backref" href="#id9">Using <code class="docutils literal"><span class="pre">find_packages()</span></code></a><a class="headerlink" href="#using-find-packages" title="Permalink to this headline"></a></h4>
<p>For simple projects, it&#8217;s usually easy enough to manually add packages to
the <code class="docutils literal"><span class="pre">packages</span></code> argument of <code class="docutils literal"><span class="pre">setup()</span></code>.  However, for very large projects
(Twisted, PEAK, Zope, Chandler, etc.), it can be a big burden to keep the
package list updated.  That&#8217;s what <code class="docutils literal"><span class="pre">setuptools.find_packages()</span></code> is for.</p>
<p><code class="docutils literal"><span class="pre">find_packages()</span></code> takes a source directory and two lists of package name
patterns to exclude and include.  If omitted, the source directory defaults to
the same
directory as the setup script.  Some projects use a <code class="docutils literal"><span class="pre">src</span></code> or <code class="docutils literal"><span class="pre">lib</span></code>
directory as the root of their source tree, and those projects would of course
use <code class="docutils literal"><span class="pre">&quot;src&quot;</span></code> or <code class="docutils literal"><span class="pre">&quot;lib&quot;</span></code> as the first argument to <code class="docutils literal"><span class="pre">find_packages()</span></code>.  (And
such projects also need something like <code class="docutils literal"><span class="pre">package_dir={'':'src'}</span></code> in their
<code class="docutils literal"><span class="pre">setup()</span></code> arguments, but that&#8217;s just a normal distutils thing.)</p>
<p>Anyway, <code class="docutils literal"><span class="pre">find_packages()</span></code> walks the target directory, filtering by inclusion
patterns, and finds Python packages (any directory). On Python 3.2 and
earlier, packages are only recognized if they include an <code class="docutils literal"><span class="pre">__init__.py</span></code> file.
Finally, exclusion patterns are applied to remove matching packages.</p>
<p>Inclusion and exclusion patterns are package names, optionally including
wildcards.  For
example, <code class="docutils literal"><span class="pre">find_packages(exclude=[&quot;*.tests&quot;])</span></code> will exclude all packages whose
last name part is <code class="docutils literal"><span class="pre">tests</span></code>.   Or, <code class="docutils literal"><span class="pre">find_packages(exclude=[&quot;*.tests&quot;,</span>
<span class="pre">&quot;*.tests.*&quot;])</span></code> will also exclude any subpackages of packages named <code class="docutils literal"><span class="pre">tests</span></code>,
but it still won&#8217;t exclude a top-level <code class="docutils literal"><span class="pre">tests</span></code> package or the children
thereof.  In fact, if you really want no <code class="docutils literal"><span class="pre">tests</span></code> packages at all, you&#8217;ll need
something like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">find_packages</span><span class="p">(</span><span class="n">exclude</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;*.tests&quot;</span><span class="p">,</span> <span class="s2">&quot;*.tests.*&quot;</span><span class="p">,</span> <span class="s2">&quot;tests.*&quot;</span><span class="p">,</span> <span class="s2">&quot;tests&quot;</span><span class="p">])</span>
</pre></div>
</div>
<p>in order to cover all the bases.  Really, the exclusion patterns are intended
to cover simpler use cases than this, like excluding a single, specified
package and its subpackages.</p>
<p>Regardless of the parameters, the <code class="docutils literal"><span class="pre">find_packages()</span></code>
function returns a list of package names suitable for use as the <code class="docutils literal"><span class="pre">packages</span></code>
argument to <code class="docutils literal"><span class="pre">setup()</span></code>, and so is usually the easiest way to set that
argument in your setup script.  Especially since it frees you from having to
remember to modify your setup script whenever your project grows additional
top-level packages or subpackages.</p>
</div>
</div>
<div class="section" id="automatic-script-creation">
<h3><a class="toc-backref" href="#id10">Automatic Script Creation</a><a class="headerlink" href="#automatic-script-creation" title="Permalink to this headline"></a></h3>
<p>Packaging and installing scripts can be a bit awkward with the distutils.  For
one thing, there&#8217;s no easy way to have a script&#8217;s filename match local
conventions on both Windows and POSIX platforms.  For another, you often have
to create a separate file just for the &#8220;main&#8221; script, when your actual &#8220;main&#8221;
is a function in a module somewhere.  And even in Python 2.4, using the <code class="docutils literal"><span class="pre">-m</span></code>
option only works for actual <code class="docutils literal"><span class="pre">.py</span></code> files that aren&#8217;t installed in a package.</p>
<p><code class="docutils literal"><span class="pre">setuptools</span></code> fixes all of these problems by automatically generating scripts
for you with the correct extension, and on Windows it will even create an
<code class="docutils literal"><span class="pre">.exe</span></code> file so that users don&#8217;t have to change their <code class="docutils literal"><span class="pre">PATHEXT</span></code> settings.
The way to use this feature is to define &#8220;entry points&#8221; in your setup script
that indicate what function the generated script should import and run.  For
example, to create two console scripts called <code class="docutils literal"><span class="pre">foo</span></code> and <code class="docutils literal"><span class="pre">bar</span></code>, and a GUI
script called <code class="docutils literal"><span class="pre">baz</span></code>, you might do something like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="c1"># other arguments here...</span>
    <span class="n">entry_points</span><span class="o">=</span><span class="p">{</span>
        <span class="s1">&#39;console_scripts&#39;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s1">&#39;foo = my_package.some_module:main_func&#39;</span><span class="p">,</span>
            <span class="s1">&#39;bar = other_module:some_func&#39;</span><span class="p">,</span>
        <span class="p">],</span>
        <span class="s1">&#39;gui_scripts&#39;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s1">&#39;baz = my_package_gui:start_func&#39;</span><span class="p">,</span>
        <span class="p">]</span>
    <span class="p">}</span>
<span class="p">)</span>
</pre></div>
</div>
<p>When this project is installed on non-Windows platforms (using &#8220;setup.py
install&#8221;, &#8220;setup.py develop&#8221;, or by using EasyInstall), a set of <code class="docutils literal"><span class="pre">foo</span></code>,
<code class="docutils literal"><span class="pre">bar</span></code>, and <code class="docutils literal"><span class="pre">baz</span></code> scripts will be installed that import <code class="docutils literal"><span class="pre">main_func</span></code> and
<code class="docutils literal"><span class="pre">some_func</span></code> from the specified modules.  The functions you specify are called
with no arguments, and their return value is passed to <code class="docutils literal"><span class="pre">sys.exit()</span></code>, so you
can return an errorlevel or message to print to stderr.</p>
<p>On Windows, a set of <code class="docutils literal"><span class="pre">foo.exe</span></code>, <code class="docutils literal"><span class="pre">bar.exe</span></code>, and <code class="docutils literal"><span class="pre">baz.exe</span></code> launchers are
created, alongside a set of <code class="docutils literal"><span class="pre">foo.py</span></code>, <code class="docutils literal"><span class="pre">bar.py</span></code>, and <code class="docutils literal"><span class="pre">baz.pyw</span></code> files.  The
<code class="docutils literal"><span class="pre">.exe</span></code> wrappers find and execute the right version of Python to run the
<code class="docutils literal"><span class="pre">.py</span></code> or <code class="docutils literal"><span class="pre">.pyw</span></code> file.</p>
<p>You may define as many &#8220;console script&#8221; and &#8220;gui script&#8221; entry points as you
like, and each one can optionally specify &#8220;extras&#8221; that it depends on, that
will be added to <code class="docutils literal"><span class="pre">sys.path</span></code> when the script is run.  For more information on
&#8220;extras&#8221;, see the section below on <a class="reference internal" href="#declaring-extras">Declaring Extras</a>.  For more information
on &#8220;entry points&#8221; in general, see the section below on <a class="reference internal" href="#dynamic-discovery-of-services-and-plugins">Dynamic Discovery of
Services and Plugins</a>.</p>
<div class="section" id="eggsecutable-scripts">
<h4><a class="toc-backref" href="#id11">&#8220;Eggsecutable&#8221; Scripts</a><a class="headerlink" href="#eggsecutable-scripts" title="Permalink to this headline"></a></h4>
<p>Occasionally, there are situations where it&#8217;s desirable to make an <code class="docutils literal"><span class="pre">.egg</span></code>
file directly executable.  You can do this by including an entry point such
as the following:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="c1"># other arguments here...</span>
    <span class="n">entry_points</span><span class="o">=</span><span class="p">{</span>
        <span class="s1">&#39;setuptools.installation&#39;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s1">&#39;eggsecutable = my_package.some_module:main_func&#39;</span><span class="p">,</span>
        <span class="p">]</span>
    <span class="p">}</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Any eggs built from the above setup script will include a short executable
prelude that imports and calls <code class="docutils literal"><span class="pre">main_func()</span></code> from <code class="docutils literal"><span class="pre">my_package.some_module</span></code>.
The prelude can be run on Unix-like platforms (including Mac and Linux) by
invoking the egg with <code class="docutils literal"><span class="pre">/bin/sh</span></code>, or by enabling execute permissions on the
<code class="docutils literal"><span class="pre">.egg</span></code> file.  For the executable prelude to run, the appropriate version of
Python must be available via the <code class="docutils literal"><span class="pre">PATH</span></code> environment variable, under its
&#8220;long&#8221; name.  That is, if the egg is built for Python 2.3, there must be a
<code class="docutils literal"><span class="pre">python2.3</span></code> executable present in a directory on <code class="docutils literal"><span class="pre">PATH</span></code>.</p>
<p>This feature is primarily intended to support ez_setup the installation of
setuptools itself on non-Windows platforms, but may also be useful for other
projects as well.</p>
<p>IMPORTANT NOTE: Eggs with an &#8220;eggsecutable&#8221; header cannot be renamed, or
invoked via symlinks.  They <em>must</em> be invoked using their original filename, in
order to ensure that, once running, <code class="docutils literal"><span class="pre">pkg_resources</span></code> will know what project
and version is in use.  The header script will check this and exit with an
error if the <code class="docutils literal"><span class="pre">.egg</span></code> file has been renamed or is invoked via a symlink that
changes its base name.</p>
</div>
</div>
<div class="section" id="declaring-dependencies">
<h3><a class="toc-backref" href="#id12">Declaring Dependencies</a><a class="headerlink" href="#declaring-dependencies" title="Permalink to this headline"></a></h3>
<p><code class="docutils literal"><span class="pre">setuptools</span></code> supports automatically installing dependencies when a package is
installed, and including information about dependencies in Python Eggs (so that
package management tools like EasyInstall can use the information).</p>
<p><code class="docutils literal"><span class="pre">setuptools</span></code> and <code class="docutils literal"><span class="pre">pkg_resources</span></code> use a common syntax for specifying a
project&#8217;s required dependencies.  This syntax consists of a project&#8217;s PyPI
name, optionally followed by a comma-separated list of &#8220;extras&#8221; in square
brackets, optionally followed by a comma-separated list of version
specifiers.  A version specifier is one of the operators <code class="docutils literal"><span class="pre">&lt;</span></code>, <code class="docutils literal"><span class="pre">&gt;</span></code>, <code class="docutils literal"><span class="pre">&lt;=</span></code>,
<code class="docutils literal"><span class="pre">&gt;=</span></code>, <code class="docutils literal"><span class="pre">==</span></code> or <code class="docutils literal"><span class="pre">!=</span></code>, followed by a version identifier.  Tokens may be
separated by whitespace, but any whitespace or nonstandard characters within a
project name or version identifier must be replaced with <code class="docutils literal"><span class="pre">-</span></code>.</p>
<p>Version specifiers for a given project are internally sorted into ascending
version order, and used to establish what ranges of versions are acceptable.
Adjacent redundant conditions are also consolidated (e.g. <code class="docutils literal"><span class="pre">&quot;&gt;1,</span> <span class="pre">&gt;2&quot;</span></code> becomes
<code class="docutils literal"><span class="pre">&quot;&gt;1&quot;</span></code>, and <code class="docutils literal"><span class="pre">&quot;&lt;2,&lt;3&quot;</span></code> becomes <code class="docutils literal"><span class="pre">&quot;&lt;3&quot;</span></code>). <code class="docutils literal"><span class="pre">&quot;!=&quot;</span></code> versions are excised from
the ranges they fall within.  A project&#8217;s version is then checked for
membership in the resulting ranges. (Note that providing conflicting conditions
for the same version (e.g. &#8220;&lt;2,&gt;=2&#8221; or &#8220;==2,!=2&#8221;) is meaningless and may
therefore produce bizarre results.)</p>
<p>Here are some example requirement specifiers:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">docutils</span> <span class="o">&gt;=</span> <span class="mf">0.3</span>

<span class="c1"># comment lines and \ continuations are allowed in requirement strings</span>
<span class="n">BazSpam</span> <span class="o">==</span><span class="mf">1.1</span><span class="p">,</span> <span class="o">==</span><span class="mf">1.2</span><span class="p">,</span> <span class="o">==</span><span class="mf">1.3</span><span class="p">,</span> <span class="o">==</span><span class="mf">1.4</span><span class="p">,</span> <span class="o">==</span><span class="mf">1.5</span><span class="p">,</span> \
    <span class="o">==</span><span class="mf">1.6</span><span class="p">,</span> <span class="o">==</span><span class="mf">1.7</span>  <span class="c1"># and so are line-end comments</span>

<span class="n">PEAK</span><span class="p">[</span><span class="n">FastCGI</span><span class="p">,</span> <span class="n">reST</span><span class="p">]</span><span class="o">&gt;=</span><span class="mf">0.5</span><span class="n">a4</span>

<span class="n">setuptools</span><span class="o">==</span><span class="mf">0.5</span><span class="n">a7</span>
</pre></div>
</div>
<p>The simplest way to include requirement specifiers is to use the
<code class="docutils literal"><span class="pre">install_requires</span></code> argument to <code class="docutils literal"><span class="pre">setup()</span></code>.  It takes a string or list of
strings containing requirement specifiers.  If you include more than one
requirement in a string, each requirement must begin on a new line.</p>
<p>This has three effects:</p>
<ol class="arabic simple">
<li>When your project is installed, either by using EasyInstall, <code class="docutils literal"><span class="pre">setup.py</span>
<span class="pre">install</span></code>, or <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">develop</span></code>, all of the dependencies not already
installed will be located (via PyPI), downloaded, built (if necessary),
and installed.</li>
<li>Any scripts in your project will be installed with wrappers that verify
the availability of the specified dependencies at runtime, and ensure that
the correct versions are added to <code class="docutils literal"><span class="pre">sys.path</span></code> (e.g. if multiple versions
have been installed).</li>
<li>Python Egg distributions will include a metadata file listing the
dependencies.</li>
</ol>
<p>Note, by the way, that if you declare your dependencies in <code class="docutils literal"><span class="pre">setup.py</span></code>, you do
<em>not</em> need to use the <code class="docutils literal"><span class="pre">require()</span></code> function in your scripts or modules, as
long as you either install the project or use <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">develop</span></code> to do
development work on it.  (See <a class="reference internal" href="#development-mode">&#8220;Development Mode&#8221;</a> below for more details on
using <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">develop</span></code>.)</p>
<div class="section" id="dependencies-that-aren-t-in-pypi">
<h4><a class="toc-backref" href="#id13">Dependencies that aren&#8217;t in PyPI</a><a class="headerlink" href="#dependencies-that-aren-t-in-pypi" title="Permalink to this headline"></a></h4>
<p>If your project depends on packages that aren&#8217;t registered in PyPI, you may
still be able to depend on them, as long as they are available for download
as:</p>
<ul class="simple">
<li>an egg, in the standard distutils <code class="docutils literal"><span class="pre">sdist</span></code> format,</li>
<li>a single <code class="docutils literal"><span class="pre">.py</span></code> file, or</li>
<li>a VCS repository (Subversion, Mercurial, or Git).</li>
</ul>
<p>You just need to add some URLs to the <code class="docutils literal"><span class="pre">dependency_links</span></code> argument to
<code class="docutils literal"><span class="pre">setup()</span></code>.</p>
<p>The URLs must be either:</p>
<ol class="arabic simple">
<li>direct download URLs,</li>
<li>the URLs of web pages that contain direct download links, or</li>
<li>the repository&#8217;s URL</li>
</ol>
<p>In general, it&#8217;s better to link to web pages, because it is usually less
complex to update a web page than to release a new version of your project.
You can also use a SourceForge <code class="docutils literal"><span class="pre">showfiles.php</span></code> link in the case where a
package you depend on is distributed via SourceForge.</p>
<p>If you depend on a package that&#8217;s distributed as a single <code class="docutils literal"><span class="pre">.py</span></code> file, you
must include an <code class="docutils literal"><span class="pre">&quot;#egg=project-version&quot;</span></code> suffix to the URL, to give a project
name and version number.  (Be sure to escape any dashes in the name or version
by replacing them with underscores.)  EasyInstall will recognize this suffix
and automatically create a trivial <code class="docutils literal"><span class="pre">setup.py</span></code> to wrap the single <code class="docutils literal"><span class="pre">.py</span></code> file
as an egg.</p>
<p>In the case of a VCS checkout, you should also append <code class="docutils literal"><span class="pre">#egg=project-version</span></code>
in order to identify for what package that checkout should be used. You can
append <code class="docutils literal"><span class="pre">&#64;REV</span></code> to the URL&#8217;s path (before the fragment) to specify a revision.
Additionally, you can also force the VCS being used by prepending the URL with
a certain prefix. Currently available are:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">svn+URL</span></code> for Subversion,</li>
<li><code class="docutils literal"><span class="pre">git+URL</span></code> for Git, and</li>
<li><code class="docutils literal"><span class="pre">hg+URL</span></code> for Mercurial</li>
</ul>
<p>A more complete example would be:</p>
<blockquote>
<div><code class="docutils literal"><span class="pre">vcs+proto://host/path&#64;revision#egg=project-version</span></code></div></blockquote>
<p>Be careful with the version. It should match the one inside the project files.
If you want to disregard the version, you have to omit it both in the
<code class="docutils literal"><span class="pre">requires</span></code> and in the URL&#8217;s fragment.</p>
<p>This will do a checkout (or a clone, in Git and Mercurial parlance) to a
temporary folder and run <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">bdist_egg</span></code>.</p>
<p>The <code class="docutils literal"><span class="pre">dependency_links</span></code> option takes the form of a list of URL strings.  For
example, the below will cause EasyInstall to search the specified page for
eggs or source distributions, if the package&#8217;s dependencies aren&#8217;t already
installed:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="o">...</span>
    <span class="n">dependency_links</span><span class="o">=</span><span class="p">[</span>
        <span class="s2">&quot;http://peak.telecommunity.com/snapshots/&quot;</span>
    <span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="declaring-extras-optional-features-with-their-own-dependencies">
<span id="declaring-extras"></span><h4><a class="toc-backref" href="#id14">Declaring &#8220;Extras&#8221; (optional features with their own dependencies)</a><a class="headerlink" href="#declaring-extras-optional-features-with-their-own-dependencies" title="Permalink to this headline"></a></h4>
<p>Sometimes a project has &#8220;recommended&#8221; dependencies, that are not required for
all uses of the project.  For example, a project might offer optional PDF
output if ReportLab is installed, and reStructuredText support if docutils is
installed.  These optional features are called &#8220;extras&#8221;, and setuptools allows
you to define their requirements as well.  In this way, other projects that
require these optional features can force the additional requirements to be
installed, by naming the desired extras in their <code class="docutils literal"><span class="pre">install_requires</span></code>.</p>
<p>For example, let&#8217;s say that Project A offers optional PDF and reST support:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="n">name</span><span class="o">=</span><span class="s2">&quot;Project-A&quot;</span><span class="p">,</span>
    <span class="o">...</span>
    <span class="n">extras_require</span><span class="o">=</span><span class="p">{</span>
        <span class="s1">&#39;PDF&#39;</span><span class="p">:</span>  <span class="p">[</span><span class="s2">&quot;ReportLab&gt;=1.2&quot;</span><span class="p">,</span> <span class="s2">&quot;RXP&quot;</span><span class="p">],</span>
        <span class="s1">&#39;reST&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;docutils&gt;=0.3&quot;</span><span class="p">],</span>
    <span class="p">}</span>
<span class="p">)</span>
</pre></div>
</div>
<p>As you can see, the <code class="docutils literal"><span class="pre">extras_require</span></code> argument takes a dictionary mapping
names of &#8220;extra&#8221; features, to strings or lists of strings describing those
features&#8217; requirements.  These requirements will <em>not</em> be automatically
installed unless another package depends on them (directly or indirectly) by
including the desired &#8220;extras&#8221; in square brackets after the associated project
name.  (Or if the extras were listed in a requirement spec on the EasyInstall
command line.)</p>
<p>Extras can be used by a project&#8217;s <a class="reference internal" href="#entry-points">entry points</a> to specify dynamic
dependencies.  For example, if Project A includes a &#8220;rst2pdf&#8221; script, it might
declare it like this, so that the &#8220;PDF&#8221; requirements are only resolved if the
&#8220;rst2pdf&#8221; script is run:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="n">name</span><span class="o">=</span><span class="s2">&quot;Project-A&quot;</span><span class="p">,</span>
    <span class="o">...</span>
    <span class="n">entry_points</span><span class="o">=</span><span class="p">{</span>
        <span class="s1">&#39;console_scripts&#39;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s1">&#39;rst2pdf = project_a.tools.pdfgen [PDF]&#39;</span><span class="p">,</span>
            <span class="s1">&#39;rst2html = project_a.tools.htmlgen&#39;</span><span class="p">,</span>
            <span class="c1"># more script entry points ...</span>
        <span class="p">],</span>
    <span class="p">}</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Projects can also use another project&#8217;s extras when specifying dependencies.
For example, if project B needs &#8220;project A&#8221; with PDF support installed, it
might declare the dependency like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="n">name</span><span class="o">=</span><span class="s2">&quot;Project-B&quot;</span><span class="p">,</span>
    <span class="n">install_requires</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;Project-A[PDF]&quot;</span><span class="p">],</span>
    <span class="o">...</span>
<span class="p">)</span>
</pre></div>
</div>
<p>This will cause ReportLab to be installed along with project A, if project B is
installed &#8211; even if project A was already installed.  In this way, a project
can encapsulate groups of optional &#8220;downstream dependencies&#8221; under a feature
name, so that packages that depend on it don&#8217;t have to know what the downstream
dependencies are.  If a later version of Project A builds in PDF support and
no longer needs ReportLab, or if it ends up needing other dependencies besides
ReportLab in order to provide PDF support, Project B&#8217;s setup information does
not need to change, but the right packages will still be installed if needed.</p>
<p>Note, by the way, that if a project ends up not needing any other packages to
support a feature, it should keep an empty requirements list for that feature
in its <code class="docutils literal"><span class="pre">extras_require</span></code> argument, so that packages depending on that feature
don&#8217;t break (due to an invalid feature name).  For example, if Project A above
builds in PDF support and no longer needs ReportLab, it could change its
setup to this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="n">name</span><span class="o">=</span><span class="s2">&quot;Project-A&quot;</span><span class="p">,</span>
    <span class="o">...</span>
    <span class="n">extras_require</span><span class="o">=</span><span class="p">{</span>
        <span class="s1">&#39;PDF&#39;</span><span class="p">:</span>  <span class="p">[],</span>
        <span class="s1">&#39;reST&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;docutils&gt;=0.3&quot;</span><span class="p">],</span>
    <span class="p">}</span>
<span class="p">)</span>
</pre></div>
</div>
<p>so that Package B doesn&#8217;t have to remove the <code class="docutils literal"><span class="pre">[PDF]</span></code> from its requirement
specifier.</p>
</div>
<div class="section" id="declaring-platform-specific-dependencies">
<span id="platform-specific-dependencies"></span><h4><a class="toc-backref" href="#id15">Declaring platform specific dependencies</a><a class="headerlink" href="#declaring-platform-specific-dependencies" title="Permalink to this headline"></a></h4>
<p>Sometimes a project might require a dependency to run on a specific platform.
This could to a package that back ports a module so that it can be used in
older python versions.  Or it could be a package that is required to run on a
specific operating system.  This will allow a project to work on multiple
different platforms without installing dependencies that are not required for
a platform that is installing the project.</p>
<p>For example, here is a project that uses the <code class="docutils literal"><span class="pre">enum</span></code> module and <code class="docutils literal"><span class="pre">pywin32</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="n">name</span><span class="o">=</span><span class="s2">&quot;Project&quot;</span><span class="p">,</span>
    <span class="o">...</span>
    <span class="n">install_requires</span><span class="o">=</span><span class="p">[</span>
        <span class="s1">&#39;enum34;python_version&lt;&quot;3.4&quot;&#39;</span><span class="p">,</span>
        <span class="s1">&#39;pywin32 &gt;= 1.0;platform_system==&quot;Windows&quot;&#39;</span>
    <span class="p">]</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Since the <code class="docutils literal"><span class="pre">enum</span></code> module was added in Python 3.4, it should only be installed
if the python version is earlier.  Since <code class="docutils literal"><span class="pre">pywin32</span></code> will only be used on
windows, it should only be installed when the operating system is Windows.
Specifying version requirements for the dependencies is supported as normal.</p>
<p>The environmental markers that may be used for testing platform types are
detailed in <a class="reference external" href="https://www.python.org/dev/peps/pep-0508/">PEP 508</a>.</p>
</div>
</div>
<div class="section" id="including-data-files">
<h3><a class="toc-backref" href="#id16">Including Data Files</a><a class="headerlink" href="#including-data-files" title="Permalink to this headline"></a></h3>
<p>The distutils have traditionally allowed installation of &#8220;data files&#8221;, which
are placed in a platform-specific location.  However, the most common use case
for data files distributed with a package is for use <em>by</em> the package, usually
by including the data files in the package directory.</p>
<p>Setuptools offers three ways to specify data files to be included in your
packages.  First, you can simply use the <code class="docutils literal"><span class="pre">include_package_data</span></code> keyword,
e.g.:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">setuptools</span> <span class="k">import</span> <span class="n">setup</span><span class="p">,</span> <span class="n">find_packages</span>
<span class="n">setup</span><span class="p">(</span>
    <span class="o">...</span>
    <span class="n">include_package_data</span><span class="o">=</span><span class="kc">True</span>
<span class="p">)</span>
</pre></div>
</div>
<p>This tells setuptools to install any data files it finds in your packages.
The data files must be specified via the distutils&#8217; <code class="docutils literal"><span class="pre">MANIFEST.in</span></code> file.
(They can also be tracked by a revision control system, using an appropriate
plugin.  See the section below on <a class="reference internal" href="#adding-support-for-revision-control-systems">Adding Support for Revision Control
Systems</a> for information on how to write such plugins.)</p>
<p>If you want finer-grained control over what files are included (for example,
if you have documentation files in your package directories and want to exclude
them from installation), then you can also use the <code class="docutils literal"><span class="pre">package_data</span></code> keyword,
e.g.:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">setuptools</span> <span class="k">import</span> <span class="n">setup</span><span class="p">,</span> <span class="n">find_packages</span>
<span class="n">setup</span><span class="p">(</span>
    <span class="o">...</span>
    <span class="n">package_data</span><span class="o">=</span><span class="p">{</span>
        <span class="c1"># If any package contains *.txt or *.rst files, include them:</span>
        <span class="s1">&#39;&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;*.txt&#39;</span><span class="p">,</span> <span class="s1">&#39;*.rst&#39;</span><span class="p">],</span>
        <span class="c1"># And include any *.msg files found in the &#39;hello&#39; package, too:</span>
        <span class="s1">&#39;hello&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;*.msg&#39;</span><span class="p">],</span>
    <span class="p">}</span>
<span class="p">)</span>
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">package_data</span></code> argument is a dictionary that maps from package names to
lists of glob patterns.  The globs may include subdirectory names, if the data
files are contained in a subdirectory of the package.  For example, if the
package tree looks like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span>
<span class="n">src</span><span class="o">/</span>
    <span class="n">mypkg</span><span class="o">/</span>
        <span class="n">__init__</span><span class="o">.</span><span class="n">py</span>
        <span class="n">mypkg</span><span class="o">.</span><span class="n">txt</span>
        <span class="n">data</span><span class="o">/</span>
            <span class="n">somefile</span><span class="o">.</span><span class="n">dat</span>
            <span class="n">otherdata</span><span class="o">.</span><span class="n">dat</span>
</pre></div>
</div>
<p>The setuptools setup file might look like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">setuptools</span> <span class="k">import</span> <span class="n">setup</span><span class="p">,</span> <span class="n">find_packages</span>
<span class="n">setup</span><span class="p">(</span>
    <span class="o">...</span>
    <span class="n">packages</span><span class="o">=</span><span class="n">find_packages</span><span class="p">(</span><span class="s1">&#39;src&#39;</span><span class="p">),</span>  <span class="c1"># include all packages under src</span>
    <span class="n">package_dir</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;&#39;</span><span class="p">:</span><span class="s1">&#39;src&#39;</span><span class="p">},</span>   <span class="c1"># tell distutils packages are under src</span>

    <span class="n">package_data</span><span class="o">=</span><span class="p">{</span>
        <span class="c1"># If any package contains *.txt files, include them:</span>
        <span class="s1">&#39;&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;*.txt&#39;</span><span class="p">],</span>
        <span class="c1"># And include any *.dat files found in the &#39;data&#39; subdirectory</span>
        <span class="c1"># of the &#39;mypkg&#39; package, also:</span>
        <span class="s1">&#39;mypkg&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;data/*.dat&#39;</span><span class="p">],</span>
    <span class="p">}</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Notice that if you list patterns in <code class="docutils literal"><span class="pre">package_data</span></code> under the empty string,
these patterns are used to find files in every package, even ones that also
have their own patterns listed.  Thus, in the above example, the <code class="docutils literal"><span class="pre">mypkg.txt</span></code>
file gets included even though it&#8217;s not listed in the patterns for <code class="docutils literal"><span class="pre">mypkg</span></code>.</p>
<p>Also notice that if you use paths, you <em>must</em> use a forward slash (<code class="docutils literal"><span class="pre">/</span></code>) as
the path separator, even if you are on Windows.  Setuptools automatically
converts slashes to appropriate platform-specific separators at build time.</p>
<p>(Note: although the <code class="docutils literal"><span class="pre">package_data</span></code> argument was previously only available in
<code class="docutils literal"><span class="pre">setuptools</span></code>, it was also added to the Python <code class="docutils literal"><span class="pre">distutils</span></code> package as of
Python 2.4; there is <a class="reference external" href="http://docs.python.org/dist/node11.html">some documentation for the feature</a> available on the
python.org website.  If using the setuptools-specific <code class="docutils literal"><span class="pre">include_package_data</span></code>
argument, files specified by <code class="docutils literal"><span class="pre">package_data</span></code> will <em>not</em> be automatically
added to the manifest unless they are listed in the MANIFEST.in file.)</p>
<p>Sometimes, the <code class="docutils literal"><span class="pre">include_package_data</span></code> or <code class="docutils literal"><span class="pre">package_data</span></code> options alone
aren&#8217;t sufficient to precisely define what files you want included.  For
example, you may want to include package README files in your revision control
system and source distributions, but exclude them from being installed.  So,
setuptools offers an <code class="docutils literal"><span class="pre">exclude_package_data</span></code> option as well, that allows you
to do things like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">setuptools</span> <span class="k">import</span> <span class="n">setup</span><span class="p">,</span> <span class="n">find_packages</span>
<span class="n">setup</span><span class="p">(</span>
    <span class="o">...</span>
    <span class="n">packages</span><span class="o">=</span><span class="n">find_packages</span><span class="p">(</span><span class="s1">&#39;src&#39;</span><span class="p">),</span>  <span class="c1"># include all packages under src</span>
    <span class="n">package_dir</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;&#39;</span><span class="p">:</span><span class="s1">&#39;src&#39;</span><span class="p">},</span>   <span class="c1"># tell distutils packages are under src</span>

    <span class="n">include_package_data</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>    <span class="c1"># include everything in source control</span>

    <span class="c1"># ...but exclude README.txt from all packages</span>
    <span class="n">exclude_package_data</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;README.txt&#39;</span><span class="p">]},</span>
<span class="p">)</span>
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">exclude_package_data</span></code> option is a dictionary mapping package names to
lists of wildcard patterns, just like the <code class="docutils literal"><span class="pre">package_data</span></code> option.  And, just
as with that option, a key of <code class="docutils literal"><span class="pre">''</span></code> will apply the given pattern(s) to all
packages.  However, any files that match these patterns will be <em>excluded</em>
from installation, even if they were listed in <code class="docutils literal"><span class="pre">package_data</span></code> or were
included as a result of using <code class="docutils literal"><span class="pre">include_package_data</span></code>.</p>
<p>In summary, the three options allow you to:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">include_package_data</span></code></dt>
<dd>Accept all data files and directories matched by <code class="docutils literal"><span class="pre">MANIFEST.in</span></code>.</dd>
<dt><code class="docutils literal"><span class="pre">package_data</span></code></dt>
<dd>Specify additional patterns to match files and directories that may or may
not be matched by <code class="docutils literal"><span class="pre">MANIFEST.in</span></code> or found in source control.</dd>
<dt><code class="docutils literal"><span class="pre">exclude_package_data</span></code></dt>
<dd>Specify patterns for data files and directories that should <em>not</em> be
included when a package is installed, even if they would otherwise have
been included due to the use of the preceding options.</dd>
</dl>
<p>NOTE: Due to the way the distutils build process works, a data file that you
include in your project and then stop including may be &#8220;orphaned&#8221; in your
project&#8217;s build directories, requiring you to run <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">clean</span> <span class="pre">--all</span></code> to
fully remove them.  This may also be important for your users and contributors
if they track intermediate revisions of your project using Subversion; be sure
to let them know when you make changes that remove files from inclusion so they
can run <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">clean</span> <span class="pre">--all</span></code>.</p>
<div class="section" id="accessing-data-files-at-runtime">
<h4><a class="toc-backref" href="#id17">Accessing Data Files at Runtime</a><a class="headerlink" href="#accessing-data-files-at-runtime" title="Permalink to this headline"></a></h4>
<p>Typically, existing programs manipulate a package&#8217;s <code class="docutils literal"><span class="pre">__file__</span></code> attribute in
order to find the location of data files.  However, this manipulation isn&#8217;t
compatible with PEP 302-based import hooks, including importing from zip files
and Python Eggs.  It is strongly recommended that, if you are using data files,
you should use the <a class="reference external" href="http://peak.telecommunity.com/DevCenter/PkgResources#resourcemanager-api">Resource Management API</a> of <code class="docutils literal"><span class="pre">pkg_resources</span></code> to access
them.  The <code class="docutils literal"><span class="pre">pkg_resources</span></code> module is distributed as part of setuptools, so if
you&#8217;re using setuptools to distribute your package, there is no reason not to
use its resource management API.  See also <a class="reference external" href="http://peak.telecommunity.com/DevCenter/PythonEggs#accessing-package-resources">Accessing Package Resources</a> for
a quick example of converting code that uses <code class="docutils literal"><span class="pre">__file__</span></code> to use
<code class="docutils literal"><span class="pre">pkg_resources</span></code> instead.</p>
</div>
<div class="section" id="non-package-data-files">
<h4><a class="toc-backref" href="#id18">Non-Package Data Files</a><a class="headerlink" href="#non-package-data-files" title="Permalink to this headline"></a></h4>
<p>The <code class="docutils literal"><span class="pre">distutils</span></code> normally install general &#8220;data files&#8221; to a platform-specific
location (e.g. <code class="docutils literal"><span class="pre">/usr/share</span></code>).  This feature intended to be used for things
like documentation, example configuration files, and the like.  <code class="docutils literal"><span class="pre">setuptools</span></code>
does not install these data files in a separate location, however.  They are
bundled inside the egg file or directory, alongside the Python modules and
packages.  The data files can also be accessed using the <a class="reference external" href="http://peak.telecommunity.com/DevCenter/PkgResources#resourcemanager-api">Resource Management
API</a>, by specifying a <code class="docutils literal"><span class="pre">Requirement</span></code> instead of a package name:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">pkg_resources</span> <span class="k">import</span> <span class="n">Requirement</span><span class="p">,</span> <span class="n">resource_filename</span>
<span class="n">filename</span> <span class="o">=</span> <span class="n">resource_filename</span><span class="p">(</span><span class="n">Requirement</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="s2">&quot;MyProject&quot;</span><span class="p">),</span><span class="s2">&quot;sample.conf&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>The above code will obtain the filename of the &#8220;sample.conf&#8221; file in the data
root of the &#8220;MyProject&#8221; distribution.</p>
<p>Note, by the way, that this encapsulation of data files means that you can&#8217;t
actually install data files to some arbitrary location on a user&#8217;s machine;
this is a feature, not a bug.  You can always include a script in your
distribution that extracts and copies your the documentation or data files to
a user-specified location, at their discretion.  If you put related data files
in a single directory, you can use <code class="docutils literal"><span class="pre">resource_filename()</span></code> with the directory
name to get a filesystem directory that then can be copied with the <code class="docutils literal"><span class="pre">shutil</span></code>
module.  (Even if your package is installed as a zipfile, calling
<code class="docutils literal"><span class="pre">resource_filename()</span></code> on a directory will return an actual filesystem
directory, whose contents will be that entire subtree of your distribution.)</p>
<p>(Of course, if you&#8217;re writing a new package, you can just as easily place your
data files or directories inside one of your packages, rather than using the
distutils&#8217; approach.  However, if you&#8217;re updating an existing application, it
may be simpler not to change the way it currently specifies these data files.)</p>
</div>
<div class="section" id="automatic-resource-extraction">
<h4><a class="toc-backref" href="#id19">Automatic Resource Extraction</a><a class="headerlink" href="#automatic-resource-extraction" title="Permalink to this headline"></a></h4>
<p>If you are using tools that expect your resources to be &#8220;real&#8221; files, or your
project includes non-extension native libraries or other files that your C
extensions expect to be able to access, you may need to list those files in
the <code class="docutils literal"><span class="pre">eager_resources</span></code> argument to <code class="docutils literal"><span class="pre">setup()</span></code>, so that the files will be
extracted together, whenever a C extension in the project is imported.</p>
<p>This is especially important if your project includes shared libraries <em>other</em>
than distutils-built C extensions, and those shared libraries use file
extensions other than <code class="docutils literal"><span class="pre">.dll</span></code>, <code class="docutils literal"><span class="pre">.so</span></code>, or <code class="docutils literal"><span class="pre">.dylib</span></code>, which are the
extensions that setuptools 0.6a8 and higher automatically detects as shared
libraries and adds to the <code class="docutils literal"><span class="pre">native_libs.txt</span></code> file for you.  Any shared
libraries whose names do not end with one of those extensions should be listed
as <code class="docutils literal"><span class="pre">eager_resources</span></code>, because they need to be present in the filesystem when
he C extensions that link to them are used.</p>
<p>The <code class="docutils literal"><span class="pre">pkg_resources</span></code> runtime for compressed packages will automatically
extract <em>all</em> C extensions and <code class="docutils literal"><span class="pre">eager_resources</span></code> at the same time, whenever
<em>any</em> C extension or eager resource is requested via the <code class="docutils literal"><span class="pre">resource_filename()</span></code>
API.  (C extensions are imported using <code class="docutils literal"><span class="pre">resource_filename()</span></code> internally.)
This ensures that C extensions will see all of the &#8220;real&#8221; files that they
expect to see.</p>
<p>Note also that you can list directory resource names in <code class="docutils literal"><span class="pre">eager_resources</span></code> as
well, in which case the directory&#8217;s contents (including subdirectories) will be
extracted whenever any C extension or eager resource is requested.</p>
<p>Please note that if you&#8217;re not sure whether you need to use this argument, you
don&#8217;t!  It&#8217;s really intended to support projects with lots of non-Python
dependencies and as a last resort for crufty projects that can&#8217;t otherwise
handle being compressed.  If your package is pure Python, Python plus data
files, or Python plus C, you really don&#8217;t need this.  You&#8217;ve got to be using
either C or an external program that needs &#8220;real&#8221; files in your project before
there&#8217;s any possibility of <code class="docutils literal"><span class="pre">eager_resources</span></code> being relevant to your project.</p>
</div>
</div>
<div class="section" id="extensible-applications-and-frameworks">
<h3><a class="toc-backref" href="#id20">Extensible Applications and Frameworks</a><a class="headerlink" href="#extensible-applications-and-frameworks" title="Permalink to this headline"></a></h3>
<div class="section" id="dynamic-discovery-of-services-and-plugins">
<span id="entry-points"></span><h4><a class="toc-backref" href="#id21">Dynamic Discovery of Services and Plugins</a><a class="headerlink" href="#dynamic-discovery-of-services-and-plugins" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal"><span class="pre">setuptools</span></code> supports creating libraries that &#8220;plug in&#8221; to extensible
applications and frameworks, by letting you register &#8220;entry points&#8221; in your
project that can be imported by the application or framework.</p>
<p>For example, suppose that a blogging tool wants to support plugins
that provide translation for various file types to the blog&#8217;s output format.
The framework might define an &#8220;entry point group&#8221; called <code class="docutils literal"><span class="pre">blogtool.parsers</span></code>,
and then allow plugins to register entry points for the file extensions they
support.</p>
<p>This would allow people to create distributions that contain one or more
parsers for different file types, and then the blogging tool would be able to
find the parsers at runtime by looking up an entry point for the file
extension (or mime type, or however it wants to).</p>
<p>Note that if the blogging tool includes parsers for certain file formats, it
can register these as entry points in its own setup script, which means it
doesn&#8217;t have to special-case its built-in formats.  They can just be treated
the same as any other plugin&#8217;s entry points would be.</p>
<p>If you&#8217;re creating a project that plugs in to an existing application or
framework, you&#8217;ll need to know what entry points or entry point groups are
defined by that application or framework.  Then, you can register entry points
in your setup script.  Here are a few examples of ways you might register an
<code class="docutils literal"><span class="pre">.rst</span></code> file parser entry point in the <code class="docutils literal"><span class="pre">blogtool.parsers</span></code> entry point group,
for our hypothetical blogging tool:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="c1"># ...</span>
    <span class="n">entry_points</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;blogtool.parsers&#39;</span><span class="p">:</span> <span class="s1">&#39;.rst = some_module:SomeClass&#39;</span><span class="p">}</span>
<span class="p">)</span>

<span class="n">setup</span><span class="p">(</span>
    <span class="c1"># ...</span>
    <span class="n">entry_points</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;blogtool.parsers&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;.rst = some_module:a_func&#39;</span><span class="p">]}</span>
<span class="p">)</span>

<span class="n">setup</span><span class="p">(</span>
    <span class="c1"># ...</span>
    <span class="n">entry_points</span><span class="o">=</span><span class="s2">&quot;&quot;&quot;</span>
<span class="s2">        [blogtool.parsers]</span>
<span class="s2">        .rst = some.nested.module:SomeClass.some_classmethod [reST]</span>
<span class="s2">    &quot;&quot;&quot;</span><span class="p">,</span>
    <span class="n">extras_require</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">reST</span><span class="o">=</span><span class="s2">&quot;Docutils&gt;=0.3.5&quot;</span><span class="p">)</span>
<span class="p">)</span>
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">entry_points</span></code> argument to <code class="docutils literal"><span class="pre">setup()</span></code> accepts either a string with
<code class="docutils literal"><span class="pre">.ini</span></code>-style sections, or a dictionary mapping entry point group names to
either strings or lists of strings containing entry point specifiers.  An
entry point specifier consists of a name and value, separated by an <code class="docutils literal"><span class="pre">=</span></code>
sign.  The value consists of a dotted module name, optionally followed by a
<code class="docutils literal"><span class="pre">:</span></code> and a dotted identifier naming an object within the module.  It can
also include a bracketed list of &#8220;extras&#8221; that are required for the entry
point to be used.  When the invoking application or framework requests loading
of an entry point, any requirements implied by the associated extras will be
passed to <code class="docutils literal"><span class="pre">pkg_resources.require()</span></code>, so that an appropriate error message
can be displayed if the needed package(s) are missing.  (Of course, the
invoking app or framework can ignore such errors if it wants to make an entry
point optional if a requirement isn&#8217;t installed.)</p>
</div>
<div class="section" id="defining-additional-metadata">
<h4><a class="toc-backref" href="#id22">Defining Additional Metadata</a><a class="headerlink" href="#defining-additional-metadata" title="Permalink to this headline"></a></h4>
<p>Some extensible applications and frameworks may need to define their own kinds
of metadata to include in eggs, which they can then access using the
<code class="docutils literal"><span class="pre">pkg_resources</span></code> metadata APIs.  Ordinarily, this is done by having plugin
developers include additional files in their <code class="docutils literal"><span class="pre">ProjectName.egg-info</span></code>
directory.  However, since it can be tedious to create such files by hand, you
may want to create a distutils extension that will create the necessary files
from arguments to <code class="docutils literal"><span class="pre">setup()</span></code>, in much the same way that <code class="docutils literal"><span class="pre">setuptools</span></code> does
for many of the <code class="docutils literal"><span class="pre">setup()</span></code> arguments it adds.  See the section below on
<a class="reference internal" href="#creating-distutils-extensions">Creating distutils Extensions</a> for more details, especially the subsection on
<a class="reference internal" href="#adding-new-egg-info-files">Adding new EGG-INFO Files</a>.</p>
</div>
</div>
<div class="section" id="development-mode">
<h3><a class="toc-backref" href="#id23">&#8220;Development Mode&#8221;</a><a class="headerlink" href="#development-mode" title="Permalink to this headline"></a></h3>
<p>Under normal circumstances, the <code class="docutils literal"><span class="pre">distutils</span></code> assume that you are going to
build a distribution of your project, not use it in its &#8220;raw&#8221; or &#8220;unbuilt&#8221;
form.  If you were to use the <code class="docutils literal"><span class="pre">distutils</span></code> that way, you would have to rebuild
and reinstall your project every time you made a change to it during
development.</p>
<p>Another problem that sometimes comes up with the <code class="docutils literal"><span class="pre">distutils</span></code> is that you may
need to do development on two related projects at the same time.  You may need
to put both projects&#8217; packages in the same directory to run them, but need to
keep them separate for revision control purposes.  How can you do this?</p>
<p>Setuptools allows you to deploy your projects for use in a common directory or
staging area, but without copying any files.  Thus, you can edit each project&#8217;s
code in its checkout directory, and only need to run build commands when you
change a project&#8217;s C extensions or similarly compiled files.  You can even
deploy a project into another project&#8217;s checkout directory, if that&#8217;s your
preferred way of working (as opposed to using a common independent staging area
or the site-packages directory).</p>
<p>To do this, use the <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">develop</span></code> command.  It works very similarly to
<code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">install</span></code> or the EasyInstall tool, except that it doesn&#8217;t actually
install anything.  Instead, it creates a special <code class="docutils literal"><span class="pre">.egg-link</span></code> file in the
deployment directory, that links to your project&#8217;s source code.  And, if your
deployment directory is Python&#8217;s <code class="docutils literal"><span class="pre">site-packages</span></code> directory, it will also
update the <code class="docutils literal"><span class="pre">easy-install.pth</span></code> file to include your project&#8217;s source code,
thereby making it available on <code class="docutils literal"><span class="pre">sys.path</span></code> for all programs using that Python
installation.</p>
<p>If you have enabled the <code class="docutils literal"><span class="pre">use_2to3</span></code> flag, then of course the <code class="docutils literal"><span class="pre">.egg-link</span></code>
will not link directly to your source code when run under Python 3, since
that source code would be made for Python 2 and not work under Python 3.
Instead the <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">develop</span></code> will build Python 3 code under the <code class="docutils literal"><span class="pre">build</span></code>
directory, and link there. This means that after doing code changes you will
have to run <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">build</span></code> before these changes are picked up by your
Python 3 installation.</p>
<p>In addition, the <code class="docutils literal"><span class="pre">develop</span></code> command creates wrapper scripts in the target
script directory that will run your in-development scripts after ensuring that
all your <code class="docutils literal"><span class="pre">install_requires</span></code> packages are available on <code class="docutils literal"><span class="pre">sys.path</span></code>.</p>
<p>You can deploy the same project to multiple staging areas, e.g. if you have
multiple projects on the same machine that are sharing the same project you&#8217;re
doing development work.</p>
<p>When you&#8217;re done with a given development task, you can remove the project
source from a staging area using <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">develop</span> <span class="pre">--uninstall</span></code>, specifying
the desired staging area if it&#8217;s not the default.</p>
<p>There are several options to control the precise behavior of the <code class="docutils literal"><span class="pre">develop</span></code>
command; see the section on the <a class="reference internal" href="#develop">develop</a> command below for more details.</p>
<p>Note that you can also apply setuptools commands to non-setuptools projects,
using commands like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">c</span> <span class="s2">&quot;import setuptools; execfile(&#39;setup.py&#39;)&quot;</span> <span class="n">develop</span>
</pre></div>
</div>
<p>That is, you can simply list the normal setup commands and options following
the quoted part.</p>
</div>
<div class="section" id="distributing-a-setuptools-based-project">
<h3><a class="toc-backref" href="#id24">Distributing a <code class="docutils literal"><span class="pre">setuptools</span></code>-based project</a><a class="headerlink" href="#distributing-a-setuptools-based-project" title="Permalink to this headline"></a></h3>
<div class="section" id="using-setuptools-without-bundling-it">
<h4><a class="toc-backref" href="#id25">Using <code class="docutils literal"><span class="pre">setuptools</span></code>...  Without bundling it!</a><a class="headerlink" href="#using-setuptools-without-bundling-it" title="Permalink to this headline"></a></h4>
<p>Your users might not have <code class="docutils literal"><span class="pre">setuptools</span></code> installed on their machines, or even
if they do, it might not be the right version.  Fixing this is easy; just
download <a class="reference external" href="https://bootstrap.pypa.io/ez_setup.py">ez_setup.py</a>, and put it in the same directory as your <code class="docutils literal"><span class="pre">setup.py</span></code>
script.  (Be sure to add it to your revision control system, too.)  Then add
these two lines to the very top of your setup script, before the script imports
anything from setuptools:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">ez_setup</span>
<span class="n">ez_setup</span><span class="o">.</span><span class="n">use_setuptools</span><span class="p">()</span>
</pre></div>
</div>
<p>That&#8217;s it.  The <code class="docutils literal"><span class="pre">ez_setup</span></code> module will automatically download a matching
version of <code class="docutils literal"><span class="pre">setuptools</span></code> from PyPI, if it isn&#8217;t present on the target system.
Whenever you install an updated version of setuptools, you should also update
your projects&#8217; <code class="docutils literal"><span class="pre">ez_setup.py</span></code> files, so that a matching version gets installed
on the target machine(s).</p>
<p>By the way, setuptools supports the new PyPI &#8220;upload&#8221; command, so you can use
<code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">sdist</span> <span class="pre">upload</span></code> or <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">bdist_egg</span> <span class="pre">upload</span></code> to upload your
source or egg distributions respectively.  Your project&#8217;s current version must
be registered with PyPI first, of course; you can use <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">register</span></code> to
do that.  Or you can do it all in one step, e.g. <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">register</span> <span class="pre">sdist</span>
<span class="pre">bdist_egg</span> <span class="pre">upload</span></code> will register the package, build source and egg
distributions, and then upload them both to PyPI, where they&#8217;ll be easily
found by other projects that depend on them.</p>
<p>(By the way, if you need to distribute a specific version of <code class="docutils literal"><span class="pre">setuptools</span></code>,
you can specify the exact version and base download URL as parameters to the
<code class="docutils literal"><span class="pre">use_setuptools()</span></code> function.  See the function&#8217;s docstring for details.)</p>
</div>
<div class="section" id="what-your-users-should-know">
<h4><a class="toc-backref" href="#id26">What Your Users Should Know</a><a class="headerlink" href="#what-your-users-should-know" title="Permalink to this headline"></a></h4>
<p>In general, a setuptools-based project looks just like any distutils-based
project &#8211; as long as your users have an internet connection and are installing
to <code class="docutils literal"><span class="pre">site-packages</span></code>, that is.  But for some users, these conditions don&#8217;t
apply, and they may become frustrated if this is their first encounter with
a setuptools-based project.  To keep these users happy, you should review the
following topics in your project&#8217;s installation instructions, if they are
relevant to your project and your target audience isn&#8217;t already familiar with
setuptools and <code class="docutils literal"><span class="pre">easy_install</span></code>.</p>
<dl class="docutils">
<dt>Network Access</dt>
<dd>If your project is using <code class="docutils literal"><span class="pre">ez_setup</span></code>, you should inform users of the
need to either have network access, or to preinstall the correct version of
setuptools using the <a class="reference external" href="easy_install.html#installation-instructions">EasyInstall installation instructions</a>.  Those
instructions also have tips for dealing with firewalls as well as how to
manually download and install setuptools.</dd>
<dt>Custom Installation Locations</dt>
<dd>You should inform your users that if they are installing your project to
somewhere other than the main <code class="docutils literal"><span class="pre">site-packages</span></code> directory, they should
first install setuptools using the instructions for <a class="reference external" href="easy_install.html#custom-installation-locations">Custom Installation
Locations</a>, before installing your project.</dd>
<dt>Your Project&#8217;s Dependencies</dt>
<dd><p class="first">If your project depends on other projects that may need to be downloaded
from PyPI or elsewhere, you should list them in your installation
instructions, or tell users how to find out what they are.  While most
users will not need this information, any users who don&#8217;t have unrestricted
internet access may have to find, download, and install the other projects
manually.  (Note, however, that they must still install those projects
using <code class="docutils literal"><span class="pre">easy_install</span></code>, or your project will not know they are installed,
and your setup script will try to download them again.)</p>
<p class="last">If you want to be especially friendly to users with limited network access,
you may wish to build eggs for your project and its dependencies, making
them all available for download from your site, or at least create a page
with links to all of the needed eggs.  In this way, users with limited
network access can manually download all the eggs to a single directory,
then use the <code class="docutils literal"><span class="pre">-f</span></code> option of <code class="docutils literal"><span class="pre">easy_install</span></code> to specify the directory
to find eggs in.  Users who have full network access can just use <code class="docutils literal"><span class="pre">-f</span></code>
with the URL of your download page, and <code class="docutils literal"><span class="pre">easy_install</span></code> will find all the
needed eggs using your links directly.  This is also useful when your
target audience isn&#8217;t able to compile packages (e.g. most Windows users)
and your package or some of its dependencies include C code.</p>
</dd>
<dt>Revision Control System Users and Co-Developers</dt>
<dd><p class="first">Users and co-developers who are tracking your in-development code using
a revision control system should probably read this manual&#8217;s sections
regarding such development.  Alternately, you may wish to create a
quick-reference guide containing the tips from this manual that apply to
your particular situation.  For example, if you recommend that people use
<code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">develop</span></code> when tracking your in-development code, you should let
them know that this needs to be run after every update or commit.</p>
<p class="last">Similarly, if you remove modules or data files from your project, you
should remind them to run <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">clean</span> <span class="pre">--all</span></code> and delete any obsolete
<code class="docutils literal"><span class="pre">.pyc</span></code> or <code class="docutils literal"><span class="pre">.pyo</span></code>.  (This tip applies to the distutils in general, not
just setuptools, but not everybody knows about them; be kind to your users
by spelling out your project&#8217;s best practices rather than leaving them
guessing.)</p>
</dd>
<dt>Creating System Packages</dt>
<dd><p class="first">Some users want to manage all Python packages using a single package
manager, and sometimes that package manager isn&#8217;t <code class="docutils literal"><span class="pre">easy_install</span></code>!
Setuptools currently supports <code class="docutils literal"><span class="pre">bdist_rpm</span></code>, <code class="docutils literal"><span class="pre">bdist_wininst</span></code>, and
<code class="docutils literal"><span class="pre">bdist_dumb</span></code> formats for system packaging.  If a user has a locally-
installed &#8220;bdist&#8221; packaging tool that internally uses the distutils
<code class="docutils literal"><span class="pre">install</span></code> command, it should be able to work with <code class="docutils literal"><span class="pre">setuptools</span></code>.  Some
examples of &#8220;bdist&#8221; formats that this should work with include the
<code class="docutils literal"><span class="pre">bdist_nsi</span></code> and <code class="docutils literal"><span class="pre">bdist_msi</span></code> formats for Windows.</p>
<p>However, packaging tools that build binary distributions by running
<code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">install</span></code> on the command line or as a subprocess will require
modification to work with setuptools.  They should use the
<code class="docutils literal"><span class="pre">--single-version-externally-managed</span></code> option to the <code class="docutils literal"><span class="pre">install</span></code> command,
combined with the standard <code class="docutils literal"><span class="pre">--root</span></code> or <code class="docutils literal"><span class="pre">--record</span></code> options.
See the <a class="reference internal" href="#install-command">install command</a> documentation below for more details.  The
<code class="docutils literal"><span class="pre">bdist_deb</span></code> command is an example of a command that currently requires
this kind of patching to work with setuptools.</p>
<p class="last">If you or your users have a problem building a usable system package for
your project, please report the problem via the mailing list so that
either the &#8220;bdist&#8221; tool in question or setuptools can be modified to
resolve the issue.</p>
</dd>
</dl>
</div>
<div class="section" id="setting-the-zip-safe-flag">
<h4><a class="toc-backref" href="#id27">Setting the <code class="docutils literal"><span class="pre">zip_safe</span></code> flag</a><a class="headerlink" href="#setting-the-zip-safe-flag" title="Permalink to this headline"></a></h4>
<p>For some use cases (such as bundling as part of a larger application), Python
packages may be run directly from a zip file.
Not all packages, however, are capable of running in compressed form, because
they may expect to be able to access either source code or data files as
normal operating system files.  So, <code class="docutils literal"><span class="pre">setuptools</span></code> can install your project
as a zipfile or a directory, and its default choice is determined by the
project&#8217;s <code class="docutils literal"><span class="pre">zip_safe</span></code> flag.</p>
<p>You can pass a True or False value for the <code class="docutils literal"><span class="pre">zip_safe</span></code> argument to the
<code class="docutils literal"><span class="pre">setup()</span></code> function, or you can omit it.  If you omit it, the <code class="docutils literal"><span class="pre">bdist_egg</span></code>
command will analyze your project&#8217;s contents to see if it can detect any
conditions that would prevent it from working in a zipfile.  It will output
notices to the console about any such conditions that it finds.</p>
<p>Currently, this analysis is extremely conservative: it will consider the
project unsafe if it contains any C extensions or datafiles whatsoever.  This
does <em>not</em> mean that the project can&#8217;t or won&#8217;t work as a zipfile!  It just
means that the <code class="docutils literal"><span class="pre">bdist_egg</span></code> authors aren&#8217;t yet comfortable asserting that
the project <em>will</em> work.  If the project contains no C or data files, and does
no <code class="docutils literal"><span class="pre">__file__</span></code> or <code class="docutils literal"><span class="pre">__path__</span></code> introspection or source code manipulation, then
there is an extremely solid chance the project will work when installed as a
zipfile.  (And if the project uses <code class="docutils literal"><span class="pre">pkg_resources</span></code> for all its data file
access, then C extensions and other data files shouldn&#8217;t be a problem at all.
See the <a class="reference internal" href="#accessing-data-files-at-runtime">Accessing Data Files at Runtime</a> section above for more information.)</p>
<p>However, if <code class="docutils literal"><span class="pre">bdist_egg</span></code> can&#8217;t be <em>sure</em> that your package will work, but
you&#8217;ve checked over all the warnings it issued, and you are either satisfied it
<em>will</em> work (or if you want to try it for yourself), then you should set
<code class="docutils literal"><span class="pre">zip_safe</span></code> to <code class="docutils literal"><span class="pre">True</span></code> in your <code class="docutils literal"><span class="pre">setup()</span></code> call.  If it turns out that it
doesn&#8217;t work, you can always change it to <code class="docutils literal"><span class="pre">False</span></code>, which will force
<code class="docutils literal"><span class="pre">setuptools</span></code> to install your project as a directory rather than as a zipfile.</p>
<p>Of course, the end-user can still override either decision, if they are using
EasyInstall to install your package.  And, if you want to override for testing
purposes, you can just run <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">easy_install</span> <span class="pre">--zip-ok</span> <span class="pre">.</span></code> or <code class="docutils literal"><span class="pre">setup.py</span>
<span class="pre">easy_install</span> <span class="pre">--always-unzip</span> <span class="pre">.</span></code> in your project directory. to install the
package as a zipfile or directory, respectively.</p>
<p>In the future, as we gain more experience with different packages and become
more satisfied with the robustness of the <code class="docutils literal"><span class="pre">pkg_resources</span></code> runtime, the
&#8220;zip safety&#8221; analysis may become less conservative.  However, we strongly
recommend that you determine for yourself whether your project functions
correctly when installed as a zipfile, correct any problems if you can, and
then make an explicit declaration of <code class="docutils literal"><span class="pre">True</span></code> or <code class="docutils literal"><span class="pre">False</span></code> for the <code class="docutils literal"><span class="pre">zip_safe</span></code>
flag, so that it will not be necessary for <code class="docutils literal"><span class="pre">bdist_egg</span></code> or <code class="docutils literal"><span class="pre">EasyInstall</span></code> to
try to guess whether your project can work as a zipfile.</p>
</div>
<div class="section" id="namespace-packages">
<h4><a class="toc-backref" href="#id28">Namespace Packages</a><a class="headerlink" href="#namespace-packages" title="Permalink to this headline"></a></h4>
<p>Sometimes, a large package is more useful if distributed as a collection of
smaller eggs.  However, Python does not normally allow the contents of a
package to be retrieved from more than one location.  &#8220;Namespace packages&#8221;
are a solution for this problem.  When you declare a package to be a namespace
package, it means that the package has no meaningful contents in its
<code class="docutils literal"><span class="pre">__init__.py</span></code>, and that it is merely a container for modules and subpackages.</p>
<p>The <code class="docutils literal"><span class="pre">pkg_resources</span></code> runtime will then automatically ensure that the contents
of namespace packages that are spread over multiple eggs or directories are
combined into a single &#8220;virtual&#8221; package.</p>
<p>The <code class="docutils literal"><span class="pre">namespace_packages</span></code> argument to <code class="docutils literal"><span class="pre">setup()</span></code> lets you declare your
project&#8217;s namespace packages, so that they will be included in your project&#8217;s
metadata.  The argument should list the namespace packages that the egg
participates in.  For example, the ZopeInterface project might do this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="c1"># ...</span>
    <span class="n">namespace_packages</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;zope&#39;</span><span class="p">]</span>
<span class="p">)</span>
</pre></div>
</div>
<p>because it contains a <code class="docutils literal"><span class="pre">zope.interface</span></code> package that lives in the <code class="docutils literal"><span class="pre">zope</span></code>
namespace package.  Similarly, a project for a standalone <code class="docutils literal"><span class="pre">zope.publisher</span></code>
would also declare the <code class="docutils literal"><span class="pre">zope</span></code> namespace package.  When these projects are
installed and used, Python will see them both as part of a &#8220;virtual&#8221; <code class="docutils literal"><span class="pre">zope</span></code>
package, even though they will be installed in different locations.</p>
<p>Namespace packages don&#8217;t have to be top-level packages.  For example, Zope 3&#8217;s
<code class="docutils literal"><span class="pre">zope.app</span></code> package is a namespace package, and in the future PEAK&#8217;s
<code class="docutils literal"><span class="pre">peak.util</span></code> package will be too.</p>
<p>Note, by the way, that your project&#8217;s source tree must include the namespace
packages&#8217; <code class="docutils literal"><span class="pre">__init__.py</span></code> files (and the <code class="docutils literal"><span class="pre">__init__.py</span></code> of any parent
packages), in a normal Python package layout.  These <code class="docutils literal"><span class="pre">__init__.py</span></code> files
<em>must</em> contain the line:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="nb">__import__</span><span class="p">(</span><span class="s1">&#39;pkg_resources&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">declare_namespace</span><span class="p">(</span><span class="n">__name__</span><span class="p">)</span>
</pre></div>
</div>
<p>This code ensures that the namespace package machinery is operating and that
the current package is registered as a namespace package.</p>
<p>You must NOT include any other code and data in a namespace package&#8217;s
<code class="docutils literal"><span class="pre">__init__.py</span></code>.  Even though it may appear to work during development, or when
projects are installed as <code class="docutils literal"><span class="pre">.egg</span></code> files, it will not work when the projects
are installed using &#8220;system&#8221; packaging tools &#8211; in such cases the
<code class="docutils literal"><span class="pre">__init__.py</span></code> files will not be installed, let alone executed.</p>
<p>You must include the <code class="docutils literal"><span class="pre">declare_namespace()</span></code>  line in the <code class="docutils literal"><span class="pre">__init__.py</span></code> of
<em>every</em> project that has contents for the namespace package in question, in
order to ensure that the namespace will be declared regardless of which
project&#8217;s copy of <code class="docutils literal"><span class="pre">__init__.py</span></code> is loaded first.  If the first loaded
<code class="docutils literal"><span class="pre">__init__.py</span></code> doesn&#8217;t declare it, it will never <em>be</em> declared, because no
other copies will ever be loaded!</p>
<div class="section" id="transitional-note">
<h5><a class="toc-backref" href="#id29">TRANSITIONAL NOTE</a><a class="headerlink" href="#transitional-note" title="Permalink to this headline"></a></h5>
<p>Setuptools automatically calls <code class="docutils literal"><span class="pre">declare_namespace()</span></code> for you at runtime,
but future versions may <em>not</em>.  This is because the automatic declaration
feature has some negative side effects, such as needing to import all namespace
packages during the initialization of the <code class="docutils literal"><span class="pre">pkg_resources</span></code> runtime, and also
the need for <code class="docutils literal"><span class="pre">pkg_resources</span></code> to be explicitly imported before any namespace
packages work at all.  In some future releases, you&#8217;ll be responsible
for including your own declaration lines, and the automatic declaration feature
will be dropped to get rid of the negative side effects.</p>
<p>During the remainder of the current development cycle, therefore, setuptools
will warn you about missing <code class="docutils literal"><span class="pre">declare_namespace()</span></code> calls in your
<code class="docutils literal"><span class="pre">__init__.py</span></code> files, and you should correct these as soon as possible
before the compatibility support is removed.
Namespace packages without declaration lines will not work
correctly once a user has upgraded to a later version, so it&#8217;s important that
you make this change now in order to avoid having your code break in the field.
Our apologies for the inconvenience, and thank you for your patience.</p>
</div>
</div>
<div class="section" id="tagging-and-daily-build-or-snapshot-releases">
<h4><a class="toc-backref" href="#id30">Tagging and &#8220;Daily Build&#8221; or &#8220;Snapshot&#8221; Releases</a><a class="headerlink" href="#tagging-and-daily-build-or-snapshot-releases" title="Permalink to this headline"></a></h4>
<p>When a set of related projects are under development, it may be important to
track finer-grained version increments than you would normally use for e.g.
&#8220;stable&#8221; releases.  While stable releases might be measured in dotted numbers
with alpha/beta/etc. status codes, development versions of a project often
need to be tracked by revision or build number or even build date.  This is
especially true when projects in development need to refer to one another, and
therefore may literally need an up-to-the-minute version of something!</p>
<p>To support these scenarios, <code class="docutils literal"><span class="pre">setuptools</span></code> allows you to &#8220;tag&#8221; your source and
egg distributions by adding one or more of the following to the project&#8217;s
&#8220;official&#8221; version identifier:</p>
<ul class="simple">
<li>A manually-specified pre-release tag, such as &#8220;build&#8221; or &#8220;dev&#8221;, or a
manually-specified post-release tag, such as a build or revision number
(<code class="docutils literal"><span class="pre">--tag-build=STRING,</span> <span class="pre">-bSTRING</span></code>)</li>
<li>An 8-character representation of the build date (<code class="docutils literal"><span class="pre">--tag-date,</span> <span class="pre">-d</span></code>), as
a postrelease tag</li>
</ul>
<p>You can add these tags by adding <code class="docutils literal"><span class="pre">egg_info</span></code> and the desired options to
the command line ahead of the <code class="docutils literal"><span class="pre">sdist</span></code> or <code class="docutils literal"><span class="pre">bdist</span></code> commands that you want
to generate a daily build or snapshot for.  See the section below on the
<a class="reference internal" href="#egg-info">egg_info</a> command for more details.</p>
<p>(Also, before you release your project, be sure to see the section above on
<a class="reference internal" href="#specifying-your-project-s-version">Specifying Your Project&#8217;s Version</a> for more information about how pre- and
post-release tags affect how setuptools and EasyInstall interpret version
numbers.  This is important in order to make sure that dependency processing
tools will know which versions of your project are newer than others.)</p>
<p>Finally, if you are creating builds frequently, and either building them in a
downloadable location or are copying them to a distribution server, you should
probably also check out the <a class="reference internal" href="#rotate">rotate</a> command, which lets you automatically
delete all but the N most-recently-modified distributions matching a glob
pattern.  So, you can use a command line like:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">egg_info</span> <span class="o">-</span><span class="n">rbDEV</span> <span class="n">bdist_egg</span> <span class="n">rotate</span> <span class="o">-</span><span class="n">m</span><span class="o">.</span><span class="n">egg</span> <span class="o">-</span><span class="n">k3</span>
</pre></div>
</div>
<p>to build an egg whose version info includes &#8216;DEV-rNNNN&#8217; (where NNNN is the
most recent Subversion revision that affected the source tree), and then
delete any egg files from the distribution directory except for the three
that were built most recently.</p>
<p>If you have to manage automated builds for multiple packages, each with
different tagging and rotation policies, you may also want to check out the
<a class="reference internal" href="#alias">alias</a> command, which would let each package define an alias like <code class="docutils literal"><span class="pre">daily</span></code>
that would perform the necessary tag, build, and rotate commands.  Then, a
simpler script or cron job could just run <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">daily</span></code> in each project
directory.  (And, you could also define sitewide or per-user default versions
of the <code class="docutils literal"><span class="pre">daily</span></code> alias, so that projects that didn&#8217;t define their own would
use the appropriate defaults.)</p>
</div>
<div class="section" id="generating-source-distributions">
<h4><a class="toc-backref" href="#id31">Generating Source Distributions</a><a class="headerlink" href="#generating-source-distributions" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal"><span class="pre">setuptools</span></code> enhances the distutils&#8217; default algorithm for source file
selection with pluggable endpoints for looking up files to include. If you are
using a revision control system, and your source distributions only need to
include files that you&#8217;re tracking in revision control, use a corresponding
plugin instead of writing a <code class="docutils literal"><span class="pre">MANIFEST.in</span></code> file. See the section below on
<a class="reference internal" href="#adding-support-for-revision-control-systems">Adding Support for Revision Control Systems</a> for information on plugins.</p>
<p>If you need to include automatically generated files, or files that are kept in
an unsupported revision control system, you&#8217;ll need to create a <code class="docutils literal"><span class="pre">MANIFEST.in</span></code>
file to specify any files that the default file location algorithm doesn&#8217;t
catch.  See the distutils documentation for more information on the format of
the <code class="docutils literal"><span class="pre">MANIFEST.in</span></code> file.</p>
<p>But, be sure to ignore any part of the distutils documentation that deals with
<code class="docutils literal"><span class="pre">MANIFEST</span></code> or how it&#8217;s generated from <code class="docutils literal"><span class="pre">MANIFEST.in</span></code>; setuptools shields you
from these issues and doesn&#8217;t work the same way in any case.  Unlike the
distutils, setuptools regenerates the source distribution manifest file
every time you build a source distribution, and it builds it inside the
project&#8217;s <code class="docutils literal"><span class="pre">.egg-info</span></code> directory, out of the way of your main project
directory.  You therefore need not worry about whether it is up-to-date or not.</p>
<p>Indeed, because setuptools&#8217; approach to determining the contents of a source
distribution is so much simpler, its <code class="docutils literal"><span class="pre">sdist</span></code> command omits nearly all of
the options that the distutils&#8217; more complex <code class="docutils literal"><span class="pre">sdist</span></code> process requires.  For
all practical purposes, you&#8217;ll probably use only the <code class="docutils literal"><span class="pre">--formats</span></code> option, if
you use any option at all.</p>
</div>
<div class="section" id="making-your-package-available-for-easyinstall">
<h4><a class="toc-backref" href="#id32">Making your package available for EasyInstall</a><a class="headerlink" href="#making-your-package-available-for-easyinstall" title="Permalink to this headline"></a></h4>
<p>If you use the <code class="docutils literal"><span class="pre">register</span></code> command (<code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">register</span></code>) to register your
package with PyPI, that&#8217;s most of the battle right there.  (See the
<a class="reference external" href="http://docs.python.org/dist/package-index.html">docs for the register command</a> for more details.)</p>
<p>If you also use the <a class="reference internal" href="#upload">upload</a> command to upload actual distributions of your
package, that&#8217;s even better, because EasyInstall will be able to find and
download them directly from your project&#8217;s PyPI page.</p>
<p>However, there may be reasons why you don&#8217;t want to upload distributions to
PyPI, and just want your existing distributions (or perhaps a Subversion
checkout) to be used instead.</p>
<p>So here&#8217;s what you need to do before running the <code class="docutils literal"><span class="pre">register</span></code> command.  There
are three <code class="docutils literal"><span class="pre">setup()</span></code> arguments that affect EasyInstall:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">url</span></code> and <code class="docutils literal"><span class="pre">download_url</span></code></dt>
<dd>These become links on your project&#8217;s PyPI page.  EasyInstall will examine
them to see if they link to a package (&#8220;primary links&#8221;), or whether they are
HTML pages.  If they&#8217;re HTML pages, EasyInstall scans all HREF&#8217;s on the
page for primary links</dd>
<dt><code class="docutils literal"><span class="pre">long_description</span></code></dt>
<dd>EasyInstall will check any URLs contained in this argument to see if they
are primary links.</dd>
</dl>
<p>A URL is considered a &#8220;primary link&#8221; if it is a link to a .tar.gz, .tgz, .zip,
.egg, .egg.zip, .tar.bz2, or .exe file, or if it has an <code class="docutils literal"><span class="pre">#egg=project</span></code> or
<code class="docutils literal"><span class="pre">#egg=project-version</span></code> fragment identifier attached to it.  EasyInstall
attempts to determine a project name and optional version number from the text
of a primary link <em>without</em> downloading it.  When it has found all the primary
links, EasyInstall will select the best match based on requested version,
platform compatibility, and other criteria.</p>
<p>So, if your <code class="docutils literal"><span class="pre">url</span></code> or <code class="docutils literal"><span class="pre">download_url</span></code> point either directly to a downloadable
source distribution, or to HTML page(s) that have direct links to such, then
EasyInstall will be able to locate downloads automatically.  If you want to
make Subversion checkouts available, then you should create links with either
<code class="docutils literal"><span class="pre">#egg=project</span></code> or <code class="docutils literal"><span class="pre">#egg=project-version</span></code> added to the URL.  You should
replace <code class="docutils literal"><span class="pre">project</span></code> and <code class="docutils literal"><span class="pre">version</span></code> with the values they would have in an egg
filename.  (Be sure to actually generate an egg and then use the initial part
of the filename, rather than trying to guess what the escaped form of the
project name and version number will be.)</p>
<p>Note that Subversion checkout links are of lower precedence than other kinds
of distributions, so EasyInstall will not select a Subversion checkout for
downloading unless it has a version included in the <code class="docutils literal"><span class="pre">#egg=</span></code> suffix, and
it&#8217;s a higher version than EasyInstall has seen in any other links for your
project.</p>
<p>As a result, it&#8217;s a common practice to use mark checkout URLs with a version of
&#8220;dev&#8221; (i.e., <code class="docutils literal"><span class="pre">#egg=projectname-dev</span></code>), so that users can do something like
this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">easy_install</span> <span class="o">--</span><span class="n">editable</span> <span class="n">projectname</span><span class="o">==</span><span class="n">dev</span>
</pre></div>
</div>
<p>in order to check out the in-development version of <code class="docutils literal"><span class="pre">projectname</span></code>.</p>
<div class="section" id="making-official-non-snapshot-releases">
<h5><a class="toc-backref" href="#id33">Making &#8220;Official&#8221; (Non-Snapshot) Releases</a><a class="headerlink" href="#making-official-non-snapshot-releases" title="Permalink to this headline"></a></h5>
<p>When you make an official release, creating source or binary distributions,
you will need to override the tag settings from <code class="docutils literal"><span class="pre">setup.cfg</span></code>, so that you
don&#8217;t end up registering versions like <code class="docutils literal"><span class="pre">foobar-0.7a1.dev-r34832</span></code>.  This is
easy to do if you are developing on the trunk and using tags or branches for
your releases - just make the change to <code class="docutils literal"><span class="pre">setup.cfg</span></code> after branching or
tagging the release, so the trunk will still produce development snapshots.</p>
<p>Alternately, if you are not branching for releases, you can override the
default version options on the command line, using something like:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">egg_info</span> <span class="o">-</span><span class="n">Db</span> <span class="s2">&quot;&quot;</span> <span class="n">sdist</span> <span class="n">bdist_egg</span> <span class="n">register</span> <span class="n">upload</span>
</pre></div>
</div>
<p>The first part of this command (<code class="docutils literal"><span class="pre">egg_info</span> <span class="pre">-Db</span> <span class="pre">&quot;&quot;</span></code>) will override the
configured tag information, before creating source and binary eggs, registering
the project with PyPI, and uploading the files.  Thus, these commands will use
the plain version from your <code class="docutils literal"><span class="pre">setup.py</span></code>, without adding the build designation
string.</p>
<p>Of course, if you will be doing this a lot, you may wish to create a personal
alias for this operation, e.g.:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">alias</span> <span class="o">-</span><span class="n">u</span> <span class="n">release</span> <span class="n">egg_info</span> <span class="o">-</span><span class="n">Db</span> <span class="s2">&quot;&quot;</span>
</pre></div>
</div>
<p>You can then use it like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">release</span> <span class="n">sdist</span> <span class="n">bdist_egg</span> <span class="n">register</span> <span class="n">upload</span>
</pre></div>
</div>
<p>Or of course you can create more elaborate aliases that do all of the above.
See the sections below on the <a class="reference internal" href="#egg-info">egg_info</a> and <a class="reference internal" href="#alias">alias</a> commands for more ideas.</p>
</div>
</div>
<div class="section" id="distributing-extensions-compiled-with-pyrex">
<h4><a class="toc-backref" href="#id34">Distributing Extensions compiled with Pyrex</a><a class="headerlink" href="#distributing-extensions-compiled-with-pyrex" title="Permalink to this headline"></a></h4>
<p><code class="docutils literal"><span class="pre">setuptools</span></code> includes transparent support for building Pyrex extensions, as
long as you define your extensions using <code class="docutils literal"><span class="pre">setuptools.Extension</span></code>, <em>not</em>
<code class="docutils literal"><span class="pre">distutils.Extension</span></code>.  You must also not import anything from Pyrex in
your setup script.</p>
<p>If you follow these rules, you can safely list <code class="docutils literal"><span class="pre">.pyx</span></code> files as the source
of your <code class="docutils literal"><span class="pre">Extension</span></code> objects in the setup script.  <code class="docutils literal"><span class="pre">setuptools</span></code> will detect
at build time whether Pyrex is installed or not.  If it is, then <code class="docutils literal"><span class="pre">setuptools</span></code>
will use it.  If not, then <code class="docutils literal"><span class="pre">setuptools</span></code> will silently change the
<code class="docutils literal"><span class="pre">Extension</span></code> objects to refer to the <code class="docutils literal"><span class="pre">.c</span></code> counterparts of the <code class="docutils literal"><span class="pre">.pyx</span></code>
files, so that the normal distutils C compilation process will occur.</p>
<p>Of course, for this to work, your source distributions must include the C
code generated by Pyrex, as well as your original <code class="docutils literal"><span class="pre">.pyx</span></code> files.  This means
that you will probably want to include current <code class="docutils literal"><span class="pre">.c</span></code> files in your revision
control system, rebuilding them whenever you check changes in for the <code class="docutils literal"><span class="pre">.pyx</span></code>
source files.  This will ensure that people tracking your project in a revision
control system will be able to build it even if they don&#8217;t have Pyrex
installed, and that your source releases will be similarly usable with or
without Pyrex.</p>
</div>
</div>
</div>
<div class="section" id="command-reference">
<h2><a class="toc-backref" href="#id35">Command Reference</a><a class="headerlink" href="#command-reference" title="Permalink to this headline"></a></h2>
<div class="section" id="alias-define-shortcuts-for-commonly-used-commands">
<span id="alias"></span><h3><a class="toc-backref" href="#id36"><code class="docutils literal"><span class="pre">alias</span></code> - Define shortcuts for commonly used commands</a><a class="headerlink" href="#alias-define-shortcuts-for-commonly-used-commands" title="Permalink to this headline"></a></h3>
<p>Sometimes, you need to use the same commands over and over, but you can&#8217;t
necessarily set them as defaults.  For example, if you produce both development
snapshot releases and &#8220;stable&#8221; releases of a project, you may want to put
the distributions in different places, or use different <code class="docutils literal"><span class="pre">egg_info</span></code> tagging
options, etc.  In these cases, it doesn&#8217;t make sense to set the options in
a distutils configuration file, because the values of the options changed based
on what you&#8217;re trying to do.</p>
<p>Setuptools therefore allows you to define &#8220;aliases&#8221; - shortcut names for
an arbitrary string of commands and options, using <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">alias</span> <span class="pre">aliasname</span>
<span class="pre">expansion</span></code>, where aliasname is the name of the new alias, and the remainder of
the command line supplies its expansion.  For example, this command defines
a sitewide alias called &#8220;daily&#8221;, that sets various <code class="docutils literal"><span class="pre">egg_info</span></code> tagging
options:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">alias</span> <span class="o">--</span><span class="k">global</span><span class="o">-</span><span class="n">config</span> <span class="n">daily</span> <span class="n">egg_info</span> <span class="o">--</span><span class="n">tag</span><span class="o">-</span><span class="n">build</span><span class="o">=</span><span class="n">development</span>
</pre></div>
</div>
<p>Once the alias is defined, it can then be used with other setup commands,
e.g.:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">daily</span> <span class="n">bdist_egg</span>        <span class="c1"># generate a daily-build .egg file</span>
<span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">daily</span> <span class="n">sdist</span>            <span class="c1"># generate a daily-build source distro</span>
<span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">daily</span> <span class="n">sdist</span> <span class="n">bdist_egg</span>  <span class="c1"># generate both</span>
</pre></div>
</div>
<p>The above commands are interpreted as if the word <code class="docutils literal"><span class="pre">daily</span></code> were replaced with
<code class="docutils literal"><span class="pre">egg_info</span> <span class="pre">--tag-build=development</span></code>.</p>
<p>Note that setuptools will expand each alias <em>at most once</em> in a given command
line.  This serves two purposes.  First, if you accidentally create an alias
loop, it will have no effect; you&#8217;ll instead get an error message about an
unknown command.  Second, it allows you to define an alias for a command, that
uses that command.  For example, this (project-local) alias:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">alias</span> <span class="n">bdist_egg</span> <span class="n">bdist_egg</span> <span class="n">rotate</span> <span class="o">-</span><span class="n">k1</span> <span class="o">-</span><span class="n">m</span><span class="o">.</span><span class="n">egg</span>
</pre></div>
</div>
<p>redefines the <code class="docutils literal"><span class="pre">bdist_egg</span></code> command so that it always runs the <code class="docutils literal"><span class="pre">rotate</span></code>
command afterwards to delete all but the newest egg file.  It doesn&#8217;t loop
indefinitely on <code class="docutils literal"><span class="pre">bdist_egg</span></code> because the alias is only expanded once when
used.</p>
<p>You can remove a defined alias with the <code class="docutils literal"><span class="pre">--remove</span></code> (or <code class="docutils literal"><span class="pre">-r</span></code>) option, e.g.:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">alias</span> <span class="o">--</span><span class="k">global</span><span class="o">-</span><span class="n">config</span> <span class="o">--</span><span class="n">remove</span> <span class="n">daily</span>
</pre></div>
</div>
<p>would delete the &#8220;daily&#8221; alias we defined above.</p>
<p>Aliases can be defined on a project-specific, per-user, or sitewide basis.  The
default is to define or remove a project-specific alias, but you can use any of
the <a class="reference internal" href="#configuration-file-options">configuration file options</a> (listed under the <a class="reference internal" href="#saveopts">saveopts</a> command, below)
to determine which distutils configuration file an aliases will be added to
(or removed from).</p>
<p>Note that if you omit the &#8220;expansion&#8221; argument to the <code class="docutils literal"><span class="pre">alias</span></code> command,
you&#8217;ll get output showing that alias&#8217; current definition (and what
configuration file it&#8217;s defined in).  If you omit the alias name as well,
you&#8217;ll get a listing of all current aliases along with their configuration
file locations.</p>
</div>
<div class="section" id="bdist-egg-create-a-python-egg-for-the-project">
<h3><a class="toc-backref" href="#id37"><code class="docutils literal"><span class="pre">bdist_egg</span></code> - Create a Python Egg for the project</a><a class="headerlink" href="#bdist-egg-create-a-python-egg-for-the-project" title="Permalink to this headline"></a></h3>
<p>This command generates a Python Egg (<code class="docutils literal"><span class="pre">.egg</span></code> file) for the project.  Python
Eggs are the preferred binary distribution format for EasyInstall, because they
are cross-platform (for &#8220;pure&#8221; packages), directly importable, and contain
project metadata including scripts and information about the project&#8217;s
dependencies.  They can be simply downloaded and added to <code class="docutils literal"><span class="pre">sys.path</span></code>
directly, or they can be placed in a directory on <code class="docutils literal"><span class="pre">sys.path</span></code> and then
automatically discovered by the egg runtime system.</p>
<p>This command runs the <a class="reference internal" href="#egg-info">egg_info</a> command (if it hasn&#8217;t already run) to update
the project&#8217;s metadata (<code class="docutils literal"><span class="pre">.egg-info</span></code>) directory.  If you have added any extra
metadata files to the <code class="docutils literal"><span class="pre">.egg-info</span></code> directory, those files will be included in
the new egg file&#8217;s metadata directory, for use by the egg runtime system or by
any applications or frameworks that use that metadata.</p>
<p>You won&#8217;t usually need to specify any special options for this command; just
use <code class="docutils literal"><span class="pre">bdist_egg</span></code> and you&#8217;re done.  But there are a few options that may
be occasionally useful:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">--dist-dir=DIR,</span> <span class="pre">-d</span> <span class="pre">DIR</span></code></dt>
<dd>Set the directory where the <code class="docutils literal"><span class="pre">.egg</span></code> file will be placed.  If you don&#8217;t
supply this, then the <code class="docutils literal"><span class="pre">--dist-dir</span></code> setting of the <code class="docutils literal"><span class="pre">bdist</span></code> command
will be used, which is usually a directory named <code class="docutils literal"><span class="pre">dist</span></code> in the project
directory.</dd>
<dt><code class="docutils literal"><span class="pre">--plat-name=PLATFORM,</span> <span class="pre">-p</span> <span class="pre">PLATFORM</span></code></dt>
<dd>Set the platform name string that will be embedded in the egg&#8217;s filename
(assuming the egg contains C extensions).  This can be used to override
the distutils default platform name with something more meaningful.  Keep
in mind, however, that the egg runtime system expects to see eggs with
distutils platform names, so it may ignore or reject eggs with non-standard
platform names.  Similarly, the EasyInstall program may ignore them when
searching web pages for download links.  However, if you are
cross-compiling or doing some other unusual things, you might find a use
for this option.</dd>
<dt><code class="docutils literal"><span class="pre">--exclude-source-files</span></code></dt>
<dd>Don&#8217;t include any modules&#8217; <code class="docutils literal"><span class="pre">.py</span></code> files in the egg, just compiled Python,
C, and data files.  (Note that this doesn&#8217;t affect any <code class="docutils literal"><span class="pre">.py</span></code> files in the
EGG-INFO directory or its subdirectories, since for example there may be
scripts with a <code class="docutils literal"><span class="pre">.py</span></code> extension which must still be retained.)  We don&#8217;t
recommend that you use this option except for packages that are being
bundled for proprietary end-user applications, or for &#8220;embedded&#8221; scenarios
where space is at an absolute premium.  On the other hand, if your package
is going to be installed and used in compressed form, you might as well
exclude the source because Python&#8217;s <code class="docutils literal"><span class="pre">traceback</span></code> module doesn&#8217;t currently
understand how to display zipped source code anyway, or how to deal with
files that are in a different place from where their code was compiled.</dd>
</dl>
<p>There are also some options you will probably never need, but which are there
because they were copied from similar <code class="docutils literal"><span class="pre">bdist</span></code> commands used as an example for
creating this one.  They may be useful for testing and debugging, however,
which is why we kept them:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">--keep-temp,</span> <span class="pre">-k</span></code></dt>
<dd>Keep the contents of the <code class="docutils literal"><span class="pre">--bdist-dir</span></code> tree around after creating the
<code class="docutils literal"><span class="pre">.egg</span></code> file.</dd>
<dt><code class="docutils literal"><span class="pre">--bdist-dir=DIR,</span> <span class="pre">-b</span> <span class="pre">DIR</span></code></dt>
<dd>Set the temporary directory for creating the distribution.  The entire
contents of this directory are zipped to create the <code class="docutils literal"><span class="pre">.egg</span></code> file, after
running various installation commands to copy the package&#8217;s modules, data,
and extensions here.</dd>
<dt><code class="docutils literal"><span class="pre">--skip-build</span></code></dt>
<dd>Skip doing any &#8220;build&#8221; commands; just go straight to the
install-and-compress phases.</dd>
</dl>
</div>
<div class="section" id="develop-deploy-the-project-source-in-development-mode">
<span id="develop"></span><h3><a class="toc-backref" href="#id38"><code class="docutils literal"><span class="pre">develop</span></code> - Deploy the project source in &#8220;Development Mode&#8221;</a><a class="headerlink" href="#develop-deploy-the-project-source-in-development-mode" title="Permalink to this headline"></a></h3>
<p>This command allows you to deploy your project&#8217;s source for use in one or more
&#8220;staging areas&#8221; where it will be available for importing.  This deployment is
done in such a way that changes to the project source are immediately available
in the staging area(s), without needing to run a build or install step after
each change.</p>
<p>The <code class="docutils literal"><span class="pre">develop</span></code> command works by creating an <code class="docutils literal"><span class="pre">.egg-link</span></code> file (named for the
project) in the given staging area.  If the staging area is Python&#8217;s
<code class="docutils literal"><span class="pre">site-packages</span></code> directory, it also updates an <code class="docutils literal"><span class="pre">easy-install.pth</span></code> file so
that the project is on <code class="docutils literal"><span class="pre">sys.path</span></code> by default for all programs run using that
Python installation.</p>
<p>The <code class="docutils literal"><span class="pre">develop</span></code> command also installs wrapper scripts in the staging area (or
a separate directory, as specified) that will ensure the project&#8217;s dependencies
are available on <code class="docutils literal"><span class="pre">sys.path</span></code> before running the project&#8217;s source scripts.
And, it ensures that any missing project dependencies are available in the
staging area, by downloading and installing them if necessary.</p>
<p>Last, but not least, the <code class="docutils literal"><span class="pre">develop</span></code> command invokes the <code class="docutils literal"><span class="pre">build_ext</span> <span class="pre">-i</span></code>
command to ensure any C extensions in the project have been built and are
up-to-date, and the <code class="docutils literal"><span class="pre">egg_info</span></code> command to ensure the project&#8217;s metadata is
updated (so that the runtime and wrappers know what the project&#8217;s dependencies
are).  If you make any changes to the project&#8217;s setup script or C extensions,
you should rerun the <code class="docutils literal"><span class="pre">develop</span></code> command against all relevant staging areas to
keep the project&#8217;s scripts, metadata and extensions up-to-date.  Most other
kinds of changes to your project should not require any build operations or
rerunning <code class="docutils literal"><span class="pre">develop</span></code>, but keep in mind that even minor changes to the setup
script (e.g. changing an entry point definition) require you to re-run the
<code class="docutils literal"><span class="pre">develop</span></code> or <code class="docutils literal"><span class="pre">test</span></code> commands to keep the distribution updated.</p>
<p>Here are some of the options that the <code class="docutils literal"><span class="pre">develop</span></code> command accepts.  Note that
they affect the project&#8217;s dependencies as well as the project itself, so if you
have dependencies that need to be installed and you use <code class="docutils literal"><span class="pre">--exclude-scripts</span></code>
(for example), the dependencies&#8217; scripts will not be installed either!  For
this reason, you may want to use EasyInstall to install the project&#8217;s
dependencies before using the <code class="docutils literal"><span class="pre">develop</span></code> command, if you need finer control
over the installation options for dependencies.</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">--uninstall,</span> <span class="pre">-u</span></code></dt>
<dd><p class="first">Un-deploy the current project.  You may use the <code class="docutils literal"><span class="pre">--install-dir</span></code> or <code class="docutils literal"><span class="pre">-d</span></code>
option to designate the staging area.  The created <code class="docutils literal"><span class="pre">.egg-link</span></code> file will
be removed, if present and it is still pointing to the project directory.
The project directory will be removed from <code class="docutils literal"><span class="pre">easy-install.pth</span></code> if the
staging area is Python&#8217;s <code class="docutils literal"><span class="pre">site-packages</span></code> directory.</p>
<p class="last">Note that this option currently does <em>not</em> uninstall script wrappers!  You
must uninstall them yourself, or overwrite them by using EasyInstall to
activate a different version of the package.  You can also avoid installing
script wrappers in the first place, if you use the <code class="docutils literal"><span class="pre">--exclude-scripts</span></code>
(aka <code class="docutils literal"><span class="pre">-x</span></code>) option when you run <code class="docutils literal"><span class="pre">develop</span></code> to deploy the project.</p>
</dd>
<dt><code class="docutils literal"><span class="pre">--multi-version,</span> <span class="pre">-m</span></code></dt>
<dd><p class="first">&#8220;Multi-version&#8221; mode. Specifying this option prevents <code class="docutils literal"><span class="pre">develop</span></code> from
adding an <code class="docutils literal"><span class="pre">easy-install.pth</span></code> entry for the project(s) being deployed, and
if an entry for any version of a project already exists, the entry will be
removed upon successful deployment.  In multi-version mode, no specific
version of the package is available for importing, unless you use
<code class="docutils literal"><span class="pre">pkg_resources.require()</span></code> to put it on <code class="docutils literal"><span class="pre">sys.path</span></code>, or you are running
a wrapper script generated by <code class="docutils literal"><span class="pre">setuptools</span></code> or EasyInstall.  (In which
case the wrapper script calls <code class="docutils literal"><span class="pre">require()</span></code> for you.)</p>
<p class="last">Note that if you install to a directory other than <code class="docutils literal"><span class="pre">site-packages</span></code>,
this option is automatically in effect, because <code class="docutils literal"><span class="pre">.pth</span></code> files can only be
used in <code class="docutils literal"><span class="pre">site-packages</span></code> (at least in Python 2.3 and 2.4). So, if you use
the <code class="docutils literal"><span class="pre">--install-dir</span></code> or <code class="docutils literal"><span class="pre">-d</span></code> option (or they are set via configuration
file(s)) your project and its dependencies will be deployed in multi-
version mode.</p>
</dd>
<dt><code class="docutils literal"><span class="pre">--install-dir=DIR,</span> <span class="pre">-d</span> <span class="pre">DIR</span></code></dt>
<dd>Set the installation directory (staging area).  If this option is not
directly specified on the command line or in a distutils configuration
file, the distutils default installation location is used.  Normally, this
will be the <code class="docutils literal"><span class="pre">site-packages</span></code> directory, but if you are using distutils
configuration files, setting things like <code class="docutils literal"><span class="pre">prefix</span></code> or <code class="docutils literal"><span class="pre">install_lib</span></code>,
then those settings are taken into account when computing the default
staging area.</dd>
<dt><code class="docutils literal"><span class="pre">--script-dir=DIR,</span> <span class="pre">-s</span> <span class="pre">DIR</span></code></dt>
<dd>Set the script installation directory.  If you don&#8217;t supply this option
(via the command line or a configuration file), but you <em>have</em> supplied
an <code class="docutils literal"><span class="pre">--install-dir</span></code> (via command line or config file), then this option
defaults to the same directory, so that the scripts will be able to find
their associated package installation.  Otherwise, this setting defaults
to the location where the distutils would normally install scripts, taking
any distutils configuration file settings into account.</dd>
<dt><code class="docutils literal"><span class="pre">--exclude-scripts,</span> <span class="pre">-x</span></code></dt>
<dd>Don&#8217;t deploy script wrappers.  This is useful if you don&#8217;t want to disturb
existing versions of the scripts in the staging area.</dd>
<dt><code class="docutils literal"><span class="pre">--always-copy,</span> <span class="pre">-a</span></code></dt>
<dd>Copy all needed distributions to the staging area, even if they
are already present in another directory on <code class="docutils literal"><span class="pre">sys.path</span></code>.  By default, if
a requirement can be met using a distribution that is already available in
a directory on <code class="docutils literal"><span class="pre">sys.path</span></code>, it will not be copied to the staging area.</dd>
<dt><code class="docutils literal"><span class="pre">--egg-path=DIR</span></code></dt>
<dd>Force the generated <code class="docutils literal"><span class="pre">.egg-link</span></code> file to use a specified relative path
to the source directory.  This can be useful in circumstances where your
installation directory is being shared by code running under multiple
platforms (e.g. Mac and Windows) which have different absolute locations
for the code under development, but the same <em>relative</em> locations with
respect to the installation directory.  If you use this option when
installing, you must supply the same relative path when uninstalling.</dd>
</dl>
<p>In addition to the above options, the <code class="docutils literal"><span class="pre">develop</span></code> command also accepts all of
the same options accepted by <code class="docutils literal"><span class="pre">easy_install</span></code>.  If you&#8217;ve configured any
<code class="docutils literal"><span class="pre">easy_install</span></code> settings in your <code class="docutils literal"><span class="pre">setup.cfg</span></code> (or other distutils config
files), the <code class="docutils literal"><span class="pre">develop</span></code> command will use them as defaults, unless you override
them in a <code class="docutils literal"><span class="pre">[develop]</span></code> section or on the command line.</p>
</div>
<div class="section" id="easy-install-find-and-install-packages">
<h3><a class="toc-backref" href="#id39"><code class="docutils literal"><span class="pre">easy_install</span></code> - Find and install packages</a><a class="headerlink" href="#easy-install-find-and-install-packages" title="Permalink to this headline"></a></h3>
<p>This command runs the <a class="reference external" href="easy_install.html">EasyInstall tool</a> for you.  It is exactly
equivalent to running the <code class="docutils literal"><span class="pre">easy_install</span></code> command.  All command line arguments
following this command are consumed and not processed further by the distutils,
so this must be the last command listed on the command line.  Please see
the EasyInstall documentation for the options reference and usage examples.
Normally, there is no reason to use this command via the command line, as you
can just use <code class="docutils literal"><span class="pre">easy_install</span></code> directly.  It&#8217;s only listed here so that you know
it&#8217;s a distutils command, which means that you can:</p>
<ul class="simple">
<li>create command aliases that use it,</li>
<li>create distutils extensions that invoke it as a subcommand, and</li>
<li>configure options for it in your <code class="docutils literal"><span class="pre">setup.cfg</span></code> or other distutils config
files.</li>
</ul>
</div>
<div class="section" id="egg-info-create-egg-metadata-and-set-build-tags">
<span id="egg-info"></span><h3><a class="toc-backref" href="#id40"><code class="docutils literal"><span class="pre">egg_info</span></code> - Create egg metadata and set build tags</a><a class="headerlink" href="#egg-info-create-egg-metadata-and-set-build-tags" title="Permalink to this headline"></a></h3>
<p>This command performs two operations: it updates a project&#8217;s <code class="docutils literal"><span class="pre">.egg-info</span></code>
metadata directory (used by the <code class="docutils literal"><span class="pre">bdist_egg</span></code>, <code class="docutils literal"><span class="pre">develop</span></code>, and <code class="docutils literal"><span class="pre">test</span></code>
commands), and it allows you to temporarily change a project&#8217;s version string,
to support &#8220;daily builds&#8221; or &#8220;snapshot&#8221; releases.  It is run automatically by
the <code class="docutils literal"><span class="pre">sdist</span></code>, <code class="docutils literal"><span class="pre">bdist_egg</span></code>, <code class="docutils literal"><span class="pre">develop</span></code>, <code class="docutils literal"><span class="pre">register</span></code>, and <code class="docutils literal"><span class="pre">test</span></code> commands
in order to update the project&#8217;s metadata, but you can also specify it
explicitly in order to temporarily change the project&#8217;s version string while
executing other commands.  (It also generates the``.egg-info/SOURCES.txt``
manifest file, which is used when you are building source distributions.)</p>
<p>In addition to writing the core egg metadata defined by <code class="docutils literal"><span class="pre">setuptools</span></code> and
required by <code class="docutils literal"><span class="pre">pkg_resources</span></code>, this command can be extended to write other
metadata files as well, by defining entry points in the <code class="docutils literal"><span class="pre">egg_info.writers</span></code>
group.  See the section on <a class="reference internal" href="#adding-new-egg-info-files">Adding new EGG-INFO Files</a> below for more details.
Note that using additional metadata writers may require you to include a
<code class="docutils literal"><span class="pre">setup_requires</span></code> argument to <code class="docutils literal"><span class="pre">setup()</span></code> in order to ensure that the desired
writers are available on <code class="docutils literal"><span class="pre">sys.path</span></code>.</p>
<div class="section" id="release-tagging-options">
<h4><a class="toc-backref" href="#id41">Release Tagging Options</a><a class="headerlink" href="#release-tagging-options" title="Permalink to this headline"></a></h4>
<p>The following options can be used to modify the project&#8217;s version string for
all remaining commands on the setup command line.  The options are processed
in the order shown, so if you use more than one, the requested tags will be
added in the following order:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">--tag-build=NAME,</span> <span class="pre">-b</span> <span class="pre">NAME</span></code></dt>
<dd><p class="first">Append NAME to the project&#8217;s version string.  Due to the way setuptools
processes &#8220;pre-release&#8221; version suffixes beginning with the letters &#8220;a&#8221;
through &#8220;e&#8221; (like &#8220;alpha&#8221;, &#8220;beta&#8221;, and &#8220;candidate&#8221;), you will usually want
to use a tag like &#8221;.build&#8221; or &#8221;.dev&#8221;, as this will cause the version number
to be considered <em>lower</em> than the project&#8217;s default version.  (If you
want to make the version number <em>higher</em> than the default version, you can
always leave off &#8211;tag-build and then use one or both of the following
options.)</p>
<p class="last">If you have a default build tag set in your <code class="docutils literal"><span class="pre">setup.cfg</span></code>, you can suppress
it on the command line using <code class="docutils literal"><span class="pre">-b</span> <span class="pre">&quot;&quot;</span></code> or <code class="docutils literal"><span class="pre">--tag-build=&quot;&quot;</span></code> as an argument
to the <code class="docutils literal"><span class="pre">egg_info</span></code> command.</p>
</dd>
<dt><code class="docutils literal"><span class="pre">--tag-date,</span> <span class="pre">-d</span></code></dt>
<dd>Add a date stamp of the form &#8220;-YYYYMMDD&#8221; (e.g. &#8220;-20050528&#8221;) to the
project&#8217;s version number.</dd>
<dt><code class="docutils literal"><span class="pre">--no-date,</span> <span class="pre">-D</span></code></dt>
<dd>Don&#8217;t include a date stamp in the version number.  This option is included
so you can override a default setting in <code class="docutils literal"><span class="pre">setup.cfg</span></code>.</dd>
</dl>
<p>(Note: Because these options modify the version number used for source and
binary distributions of your project, you should first make sure that you know
how the resulting version numbers will be interpreted by automated tools
like EasyInstall.  See the section above on <a class="reference internal" href="#specifying-your-project-s-version">Specifying Your Project&#8217;s
Version</a> for an explanation of pre- and post-release tags, as well as tips on
how to choose and verify a versioning scheme for your your project.)</p>
<p>For advanced uses, there is one other option that can be set, to change the
location of the project&#8217;s <code class="docutils literal"><span class="pre">.egg-info</span></code> directory.  Commands that need to find
the project&#8217;s source directory or metadata should get it from this setting:</p>
</div>
<div class="section" id="other-egg-info-options">
<h4><a class="toc-backref" href="#id42">Other <code class="docutils literal"><span class="pre">egg_info</span></code> Options</a><a class="headerlink" href="#other-egg-info-options" title="Permalink to this headline"></a></h4>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">--egg-base=SOURCEDIR,</span> <span class="pre">-e</span> <span class="pre">SOURCEDIR</span></code></dt>
<dd>Specify the directory that should contain the .egg-info directory.  This
should normally be the root of your project&#8217;s source tree (which is not
necessarily the same as your project directory; some projects use a <code class="docutils literal"><span class="pre">src</span></code>
or <code class="docutils literal"><span class="pre">lib</span></code> subdirectory as the source root).  You should not normally need
to specify this directory, as it is normally determined from the
<code class="docutils literal"><span class="pre">package_dir</span></code> argument to the <code class="docutils literal"><span class="pre">setup()</span></code> function, if any.  If there is
no <code class="docutils literal"><span class="pre">package_dir</span></code> set, this option defaults to the current directory.</dd>
</dl>
</div>
<div class="section" id="egg-info-examples">
<h4><a class="toc-backref" href="#id43"><code class="docutils literal"><span class="pre">egg_info</span></code> Examples</a><a class="headerlink" href="#egg-info-examples" title="Permalink to this headline"></a></h4>
<p>Creating a dated &#8220;nightly build&#8221; snapshot egg:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">egg_info</span> <span class="o">--</span><span class="n">tag</span><span class="o">-</span><span class="n">date</span> <span class="o">--</span><span class="n">tag</span><span class="o">-</span><span class="n">build</span><span class="o">=</span><span class="n">DEV</span> <span class="n">bdist_egg</span>
</pre></div>
</div>
<p>Creating and uploading a release with no version tags, even if some default
tags are specified in <code class="docutils literal"><span class="pre">setup.cfg</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">egg_info</span> <span class="o">-</span><span class="n">RDb</span> <span class="s2">&quot;&quot;</span> <span class="n">sdist</span> <span class="n">bdist_egg</span> <span class="n">register</span> <span class="n">upload</span>
</pre></div>
</div>
<p>(Notice that <code class="docutils literal"><span class="pre">egg_info</span></code> must always appear on the command line <em>before</em> any
commands that you want the version changes to apply to.)</p>
</div>
</div>
<div class="section" id="install-run-easy-install-or-old-style-installation">
<span id="install-command"></span><h3><a class="toc-backref" href="#id44"><code class="docutils literal"><span class="pre">install</span></code> - Run <code class="docutils literal"><span class="pre">easy_install</span></code> or old-style installation</a><a class="headerlink" href="#install-run-easy-install-or-old-style-installation" title="Permalink to this headline"></a></h3>
<p>The setuptools <code class="docutils literal"><span class="pre">install</span></code> command is basically a shortcut to run the
<code class="docutils literal"><span class="pre">easy_install</span></code> command on the current project.  However, for convenience
in creating &#8220;system packages&#8221; of setuptools-based projects, you can also
use this option:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">--single-version-externally-managed</span></code></dt>
<dd>This boolean option tells the <code class="docutils literal"><span class="pre">install</span></code> command to perform an &#8220;old style&#8221;
installation, with the addition of an <code class="docutils literal"><span class="pre">.egg-info</span></code> directory so that the
installed project will still have its metadata available and operate
normally.  If you use this option, you <em>must</em> also specify the <code class="docutils literal"><span class="pre">--root</span></code>
or <code class="docutils literal"><span class="pre">--record</span></code> options (or both), because otherwise you will have no way
to identify and remove the installed files.</dd>
</dl>
<p>This option is automatically in effect when <code class="docutils literal"><span class="pre">install</span></code> is invoked by another
distutils command, so that commands like <code class="docutils literal"><span class="pre">bdist_wininst</span></code> and <code class="docutils literal"><span class="pre">bdist_rpm</span></code>
will create system packages of eggs.  It is also automatically in effect if
you specify the <code class="docutils literal"><span class="pre">--root</span></code> option.</p>
</div>
<div class="section" id="install-egg-info-install-an-egg-info-directory-in-site-packages">
<h3><a class="toc-backref" href="#id45"><code class="docutils literal"><span class="pre">install_egg_info</span></code> - Install an <code class="docutils literal"><span class="pre">.egg-info</span></code> directory in <code class="docutils literal"><span class="pre">site-packages</span></code></a><a class="headerlink" href="#install-egg-info-install-an-egg-info-directory-in-site-packages" title="Permalink to this headline"></a></h3>
<p>Setuptools runs this command as part of <code class="docutils literal"><span class="pre">install</span></code> operations that use the
<code class="docutils literal"><span class="pre">--single-version-externally-managed</span></code> options.  You should not invoke it
directly; it is documented here for completeness and so that distutils
extensions such as system package builders can make use of it.  This command
has only one option:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">--install-dir=DIR,</span> <span class="pre">-d</span> <span class="pre">DIR</span></code></dt>
<dd>The parent directory where the <code class="docutils literal"><span class="pre">.egg-info</span></code> directory will be placed.
Defaults to the same as the <code class="docutils literal"><span class="pre">--install-dir</span></code> option specified for the
<code class="docutils literal"><span class="pre">install_lib</span></code> command, which is usually the system <code class="docutils literal"><span class="pre">site-packages</span></code>
directory.</dd>
</dl>
<p>This command assumes that the <code class="docutils literal"><span class="pre">egg_info</span></code> command has been given valid options
via the command line or <code class="docutils literal"><span class="pre">setup.cfg</span></code>, as it will invoke the <code class="docutils literal"><span class="pre">egg_info</span></code>
command and use its options to locate the project&#8217;s source <code class="docutils literal"><span class="pre">.egg-info</span></code>
directory.</p>
</div>
<div class="section" id="rotate-delete-outdated-distribution-files">
<span id="rotate"></span><h3><a class="toc-backref" href="#id46"><code class="docutils literal"><span class="pre">rotate</span></code> - Delete outdated distribution files</a><a class="headerlink" href="#rotate-delete-outdated-distribution-files" title="Permalink to this headline"></a></h3>
<p>As you develop new versions of your project, your distribution (<code class="docutils literal"><span class="pre">dist</span></code>)
directory will gradually fill up with older source and/or binary distribution
files.  The <code class="docutils literal"><span class="pre">rotate</span></code> command lets you automatically clean these up, keeping
only the N most-recently modified files matching a given pattern.</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">--match=PATTERNLIST,</span> <span class="pre">-m</span> <span class="pre">PATTERNLIST</span></code></dt>
<dd>Comma-separated list of glob patterns to match.  This option is <em>required</em>.
The project name and <code class="docutils literal"><span class="pre">-*</span></code> is prepended to the supplied patterns, in order
to match only distributions belonging to the current project (in case you
have a shared distribution directory for multiple projects).  Typically,
you will use a glob pattern like <code class="docutils literal"><span class="pre">.zip</span></code> or <code class="docutils literal"><span class="pre">.egg</span></code> to match files of
the specified type.  Note that each supplied pattern is treated as a
distinct group of files for purposes of selecting files to delete.</dd>
<dt><code class="docutils literal"><span class="pre">--keep=COUNT,</span> <span class="pre">-k</span> <span class="pre">COUNT</span></code></dt>
<dd>Number of matching distributions to keep.  For each group of files
identified by a pattern specified with the <code class="docutils literal"><span class="pre">--match</span></code> option, delete all
but the COUNT most-recently-modified files in that group.  This option is
<em>required</em>.</dd>
<dt><code class="docutils literal"><span class="pre">--dist-dir=DIR,</span> <span class="pre">-d</span> <span class="pre">DIR</span></code></dt>
<dd>Directory where the distributions are.  This defaults to the value of the
<code class="docutils literal"><span class="pre">bdist</span></code> command&#8217;s <code class="docutils literal"><span class="pre">--dist-dir</span></code> option, which will usually be the
project&#8217;s <code class="docutils literal"><span class="pre">dist</span></code> subdirectory.</dd>
</dl>
<p><strong>Example 1</strong>: Delete all .tar.gz files from the distribution directory, except
for the 3 most recently modified ones:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">rotate</span> <span class="o">--</span><span class="n">match</span><span class="o">=.</span><span class="n">tar</span><span class="o">.</span><span class="n">gz</span> <span class="o">--</span><span class="n">keep</span><span class="o">=</span><span class="mi">3</span>
</pre></div>
</div>
<p><strong>Example 2</strong>: Delete all Python 2.3 or Python 2.4 eggs from the distribution
directory, except the most recently modified one for each Python version:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">rotate</span> <span class="o">--</span><span class="n">match</span><span class="o">=-</span><span class="n">py2</span><span class="o">.</span><span class="mi">3</span><span class="o">*.</span><span class="n">egg</span><span class="p">,</span><span class="o">-</span><span class="n">py2</span><span class="o">.</span><span class="mi">4</span><span class="o">*.</span><span class="n">egg</span> <span class="o">--</span><span class="n">keep</span><span class="o">=</span><span class="mi">1</span>
</pre></div>
</div>
</div>
<div class="section" id="saveopts-save-used-options-to-a-configuration-file">
<span id="saveopts"></span><h3><a class="toc-backref" href="#id47"><code class="docutils literal"><span class="pre">saveopts</span></code> - Save used options to a configuration file</a><a class="headerlink" href="#saveopts-save-used-options-to-a-configuration-file" title="Permalink to this headline"></a></h3>
<p>Finding and editing <code class="docutils literal"><span class="pre">distutils</span></code> configuration files can be a pain, especially
since you also have to translate the configuration options from command-line
form to the proper configuration file format.  You can avoid these hassles by
using the <code class="docutils literal"><span class="pre">saveopts</span></code> command.  Just add it to the command line to save the
options you used.  For example, this command builds the project using
the <code class="docutils literal"><span class="pre">mingw32</span></code> C compiler, then saves the &#8211;compiler setting as the default
for future builds (even those run implicitly by the <code class="docutils literal"><span class="pre">install</span></code> command):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">build</span> <span class="o">--</span><span class="n">compiler</span><span class="o">=</span><span class="n">mingw32</span> <span class="n">saveopts</span>
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">saveopts</span></code> command saves all options for every command specified on the
command line to the project&#8217;s local <code class="docutils literal"><span class="pre">setup.cfg</span></code> file, unless you use one of
the <a class="reference internal" href="#configuration-file-options">configuration file options</a> to change where the options are saved.  For
example, this command does the same as above, but saves the compiler setting
to the site-wide (global) distutils configuration:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">build</span> <span class="o">--</span><span class="n">compiler</span><span class="o">=</span><span class="n">mingw32</span> <span class="n">saveopts</span> <span class="o">-</span><span class="n">g</span>
</pre></div>
</div>
<p>Note that it doesn&#8217;t matter where you place the <code class="docutils literal"><span class="pre">saveopts</span></code> command on the
command line; it will still save all the options specified for all commands.
For example, this is another valid way to spell the last example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">saveopts</span> <span class="o">-</span><span class="n">g</span> <span class="n">build</span> <span class="o">--</span><span class="n">compiler</span><span class="o">=</span><span class="n">mingw32</span>
</pre></div>
</div>
<p>Note, however, that all of the commands specified are always run, regardless of
where <code class="docutils literal"><span class="pre">saveopts</span></code> is placed on the command line.</p>
<div class="section" id="configuration-file-options">
<h4><a class="toc-backref" href="#id48">Configuration File Options</a><a class="headerlink" href="#configuration-file-options" title="Permalink to this headline"></a></h4>
<p>Normally, settings such as options and aliases are saved to the project&#8217;s
local <code class="docutils literal"><span class="pre">setup.cfg</span></code> file.  But you can override this and save them to the
global or per-user configuration files, or to a manually-specified filename.</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">--global-config,</span> <span class="pre">-g</span></code></dt>
<dd>Save settings to the global <code class="docutils literal"><span class="pre">distutils.cfg</span></code> file inside the <code class="docutils literal"><span class="pre">distutils</span></code>
package directory.  You must have write access to that directory to use
this option.  You also can&#8217;t combine this option with <code class="docutils literal"><span class="pre">-u</span></code> or <code class="docutils literal"><span class="pre">-f</span></code>.</dd>
<dt><code class="docutils literal"><span class="pre">--user-config,</span> <span class="pre">-u</span></code></dt>
<dd>Save settings to the current user&#8217;s <code class="docutils literal"><span class="pre">~/.pydistutils.cfg</span></code> (POSIX) or
<code class="docutils literal"><span class="pre">$HOME/pydistutils.cfg</span></code> (Windows) file.  You can&#8217;t combine this option
with <code class="docutils literal"><span class="pre">-g</span></code> or <code class="docutils literal"><span class="pre">-f</span></code>.</dd>
<dt><code class="docutils literal"><span class="pre">--filename=FILENAME,</span> <span class="pre">-f</span> <span class="pre">FILENAME</span></code></dt>
<dd>Save settings to the specified configuration file to use.  You can&#8217;t
combine this option with <code class="docutils literal"><span class="pre">-g</span></code> or <code class="docutils literal"><span class="pre">-u</span></code>.  Note that if you specify a
non-standard filename, the <code class="docutils literal"><span class="pre">distutils</span></code> and <code class="docutils literal"><span class="pre">setuptools</span></code> will not
use the file&#8217;s contents.  This option is mainly included for use in
testing.</dd>
</dl>
<p>These options are used by other <code class="docutils literal"><span class="pre">setuptools</span></code> commands that modify
configuration files, such as the <a class="reference internal" href="#alias">alias</a> and <a class="reference internal" href="#setopt">setopt</a> commands.</p>
</div>
</div>
<div class="section" id="setopt-set-a-distutils-or-setuptools-option-in-a-config-file">
<span id="setopt"></span><h3><a class="toc-backref" href="#id49"><code class="docutils literal"><span class="pre">setopt</span></code> - Set a distutils or setuptools option in a config file</a><a class="headerlink" href="#setopt-set-a-distutils-or-setuptools-option-in-a-config-file" title="Permalink to this headline"></a></h3>
<p>This command is mainly for use by scripts, but it can also be used as a quick
and dirty way to change a distutils configuration option without having to
remember what file the options are in and then open an editor.</p>
<p><strong>Example 1</strong>.  Set the default C compiler to <code class="docutils literal"><span class="pre">mingw32</span></code> (using long option
names):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">setopt</span> <span class="o">--</span><span class="n">command</span><span class="o">=</span><span class="n">build</span> <span class="o">--</span><span class="n">option</span><span class="o">=</span><span class="n">compiler</span> <span class="o">--</span><span class="nb">set</span><span class="o">-</span><span class="n">value</span><span class="o">=</span><span class="n">mingw32</span>
</pre></div>
</div>
<p><strong>Example 2</strong>.  Remove any setting for the distutils default package
installation directory (short option names):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">setopt</span> <span class="o">-</span><span class="n">c</span> <span class="n">install</span> <span class="o">-</span><span class="n">o</span> <span class="n">install_lib</span> <span class="o">-</span><span class="n">r</span>
</pre></div>
</div>
<p>Options for the <code class="docutils literal"><span class="pre">setopt</span></code> command:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">--command=COMMAND,</span> <span class="pre">-c</span> <span class="pre">COMMAND</span></code></dt>
<dd>Command to set the option for.  This option is required.</dd>
<dt><code class="docutils literal"><span class="pre">--option=OPTION,</span> <span class="pre">-o</span> <span class="pre">OPTION</span></code></dt>
<dd>The name of the option to set.  This option is required.</dd>
<dt><code class="docutils literal"><span class="pre">--set-value=VALUE,</span> <span class="pre">-s</span> <span class="pre">VALUE</span></code></dt>
<dd>The value to set the option to.  Not needed if <code class="docutils literal"><span class="pre">-r</span></code> or <code class="docutils literal"><span class="pre">--remove</span></code> is
set.</dd>
<dt><code class="docutils literal"><span class="pre">--remove,</span> <span class="pre">-r</span></code></dt>
<dd>Remove (unset) the option, instead of setting it.</dd>
</dl>
<p>In addition to the above options, you may use any of the <a class="reference internal" href="#configuration-file-options">configuration file
options</a> (listed under the <a class="reference internal" href="#saveopts">saveopts</a> command, above) to determine which
distutils configuration file the option will be added to (or removed from).</p>
</div>
<div class="section" id="test-build-package-and-run-a-unittest-suite">
<span id="test"></span><h3><a class="toc-backref" href="#id50"><code class="docutils literal"><span class="pre">test</span></code> - Build package and run a unittest suite</a><a class="headerlink" href="#test-build-package-and-run-a-unittest-suite" title="Permalink to this headline"></a></h3>
<p>When doing test-driven development, or running automated builds that need
testing before they are deployed for downloading or use, it&#8217;s often useful
to be able to run a project&#8217;s unit tests without actually deploying the project
anywhere, even using the <code class="docutils literal"><span class="pre">develop</span></code> command.  The <code class="docutils literal"><span class="pre">test</span></code> command runs a
project&#8217;s unit tests without actually deploying it, by temporarily putting the
project&#8217;s source on <code class="docutils literal"><span class="pre">sys.path</span></code>, after first running <code class="docutils literal"><span class="pre">build_ext</span> <span class="pre">-i</span></code> and
<code class="docutils literal"><span class="pre">egg_info</span></code> to ensure that any C extensions and project metadata are
up-to-date.</p>
<p>To use this command, your project&#8217;s tests must be wrapped in a <code class="docutils literal"><span class="pre">unittest</span></code>
test suite by either a function, a <code class="docutils literal"><span class="pre">TestCase</span></code> class or method, or a module
or package containing <code class="docutils literal"><span class="pre">TestCase</span></code> classes.  If the named suite is a module,
and the module has an <code class="docutils literal"><span class="pre">additional_tests()</span></code> function, it is called and the
result (which must be a <code class="docutils literal"><span class="pre">unittest.TestSuite</span></code>) is added to the tests to be
run.  If the named suite is a package, any submodules and subpackages are
recursively added to the overall test suite.  (Note: if your project specifies
a <code class="docutils literal"><span class="pre">test_loader</span></code>, the rules for processing the chosen <code class="docutils literal"><span class="pre">test_suite</span></code> may
differ; see the <a class="reference internal" href="#test-loader">test_loader</a> documentation for more details.)</p>
<p>Note that many test systems including <code class="docutils literal"><span class="pre">doctest</span></code> support wrapping their
non-<code class="docutils literal"><span class="pre">unittest</span></code> tests in <code class="docutils literal"><span class="pre">TestSuite</span></code> objects.  So, if you are using a test
package that does not support this, we suggest you encourage its developers to
implement test suite support, as this is a convenient and standard way to
aggregate a collection of tests to be run under a common test harness.</p>
<p>By default, tests will be run in the &#8220;verbose&#8221; mode of the <code class="docutils literal"><span class="pre">unittest</span></code>
package&#8217;s text test runner, but you can get the &#8220;quiet&#8221; mode (just dots) if
you supply the <code class="docutils literal"><span class="pre">-q</span></code> or <code class="docutils literal"><span class="pre">--quiet</span></code> option, either as a global option to
the setup script (e.g. <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">-q</span> <span class="pre">test</span></code>) or as an option for the <code class="docutils literal"><span class="pre">test</span></code>
command itself (e.g. <code class="docutils literal"><span class="pre">setup.py</span> <span class="pre">test</span> <span class="pre">-q</span></code>).  There is one other option
available:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">--test-suite=NAME,</span> <span class="pre">-s</span> <span class="pre">NAME</span></code></dt>
<dd><p class="first">Specify the test suite (or module, class, or method) to be run
(e.g. <code class="docutils literal"><span class="pre">some_module.test_suite</span></code>).  The default for this option can be
set by giving a <code class="docutils literal"><span class="pre">test_suite</span></code> argument to the <code class="docutils literal"><span class="pre">setup()</span></code> function, e.g.:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="c1"># ...</span>
    <span class="n">test_suite</span><span class="o">=</span><span class="s2">&quot;my_package.tests.test_all&quot;</span>
<span class="p">)</span>
</pre></div>
</div>
<p class="last">If you did not set a <code class="docutils literal"><span class="pre">test_suite</span></code> in your <code class="docutils literal"><span class="pre">setup()</span></code> call, and do not
provide a <code class="docutils literal"><span class="pre">--test-suite</span></code> option, an error will occur.</p>
</dd>
</dl>
</div>
<div class="section" id="upload-upload-source-and-or-egg-distributions-to-pypi">
<span id="upload"></span><h3><a class="toc-backref" href="#id51"><code class="docutils literal"><span class="pre">upload</span></code> - Upload source and/or egg distributions to PyPI</a><a class="headerlink" href="#upload-upload-source-and-or-egg-distributions-to-pypi" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal"><span class="pre">upload</span></code> command is implemented and <a class="reference external" href="https://docs.python.org/3.1/distutils/uploading.html">documented</a>
in distutils.</p>
<p>Setuptools augments the <code class="docutils literal"><span class="pre">upload</span></code> command with support
for <a class="reference external" href="https://pypi.python.org/pypi/keyring">keyring</a>,
allowing the password to be stored in a secure
location and not in plaintext in the .pypirc file. To use
keyring, first install keyring and set the password for
the relevant repository, e.g.:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">keyring</span> <span class="nb">set</span> <span class="o">&lt;</span><span class="n">repository</span><span class="o">&gt;</span> <span class="o">&lt;</span><span class="n">username</span><span class="o">&gt;</span>
<span class="n">Password</span> <span class="k">for</span> <span class="s1">&#39;&lt;username&gt;&#39;</span> <span class="ow">in</span> <span class="s1">&#39;&lt;repository&gt;&#39;</span><span class="p">:</span> <span class="o">********</span>
</pre></div>
</div>
<p>Then, in .pypirc, set the repository configuration as normal,
but omit the password. Thereafter, uploads will use the
password from the keyring.</p>
<p>New in 20.1: Added keyring support.</p>
</div>
</div>
<div class="section" id="configuring-setup-using-setup-cfg-files">
<h2><a class="toc-backref" href="#id52">Configuring setup() using setup.cfg files</a><a class="headerlink" href="#configuring-setup-using-setup-cfg-files" title="Permalink to this headline"></a></h2>
<p><code class="docutils literal"><span class="pre">Setuptools</span></code> allows using configuration files (usually <cite>setup.cfg</cite>)
to define package’s metadata and other options which are normally supplied
to <code class="docutils literal"><span class="pre">setup()</span></code> function.</p>
<p>This approach not only allows automation scenarios, but also reduces
boilerplate code in some cases.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Implementation presents limited compatibility with distutils2-like
<code class="docutils literal"><span class="pre">setup.cfg</span></code> sections (used by <code class="docutils literal"><span class="pre">pbr</span></code> and <code class="docutils literal"><span class="pre">d2to1</span></code> packages).</p>
<p class="last">Namely: only metadata related keys from <code class="docutils literal"><span class="pre">metadata</span></code> section are supported
(except for <code class="docutils literal"><span class="pre">description-file</span></code>); keys from <code class="docutils literal"><span class="pre">files</span></code>, <code class="docutils literal"><span class="pre">entry_points</span></code>
and <code class="docutils literal"><span class="pre">backwards_compat</span></code> are not supported.</p>
</div>
<div class="highlight-ini"><div class="highlight"><pre><span></span>[metadata]
name = my_package
version = attr: src.VERSION
description = My package description
long_description = file: README.rst
keywords = one, two
license = BSD 3-Clause License

[metadata.classifiers]
Framework :: Django
Programming Language :: Python :: 3.5

[options]
zip_safe = False
include_package_data = True
packages = find:
scripts =
  bin/first.py
  bin/second.py

[options.package_data]
* = *.txt, *.rst
hello = *.msg

[options.extras_require]
pdf = ReportLab&gt;=1.2; RXP
rest = docutils&gt;=0.3; pack ==1.1, ==1.3

[options.packages.find]
exclude =
    src.subpackage1
    src.subpackage2
</pre></div>
</div>
<p>Metadata and options could be set in sections with the same names.</p>
<ul>
<li><p class="first">Keys are the same as keyword arguments one provides to <code class="docutils literal"><span class="pre">setup()</span></code> function.</p>
</li>
<li><p class="first">Complex values could be placed comma-separated or one per line
in <em>dangling</em> sections. The following are the same:</p>
<div class="highlight-ini"><div class="highlight"><pre><span></span><span class="k">[metadata]</span>
<span class="na">keywords</span> <span class="o">=</span> <span class="s">one, two</span>

<span class="k">[metadata]</span>
<span class="na">keywords</span> <span class="o">=</span><span class="s"></span>
<span class="s">  one</span>
<span class="s">  two</span>
</pre></div>
</div>
</li>
<li><p class="first">In some cases complex values could be provided in subsections for clarity.</p>
</li>
<li><p class="first">Some keys allow <code class="docutils literal"><span class="pre">file:</span></code>, <code class="docutils literal"><span class="pre">attr:</span></code> and <code class="docutils literal"><span class="pre">find:</span></code> directives to cover
common usecases.</p>
</li>
<li><p class="first">Unknown keys are ignored.</p>
</li>
</ul>
<div class="section" id="specifying-values">
<h3><a class="toc-backref" href="#id53">Specifying values</a><a class="headerlink" href="#specifying-values" title="Permalink to this headline"></a></h3>
<p>Some values are treated as simple strings, some allow more logic.</p>
<p>Type names used below:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">str</span></code> - simple string</li>
<li><code class="docutils literal"><span class="pre">list-comma</span></code> - dangling list or comma-separated values string</li>
<li><code class="docutils literal"><span class="pre">list-semi</span></code> - dangling list or semicolon-separated values string</li>
<li><code class="docutils literal"><span class="pre">bool</span></code> -  <code class="docutils literal"><span class="pre">True</span></code> is 1, yes, true</li>
<li><code class="docutils literal"><span class="pre">dict</span></code> - list-comma where keys from values are separated by =</li>
<li><code class="docutils literal"><span class="pre">section</span></code> - values could be read from a dedicated (sub)section</li>
</ul>
<p>Special directives:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">attr:</span></code> - value could be read from module attribute</li>
<li><code class="docutils literal"><span class="pre">file:</span></code> - value could be read from a file</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><code class="docutils literal"><span class="pre">file:</span></code> directive is sandboxed and won&#8217;t reach anything outside
directory with <code class="docutils literal"><span class="pre">setup.py</span></code>.</p>
</div>
<div class="section" id="metadata">
<h4><a class="toc-backref" href="#id54">Metadata</a><a class="headerlink" href="#metadata" title="Permalink to this headline"></a></h4>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Aliases given below are supported for compatibility reasons,
but not advised.</p>
</div>
<table border="1" class="docutils">
<colgroup>
<col width="28%" />
<col width="28%" />
<col width="43%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Key</th>
<th class="head">Aliases</th>
<th class="head">Accepted value type</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>name</td>
<td>&nbsp;</td>
<td>str</td>
</tr>
<tr class="row-odd"><td>version</td>
<td>&nbsp;</td>
<td>attr:, str</td>
</tr>
<tr class="row-even"><td>url</td>
<td>home-page</td>
<td>str</td>
</tr>
<tr class="row-odd"><td>download_url</td>
<td>download-url</td>
<td>str</td>
</tr>
<tr class="row-even"><td>author</td>
<td>&nbsp;</td>
<td>str</td>
</tr>
<tr class="row-odd"><td>author_email</td>
<td>author-email</td>
<td>str</td>
</tr>
<tr class="row-even"><td>maintainer</td>
<td>&nbsp;</td>
<td>str</td>
</tr>
<tr class="row-odd"><td>maintainer_email</td>
<td>maintainer-email</td>
<td>str</td>
</tr>
<tr class="row-even"><td>classifiers</td>
<td>classifier</td>
<td>file:, section, list-comma</td>
</tr>
<tr class="row-odd"><td>license</td>
<td>&nbsp;</td>
<td>file:, str</td>
</tr>
<tr class="row-even"><td>description</td>
<td>summary</td>
<td>file:, str</td>
</tr>
<tr class="row-odd"><td>long_description</td>
<td>long-description</td>
<td>file:, str</td>
</tr>
<tr class="row-even"><td>keywords</td>
<td>&nbsp;</td>
<td>list-comma</td>
</tr>
<tr class="row-odd"><td>platforms</td>
<td>platform</td>
<td>list-comma</td>
</tr>
<tr class="row-even"><td>provides</td>
<td>&nbsp;</td>
<td>list-comma</td>
</tr>
<tr class="row-odd"><td>requires</td>
<td>&nbsp;</td>
<td>list-comma</td>
</tr>
<tr class="row-even"><td>obsoletes</td>
<td>&nbsp;</td>
<td>list-comma</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><strong>version</strong> - <code class="docutils literal"><span class="pre">attr:</span></code> supports callables; supports iterables;
unsupported types are casted using <code class="docutils literal"><span class="pre">str()</span></code>.</p>
</div>
</div>
<div class="section" id="options">
<h4><a class="toc-backref" href="#id55">Options</a><a class="headerlink" href="#options" title="Permalink to this headline"></a></h4>
<table border="1" class="docutils">
<colgroup>
<col width="55%" />
<col width="45%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Key</th>
<th class="head">Accepted value type</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>zip_safe</td>
<td>bool</td>
</tr>
<tr class="row-odd"><td>setup_requires</td>
<td>list-semi</td>
</tr>
<tr class="row-even"><td>install_requires</td>
<td>list-semi</td>
</tr>
<tr class="row-odd"><td>extras_require</td>
<td>section</td>
</tr>
<tr class="row-even"><td>entry_points</td>
<td>file:, section</td>
</tr>
<tr class="row-odd"><td>use_2to3</td>
<td>bool</td>
</tr>
<tr class="row-even"><td>use_2to3_fixers</td>
<td>list-comma</td>
</tr>
<tr class="row-odd"><td>use_2to3_exclude_fixers</td>
<td>list-comma</td>
</tr>
<tr class="row-even"><td>convert_2to3_doctests</td>
<td>list-comma</td>
</tr>
<tr class="row-odd"><td>scripts</td>
<td>list-comma</td>
</tr>
<tr class="row-even"><td>eager_resources</td>
<td>list-comma</td>
</tr>
<tr class="row-odd"><td>dependency_links</td>
<td>list-comma</td>
</tr>
<tr class="row-even"><td>tests_require</td>
<td>list-semi</td>
</tr>
<tr class="row-odd"><td>include_package_data</td>
<td>bool</td>
</tr>
<tr class="row-even"><td>packages</td>
<td>find:, list-comma</td>
</tr>
<tr class="row-odd"><td>package_dir</td>
<td>dict</td>
</tr>
<tr class="row-even"><td>package_data</td>
<td>section</td>
</tr>
<tr class="row-odd"><td>exclude_package_data</td>
<td>section</td>
</tr>
<tr class="row-even"><td>namespace_packages</td>
<td>list-comma</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><strong>packages</strong> - <code class="docutils literal"><span class="pre">find:</span></code> directive can be further configured
in a dedicated subsection <cite>options.packages.find</cite>. This subsection
accepts the same keys as <cite>setuptools.find</cite> function:
<cite>where</cite>, <cite>include</cite>, <cite>exclude</cite>.</p>
</div>
</div>
</div>
<div class="section" id="configuration-api">
<h3><a class="toc-backref" href="#id56">Configuration API</a><a class="headerlink" href="#configuration-api" title="Permalink to this headline"></a></h3>
<p>Some automation tools may wish to access data from a configuration file.</p>
<p><code class="docutils literal"><span class="pre">Setuptools</span></code> exposes <code class="docutils literal"><span class="pre">read_configuration()</span></code> function allowing
parsing <code class="docutils literal"><span class="pre">metadata</span></code> and <code class="docutils literal"><span class="pre">options</span></code> sections into a dictionary.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">setuptools.config</span> <span class="kn">import</span> <span class="n">read_configuration</span>

<span class="n">conf_dict</span> <span class="o">=</span> <span class="n">read_configuration</span><span class="p">(</span><span class="s1">&#39;/home/user/dev/package/setup.cfg&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>By default <code class="docutils literal"><span class="pre">read_configuration()</span></code> will read only file provided
in the first argument. To include values from other configuration files
which could be in various places set <cite>find_others</cite> function argument
to <code class="docutils literal"><span class="pre">True</span></code>.</p>
<p>If you have only a configuration file but not the whole package you can still
try to get data out of it with the help of <cite>ignore_option_errors</cite> function
argument. When it is set to <code class="docutils literal"><span class="pre">True</span></code> all options with errors possibly produced
by directives, such as <code class="docutils literal"><span class="pre">attr:</span></code> and others will be silently ignored.
As a consequence the resulting dictionary will include no such options.</p>
</div>
</div>
<div class="section" id="extending-and-reusing-setuptools">
<h2><a class="toc-backref" href="#id57">Extending and Reusing Setuptools</a><a class="headerlink" href="#extending-and-reusing-setuptools" title="Permalink to this headline"></a></h2>
<div class="section" id="creating-distutils-extensions">
<h3><a class="toc-backref" href="#id58">Creating <code class="docutils literal"><span class="pre">distutils</span></code> Extensions</a><a class="headerlink" href="#creating-distutils-extensions" title="Permalink to this headline"></a></h3>
<p>It can be hard to add new commands or setup arguments to the distutils.  But
the <code class="docutils literal"><span class="pre">setuptools</span></code> package makes it a bit easier, by allowing you to distribute
a distutils extension as a separate project, and then have projects that need
the extension just refer to it in their <code class="docutils literal"><span class="pre">setup_requires</span></code> argument.</p>
<p>With <code class="docutils literal"><span class="pre">setuptools</span></code>, your distutils extension projects can hook in new
commands and <code class="docutils literal"><span class="pre">setup()</span></code> arguments just by defining &#8220;entry points&#8221;.  These
are mappings from command or argument names to a specification of where to
import a handler from.  (See the section on <a class="reference internal" href="#dynamic-discovery-of-services-and-plugins">Dynamic Discovery of Services and
Plugins</a> above for some more background on entry points.)</p>
<div class="section" id="adding-commands">
<h4><a class="toc-backref" href="#id59">Adding Commands</a><a class="headerlink" href="#adding-commands" title="Permalink to this headline"></a></h4>
<p>You can add new <code class="docutils literal"><span class="pre">setup</span></code> commands by defining entry points in the
<code class="docutils literal"><span class="pre">distutils.commands</span></code> group.  For example, if you wanted to add a <code class="docutils literal"><span class="pre">foo</span></code>
command, you might add something like this to your distutils extension
project&#8217;s setup script:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="c1"># ...</span>
    <span class="n">entry_points</span><span class="o">=</span><span class="p">{</span>
        <span class="s2">&quot;distutils.commands&quot;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s2">&quot;foo = mypackage.some_module:foo&quot;</span><span class="p">,</span>
        <span class="p">],</span>
    <span class="p">},</span>
<span class="p">)</span>
</pre></div>
</div>
<p>(Assuming, of course, that the <code class="docutils literal"><span class="pre">foo</span></code> class in <code class="docutils literal"><span class="pre">mypackage.some_module</span></code> is
a <code class="docutils literal"><span class="pre">setuptools.Command</span></code> subclass.)</p>
<p>Once a project containing such entry points has been activated on <code class="docutils literal"><span class="pre">sys.path</span></code>,
(e.g. by running &#8220;install&#8221; or &#8220;develop&#8221; with a site-packages installation
directory) the command(s) will be available to any <code class="docutils literal"><span class="pre">setuptools</span></code>-based setup
scripts.  It is not necessary to use the <code class="docutils literal"><span class="pre">--command-packages</span></code> option or
to monkeypatch the <code class="docutils literal"><span class="pre">distutils.command</span></code> package to install your commands;
<code class="docutils literal"><span class="pre">setuptools</span></code> automatically adds a wrapper to the distutils to search for
entry points in the active distributions on <code class="docutils literal"><span class="pre">sys.path</span></code>.  In fact, this is
how setuptools&#8217; own commands are installed: the setuptools project&#8217;s setup
script defines entry points for them!</p>
</div>
<div class="section" id="adding-setup-arguments">
<h4><a class="toc-backref" href="#id60">Adding <code class="docutils literal"><span class="pre">setup()</span></code> Arguments</a><a class="headerlink" href="#adding-setup-arguments" title="Permalink to this headline"></a></h4>
<p>Sometimes, your commands may need additional arguments to the <code class="docutils literal"><span class="pre">setup()</span></code>
call.  You can enable this by defining entry points in the
<code class="docutils literal"><span class="pre">distutils.setup_keywords</span></code> group.  For example, if you wanted a <code class="docutils literal"><span class="pre">setup()</span></code>
argument called <code class="docutils literal"><span class="pre">bar_baz</span></code>, you might add something like this to your
distutils extension project&#8217;s setup script:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="c1"># ...</span>
    <span class="n">entry_points</span><span class="o">=</span><span class="p">{</span>
        <span class="s2">&quot;distutils.commands&quot;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s2">&quot;foo = mypackage.some_module:foo&quot;</span><span class="p">,</span>
        <span class="p">],</span>
        <span class="s2">&quot;distutils.setup_keywords&quot;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s2">&quot;bar_baz = mypackage.some_module:validate_bar_baz&quot;</span><span class="p">,</span>
        <span class="p">],</span>
    <span class="p">},</span>
<span class="p">)</span>
</pre></div>
</div>
<p>The idea here is that the entry point defines a function that will be called
to validate the <code class="docutils literal"><span class="pre">setup()</span></code> argument, if it&#8217;s supplied.  The <code class="docutils literal"><span class="pre">Distribution</span></code>
object will have the initial value of the attribute set to <code class="docutils literal"><span class="pre">None</span></code>, and the
validation function will only be called if the <code class="docutils literal"><span class="pre">setup()</span></code> call sets it to
a non-None value.  Here&#8217;s an example validation function:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">assert_bool</span><span class="p">(</span><span class="n">dist</span><span class="p">,</span> <span class="n">attr</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;Verify that value is True, False, 0, or 1&quot;&quot;&quot;</span>
    <span class="k">if</span> <span class="nb">bool</span><span class="p">(</span><span class="n">value</span><span class="p">)</span> <span class="o">!=</span> <span class="n">value</span><span class="p">:</span>
        <span class="k">raise</span> <span class="n">DistutilsSetupError</span><span class="p">(</span>
            <span class="s2">&quot;</span><span class="si">%r</span><span class="s2"> must be a boolean value (got </span><span class="si">%r</span><span class="s2">)&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">attr</span><span class="p">,</span><span class="n">value</span><span class="p">)</span>
        <span class="p">)</span>
</pre></div>
</div>
<p>Your function should accept three arguments: the <code class="docutils literal"><span class="pre">Distribution</span></code> object,
the attribute name, and the attribute value.  It should raise a
<code class="docutils literal"><span class="pre">DistutilsSetupError</span></code> (from the <code class="docutils literal"><span class="pre">distutils.errors</span></code> module) if the argument
is invalid.  Remember, your function will only be called with non-None values,
and the default value of arguments defined this way is always None.  So, your
commands should always be prepared for the possibility that the attribute will
be <code class="docutils literal"><span class="pre">None</span></code> when they access it later.</p>
<p>If more than one active distribution defines an entry point for the same
<code class="docutils literal"><span class="pre">setup()</span></code> argument, <em>all</em> of them will be called.  This allows multiple
distutils extensions to define a common argument, as long as they agree on
what values of that argument are valid.</p>
<p>Also note that as with commands, it is not necessary to subclass or monkeypatch
the distutils <code class="docutils literal"><span class="pre">Distribution</span></code> class in order to add your arguments; it is
sufficient to define the entry points in your extension, as long as any setup
script using your extension lists your project in its <code class="docutils literal"><span class="pre">setup_requires</span></code>
argument.</p>
</div>
<div class="section" id="adding-new-egg-info-files">
<h4><a class="toc-backref" href="#id61">Adding new EGG-INFO Files</a><a class="headerlink" href="#adding-new-egg-info-files" title="Permalink to this headline"></a></h4>
<p>Some extensible applications or frameworks may want to allow third parties to
develop plugins with application or framework-specific metadata included in
the plugins&#8217; EGG-INFO directory, for easy access via the <code class="docutils literal"><span class="pre">pkg_resources</span></code>
metadata API.  The easiest way to allow this is to create a distutils extension
to be used from the plugin projects&#8217; setup scripts (via <code class="docutils literal"><span class="pre">setup_requires</span></code>)
that defines a new setup keyword, and then uses that data to write an EGG-INFO
file when the <code class="docutils literal"><span class="pre">egg_info</span></code> command is run.</p>
<p>The <code class="docutils literal"><span class="pre">egg_info</span></code> command looks for extension points in an <code class="docutils literal"><span class="pre">egg_info.writers</span></code>
group, and calls them to write the files.  Here&#8217;s a simple example of a
distutils extension defining a setup argument <code class="docutils literal"><span class="pre">foo_bar</span></code>, which is a list of
lines that will be written to <code class="docutils literal"><span class="pre">foo_bar.txt</span></code> in the EGG-INFO directory of any
project that uses the argument:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span>
    <span class="c1"># ...</span>
    <span class="n">entry_points</span><span class="o">=</span><span class="p">{</span>
        <span class="s2">&quot;distutils.setup_keywords&quot;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s2">&quot;foo_bar = setuptools.dist:assert_string_list&quot;</span><span class="p">,</span>
        <span class="p">],</span>
        <span class="s2">&quot;egg_info.writers&quot;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s2">&quot;foo_bar.txt = setuptools.command.egg_info:write_arg&quot;</span><span class="p">,</span>
        <span class="p">],</span>
    <span class="p">},</span>
<span class="p">)</span>
</pre></div>
</div>
<p>This simple example makes use of two utility functions defined by setuptools
for its own use: a routine to validate that a setup keyword is a sequence of
strings, and another one that looks up a setup argument and writes it to
a file.  Here&#8217;s what the writer utility looks like:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">write_arg</span><span class="p">(</span><span class="n">cmd</span><span class="p">,</span> <span class="n">basename</span><span class="p">,</span> <span class="n">filename</span><span class="p">):</span>
    <span class="n">argname</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">splitext</span><span class="p">(</span><span class="n">basename</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
    <span class="n">value</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">cmd</span><span class="o">.</span><span class="n">distribution</span><span class="p">,</span> <span class="n">argname</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
    <span class="k">if</span> <span class="n">value</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
        <span class="n">value</span> <span class="o">=</span> <span class="s1">&#39;</span><span class="se">\n</span><span class="s1">&#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">value</span><span class="p">)</span> <span class="o">+</span> <span class="s1">&#39;</span><span class="se">\n</span><span class="s1">&#39;</span>
    <span class="n">cmd</span><span class="o">.</span><span class="n">write_or_delete_file</span><span class="p">(</span><span class="n">argname</span><span class="p">,</span> <span class="n">filename</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>
</pre></div>
</div>
<p>As you can see, <code class="docutils literal"><span class="pre">egg_info.writers</span></code> entry points must be a function taking
three arguments: a <code class="docutils literal"><span class="pre">egg_info</span></code> command instance, the basename of the file to
write (e.g. <code class="docutils literal"><span class="pre">foo_bar.txt</span></code>), and the actual full filename that should be
written to.</p>
<p>In general, writer functions should honor the command object&#8217;s <code class="docutils literal"><span class="pre">dry_run</span></code>
setting when writing files, and use the <code class="docutils literal"><span class="pre">distutils.log</span></code> object to do any
console output.  The easiest way to conform to this requirement is to use
the <code class="docutils literal"><span class="pre">cmd</span></code> object&#8217;s <code class="docutils literal"><span class="pre">write_file()</span></code>, <code class="docutils literal"><span class="pre">delete_file()</span></code>, and
<code class="docutils literal"><span class="pre">write_or_delete_file()</span></code> methods exclusively for your file operations.  See
those methods&#8217; docstrings for more details.</p>
</div>
<div class="section" id="adding-support-for-revision-control-systems">
<h4><a class="toc-backref" href="#id62">Adding Support for Revision Control Systems</a><a class="headerlink" href="#adding-support-for-revision-control-systems" title="Permalink to this headline"></a></h4>
<p>If the files you want to include in the source distribution are tracked using
Git, Mercurial or SVN, you can use the following packages to achieve that:</p>
<ul class="simple">
<li>Git and Mercurial: <a class="reference external" href="https://pypi.python.org/pypi/setuptools_scm">setuptools_scm</a></li>
<li>SVN: <a class="reference external" href="https://pypi.python.org/pypi/setuptools_svn">setuptools_svn</a></li>
</ul>
<p>If you would like to create a plugin for <code class="docutils literal"><span class="pre">setuptools</span></code> to find files tracked
by another revision control system, you can do so by adding an entry point to
the <code class="docutils literal"><span class="pre">setuptools.file_finders</span></code> group.  The entry point should be a function
accepting a single directory name, and should yield all the filenames within
that directory (and any subdirectories thereof) that are under revision
control.</p>
<p>For example, if you were going to create a plugin for a revision control system
called &#8220;foobar&#8221;, you would write a function something like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">find_files_for_foobar</span><span class="p">(</span><span class="n">dirname</span><span class="p">):</span>
    <span class="c1"># loop to yield paths that start with `dirname`</span>
</pre></div>
</div>
<p>And you would register it in a setup script using something like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">entry_points</span><span class="o">=</span><span class="p">{</span>
    <span class="s2">&quot;setuptools.file_finders&quot;</span><span class="p">:</span> <span class="p">[</span>
        <span class="s2">&quot;foobar = my_foobar_module:find_files_for_foobar&quot;</span><span class="p">,</span>
    <span class="p">]</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Then, anyone who wants to use your plugin can simply install it, and their
local setuptools installation will be able to find the necessary files.</p>
<p>It is not necessary to distribute source control plugins with projects that
simply use the other source control system, or to specify the plugins in
<code class="docutils literal"><span class="pre">setup_requires</span></code>.  When you create a source distribution with the <code class="docutils literal"><span class="pre">sdist</span></code>
command, setuptools automatically records what files were found in the
<code class="docutils literal"><span class="pre">SOURCES.txt</span></code> file.  That way, recipients of source distributions don&#8217;t need
to have revision control at all.  However, if someone is working on a package
by checking out with that system, they will need the same plugin(s) that the
original author is using.</p>
<p>A few important points for writing revision control file finders:</p>
<ul class="simple">
<li>Your finder function MUST return relative paths, created by appending to the
passed-in directory name.  Absolute paths are NOT allowed, nor are relative
paths that reference a parent directory of the passed-in directory.</li>
<li>Your finder function MUST accept an empty string as the directory name,
meaning the current directory.  You MUST NOT convert this to a dot; just
yield relative paths.  So, yielding a subdirectory named <code class="docutils literal"><span class="pre">some/dir</span></code> under
the current directory should NOT be rendered as <code class="docutils literal"><span class="pre">./some/dir</span></code> or
<code class="docutils literal"><span class="pre">/somewhere/some/dir</span></code>, but <em>always</em> as simply <code class="docutils literal"><span class="pre">some/dir</span></code></li>
<li>Your finder function SHOULD NOT raise any errors, and SHOULD deal gracefully
with the absence of needed programs (i.e., ones belonging to the revision
control system itself.  It <em>may</em>, however, use <code class="docutils literal"><span class="pre">distutils.log.warn()</span></code> to
inform the user of the missing program(s).</li>
</ul>
</div>
<div class="section" id="subclassing-command">
<h4><a class="toc-backref" href="#id63">Subclassing <code class="docutils literal"><span class="pre">Command</span></code></a><a class="headerlink" href="#subclassing-command" title="Permalink to this headline"></a></h4>
<p>Sorry, this section isn&#8217;t written yet, and neither is a lot of what&#8217;s below
this point.</p>
<p>XXX</p>
</div>
</div>
<div class="section" id="reusing-setuptools-code">
<h3><a class="toc-backref" href="#id64">Reusing <code class="docutils literal"><span class="pre">setuptools</span></code> Code</a><a class="headerlink" href="#reusing-setuptools-code" title="Permalink to this headline"></a></h3>
<div class="section" id="ez-setup">
<h4><a class="toc-backref" href="#id65"><code class="docutils literal"><span class="pre">ez_setup</span></code></a><a class="headerlink" href="#ez-setup" title="Permalink to this headline"></a></h4>
<p>XXX</p>
</div>
<div class="section" id="setuptools-archive-util">
<h4><a class="toc-backref" href="#id66"><code class="docutils literal"><span class="pre">setuptools.archive_util</span></code></a><a class="headerlink" href="#setuptools-archive-util" title="Permalink to this headline"></a></h4>
<p>XXX</p>
</div>
<div class="section" id="setuptools-sandbox">
<h4><a class="toc-backref" href="#id67"><code class="docutils literal"><span class="pre">setuptools.sandbox</span></code></a><a class="headerlink" href="#setuptools-sandbox" title="Permalink to this headline"></a></h4>
<p>XXX</p>
</div>
<div class="section" id="setuptools-package-index">
<h4><a class="toc-backref" href="#id68"><code class="docutils literal"><span class="pre">setuptools.package_index</span></code></a><a class="headerlink" href="#setuptools-package-index" title="Permalink to this headline"></a></h4>
<p>XXX</p>
</div>
</div>
<div class="section" id="mailing-list-and-bug-tracker">
<h3><a class="toc-backref" href="#id69">Mailing List and Bug Tracker</a><a class="headerlink" href="#mailing-list-and-bug-tracker" title="Permalink to this headline"></a></h3>
<p>Please use the <a class="reference external" href="http://mail.python.org/pipermail/distutils-sig/">distutils-sig mailing list</a> for questions and discussion about
setuptools, and the <a class="reference external" href="https://github.com/pypa/setuptools/">setuptools bug tracker</a> ONLY for issues you have
confirmed via the list are actual bugs, and which you have reduced to a minimal
set of steps to reproduce.</p>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Building and Distributing Packages with Setuptools</a><ul>
<li><a class="reference internal" href="#developer-s-guide">Developer&#8217;s Guide</a><ul>
<li><a class="reference internal" href="#installing-setuptools">Installing <code class="docutils literal"><span class="pre">setuptools</span></code></a></li>
<li><a class="reference internal" href="#basic-use">Basic Use</a><ul>
<li><a class="reference internal" href="#specifying-your-project-s-version">Specifying Your Project&#8217;s Version</a></li>
</ul>
</li>
<li><a class="reference internal" href="#new-and-changed-setup-keywords">New and Changed <code class="docutils literal"><span class="pre">setup()</span></code> Keywords</a><ul>
<li><a class="reference internal" href="#using-find-packages">Using <code class="docutils literal"><span class="pre">find_packages()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#automatic-script-creation">Automatic Script Creation</a><ul>
<li><a class="reference internal" href="#eggsecutable-scripts">&#8220;Eggsecutable&#8221; Scripts</a></li>
</ul>
</li>
<li><a class="reference internal" href="#declaring-dependencies">Declaring Dependencies</a><ul>
<li><a class="reference internal" href="#dependencies-that-aren-t-in-pypi">Dependencies that aren&#8217;t in PyPI</a></li>
<li><a class="reference internal" href="#declaring-extras-optional-features-with-their-own-dependencies">Declaring &#8220;Extras&#8221; (optional features with their own dependencies)</a></li>
<li><a class="reference internal" href="#declaring-platform-specific-dependencies">Declaring platform specific dependencies</a></li>
</ul>
</li>
<li><a class="reference internal" href="#including-data-files">Including Data Files</a><ul>
<li><a class="reference internal" href="#accessing-data-files-at-runtime">Accessing Data Files at Runtime</a></li>
<li><a class="reference internal" href="#non-package-data-files">Non-Package Data Files</a></li>
<li><a class="reference internal" href="#automatic-resource-extraction">Automatic Resource Extraction</a></li>
</ul>
</li>
<li><a class="reference internal" href="#extensible-applications-and-frameworks">Extensible Applications and Frameworks</a><ul>
<li><a class="reference internal" href="#dynamic-discovery-of-services-and-plugins">Dynamic Discovery of Services and Plugins</a></li>
<li><a class="reference internal" href="#defining-additional-metadata">Defining Additional Metadata</a></li>
</ul>
</li>
<li><a class="reference internal" href="#development-mode">&#8220;Development Mode&#8221;</a></li>
<li><a class="reference internal" href="#distributing-a-setuptools-based-project">Distributing a <code class="docutils literal"><span class="pre">setuptools</span></code>-based project</a><ul>
<li><a class="reference internal" href="#using-setuptools-without-bundling-it">Using <code class="docutils literal"><span class="pre">setuptools</span></code>...  Without bundling it!</a></li>
<li><a class="reference internal" href="#what-your-users-should-know">What Your Users Should Know</a></li>
<li><a class="reference internal" href="#setting-the-zip-safe-flag">Setting the <code class="docutils literal"><span class="pre">zip_safe</span></code> flag</a></li>
<li><a class="reference internal" href="#namespace-packages">Namespace Packages</a><ul>
<li><a class="reference internal" href="#transitional-note">TRANSITIONAL NOTE</a></li>
</ul>
</li>
<li><a class="reference internal" href="#tagging-and-daily-build-or-snapshot-releases">Tagging and &#8220;Daily Build&#8221; or &#8220;Snapshot&#8221; Releases</a></li>
<li><a class="reference internal" href="#generating-source-distributions">Generating Source Distributions</a></li>
<li><a class="reference internal" href="#making-your-package-available-for-easyinstall">Making your package available for EasyInstall</a><ul>
<li><a class="reference internal" href="#making-official-non-snapshot-releases">Making &#8220;Official&#8221; (Non-Snapshot) Releases</a></li>
</ul>
</li>
<li><a class="reference internal" href="#distributing-extensions-compiled-with-pyrex">Distributing Extensions compiled with Pyrex</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#command-reference">Command Reference</a><ul>
<li><a class="reference internal" href="#alias-define-shortcuts-for-commonly-used-commands"><code class="docutils literal"><span class="pre">alias</span></code> - Define shortcuts for commonly used commands</a></li>
<li><a class="reference internal" href="#bdist-egg-create-a-python-egg-for-the-project"><code class="docutils literal"><span class="pre">bdist_egg</span></code> - Create a Python Egg for the project</a></li>
<li><a class="reference internal" href="#develop-deploy-the-project-source-in-development-mode"><code class="docutils literal"><span class="pre">develop</span></code> - Deploy the project source in &#8220;Development Mode&#8221;</a></li>
<li><a class="reference internal" href="#easy-install-find-and-install-packages"><code class="docutils literal"><span class="pre">easy_install</span></code> - Find and install packages</a></li>
<li><a class="reference internal" href="#egg-info-create-egg-metadata-and-set-build-tags"><code class="docutils literal"><span class="pre">egg_info</span></code> - Create egg metadata and set build tags</a><ul>
<li><a class="reference internal" href="#release-tagging-options">Release Tagging Options</a></li>
<li><a class="reference internal" href="#other-egg-info-options">Other <code class="docutils literal"><span class="pre">egg_info</span></code> Options</a></li>
<li><a class="reference internal" href="#egg-info-examples"><code class="docutils literal"><span class="pre">egg_info</span></code> Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#install-run-easy-install-or-old-style-installation"><code class="docutils literal"><span class="pre">install</span></code> - Run <code class="docutils literal"><span class="pre">easy_install</span></code> or old-style installation</a></li>
<li><a class="reference internal" href="#install-egg-info-install-an-egg-info-directory-in-site-packages"><code class="docutils literal"><span class="pre">install_egg_info</span></code> - Install an <code class="docutils literal"><span class="pre">.egg-info</span></code> directory in <code class="docutils literal"><span class="pre">site-packages</span></code></a></li>
<li><a class="reference internal" href="#rotate-delete-outdated-distribution-files"><code class="docutils literal"><span class="pre">rotate</span></code> - Delete outdated distribution files</a></li>
<li><a class="reference internal" href="#saveopts-save-used-options-to-a-configuration-file"><code class="docutils literal"><span class="pre">saveopts</span></code> - Save used options to a configuration file</a><ul>
<li><a class="reference internal" href="#configuration-file-options">Configuration File Options</a></li>
</ul>
</li>
<li><a class="reference internal" href="#setopt-set-a-distutils-or-setuptools-option-in-a-config-file"><code class="docutils literal"><span class="pre">setopt</span></code> - Set a distutils or setuptools option in a config file</a></li>
<li><a class="reference internal" href="#test-build-package-and-run-a-unittest-suite"><code class="docutils literal"><span class="pre">test</span></code> - Build package and run a unittest suite</a></li>
<li><a class="reference internal" href="#upload-upload-source-and-or-egg-distributions-to-pypi"><code class="docutils literal"><span class="pre">upload</span></code> - Upload source and/or egg distributions to PyPI</a></li>
</ul>
</li>
<li><a class="reference internal" href="#configuring-setup-using-setup-cfg-files">Configuring setup() using setup.cfg files</a><ul>
<li><a class="reference internal" href="#specifying-values">Specifying values</a><ul>
<li><a class="reference internal" href="#metadata">Metadata</a></li>
<li><a class="reference internal" href="#options">Options</a></li>
</ul>
</li>
<li><a class="reference internal" href="#configuration-api">Configuration API</a></li>
</ul>
</li>
<li><a class="reference internal" href="#extending-and-reusing-setuptools">Extending and Reusing Setuptools</a><ul>
<li><a class="reference internal" href="#creating-distutils-extensions">Creating <code class="docutils literal"><span class="pre">distutils</span></code> Extensions</a><ul>
<li><a class="reference internal" href="#adding-commands">Adding Commands</a></li>
<li><a class="reference internal" href="#adding-setup-arguments">Adding <code class="docutils literal"><span class="pre">setup()</span></code> Arguments</a></li>
<li><a class="reference internal" href="#adding-new-egg-info-files">Adding new EGG-INFO Files</a></li>
<li><a class="reference internal" href="#adding-support-for-revision-control-systems">Adding Support for Revision Control Systems</a></li>
<li><a class="reference internal" href="#subclassing-command">Subclassing <code class="docutils literal"><span class="pre">Command</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#reusing-setuptools-code">Reusing <code class="docutils literal"><span class="pre">setuptools</span></code> Code</a><ul>
<li><a class="reference internal" href="#ez-setup"><code class="docutils literal"><span class="pre">ez_setup</span></code></a></li>
<li><a class="reference internal" href="#setuptools-archive-util"><code class="docutils literal"><span class="pre">setuptools.archive_util</span></code></a></li>
<li><a class="reference internal" href="#setuptools-sandbox"><code class="docutils literal"><span class="pre">setuptools.sandbox</span></code></a></li>
<li><a class="reference internal" href="#setuptools-package-index"><code class="docutils literal"><span class="pre">setuptools.package_index</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#mailing-list-and-bug-tracker">Mailing List and Bug Tracker</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="index.html"
                        title="previous chapter">Welcome to Setuptools&#8217; documentation!</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="easy_install.html"
                        title="next chapter">Easy Install</a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="_sources/setuptools.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <div><input type="text" name="q" /></div>
      <div><input type="submit" value="Go" /></div>
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="easy_install.html" title="Easy Install"
             >next</a></li>
        <li class="right" >
          <a href="index.html" title="Welcome to Setuptools’ documentation!"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">Setuptools</a> &#187;</li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; Copyright 2009-2017, The fellowship of the packaging.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.9.
    </div>
  </body>
</html>