/usr/share/doc/html/setuptools.html is in python-setuptools-doc 3.3-1ubuntu1.
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 | <!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 — 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: '3.3',
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="top" title="Setuptools documentation" href="index.html" />
<link rel="next" title="Easy Install" href="easy_install.html" />
<link rel="prev" title="Using Setuptools in your project" href="using.html" />
</head>
<body>
<div class="related">
<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="using.html" title="Using Setuptools in your project"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Setuptools</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<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><tt class="docutils literal"><span class="pre">Setuptools</span></tt> is a collection of enhancements to the Python <tt class="docutils literal"><span class="pre">distutils</span></tt>
(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 <tt class="docutils literal"><span class="pre">setuptools</span></tt> look to the user like
ordinary Python packages based on the <tt class="docutils literal"><span class="pre">distutils</span></tt>. Your users don’t need to
install or even know about setuptools in order to use them, and you don’t
have to include the entire setuptools package in your distributions. By
including just a single <a class="reference external" href="https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py">bootstrap module</a> (a 12K .py file), your package will
automatically download and install <tt class="docutils literal"><span class="pre">setuptools</span></tt> if the user is building your
package from source and doesn’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’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 <tt class="docutils literal"><span class="pre">MANIFEST.in</span></tt> file, and without having to force
regeneration of the <tt class="docutils literal"><span class="pre">MANIFEST</span></tt> file when your source tree changes.</li>
<li>Automatically generate wrapper scripts or Windows (console and GUI) .exe
files for any number of “main” 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 <tt class="docutils literal"><span class="pre">.pyx</span></tt> files and
still work even when the end-user doesn’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 “development mode”, such that it’s available on
<tt class="docutils literal"><span class="pre">sys.path</span></tt>, yet can still be edited directly from its source checkout.</li>
<li>Easily extend the distutils with new commands or <tt class="docutils literal"><span class="pre">setup()</span></tt> 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 “entry points” declared in a project’s setup script.</li>
</ul>
<p>In addition to the PyPI downloads, the development version of <tt class="docutils literal"><span class="pre">setuptools</span></tt>
is available from the <a class="reference external" href="http://svn.python.org/projects/sandbox/trunk/setuptools/#egg=setuptools-dev">Python SVN sandbox</a>, and in-development versions of the
<a class="reference external" href="http://svn.python.org/projects/sandbox/branches/setuptools-0.6/#egg=setuptools-dev06">0.6 branch</a> are available as well.</p>
<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’s Guide</a><ul>
<li><a class="reference internal" href="#installing-setuptools" id="id5">Installing <tt class="docutils literal"><span class="pre">setuptools</span></tt></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’s Version</a></li>
</ul>
</li>
<li><a class="reference internal" href="#new-and-changed-setup-keywords" id="id8">New and Changed <tt class="docutils literal"><span class="pre">setup()</span></tt> Keywords</a><ul>
<li><a class="reference internal" href="#using-find-packages" id="id9">Using <tt class="docutils literal"><span class="pre">find_packages()</span></tt></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">“Eggsecutable” 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’t in PyPI</a></li>
<li><a class="reference internal" href="#declaring-extras-optional-features-with-their-own-dependencies" id="id14">Declaring “Extras” (optional features with their own dependencies)</a></li>
</ul>
</li>
<li><a class="reference internal" href="#including-data-files" id="id15">Including Data Files</a><ul>
<li><a class="reference internal" href="#accessing-data-files-at-runtime" id="id16">Accessing Data Files at Runtime</a></li>
<li><a class="reference internal" href="#non-package-data-files" id="id17">Non-Package Data Files</a></li>
<li><a class="reference internal" href="#automatic-resource-extraction" id="id18">Automatic Resource Extraction</a></li>
</ul>
</li>
<li><a class="reference internal" href="#extensible-applications-and-frameworks" id="id19">Extensible Applications and Frameworks</a><ul>
<li><a class="reference internal" href="#dynamic-discovery-of-services-and-plugins" id="id20">Dynamic Discovery of Services and Plugins</a></li>
<li><a class="reference internal" href="#defining-additional-metadata" id="id21">Defining Additional Metadata</a></li>
</ul>
</li>
<li><a class="reference internal" href="#development-mode" id="id22">“Development Mode”</a></li>
<li><a class="reference internal" href="#distributing-a-setuptools-based-project" id="id23">Distributing a <tt class="docutils literal"><span class="pre">setuptools</span></tt>-based project</a><ul>
<li><a class="reference internal" href="#using-setuptools-without-bundling-it" id="id24">Using <tt class="docutils literal"><span class="pre">setuptools</span></tt>... Without bundling it!</a></li>
<li><a class="reference internal" href="#what-your-users-should-know" id="id25">What Your Users Should Know</a></li>
<li><a class="reference internal" href="#setting-the-zip-safe-flag" id="id26">Setting the <tt class="docutils literal"><span class="pre">zip_safe</span></tt> flag</a></li>
<li><a class="reference internal" href="#namespace-packages" id="id27">Namespace Packages</a><ul>
<li><a class="reference internal" href="#transitional-note" id="id28">TRANSITIONAL NOTE</a></li>
</ul>
</li>
<li><a class="reference internal" href="#tagging-and-daily-build-or-snapshot-releases" id="id29">Tagging and “Daily Build” or “Snapshot” Releases</a></li>
<li><a class="reference internal" href="#generating-source-distributions" id="id30">Generating Source Distributions</a></li>
<li><a class="reference internal" href="#making-your-package-available-for-easyinstall" id="id31">Making your package available for EasyInstall</a></li>
<li><a class="reference internal" href="#managing-continuous-releases-using-subversion" id="id32">Managing “Continuous Releases” Using Subversion</a><ul>
<li><a class="reference internal" href="#making-official-non-snapshot-releases" id="id33">Making “Official” (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"><tt class="docutils literal"><span class="pre">alias</span></tt> - 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"><tt class="docutils literal"><span class="pre">bdist_egg</span></tt> - 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"><tt class="docutils literal"><span class="pre">develop</span></tt> - Deploy the project source in “Development Mode”</a></li>
<li><a class="reference internal" href="#easy-install-find-and-install-packages" id="id39"><tt class="docutils literal"><span class="pre">easy_install</span></tt> - Find and install packages</a></li>
<li><a class="reference internal" href="#egg-info-create-egg-metadata-and-set-build-tags" id="id40"><tt class="docutils literal"><span class="pre">egg_info</span></tt> - 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 <tt class="docutils literal"><span class="pre">egg_info</span></tt> Options</a></li>
<li><a class="reference internal" href="#egg-info-examples" id="id43"><tt class="docutils literal"><span class="pre">egg_info</span></tt> Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#install-run-easy-install-or-old-style-installation" id="id44"><tt class="docutils literal"><span class="pre">install</span></tt> - Run <tt class="docutils literal"><span class="pre">easy_install</span></tt> 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"><tt class="docutils literal"><span class="pre">install_egg_info</span></tt> - Install an <tt class="docutils literal"><span class="pre">.egg-info</span></tt> directory in <tt class="docutils literal"><span class="pre">site-packages</span></tt></a></li>
<li><a class="reference internal" href="#rotate-delete-outdated-distribution-files" id="id46"><tt class="docutils literal"><span class="pre">rotate</span></tt> - Delete outdated distribution files</a></li>
<li><a class="reference internal" href="#saveopts-save-used-options-to-a-configuration-file" id="id47"><tt class="docutils literal"><span class="pre">saveopts</span></tt> - 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"><tt class="docutils literal"><span class="pre">setopt</span></tt> - 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"><tt class="docutils literal"><span class="pre">test</span></tt> - 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"><tt class="docutils literal"><span class="pre">upload</span></tt> - Upload source and/or egg distributions to PyPI</a></li>
<li><a class="reference internal" href="#upload-docs-upload-package-documentation-to-pypi" id="id52"><tt class="docutils literal"><span class="pre">upload_docs</span></tt> - Upload package documentation to PyPI</a></li>
</ul>
</li>
<li><a class="reference internal" href="#extending-and-reusing-distribute" id="id53">Extending and Reusing Distribute</a><ul>
<li><a class="reference internal" href="#creating-distutils-extensions" id="id54">Creating <tt class="docutils literal"><span class="pre">distutils</span></tt> Extensions</a><ul>
<li><a class="reference internal" href="#adding-commands" id="id55">Adding Commands</a></li>
<li><a class="reference internal" href="#adding-setup-arguments" id="id56">Adding <tt class="docutils literal"><span class="pre">setup()</span></tt> Arguments</a></li>
<li><a class="reference internal" href="#adding-new-egg-info-files" id="id57">Adding new EGG-INFO Files</a></li>
<li><a class="reference internal" href="#adding-support-for-other-revision-control-systems" id="id58">Adding Support for Other Revision Control Systems</a></li>
<li><a class="reference internal" href="#subclassing-command" id="id59">Subclassing <tt class="docutils literal"><span class="pre">Command</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#reusing-setuptools-code" id="id60">Reusing <tt class="docutils literal"><span class="pre">setuptools</span></tt> Code</a><ul>
<li><a class="reference internal" href="#ez-setup" id="id61"><tt class="docutils literal"><span class="pre">ez_setup</span></tt></a></li>
<li><a class="reference internal" href="#setuptools-archive-util" id="id62"><tt class="docutils literal"><span class="pre">setuptools.archive_util</span></tt></a></li>
<li><a class="reference internal" href="#setuptools-sandbox" id="id63"><tt class="docutils literal"><span class="pre">setuptools.sandbox</span></tt></a></li>
<li><a class="reference internal" href="#setuptools-package-index" id="id64"><tt class="docutils literal"><span class="pre">setuptools.package_index</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#mailing-list-and-bug-tracker" id="id65">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’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 <tt class="docutils literal"><span class="pre">setuptools</span></tt></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’s <tt class="docutils literal"><span class="pre">site-packages</span></tt> 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-python"><div class="highlight"><pre>ez_setup.py setuptools==dev
</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’s a minimal setup script using setuptools:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">setuptools</span> <span class="kn">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="s">"HelloWorld"</span><span class="p">,</span>
<span class="n">version</span> <span class="o">=</span> <span class="s">"0.1"</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’t take much to use setuptools in a project.
Just by doing the above, this project will be able 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.</p>
<p>Of course, before you release your project to PyPI, you’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-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">setuptools</span> <span class="kn">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="s">"HelloWorld"</span><span class="p">,</span>
<span class="n">version</span> <span class="o">=</span> <span class="s">"0.1"</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="s">'say_hello.py'</span><span class="p">],</span>
<span class="c"># Project uses reStructuredText, so ensure that the docutils get</span>
<span class="c"># installed or upgraded on the target machine</span>
<span class="n">install_requires</span> <span class="o">=</span> <span class="p">[</span><span class="s">'docutils>=0.3'</span><span class="p">],</span>
<span class="n">package_data</span> <span class="o">=</span> <span class="p">{</span>
<span class="c"># If any package contains *.txt or *.rst files, include them:</span>
<span class="s">''</span><span class="p">:</span> <span class="p">[</span><span class="s">'*.txt'</span><span class="p">,</span> <span class="s">'*.rst'</span><span class="p">],</span>
<span class="c"># And include any *.msg files found in the 'hello' package, too:</span>
<span class="s">'hello'</span><span class="p">:</span> <span class="p">[</span><span class="s">'*.msg'</span><span class="p">],</span>
<span class="p">},</span>
<span class="c"># metadata for upload to PyPI</span>
<span class="n">author</span> <span class="o">=</span> <span class="s">"Me"</span><span class="p">,</span>
<span class="n">author_email</span> <span class="o">=</span> <span class="s">"me@example.com"</span><span class="p">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s">"This is an Example Package"</span><span class="p">,</span>
<span class="n">license</span> <span class="o">=</span> <span class="s">"PSF"</span><span class="p">,</span>
<span class="n">keywords</span> <span class="o">=</span> <span class="s">"hello world example examples"</span><span class="p">,</span>
<span class="n">url</span> <span class="o">=</span> <span class="s">"http://example.com/HelloWorld/"</span><span class="p">,</span> <span class="c"># project home page, if any</span>
<span class="c"># could also include long_description, download_url, classifiers, etc.</span>
<span class="p">)</span>
</pre></div>
</div>
<p>In the sections that follow, we’ll explain what most of these <tt class="docutils literal"><span class="pre">setup()</span></tt>
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’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 <tt class="docutils literal"><span class="pre">2.4</span></tt> or <tt class="docutils literal"><span class="pre">0.5</span></tt>. Each series of digits is treated
numerically, so releases <tt class="docutils literal"><span class="pre">2.1</span></tt> and <tt class="docutils literal"><span class="pre">2.1.0</span></tt> are different ways to spell the
same release number, denoting the first subrelease of release 2. But <tt class="docutils literal"><span class="pre">2.10</span></tt>
is the <em>tenth</em> subrelease of release 2, and so is a different and newer release
from <tt class="docutils literal"><span class="pre">2.1</span></tt> or <tt class="docutils literal"><span class="pre">2.1.0</span></tt>. Leading zeros within a series of digits are also
ignored, so <tt class="docutils literal"><span class="pre">2.01</span></tt> is the same as <tt class="docutils literal"><span class="pre">2.1</span></tt>, and different from <tt class="docutils literal"><span class="pre">2.0.1</span></tt>.</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 <tt class="docutils literal"><span class="pre">2.4</span></tt> is <em>newer</em> than revision <tt class="docutils literal"><span class="pre">2.4c1</span></tt>,
which in turn is newer than <tt class="docutils literal"><span class="pre">2.4b1</span></tt> or <tt class="docutils literal"><span class="pre">2.4a1</span></tt>. Postrelease tags make
a version be considered <em>newer</em> than the version they are appended to. So,
revisions like <tt class="docutils literal"><span class="pre">2.4-1</span></tt> and <tt class="docutils literal"><span class="pre">2.4pl3</span></tt> are newer than <tt class="docutils literal"><span class="pre">2.4</span></tt>, but are <em>older</em>
than <tt class="docutils literal"><span class="pre">2.4.1</span></tt> (which has a higher release number).</p>
<p>A pre-release tag is a series of letters that are alphabetically before
“final”. Some examples of prerelease tags would include <tt class="docutils literal"><span class="pre">alpha</span></tt>, <tt class="docutils literal"><span class="pre">beta</span></tt>,
<tt class="docutils literal"><span class="pre">a</span></tt>, <tt class="docutils literal"><span class="pre">c</span></tt>, <tt class="docutils literal"><span class="pre">dev</span></tt>, and so on. You do not have to place a dot or dash
before the prerelease tag if it’s immediately after a number, but it’s okay to
do so if you prefer. Thus, <tt class="docutils literal"><span class="pre">2.4c1</span></tt> and <tt class="docutils literal"><span class="pre">2.4.c1</span></tt> and <tt class="docutils literal"><span class="pre">2.4-c1</span></tt> all
represent release candidate 1 of version <tt class="docutils literal"><span class="pre">2.4</span></tt>, 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 <tt class="docutils literal"><span class="pre">c</span></tt>: <tt class="docutils literal"><span class="pre">pre</span></tt>, <tt class="docutils literal"><span class="pre">preview</span></tt>, and <tt class="docutils literal"><span class="pre">rc</span></tt>. So, version
<tt class="docutils literal"><span class="pre">2.4rc1</span></tt>, <tt class="docutils literal"><span class="pre">2.4pre1</span></tt> and <tt class="docutils literal"><span class="pre">2.4preview1</span></tt> are all the exact same version as
<tt class="docutils literal"><span class="pre">2.4c1</span></tt>, 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 “final”, or a dash (<tt class="docutils literal"><span class="pre">-</span></tt>). 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
<tt class="docutils literal"><span class="pre">2.4-r1263</span></tt> might denote Subversion revision 1263 of a post-release patch of
version <tt class="docutils literal"><span class="pre">2.4</span></tt>. Or you might use <tt class="docutils literal"><span class="pre">2.4-20051127</span></tt> 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,
<tt class="docutils literal"><span class="pre">0.6a9.dev-r41475</span></tt> could denote Subversion revision 41475 of the in-
development version of the ninth alpha of release 0.6. Notice that <tt class="docutils literal"><span class="pre">dev</span></tt> is
a pre-release tag, so this version is a <em>lower</em> version number than <tt class="docutils literal"><span class="pre">0.6a9</span></tt>,
which would be the actual ninth alpha of release 0.6. But the <tt class="docutils literal"><span class="pre">-r41475</span></tt> is
a post-release tag, so this version is <em>newer</em> than <tt class="docutils literal"><span class="pre">0.6a9.dev</span></tt>.</p>
<p>For the most part, setuptools’ 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’t stick adjoining pre-release tags together without a dot or number
between them. Version <tt class="docutils literal"><span class="pre">1.9adev</span></tt> is the <tt class="docutils literal"><span class="pre">adev</span></tt> prerelease of <tt class="docutils literal"><span class="pre">1.9</span></tt>,
<em>not</em> a development pre-release of <tt class="docutils literal"><span class="pre">1.9a</span></tt>. Use <tt class="docutils literal"><span class="pre">.dev</span></tt> instead, as in
<tt class="docutils literal"><span class="pre">1.9a.dev</span></tt>, or separate the prerelease tags with a number, as in
<tt class="docutils literal"><span class="pre">1.9a0dev</span></tt>. <tt class="docutils literal"><span class="pre">1.9a.dev</span></tt>, <tt class="docutils literal"><span class="pre">1.9a0dev</span></tt>, and even <tt class="docutils literal"><span class="pre">1.9.a.dev</span></tt> are
identical versions from setuptools’ 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 <tt class="docutils literal"><span class="pre">pkg_resources.parse_version()</span></tt> function
to compare different version numbers:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">pkg_resources</span> <span class="kn">import</span> <span class="n">parse_version</span>
<span class="gp">>>> </span><span class="n">parse_version</span><span class="p">(</span><span class="s">'1.9.a.dev'</span><span class="p">)</span> <span class="o">==</span> <span class="n">parse_version</span><span class="p">(</span><span class="s">'1.9a0dev'</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">parse_version</span><span class="p">(</span><span class="s">'2.1-rc2'</span><span class="p">)</span> <span class="o"><</span> <span class="n">parse_version</span><span class="p">(</span><span class="s">'2.1'</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">parse_version</span><span class="p">(</span><span class="s">'0.6a9dev-r41475'</span><span class="p">)</span> <span class="o"><</span> <span class="n">parse_version</span><span class="p">(</span><span class="s">'0.6a9'</span><span class="p">)</span>
<span class="go">True</span>
</pre></div>
</div>
</li>
</ul>
<p>Once you’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 “Daily Build” or “Snapshot” Releases</a></li>
<li><a class="reference internal" href="#managing-continuous-releases-using-subversion">Managing “Continuous Releases” Using Subversion</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 <tt class="docutils literal"><span class="pre">setup()</span></tt> Keywords</a><a class="headerlink" href="#new-and-changed-setup-keywords" title="Permalink to this headline">¶</a></h3>
<p>The following keyword arguments to <tt class="docutils literal"><span class="pre">setup()</span></tt> are added or changed by
<tt class="docutils literal"><span class="pre">setuptools</span></tt>. All of them are optional; you do not have to supply them
unless you need the associated <tt class="docutils literal"><span class="pre">setuptools</span></tt> feature.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">include_package_data</span></tt></dt>
<dd>If set to <tt class="docutils literal"><span class="pre">True</span></tt>, this tells <tt class="docutils literal"><span class="pre">setuptools</span></tt> to automatically include any
data files it finds inside your package directories, that are either under
CVS or Subversion control, or which are specified by your <tt class="docutils literal"><span class="pre">MANIFEST.in</span></tt>
file. For more information, see the section below on <a class="reference internal" href="#including-data-files">Including Data
Files</a>.</dd>
<dt><tt class="docutils literal"><span class="pre">exclude_package_data</span></tt></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 <tt class="docutils literal"><span class="pre">include_package_data</span></tt>. 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><tt class="docutils literal"><span class="pre">package_data</span></tt></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
<tt class="docutils literal"><span class="pre">include_package_data</span></tt>, 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’t want to include in your
source distribution.)</dd>
<dt><tt class="docutils literal"><span class="pre">zip_safe</span></tt></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 <tt class="docutils literal"><span class="pre">bdist_egg</span></tt> command will have to analyze all of your
project’s contents for possible problems each time it buids an egg.</dd>
<dt><tt class="docutils literal"><span class="pre">install_requires</span></tt></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><tt class="docutils literal"><span class="pre">entry_points</span></tt></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><tt class="docutils literal"><span class="pre">extras_require</span></tt></dt>
<dd>A dictionary mapping names of “extras” (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><tt class="docutils literal"><span class="pre">setup_requires</span></tt></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. <tt class="docutils literal"><span class="pre">setuptools</span></tt> will
attempt to obtain these (even going so far as to download them using
<tt class="docutils literal"><span class="pre">EasyInstall</span></tt>) 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 <tt class="docutils literal"><span class="pre">setup_requires</span></tt> will NOT be automatically
installed on the system where the setup script is being run. They are
simply downloaded to the setup directory if they’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 <tt class="docutils literal"><span class="pre">install_requires</span></tt>
<strong>and</strong> <tt class="docutils literal"><span class="pre">setup_requires</span></tt>.)</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">dependency_links</span></tt></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
<tt class="docutils literal"><span class="pre">setup_requires</span></tt> or <tt class="docutils literal"><span class="pre">tests_require</span></tt>. They will also be written into
the egg’s metadata for use by tools like EasyInstall to use when installing
an <tt class="docutils literal"><span class="pre">.egg</span></tt> file.</dd>
<dt><tt class="docutils literal"><span class="pre">namespace_packages</span></tt></dt>
<dd>A list of strings naming the project’s “namespace packages”. A namespace
package is a package that may be split across multiple project
distributions. For example, Zope 3’s <tt class="docutils literal"><span class="pre">zope</span></tt> package is a namespace
package, because subpackages like <tt class="docutils literal"><span class="pre">zope.interface</span></tt> and <tt class="docutils literal"><span class="pre">zope.publisher</span></tt>
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’s <tt class="docutils literal"><span class="pre">__init__.py</span></tt>
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><tt class="docutils literal"><span class="pre">test_suite</span></tt></dt>
<dd><p class="first">A string naming a <tt class="docutils literal"><span class="pre">unittest.TestCase</span></tt> 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
<tt class="docutils literal"><span class="pre">unittest.TestSuite</span></tt>. If the named suite is a module, and the module
has an <tt class="docutils literal"><span class="pre">additional_tests()</span></tt> 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 <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">test</span></tt>. See the section on the
<a class="reference internal" href="#test">test</a> command below for more details.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">tests_require</span></tt></dt>
<dd>If your project’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’s tests to run. When you run the <tt class="docutils literal"><span class="pre">test</span></tt>
command, <tt class="docutils literal"><span class="pre">setuptools</span></tt> will attempt to obtain these (even going
so far as to download them using <tt class="docutils literal"><span class="pre">EasyInstall</span></tt>). 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’s setup directory if they’re
not already installed locally.</dd>
</dl>
<dl class="docutils" id="test-loader">
<dt><tt class="docutils literal"><span class="pre">test_loader</span></tt></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 <tt class="docutils literal"><span class="pre">loadTestsFromNames()</span></tt> method as defined
in the Python <tt class="docutils literal"><span class="pre">unittest</span></tt> module’s <tt class="docutils literal"><span class="pre">TestLoader</span></tt> class. Setuptools will
pass only one test “name” in the <cite>names</cite> argument: the value supplied for
the <tt class="docutils literal"><span class="pre">test_suite</span></tt> 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 <tt class="docutils literal"><span class="pre">test_suite</span></tt> string.</p>
<p>The module name and class name must be separated by a <tt class="docutils literal"><span class="pre">:</span></tt>. The default
value of this argument is <tt class="docutils literal"><span class="pre">"setuptools.command.test:ScanningLoader"</span></tt>. If
you want to use the default <tt class="docutils literal"><span class="pre">unittest</span></tt> behavior, you can specify
<tt class="docutils literal"><span class="pre">"unittest:TestLoader"</span></tt> as your <tt class="docutils literal"><span class="pre">test_loader</span></tt> 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 <tt class="docutils literal"><span class="pre">tests_require</span></tt> option to ensure that the package
containing the loader class is available when the <tt class="docutils literal"><span class="pre">test</span></tt> command is run.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">eager_resources</span></tt></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 ‘/’-separated paths, relative to the source root, so to list a
resource <tt class="docutils literal"><span class="pre">foo.png</span></tt> in package <tt class="docutils literal"><span class="pre">bar.baz</span></tt>, you would include the string
<tt class="docutils literal"><span class="pre">bar/baz/foo.png</span></tt> in this argument.</p>
<p class="last">If you only need to obtain resources one at a time, or you don’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’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><tt class="docutils literal"><span class="pre">use_2to3</span></tt></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"><em>Supporting both Python 2 and Python 3 with Setuptools</em></a> for more details.</dd>
<dt><tt class="docutils literal"><span class="pre">convert_2to3_doctests</span></tt></dt>
<dd>List of doctest source files that need to be converted with 2to3.
See <a class="reference internal" href="python3.html"><em>Supporting both Python 2 and Python 3 with Setuptools</em></a> for more details.</dd>
<dt><tt class="docutils literal"><span class="pre">use_2to3_fixers</span></tt></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"><em>Supporting both Python 2 and Python 3 with Setuptools</em></a> for more details.</dd>
</dl>
<div class="section" id="using-find-packages">
<h4><a class="toc-backref" href="#id9">Using <tt class="docutils literal"><span class="pre">find_packages()</span></tt></a><a class="headerlink" href="#using-find-packages" title="Permalink to this headline">¶</a></h4>
<p>For simple projects, it’s usually easy enough to manually add packages to
the <tt class="docutils literal"><span class="pre">packages</span></tt> argument of <tt class="docutils literal"><span class="pre">setup()</span></tt>. However, for very large projects
(Twisted, PEAK, Zope, Chandler, etc.), it can be a big burden to keep the
package list updated. That’s what <tt class="docutils literal"><span class="pre">setuptools.find_packages()</span></tt> is for.</p>
<p><tt class="docutils literal"><span class="pre">find_packages()</span></tt> 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 <tt class="docutils literal"><span class="pre">src</span></tt> or <tt class="docutils literal"><span class="pre">lib</span></tt>
directory as the root of their source tree, and those projects would of course
use <tt class="docutils literal"><span class="pre">"src"</span></tt> or <tt class="docutils literal"><span class="pre">"lib"</span></tt> as the first argument to <tt class="docutils literal"><span class="pre">find_packages()</span></tt>. (And
such projects also need something like <tt class="docutils literal"><span class="pre">package_dir</span> <span class="pre">=</span> <span class="pre">{'':'src'}</span></tt> in their
<tt class="docutils literal"><span class="pre">setup()</span></tt> arguments, but that’s just a normal distutils thing.)</p>
<p>Anyway, <tt class="docutils literal"><span class="pre">find_packages()</span></tt> walks the target directory, filtering by inclusion
patterns, and finds Python
packages by looking for <tt class="docutils literal"><span class="pre">__init__.py</span></tt> files. It then filters the list of
packages using the exclusion patterns.</p>
<p>Inclusion and exclusion patterns are package names, optionally including
wildcards. For
example, <tt class="docutils literal"><span class="pre">find_packages(exclude=["*.tests"])</span></tt> will exclude all packages whose
last name part is <tt class="docutils literal"><span class="pre">tests</span></tt>. Or, <tt class="docutils literal"><span class="pre">find_packages(exclude=["*.tests",</span>
<span class="pre">"*.tests.*"])</span></tt> will also exclude any subpackages of packages named <tt class="docutils literal"><span class="pre">tests</span></tt>,
but it still won’t exclude a top-level <tt class="docutils literal"><span class="pre">tests</span></tt> package or the children
thereof. In fact, if you really want no <tt class="docutils literal"><span class="pre">tests</span></tt> packages at all, you’ll need
something like this:</p>
<div class="highlight-python"><div class="highlight"><pre><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="s">"*.tests"</span><span class="p">,</span> <span class="s">"*.tests.*"</span><span class="p">,</span> <span class="s">"tests.*"</span><span class="p">,</span> <span class="s">"tests"</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 <tt class="docutils literal"><span class="pre">find_packages()</span></tt>
function returns a list of package names suitable for use as the <tt class="docutils literal"><span class="pre">packages</span></tt>
argument to <tt class="docutils literal"><span class="pre">setup()</span></tt>, 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’s no easy way to have a script’s filename match local
conventions on both Windows and POSIX platforms. For another, you often have
to create a separate file just for the “main” script, when your actual “main”
is a function in a module somewhere. And even in Python 2.4, using the <tt class="docutils literal"><span class="pre">-m</span></tt>
option only works for actual <tt class="docutils literal"><span class="pre">.py</span></tt> files that aren’t installed in a package.</p>
<p><tt class="docutils literal"><span class="pre">setuptools</span></tt> fixes all of these problems by automatically generating scripts
for you with the correct extension, and on Windows it will even create an
<tt class="docutils literal"><span class="pre">.exe</span></tt> file so that users don’t have to change their <tt class="docutils literal"><span class="pre">PATHEXT</span></tt> settings.
The way to use this feature is to define “entry points” in your setup script
that indicate what function the generated script should import and run. For
example, to create two console scripts called <tt class="docutils literal"><span class="pre">foo</span></tt> and <tt class="docutils literal"><span class="pre">bar</span></tt>, and a GUI
script called <tt class="docutils literal"><span class="pre">baz</span></tt>, you might do something like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">setup</span><span class="p">(</span>
<span class="c"># other arguments here...</span>
<span class="n">entry_points</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'console_scripts'</span><span class="p">:</span> <span class="p">[</span>
<span class="s">'foo = my_package.some_module:main_func'</span><span class="p">,</span>
<span class="s">'bar = other_module:some_func'</span><span class="p">,</span>
<span class="p">],</span>
<span class="s">'gui_scripts'</span><span class="p">:</span> <span class="p">[</span>
<span class="s">'baz = my_package_gui.start_func'</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 “setup.py
install”, “setup.py develop”, or by using EasyInstall), a set of <tt class="docutils literal"><span class="pre">foo</span></tt>,
<tt class="docutils literal"><span class="pre">bar</span></tt>, and <tt class="docutils literal"><span class="pre">baz</span></tt> scripts will be installed that import <tt class="docutils literal"><span class="pre">main_func</span></tt> and
<tt class="docutils literal"><span class="pre">some_func</span></tt> from the specified modules. The functions you specify are called
with no arguments, and their return value is passed to <tt class="docutils literal"><span class="pre">sys.exit()</span></tt>, so you
can return an errorlevel or message to print to stderr.</p>
<p>On Windows, a set of <tt class="docutils literal"><span class="pre">foo.exe</span></tt>, <tt class="docutils literal"><span class="pre">bar.exe</span></tt>, and <tt class="docutils literal"><span class="pre">baz.exe</span></tt> launchers are
created, alongside a set of <tt class="docutils literal"><span class="pre">foo.py</span></tt>, <tt class="docutils literal"><span class="pre">bar.py</span></tt>, and <tt class="docutils literal"><span class="pre">baz.pyw</span></tt> files. The
<tt class="docutils literal"><span class="pre">.exe</span></tt> wrappers find and execute the right version of Python to run the
<tt class="docutils literal"><span class="pre">.py</span></tt> or <tt class="docutils literal"><span class="pre">.pyw</span></tt> file.</p>
<p>You may define as many “console script” and “gui script” entry points as you
like, and each one can optionally specify “extras” that it depends on, that
will be added to <tt class="docutils literal"><span class="pre">sys.path</span></tt> when the script is run. For more information on
“extras”, see the section below on <a class="reference internal" href="#declaring-extras">Declaring Extras</a>. For more information
on “entry points” 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">“Eggsecutable” Scripts</a><a class="headerlink" href="#eggsecutable-scripts" title="Permalink to this headline">¶</a></h4>
<p>Occasionally, there are situations where it’s desirable to make an <tt class="docutils literal"><span class="pre">.egg</span></tt>
file directly executable. You can do this by including an entry point such
as the following:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">setup</span><span class="p">(</span>
<span class="c"># other arguments here...</span>
<span class="n">entry_points</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'setuptools.installation'</span><span class="p">:</span> <span class="p">[</span>
<span class="s">'eggsecutable = my_package.some_module:main_func'</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 excecutable
prelude that imports and calls <tt class="docutils literal"><span class="pre">main_func()</span></tt> from <tt class="docutils literal"><span class="pre">my_package.some_module</span></tt>.
The prelude can be run on Unix-like platforms (including Mac and Linux) by
invoking the egg with <tt class="docutils literal"><span class="pre">/bin/sh</span></tt>, or by enabling execute permissions on the
<tt class="docutils literal"><span class="pre">.egg</span></tt> file. For the executable prelude to run, the appropriate version of
Python must be available via the <tt class="docutils literal"><span class="pre">PATH</span></tt> environment variable, under its
“long” name. That is, if the egg is built for Python 2.3, there must be a
<tt class="docutils literal"><span class="pre">python2.3</span></tt> executable present in a directory on <tt class="docutils literal"><span class="pre">PATH</span></tt>.</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 “eggsecutable” 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, <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> will know what project
and version is in use. The header script will check this and exit with an
error if the <tt class="docutils literal"><span class="pre">.egg</span></tt> 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><tt class="docutils literal"><span class="pre">setuptools</span></tt> 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><tt class="docutils literal"><span class="pre">setuptools</span></tt> and <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> use a common syntax for specifying a
project’s required dependencies. This syntax consists of a project’s PyPI
name, optionally followed by a comma-separated list of “extras” in square
brackets, optionally followed by a comma-separated list of version
specifiers. A version specifier is one of the operators <tt class="docutils literal"><span class="pre"><</span></tt>, <tt class="docutils literal"><span class="pre">></span></tt>, <tt class="docutils literal"><span class="pre"><=</span></tt>,
<tt class="docutils literal"><span class="pre">>=</span></tt>, <tt class="docutils literal"><span class="pre">==</span></tt> or <tt class="docutils literal"><span class="pre">!=</span></tt>, 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 <tt class="docutils literal"><span class="pre">-</span></tt>.</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. <tt class="docutils literal"><span class="pre">">1,</span> <span class="pre">>2"</span></tt> becomes
<tt class="docutils literal"><span class="pre">">1"</span></tt>, and <tt class="docutils literal"><span class="pre">"<2,<3"</span></tt> becomes <tt class="docutils literal"><span class="pre">"<3"</span></tt>). <tt class="docutils literal"><span class="pre">"!="</span></tt> versions are excised from
the ranges they fall within. A project’s version is then checked for
membership in the resulting ranges. (Note that providing conflicting conditions
for the same version (e.g. “<2,>=2” or “==2,!=2”) is meaningless and may
therefore produce bizarre results.)</p>
<p>Here are some example requirement specifiers:</p>
<div class="highlight-python"><div class="highlight"><pre>docutils >= 0.3
# comment lines and \ continuations are allowed in requirement strings
BazSpam ==1.1, ==1.2, ==1.3, ==1.4, ==1.5, \
==1.6, ==1.7 # and so are line-end comments
PEAK[FastCGI, reST]>=0.5a4
setuptools==0.5a7
</pre></div>
</div>
<p>The simplest way to include requirement specifiers is to use the
<tt class="docutils literal"><span class="pre">install_requires</span></tt> argument to <tt class="docutils literal"><span class="pre">setup()</span></tt>. 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, <tt class="docutils literal"><span class="pre">setup.py</span>
<span class="pre">install</span></tt>, or <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">develop</span></tt>, 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 <tt class="docutils literal"><span class="pre">sys.path</span></tt> (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 <tt class="docutils literal"><span class="pre">setup.py</span></tt>, you do
<em>not</em> need to use the <tt class="docutils literal"><span class="pre">require()</span></tt> function in your scripts or modules, as
long as you either install the project or use <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">develop</span></tt> to do
development work on it. (See <a class="reference internal" href="#development-mode">“Development Mode”</a> below for more details on
using <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">develop</span></tt>.)</p>
<div class="section" id="dependencies-that-aren-t-in-pypi">
<h4><a class="toc-backref" href="#id13">Dependencies that aren’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’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 <tt class="docutils literal"><span class="pre">sdist</span></tt> format,</li>
<li>a single <tt class="docutils literal"><span class="pre">.py</span></tt> file, or</li>
<li>a VCS repository (Subversion, Mercurial, or Git).</li>
</ul>
<p>You just need to add some URLs to the <tt class="docutils literal"><span class="pre">dependency_links</span></tt> argument to
<tt class="docutils literal"><span class="pre">setup()</span></tt>.</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’s URL</li>
</ol>
<p>In general, it’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 <tt class="docutils literal"><span class="pre">showfiles.php</span></tt> link in the case where a
package you depend on is distributed via SourceForge.</p>
<p>If you depend on a package that’s distributed as a single <tt class="docutils literal"><span class="pre">.py</span></tt> file, you
must include an <tt class="docutils literal"><span class="pre">"#egg=project-version"</span></tt> 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 <tt class="docutils literal"><span class="pre">setup.py</span></tt> to wrap the single <tt class="docutils literal"><span class="pre">.py</span></tt> file
as an egg.</p>
<p>In the case of a VCS checkout, you should also append <tt class="docutils literal"><span class="pre">#egg=project-version</span></tt>
in order to identify for what package that checkout should be used. You can
append <tt class="docutils literal"><span class="pre">@REV</span></tt> to the URL’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><tt class="docutils literal"><span class="pre">svn+URL</span></tt> for Subversion,</li>
<li><tt class="docutils literal"><span class="pre">git+URL</span></tt> for Git, and</li>
<li><tt class="docutils literal"><span class="pre">hg+URL</span></tt> for Mercurial</li>
</ul>
<p>A more complete example would be:</p>
<blockquote>
<div><tt class="docutils literal"><span class="pre">vcs+proto://host/path@revision#egg=project-version</span></tt></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
<tt class="docutils literal"><span class="pre">requires</span></tt> and in the URL’s fragment.</p>
<p>This will do a checkout (or a clone, in Git and Mercurial parlance) to a
temporary folder and run <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">bdist_egg</span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre">dependency_links</span></tt> 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’s dependencies aren’t already
installed:</p>
<div class="highlight-python"><div class="highlight"><pre>setup(
...
dependency_links = [
"http://peak.telecommunity.com/snapshots/"
],
)
</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 “Extras” (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 “recommended” 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 “extras”, 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 <tt class="docutils literal"><span class="pre">install_requires</span></tt>.</p>
<p>For example, let’s say that Project A offers optional PDF and reST support:</p>
<div class="highlight-python"><div class="highlight"><pre>setup(
name="Project-A",
...
extras_require = {
'PDF': ["ReportLab>=1.2", "RXP"],
'reST': ["docutils>=0.3"],
}
)
</pre></div>
</div>
<p>As you can see, the <tt class="docutils literal"><span class="pre">extras_require</span></tt> argument takes a dictionary mapping
names of “extra” features, to strings or lists of strings describing those
features’ requirements. These requirements will <em>not</em> be automatically
installed unless another package depends on them (directly or indirectly) by
including the desired “extras” 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’s <a class="reference internal" href="#entry-points">entry points</a> to specify dynamic
dependencies. For example, if Project A includes a “rst2pdf” script, it might
declare it like this, so that the “PDF” requirements are only resolved if the
“rst2pdf” script is run:</p>
<div class="highlight-python"><div class="highlight"><pre>setup(
name="Project-A",
...
entry_points = {
'console_scripts': [
'rst2pdf = project_a.tools.pdfgen [PDF]',
'rst2html = project_a.tools.htmlgen',
# more script entry points ...
],
}
)
</pre></div>
</div>
<p>Projects can also use another project’s extras when specifying dependencies.
For example, if project B needs “project A” with PDF support installed, it
might declare the dependency like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">setup</span><span class="p">(</span>
<span class="n">name</span><span class="o">=</span><span class="s">"Project-B"</span><span class="p">,</span>
<span class="n">install_requires</span> <span class="o">=</span> <span class="p">[</span><span class="s">"Project-A[PDF]"</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 – even if project A was already installed. In this way, a project
can encapsulate groups of optional “downstream dependencies” under a feature
name, so that packages that depend on it don’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’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 <tt class="docutils literal"><span class="pre">extras_require</span></tt> argument, so that packages depending on that feature
don’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-python"><div class="highlight"><pre>setup(
name="Project-A",
...
extras_require = {
'PDF': [],
'reST': ["docutils>=0.3"],
}
)
</pre></div>
</div>
<p>so that Package B doesn’t have to remove the <tt class="docutils literal"><span class="pre">[PDF]</span></tt> from its requirement
specifier.</p>
</div>
</div>
<div class="section" id="including-data-files">
<h3><a class="toc-backref" href="#id15">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 “data files”, 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 <tt class="docutils literal"><span class="pre">include_package_data</span></tt> keyword,
e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre>from setuptools import setup, find_packages
setup(
...
include_package_data = True
)
</pre></div>
</div>
<p>This tells setuptools to install any data files it finds in your packages.
The data files must be under CVS or Subversion control, or else they must be
specified via the distutils’ <tt class="docutils literal"><span class="pre">MANIFEST.in</span></tt> file. (They can also be tracked
by another revision control system, using an appropriate plugin. See the
section below on <a class="reference internal" href="#adding-support-for-other-revision-control-systems">Adding Support for Other Revision Control Systems</a> for
information on how to write such plugins.)</p>
<p>If the data files are not under version control, or are not in a supported
version control system, or 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 <tt class="docutils literal"><span class="pre">package_data</span></tt> keyword, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre>from setuptools import setup, find_packages
setup(
...
package_data = {
# If any package contains *.txt or *.rst files, include them:
'': ['*.txt', '*.rst'],
# And include any *.msg files found in the 'hello' package, too:
'hello': ['*.msg'],
}
)
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">package_data</span></tt> 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-python"><div class="highlight"><pre>setup.py
src/
mypkg/
__init__.py
mypkg.txt
data/
somefile.dat
otherdata.dat
</pre></div>
</div>
<p>The setuptools setup file might look like this:</p>
<div class="highlight-python"><div class="highlight"><pre>from setuptools import setup, find_packages
setup(
...
packages = find_packages('src'), # include all packages under src
package_dir = {'':'src'}, # tell distutils packages are under src
package_data = {
# If any package contains *.txt files, include them:
'': ['*.txt'],
# And include any *.dat files found in the 'data' subdirectory
# of the 'mypkg' package, also:
'mypkg': ['data/*.dat'],
}
)
</pre></div>
</div>
<p>Notice that if you list patterns in <tt class="docutils literal"><span class="pre">package_data</span></tt> 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 <tt class="docutils literal"><span class="pre">mypkg.txt</span></tt>
file gets included even though it’s not listed in the patterns for <tt class="docutils literal"><span class="pre">mypkg</span></tt>.</p>
<p>Also notice that if you use paths, you <em>must</em> use a forward slash (<tt class="docutils literal"><span class="pre">/</span></tt>) 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 <tt class="docutils literal"><span class="pre">package_data</span></tt> argument was previously only available in
<tt class="docutils literal"><span class="pre">setuptools</span></tt>, it was also added to the Python <tt class="docutils literal"><span class="pre">distutils</span></tt> 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 <tt class="docutils literal"><span class="pre">include_package_data</span></tt>
argument, files specified by <tt class="docutils literal"><span class="pre">package_data</span></tt> will <em>not</em> be automatically
added to the manifest unless they are tracked by a supported version control
system, or are listed in the MANIFEST.in file.)</p>
<p>Sometimes, the <tt class="docutils literal"><span class="pre">include_package_data</span></tt> or <tt class="docutils literal"><span class="pre">package_data</span></tt> options alone
aren’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 <tt class="docutils literal"><span class="pre">exclude_package_data</span></tt> option as well, that allows you
to do things like this:</p>
<div class="highlight-python"><div class="highlight"><pre>from setuptools import setup, find_packages
setup(
...
packages = find_packages('src'), # include all packages under src
package_dir = {'':'src'}, # tell distutils packages are under src
include_package_data = True, # include everything in source control
# ...but exclude README.txt from all packages
exclude_package_data = { '': ['README.txt'] },
)
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">exclude_package_data</span></tt> option is a dictionary mapping package names to
lists of wildcard patterns, just like the <tt class="docutils literal"><span class="pre">package_data</span></tt> option. And, just
as with that option, a key of <tt class="docutils literal"><span class="pre">''</span></tt> 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 <tt class="docutils literal"><span class="pre">package_data</span></tt> or were
included as a result of using <tt class="docutils literal"><span class="pre">include_package_data</span></tt>.</p>
<p>In summary, the three options allow you to:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">include_package_data</span></tt></dt>
<dd>Accept all data files and directories matched by <tt class="docutils literal"><span class="pre">MANIFEST.in</span></tt> or found
in source control.</dd>
<dt><tt class="docutils literal"><span class="pre">package_data</span></tt></dt>
<dd>Specify additional patterns to match files and directories that may or may
not be matched by <tt class="docutils literal"><span class="pre">MANIFEST.in</span></tt> or found in source control.</dd>
<dt><tt class="docutils literal"><span class="pre">exclude_package_data</span></tt></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 “orphaned” in your
project’s build directories, requiring you to run <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">clean</span> <span class="pre">--all</span></tt> 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 <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">clean</span> <span class="pre">--all</span></tt>.</p>
<div class="section" id="accessing-data-files-at-runtime">
<h4><a class="toc-backref" href="#id16">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’s <tt class="docutils literal"><span class="pre">__file__</span></tt> attribute in
order to find the location of data files. However, this manipulation isn’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/PythonEggs#resource-management">Resource Management API</a> of <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> to access
them. The <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> module is distributed as part of setuptools, so if
you’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 <tt class="docutils literal"><span class="pre">__file__</span></tt> to use
<tt class="docutils literal"><span class="pre">pkg_resources</span></tt> instead.</p>
</div>
<div class="section" id="non-package-data-files">
<h4><a class="toc-backref" href="#id17">Non-Package Data Files</a><a class="headerlink" href="#non-package-data-files" title="Permalink to this headline">¶</a></h4>
<p>The <tt class="docutils literal"><span class="pre">distutils</span></tt> normally install general “data files” to a platform-specific
location (e.g. <tt class="docutils literal"><span class="pre">/usr/share</span></tt>). This feature intended to be used for things
like documentation, example configuration files, and the like. <tt class="docutils literal"><span class="pre">setuptools</span></tt>
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/PythonEggs#resource-management">Resource Management
API</a>, by specifying a <tt class="docutils literal"><span class="pre">Requirement</span></tt> instead of a package name:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">pkg_resources</span> <span class="kn">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="s">"MyProject"</span><span class="p">),</span><span class="s">"sample.conf"</span><span class="p">)</span>
</pre></div>
</div>
<p>The above code will obtain the filename of the “sample.conf” file in the data
root of the “MyProject” distribution.</p>
<p>Note, by the way, that this encapsulation of data files means that you can’t
actually install data files to some arbitrary location on a user’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 <tt class="docutils literal"><span class="pre">resource_filename()</span></tt> with the directory
name to get a filesystem directory that then can be copied with the <tt class="docutils literal"><span class="pre">shutil</span></tt>
module. (Even if your package is installed as a zipfile, calling
<tt class="docutils literal"><span class="pre">resource_filename()</span></tt> 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’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’ approach. However, if you’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="#id18">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 “real” 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 <tt class="docutils literal"><span class="pre">eager_resources</span></tt> argument to <tt class="docutils literal"><span class="pre">setup()</span></tt>, 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 <tt class="docutils literal"><span class="pre">.dll</span></tt>, <tt class="docutils literal"><span class="pre">.so</span></tt>, or <tt class="docutils literal"><span class="pre">.dylib</span></tt>, which are the
extensions that setuptools 0.6a8 and higher automatically detects as shared
libraries and adds to the <tt class="docutils literal"><span class="pre">native_libs.txt</span></tt> file for you. Any shared
libraries whose names do not end with one of those extensions should be listed
as <tt class="docutils literal"><span class="pre">eager_resources</span></tt>, because they need to be present in the filesystem when
he C extensions that link to them are used.</p>
<p>The <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> runtime for compressed packages will automatically
extract <em>all</em> C extensions and <tt class="docutils literal"><span class="pre">eager_resources</span></tt> at the same time, whenever
<em>any</em> C extension or eager resource is requested via the <tt class="docutils literal"><span class="pre">resource_filename()</span></tt>
API. (C extensions are imported using <tt class="docutils literal"><span class="pre">resource_filename()</span></tt> internally.)
This ensures that C extensions will see all of the “real” files that they
expect to see.</p>
<p>Note also that you can list directory resource names in <tt class="docutils literal"><span class="pre">eager_resources</span></tt> as
well, in which case the directory’s contents (including subdirectories) will be
extracted whenever any C extension or eager resource is requested.</p>
<p>Please note that if you’re not sure whether you need to use this argument, you
don’t! It’s really intended to support projects with lots of non-Python
dependencies and as a last resort for crufty projects that can’t otherwise
handle being compressed. If your package is pure Python, Python plus data
files, or Python plus C, you really don’t need this. You’ve got to be using
either C or an external program that needs “real” files in your project before
there’s any possibility of <tt class="docutils literal"><span class="pre">eager_resources</span></tt> being relevant to your project.</p>
</div>
</div>
<div class="section" id="extensible-applications-and-frameworks">
<h3><a class="toc-backref" href="#id19">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="#id20">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><tt class="docutils literal"><span class="pre">setuptools</span></tt> supports creating libraries that “plug in” to extensible
applications and frameworks, by letting you register “entry points” 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’s output format.
The framework might define an “entry point group” called <tt class="docutils literal"><span class="pre">blogtool.parsers</span></tt>,
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’t have to special-case its built-in formats. They can just be treated
the same as any other plugin’s entry points would be.</p>
<p>If you’re creating a project that plugs in to an existing application or
framework, you’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
<tt class="docutils literal"><span class="pre">.rst</span></tt> file parser entry point in the <tt class="docutils literal"><span class="pre">blogtool.parsers</span></tt> entry point group,
for our hypothetical blogging tool:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">setup</span><span class="p">(</span>
<span class="c"># ...</span>
<span class="n">entry_points</span> <span class="o">=</span> <span class="p">{</span><span class="s">'blogtool.parsers'</span><span class="p">:</span> <span class="s">'.rst = some_module:SomeClass'</span><span class="p">}</span>
<span class="p">)</span>
<span class="n">setup</span><span class="p">(</span>
<span class="c"># ...</span>
<span class="n">entry_points</span> <span class="o">=</span> <span class="p">{</span><span class="s">'blogtool.parsers'</span><span class="p">:</span> <span class="p">[</span><span class="s">'.rst = some_module:a_func'</span><span class="p">]}</span>
<span class="p">)</span>
<span class="n">setup</span><span class="p">(</span>
<span class="c"># ...</span>
<span class="n">entry_points</span> <span class="o">=</span> <span class="s">"""</span>
<span class="s"> [blogtool.parsers]</span>
<span class="s"> .rst = some.nested.module:SomeClass.some_classmethod [reST]</span>
<span class="s"> """</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="s">"Docutils>=0.3.5"</span><span class="p">)</span>
<span class="p">)</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">entry_points</span></tt> argument to <tt class="docutils literal"><span class="pre">setup()</span></tt> accepts either a string with
<tt class="docutils literal"><span class="pre">.ini</span></tt>-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 <tt class="docutils literal"><span class="pre">=</span></tt>
sign. The value consists of a dotted module name, optionally followed by a
<tt class="docutils literal"><span class="pre">:</span></tt> and a dotted identifier naming an object within the module. It can
also include a bracketed list of “extras” 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 <tt class="docutils literal"><span class="pre">pkg_resources.require()</span></tt>, 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’t installed.)</p>
</div>
<div class="section" id="defining-additional-metadata">
<h4><a class="toc-backref" href="#id21">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
<tt class="docutils literal"><span class="pre">pkg_resources</span></tt> metadata APIs. Ordinarily, this is done by having plugin
developers include additional files in their <tt class="docutils literal"><span class="pre">ProjectName.egg-info</span></tt>
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 <tt class="docutils literal"><span class="pre">setup()</span></tt>, in much the same way that <tt class="docutils literal"><span class="pre">setuptools</span></tt> does
for many of the <tt class="docutils literal"><span class="pre">setup()</span></tt> 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="#id22">“Development Mode”</a><a class="headerlink" href="#development-mode" title="Permalink to this headline">¶</a></h3>
<p>Under normal circumstances, the <tt class="docutils literal"><span class="pre">distutils</span></tt> assume that you are going to
build a distribution of your project, not use it in its “raw” or “unbuilt”
form. If you were to use the <tt class="docutils literal"><span class="pre">distutils</span></tt> 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 <tt class="docutils literal"><span class="pre">distutils</span></tt> is that you may
need to do development on two related projects at the same time. You may need
to put both projects’ 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’s
code in its checkout directory, and only need to run build commands when you
change a project’s C extensions or similarly compiled files. You can even
deploy a project into another project’s checkout directory, if that’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 <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">develop</span></tt> command. It works very similarly to
<tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">install</span></tt> or the EasyInstall tool, except that it doesn’t actually
install anything. Instead, it creates a special <tt class="docutils literal"><span class="pre">.egg-link</span></tt> file in the
deployment directory, that links to your project’s source code. And, if your
deployment directory is Python’s <tt class="docutils literal"><span class="pre">site-packages</span></tt> directory, it will also
update the <tt class="docutils literal"><span class="pre">easy-install.pth</span></tt> file to include your project’s source code,
thereby making it available on <tt class="docutils literal"><span class="pre">sys.path</span></tt> for all programs using that Python
installation.</p>
<p>If you have enabled the <tt class="docutils literal"><span class="pre">use_2to3</span></tt> flag, then of course the <tt class="docutils literal"><span class="pre">.egg-link</span></tt>
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 <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">develop</span></tt> will build Python 3 code under the <tt class="docutils literal"><span class="pre">build</span></tt>
directory, and link there. This means that after doing code changes you will
have to run <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">build</span></tt> before these changes are picked up by your
Python 3 installation.</p>
<p>In addition, the <tt class="docutils literal"><span class="pre">develop</span></tt> command creates wrapper scripts in the target
script directory that will run your in-development scripts after ensuring that
all your <tt class="docutils literal"><span class="pre">install_requires</span></tt> packages are available on <tt class="docutils literal"><span class="pre">sys.path</span></tt>.</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’re
doing development work.</p>
<p>When you’re done with a given development task, you can remove the project
source from a staging area using <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">develop</span> <span class="pre">--uninstall</span></tt>, specifying
the desired staging area if it’s not the default.</p>
<p>There are several options to control the precise behavior of the <tt class="docutils literal"><span class="pre">develop</span></tt>
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-python"><div class="highlight"><pre>python -c "import setuptools; execfile('setup.py')" develop
</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="#id23">Distributing a <tt class="docutils literal"><span class="pre">setuptools</span></tt>-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="#id24">Using <tt class="docutils literal"><span class="pre">setuptools</span></tt>... 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 <tt class="docutils literal"><span class="pre">setuptools</span></tt> 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://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py">ez_setup.py</a>, and put it in the same directory as your <tt class="docutils literal"><span class="pre">setup.py</span></tt>
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 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’s it. The <tt class="docutils literal"><span class="pre">ez_setup</span></tt> module will automatically download a matching
version of <tt class="docutils literal"><span class="pre">setuptools</span></tt> from PyPI, if it isn’t present on the target system.
Whenever you install an updated version of setuptools, you should also update
your projects’ <tt class="docutils literal"><span class="pre">ez_setup.py</span></tt> files, so that a matching version gets installed
on the target machine(s).</p>
<p>By the way, setuptools supports the new PyPI “upload” command, so you can use
<tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">sdist</span> <span class="pre">upload</span></tt> or <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">bdist_egg</span> <span class="pre">upload</span></tt> to upload your
source or egg distributions respectively. Your project’s current version must
be registered with PyPI first, of course; you can use <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">register</span></tt> to
do that. Or you can do it all in one step, e.g. <tt 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></tt> will register the package, build source and egg
distributions, and then upload them both to PyPI, where they’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 <tt class="docutils literal"><span class="pre">setuptools</span></tt>,
you can specify the exact version and base download URL as parameters to the
<tt class="docutils literal"><span class="pre">use_setuptools()</span></tt> function. See the function’s docstring for details.)</p>
</div>
<div class="section" id="what-your-users-should-know">
<h4><a class="toc-backref" href="#id25">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 – as long as your users have an internet connection and are installing
to <tt class="docutils literal"><span class="pre">site-packages</span></tt>, that is. But for some users, these conditions don’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’s installation instructions, if they are
relevant to your project and your target audience isn’t already familiar with
setuptools and <tt class="docutils literal"><span class="pre">easy_install</span></tt>.</p>
<dl class="docutils">
<dt>Network Access</dt>
<dd>If your project is using <tt class="docutils literal"><span class="pre">ez_setup</span></tt>, 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 <tt class="docutils literal"><span class="pre">site-packages</span></tt> 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’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’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 <tt class="docutils literal"><span class="pre">easy_install</span></tt>, 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 <tt class="docutils literal"><span class="pre">-f</span></tt> option of <tt class="docutils literal"><span class="pre">easy_install</span></tt> to specify the directory
to find eggs in. Users who have full network access can just use <tt class="docutils literal"><span class="pre">-f</span></tt>
with the URL of your download page, and <tt class="docutils literal"><span class="pre">easy_install</span></tt> will find all the
needed eggs using your links directly. This is also useful when your
target audience isn’t able to compile packages (e.g. most Windows users)
and your package or some of its dependencies include C code.</p>
</dd>
<dt>Subversion or CVS Users and Co-Developers</dt>
<dd><p class="first">Users and co-developers who are tracking your in-development code using
CVS, Subversion, or some other revision control system should probably read
this manual’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 <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">develop</span></tt> 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 <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">clean</span> <span class="pre">--all</span></tt> and delete any obsolete
<tt class="docutils literal"><span class="pre">.pyc</span></tt> or <tt class="docutils literal"><span class="pre">.pyo</span></tt>. (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’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’t <tt class="docutils literal"><span class="pre">easy_install</span></tt>!
Setuptools currently supports <tt class="docutils literal"><span class="pre">bdist_rpm</span></tt>, <tt class="docutils literal"><span class="pre">bdist_wininst</span></tt>, and
<tt class="docutils literal"><span class="pre">bdist_dumb</span></tt> formats for system packaging. If a user has a locally-
installed “bdist” packaging tool that internally uses the distutils
<tt class="docutils literal"><span class="pre">install</span></tt> command, it should be able to work with <tt class="docutils literal"><span class="pre">setuptools</span></tt>. Some
examples of “bdist” formats that this should work with include the
<tt class="docutils literal"><span class="pre">bdist_nsi</span></tt> and <tt class="docutils literal"><span class="pre">bdist_msi</span></tt> formats for Windows.</p>
<p>However, packaging tools that build binary distributions by running
<tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">install</span></tt> on the command line or as a subprocess will require
modification to work with setuptools. They should use the
<tt class="docutils literal"><span class="pre">--single-version-externally-managed</span></tt> option to the <tt class="docutils literal"><span class="pre">install</span></tt> command,
combined with the standard <tt class="docutils literal"><span class="pre">--root</span></tt> or <tt class="docutils literal"><span class="pre">--record</span></tt> options.
See the <a class="reference internal" href="#install-command">install command</a> documentation below for more details. The
<tt class="docutils literal"><span class="pre">bdist_deb</span></tt> 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 “bdist” 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="#id26">Setting the <tt class="docutils literal"><span class="pre">zip_safe</span></tt> flag</a><a class="headerlink" href="#setting-the-zip-safe-flag" title="Permalink to this headline">¶</a></h4>
<p>For maximum performance, Python packages are best installed as zip files.
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, <tt class="docutils literal"><span class="pre">setuptools</span></tt> can install your project
as a zipfile or a directory, and its default choice is determined by the
project’s <tt class="docutils literal"><span class="pre">zip_safe</span></tt> flag.</p>
<p>You can pass a True or False value for the <tt class="docutils literal"><span class="pre">zip_safe</span></tt> argument to the
<tt class="docutils literal"><span class="pre">setup()</span></tt> function, or you can omit it. If you omit it, the <tt class="docutils literal"><span class="pre">bdist_egg</span></tt>
command will analyze your project’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’t or won’t work as a zipfile! It just
means that the <tt class="docutils literal"><span class="pre">bdist_egg</span></tt> authors aren’t yet comfortable asserting that
the project <em>will</em> work. If the project contains no C or data files, and does
no <tt class="docutils literal"><span class="pre">__file__</span></tt> or <tt class="docutils literal"><span class="pre">__path__</span></tt> 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 <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> for all its data file
access, then C extensions and other data files shouldn’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 <tt class="docutils literal"><span class="pre">bdist_egg</span></tt> can’t be <em>sure</em> that your package will work, but
you’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
<tt class="docutils literal"><span class="pre">zip_safe</span></tt> to <tt class="docutils literal"><span class="pre">True</span></tt> in your <tt class="docutils literal"><span class="pre">setup()</span></tt> call. If it turns out that it
doesn’t work, you can always change it to <tt class="docutils literal"><span class="pre">False</span></tt>, which will force
<tt class="docutils literal"><span class="pre">setuptools</span></tt> 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 <tt 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></tt> or <tt 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></tt> 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 <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> runtime, the
“zip safety” 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 <tt class="docutils literal"><span class="pre">True</span></tt> or <tt class="docutils literal"><span class="pre">False</span></tt> for the <tt class="docutils literal"><span class="pre">zip_safe</span></tt>
flag, so that it will not be necessary for <tt class="docutils literal"><span class="pre">bdist_egg</span></tt> or <tt class="docutils literal"><span class="pre">EasyInstall</span></tt> 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="#id27">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. “Namespace packages”
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
<tt class="docutils literal"><span class="pre">__init__.py</span></tt>, and that it is merely a container for modules and subpackages.</p>
<p>The <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> runtime will then automatically ensure that the contents
of namespace packages that are spread over multiple eggs or directories are
combined into a single “virtual” package.</p>
<p>The <tt class="docutils literal"><span class="pre">namespace_packages</span></tt> argument to <tt class="docutils literal"><span class="pre">setup()</span></tt> lets you declare your
project’s namespace packages, so that they will be included in your project’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-python"><div class="highlight"><pre><span class="n">setup</span><span class="p">(</span>
<span class="c"># ...</span>
<span class="n">namespace_packages</span> <span class="o">=</span> <span class="p">[</span><span class="s">'zope'</span><span class="p">]</span>
<span class="p">)</span>
</pre></div>
</div>
<p>because it contains a <tt class="docutils literal"><span class="pre">zope.interface</span></tt> package that lives in the <tt class="docutils literal"><span class="pre">zope</span></tt>
namespace package. Similarly, a project for a standalone <tt class="docutils literal"><span class="pre">zope.publisher</span></tt>
would also declare the <tt class="docutils literal"><span class="pre">zope</span></tt> namespace package. When these projects are
installed and used, Python will see them both as part of a “virtual” <tt class="docutils literal"><span class="pre">zope</span></tt>
package, even though they will be installed in different locations.</p>
<p>Namespace packages don’t have to be top-level packages. For example, Zope 3’s
<tt class="docutils literal"><span class="pre">zope.app</span></tt> package is a namespace package, and in the future PEAK’s
<tt class="docutils literal"><span class="pre">peak.util</span></tt> package will be too.</p>
<p>Note, by the way, that your project’s source tree must include the namespace
packages’ <tt class="docutils literal"><span class="pre">__init__.py</span></tt> files (and the <tt class="docutils literal"><span class="pre">__init__.py</span></tt> of any parent
packages), in a normal Python package layout. These <tt class="docutils literal"><span class="pre">__init__.py</span></tt> files
<em>must</em> contain the line:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nb">__import__</span><span class="p">(</span><span class="s">'pkg_resources'</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’s
<tt class="docutils literal"><span class="pre">__init__.py</span></tt>. Even though it may appear to work during development, or when
projects are installed as <tt class="docutils literal"><span class="pre">.egg</span></tt> files, it will not work when the projects
are installed using “system” packaging tools – in such cases the
<tt class="docutils literal"><span class="pre">__init__.py</span></tt> files will not be installed, let alone executed.</p>
<p>You must include the <tt class="docutils literal"><span class="pre">declare_namespace()</span></tt> line in the <tt class="docutils literal"><span class="pre">__init__.py</span></tt> 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’s copy of <tt class="docutils literal"><span class="pre">__init__.py</span></tt> is loaded first. If the first loaded
<tt class="docutils literal"><span class="pre">__init__.py</span></tt> doesn’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="#id28">TRANSITIONAL NOTE</a><a class="headerlink" href="#transitional-note" title="Permalink to this headline">¶</a></h5>
<p>Setuptools automatically calls <tt class="docutils literal"><span class="pre">declare_namespace()</span></tt> 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 <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> runtime, and also
the need for <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> to be explicitly imported before any namespace
packages work at all. In some future releases, you’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 <tt class="docutils literal"><span class="pre">declare_namespace()</span></tt> calls in your
<tt class="docutils literal"><span class="pre">__init__.py</span></tt> 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’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="#id29">Tagging and “Daily Build” or “Snapshot” 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.
“stable” 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, <tt class="docutils literal"><span class="pre">setuptools</span></tt> allows you to “tag” your source and
egg distributions by adding one or more of the following to the project’s
“official” version identifier:</p>
<ul class="simple">
<li>A manually-specified pre-release tag, such as “build” or “dev”, or a
manually-specified post-release tag, such as a build or revision number
(<tt class="docutils literal"><span class="pre">--tag-build=STRING,</span> <span class="pre">-bSTRING</span></tt>)</li>
<li>A “last-modified revision number” string generated automatically from
Subversion’s metadata (assuming your project is being built from a Subversion
“working copy”) (<tt class="docutils literal"><span class="pre">--tag-svn-revision,</span> <span class="pre">-r</span></tt>)</li>
<li>An 8-character representation of the build date (<tt class="docutils literal"><span class="pre">--tag-date,</span> <span class="pre">-d</span></tt>), as
a postrelease tag</li>
</ul>
<p>You can add these tags by adding <tt class="docutils literal"><span class="pre">egg_info</span></tt> and the desired options to
the command line ahead of the <tt class="docutils literal"><span class="pre">sdist</span></tt> or <tt class="docutils literal"><span class="pre">bdist</span></tt> 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’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-python"><div class="highlight"><pre>setup.py egg_info -rbDEV bdist_egg rotate -m.egg -k3
</pre></div>
</div>
<p>to build an egg whose version info includes ‘DEV-rNNNN’ (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 <tt class="docutils literal"><span class="pre">daily</span></tt>
that would perform the necessary tag, build, and rotate commands. Then, a
simpler script or cron job could just run <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">daily</span></tt> in each project
directory. (And, you could also define sitewide or per-user default versions
of the <tt class="docutils literal"><span class="pre">daily</span></tt> alias, so that projects that didn’t define their own would
use the appropriate defaults.)</p>
</div>
<div class="section" id="generating-source-distributions">
<h4><a class="toc-backref" href="#id30">Generating Source Distributions</a><a class="headerlink" href="#generating-source-distributions" title="Permalink to this headline">¶</a></h4>
<p><tt class="docutils literal"><span class="pre">setuptools</span></tt> enhances the distutils’ default algorithm for source file
selection, so that all files managed by CVS or Subversion in your project tree
are included in any source distribution you build. This is a big improvement
over having to manually write a <tt class="docutils literal"><span class="pre">MANIFEST.in</span></tt> file and try to keep it in
sync with your project. So, if you are using CVS or Subversion, and your
source distributions only need to include files that you’re tracking in
revision control, don’t create a a <tt class="docutils literal"><span class="pre">MANIFEST.in</span></tt> file for your project.
(And, if you already have one, you might consider deleting it the next time
you would otherwise have to change it.)</p>
<p>(NOTE: other revision control systems besides CVS and Subversion can be
supported using plugins; see the section below on <a class="reference internal" href="#adding-support-for-other-revision-control-systems">Adding Support for Other
Revision Control Systems</a> for information on how to write such plugins.)</p>
<p>If you need to include automatically generated files, or files that are kept in
an unsupported revision control system, you’ll need to create a <tt class="docutils literal"><span class="pre">MANIFEST.in</span></tt>
file to specify any files that the default file location algorithm doesn’t
catch. See the distutils documentation for more information on the format of
the <tt class="docutils literal"><span class="pre">MANIFEST.in</span></tt> file.</p>
<p>But, be sure to ignore any part of the distutils documentation that deals with
<tt class="docutils literal"><span class="pre">MANIFEST</span></tt> or how it’s generated from <tt class="docutils literal"><span class="pre">MANIFEST.in</span></tt>; setuptools shields you
from these issues and doesn’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’s <tt class="docutils literal"><span class="pre">.egg-info</span></tt> 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’ approach to determining the contents of a source
distribution is so much simpler, its <tt class="docutils literal"><span class="pre">sdist</span></tt> command omits nearly all of
the options that the distutils’ more complex <tt class="docutils literal"><span class="pre">sdist</span></tt> process requires. For
all practical purposes, you’ll probably use only the <tt class="docutils literal"><span class="pre">--formats</span></tt> option, if
you use any option at all.</p>
<p>(By the way, if you’re using some other revision control system, you might
consider creating and publishing a <a class="reference internal" href="#adding-support-for-other-revision-control-systems">revision control plugin for setuptools</a>.)</p>
</div>
<div class="section" id="making-your-package-available-for-easyinstall">
<h4><a class="toc-backref" href="#id31">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 <tt class="docutils literal"><span class="pre">register</span></tt> command (<tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">register</span></tt>) to register your
package with PyPI, that’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’s even better, because EasyInstall will be able to find and
download them directly from your project’s PyPI page.</p>
<p>However, there may be reasons why you don’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’s what you need to do before running the <tt class="docutils literal"><span class="pre">register</span></tt> command. There
are three <tt class="docutils literal"><span class="pre">setup()</span></tt> arguments that affect EasyInstall:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">url</span></tt> and <tt class="docutils literal"><span class="pre">download_url</span></tt></dt>
<dd>These become links on your project’s PyPI page. EasyInstall will examine
them to see if they link to a package (“primary links”), or whether they are
HTML pages. If they’re HTML pages, EasyInstall scans all HREF’s on the
page for primary links</dd>
<dt><tt class="docutils literal"><span class="pre">long_description</span></tt></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 “primary link” if it is a link to a .tar.gz, .tgz, .zip,
.egg, .egg.zip, .tar.bz2, or .exe file, or if it has an <tt class="docutils literal"><span class="pre">#egg=project</span></tt> or
<tt class="docutils literal"><span class="pre">#egg=project-version</span></tt> 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 <tt class="docutils literal"><span class="pre">url</span></tt> or <tt class="docutils literal"><span class="pre">download_url</span></tt> 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
<tt class="docutils literal"><span class="pre">#egg=project</span></tt> or <tt class="docutils literal"><span class="pre">#egg=project-version</span></tt> added to the URL. You should
replace <tt class="docutils literal"><span class="pre">project</span></tt> and <tt class="docutils literal"><span class="pre">version</span></tt> 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 <tt class="docutils literal"><span class="pre">#egg=</span></tt> suffix, and
it’s a higher version than EasyInstall has seen in any other links for your
project.</p>
<p>As a result, it’s a common practice to use mark checkout URLs with a version of
“dev” (i.e., <tt class="docutils literal"><span class="pre">#egg=projectname-dev</span></tt>), so that users can do something like
this:</p>
<div class="highlight-python"><div class="highlight"><pre>easy_install --editable projectname==dev
</pre></div>
</div>
<p>in order to check out the in-development version of <tt class="docutils literal"><span class="pre">projectname</span></tt>.</p>
</div>
<div class="section" id="managing-continuous-releases-using-subversion">
<h4><a class="toc-backref" href="#id32">Managing “Continuous Releases” Using Subversion</a><a class="headerlink" href="#managing-continuous-releases-using-subversion" title="Permalink to this headline">¶</a></h4>
<p>If you expect your users to track in-development versions of your project via
Subversion, there are a few additional steps you should take to ensure that
things work smoothly with EasyInstall. First, you should add the following
to your project’s <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> file:</p>
<div class="highlight-ini"><div class="highlight"><pre><span class="k">[egg_info]</span>
<span class="na">tag_build</span> <span class="o">=</span> <span class="s">.dev</span>
<span class="na">tag_svn_revision</span> <span class="o">=</span> <span class="s">1</span>
</pre></div>
</div>
<p>This will tell <tt class="docutils literal"><span class="pre">setuptools</span></tt> to generate package version numbers like
<tt class="docutils literal"><span class="pre">1.0a1.dev-r1263</span></tt>, which will be considered to be an <em>older</em> release than
<tt class="docutils literal"><span class="pre">1.0a1</span></tt>. Thus, when you actually release <tt class="docutils literal"><span class="pre">1.0a1</span></tt>, the entire egg
infrastructure (including <tt class="docutils literal"><span class="pre">setuptools</span></tt>, <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> and EasyInstall)
will know that <tt class="docutils literal"><span class="pre">1.0a1</span></tt> supersedes any interim snapshots from Subversion, and
handle upgrades accordingly.</p>
<p>(Note: the project version number you specify in <tt class="docutils literal"><span class="pre">setup.py</span></tt> should always be
the <em>next</em> version of your software, not the last released version.
Alternately, you can leave out the <tt class="docutils literal"><span class="pre">tag_build=.dev</span></tt>, and always use the
<em>last</em> release as a version number, so that your post-1.0 builds are labelled
<tt class="docutils literal"><span class="pre">1.0-r1263</span></tt>, indicating a post-1.0 patchlevel. Most projects so far,
however, seem to prefer to think of their project as being a future version
still under development, rather than a past version being patched. It is of
course possible for a single project to have both situations, using
post-release numbering on release branches, and pre-release numbering on the
trunk. But you don’t have to make things this complex if you don’t want to.)</p>
<p>Commonly, projects releasing code from Subversion will include a PyPI link to
their checkout URL (as described in the previous section) with an
<tt class="docutils literal"><span class="pre">#egg=projectname-dev</span></tt> suffix. This allows users to request EasyInstall
to download <tt class="docutils literal"><span class="pre">projectname==dev</span></tt> in order to get the latest in-development
code. Note that if your project depends on such in-progress code, you may wish
to specify your <tt class="docutils literal"><span class="pre">install_requires</span></tt> (or other requirements) to include
<tt class="docutils literal"><span class="pre">==dev</span></tt>, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">install_requires</span> <span class="o">=</span> <span class="p">[</span><span class="s">"OtherProject>=0.2a1.dev-r143,==dev"</span><span class="p">]</span>
</pre></div>
</div>
<p>The above example says, “I really want at least this particular development
revision number, but feel free to follow and use an <tt class="docutils literal"><span class="pre">#egg=OtherProject-dev</span></tt>
link if you find one”. This avoids the need to have actual source or binary
distribution snapshots of in-development code available, just to be able to
depend on the latest and greatest a project has to offer.</p>
<p>A final note for Subversion development: if you are using SVN revision tags
as described in this section, it’s a good idea to run <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">develop</span></tt>
after each Subversion checkin or update, because your project’s version number
will be changing, and your script wrappers need to be updated accordingly.</p>
<p>Also, if the project’s requirements have changed, the <tt class="docutils literal"><span class="pre">develop</span></tt> command will
take care of fetching the updated dependencies, building changed extensions,
etc. Be sure to also remind any of your users who check out your project
from Subversion that they need to run <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">develop</span></tt> after every update
in order to keep their checkout completely in sync.</p>
<div class="section" id="making-official-non-snapshot-releases">
<h5><a class="toc-backref" href="#id33">Making “Official” (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 <tt class="docutils literal"><span class="pre">setup.cfg</span></tt>, so that you
don’t end up registering versions like <tt class="docutils literal"><span class="pre">foobar-0.7a1.dev-r34832</span></tt>. 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 <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> 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-python"><div class="highlight"><pre>python setup.py egg_info -RDb "" sdist bdist_egg register upload
</pre></div>
</div>
<p>The first part of this command (<tt class="docutils literal"><span class="pre">egg_info</span> <span class="pre">-RDb</span> <span class="pre">""</span></tt>) 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 <tt class="docutils literal"><span class="pre">setup.py</span></tt>, without adding the Subversion
revision number or 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-python"><div class="highlight"><pre>python setup.py alias -u release egg_info -RDb ""
</pre></div>
</div>
<p>You can then use it like this:</p>
<div class="highlight-python"><div class="highlight"><pre>python setup.py release sdist bdist_egg register upload
</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><tt class="docutils literal"><span class="pre">setuptools</span></tt> includes transparent support for building Pyrex extensions, as
long as you define your extensions using <tt class="docutils literal"><span class="pre">setuptools.Extension</span></tt>, <em>not</em>
<tt class="docutils literal"><span class="pre">distutils.Extension</span></tt>. You must also not import anything from Pyrex in
your setup script.</p>
<p>If you follow these rules, you can safely list <tt class="docutils literal"><span class="pre">.pyx</span></tt> files as the source
of your <tt class="docutils literal"><span class="pre">Extension</span></tt> objects in the setup script. <tt class="docutils literal"><span class="pre">setuptools</span></tt> will detect
at build time whether Pyrex is installed or not. If it is, then <tt class="docutils literal"><span class="pre">setuptools</span></tt>
will use it. If not, then <tt class="docutils literal"><span class="pre">setuptools</span></tt> will silently change the
<tt class="docutils literal"><span class="pre">Extension</span></tt> objects to refer to the <tt class="docutils literal"><span class="pre">.c</span></tt> counterparts of the <tt class="docutils literal"><span class="pre">.pyx</span></tt>
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 <tt class="docutils literal"><span class="pre">.pyx</span></tt> files. This means
that you will probably want to include current <tt class="docutils literal"><span class="pre">.c</span></tt> files in your revision
control system, rebuilding them whenever you check changes in for the <tt class="docutils literal"><span class="pre">.pyx</span></tt>
source files. This will ensure that people tracking your project in CVS or
Subversion will be able to build it even if they don’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"><tt class="docutils literal"><span class="pre">alias</span></tt> - 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’t
necessarily set them as defaults. For example, if you produce both development
snapshot releases and “stable” releases of a project, you may want to put
the distributions in different places, or use different <tt class="docutils literal"><span class="pre">egg_info</span></tt> tagging
options, etc. In these cases, it doesn’t make sense to set the options in
a distutils configuration file, because the values of the options changed based
on what you’re trying to do.</p>
<p>Setuptools therefore allows you to define “aliases” - shortcut names for
an arbitrary string of commands and options, using <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">alias</span> <span class="pre">aliasname</span>
<span class="pre">expansion</span></tt>, 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 “daily”, that sets various <tt class="docutils literal"><span class="pre">egg_info</span></tt> tagging
options:</p>
<div class="highlight-python"><div class="highlight"><pre>setup.py alias --global-config daily egg_info --tag-svn-revision \
--tag-build=development
</pre></div>
</div>
<p>Once the alias is defined, it can then be used with other setup commands,
e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre>setup.py daily bdist_egg # generate a daily-build .egg file
setup.py daily sdist # generate a daily-build source distro
setup.py daily sdist bdist_egg # generate both
</pre></div>
</div>
<p>The above commands are interpreted as if the word <tt class="docutils literal"><span class="pre">daily</span></tt> were replaced with
<tt class="docutils literal"><span class="pre">egg_info</span> <span class="pre">--tag-svn-revision</span> <span class="pre">--tag-build=development</span></tt>.</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’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-python"><div class="highlight"><pre>setup.py alias bdist_egg bdist_egg rotate -k1 -m.egg
</pre></div>
</div>
<p>redefines the <tt class="docutils literal"><span class="pre">bdist_egg</span></tt> command so that it always runs the <tt class="docutils literal"><span class="pre">rotate</span></tt>
command afterwards to delete all but the newest egg file. It doesn’t loop
indefinitely on <tt class="docutils literal"><span class="pre">bdist_egg</span></tt> because the alias is only expanded once when
used.</p>
<p>You can remove a defined alias with the <tt class="docutils literal"><span class="pre">--remove</span></tt> (or <tt class="docutils literal"><span class="pre">-r</span></tt>) option, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre>setup.py alias --global-config --remove daily
</pre></div>
</div>
<p>would delete the “daily” 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 “expansion” argument to the <tt class="docutils literal"><span class="pre">alias</span></tt> command,
you’ll get output showing that alias’ current definition (and what
configuration file it’s defined in). If you omit the alias name as well,
you’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"><tt class="docutils literal"><span class="pre">bdist_egg</span></tt> - 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 (<tt class="docutils literal"><span class="pre">.egg</span></tt> file) for the project. Python
Eggs are the preferred binary distribution format for EasyInstall, because they
are cross-platform (for “pure” packages), directly importable, and contain
project metadata including scripts and information about the project’s
dependencies. They can be simply downloaded and added to <tt class="docutils literal"><span class="pre">sys.path</span></tt>
directly, or they can be placed in a directory on <tt class="docutils literal"><span class="pre">sys.path</span></tt> 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’t already run) to update
the project’s metadata (<tt class="docutils literal"><span class="pre">.egg-info</span></tt>) directory. If you have added any extra
metadata files to the <tt class="docutils literal"><span class="pre">.egg-info</span></tt> directory, those files will be included in
the new egg file’s metadata directory, for use by the egg runtime system or by
any applications or frameworks that use that metadata.</p>
<p>You won’t usually need to specify any special options for this command; just
use <tt class="docutils literal"><span class="pre">bdist_egg</span></tt> and you’re done. But there are a few options that may
be occasionally useful:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">--dist-dir=DIR,</span> <span class="pre">-d</span> <span class="pre">DIR</span></tt></dt>
<dd>Set the directory where the <tt class="docutils literal"><span class="pre">.egg</span></tt> file will be placed. If you don’t
supply this, then the <tt class="docutils literal"><span class="pre">--dist-dir</span></tt> setting of the <tt class="docutils literal"><span class="pre">bdist</span></tt> command
will be used, which is usually a directory named <tt class="docutils literal"><span class="pre">dist</span></tt> in the project
directory.</dd>
<dt><tt class="docutils literal"><span class="pre">--plat-name=PLATFORM,</span> <span class="pre">-p</span> <span class="pre">PLATFORM</span></tt></dt>
<dd>Set the platform name string that will be embedded in the egg’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><tt class="docutils literal"><span class="pre">--exclude-source-files</span></tt></dt>
<dd>Don’t include any modules’ <tt class="docutils literal"><span class="pre">.py</span></tt> files in the egg, just compiled Python,
C, and data files. (Note that this doesn’t affect any <tt class="docutils literal"><span class="pre">.py</span></tt> files in the
EGG-INFO directory or its subdirectories, since for example there may be
scripts with a <tt class="docutils literal"><span class="pre">.py</span></tt> extension which must still be retained.) We don’t
recommend that you use this option except for packages that are being
bundled for proprietary end-user applications, or for “embedded” 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’s <tt class="docutils literal"><span class="pre">traceback</span></tt> module doesn’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 <tt class="docutils literal"><span class="pre">bdist</span></tt> 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><tt class="docutils literal"><span class="pre">--keep-temp,</span> <span class="pre">-k</span></tt></dt>
<dd>Keep the contents of the <tt class="docutils literal"><span class="pre">--bdist-dir</span></tt> tree around after creating the
<tt class="docutils literal"><span class="pre">.egg</span></tt> file.</dd>
<dt><tt class="docutils literal"><span class="pre">--bdist-dir=DIR,</span> <span class="pre">-b</span> <span class="pre">DIR</span></tt></dt>
<dd>Set the temporary directory for creating the distribution. The entire
contents of this directory are zipped to create the <tt class="docutils literal"><span class="pre">.egg</span></tt> file, after
running various installation commands to copy the package’s modules, data,
and extensions here.</dd>
<dt><tt class="docutils literal"><span class="pre">--skip-build</span></tt></dt>
<dd>Skip doing any “build” 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"><tt class="docutils literal"><span class="pre">develop</span></tt> - Deploy the project source in “Development Mode”</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’s source for use in one or more
“staging areas” 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 <tt class="docutils literal"><span class="pre">develop</span></tt> command works by creating an <tt class="docutils literal"><span class="pre">.egg-link</span></tt> file (named for the
project) in the given staging area. If the staging area is Python’s
<tt class="docutils literal"><span class="pre">site-packages</span></tt> directory, it also updates an <tt class="docutils literal"><span class="pre">easy-install.pth</span></tt> file so
that the project is on <tt class="docutils literal"><span class="pre">sys.path</span></tt> by default for all programs run using that
Python installation.</p>
<p>The <tt class="docutils literal"><span class="pre">develop</span></tt> command also installs wrapper scripts in the staging area (or
a separate directory, as specified) that will ensure the project’s dependencies
are available on <tt class="docutils literal"><span class="pre">sys.path</span></tt> before running the project’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 <tt class="docutils literal"><span class="pre">develop</span></tt> command invokes the <tt class="docutils literal"><span class="pre">build_ext</span> <span class="pre">-i</span></tt>
command to ensure any C extensions in the project have been built and are
up-to-date, and the <tt class="docutils literal"><span class="pre">egg_info</span></tt> command to ensure the project’s metadata is
updated (so that the runtime and wrappers know what the project’s dependencies
are). If you make any changes to the project’s setup script or C extensions,
you should rerun the <tt class="docutils literal"><span class="pre">develop</span></tt> command against all relevant staging areas to
keep the project’s scripts, metadata and extensions up-to-date. Most other
kinds of changes to your project should not require any build operations or
rerunning <tt class="docutils literal"><span class="pre">develop</span></tt>, 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
<tt class="docutils literal"><span class="pre">develop</span></tt> or <tt class="docutils literal"><span class="pre">test</span></tt> commands to keep the distribution updated.</p>
<p>Here are some of the options that the <tt class="docutils literal"><span class="pre">develop</span></tt> command accepts. Note that
they affect the project’s dependencies as well as the project itself, so if you
have dependencies that need to be installed and you use <tt class="docutils literal"><span class="pre">--exclude-scripts</span></tt>
(for example), the dependencies’ scripts will not be installed either! For
this reason, you may want to use EasyInstall to install the project’s
dependencies before using the <tt class="docutils literal"><span class="pre">develop</span></tt> command, if you need finer control
over the installation options for dependencies.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">--uninstall,</span> <span class="pre">-u</span></tt></dt>
<dd><p class="first">Un-deploy the current project. You may use the <tt class="docutils literal"><span class="pre">--install-dir</span></tt> or <tt class="docutils literal"><span class="pre">-d</span></tt>
option to designate the staging area. The created <tt class="docutils literal"><span class="pre">.egg-link</span></tt> file will
be removed, if present and it is still pointing to the project directory.
The project directory will be removed from <tt class="docutils literal"><span class="pre">easy-install.pth</span></tt> if the
staging area is Python’s <tt class="docutils literal"><span class="pre">site-packages</span></tt> 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 <tt class="docutils literal"><span class="pre">--exclude-scripts</span></tt>
(aka <tt class="docutils literal"><span class="pre">-x</span></tt>) option when you run <tt class="docutils literal"><span class="pre">develop</span></tt> to deploy the project.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">--multi-version,</span> <span class="pre">-m</span></tt></dt>
<dd><p class="first">“Multi-version” mode. Specifying this option prevents <tt class="docutils literal"><span class="pre">develop</span></tt> from
adding an <tt class="docutils literal"><span class="pre">easy-install.pth</span></tt> 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
<tt class="docutils literal"><span class="pre">pkg_resources.require()</span></tt> to put it on <tt class="docutils literal"><span class="pre">sys.path</span></tt>, or you are running
a wrapper script generated by <tt class="docutils literal"><span class="pre">setuptools</span></tt> or EasyInstall. (In which
case the wrapper script calls <tt class="docutils literal"><span class="pre">require()</span></tt> for you.)</p>
<p class="last">Note that if you install to a directory other than <tt class="docutils literal"><span class="pre">site-packages</span></tt>,
this option is automatically in effect, because <tt class="docutils literal"><span class="pre">.pth</span></tt> files can only be
used in <tt class="docutils literal"><span class="pre">site-packages</span></tt> (at least in Python 2.3 and 2.4). So, if you use
the <tt class="docutils literal"><span class="pre">--install-dir</span></tt> or <tt class="docutils literal"><span class="pre">-d</span></tt> option (or they are set via configuration
file(s)) your project and its dependencies will be deployed in multi-
version mode.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">--install-dir=DIR,</span> <span class="pre">-d</span> <span class="pre">DIR</span></tt></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 <tt class="docutils literal"><span class="pre">site-packages</span></tt> directory, but if you are using distutils
configuration files, setting things like <tt class="docutils literal"><span class="pre">prefix</span></tt> or <tt class="docutils literal"><span class="pre">install_lib</span></tt>,
then those settings are taken into account when computing the default
staging area.</dd>
<dt><tt class="docutils literal"><span class="pre">--script-dir=DIR,</span> <span class="pre">-s</span> <span class="pre">DIR</span></tt></dt>
<dd>Set the script installation directory. If you don’t supply this option
(via the command line or a configuration file), but you <em>have</em> supplied
an <tt class="docutils literal"><span class="pre">--install-dir</span></tt> (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><tt class="docutils literal"><span class="pre">--exclude-scripts,</span> <span class="pre">-x</span></tt></dt>
<dd>Don’t deploy script wrappers. This is useful if you don’t want to disturb
existing versions of the scripts in the staging area.</dd>
<dt><tt class="docutils literal"><span class="pre">--always-copy,</span> <span class="pre">-a</span></tt></dt>
<dd>Copy all needed distributions to the staging area, even if they
are already present in another directory on <tt class="docutils literal"><span class="pre">sys.path</span></tt>. By default, if
a requirement can be met using a distribution that is already available in
a directory on <tt class="docutils literal"><span class="pre">sys.path</span></tt>, it will not be copied to the staging area.</dd>
<dt><tt class="docutils literal"><span class="pre">--egg-path=DIR</span></tt></dt>
<dd>Force the generated <tt class="docutils literal"><span class="pre">.egg-link</span></tt> 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 <tt class="docutils literal"><span class="pre">develop</span></tt> command also accepts all of
the same options accepted by <tt class="docutils literal"><span class="pre">easy_install</span></tt>. If you’ve configured any
<tt class="docutils literal"><span class="pre">easy_install</span></tt> settings in your <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> (or other distutils config
files), the <tt class="docutils literal"><span class="pre">develop</span></tt> command will use them as defaults, unless you override
them in a <tt class="docutils literal"><span class="pre">[develop]</span></tt> 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"><tt class="docutils literal"><span class="pre">easy_install</span></tt> - 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 <tt class="docutils literal"><span class="pre">easy_install</span></tt> 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 <tt class="docutils literal"><span class="pre">easy_install</span></tt> directly. It’s only listed here so that you know
it’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 <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> 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"><tt class="docutils literal"><span class="pre">egg_info</span></tt> - 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’s <tt class="docutils literal"><span class="pre">.egg-info</span></tt>
metadata directory (used by the <tt class="docutils literal"><span class="pre">bdist_egg</span></tt>, <tt class="docutils literal"><span class="pre">develop</span></tt>, and <tt class="docutils literal"><span class="pre">test</span></tt>
commands), and it allows you to temporarily change a project’s version string,
to support “daily builds” or “snapshot” releases. It is run automatically by
the <tt class="docutils literal"><span class="pre">sdist</span></tt>, <tt class="docutils literal"><span class="pre">bdist_egg</span></tt>, <tt class="docutils literal"><span class="pre">develop</span></tt>, <tt class="docutils literal"><span class="pre">register</span></tt>, and <tt class="docutils literal"><span class="pre">test</span></tt> commands
in order to update the project’s metadata, but you can also specify it
explicitly in order to temporarily change the project’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 <tt class="docutils literal"><span class="pre">setuptools</span></tt> and
required by <tt class="docutils literal"><span class="pre">pkg_resources</span></tt>, this command can be extended to write other
metadata files as well, by defining entry points in the <tt class="docutils literal"><span class="pre">egg_info.writers</span></tt>
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
<tt class="docutils literal"><span class="pre">setup_requires</span></tt> argument to <tt class="docutils literal"><span class="pre">setup()</span></tt> in order to ensure that the desired
writers are available on <tt class="docutils literal"><span class="pre">sys.path</span></tt>.</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’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><tt class="docutils literal"><span class="pre">--tag-build=NAME,</span> <span class="pre">-b</span> <span class="pre">NAME</span></tt></dt>
<dd><p class="first">Append NAME to the project’s version string. Due to the way setuptools
processes “pre-release” version suffixes beginning with the letters “a”
through “e” (like “alpha”, “beta”, and “candidate”), you will usually want
to use a tag like ”.build” or ”.dev”, as this will cause the version number
to be considered <em>lower</em> than the project’s default version. (If you
want to make the version number <em>higher</em> than the default version, you can
always leave off –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 <tt class="docutils literal"><span class="pre">setup.cfg</span></tt>, you can suppress
it on the command line using <tt class="docutils literal"><span class="pre">-b</span> <span class="pre">""</span></tt> or <tt class="docutils literal"><span class="pre">--tag-build=""</span></tt> as an argument
to the <tt class="docutils literal"><span class="pre">egg_info</span></tt> command.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">--tag-svn-revision,</span> <span class="pre">-r</span></tt></dt>
<dd><p class="first">If the current directory is a Subversion checkout (i.e. has a <tt class="docutils literal"><span class="pre">.svn</span></tt>
subdirectory, this appends a string of the form “-rNNNN” to the project’s
version string, where NNNN is the revision number of the most recent
modification to the current directory, as obtained from the <tt class="docutils literal"><span class="pre">svn</span> <span class="pre">info</span></tt>
command.</p>
<p>If the current directory is not a Subversion checkout, the command will
look for a <tt class="docutils literal"><span class="pre">PKG-INFO</span></tt> file instead, and try to find the revision number
from that, by looking for a “-rNNNN” string at the end of the version
number. (This is so that building a package from a source distribution of
a Subversion snapshot will produce a binary with the correct version
number.)</p>
<p class="last">If there is no <tt class="docutils literal"><span class="pre">PKG-INFO</span></tt> file, or the version number contained therein
does not end with <tt class="docutils literal"><span class="pre">-r</span></tt> and a number, then <tt class="docutils literal"><span class="pre">-r0</span></tt> is used.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">--no-svn-revision,</span> <span class="pre">-R</span></tt></dt>
<dd>Don’t include the Subversion revision in the version number. This option
is included so you can override a default setting put in <tt class="docutils literal"><span class="pre">setup.cfg</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">--tag-date,</span> <span class="pre">-d</span></tt></dt>
<dd>Add a date stamp of the form “-YYYYMMDD” (e.g. “-20050528”) to the
project’s version number.</dd>
<dt><tt class="docutils literal"><span class="pre">--no-date,</span> <span class="pre">-D</span></tt></dt>
<dd>Don’t include a date stamp in the version number. This option is included
so you can override a default setting in <tt class="docutils literal"><span class="pre">setup.cfg</span></tt>.</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’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’s <tt class="docutils literal"><span class="pre">.egg-info</span></tt> directory. Commands that need to find
the project’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 <tt class="docutils literal"><span class="pre">egg_info</span></tt> Options</a><a class="headerlink" href="#other-egg-info-options" title="Permalink to this headline">¶</a></h4>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">--egg-base=SOURCEDIR,</span> <span class="pre">-e</span> <span class="pre">SOURCEDIR</span></tt></dt>
<dd>Specify the directory that should contain the .egg-info directory. This
should normally be the root of your project’s source tree (which is not
necessarily the same as your project directory; some projects use a <tt class="docutils literal"><span class="pre">src</span></tt>
or <tt class="docutils literal"><span class="pre">lib</span></tt> subdirectory as the source root). You should not normally need
to specify this directory, as it is normally determined from the
<tt class="docutils literal"><span class="pre">package_dir</span></tt> argument to the <tt class="docutils literal"><span class="pre">setup()</span></tt> function, if any. If there is
no <tt class="docutils literal"><span class="pre">package_dir</span></tt> 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"><tt class="docutils literal"><span class="pre">egg_info</span></tt> Examples</a><a class="headerlink" href="#egg-info-examples" title="Permalink to this headline">¶</a></h4>
<p>Creating a dated “nightly build” snapshot egg:</p>
<div class="highlight-python"><div class="highlight"><pre>python setup.py egg_info --tag-date --tag-build=DEV bdist_egg
</pre></div>
</div>
<p>Creating and uploading a release with no version tags, even if some default
tags are specified in <tt class="docutils literal"><span class="pre">setup.cfg</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre>python setup.py egg_info -RDb "" sdist bdist_egg register upload
</pre></div>
</div>
<p>(Notice that <tt class="docutils literal"><span class="pre">egg_info</span></tt> 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"><tt class="docutils literal"><span class="pre">install</span></tt> - Run <tt class="docutils literal"><span class="pre">easy_install</span></tt> 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 <tt class="docutils literal"><span class="pre">install</span></tt> command is basically a shortcut to run the
<tt class="docutils literal"><span class="pre">easy_install</span></tt> command on the current project. However, for convenience
in creating “system packages” of setuptools-based projects, you can also
use this option:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">--single-version-externally-managed</span></tt></dt>
<dd>This boolean option tells the <tt class="docutils literal"><span class="pre">install</span></tt> command to perform an “old style”
installation, with the addition of an <tt class="docutils literal"><span class="pre">.egg-info</span></tt> 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 <tt class="docutils literal"><span class="pre">--root</span></tt>
or <tt class="docutils literal"><span class="pre">--record</span></tt> 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 <tt class="docutils literal"><span class="pre">install</span></tt> is invoked by another
distutils command, so that commands like <tt class="docutils literal"><span class="pre">bdist_wininst</span></tt> and <tt class="docutils literal"><span class="pre">bdist_rpm</span></tt>
will create system packages of eggs. It is also automatically in effect if
you specify the <tt class="docutils literal"><span class="pre">--root</span></tt> 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"><tt class="docutils literal"><span class="pre">install_egg_info</span></tt> - Install an <tt class="docutils literal"><span class="pre">.egg-info</span></tt> directory in <tt class="docutils literal"><span class="pre">site-packages</span></tt></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 <tt class="docutils literal"><span class="pre">install</span></tt> operations that use the
<tt class="docutils literal"><span class="pre">--single-version-externally-managed</span></tt> 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><tt class="docutils literal"><span class="pre">--install-dir=DIR,</span> <span class="pre">-d</span> <span class="pre">DIR</span></tt></dt>
<dd>The parent directory where the <tt class="docutils literal"><span class="pre">.egg-info</span></tt> directory will be placed.
Defaults to the same as the <tt class="docutils literal"><span class="pre">--install-dir</span></tt> option specified for the
<tt class="docutils literal"><span class="pre">install_lib</span></tt> command, which is usually the system <tt class="docutils literal"><span class="pre">site-packages</span></tt>
directory.</dd>
</dl>
<p>This command assumes that the <tt class="docutils literal"><span class="pre">egg_info</span></tt> command has been given valid options
via the command line or <tt class="docutils literal"><span class="pre">setup.cfg</span></tt>, as it will invoke the <tt class="docutils literal"><span class="pre">egg_info</span></tt>
command and use its options to locate the project’s source <tt class="docutils literal"><span class="pre">.egg-info</span></tt>
directory.</p>
</div>
<div class="section" id="rotate-delete-outdated-distribution-files">
<span id="rotate"></span><h3><a class="toc-backref" href="#id46"><tt class="docutils literal"><span class="pre">rotate</span></tt> - 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 (<tt class="docutils literal"><span class="pre">dist</span></tt>)
directory will gradually fill up with older source and/or binary distribution
files. The <tt class="docutils literal"><span class="pre">rotate</span></tt> command lets you automatically clean these up, keeping
only the N most-recently modified files matching a given pattern.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">--match=PATTERNLIST,</span> <span class="pre">-m</span> <span class="pre">PATTERNLIST</span></tt></dt>
<dd>Comma-separated list of glob patterns to match. This option is <em>required</em>.
The project name and <tt class="docutils literal"><span class="pre">-*</span></tt> 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 <tt class="docutils literal"><span class="pre">.zip</span></tt> or <tt class="docutils literal"><span class="pre">.egg</span></tt> 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><tt class="docutils literal"><span class="pre">--keep=COUNT,</span> <span class="pre">-k</span> <span class="pre">COUNT</span></tt></dt>
<dd>Number of matching distributions to keep. For each group of files
identified by a pattern specified with the <tt class="docutils literal"><span class="pre">--match</span></tt> option, delete all
but the COUNT most-recently-modified files in that group. This option is
<em>required</em>.</dd>
<dt><tt class="docutils literal"><span class="pre">--dist-dir=DIR,</span> <span class="pre">-d</span> <span class="pre">DIR</span></tt></dt>
<dd>Directory where the distributions are. This defaults to the value of the
<tt class="docutils literal"><span class="pre">bdist</span></tt> command’s <tt class="docutils literal"><span class="pre">--dist-dir</span></tt> option, which will usually be the
project’s <tt class="docutils literal"><span class="pre">dist</span></tt> 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-python"><div class="highlight"><pre>setup.py rotate --match=.tar.gz --keep=3
</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-python"><div class="highlight"><pre>setup.py rotate --match=-py2.3*.egg,-py2.4*.egg --keep=1
</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"><tt class="docutils literal"><span class="pre">saveopts</span></tt> - 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 <tt class="docutils literal"><span class="pre">distutils</span></tt> 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 <tt class="docutils literal"><span class="pre">saveopts</span></tt> command. Just add it to the command line to save the
options you used. For example, this command builds the project using
the <tt class="docutils literal"><span class="pre">mingw32</span></tt> C compiler, then saves the –compiler setting as the default
for future builds (even those run implicitly by the <tt class="docutils literal"><span class="pre">install</span></tt> command):</p>
<div class="highlight-python"><div class="highlight"><pre>setup.py build --compiler=mingw32 saveopts
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">saveopts</span></tt> command saves all options for every commmand specified on the
command line to the project’s local <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> 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-python"><div class="highlight"><pre>setup.py build --compiler=mingw32 saveopts -g
</pre></div>
</div>
<p>Note that it doesn’t matter where you place the <tt class="docutils literal"><span class="pre">saveopts</span></tt> 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-python"><div class="highlight"><pre>setup.py saveopts -g build --compiler=mingw32
</pre></div>
</div>
<p>Note, however, that all of the commands specified are always run, regardless of
where <tt class="docutils literal"><span class="pre">saveopts</span></tt> 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’s
local <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> 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><tt class="docutils literal"><span class="pre">--global-config,</span> <span class="pre">-g</span></tt></dt>
<dd>Save settings to the global <tt class="docutils literal"><span class="pre">distutils.cfg</span></tt> file inside the <tt class="docutils literal"><span class="pre">distutils</span></tt>
package directory. You must have write access to that directory to use
this option. You also can’t combine this option with <tt class="docutils literal"><span class="pre">-u</span></tt> or <tt class="docutils literal"><span class="pre">-f</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">--user-config,</span> <span class="pre">-u</span></tt></dt>
<dd>Save settings to the current user’s <tt class="docutils literal"><span class="pre">~/.pydistutils.cfg</span></tt> (POSIX) or
<tt class="docutils literal"><span class="pre">$HOME/pydistutils.cfg</span></tt> (Windows) file. You can’t combine this option
with <tt class="docutils literal"><span class="pre">-g</span></tt> or <tt class="docutils literal"><span class="pre">-f</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">--filename=FILENAME,</span> <span class="pre">-f</span> <span class="pre">FILENAME</span></tt></dt>
<dd>Save settings to the specified configuration file to use. You can’t
combine this option with <tt class="docutils literal"><span class="pre">-g</span></tt> or <tt class="docutils literal"><span class="pre">-u</span></tt>. Note that if you specify a
non-standard filename, the <tt class="docutils literal"><span class="pre">distutils</span></tt> and <tt class="docutils literal"><span class="pre">setuptools</span></tt> will not
use the file’s contents. This option is mainly included for use in
testing.</dd>
</dl>
<p>These options are used by other <tt class="docutils literal"><span class="pre">setuptools</span></tt> 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"><tt class="docutils literal"><span class="pre">setopt</span></tt> - 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 <tt class="docutils literal"><span class="pre">mingw32</span></tt> (using long option
names):</p>
<div class="highlight-python"><div class="highlight"><pre>setup.py setopt --command=build --option=compiler --set-value=mingw32
</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-python"><div class="highlight"><pre>setup.py setopt -c install -o install_lib -r
</pre></div>
</div>
<p>Options for the <tt class="docutils literal"><span class="pre">setopt</span></tt> command:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">--command=COMMAND,</span> <span class="pre">-c</span> <span class="pre">COMMAND</span></tt></dt>
<dd>Command to set the option for. This option is required.</dd>
<dt><tt class="docutils literal"><span class="pre">--option=OPTION,</span> <span class="pre">-o</span> <span class="pre">OPTION</span></tt></dt>
<dd>The name of the option to set. This option is required.</dd>
<dt><tt class="docutils literal"><span class="pre">--set-value=VALUE,</span> <span class="pre">-s</span> <span class="pre">VALUE</span></tt></dt>
<dd>The value to set the option to. Not needed if <tt class="docutils literal"><span class="pre">-r</span></tt> or <tt class="docutils literal"><span class="pre">--remove</span></tt> is
set.</dd>
<dt><tt class="docutils literal"><span class="pre">--remove,</span> <span class="pre">-r</span></tt></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"><tt class="docutils literal"><span class="pre">test</span></tt> - 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’s often useful
to be able to run a project’s unit tests without actually deploying the project
anywhere, even using the <tt class="docutils literal"><span class="pre">develop</span></tt> command. The <tt class="docutils literal"><span class="pre">test</span></tt> command runs a
project’s unit tests without actually deploying it, by temporarily putting the
project’s source on <tt class="docutils literal"><span class="pre">sys.path</span></tt>, after first running <tt class="docutils literal"><span class="pre">build_ext</span> <span class="pre">-i</span></tt> and
<tt class="docutils literal"><span class="pre">egg_info</span></tt> to ensure that any C extensions and project metadata are
up-to-date.</p>
<p>To use this command, your project’s tests must be wrapped in a <tt class="docutils literal"><span class="pre">unittest</span></tt>
test suite by either a function, a <tt class="docutils literal"><span class="pre">TestCase</span></tt> class or method, or a module
or package containing <tt class="docutils literal"><span class="pre">TestCase</span></tt> classes. If the named suite is a module,
and the module has an <tt class="docutils literal"><span class="pre">additional_tests()</span></tt> function, it is called and the
result (which must be a <tt class="docutils literal"><span class="pre">unittest.TestSuite</span></tt>) 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 <tt class="docutils literal"><span class="pre">test_loader</span></tt>, the rules for processing the chosen <tt class="docutils literal"><span class="pre">test_suite</span></tt> 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 <tt class="docutils literal"><span class="pre">doctest</span></tt> support wrapping their
non-<tt class="docutils literal"><span class="pre">unittest</span></tt> tests in <tt class="docutils literal"><span class="pre">TestSuite</span></tt> 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 “verbose” mode of the <tt class="docutils literal"><span class="pre">unittest</span></tt>
package’s text test runner, but you can get the “quiet” mode (just dots) if
you supply the <tt class="docutils literal"><span class="pre">-q</span></tt> or <tt class="docutils literal"><span class="pre">--quiet</span></tt> option, either as a global option to
the setup script (e.g. <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">-q</span> <span class="pre">test</span></tt>) or as an option for the <tt class="docutils literal"><span class="pre">test</span></tt>
command itself (e.g. <tt class="docutils literal"><span class="pre">setup.py</span> <span class="pre">test</span> <span class="pre">-q</span></tt>). There is one other option
available:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">--test-suite=NAME,</span> <span class="pre">-s</span> <span class="pre">NAME</span></tt></dt>
<dd><p class="first">Specify the test suite (or module, class, or method) to be run
(e.g. <tt class="docutils literal"><span class="pre">some_module.test_suite</span></tt>). The default for this option can be
set by giving a <tt class="docutils literal"><span class="pre">test_suite</span></tt> argument to the <tt class="docutils literal"><span class="pre">setup()</span></tt> function, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">setup</span><span class="p">(</span>
<span class="c"># ...</span>
<span class="n">test_suite</span> <span class="o">=</span> <span class="s">"my_package.tests.test_all"</span>
<span class="p">)</span>
</pre></div>
</div>
<p class="last">If you did not set a <tt class="docutils literal"><span class="pre">test_suite</span></tt> in your <tt class="docutils literal"><span class="pre">setup()</span></tt> call, and do not
provide a <tt class="docutils literal"><span class="pre">--test-suite</span></tt> 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"><tt class="docutils literal"><span class="pre">upload</span></tt> - 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>PyPI now supports uploading project files for redistribution; uploaded files
are easily found by EasyInstall, even if you don’t have download links on your
project’s home page.</p>
<p>Although Python 2.5 will support uploading all types of distributions to PyPI,
setuptools only supports source distributions and eggs. (This is partly
because PyPI’s upload support is currently broken for various other file
types.) To upload files, you must include the <tt class="docutils literal"><span class="pre">upload</span></tt> command <em>after</em> the
<tt class="docutils literal"><span class="pre">sdist</span></tt> or <tt class="docutils literal"><span class="pre">bdist_egg</span></tt> commands on the setup command line. For example:</p>
<div class="highlight-python"><div class="highlight"><pre>setup.py bdist_egg upload # create an egg and upload it
setup.py sdist upload # create a source distro and upload it
setup.py sdist bdist_egg upload # create and upload both
</pre></div>
</div>
<p>Note that to upload files for a project, the corresponding version must already
be registered with PyPI, using the distutils <tt class="docutils literal"><span class="pre">register</span></tt> command. It’s
usually a good idea to include the <tt class="docutils literal"><span class="pre">register</span></tt> command at the start of the
command line, so that any registration problems can be found and fixed before
building and uploading the distributions, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre>setup.py register sdist bdist_egg upload
</pre></div>
</div>
<p>This will update PyPI’s listing for your project’s current version.</p>
<p>Note, by the way, that the metadata in your <tt class="docutils literal"><span class="pre">setup()</span></tt> call determines what
will be listed in PyPI for your package. Try to fill out as much of it as
possible, as it will save you a lot of trouble manually adding and updating
your PyPI listings. Just put it in <tt class="docutils literal"><span class="pre">setup.py</span></tt> and use the <tt class="docutils literal"><span class="pre">register</span></tt>
comamnd to keep PyPI up to date.</p>
<p>The <tt class="docutils literal"><span class="pre">upload</span></tt> command has a few options worth noting:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">--sign,</span> <span class="pre">-s</span></tt></dt>
<dd>Sign each uploaded file using GPG (GNU Privacy Guard). The <tt class="docutils literal"><span class="pre">gpg</span></tt> program
must be available for execution on the system <tt class="docutils literal"><span class="pre">PATH</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">--identity=NAME,</span> <span class="pre">-i</span> <span class="pre">NAME</span></tt></dt>
<dd>Specify the identity or key name for GPG to use when signing. The value of
this option will be passed through the <tt class="docutils literal"><span class="pre">--local-user</span></tt> option of the
<tt class="docutils literal"><span class="pre">gpg</span></tt> program.</dd>
<dt><tt class="docutils literal"><span class="pre">--show-response</span></tt></dt>
<dd>Display the full response text from server; this is useful for debugging
PyPI problems.</dd>
<dt><tt class="docutils literal"><span class="pre">--repository=URL,</span> <span class="pre">-r</span> <span class="pre">URL</span></tt></dt>
<dd>The URL of the repository to upload to. Defaults to
<a class="reference external" href="https://pypi.python.org/pypi">https://pypi.python.org/pypi</a> (i.e., the main PyPI installation).</dd>
</dl>
</div>
<div class="section" id="upload-docs-upload-package-documentation-to-pypi">
<span id="upload-docs"></span><h3><a class="toc-backref" href="#id52"><tt class="docutils literal"><span class="pre">upload_docs</span></tt> - Upload package documentation to PyPI</a><a class="headerlink" href="#upload-docs-upload-package-documentation-to-pypi" title="Permalink to this headline">¶</a></h3>
<p>PyPI now supports uploading project documentation to the dedicated URL
<a class="reference external" href="https://pythonhosted.org">https://pythonhosted.org</a>/<project>/.</p>
<p>The <tt class="docutils literal"><span class="pre">upload_docs</span></tt> command will create the necessary zip file out of a
documentation directory and will post to the repository.</p>
<p>Note that to upload the documentation of a project, the corresponding version
must already be registered with PyPI, using the distutils <tt class="docutils literal"><span class="pre">register</span></tt>
command – just like the <tt class="docutils literal"><span class="pre">upload</span></tt> command.</p>
<p>Assuming there is an <tt class="docutils literal"><span class="pre">Example</span></tt> project with documentation in the
subdirectory <tt class="docutils literal"><span class="pre">docs</span></tt>, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre>Example/
|-- example.py
|-- setup.cfg
|-- setup.py
|-- docs
| |-- build
| | `-- html
| | | |-- index.html
| | | `-- tips_tricks.html
| |-- conf.py
| |-- index.txt
| `-- tips_tricks.txt
</pre></div>
</div>
<p>You can simply pass the documentation directory path to the <tt class="docutils literal"><span class="pre">upload_docs</span></tt>
command:</p>
<div class="highlight-python"><div class="highlight"><pre>python setup.py upload_docs --upload-dir=docs/build/html
</pre></div>
</div>
<p>If no <tt class="docutils literal"><span class="pre">--upload-dir</span></tt> is given, <tt class="docutils literal"><span class="pre">upload_docs</span></tt> will attempt to run the
<tt class="docutils literal"><span class="pre">build_sphinx</span></tt> command to generate uploadable documentation.
For the command to become available, <a class="reference external" href="http://sphinx.pocoo.org/">Sphinx</a>
must be installed in the same environment as distribute.</p>
<p>As with other <tt class="docutils literal"><span class="pre">setuptools</span></tt>-based commands, you can define useful
defaults in the <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> of your Python project, e.g.:</p>
<div class="highlight-ini"><div class="highlight"><pre><span class="k">[upload_docs]</span>
<span class="na">upload-dir</span> <span class="o">=</span> <span class="s">docs/build/html</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">upload_docs</span></tt> command has the following options:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">--upload-dir</span></tt></dt>
<dd>The directory to be uploaded to the repository.</dd>
<dt><tt class="docutils literal"><span class="pre">--show-response</span></tt></dt>
<dd>Display the full response text from server; this is useful for debugging
PyPI problems.</dd>
<dt><tt class="docutils literal"><span class="pre">--repository=URL,</span> <span class="pre">-r</span> <span class="pre">URL</span></tt></dt>
<dd>The URL of the repository to upload to. Defaults to
<a class="reference external" href="https://pypi.python.org/pypi">https://pypi.python.org/pypi</a> (i.e., the main PyPI installation).</dd>
</dl>
</div>
</div>
<div class="section" id="extending-and-reusing-distribute">
<h2><a class="toc-backref" href="#id53">Extending and Reusing Distribute</a><a class="headerlink" href="#extending-and-reusing-distribute" title="Permalink to this headline">¶</a></h2>
<div class="section" id="creating-distutils-extensions">
<h3><a class="toc-backref" href="#id54">Creating <tt class="docutils literal"><span class="pre">distutils</span></tt> 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 <tt class="docutils literal"><span class="pre">setuptools</span></tt> 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 <tt class="docutils literal"><span class="pre">setup_requires</span></tt> argument.</p>
<p>With <tt class="docutils literal"><span class="pre">setuptools</span></tt>, your distutils extension projects can hook in new
commands and <tt class="docutils literal"><span class="pre">setup()</span></tt> arguments just by defining “entry points”. 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="#id55">Adding Commands</a><a class="headerlink" href="#adding-commands" title="Permalink to this headline">¶</a></h4>
<p>You can add new <tt class="docutils literal"><span class="pre">setup</span></tt> commands by defining entry points in the
<tt class="docutils literal"><span class="pre">distutils.commands</span></tt> group. For example, if you wanted to add a <tt class="docutils literal"><span class="pre">foo</span></tt>
command, you might add something like this to your distutils extension
project’s setup script:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">setup</span><span class="p">(</span>
<span class="c"># ...</span>
<span class="n">entry_points</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">"distutils.commands"</span><span class="p">:</span> <span class="p">[</span>
<span class="s">"foo = mypackage.some_module:foo"</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 <tt class="docutils literal"><span class="pre">foo</span></tt> class in <tt class="docutils literal"><span class="pre">mypackage.some_module</span></tt> is
a <tt class="docutils literal"><span class="pre">setuptools.Command</span></tt> subclass.)</p>
<p>Once a project containing such entry points has been activated on <tt class="docutils literal"><span class="pre">sys.path</span></tt>,
(e.g. by running “install” or “develop” with a site-packages installation
directory) the command(s) will be available to any <tt class="docutils literal"><span class="pre">setuptools</span></tt>-based setup
scripts. It is not necessary to use the <tt class="docutils literal"><span class="pre">--command-packages</span></tt> option or
to monkeypatch the <tt class="docutils literal"><span class="pre">distutils.command</span></tt> package to install your commands;
<tt class="docutils literal"><span class="pre">setuptools</span></tt> automatically adds a wrapper to the distutils to search for
entry points in the active distributions on <tt class="docutils literal"><span class="pre">sys.path</span></tt>. In fact, this is
how setuptools’ own commands are installed: the setuptools project’s setup
script defines entry points for them!</p>
</div>
<div class="section" id="adding-setup-arguments">
<h4><a class="toc-backref" href="#id56">Adding <tt class="docutils literal"><span class="pre">setup()</span></tt> 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 <tt class="docutils literal"><span class="pre">setup()</span></tt>
call. You can enable this by defining entry points in the
<tt class="docutils literal"><span class="pre">distutils.setup_keywords</span></tt> group. For example, if you wanted a <tt class="docutils literal"><span class="pre">setup()</span></tt>
argument called <tt class="docutils literal"><span class="pre">bar_baz</span></tt>, you might add something like this to your
distutils extension project’s setup script:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">setup</span><span class="p">(</span>
<span class="c"># ...</span>
<span class="n">entry_points</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">"distutils.commands"</span><span class="p">:</span> <span class="p">[</span>
<span class="s">"foo = mypackage.some_module:foo"</span><span class="p">,</span>
<span class="p">],</span>
<span class="s">"distutils.setup_keywords"</span><span class="p">:</span> <span class="p">[</span>
<span class="s">"bar_baz = mypackage.some_module:validate_bar_baz"</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 <tt class="docutils literal"><span class="pre">setup()</span></tt> argument, if it’s supplied. The <tt class="docutils literal"><span class="pre">Distribution</span></tt>
object will have the initial value of the attribute set to <tt class="docutils literal"><span class="pre">None</span></tt>, and the
validation function will only be called if the <tt class="docutils literal"><span class="pre">setup()</span></tt> call sets it to
a non-None value. Here’s an example validation function:</p>
<div class="highlight-python"><div class="highlight"><pre><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">"""Verify that value is True, False, 0, or 1"""</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="s">"</span><span class="si">%r</span><span class="s"> must be a boolean value (got </span><span class="si">%r</span><span class="s">)"</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 <tt class="docutils literal"><span class="pre">Distribution</span></tt> object,
the attribute name, and the attribute value. It should raise a
<tt class="docutils literal"><span class="pre">DistutilsSetupError</span></tt> (from the <tt class="docutils literal"><span class="pre">distutils.errors</span></tt> 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 <tt class="docutils literal"><span class="pre">None</span></tt> when they access it later.</p>
<p>If more than one active distribution defines an entry point for the same
<tt class="docutils literal"><span class="pre">setup()</span></tt> 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 <tt class="docutils literal"><span class="pre">Distribution</span></tt> 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 <tt class="docutils literal"><span class="pre">setup_requires</span></tt>
argument.</p>
</div>
<div class="section" id="adding-new-egg-info-files">
<h4><a class="toc-backref" href="#id57">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’ EGG-INFO directory, for easy access via the <tt class="docutils literal"><span class="pre">pkg_resources</span></tt>
metadata API. The easiest way to allow this is to create a distutils extension
to be used from the plugin projects’ setup scripts (via <tt class="docutils literal"><span class="pre">setup_requires</span></tt>)
that defines a new setup keyword, and then uses that data to write an EGG-INFO
file when the <tt class="docutils literal"><span class="pre">egg_info</span></tt> command is run.</p>
<p>The <tt class="docutils literal"><span class="pre">egg_info</span></tt> command looks for extension points in an <tt class="docutils literal"><span class="pre">egg_info.writers</span></tt>
group, and calls them to write the files. Here’s a simple example of a
distutils extension defining a setup argument <tt class="docutils literal"><span class="pre">foo_bar</span></tt>, which is a list of
lines that will be written to <tt class="docutils literal"><span class="pre">foo_bar.txt</span></tt> in the EGG-INFO directory of any
project that uses the argument:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">setup</span><span class="p">(</span>
<span class="c"># ...</span>
<span class="n">entry_points</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">"distutils.setup_keywords"</span><span class="p">:</span> <span class="p">[</span>
<span class="s">"foo_bar = setuptools.dist:assert_string_list"</span><span class="p">,</span>
<span class="p">],</span>
<span class="s">"egg_info.writers"</span><span class="p">:</span> <span class="p">[</span>
<span class="s">"foo_bar.txt = setuptools.command.egg_info:write_arg"</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’s what the writer utility looks like:</p>
<div class="highlight-python"><div class="highlight"><pre><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="bp">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="bp">None</span><span class="p">:</span>
<span class="n">value</span> <span class="o">=</span> <span class="s">'</span><span class="se">\n</span><span class="s">'</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="s">'</span><span class="se">\n</span><span class="s">'</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, <tt class="docutils literal"><span class="pre">egg_info.writers</span></tt> entry points must be a function taking
three arguments: a <tt class="docutils literal"><span class="pre">egg_info</span></tt> command instance, the basename of the file to
write (e.g. <tt class="docutils literal"><span class="pre">foo_bar.txt</span></tt>), and the actual full filename that should be
written to.</p>
<p>In general, writer functions should honor the command object’s <tt class="docutils literal"><span class="pre">dry_run</span></tt>
setting when writing files, and use the <tt class="docutils literal"><span class="pre">distutils.log</span></tt> object to do any
console output. The easiest way to conform to this requirement is to use
the <tt class="docutils literal"><span class="pre">cmd</span></tt> object’s <tt class="docutils literal"><span class="pre">write_file()</span></tt>, <tt class="docutils literal"><span class="pre">delete_file()</span></tt>, and
<tt class="docutils literal"><span class="pre">write_or_delete_file()</span></tt> methods exclusively for your file operations. See
those methods’ docstrings for more details.</p>
</div>
<div class="section" id="adding-support-for-other-revision-control-systems">
<h4><a class="toc-backref" href="#id58">Adding Support for Other Revision Control Systems</a><a class="headerlink" href="#adding-support-for-other-revision-control-systems" title="Permalink to this headline">¶</a></h4>
<p>If you would like to create a plugin for <tt class="docutils literal"><span class="pre">setuptools</span></tt> to find files in other
source control systems besides CVS and Subversion, you can do so by adding an
entry point to the <tt class="docutils literal"><span class="pre">setuptools.file_finders</span></tt> 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 “foobar”, you would write a function something like this:</p>
<div class="highlight-python"><div class="highlight"><pre><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="c"># 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-python"><div class="highlight"><pre><span class="n">entry_points</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">"setuptools.file_finders"</span><span class="p">:</span> <span class="p">[</span>
<span class="s">"foobar = my_foobar_module:find_files_for_foobar"</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
<tt class="docutils literal"><span class="pre">setup_requires</span></tt>. When you create a source distribution with the <tt class="docutils literal"><span class="pre">sdist</span></tt>
command, setuptools automatically records what files were found in the
<tt class="docutils literal"><span class="pre">SOURCES.txt</span></tt> file. That way, recipients of source distributions don’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 <tt class="docutils literal"><span class="pre">some/dir</span></tt> under
the current directory should NOT be rendered as <tt class="docutils literal"><span class="pre">./some/dir</span></tt> or
<tt class="docutils literal"><span class="pre">/somewhere/some/dir</span></tt>, but <em>always</em> as simply <tt class="docutils literal"><span class="pre">some/dir</span></tt></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 <tt class="docutils literal"><span class="pre">distutils.log.warn()</span></tt> to
inform the user of the missing program(s).</li>
</ul>
</div>
<div class="section" id="subclassing-command">
<h4><a class="toc-backref" href="#id59">Subclassing <tt class="docutils literal"><span class="pre">Command</span></tt></a><a class="headerlink" href="#subclassing-command" title="Permalink to this headline">¶</a></h4>
<p>Sorry, this section isn’t written yet, and neither is a lot of what’s below
this point, except for the change log. You might want to <a class="reference external" href="setuptools?action=subscribe">subscribe to changes
in this page</a> to see when new documentation is
added or updated.</p>
<p>XXX</p>
</div>
</div>
<div class="section" id="reusing-setuptools-code">
<h3><a class="toc-backref" href="#id60">Reusing <tt class="docutils literal"><span class="pre">setuptools</span></tt> 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="#id61"><tt class="docutils literal"><span class="pre">ez_setup</span></tt></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="#id62"><tt class="docutils literal"><span class="pre">setuptools.archive_util</span></tt></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="#id63"><tt class="docutils literal"><span class="pre">setuptools.sandbox</span></tt></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="#id64"><tt class="docutils literal"><span class="pre">setuptools.package_index</span></tt></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="#id65">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://bitbucket.org/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">
<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’s Guide</a><ul>
<li><a class="reference internal" href="#installing-setuptools">Installing <tt class="docutils literal"><span class="pre">setuptools</span></tt></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’s Version</a></li>
</ul>
</li>
<li><a class="reference internal" href="#new-and-changed-setup-keywords">New and Changed <tt class="docutils literal"><span class="pre">setup()</span></tt> Keywords</a><ul>
<li><a class="reference internal" href="#using-find-packages">Using <tt class="docutils literal"><span class="pre">find_packages()</span></tt></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">“Eggsecutable” 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’t in PyPI</a></li>
<li><a class="reference internal" href="#declaring-extras-optional-features-with-their-own-dependencies">Declaring “Extras” (optional features with their own 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">“Development Mode”</a></li>
<li><a class="reference internal" href="#distributing-a-setuptools-based-project">Distributing a <tt class="docutils literal"><span class="pre">setuptools</span></tt>-based project</a><ul>
<li><a class="reference internal" href="#using-setuptools-without-bundling-it">Using <tt class="docutils literal"><span class="pre">setuptools</span></tt>... 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 <tt class="docutils literal"><span class="pre">zip_safe</span></tt> 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 “Daily Build” or “Snapshot” 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></li>
<li><a class="reference internal" href="#managing-continuous-releases-using-subversion">Managing “Continuous Releases” Using Subversion</a><ul>
<li><a class="reference internal" href="#making-official-non-snapshot-releases">Making “Official” (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"><tt class="docutils literal"><span class="pre">alias</span></tt> - Define shortcuts for commonly used commands</a></li>
<li><a class="reference internal" href="#bdist-egg-create-a-python-egg-for-the-project"><tt class="docutils literal"><span class="pre">bdist_egg</span></tt> - Create a Python Egg for the project</a></li>
<li><a class="reference internal" href="#develop-deploy-the-project-source-in-development-mode"><tt class="docutils literal"><span class="pre">develop</span></tt> - Deploy the project source in “Development Mode”</a></li>
<li><a class="reference internal" href="#easy-install-find-and-install-packages"><tt class="docutils literal"><span class="pre">easy_install</span></tt> - Find and install packages</a></li>
<li><a class="reference internal" href="#egg-info-create-egg-metadata-and-set-build-tags"><tt class="docutils literal"><span class="pre">egg_info</span></tt> - 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 <tt class="docutils literal"><span class="pre">egg_info</span></tt> Options</a></li>
<li><a class="reference internal" href="#egg-info-examples"><tt class="docutils literal"><span class="pre">egg_info</span></tt> Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#install-run-easy-install-or-old-style-installation"><tt class="docutils literal"><span class="pre">install</span></tt> - Run <tt class="docutils literal"><span class="pre">easy_install</span></tt> or old-style installation</a></li>
<li><a class="reference internal" href="#install-egg-info-install-an-egg-info-directory-in-site-packages"><tt class="docutils literal"><span class="pre">install_egg_info</span></tt> - Install an <tt class="docutils literal"><span class="pre">.egg-info</span></tt> directory in <tt class="docutils literal"><span class="pre">site-packages</span></tt></a></li>
<li><a class="reference internal" href="#rotate-delete-outdated-distribution-files"><tt class="docutils literal"><span class="pre">rotate</span></tt> - Delete outdated distribution files</a></li>
<li><a class="reference internal" href="#saveopts-save-used-options-to-a-configuration-file"><tt class="docutils literal"><span class="pre">saveopts</span></tt> - 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"><tt class="docutils literal"><span class="pre">setopt</span></tt> - 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"><tt class="docutils literal"><span class="pre">test</span></tt> - Build package and run a unittest suite</a></li>
<li><a class="reference internal" href="#upload-upload-source-and-or-egg-distributions-to-pypi"><tt class="docutils literal"><span class="pre">upload</span></tt> - Upload source and/or egg distributions to PyPI</a></li>
<li><a class="reference internal" href="#upload-docs-upload-package-documentation-to-pypi"><tt class="docutils literal"><span class="pre">upload_docs</span></tt> - Upload package documentation to PyPI</a></li>
</ul>
</li>
<li><a class="reference internal" href="#extending-and-reusing-distribute">Extending and Reusing Distribute</a><ul>
<li><a class="reference internal" href="#creating-distutils-extensions">Creating <tt class="docutils literal"><span class="pre">distutils</span></tt> 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 <tt class="docutils literal"><span class="pre">setup()</span></tt> 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-other-revision-control-systems">Adding Support for Other Revision Control Systems</a></li>
<li><a class="reference internal" href="#subclassing-command">Subclassing <tt class="docutils literal"><span class="pre">Command</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#reusing-setuptools-code">Reusing <tt class="docutils literal"><span class="pre">setuptools</span></tt> Code</a><ul>
<li><a class="reference internal" href="#ez-setup"><tt class="docutils literal"><span class="pre">ez_setup</span></tt></a></li>
<li><a class="reference internal" href="#setuptools-archive-util"><tt class="docutils literal"><span class="pre">setuptools.archive_util</span></tt></a></li>
<li><a class="reference internal" href="#setuptools-sandbox"><tt class="docutils literal"><span class="pre">setuptools.sandbox</span></tt></a></li>
<li><a class="reference internal" href="#setuptools-package-index"><tt class="docutils literal"><span class="pre">setuptools.package_index</span></tt></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="using.html"
title="previous chapter">Using Setuptools in your project</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="easy_install.html"
title="next chapter">Easy Install</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/setuptools.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<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="using.html" title="Using Setuptools in your project"
>previous</a> |</li>
<li><a href="index.html">Setuptools</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2009-2013, The fellowship of the packaging.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
</div>
</body>
</html>
|