/usr/share/doc/html/pkg_resources.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 | <!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>Package Discovery and Resource Access using pkg_resources — 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="Development on Setuptools" href="development.html" />
<link rel="prev" title="Easy Install" href="easy_install.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="development.html" title="Development on Setuptools"
accesskey="N">next</a></li>
<li class="right" >
<a href="easy_install.html" title="Easy Install"
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="package-discovery-and-resource-access-using-pkg-resources">
<h1><a class="toc-backref" href="#id1">Package Discovery and Resource Access using <tt class="docutils literal"><span class="pre">pkg_resources</span></tt></a><a class="headerlink" href="#package-discovery-and-resource-access-using-pkg-resources" title="Permalink to this headline">¶</a></h1>
<p>The <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> module distributed with <tt class="docutils literal"><span class="pre">setuptools</span></tt> provides an API
for Python libraries to access their resource files, and for extensible
applications and frameworks to automatically discover plugins. It also
provides runtime support for using C extensions that are inside zipfile-format
eggs, support for merging packages that have separately-distributed modules or
subpackages, and APIs for managing Python’s current “working set” of active
packages.</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="#package-discovery-and-resource-access-using-pkg-resources" id="id1">Package Discovery and Resource Access using <tt class="docutils literal"><span class="pre">pkg_resources</span></tt></a><ul>
<li><a class="reference internal" href="#overview" id="id2">Overview</a></li>
<li><a class="reference internal" href="#api-reference" id="id3">API Reference</a><ul>
<li><a class="reference internal" href="#namespace-package-support" id="id4">Namespace Package Support</a></li>
<li><a class="reference internal" href="#workingset-objects" id="id5"><tt class="docutils literal"><span class="pre">WorkingSet</span></tt> Objects</a><ul>
<li><a class="reference internal" href="#basic-workingset-methods" id="id6">Basic <tt class="docutils literal"><span class="pre">WorkingSet</span></tt> Methods</a></li>
<li><a class="reference internal" href="#workingset-methods-and-attributes" id="id7"><tt class="docutils literal"><span class="pre">WorkingSet</span></tt> Methods and Attributes</a></li>
<li><a class="reference internal" href="#receiving-change-notifications" id="id8">Receiving Change Notifications</a></li>
<li><a class="reference internal" href="#locating-plugins" id="id9">Locating Plugins</a></li>
</ul>
</li>
<li><a class="reference internal" href="#environment-objects" id="id10"><tt class="docutils literal"><span class="pre">Environment</span></tt> Objects</a></li>
<li><a class="reference internal" href="#requirement-objects" id="id11"><tt class="docutils literal"><span class="pre">Requirement</span></tt> Objects</a><ul>
<li><a class="reference internal" href="#requirements-parsing" id="id12">Requirements Parsing</a></li>
<li><a class="reference internal" href="#requirement-methods-and-attributes" id="id13"><tt class="docutils literal"><span class="pre">Requirement</span></tt> Methods and Attributes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#entry-points" id="id14">Entry Points</a><ul>
<li><a class="reference internal" href="#convenience-api" id="id15">Convenience API</a></li>
<li><a class="reference internal" href="#creating-and-parsing" id="id16">Creating and Parsing</a></li>
<li><a class="reference internal" href="#entrypoint-objects" id="id17"><tt class="docutils literal"><span class="pre">EntryPoint</span></tt> Objects</a></li>
</ul>
</li>
<li><a class="reference internal" href="#distribution-objects" id="id18"><tt class="docutils literal"><span class="pre">Distribution</span></tt> Objects</a><ul>
<li><a class="reference internal" href="#getting-or-creating-distributions" id="id19">Getting or Creating Distributions</a></li>
<li><a class="reference internal" href="#distribution-attributes" id="id20"><tt class="docutils literal"><span class="pre">Distribution</span></tt> Attributes</a></li>
<li><a class="reference internal" href="#distribution-methods" id="id21"><tt class="docutils literal"><span class="pre">Distribution</span></tt> Methods</a></li>
</ul>
</li>
<li><a class="reference internal" href="#resourcemanager-api" id="id22"><tt class="docutils literal"><span class="pre">ResourceManager</span></tt> API</a><ul>
<li><a class="reference internal" href="#basic-resource-access" id="id23">Basic Resource Access</a></li>
<li><a class="reference internal" href="#resource-extraction" id="id24">Resource Extraction</a></li>
<li><a class="reference internal" href="#provider-interface" id="id25">“Provider” Interface</a></li>
</ul>
</li>
<li><a class="reference internal" href="#metadata-api" id="id26">Metadata API</a><ul>
<li><a class="reference internal" href="#imetadataprovider-methods" id="id27"><tt class="docutils literal"><span class="pre">IMetadataProvider</span></tt> Methods</a></li>
</ul>
</li>
<li><a class="reference internal" href="#exceptions" id="id28">Exceptions</a></li>
<li><a class="reference internal" href="#supporting-custom-importers" id="id29">Supporting Custom Importers</a><ul>
<li><a class="reference internal" href="#iresourceprovider" id="id30">IResourceProvider</a></li>
<li><a class="reference internal" href="#built-in-resource-providers" id="id31">Built-in Resource Providers</a></li>
</ul>
</li>
<li><a class="reference internal" href="#utility-functions" id="id32">Utility Functions</a><ul>
<li><a class="reference internal" href="#parsing-utilities" id="id33">Parsing Utilities</a></li>
<li><a class="reference internal" href="#platform-utilities" id="id34">Platform Utilities</a></li>
<li><a class="reference internal" href="#pep-302-utilities" id="id35">PEP 302 Utilities</a></li>
<li><a class="reference internal" href="#file-path-utilities" id="id36">File/Path Utilities</a></li>
<li><a class="reference internal" href="#history" id="id37">History</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="overview">
<h2><a class="toc-backref" href="#id2">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
<p>The <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> module provides runtime facilities for finding,
introspecting, activating and using installed Python distributions. Some
of the more advanced features (notably the support for parallel installation
of multiple versions) rely specifically on the “egg” format (either as a
zip archive or subdirectory), while others (such as plugin discovery) will
work correctly so long as “egg-info” metadata directories are available for
relevant distributions.</p>
<p>Eggs are a distribution format for Python modules, similar in concept to
Java’s “jars” or Ruby’s “gems”, or the “wheel” format defined in PEP 427.
However, unlike a pure distribution format, eggs can also be installed and
added directly to <tt class="docutils literal"><span class="pre">sys.path</span></tt> as an import location. When installed in
this way, eggs are <em>discoverable</em>, meaning that they carry metadata that
unambiguously identifies their contents and dependencies. This means that
an installed egg can be <em>automatically</em> found and added to <tt class="docutils literal"><span class="pre">sys.path</span></tt> in
response to simple requests of the form, “get me everything I need to use
docutils’ PDF support”. This feature allows mutually conflicting versions of
a distribution to co-exist in the same Python installation, with individual
applications activating the desired version at runtime by manipulating the
contents of <tt class="docutils literal"><span class="pre">sys.path</span></tt> (this differs from the virtual environment
approach, which involves creating isolated environments for each
application).</p>
<p>The following terms are needed in order to explain the capabilities offered
by this module:</p>
<dl class="docutils">
<dt>project</dt>
<dd>A library, framework, script, plugin, application, or collection of data
or other resources, or some combination thereof. Projects are assumed to
have “relatively unique” names, e.g. names registered with PyPI.</dd>
<dt>release</dt>
<dd>A snapshot of a project at a particular point in time, denoted by a version
identifier.</dd>
<dt>distribution</dt>
<dd>A file or files that represent a particular release.</dd>
<dt>importable distribution</dt>
<dd>A file or directory that, if placed on <tt class="docutils literal"><span class="pre">sys.path</span></tt>, allows Python to
import any modules contained within it.</dd>
<dt>pluggable distribution</dt>
<dd>An importable distribution whose filename unambiguously identifies its
release (i.e. project and version), and whose contents unamabiguously
specify what releases of other projects will satisfy its runtime
requirements.</dd>
<dt>extra</dt>
<dd>An “extra” is an optional feature of a release, that may impose additional
runtime requirements. For example, if docutils PDF support required a
PDF support library to be present, docutils could define its PDF support as
an “extra”, and list what other project releases need to be available in
order to provide it.</dd>
<dt>environment</dt>
<dd>A collection of distributions potentially available for importing, but not
necessarily active. More than one distribution (i.e. release version) for
a given project may be present in an environment.</dd>
<dt>working set</dt>
<dd>A collection of distributions actually available for importing, as on
<tt class="docutils literal"><span class="pre">sys.path</span></tt>. At most one distribution (release version) of a given
project may be present in a working set, as otherwise there would be
ambiguity as to what to import.</dd>
<dt>eggs</dt>
<dd>Eggs are pluggable distributions in one of the three formats currently
supported by <tt class="docutils literal"><span class="pre">pkg_resources</span></tt>. There are built eggs, development eggs,
and egg links. Built eggs are directories or zipfiles whose name ends
with <tt class="docutils literal"><span class="pre">.egg</span></tt> and follows the egg naming conventions, and contain an
<tt class="docutils literal"><span class="pre">EGG-INFO</span></tt> subdirectory (zipped or otherwise). Development eggs are
normal directories of Python code with one or more <tt class="docutils literal"><span class="pre">ProjectName.egg-info</span></tt>
subdirectories. The development egg format is also used to provide a
default version of a distribution that is available to software that
doesn’t use <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> to request specific versions. Egg links
are <tt class="docutils literal"><span class="pre">*.egg-link</span></tt> files that contain the name of a built or
development egg, to support symbolic linking on platforms that do not
have native symbolic links (or where the symbolic link support is
limited).</dd>
</dl>
<p>(For more information about these terms and concepts, see also this
<a class="reference external" href="http://mail.python.org/pipermail/distutils-sig/2005-June/004652.html">architectural overview</a> of <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> and Python Eggs in general.)</p>
</div>
<div class="section" id="api-reference">
<h2><a class="toc-backref" href="#id3">API Reference</a><a class="headerlink" href="#api-reference" title="Permalink to this headline">¶</a></h2>
<div class="section" id="namespace-package-support">
<h3><a class="toc-backref" href="#id4">Namespace Package Support</a><a class="headerlink" href="#namespace-package-support" title="Permalink to this headline">¶</a></h3>
<p>A namespace package is a package that only contains other packages and modules,
with no direct contents of its own. Such packages can be split across
multiple, separately-packaged distributions. They are normally used to split
up large packages produced by a single organization, such as in the <tt class="docutils literal"><span class="pre">zope</span></tt>
namespace package for Zope Corporation packages, and the <tt class="docutils literal"><span class="pre">peak</span></tt> namespace
package for the Python Enterprise Application Kit.</p>
<p>To create a namespace package, you list it in the <tt class="docutils literal"><span class="pre">namespace_packages</span></tt>
argument to <tt class="docutils literal"><span class="pre">setup()</span></tt>, in your project’s <tt class="docutils literal"><span class="pre">setup.py</span></tt>. (See the <a class="reference external" href="http://peak.telecommunity.com/DevCenter/setuptools#namespace-packages">setuptools
documentation on namespace packages</a> for more information on this.) Also,
you must add a <tt class="docutils literal"><span class="pre">declare_namespace()</span></tt> call in the package’s <tt class="docutils literal"><span class="pre">__init__.py</span></tt>
file(s):</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">declare_namespace(name)</span></tt></dt>
<dd>Declare that the dotted package name <cite>name</cite> is a “namespace package” whose
contained packages and modules may be spread across multiple distributions.
The named package’s <tt class="docutils literal"><span class="pre">__path__</span></tt> will be extended to include the
corresponding package in all distributions on <tt class="docutils literal"><span class="pre">sys.path</span></tt> that contain a
package of that name. (More precisely, if an importer’s
<tt class="docutils literal"><span class="pre">find_module(name)</span></tt> returns a loader, then it will also be searched for
the package’s contents.) Whenever a Distribution’s <tt class="docutils literal"><span class="pre">activate()</span></tt> method
is invoked, it checks for the presence of namespace packages and updates
their <tt class="docutils literal"><span class="pre">__path__</span></tt> contents accordingly.</dd>
</dl>
<p>Applications that manipulate namespace packages or directly alter <tt class="docutils literal"><span class="pre">sys.path</span></tt>
at runtime may also need to use this API function:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">fixup_namespace_packages(path_item)</span></tt></dt>
<dd>Declare that <cite>path_item</cite> is a newly added item on <tt class="docutils literal"><span class="pre">sys.path</span></tt> that may
need to be used to update existing namespace packages. Ordinarily, this is
called for you when an egg is automatically added to <tt class="docutils literal"><span class="pre">sys.path</span></tt>, but if
your application modifies <tt class="docutils literal"><span class="pre">sys.path</span></tt> to include locations that may
contain portions of a namespace package, you will need to call this
function to ensure they are added to the existing namespace packages.</dd>
</dl>
<p>Although by default <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> only supports namespace packages for
filesystem and zip importers, you can extend its support to other “importers”
compatible with PEP 302 using the <tt class="docutils literal"><span class="pre">register_namespace_handler()</span></tt> function.
See the section below on <a class="reference internal" href="#supporting-custom-importers">Supporting Custom Importers</a> for details.</p>
</div>
<div class="section" id="workingset-objects">
<h3><a class="toc-backref" href="#id5"><tt class="docutils literal"><span class="pre">WorkingSet</span></tt> Objects</a><a class="headerlink" href="#workingset-objects" title="Permalink to this headline">¶</a></h3>
<p>The <tt class="docutils literal"><span class="pre">WorkingSet</span></tt> class provides access to a collection of “active”
distributions. In general, there is only one meaningful <tt class="docutils literal"><span class="pre">WorkingSet</span></tt>
instance: the one that represents the distributions that are currently active
on <tt class="docutils literal"><span class="pre">sys.path</span></tt>. This global instance is available under the name
<tt class="docutils literal"><span class="pre">working_set</span></tt> in the <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> module. However, specialized
tools may wish to manipulate working sets that don’t correspond to
<tt class="docutils literal"><span class="pre">sys.path</span></tt>, and therefore may wish to create other <tt class="docutils literal"><span class="pre">WorkingSet</span></tt> instances.</p>
<p>It’s important to note that the global <tt class="docutils literal"><span class="pre">working_set</span></tt> object is initialized
from <tt class="docutils literal"><span class="pre">sys.path</span></tt> when <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> is first imported, but is only updated
if you do all future <tt class="docutils literal"><span class="pre">sys.path</span></tt> manipulation via <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> APIs. If
you manually modify <tt class="docutils literal"><span class="pre">sys.path</span></tt>, you must invoke the appropriate methods on
the <tt class="docutils literal"><span class="pre">working_set</span></tt> instance to keep it in sync. Unfortunately, Python does
not provide any way to detect arbitrary changes to a list object like
<tt class="docutils literal"><span class="pre">sys.path</span></tt>, so <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> cannot automatically update the
<tt class="docutils literal"><span class="pre">working_set</span></tt> based on changes to <tt class="docutils literal"><span class="pre">sys.path</span></tt>.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">WorkingSet(entries=None)</span></tt></dt>
<dd><p class="first">Create a <tt class="docutils literal"><span class="pre">WorkingSet</span></tt> from an iterable of path entries. If <cite>entries</cite>
is not supplied, it defaults to the value of <tt class="docutils literal"><span class="pre">sys.path</span></tt> at the time
the constructor is called.</p>
<p class="last">Note that you will not normally construct <tt class="docutils literal"><span class="pre">WorkingSet</span></tt> instances
yourself, but instead you will implicitly or explicitly use the global
<tt class="docutils literal"><span class="pre">working_set</span></tt> instance. For the most part, the <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> API
is designed so that the <tt class="docutils literal"><span class="pre">working_set</span></tt> is used by default, such that you
don’t have to explicitly refer to it most of the time.</p>
</dd>
</dl>
<p>All distributions available directly on <tt class="docutils literal"><span class="pre">sys.path</span></tt> will be activated
automatically when <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> is imported. This behaviour can cause
version conflicts for applications which require non-default versions of
those distributions. To handle this situation, <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> checks for a
<tt class="docutils literal"><span class="pre">__requires__</span></tt> attribute in the <tt class="docutils literal"><span class="pre">__main__</span></tt> module when initializing the
default working set, and uses this to ensure a suitable version of each
affected distribution is activated. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">__requires__</span> <span class="o">=</span> <span class="p">[</span><span class="s">"CherryPy < 3"</span><span class="p">]</span> <span class="c"># Must be set before pkg_resources import</span>
<span class="kn">import</span> <span class="nn">pkg_resources</span>
</pre></div>
</div>
<div class="section" id="basic-workingset-methods">
<h4><a class="toc-backref" href="#id6">Basic <tt class="docutils literal"><span class="pre">WorkingSet</span></tt> Methods</a><a class="headerlink" href="#basic-workingset-methods" title="Permalink to this headline">¶</a></h4>
<p>The following methods of <tt class="docutils literal"><span class="pre">WorkingSet</span></tt> objects are also available as module-
level functions in <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> that apply to the default <tt class="docutils literal"><span class="pre">working_set</span></tt>
instance. Thus, you can use e.g. <tt class="docutils literal"><span class="pre">pkg_resources.require()</span></tt> as an
abbreviation for <tt class="docutils literal"><span class="pre">pkg_resources.working_set.require()</span></tt>:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">require(*requirements)</span></tt></dt>
<dd><p class="first">Ensure that distributions matching <cite>requirements</cite> are activated</p>
<p><cite>requirements</cite> must be a string or a (possibly-nested) sequence
thereof, specifying the distributions and versions required. The
return value is a sequence of the distributions that needed to be
activated to fulfill the requirements; all relevant distributions are
included, even if they were already activated in this working set.</p>
<p>For the syntax of requirement specifiers, see the section below on
<a class="reference internal" href="#requirements-parsing">Requirements Parsing</a>.</p>
<p>In general, it should not be necessary for you to call this method
directly. It’s intended more for use in quick-and-dirty scripting and
interactive interpreter hacking than for production use. If you’re creating
an actual library or application, it’s strongly recommended that you create
a “setup.py” script using <tt class="docutils literal"><span class="pre">setuptools</span></tt>, and declare all your requirements
there. That way, tools like EasyInstall can automatically detect what
requirements your package has, and deal with them accordingly.</p>
<p class="last">Note that calling <tt class="docutils literal"><span class="pre">require('SomePackage')</span></tt> will not install
<tt class="docutils literal"><span class="pre">SomePackage</span></tt> if it isn’t already present. If you need to do this, you
should use the <tt class="docutils literal"><span class="pre">resolve()</span></tt> method instead, which allows you to pass an
<tt class="docutils literal"><span class="pre">installer</span></tt> callback that will be invoked when a needed distribution
can’t be found on the local machine. You can then have this callback
display a dialog, automatically download the needed distribution, or
whatever else is appropriate for your application. See the documentation
below on the <tt class="docutils literal"><span class="pre">resolve()</span></tt> method for more information, and also on the
<tt class="docutils literal"><span class="pre">obtain()</span></tt> method of <tt class="docutils literal"><span class="pre">Environment</span></tt> objects.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">run_script(requires,</span> <span class="pre">script_name)</span></tt></dt>
<dd><p class="first">Locate distribution specified by <cite>requires</cite> and run its <cite>script_name</cite>
script. <cite>requires</cite> must be a string containing a requirement specifier.
(See <a class="reference internal" href="#requirements-parsing">Requirements Parsing</a> below for the syntax.)</p>
<p>The script, if found, will be executed in <em>the caller’s globals</em>. That’s
because this method is intended to be called from wrapper scripts that
act as a proxy for the “real” scripts in a distribution. A wrapper script
usually doesn’t need to do anything but invoke this function with the
correct arguments.</p>
<p class="last">If you need more control over the script execution environment, you
probably want to use the <tt class="docutils literal"><span class="pre">run_script()</span></tt> method of a <tt class="docutils literal"><span class="pre">Distribution</span></tt>
object’s <a class="reference internal" href="#metadata-api">Metadata API</a> instead.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">iter_entry_points(group,</span> <span class="pre">name=None)</span></tt></dt>
<dd><p class="first">Yield entry point objects from <cite>group</cite> matching <cite>name</cite></p>
<p>If <cite>name</cite> is None, yields all entry points in <cite>group</cite> from all
distributions in the working set, otherwise only ones matching both
<cite>group</cite> and <cite>name</cite> are yielded. Entry points are yielded from the active
distributions in the order that the distributions appear in the working
set. (For the global <tt class="docutils literal"><span class="pre">working_set</span></tt>, this should be the same as the order
that they are listed in <tt class="docutils literal"><span class="pre">sys.path</span></tt>.) Note that within the entry points
advertised by an individual distribution, there is no particular ordering.</p>
<p class="last">Please see the section below on <a class="reference internal" href="#entry-points">Entry Points</a> for more information.</p>
</dd>
</dl>
</div>
<div class="section" id="workingset-methods-and-attributes">
<h4><a class="toc-backref" href="#id7"><tt class="docutils literal"><span class="pre">WorkingSet</span></tt> Methods and Attributes</a><a class="headerlink" href="#workingset-methods-and-attributes" title="Permalink to this headline">¶</a></h4>
<p>These methods are used to query or manipulate the contents of a specific
working set, so they must be explicitly invoked on a particular <tt class="docutils literal"><span class="pre">WorkingSet</span></tt>
instance:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">add_entry(entry)</span></tt></dt>
<dd><p class="first">Add a path item to the <tt class="docutils literal"><span class="pre">entries</span></tt>, finding any distributions on it. You
should use this when you add additional items to <tt class="docutils literal"><span class="pre">sys.path</span></tt> and you want
the global <tt class="docutils literal"><span class="pre">working_set</span></tt> to reflect the change. This method is also
called by the <tt class="docutils literal"><span class="pre">WorkingSet()</span></tt> constructor during initialization.</p>
<p class="last">This method uses <tt class="docutils literal"><span class="pre">find_distributions(entry,True)</span></tt> to find distributions
corresponding to the path entry, and then <tt class="docutils literal"><span class="pre">add()</span></tt> them. <cite>entry</cite> is
always appended to the <tt class="docutils literal"><span class="pre">entries</span></tt> attribute, even if it is already
present, however. (This is because <tt class="docutils literal"><span class="pre">sys.path</span></tt> can contain the same value
more than once, and the <tt class="docutils literal"><span class="pre">entries</span></tt> attribute should be able to reflect
this.)</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">__contains__(dist)</span></tt></dt>
<dd>True if <cite>dist</cite> is active in this <tt class="docutils literal"><span class="pre">WorkingSet</span></tt>. Note that only one
distribution for a given project can be active in a given <tt class="docutils literal"><span class="pre">WorkingSet</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">__iter__()</span></tt></dt>
<dd>Yield distributions for non-duplicate projects in the working set.
The yield order is the order in which the items’ path entries were
added to the working set.</dd>
<dt><tt class="docutils literal"><span class="pre">find(req)</span></tt></dt>
<dd>Find a distribution matching <cite>req</cite> (a <tt class="docutils literal"><span class="pre">Requirement</span></tt> instance).
If there is an active distribution for the requested project, this
returns it, as long as it meets the version requirement specified by
<cite>req</cite>. But, if there is an active distribution for the project and it
does <em>not</em> meet the <cite>req</cite> requirement, <tt class="docutils literal"><span class="pre">VersionConflict</span></tt> is raised.
If there is no active distribution for the requested project, <tt class="docutils literal"><span class="pre">None</span></tt>
is returned.</dd>
<dt><tt class="docutils literal"><span class="pre">resolve(requirements,</span> <span class="pre">env=None,</span> <span class="pre">installer=None)</span></tt></dt>
<dd><p class="first">List all distributions needed to (recursively) meet <cite>requirements</cite></p>
<p class="last"><cite>requirements</cite> must be a sequence of <tt class="docutils literal"><span class="pre">Requirement</span></tt> objects. <cite>env</cite>,
if supplied, should be an <tt class="docutils literal"><span class="pre">Environment</span></tt> instance. If
not supplied, an <tt class="docutils literal"><span class="pre">Environment</span></tt> is created from the working set’s
<tt class="docutils literal"><span class="pre">entries</span></tt>. <cite>installer</cite>, if supplied, will be invoked with each
requirement that cannot be met by an already-installed distribution; it
should return a <tt class="docutils literal"><span class="pre">Distribution</span></tt> or <tt class="docutils literal"><span class="pre">None</span></tt>. (See the <tt class="docutils literal"><span class="pre">obtain()</span></tt> method
of <a class="reference internal" href="#environment-objects">Environment Objects</a>, below, for more information on the <cite>installer</cite>
argument.)</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">add(dist,</span> <span class="pre">entry=None)</span></tt></dt>
<dd><p class="first">Add <cite>dist</cite> to working set, associated with <cite>entry</cite></p>
<p>If <cite>entry</cite> is unspecified, it defaults to <tt class="docutils literal"><span class="pre">dist.location</span></tt>. On exit from
this routine, <cite>entry</cite> is added to the end of the working set’s <tt class="docutils literal"><span class="pre">.entries</span></tt>
(if it wasn’t already present).</p>
<p><cite>dist</cite> is only added to the working set if it’s for a project that
doesn’t already have a distribution active in the set. If it’s
successfully added, any callbacks registered with the <tt class="docutils literal"><span class="pre">subscribe()</span></tt>
method will be called. (See <a class="reference internal" href="#receiving-change-notifications">Receiving Change Notifications</a>, below.)</p>
<p class="last">Note: <tt class="docutils literal"><span class="pre">add()</span></tt> is automatically called for you by the <tt class="docutils literal"><span class="pre">require()</span></tt>
method, so you don’t normally need to use this method directly.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">entries</span></tt></dt>
<dd>This attribute represents a “shadow” <tt class="docutils literal"><span class="pre">sys.path</span></tt>, primarily useful for
debugging. If you are experiencing import problems, you should check
the global <tt class="docutils literal"><span class="pre">working_set</span></tt> object’s <tt class="docutils literal"><span class="pre">entries</span></tt> against <tt class="docutils literal"><span class="pre">sys.path</span></tt>, to
ensure that they match. If they do not, then some part of your program
is manipulating <tt class="docutils literal"><span class="pre">sys.path</span></tt> without updating the <tt class="docutils literal"><span class="pre">working_set</span></tt>
accordingly. IMPORTANT NOTE: do not directly manipulate this attribute!
Setting it equal to <tt class="docutils literal"><span class="pre">sys.path</span></tt> will not fix your problem, any more than
putting black tape over an “engine warning” light will fix your car! If
this attribute is out of sync with <tt class="docutils literal"><span class="pre">sys.path</span></tt>, it’s merely an <em>indicator</em>
of the problem, not the cause of it.</dd>
</dl>
</div>
<div class="section" id="receiving-change-notifications">
<h4><a class="toc-backref" href="#id8">Receiving Change Notifications</a><a class="headerlink" href="#receiving-change-notifications" title="Permalink to this headline">¶</a></h4>
<p>Extensible applications and frameworks may need to receive notification when
a new distribution (such as a plug-in component) has been added to a working
set. This is what the <tt class="docutils literal"><span class="pre">subscribe()</span></tt> method and <tt class="docutils literal"><span class="pre">add_activation_listener()</span></tt>
function are for.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">subscribe(callback)</span></tt></dt>
<dd><p class="first">Invoke <tt class="docutils literal"><span class="pre">callback(distribution)</span></tt> once for each active distribution that is
in the set now, or gets added later. Because the callback is invoked for
already-active distributions, you do not need to loop over the working set
yourself to deal with the existing items; just register the callback and
be prepared for the fact that it will be called immediately by this method.</p>
<p class="last">Note that callbacks <em>must not</em> allow exceptions to propagate, or they will
interfere with the operation of other callbacks and possibly result in an
inconsistent working set state. Callbacks should use a try/except block
to ignore, log, or otherwise process any errors, especially since the code
that caused the callback to be invoked is unlikely to be able to handle
the errors any better than the callback itself.</p>
</dd>
</dl>
<p><tt class="docutils literal"><span class="pre">pkg_resources.add_activation_listener()</span></tt> is an alternate spelling of
<tt class="docutils literal"><span class="pre">pkg_resources.working_set.subscribe()</span></tt>.</p>
</div>
<div class="section" id="locating-plugins">
<h4><a class="toc-backref" href="#id9">Locating Plugins</a><a class="headerlink" href="#locating-plugins" title="Permalink to this headline">¶</a></h4>
<p>Extensible applications will sometimes have a “plugin directory” or a set of
plugin directories, from which they want to load entry points or other
metadata. The <tt class="docutils literal"><span class="pre">find_plugins()</span></tt> method allows you to do this, by scanning an
environment for the newest version of each project that can be safely loaded
without conflicts or missing requirements.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">find_plugins(plugin_env,</span> <span class="pre">full_env=None,</span> <span class="pre">fallback=True)</span></tt></dt>
<dd><p class="first">Scan <cite>plugin_env</cite> and identify which distributions could be added to this
working set without version conflicts or missing requirements.</p>
<p>Example usage:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">distributions</span><span class="p">,</span> <span class="n">errors</span> <span class="o">=</span> <span class="n">working_set</span><span class="o">.</span><span class="n">find_plugins</span><span class="p">(</span>
<span class="n">Environment</span><span class="p">(</span><span class="n">plugin_dirlist</span><span class="p">)</span>
<span class="p">)</span>
<span class="nb">map</span><span class="p">(</span><span class="n">working_set</span><span class="o">.</span><span class="n">add</span><span class="p">,</span> <span class="n">distributions</span><span class="p">)</span> <span class="c"># add plugins+libs to sys.path</span>
<span class="k">print</span> <span class="s">"Couldn't load"</span><span class="p">,</span> <span class="n">errors</span> <span class="c"># display errors</span>
</pre></div>
</div>
<p>The <cite>plugin_env</cite> should be an <tt class="docutils literal"><span class="pre">Environment</span></tt> instance that contains only
distributions that are in the project’s “plugin directory” or directories.
The <cite>full_env</cite>, if supplied, should be an <tt class="docutils literal"><span class="pre">Environment</span></tt> instance that
contains all currently-available distributions.</p>
<p>If <cite>full_env</cite> is not supplied, one is created automatically from the
<tt class="docutils literal"><span class="pre">WorkingSet</span></tt> this method is called on, which will typically mean that
every directory on <tt class="docutils literal"><span class="pre">sys.path</span></tt> will be scanned for distributions.</p>
<p>This method returns a 2-tuple: (<cite>distributions</cite>, <cite>error_info</cite>), where
<cite>distributions</cite> is a list of the distributions found in <cite>plugin_env</cite> that
were loadable, along with any other distributions that are needed to resolve
their dependencies. <cite>error_info</cite> is a dictionary mapping unloadable plugin
distributions to an exception instance describing the error that occurred.
Usually this will be a <tt class="docutils literal"><span class="pre">DistributionNotFound</span></tt> or <tt class="docutils literal"><span class="pre">VersionConflict</span></tt>
instance.</p>
<p>Most applications will use this method mainly on the master <tt class="docutils literal"><span class="pre">working_set</span></tt>
instance in <tt class="docutils literal"><span class="pre">pkg_resources</span></tt>, and then immediately add the returned
distributions to the working set so that they are available on sys.path.
This will make it possible to find any entry points, and allow any other
metadata tracking and hooks to be activated.</p>
<p>The resolution algorithm used by <tt class="docutils literal"><span class="pre">find_plugins()</span></tt> is as follows. First,
the project names of the distributions present in <cite>plugin_env</cite> are sorted.
Then, each project’s eggs are tried in descending version order (i.e.,
newest version first).</p>
<p>An attempt is made to resolve each egg’s dependencies. If the attempt is
successful, the egg and its dependencies are added to the output list and to
a temporary copy of the working set. The resolution process continues with
the next project name, and no older eggs for that project are tried.</p>
<p>If the resolution attempt fails, however, the error is added to the error
dictionary. If the <cite>fallback</cite> flag is true, the next older version of the
plugin is tried, until a working version is found. If false, the resolution
process continues with the next plugin project name.</p>
<p>Some applications may have stricter fallback requirements than others. For
example, an application that has a database schema or persistent objects
may not be able to safely downgrade a version of a package. Others may want
to ensure that a new plugin configuration is either 100% good or else
revert to a known-good configuration. (That is, they may wish to revert to
a known configuration if the <cite>error_info</cite> return value is non-empty.)</p>
<p class="last">Note that this algorithm gives precedence to satisfying the dependencies of
alphabetically prior project names in case of version conflicts. If two
projects named “AaronsPlugin” and “ZekesPlugin” both need different versions
of “TomsLibrary”, then “AaronsPlugin” will win and “ZekesPlugin” will be
disabled due to version conflict.</p>
</dd>
</dl>
</div>
</div>
<div class="section" id="environment-objects">
<h3><a class="toc-backref" href="#id10"><tt class="docutils literal"><span class="pre">Environment</span></tt> Objects</a><a class="headerlink" href="#environment-objects" title="Permalink to this headline">¶</a></h3>
<p>An “environment” is a collection of <tt class="docutils literal"><span class="pre">Distribution</span></tt> objects, usually ones
that are present and potentially importable on the current platform.
<tt class="docutils literal"><span class="pre">Environment</span></tt> objects are used by <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> to index available
distributions during dependency resolution.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">Environment(search_path=None,</span> <span class="pre">platform=get_supported_platform(),</span> <span class="pre">python=PY_MAJOR)</span></tt></dt>
<dd><p class="first">Create an environment snapshot by scanning <cite>search_path</cite> for distributions
compatible with <cite>platform</cite> and <cite>python</cite>. <cite>search_path</cite> should be a
sequence of strings such as might be used on <tt class="docutils literal"><span class="pre">sys.path</span></tt>. If a
<cite>search_path</cite> isn’t supplied, <tt class="docutils literal"><span class="pre">sys.path</span></tt> is used.</p>
<p><cite>platform</cite> is an optional string specifying the name of the platform
that platform-specific distributions must be compatible with. If
unspecified, it defaults to the current platform. <cite>python</cite> is an
optional string naming the desired version of Python (e.g. <tt class="docutils literal"><span class="pre">'2.4'</span></tt>);
it defaults to the currently-running version.</p>
<p>You may explicitly set <cite>platform</cite> (and/or <cite>python</cite>) to <tt class="docutils literal"><span class="pre">None</span></tt> if you
wish to include <em>all</em> distributions, not just those compatible with the
running platform or Python version.</p>
<p class="last">Note that <cite>search_path</cite> is scanned immediately for distributions, and the
resulting <tt class="docutils literal"><span class="pre">Environment</span></tt> is a snapshot of the found distributions. It
is not automatically updated if the system’s state changes due to e.g.
installation or removal of distributions.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">__getitem__(project_name)</span></tt></dt>
<dd>Returns a list of distributions for the given project name, ordered
from newest to oldest version. (And highest to lowest format precedence
for distributions that contain the same version of the project.) If there
are no distributions for the project, returns an empty list.</dd>
<dt><tt class="docutils literal"><span class="pre">__iter__()</span></tt></dt>
<dd>Yield the unique project names of the distributions in this environment.
The yielded names are always in lower case.</dd>
<dt><tt class="docutils literal"><span class="pre">add(dist)</span></tt></dt>
<dd>Add <cite>dist</cite> to the environment if it matches the platform and python version
specified at creation time, and only if the distribution hasn’t already
been added. (i.e., adding the same distribution more than once is a no-op.)</dd>
<dt><tt class="docutils literal"><span class="pre">remove(dist)</span></tt></dt>
<dd>Remove <cite>dist</cite> from the environment.</dd>
<dt><tt class="docutils literal"><span class="pre">can_add(dist)</span></tt></dt>
<dd>Is distribution <cite>dist</cite> acceptable for this environment? If it’s not
compatible with the <tt class="docutils literal"><span class="pre">platform</span></tt> and <tt class="docutils literal"><span class="pre">python</span></tt> version values specified
when the environment was created, a false value is returned.</dd>
<dt><tt class="docutils literal"><span class="pre">__add__(dist_or_env)</span></tt> (<tt class="docutils literal"><span class="pre">+</span></tt> operator)</dt>
<dd>Add a distribution or environment to an <tt class="docutils literal"><span class="pre">Environment</span></tt> instance, returning
a <em>new</em> environment object that contains all the distributions previously
contained by both. The new environment will have a <tt class="docutils literal"><span class="pre">platform</span></tt> and
<tt class="docutils literal"><span class="pre">python</span></tt> of <tt class="docutils literal"><span class="pre">None</span></tt>, meaning that it will not reject any distributions
from being added to it; it will simply accept whatever is added. If you
want the added items to be filtered for platform and Python version, or
you want to add them to the <em>same</em> environment instance, you should use
in-place addition (<tt class="docutils literal"><span class="pre">+=</span></tt>) instead.</dd>
<dt><tt class="docutils literal"><span class="pre">__iadd__(dist_or_env)</span></tt> (<tt class="docutils literal"><span class="pre">+=</span></tt> operator)</dt>
<dd>Add a distribution or environment to an <tt class="docutils literal"><span class="pre">Environment</span></tt> instance
<em>in-place</em>, updating the existing instance and returning it. The
<tt class="docutils literal"><span class="pre">platform</span></tt> and <tt class="docutils literal"><span class="pre">python</span></tt> filter attributes take effect, so distributions
in the source that do not have a suitable platform string or Python version
are silently ignored.</dd>
<dt><tt class="docutils literal"><span class="pre">best_match(req,</span> <span class="pre">working_set,</span> <span class="pre">installer=None)</span></tt></dt>
<dd><p class="first">Find distribution best matching <cite>req</cite> and usable on <cite>working_set</cite></p>
<p class="last">This calls the <tt class="docutils literal"><span class="pre">find(req)</span></tt> method of the <cite>working_set</cite> to see if a
suitable distribution is already active. (This may raise
<tt class="docutils literal"><span class="pre">VersionConflict</span></tt> if an unsuitable version of the project is already
active in the specified <cite>working_set</cite>.) If a suitable distribution isn’t
active, this method returns the newest distribution in the environment
that meets the <tt class="docutils literal"><span class="pre">Requirement</span></tt> in <cite>req</cite>. If no suitable distribution is
found, and <cite>installer</cite> is supplied, then the result of calling
the environment’s <tt class="docutils literal"><span class="pre">obtain(req,</span> <span class="pre">installer)</span></tt> method will be returned.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">obtain(requirement,</span> <span class="pre">installer=None)</span></tt></dt>
<dd>Obtain a distro that matches requirement (e.g. via download). In the
base <tt class="docutils literal"><span class="pre">Environment</span></tt> class, this routine just returns
<tt class="docutils literal"><span class="pre">installer(requirement)</span></tt>, unless <cite>installer</cite> is None, in which case
None is returned instead. This method is a hook that allows subclasses
to attempt other ways of obtaining a distribution before falling back
to the <cite>installer</cite> argument.</dd>
<dt><tt class="docutils literal"><span class="pre">scan(search_path=None)</span></tt></dt>
<dd><p class="first">Scan <cite>search_path</cite> for distributions usable on <cite>platform</cite></p>
<p class="last">Any distributions found are added to the environment. <cite>search_path</cite> should
be a sequence of strings such as might be used on <tt class="docutils literal"><span class="pre">sys.path</span></tt>. If not
supplied, <tt class="docutils literal"><span class="pre">sys.path</span></tt> is used. Only distributions conforming to
the platform/python version defined at initialization are added. This
method is a shortcut for using the <tt class="docutils literal"><span class="pre">find_distributions()</span></tt> function to
find the distributions from each item in <cite>search_path</cite>, and then calling
<tt class="docutils literal"><span class="pre">add()</span></tt> to add each one to the environment.</p>
</dd>
</dl>
</div>
<div class="section" id="requirement-objects">
<h3><a class="toc-backref" href="#id11"><tt class="docutils literal"><span class="pre">Requirement</span></tt> Objects</a><a class="headerlink" href="#requirement-objects" title="Permalink to this headline">¶</a></h3>
<p><tt class="docutils literal"><span class="pre">Requirement</span></tt> objects express what versions of a project are suitable for
some purpose. These objects (or their string form) are used by various
<tt class="docutils literal"><span class="pre">pkg_resources</span></tt> APIs in order to find distributions that a script or
distribution needs.</p>
<div class="section" id="requirements-parsing">
<h4><a class="toc-backref" href="#id12">Requirements Parsing</a><a class="headerlink" href="#requirements-parsing" title="Permalink to this headline">¶</a></h4>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">parse_requirements(s)</span></tt></dt>
<dd>Yield <tt class="docutils literal"><span class="pre">Requirement</span></tt> objects for a string or iterable of lines. Each
requirement must start on a new line. See below for syntax.</dd>
<dt><tt class="docutils literal"><span class="pre">Requirement.parse(s)</span></tt></dt>
<dd><p class="first">Create a <tt class="docutils literal"><span class="pre">Requirement</span></tt> object from a string or iterable of lines. A
<tt class="docutils literal"><span class="pre">ValueError</span></tt> is raised if the string or lines do not contain a valid
requirement specifier, or if they contain more than one specifier. (To
parse multiple specifiers from a string or iterable of strings, use
<tt class="docutils literal"><span class="pre">parse_requirements()</span></tt> instead.)</p>
<p>The syntax of a requirement specifier can be defined in EBNF as follows:</p>
<div class="highlight-python"><div class="highlight"><pre>requirement ::= project_name versionspec? extras?
versionspec ::= comparison version (',' comparison version)*
comparison ::= '<' | '<=' | '!=' | '==' | '>=' | '>'
extras ::= '[' extralist? ']'
extralist ::= identifier (',' identifier)*
project_name ::= identifier
identifier ::= [-A-Za-z0-9_]+
version ::= [-A-Za-z0-9_.]+
</pre></div>
</div>
<p>Tokens can be separated by whitespace, and a requirement can be continued
over multiple lines using a backslash (<tt class="docutils literal"><span class="pre">\\</span></tt>). Line-end comments (using
<tt class="docutils literal"><span class="pre">#</span></tt>) are also allowed.</p>
<p>Some examples of valid requirement specifiers:</p>
<div class="highlight-python"><div class="highlight"><pre>FooProject >= 1.2
Fizzy [foo, bar]
PickyThing<1.6,>1.9,!=1.9.6,<2.0a0,==2.4c1
SomethingWhoseVersionIDontCareAbout
</pre></div>
</div>
<p>The project name is the only required portion of a requirement string, and
if it’s the only thing supplied, the requirement will accept any version
of that project.</p>
<p>The “extras” in a requirement are used to request optional features of a
project, that may require additional project distributions in order to
function. For example, if the hypothetical “Report-O-Rama” project offered
optional PDF support, it might require an additional library in order to
provide that support. Thus, a project needing Report-O-Rama’s PDF features
could use a requirement of <tt class="docutils literal"><span class="pre">Report-O-Rama[PDF]</span></tt> to request installation
or activation of both Report-O-Rama and any libraries it needs in order to
provide PDF support. For example, you could use:</p>
<div class="highlight-python"><div class="highlight"><pre>easy_install.py Report-O-Rama[PDF]
</pre></div>
</div>
<p class="last">To install the necessary packages using the EasyInstall program, or call
<tt class="docutils literal"><span class="pre">pkg_resources.require('Report-O-Rama[PDF]')</span></tt> to add the necessary
distributions to sys.path at runtime.</p>
</dd>
</dl>
</div>
<div class="section" id="requirement-methods-and-attributes">
<h4><a class="toc-backref" href="#id13"><tt class="docutils literal"><span class="pre">Requirement</span></tt> Methods and Attributes</a><a class="headerlink" href="#requirement-methods-and-attributes" title="Permalink to this headline">¶</a></h4>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">__contains__(dist_or_version)</span></tt></dt>
<dd><p class="first">Return true if <cite>dist_or_version</cite> fits the criteria for this requirement.
If <cite>dist_or_version</cite> is a <tt class="docutils literal"><span class="pre">Distribution</span></tt> object, its project name must
match the requirement’s project name, and its version must meet the
requirement’s version criteria. If <cite>dist_or_version</cite> is a string, it is
parsed using the <tt class="docutils literal"><span class="pre">parse_version()</span></tt> utility function. Otherwise, it is
assumed to be an already-parsed version.</p>
<p class="last">The <tt class="docutils literal"><span class="pre">Requirement</span></tt> object’s version specifiers (<tt class="docutils literal"><span class="pre">.specs</span></tt>) are internally
sorted into ascending version order, and used to establish what ranges of
versions are acceptable. Adjacent redundant conditions are effectively
consolidated (e.g. <tt class="docutils literal"><span class="pre">">1,</span> <span class="pre">>2"</span></tt> produces the same results as <tt class="docutils literal"><span class="pre">">1"</span></tt>, and
<tt class="docutils literal"><span class="pre">"<2,<3"</span></tt> produces the same results as``”<3”<tt class="docutils literal"><span class="pre">).</span> <span class="pre">``"!="</span></tt> versions are
excised from the ranges they fall within. The version being tested for
acceptability is then checked for membership in the resulting ranges.
(Note that providing conflicting conditions for the same version (e.g.
<tt class="docutils literal"><span class="pre">"<2,>=2"</span></tt> or <tt class="docutils literal"><span class="pre">"==2,!=2"</span></tt>) is meaningless and may therefore produce
bizarre results when compared with actual version number(s).)</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">__eq__(other_requirement)</span></tt></dt>
<dd>A requirement compares equal to another requirement if they have
case-insensitively equal project names, version specifiers, and “extras”.
(The order that extras and version specifiers are in is also ignored.)
Equal requirements also have equal hashes, so that requirements can be
used in sets or as dictionary keys.</dd>
<dt><tt class="docutils literal"><span class="pre">__str__()</span></tt></dt>
<dd>The string form of a <tt class="docutils literal"><span class="pre">Requirement</span></tt> is a string that, if passed to
<tt class="docutils literal"><span class="pre">Requirement.parse()</span></tt>, would return an equal <tt class="docutils literal"><span class="pre">Requirement</span></tt> object.</dd>
<dt><tt class="docutils literal"><span class="pre">project_name</span></tt></dt>
<dd>The name of the required project</dd>
<dt><tt class="docutils literal"><span class="pre">key</span></tt></dt>
<dd>An all-lowercase version of the <tt class="docutils literal"><span class="pre">project_name</span></tt>, useful for comparison
or indexing.</dd>
<dt><tt class="docutils literal"><span class="pre">extras</span></tt></dt>
<dd>A tuple of names of “extras” that this requirement calls for. (These will
be all-lowercase and normalized using the <tt class="docutils literal"><span class="pre">safe_extra()</span></tt> parsing utility
function, so they may not exactly equal the extras the requirement was
created with.)</dd>
<dt><tt class="docutils literal"><span class="pre">specs</span></tt></dt>
<dd>A list of <tt class="docutils literal"><span class="pre">(op,version)</span></tt> tuples, sorted in ascending parsed-version
order. The <cite>op</cite> in each tuple is a comparison operator, represented as
a string. The <cite>version</cite> is the (unparsed) version number. The relative
order of tuples containing the same version numbers is undefined, since
having more than one operator for a given version is either redundant or
self-contradictory.</dd>
</dl>
</div>
</div>
<div class="section" id="entry-points">
<h3><a class="toc-backref" href="#id14">Entry Points</a><a class="headerlink" href="#entry-points" title="Permalink to this headline">¶</a></h3>
<p>Entry points are a simple way for distributions to “advertise” Python objects
(such as functions or classes) for use by other distributions. Extensible
applications and frameworks can search for entry points with a particular name
or group, either from a specific distribution or from all active distributions
on sys.path, and then inspect or load the advertised objects at will.</p>
<p>Entry points belong to “groups” which are named with a dotted name similar to
a Python package or module name. For example, the <tt class="docutils literal"><span class="pre">setuptools</span></tt> package uses
an entry point named <tt class="docutils literal"><span class="pre">distutils.commands</span></tt> in order to find commands defined
by distutils extensions. <tt class="docutils literal"><span class="pre">setuptools</span></tt> treats the names of entry points
defined in that group as the acceptable commands for a setup script.</p>
<p>In a similar way, other packages can define their own entry point groups,
either using dynamic names within the group (like <tt class="docutils literal"><span class="pre">distutils.commands</span></tt>), or
possibly using predefined names within the group. For example, a blogging
framework that offers various pre- or post-publishing hooks might define an
entry point group and look for entry points named “pre_process” and
“post_process” within that group.</p>
<p>To advertise an entry point, a project needs to use <tt class="docutils literal"><span class="pre">setuptools</span></tt> and provide
an <tt class="docutils literal"><span class="pre">entry_points</span></tt> argument to <tt class="docutils literal"><span class="pre">setup()</span></tt> in its setup script, so that the
entry points will be included in the distribution’s metadata. For more
details, see the <tt class="docutils literal"><span class="pre">setuptools</span></tt> documentation. (XXX link here to setuptools)</p>
<p>Each project distribution can advertise at most one entry point of a given
name within the same entry point group. For example, a distutils extension
could advertise two different <tt class="docutils literal"><span class="pre">distutils.commands</span></tt> entry points, as long as
they had different names. However, there is nothing that prevents <em>different</em>
projects from advertising entry points of the same name in the same group. In
some cases, this is a desirable thing, since the application or framework that
uses the entry points may be calling them as hooks, or in some other way
combining them. It is up to the application or framework to decide what to do
if multiple distributions advertise an entry point; some possibilities include
using both entry points, displaying an error message, using the first one found
in sys.path order, etc.</p>
<div class="section" id="convenience-api">
<h4><a class="toc-backref" href="#id15">Convenience API</a><a class="headerlink" href="#convenience-api" title="Permalink to this headline">¶</a></h4>
<p>In the following functions, the <cite>dist</cite> argument can be a <tt class="docutils literal"><span class="pre">Distribution</span></tt>
instance, a <tt class="docutils literal"><span class="pre">Requirement</span></tt> instance, or a string specifying a requirement
(i.e. project name, version, etc.). If the argument is a string or
<tt class="docutils literal"><span class="pre">Requirement</span></tt>, the specified distribution is located (and added to sys.path
if not already present). An error will be raised if a matching distribution is
not available.</p>
<p>The <cite>group</cite> argument should be a string containing a dotted identifier,
identifying an entry point group. If you are defining an entry point group,
you should include some portion of your package’s name in the group name so as
to avoid collision with other packages’ entry point groups.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">load_entry_point(dist,</span> <span class="pre">group,</span> <span class="pre">name)</span></tt></dt>
<dd>Load the named entry point from the specified distribution, or raise
<tt class="docutils literal"><span class="pre">ImportError</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">get_entry_info(dist,</span> <span class="pre">group,</span> <span class="pre">name)</span></tt></dt>
<dd>Return an <tt class="docutils literal"><span class="pre">EntryPoint</span></tt> object for the given <cite>group</cite> and <cite>name</cite> from
the specified distribution. Returns <tt class="docutils literal"><span class="pre">None</span></tt> if the distribution has not
advertised a matching entry point.</dd>
<dt><tt class="docutils literal"><span class="pre">get_entry_map(dist,</span> <span class="pre">group=None)</span></tt></dt>
<dd>Return the distribution’s entry point map for <cite>group</cite>, or the full entry
map for the distribution. This function always returns a dictionary,
even if the distribution advertises no entry points. If <cite>group</cite> is given,
the dictionary maps entry point names to the corresponding <tt class="docutils literal"><span class="pre">EntryPoint</span></tt>
object. If <cite>group</cite> is None, the dictionary maps group names to
dictionaries that then map entry point names to the corresponding
<tt class="docutils literal"><span class="pre">EntryPoint</span></tt> instance in that group.</dd>
<dt><tt class="docutils literal"><span class="pre">iter_entry_points(group,</span> <span class="pre">name=None)</span></tt></dt>
<dd><p class="first">Yield entry point objects from <cite>group</cite> matching <cite>name</cite>.</p>
<p>If <cite>name</cite> is None, yields all entry points in <cite>group</cite> from all
distributions in the working set on sys.path, otherwise only ones matching
both <cite>group</cite> and <cite>name</cite> are yielded. Entry points are yielded from
the active distributions in the order that the distributions appear on
sys.path. (Within entry points for a particular distribution, however,
there is no particular ordering.)</p>
<p class="last">(This API is actually a method of the global <tt class="docutils literal"><span class="pre">working_set</span></tt> object; see
the section above on <a class="reference internal" href="#basic-workingset-methods">Basic WorkingSet Methods</a> for more information.)</p>
</dd>
</dl>
</div>
<div class="section" id="creating-and-parsing">
<h4><a class="toc-backref" href="#id16">Creating and Parsing</a><a class="headerlink" href="#creating-and-parsing" title="Permalink to this headline">¶</a></h4>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">EntryPoint(name,</span> <span class="pre">module_name,</span> <span class="pre">attrs=(),</span> <span class="pre">extras=(),</span> <span class="pre">dist=None)</span></tt></dt>
<dd><p class="first">Create an <tt class="docutils literal"><span class="pre">EntryPoint</span></tt> instance. <cite>name</cite> is the entry point name. The
<cite>module_name</cite> is the (dotted) name of the module containing the advertised
object. <cite>attrs</cite> is an optional tuple of names to look up from the
module to obtain the advertised object. For example, an <cite>attrs</cite> of
<tt class="docutils literal"><span class="pre">("foo","bar")</span></tt> and a <cite>module_name</cite> of <tt class="docutils literal"><span class="pre">"baz"</span></tt> would mean that the
advertised object could be obtained by the following code:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">baz</span>
<span class="n">advertised_object</span> <span class="o">=</span> <span class="n">baz</span><span class="o">.</span><span class="n">foo</span><span class="o">.</span><span class="n">bar</span>
</pre></div>
</div>
<p class="last">The <cite>extras</cite> are an optional tuple of “extra feature” names that the
distribution needs in order to provide this entry point. When the
entry point is loaded, these extra features are looked up in the <cite>dist</cite>
argument to find out what other distributions may need to be activated
on sys.path; see the <tt class="docutils literal"><span class="pre">load()</span></tt> method for more details. The <cite>extras</cite>
argument is only meaningful if <cite>dist</cite> is specified. <cite>dist</cite> must be
a <tt class="docutils literal"><span class="pre">Distribution</span></tt> instance.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">EntryPoint.parse(src,</span> <span class="pre">dist=None)</span></tt> (classmethod)</dt>
<dd><p class="first">Parse a single entry point from string <cite>src</cite></p>
<p>Entry point syntax follows the form:</p>
<div class="highlight-python"><div class="highlight"><pre>name = some.module:some.attr [extra1,extra2]
</pre></div>
</div>
<p class="last">The entry name and module name are required, but the <tt class="docutils literal"><span class="pre">:attrs</span></tt> and
<tt class="docutils literal"><span class="pre">[extras]</span></tt> parts are optional, as is the whitespace shown between
some of the items. The <cite>dist</cite> argument is passed through to the
<tt class="docutils literal"><span class="pre">EntryPoint()</span></tt> constructor, along with the other values parsed from
<cite>src</cite>.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">EntryPoint.parse_group(group,</span> <span class="pre">lines,</span> <span class="pre">dist=None)</span></tt> (classmethod)</dt>
<dd>Parse <cite>lines</cite> (a string or sequence of lines) to create a dictionary
mapping entry point names to <tt class="docutils literal"><span class="pre">EntryPoint</span></tt> objects. <tt class="docutils literal"><span class="pre">ValueError</span></tt> is
raised if entry point names are duplicated, if <cite>group</cite> is not a valid
entry point group name, or if there are any syntax errors. (Note: the
<cite>group</cite> parameter is used only for validation and to create more
informative error messages.) If <cite>dist</cite> is provided, it will be used to
set the <tt class="docutils literal"><span class="pre">dist</span></tt> attribute of the created <tt class="docutils literal"><span class="pre">EntryPoint</span></tt> objects.</dd>
<dt><tt class="docutils literal"><span class="pre">EntryPoint.parse_map(data,</span> <span class="pre">dist=None)</span></tt> (classmethod)</dt>
<dd>Parse <cite>data</cite> into a dictionary mapping group names to dictionaries mapping
entry point names to <tt class="docutils literal"><span class="pre">EntryPoint</span></tt> objects. If <cite>data</cite> is a dictionary,
then the keys are used as group names and the values are passed to
<tt class="docutils literal"><span class="pre">parse_group()</span></tt> as the <cite>lines</cite> argument. If <cite>data</cite> is a string or
sequence of lines, it is first split into .ini-style sections (using
the <tt class="docutils literal"><span class="pre">split_sections()</span></tt> utility function) and the section names are used
as group names. In either case, the <cite>dist</cite> argument is passed through to
<tt class="docutils literal"><span class="pre">parse_group()</span></tt> so that the entry points will be linked to the specified
distribution.</dd>
</dl>
</div>
<div class="section" id="entrypoint-objects">
<h4><a class="toc-backref" href="#id17"><tt class="docutils literal"><span class="pre">EntryPoint</span></tt> Objects</a><a class="headerlink" href="#entrypoint-objects" title="Permalink to this headline">¶</a></h4>
<p>For simple introspection, <tt class="docutils literal"><span class="pre">EntryPoint</span></tt> objects have attributes that
correspond exactly to the constructor argument names: <tt class="docutils literal"><span class="pre">name</span></tt>,
<tt class="docutils literal"><span class="pre">module_name</span></tt>, <tt class="docutils literal"><span class="pre">attrs</span></tt>, <tt class="docutils literal"><span class="pre">extras</span></tt>, and <tt class="docutils literal"><span class="pre">dist</span></tt> are all available. In
addition, the following methods are provided:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">load(require=True,</span> <span class="pre">env=None,</span> <span class="pre">installer=None)</span></tt></dt>
<dd>Load the entry point, returning the advertised Python object, or raise
<tt class="docutils literal"><span class="pre">ImportError</span></tt> if it cannot be obtained. If <cite>require</cite> is a true value,
then <tt class="docutils literal"><span class="pre">require(env,</span> <span class="pre">installer)</span></tt> is called before attempting the import.</dd>
<dt><tt class="docutils literal"><span class="pre">require(env=None,</span> <span class="pre">installer=None)</span></tt></dt>
<dd>Ensure that any “extras” needed by the entry point are available on
sys.path. <tt class="docutils literal"><span class="pre">UnknownExtra</span></tt> is raised if the <tt class="docutils literal"><span class="pre">EntryPoint</span></tt> has <tt class="docutils literal"><span class="pre">extras</span></tt>,
but no <tt class="docutils literal"><span class="pre">dist</span></tt>, or if the named extras are not defined by the
distribution. If <cite>env</cite> is supplied, it must be an <tt class="docutils literal"><span class="pre">Environment</span></tt>, and it
will be used to search for needed distributions if they are not already
present on sys.path. If <cite>installer</cite> is supplied, it must be a callable
taking a <tt class="docutils literal"><span class="pre">Requirement</span></tt> instance and returning a matching importable
<tt class="docutils literal"><span class="pre">Distribution</span></tt> instance or None.</dd>
<dt><tt class="docutils literal"><span class="pre">__str__()</span></tt></dt>
<dd>The string form of an <tt class="docutils literal"><span class="pre">EntryPoint</span></tt> is a string that could be passed to
<tt class="docutils literal"><span class="pre">EntryPoint.parse()</span></tt> to produce an equivalent <tt class="docutils literal"><span class="pre">EntryPoint</span></tt>.</dd>
</dl>
</div>
</div>
<div class="section" id="distribution-objects">
<h3><a class="toc-backref" href="#id18"><tt class="docutils literal"><span class="pre">Distribution</span></tt> Objects</a><a class="headerlink" href="#distribution-objects" title="Permalink to this headline">¶</a></h3>
<p><tt class="docutils literal"><span class="pre">Distribution</span></tt> objects represent collections of Python code that may or may
not be importable, and may or may not have metadata and resources associated
with them. Their metadata may include information such as what other projects
the distribution depends on, what entry points the distribution advertises, and
so on.</p>
<div class="section" id="getting-or-creating-distributions">
<h4><a class="toc-backref" href="#id19">Getting or Creating Distributions</a><a class="headerlink" href="#getting-or-creating-distributions" title="Permalink to this headline">¶</a></h4>
<p>Most commonly, you’ll obtain <tt class="docutils literal"><span class="pre">Distribution</span></tt> objects from a <tt class="docutils literal"><span class="pre">WorkingSet</span></tt> or
an <tt class="docutils literal"><span class="pre">Environment</span></tt>. (See the sections above on <a class="reference internal" href="#workingset-objects">WorkingSet Objects</a> and
<a class="reference internal" href="#environment-objects">Environment Objects</a>, which are containers for active distributions and
available distributions, respectively.) You can also obtain <tt class="docutils literal"><span class="pre">Distribution</span></tt>
objects from one of these high-level APIs:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">find_distributions(path_item,</span> <span class="pre">only=False)</span></tt></dt>
<dd>Yield distributions accessible via <cite>path_item</cite>. If <cite>only</cite> is true, yield
only distributions whose <tt class="docutils literal"><span class="pre">location</span></tt> is equal to <cite>path_item</cite>. In other
words, if <cite>only</cite> is true, this yields any distributions that would be
importable if <cite>path_item</cite> were on <tt class="docutils literal"><span class="pre">sys.path</span></tt>. If <cite>only</cite> is false, this
also yields distributions that are “in” or “under” <cite>path_item</cite>, but would
not be importable unless their locations were also added to <tt class="docutils literal"><span class="pre">sys.path</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">get_distribution(dist_spec)</span></tt></dt>
<dd>Return a <tt class="docutils literal"><span class="pre">Distribution</span></tt> object for a given <tt class="docutils literal"><span class="pre">Requirement</span></tt> or string.
If <cite>dist_spec</cite> is already a <tt class="docutils literal"><span class="pre">Distribution</span></tt> instance, it is returned.
If it is a <tt class="docutils literal"><span class="pre">Requirement</span></tt> object or a string that can be parsed into one,
it is used to locate and activate a matching distribution, which is then
returned.</dd>
</dl>
<p>However, if you’re creating specialized tools for working with distributions,
or creating a new distribution format, you may also need to create
<tt class="docutils literal"><span class="pre">Distribution</span></tt> objects directly, using one of the three constructors below.</p>
<p>These constructors all take an optional <cite>metadata</cite> argument, which is used to
access any resources or metadata associated with the distribution. <cite>metadata</cite>
must be an object that implements the <tt class="docutils literal"><span class="pre">IResourceProvider</span></tt> interface, or None.
If it is None, an <tt class="docutils literal"><span class="pre">EmptyProvider</span></tt> is used instead. <tt class="docutils literal"><span class="pre">Distribution</span></tt> objects
implement both the <a class="reference internal" href="#iresourceprovider">IResourceProvider</a> and <a class="reference internal" href="#imetadataprovider-methods">IMetadataProvider Methods</a> by
delegating them to the <cite>metadata</cite> object.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">Distribution.from_location(location,</span> <span class="pre">basename,</span> <span class="pre">metadata=None,</span> <span class="pre">**kw)</span></tt> (classmethod)</dt>
<dd>Create a distribution for <cite>location</cite>, which must be a string such as a
URL, filename, or other string that might be used on <tt class="docutils literal"><span class="pre">sys.path</span></tt>.
<cite>basename</cite> is a string naming the distribution, like <tt class="docutils literal"><span class="pre">Foo-1.2-py2.4.egg</span></tt>.
If <cite>basename</cite> ends with <tt class="docutils literal"><span class="pre">.egg</span></tt>, then the project’s name, version, python
version and platform are extracted from the filename and used to set those
properties of the created distribution. Any additional keyword arguments
are forwarded to the <tt class="docutils literal"><span class="pre">Distribution()</span></tt> constructor.</dd>
<dt><tt class="docutils literal"><span class="pre">Distribution.from_filename(filename,</span> <span class="pre">metadata=None**kw)</span></tt> (classmethod)</dt>
<dd>Create a distribution by parsing a local filename. This is a shorter way
of saying <tt class="docutils literal"><span class="pre">Distribution.from_location(normalize_path(filename),</span>
<span class="pre">os.path.basename(filename),</span> <span class="pre">metadata)</span></tt>. In other words, it creates a
distribution whose location is the normalize form of the filename, parsing
name and version information from the base portion of the filename. Any
additional keyword arguments are forwarded to the <tt class="docutils literal"><span class="pre">Distribution()</span></tt>
constructor.</dd>
<dt><tt class="docutils literal"><span class="pre">Distribution(location,metadata,project_name,version,py_version,platform,precedence)</span></tt></dt>
<dd>Create a distribution by setting its properties. All arguments are
optional and default to None, except for <cite>py_version</cite> (which defaults to
the current Python version) and <cite>precedence</cite> (which defaults to
<tt class="docutils literal"><span class="pre">EGG_DIST</span></tt>; for more details see <tt class="docutils literal"><span class="pre">precedence</span></tt> under <a class="reference internal" href="#distribution-attributes">Distribution
Attributes</a> below). Note that it’s usually easier to use the
<tt class="docutils literal"><span class="pre">from_filename()</span></tt> or <tt class="docutils literal"><span class="pre">from_location()</span></tt> constructors than to specify
all these arguments individually.</dd>
</dl>
</div>
<div class="section" id="distribution-attributes">
<h4><a class="toc-backref" href="#id20"><tt class="docutils literal"><span class="pre">Distribution</span></tt> Attributes</a><a class="headerlink" href="#distribution-attributes" title="Permalink to this headline">¶</a></h4>
<dl class="docutils">
<dt>location</dt>
<dd>A string indicating the distribution’s location. For an importable
distribution, this is the string that would be added to <tt class="docutils literal"><span class="pre">sys.path</span></tt> to
make it actively importable. For non-importable distributions, this is
simply a filename, URL, or other way of locating the distribution.</dd>
<dt>project_name</dt>
<dd>A string, naming the project that this distribution is for. Project names
are defined by a project’s setup script, and they are used to identify
projects on PyPI. When a <tt class="docutils literal"><span class="pre">Distribution</span></tt> is constructed, the
<cite>project_name</cite> argument is passed through the <tt class="docutils literal"><span class="pre">safe_name()</span></tt> utility
function to filter out any unacceptable characters.</dd>
<dt>key</dt>
<dd><tt class="docutils literal"><span class="pre">dist.key</span></tt> is short for <tt class="docutils literal"><span class="pre">dist.project_name.lower()</span></tt>. It’s used for
case-insensitive comparison and indexing of distributions by project name.</dd>
<dt>extras</dt>
<dd>A list of strings, giving the names of extra features defined by the
project’s dependency list (the <tt class="docutils literal"><span class="pre">extras_require</span></tt> argument specified in
the project’s setup script).</dd>
<dt>version</dt>
<dd>A string denoting what release of the project this distribution contains.
When a <tt class="docutils literal"><span class="pre">Distribution</span></tt> is constructed, the <cite>version</cite> argument is passed
through the <tt class="docutils literal"><span class="pre">safe_version()</span></tt> utility function to filter out any
unacceptable characters. If no <cite>version</cite> is specified at construction
time, then attempting to access this attribute later will cause the
<tt class="docutils literal"><span class="pre">Distribution</span></tt> to try to discover its version by reading its <tt class="docutils literal"><span class="pre">PKG-INFO</span></tt>
metadata file. If <tt class="docutils literal"><span class="pre">PKG-INFO</span></tt> is unavailable or can’t be parsed,
<tt class="docutils literal"><span class="pre">ValueError</span></tt> is raised.</dd>
<dt>parsed_version</dt>
<dd>The <tt class="docutils literal"><span class="pre">parsed_version</span></tt> is a tuple representing a “parsed” form of the
distribution’s <tt class="docutils literal"><span class="pre">version</span></tt>. <tt class="docutils literal"><span class="pre">dist.parsed_version</span></tt> is a shortcut for
calling <tt class="docutils literal"><span class="pre">parse_version(dist.version)</span></tt>. It is used to compare or sort
distributions by version. (See the <a class="reference internal" href="#parsing-utilities">Parsing Utilities</a> section below for
more information on the <tt class="docutils literal"><span class="pre">parse_version()</span></tt> function.) Note that accessing
<tt class="docutils literal"><span class="pre">parsed_version</span></tt> may result in a <tt class="docutils literal"><span class="pre">ValueError</span></tt> if the <tt class="docutils literal"><span class="pre">Distribution</span></tt>
was constructed without a <cite>version</cite> and without <cite>metadata</cite> capable of
supplying the missing version info.</dd>
<dt>py_version</dt>
<dd>The major/minor Python version the distribution supports, as a string.
For example, “2.7” or “3.4”. The default is the current version of Python.</dd>
<dt>platform</dt>
<dd>A string representing the platform the distribution is intended for, or
<tt class="docutils literal"><span class="pre">None</span></tt> if the distribution is “pure Python” and therefore cross-platform.
See <a class="reference internal" href="#platform-utilities">Platform Utilities</a> below for more information on platform strings.</dd>
<dt>precedence</dt>
<dd>A distribution’s <tt class="docutils literal"><span class="pre">precedence</span></tt> is used to determine the relative order of
two distributions that have the same <tt class="docutils literal"><span class="pre">project_name</span></tt> and
<tt class="docutils literal"><span class="pre">parsed_version</span></tt>. The default precedence is <tt class="docutils literal"><span class="pre">pkg_resources.EGG_DIST</span></tt>,
which is the highest (i.e. most preferred) precedence. The full list
of predefined precedences, from most preferred to least preferred, is:
<tt class="docutils literal"><span class="pre">EGG_DIST</span></tt>, <tt class="docutils literal"><span class="pre">BINARY_DIST</span></tt>, <tt class="docutils literal"><span class="pre">SOURCE_DIST</span></tt>, <tt class="docutils literal"><span class="pre">CHECKOUT_DIST</span></tt>, and
<tt class="docutils literal"><span class="pre">DEVELOP_DIST</span></tt>. Normally, precedences other than <tt class="docutils literal"><span class="pre">EGG_DIST</span></tt> are used
only by the <tt class="docutils literal"><span class="pre">setuptools.package_index</span></tt> module, when sorting distributions
found in a package index to determine their suitability for installation.
“System” and “Development” eggs (i.e., ones that use the <tt class="docutils literal"><span class="pre">.egg-info</span></tt>
format), however, are automatically given a precedence of <tt class="docutils literal"><span class="pre">DEVELOP_DIST</span></tt>.</dd>
</dl>
</div>
<div class="section" id="distribution-methods">
<h4><a class="toc-backref" href="#id21"><tt class="docutils literal"><span class="pre">Distribution</span></tt> Methods</a><a class="headerlink" href="#distribution-methods" title="Permalink to this headline">¶</a></h4>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">activate(path=None)</span></tt></dt>
<dd><p class="first">Ensure distribution is importable on <cite>path</cite>. If <cite>path</cite> is None,
<tt class="docutils literal"><span class="pre">sys.path</span></tt> is used instead. This ensures that the distribution’s
<tt class="docutils literal"><span class="pre">location</span></tt> is in the <cite>path</cite> list, and it also performs any necessary
namespace package fixups or declarations. (That is, if the distribution
contains namespace packages, this method ensures that they are declared,
and that the distribution’s contents for those namespace packages are
merged with the contents provided by any other active distributions. See
the section above on <a class="reference internal" href="#namespace-package-support">Namespace Package Support</a> for more information.)</p>
<p class="last"><tt class="docutils literal"><span class="pre">pkg_resources</span></tt> adds a notification callback to the global <tt class="docutils literal"><span class="pre">working_set</span></tt>
that ensures this method is called whenever a distribution is added to it.
Therefore, you should not normally need to explicitly call this method.
(Note that this means that namespace packages on <tt class="docutils literal"><span class="pre">sys.path</span></tt> are always
imported as soon as <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> is, which is another reason why
namespace packages should not contain any code or import statements.)</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">as_requirement()</span></tt></dt>
<dd>Return a <tt class="docutils literal"><span class="pre">Requirement</span></tt> instance that matches this distribution’s project
name and version.</dd>
<dt><tt class="docutils literal"><span class="pre">requires(extras=())</span></tt></dt>
<dd>List the <tt class="docutils literal"><span class="pre">Requirement</span></tt> objects that specify this distribution’s
dependencies. If <cite>extras</cite> is specified, it should be a sequence of names
of “extras” defined by the distribution, and the list returned will then
include any dependencies needed to support the named “extras”.</dd>
<dt><tt class="docutils literal"><span class="pre">clone(**kw)</span></tt></dt>
<dd>Create a copy of the distribution. Any supplied keyword arguments override
the corresponding argument to the <tt class="docutils literal"><span class="pre">Distribution()</span></tt> constructor, allowing
you to change some of the copied distribution’s attributes.</dd>
<dt><tt class="docutils literal"><span class="pre">egg_name()</span></tt></dt>
<dd>Return what this distribution’s standard filename should be, not including
the ”.egg” extension. For example, a distribution for project “Foo”
version 1.2 that runs on Python 2.3 for Windows would have an <tt class="docutils literal"><span class="pre">egg_name()</span></tt>
of <tt class="docutils literal"><span class="pre">Foo-1.2-py2.3-win32</span></tt>. Any dashes in the name or version are
converted to underscores. (<tt class="docutils literal"><span class="pre">Distribution.from_location()</span></tt> will convert
them back when parsing a ”.egg” file name.)</dd>
<dt><tt class="docutils literal"><span class="pre">__cmp__(other)</span></tt>, <tt class="docutils literal"><span class="pre">__hash__()</span></tt></dt>
<dd>Distribution objects are hashed and compared on the basis of their parsed
version and precedence, followed by their key (lowercase project name),
location, Python version, and platform.</dd>
</dl>
<p>The following methods are used to access <tt class="docutils literal"><span class="pre">EntryPoint</span></tt> objects advertised
by the distribution. See the section above on <a class="reference internal" href="#entry-points">Entry Points</a> for more
detailed information about these operations:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">get_entry_info(group,</span> <span class="pre">name)</span></tt></dt>
<dd>Return the <tt class="docutils literal"><span class="pre">EntryPoint</span></tt> object for <cite>group</cite> and <cite>name</cite>, or None if no
such point is advertised by this distribution.</dd>
<dt><tt class="docutils literal"><span class="pre">get_entry_map(group=None)</span></tt></dt>
<dd>Return the entry point map for <cite>group</cite>. If <cite>group</cite> is None, return
a dictionary mapping group names to entry point maps for all groups.
(An entry point map is a dictionary of entry point names to <tt class="docutils literal"><span class="pre">EntryPoint</span></tt>
objects.)</dd>
<dt><tt class="docutils literal"><span class="pre">load_entry_point(group,</span> <span class="pre">name)</span></tt></dt>
<dd>Short for <tt class="docutils literal"><span class="pre">get_entry_info(group,</span> <span class="pre">name).load()</span></tt>. Returns the object
advertised by the named entry point, or raises <tt class="docutils literal"><span class="pre">ImportError</span></tt> if
the entry point isn’t advertised by this distribution, or there is some
other import problem.</dd>
</dl>
<p>In addition to the above methods, <tt class="docutils literal"><span class="pre">Distribution</span></tt> objects also implement all
of the <a class="reference internal" href="#iresourceprovider">IResourceProvider</a> and <a class="reference internal" href="#imetadataprovider-methods">IMetadataProvider Methods</a> (which are
documented in later sections):</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">has_metadata(name)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">metadata_isdir(name)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">metadata_listdir(name)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">get_metadata(name)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">get_metadata_lines(name)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">run_script(script_name,</span> <span class="pre">namespace)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">get_resource_filename(manager,</span> <span class="pre">resource_name)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">get_resource_stream(manager,</span> <span class="pre">resource_name)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">get_resource_string(manager,</span> <span class="pre">resource_name)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">has_resource(resource_name)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">resource_isdir(resource_name)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">resource_listdir(resource_name)</span></tt></li>
</ul>
<p>If the distribution was created with a <cite>metadata</cite> argument, these resource and
metadata access methods are all delegated to that <cite>metadata</cite> provider.
Otherwise, they are delegated to an <tt class="docutils literal"><span class="pre">EmptyProvider</span></tt>, so that the distribution
will appear to have no resources or metadata. This delegation approach is used
so that supporting custom importers or new distribution formats can be done
simply by creating an appropriate <a class="reference internal" href="#iresourceprovider">IResourceProvider</a> implementation; see the
section below on <a class="reference internal" href="#supporting-custom-importers">Supporting Custom Importers</a> for more details.</p>
</div>
</div>
<div class="section" id="resourcemanager-api">
<h3><a class="toc-backref" href="#id22"><tt class="docutils literal"><span class="pre">ResourceManager</span></tt> API</a><a class="headerlink" href="#resourcemanager-api" title="Permalink to this headline">¶</a></h3>
<p>The <tt class="docutils literal"><span class="pre">ResourceManager</span></tt> class provides uniform access to package resources,
whether those resources exist as files and directories or are compressed in
an archive of some kind.</p>
<p>Normally, you do not need to create or explicitly manage <tt class="docutils literal"><span class="pre">ResourceManager</span></tt>
instances, as the <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> module creates a global instance for you,
and makes most of its methods available as top-level names in the
<tt class="docutils literal"><span class="pre">pkg_resources</span></tt> module namespace. So, for example, this code actually
calls the <tt class="docutils literal"><span class="pre">resource_string()</span></tt> method of the global <tt class="docutils literal"><span class="pre">ResourceManager</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">pkg_resources</span>
<span class="n">my_data</span> <span class="o">=</span> <span class="n">pkg_resources</span><span class="o">.</span><span class="n">resource_string</span><span class="p">(</span><span class="n">__name__</span><span class="p">,</span> <span class="s">"foo.dat"</span><span class="p">)</span>
</pre></div>
</div>
<p>Thus, you can use the APIs below without needing an explicit
<tt class="docutils literal"><span class="pre">ResourceManager</span></tt> instance; just import and use them as needed.</p>
<div class="section" id="basic-resource-access">
<h4><a class="toc-backref" href="#id23">Basic Resource Access</a><a class="headerlink" href="#basic-resource-access" title="Permalink to this headline">¶</a></h4>
<p>In the following methods, the <cite>package_or_requirement</cite> argument may be either
a Python package/module name (e.g. <tt class="docutils literal"><span class="pre">foo.bar</span></tt>) or a <tt class="docutils literal"><span class="pre">Requirement</span></tt> instance.
If it is a package or module name, the named module or package must be
importable (i.e., be in a distribution or directory on <tt class="docutils literal"><span class="pre">sys.path</span></tt>), and the
<cite>resource_name</cite> argument is interpreted relative to the named package. (Note
that if a module name is used, then the resource name is relative to the
package immediately containing the named module. Also, you should not use use
a namespace package name, because a namespace package can be spread across
multiple distributions, and is therefore ambiguous as to which distribution
should be searched for the resource.)</p>
<p>If it is a <tt class="docutils literal"><span class="pre">Requirement</span></tt>, then the requirement is automatically resolved
(searching the current <tt class="docutils literal"><span class="pre">Environment</span></tt> if necessary) and a matching
distribution is added to the <tt class="docutils literal"><span class="pre">WorkingSet</span></tt> and <tt class="docutils literal"><span class="pre">sys.path</span></tt> if one was not
already present. (Unless the <tt class="docutils literal"><span class="pre">Requirement</span></tt> can’t be satisfied, in which
case an exception is raised.) The <cite>resource_name</cite> argument is then interpreted
relative to the root of the identified distribution; i.e. its first path
segment will be treated as a peer of the top-level modules or packages in the
distribution.</p>
<p>Note that resource names must be <tt class="docutils literal"><span class="pre">/</span></tt>-separated paths and cannot be absolute
(i.e. no leading <tt class="docutils literal"><span class="pre">/</span></tt>) or contain relative names like <tt class="docutils literal"><span class="pre">".."</span></tt>. Do <em>not</em> use
<tt class="docutils literal"><span class="pre">os.path</span></tt> routines to manipulate resource paths, as they are <em>not</em> filesystem
paths.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">resource_exists(package_or_requirement,</span> <span class="pre">resource_name)</span></tt></dt>
<dd>Does the named resource exist? Return <tt class="docutils literal"><span class="pre">True</span></tt> or <tt class="docutils literal"><span class="pre">False</span></tt> accordingly.</dd>
<dt><tt class="docutils literal"><span class="pre">resource_stream(package_or_requirement,</span> <span class="pre">resource_name)</span></tt></dt>
<dd>Return a readable file-like object for the specified resource; it may be
an actual file, a <tt class="docutils literal"><span class="pre">StringIO</span></tt>, or some similar object. The stream is
in “binary mode”, in the sense that whatever bytes are in the resource
will be read as-is.</dd>
<dt><tt class="docutils literal"><span class="pre">resource_string(package_or_requirement,</span> <span class="pre">resource_name)</span></tt></dt>
<dd>Return the specified resource as a string. The resource is read in
binary fashion, such that the returned string contains exactly the bytes
that are stored in the resource.</dd>
<dt><tt class="docutils literal"><span class="pre">resource_isdir(package_or_requirement,</span> <span class="pre">resource_name)</span></tt></dt>
<dd>Is the named resource a directory? Return <tt class="docutils literal"><span class="pre">True</span></tt> or <tt class="docutils literal"><span class="pre">False</span></tt>
accordingly.</dd>
<dt><tt class="docutils literal"><span class="pre">resource_listdir(package_or_requirement,</span> <span class="pre">resource_name)</span></tt></dt>
<dd>List the contents of the named resource directory, just like <tt class="docutils literal"><span class="pre">os.listdir</span></tt>
except that it works even if the resource is in a zipfile.</dd>
</dl>
<p>Note that only <tt class="docutils literal"><span class="pre">resource_exists()</span></tt> and <tt class="docutils literal"><span class="pre">resource_isdir()</span></tt> are insensitive
as to the resource type. You cannot use <tt class="docutils literal"><span class="pre">resource_listdir()</span></tt> on a file
resource, and you can’t use <tt class="docutils literal"><span class="pre">resource_string()</span></tt> or <tt class="docutils literal"><span class="pre">resource_stream()</span></tt> on
directory resources. Using an inappropriate method for the resource type may
result in an exception or undefined behavior, depending on the platform and
distribution format involved.</p>
</div>
<div class="section" id="resource-extraction">
<h4><a class="toc-backref" href="#id24">Resource Extraction</a><a class="headerlink" href="#resource-extraction" title="Permalink to this headline">¶</a></h4>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">resource_filename(package_or_requirement,</span> <span class="pre">resource_name)</span></tt></dt>
<dd><p class="first">Sometimes, it is not sufficient to access a resource in string or stream
form, and a true filesystem filename is needed. In such cases, you can
use this method (or module-level function) to obtain a filename for a
resource. If the resource is in an archive distribution (such as a zipped
egg), it will be extracted to a cache directory, and the filename within
the cache will be returned. If the named resource is a directory, then
all resources within that directory (including subdirectories) are also
extracted. If the named resource is a C extension or “eager resource”
(see the <tt class="docutils literal"><span class="pre">setuptools</span></tt> documentation for details), then all C extensions
and eager resources are extracted at the same time.</p>
<p class="last">Archived resources are extracted to a cache location that can be managed by
the following two methods:</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">set_extraction_path(path)</span></tt></dt>
<dd><p class="first">Set the base path where resources will be extracted to, if needed.</p>
<p>If you do not call this routine before any extractions take place, the
path defaults to the return value of <tt class="docutils literal"><span class="pre">get_default_cache()</span></tt>. (Which is
based on the <tt class="docutils literal"><span class="pre">PYTHON_EGG_CACHE</span></tt> environment variable, with various
platform-specific fallbacks. See that routine’s documentation for more
details.)</p>
<p>Resources are extracted to subdirectories of this path based upon
information given by the resource provider. You may set this to a
temporary directory, but then you must call <tt class="docutils literal"><span class="pre">cleanup_resources()</span></tt> to
delete the extracted files when done. There is no guarantee that
<tt class="docutils literal"><span class="pre">cleanup_resources()</span></tt> will be able to remove all extracted files. (On
Windows, for example, you can’t unlink .pyd or .dll files that are still
in use.)</p>
<p class="last">Note that you may not change the extraction path for a given resource
manager once resources have been extracted, unless you first call
<tt class="docutils literal"><span class="pre">cleanup_resources()</span></tt>.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">cleanup_resources(force=False)</span></tt></dt>
<dd>Delete all extracted resource files and directories, returning a list
of the file and directory names that could not be successfully removed.
This function does not have any concurrency protection, so it should
generally only be called when the extraction path is a temporary
directory exclusive to a single process. This method is not
automatically called; you must call it explicitly or register it as an
<tt class="docutils literal"><span class="pre">atexit</span></tt> function if you wish to ensure cleanup of a temporary
directory used for extractions.</dd>
</dl>
</div>
<div class="section" id="provider-interface">
<h4><a class="toc-backref" href="#id25">“Provider” Interface</a><a class="headerlink" href="#provider-interface" title="Permalink to this headline">¶</a></h4>
<p>If you are implementing an <tt class="docutils literal"><span class="pre">IResourceProvider</span></tt> and/or <tt class="docutils literal"><span class="pre">IMetadataProvider</span></tt>
for a new distribution archive format, you may need to use the following
<tt class="docutils literal"><span class="pre">IResourceManager</span></tt> methods to co-ordinate extraction of resources to the
filesystem. If you’re not implementing an archive format, however, you have
no need to use these methods. Unlike the other methods listed above, they are
<em>not</em> available as top-level functions tied to the global <tt class="docutils literal"><span class="pre">ResourceManager</span></tt>;
you must therefore have an explicit <tt class="docutils literal"><span class="pre">ResourceManager</span></tt> instance to use them.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">get_cache_path(archive_name,</span> <span class="pre">names=())</span></tt></dt>
<dd><p class="first">Return absolute location in cache for <cite>archive_name</cite> and <cite>names</cite></p>
<p>The parent directory of the resulting path will be created if it does
not already exist. <cite>archive_name</cite> should be the base filename of the
enclosing egg (which may not be the name of the enclosing zipfile!),
including its ”.egg” extension. <cite>names</cite>, if provided, should be a
sequence of path name parts “under” the egg’s extraction location.</p>
<p class="last">This method should only be called by resource providers that need to
obtain an extraction location, and only for names they intend to
extract, as it tracks the generated names for possible cleanup later.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">extraction_error()</span></tt></dt>
<dd>Raise an <tt class="docutils literal"><span class="pre">ExtractionError</span></tt> describing the active exception as interfering
with the extraction process. You should call this if you encounter any
OS errors extracting the file to the cache path; it will format the
operating system exception for you, and add other information to the
<tt class="docutils literal"><span class="pre">ExtractionError</span></tt> instance that may be needed by programs that want to
wrap or handle extraction errors themselves.</dd>
<dt><tt class="docutils literal"><span class="pre">postprocess(tempname,</span> <span class="pre">filename)</span></tt></dt>
<dd><p class="first">Perform any platform-specific postprocessing of <cite>tempname</cite>.
Resource providers should call this method ONLY after successfully
extracting a compressed resource. They must NOT call it on resources
that are already in the filesystem.</p>
<p class="last"><cite>tempname</cite> is the current (temporary) name of the file, and <cite>filename</cite>
is the name it will be renamed to by the caller after this routine
returns.</p>
</dd>
</dl>
</div>
</div>
<div class="section" id="metadata-api">
<h3><a class="toc-backref" href="#id26">Metadata API</a><a class="headerlink" href="#metadata-api" title="Permalink to this headline">¶</a></h3>
<p>The metadata API is used to access metadata resources bundled in a pluggable
distribution. Metadata resources are virtual files or directories containing
information about the distribution, such as might be used by an extensible
application or framework to connect “plugins”. Like other kinds of resources,
metadata resource names are <tt class="docutils literal"><span class="pre">/</span></tt>-separated and should not contain <tt class="docutils literal"><span class="pre">..</span></tt> or
begin with a <tt class="docutils literal"><span class="pre">/</span></tt>. You should not use <tt class="docutils literal"><span class="pre">os.path</span></tt> routines to manipulate
resource paths.</p>
<p>The metadata API is provided by objects implementing the <tt class="docutils literal"><span class="pre">IMetadataProvider</span></tt>
or <tt class="docutils literal"><span class="pre">IResourceProvider</span></tt> interfaces. <tt class="docutils literal"><span class="pre">Distribution</span></tt> objects implement this
interface, as do objects returned by the <tt class="docutils literal"><span class="pre">get_provider()</span></tt> function:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">get_provider(package_or_requirement)</span></tt></dt>
<dd><p class="first">If a package name is supplied, return an <tt class="docutils literal"><span class="pre">IResourceProvider</span></tt> for the
package. If a <tt class="docutils literal"><span class="pre">Requirement</span></tt> is supplied, resolve it by returning a
<tt class="docutils literal"><span class="pre">Distribution</span></tt> from the current working set (searching the current
<tt class="docutils literal"><span class="pre">Environment</span></tt> if necessary and adding the newly found <tt class="docutils literal"><span class="pre">Distribution</span></tt>
to the working set). If the named package can’t be imported, or the
<tt class="docutils literal"><span class="pre">Requirement</span></tt> can’t be satisfied, an exception is raised.</p>
<p class="last">NOTE: if you use a package name rather than a <tt class="docutils literal"><span class="pre">Requirement</span></tt>, the object
you get back may not be a pluggable distribution, depending on the method
by which the package was installed. In particular, “development” packages
and “single-version externally-managed” packages do not have any way to
map from a package name to the corresponding project’s metadata. Do not
write code that passes a package name to <tt class="docutils literal"><span class="pre">get_provider()</span></tt> and then tries
to retrieve project metadata from the returned object. It may appear to
work when the named package is in an <tt class="docutils literal"><span class="pre">.egg</span></tt> file or directory, but
it will fail in other installation scenarios. If you want project
metadata, you need to ask for a <em>project</em>, not a package.</p>
</dd>
</dl>
<div class="section" id="imetadataprovider-methods">
<h4><a class="toc-backref" href="#id27"><tt class="docutils literal"><span class="pre">IMetadataProvider</span></tt> Methods</a><a class="headerlink" href="#imetadataprovider-methods" title="Permalink to this headline">¶</a></h4>
<p>The methods provided by objects (such as <tt class="docutils literal"><span class="pre">Distribution</span></tt> instances) that
implement the <tt class="docutils literal"><span class="pre">IMetadataProvider</span></tt> or <tt class="docutils literal"><span class="pre">IResourceProvider</span></tt> interfaces are:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">has_metadata(name)</span></tt></dt>
<dd>Does the named metadata resource exist?</dd>
<dt><tt class="docutils literal"><span class="pre">metadata_isdir(name)</span></tt></dt>
<dd>Is the named metadata resource a directory?</dd>
<dt><tt class="docutils literal"><span class="pre">metadata_listdir(name)</span></tt></dt>
<dd>List of metadata names in the directory (like <tt class="docutils literal"><span class="pre">os.listdir()</span></tt>)</dd>
<dt><tt class="docutils literal"><span class="pre">get_metadata(name)</span></tt></dt>
<dd>Return the named metadata resource as a string. The data is read in binary
mode; i.e., the exact bytes of the resource file are returned.</dd>
<dt><tt class="docutils literal"><span class="pre">get_metadata_lines(name)</span></tt></dt>
<dd>Yield named metadata resource as list of non-blank non-comment lines. This
is short for calling <tt class="docutils literal"><span class="pre">yield_lines(provider.get_metadata(name))</span></tt>. See the
section on <a class="reference internal" href="#yield-lines">yield_lines()</a> below for more information on the syntax it
recognizes.</dd>
<dt><tt class="docutils literal"><span class="pre">run_script(script_name,</span> <span class="pre">namespace)</span></tt></dt>
<dd>Execute the named script in the supplied namespace dictionary. Raises
<tt class="docutils literal"><span class="pre">ResolutionError</span></tt> if there is no script by that name in the <tt class="docutils literal"><span class="pre">scripts</span></tt>
metadata directory. <cite>namespace</cite> should be a Python dictionary, usually
a module dictionary if the script is being run as a module.</dd>
</dl>
</div>
</div>
<div class="section" id="exceptions">
<h3><a class="toc-backref" href="#id28">Exceptions</a><a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h3>
<p><tt class="docutils literal"><span class="pre">pkg_resources</span></tt> provides a simple exception hierarchy for problems that may
occur when processing requests to locate and activate packages:</p>
<div class="highlight-python"><div class="highlight"><pre>ResolutionError
DistributionNotFound
VersionConflict
UnknownExtra
ExtractionError
</pre></div>
</div>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">ResolutionError</span></tt></dt>
<dd>This class is used as a base class for the other three exceptions, so that
you can catch all of them with a single “except” clause. It is also raised
directly for miscellaneous requirement-resolution problems like trying to
run a script that doesn’t exist in the distribution it was requested from.</dd>
<dt><tt class="docutils literal"><span class="pre">DistributionNotFound</span></tt></dt>
<dd>A distribution needed to fulfill a requirement could not be found.</dd>
<dt><tt class="docutils literal"><span class="pre">VersionConflict</span></tt></dt>
<dd>The requested version of a project conflicts with an already-activated
version of the same project.</dd>
<dt><tt class="docutils literal"><span class="pre">UnknownExtra</span></tt></dt>
<dd>One of the “extras” requested was not recognized by the distribution it
was requested from.</dd>
<dt><tt class="docutils literal"><span class="pre">ExtractionError</span></tt></dt>
<dd><p class="first">A problem occurred extracting a resource to the Python Egg cache. The
following attributes are available on instances of this exception:</p>
<dl class="last docutils">
<dt>manager</dt>
<dd>The resource manager that raised this exception</dd>
<dt>cache_path</dt>
<dd>The base directory for resource extraction</dd>
<dt>original_error</dt>
<dd>The exception instance that caused extraction to fail</dd>
</dl>
</dd>
</dl>
</div>
<div class="section" id="supporting-custom-importers">
<h3><a class="toc-backref" href="#id29">Supporting Custom Importers</a><a class="headerlink" href="#supporting-custom-importers" title="Permalink to this headline">¶</a></h3>
<p>By default, <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> supports normal filesystem imports, and
<tt class="docutils literal"><span class="pre">zipimport</span></tt> importers. If you wish to use the <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> features
with other (PEP 302-compatible) importers or module loaders, you may need to
register various handlers and support functions using these APIs:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">register_finder(importer_type,</span> <span class="pre">distribution_finder)</span></tt></dt>
<dd><p class="first">Register <cite>distribution_finder</cite> to find distributions in <tt class="docutils literal"><span class="pre">sys.path</span></tt> items.
<cite>importer_type</cite> is the type or class of a PEP 302 “Importer” (<tt class="docutils literal"><span class="pre">sys.path</span></tt>
item handler), and <cite>distribution_finder</cite> is a callable that, when passed a
path item, the importer instance, and an <cite>only</cite> flag, yields
<tt class="docutils literal"><span class="pre">Distribution</span></tt> instances found under that path item. (The <cite>only</cite> flag,
if true, means the finder should yield only <tt class="docutils literal"><span class="pre">Distribution</span></tt> objects whose
<tt class="docutils literal"><span class="pre">location</span></tt> is equal to the path item provided.)</p>
<p class="last">See the source of the <tt class="docutils literal"><span class="pre">pkg_resources.find_on_path</span></tt> function for an
example finder function.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">register_loader_type(loader_type,</span> <span class="pre">provider_factory)</span></tt></dt>
<dd>Register <cite>provider_factory</cite> to make <tt class="docutils literal"><span class="pre">IResourceProvider</span></tt> objects for
<cite>loader_type</cite>. <cite>loader_type</cite> is the type or class of a PEP 302
<tt class="docutils literal"><span class="pre">module.__loader__</span></tt>, and <cite>provider_factory</cite> is a function that, when
passed a module object, returns an <a class="reference internal" href="#iresourceprovider">IResourceProvider</a> for that module,
allowing it to be used with the <a class="reference internal" href="#resourcemanager-api">ResourceManager API</a>.</dd>
<dt><tt class="docutils literal"><span class="pre">register_namespace_handler(importer_type,</span> <span class="pre">namespace_handler)</span></tt></dt>
<dd><p class="first">Register <cite>namespace_handler</cite> to declare namespace packages for the given
<cite>importer_type</cite>. <cite>importer_type</cite> is the type or class of a PEP 302
“importer” (sys.path item handler), and <cite>namespace_handler</cite> is a callable
with a signature like this:</p>
<div class="highlight-python"><div class="highlight"><pre>def namespace_handler(importer, path_entry, moduleName, module):
# return a path_entry to use for child packages
</pre></div>
</div>
<p>Namespace handlers are only called if the relevant importer object has
already agreed that it can handle the relevant path item. The handler
should only return a subpath if the module <tt class="docutils literal"><span class="pre">__path__</span></tt> does not already
contain an equivalent subpath. Otherwise, it should return None.</p>
<p class="last">For an example namespace handler, see the source of the
<tt class="docutils literal"><span class="pre">pkg_resources.file_ns_handler</span></tt> function, which is used for both zipfile
importing and regular importing.</p>
</dd>
</dl>
<div class="section" id="iresourceprovider">
<h4><a class="toc-backref" href="#id30">IResourceProvider</a><a class="headerlink" href="#iresourceprovider" title="Permalink to this headline">¶</a></h4>
<p><tt class="docutils literal"><span class="pre">IResourceProvider</span></tt> is an abstract class that documents what methods are
required of objects returned by a <cite>provider_factory</cite> registered with
<tt class="docutils literal"><span class="pre">register_loader_type()</span></tt>. <tt class="docutils literal"><span class="pre">IResourceProvider</span></tt> is a subclass of
<tt class="docutils literal"><span class="pre">IMetadataProvider</span></tt>, so objects that implement this interface must also
implement all of the <a class="reference internal" href="#imetadataprovider-methods">IMetadataProvider Methods</a> as well as the methods
shown here. The <cite>manager</cite> argument to the methods below must be an object
that supports the full <a class="reference internal" href="#resourcemanager-api">ResourceManager API</a> documented above.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">get_resource_filename(manager,</span> <span class="pre">resource_name)</span></tt></dt>
<dd>Return a true filesystem path for <cite>resource_name</cite>, co-ordinating the
extraction with <cite>manager</cite>, if the resource must be unpacked to the
filesystem.</dd>
<dt><tt class="docutils literal"><span class="pre">get_resource_stream(manager,</span> <span class="pre">resource_name)</span></tt></dt>
<dd>Return a readable file-like object for <cite>resource_name</cite>.</dd>
<dt><tt class="docutils literal"><span class="pre">get_resource_string(manager,</span> <span class="pre">resource_name)</span></tt></dt>
<dd>Return a string containing the contents of <cite>resource_name</cite>.</dd>
<dt><tt class="docutils literal"><span class="pre">has_resource(resource_name)</span></tt></dt>
<dd>Does the package contain the named resource?</dd>
<dt><tt class="docutils literal"><span class="pre">resource_isdir(resource_name)</span></tt></dt>
<dd>Is the named resource a directory? Return a false value if the resource
does not exist or is not a directory.</dd>
<dt><tt class="docutils literal"><span class="pre">resource_listdir(resource_name)</span></tt></dt>
<dd>Return a list of the contents of the resource directory, ala
<tt class="docutils literal"><span class="pre">os.listdir()</span></tt>. Requesting the contents of a non-existent directory may
raise an exception.</dd>
</dl>
<p>Note, by the way, that your provider classes need not (and should not) subclass
<tt class="docutils literal"><span class="pre">IResourceProvider</span></tt> or <tt class="docutils literal"><span class="pre">IMetadataProvider</span></tt>! These classes exist solely
for documentation purposes and do not provide any useful implementation code.
You may instead wish to subclass one of the <a class="reference internal" href="#built-in-resource-providers">built-in resource providers</a>.</p>
</div>
<div class="section" id="built-in-resource-providers">
<h4><a class="toc-backref" href="#id31">Built-in Resource Providers</a><a class="headerlink" href="#built-in-resource-providers" title="Permalink to this headline">¶</a></h4>
<p><tt class="docutils literal"><span class="pre">pkg_resources</span></tt> includes several provider classes that are automatically used
where appropriate. Their inheritance tree looks like this:</p>
<div class="highlight-python"><div class="highlight"><pre>NullProvider
EggProvider
DefaultProvider
PathMetadata
ZipProvider
EggMetadata
EmptyProvider
FileMetadata
</pre></div>
</div>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">NullProvider</span></tt></dt>
<dd>This provider class is just an abstract base that provides for common
provider behaviors (such as running scripts), given a definition for just
a few abstract methods.</dd>
<dt><tt class="docutils literal"><span class="pre">EggProvider</span></tt></dt>
<dd>This provider class adds in some egg-specific features that are common
to zipped and unzipped eggs.</dd>
<dt><tt class="docutils literal"><span class="pre">DefaultProvider</span></tt></dt>
<dd>This provider class is used for unpacked eggs and “plain old Python”
filesystem modules.</dd>
<dt><tt class="docutils literal"><span class="pre">ZipProvider</span></tt></dt>
<dd>This provider class is used for all zipped modules, whether they are eggs
or not.</dd>
<dt><tt class="docutils literal"><span class="pre">EmptyProvider</span></tt></dt>
<dd>This provider class always returns answers consistent with a provider that
has no metadata or resources. <tt class="docutils literal"><span class="pre">Distribution</span></tt> objects created without
a <tt class="docutils literal"><span class="pre">metadata</span></tt> argument use an instance of this provider class instead.
Since all <tt class="docutils literal"><span class="pre">EmptyProvider</span></tt> instances are equivalent, there is no need
to have more than one instance. <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> therefore creates a
global instance of this class under the name <tt class="docutils literal"><span class="pre">empty_provider</span></tt>, and you
may use it if you have need of an <tt class="docutils literal"><span class="pre">EmptyProvider</span></tt> instance.</dd>
<dt><tt class="docutils literal"><span class="pre">PathMetadata(path,</span> <span class="pre">egg_info)</span></tt></dt>
<dd>Create an <tt class="docutils literal"><span class="pre">IResourceProvider</span></tt> for a filesystem-based distribution, where
<cite>path</cite> is the filesystem location of the importable modules, and <cite>egg_info</cite>
is the filesystem location of the distribution’s metadata directory.
<cite>egg_info</cite> should usually be the <tt class="docutils literal"><span class="pre">EGG-INFO</span></tt> subdirectory of <cite>path</cite> for an
“unpacked egg”, and a <tt class="docutils literal"><span class="pre">ProjectName.egg-info</span></tt> subdirectory of <cite>path</cite> for
a “development egg”. However, other uses are possible for custom purposes.</dd>
<dt><tt class="docutils literal"><span class="pre">EggMetadata(zipimporter)</span></tt></dt>
<dd>Create an <tt class="docutils literal"><span class="pre">IResourceProvider</span></tt> for a zipfile-based distribution. The
<cite>zipimporter</cite> should be a <tt class="docutils literal"><span class="pre">zipimport.zipimporter</span></tt> instance, and may
represent a “basket” (a zipfile containing multiple ”.egg” subdirectories)
a specific egg <em>within</em> a basket, or a zipfile egg (where the zipfile
itself is a ”.egg”). It can also be a combination, such as a zipfile egg
that also contains other eggs.</dd>
<dt><tt class="docutils literal"><span class="pre">FileMetadata(path_to_pkg_info)</span></tt></dt>
<dd>Create an <tt class="docutils literal"><span class="pre">IResourceProvider</span></tt> that provides exactly one metadata
resource: <tt class="docutils literal"><span class="pre">PKG-INFO</span></tt>. The supplied path should be a distutils PKG-INFO
file. This is basically the same as an <tt class="docutils literal"><span class="pre">EmptyProvider</span></tt>, except that
requests for <tt class="docutils literal"><span class="pre">PKG-INFO</span></tt> will be answered using the contents of the
designated file. (This provider is used to wrap <tt class="docutils literal"><span class="pre">.egg-info</span></tt> files
installed by vendor-supplied system packages.)</dd>
</dl>
</div>
</div>
<div class="section" id="utility-functions">
<h3><a class="toc-backref" href="#id32">Utility Functions</a><a class="headerlink" href="#utility-functions" title="Permalink to this headline">¶</a></h3>
<p>In addition to its high-level APIs, <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> also includes several
generally-useful utility routines. These routines are used to implement the
high-level APIs, but can also be quite useful by themselves.</p>
<div class="section" id="parsing-utilities">
<h4><a class="toc-backref" href="#id33">Parsing Utilities</a><a class="headerlink" href="#parsing-utilities" title="Permalink to this headline">¶</a></h4>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">parse_version(version)</span></tt></dt>
<dd><p class="first">Parse a project’s version string, returning a value that can be used to
compare versions by chronological order. Semantically, the format is a
rough cross between distutils’ <tt class="docutils literal"><span class="pre">StrictVersion</span></tt> and <tt class="docutils literal"><span class="pre">LooseVersion</span></tt>
classes; if you give it versions that would work with <tt class="docutils literal"><span class="pre">StrictVersion</span></tt>,
then they will compare the same way. Otherwise, comparisons are more like
a “smarter” form of <tt class="docutils literal"><span class="pre">LooseVersion</span></tt>. It is <em>possible</em> to create
pathological version coding schemes that will fool this parser, but they
should be very rare in practice.</p>
<p>The returned value will be a tuple of strings. Numeric portions of the
version are padded to 8 digits so they will compare numerically, but
without relying on how numbers compare relative to strings. Dots are
dropped, but dashes are retained. Trailing zeros between alpha segments
or dashes are suppressed, so that e.g. “2.4.0” is considered the same as
“2.4”. Alphanumeric parts are lower-cased.</p>
<p>The algorithm assumes that strings like “-” and any alpha string that
alphabetically follows “final” represents a “patch level”. So, “2.4-1”
is assumed to be a branch or patch of “2.4”, and therefore “2.4.1” is
considered newer than “2.4-1”, which in turn is newer than “2.4”.</p>
<p>Strings like “a”, “b”, “c”, “alpha”, “beta”, “candidate” and so on (that
come before “final” alphabetically) are assumed to be pre-release versions,
so that the version “2.4” is considered newer than “2.4a1”. Any “-”
characters preceding a pre-release indicator are removed. (In versions of
setuptools prior to 0.6a9, “-” characters were not removed, leading to the
unintuitive result that “0.2-rc1” was considered a newer version than
“0.2”.)</p>
<p class="last">Finally, to handle miscellaneous cases, the strings “pre”, “preview”, and
“rc” are treated as if they were “c”, i.e. as though they were release
candidates, and therefore are not as new as a version string that does not
contain them. And the string “dev” is treated as if it were an “@” sign;
that is, a version coming before even “a” or “alpha”.</p>
</dd>
</dl>
<dl class="docutils" id="yield-lines">
<dt><tt class="docutils literal"><span class="pre">yield_lines(strs)</span></tt></dt>
<dd><p class="first">Yield non-empty/non-comment lines from a string/unicode or a possibly-
nested sequence thereof. If <cite>strs</cite> is an instance of <tt class="docutils literal"><span class="pre">basestring</span></tt>, it
is split into lines, and each non-blank, non-comment line is yielded after
stripping leading and trailing whitespace. (Lines whose first non-blank
character is <tt class="docutils literal"><span class="pre">#</span></tt> are considered comment lines.)</p>
<p>If <cite>strs</cite> is not an instance of <tt class="docutils literal"><span class="pre">basestring</span></tt>, it is iterated over, and
each item is passed recursively to <tt class="docutils literal"><span class="pre">yield_lines()</span></tt>, so that an arbitarily
nested sequence of strings, or sequences of sequences of strings can be
flattened out to the lines contained therein. So for example, passing
a file object or a list of strings to <tt class="docutils literal"><span class="pre">yield_lines</span></tt> will both work.
(Note that between each string in a sequence of strings there is assumed to
be an implicit line break, so lines cannot bridge two strings in a
sequence.)</p>
<p class="last">This routine is used extensively by <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> to parse metadata
and file formats of various kinds, and most other <tt class="docutils literal"><span class="pre">pkg_resources</span></tt>
parsing functions that yield multiple values will use it to break up their
input. However, this routine is idempotent, so calling <tt class="docutils literal"><span class="pre">yield_lines()</span></tt>
on the output of another call to <tt class="docutils literal"><span class="pre">yield_lines()</span></tt> is completely harmless.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">split_sections(strs)</span></tt></dt>
<dd><p class="first">Split a string (or possibly-nested iterable thereof), yielding <tt class="docutils literal"><span class="pre">(section,</span>
<span class="pre">content)</span></tt> pairs found using an <tt class="docutils literal"><span class="pre">.ini</span></tt>-like syntax. Each <tt class="docutils literal"><span class="pre">section</span></tt> is
a whitespace-stripped version of the section name (“<tt class="docutils literal"><span class="pre">[section]</span></tt>”)
and each <tt class="docutils literal"><span class="pre">content</span></tt> is a list of stripped lines excluding blank lines and
comment-only lines. If there are any non-blank, non-comment lines before
the first section header, they’re yielded in a first <tt class="docutils literal"><span class="pre">section</span></tt> of
<tt class="docutils literal"><span class="pre">None</span></tt>.</p>
<p>This routine uses <tt class="docutils literal"><span class="pre">yield_lines()</span></tt> as its front end, so you can pass in
anything that <tt class="docutils literal"><span class="pre">yield_lines()</span></tt> accepts, such as an open text file, string,
or sequence of strings. <tt class="docutils literal"><span class="pre">ValueError</span></tt> is raised if a malformed section
header is found (i.e. a line starting with <tt class="docutils literal"><span class="pre">[</span></tt> but not ending with
<tt class="docutils literal"><span class="pre">]</span></tt>).</p>
<p class="last">Note that this simplistic parser assumes that any line whose first nonblank
character is <tt class="docutils literal"><span class="pre">[</span></tt> is a section heading, so it can’t support .ini format
variations that allow <tt class="docutils literal"><span class="pre">[</span></tt> as the first nonblank character on other lines.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">safe_name(name)</span></tt></dt>
<dd>Return a “safe” form of a project’s name, suitable for use in a
<tt class="docutils literal"><span class="pre">Requirement</span></tt> string, as a distribution name, or a PyPI project name.
All non-alphanumeric runs are condensed to single “-” characters, such that
a name like “The $$$ Tree” becomes “The-Tree”. Note that if you are
generating a filename from this value you should combine it with a call to
<tt class="docutils literal"><span class="pre">to_filename()</span></tt> so all dashes (“-”) are replaced by underscores (“_”).
See <tt class="docutils literal"><span class="pre">to_filename()</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">safe_version(version)</span></tt></dt>
<dd>Similar to <tt class="docutils literal"><span class="pre">safe_name()</span></tt> except that spaces in the input become dots, and
dots are allowed to exist in the output. As with <tt class="docutils literal"><span class="pre">safe_name()</span></tt>, if you
are generating a filename from this you should replace any “-” characters
in the output with underscores.</dd>
<dt><tt class="docutils literal"><span class="pre">safe_extra(extra)</span></tt></dt>
<dd>Return a “safe” form of an extra’s name, suitable for use in a requirement
string or a setup script’s <tt class="docutils literal"><span class="pre">extras_require</span></tt> keyword. This routine is
similar to <tt class="docutils literal"><span class="pre">safe_name()</span></tt> except that non-alphanumeric runs are replaced
by a single underbar (<tt class="docutils literal"><span class="pre">_</span></tt>), and the result is lowercased.</dd>
<dt><tt class="docutils literal"><span class="pre">to_filename(name_or_version)</span></tt></dt>
<dd>Escape a name or version string so it can be used in a dash-separated
filename (or <tt class="docutils literal"><span class="pre">#egg=name-version</span></tt> tag) without ambiguity. You
should only pass in values that were returned by <tt class="docutils literal"><span class="pre">safe_name()</span></tt> or
<tt class="docutils literal"><span class="pre">safe_version()</span></tt>.</dd>
</dl>
</div>
<div class="section" id="platform-utilities">
<h4><a class="toc-backref" href="#id34">Platform Utilities</a><a class="headerlink" href="#platform-utilities" title="Permalink to this headline">¶</a></h4>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">get_build_platform()</span></tt></dt>
<dd>Return this platform’s identifier string. For Windows, the return value
is <tt class="docutils literal"><span class="pre">"win32"</span></tt>, and for Mac OS X it is a string of the form
<tt class="docutils literal"><span class="pre">"macosx-10.4-ppc"</span></tt>. All other platforms return the same uname-based
string that the <tt class="docutils literal"><span class="pre">distutils.util.get_platform()</span></tt> function returns.
This string is the minimum platform version required by distributions built
on the local machine. (Backward compatibility note: setuptools versions
prior to 0.6b1 called this function <tt class="docutils literal"><span class="pre">get_platform()</span></tt>, and the function is
still available under that name for backward compatibility reasons.)</dd>
<dt><tt class="docutils literal"><span class="pre">get_supported_platform()</span></tt> (New in 0.6b1)</dt>
<dd>This is the similar to <tt class="docutils literal"><span class="pre">get_build_platform()</span></tt>, but is the maximum
platform version that the local machine supports. You will usually want
to use this value as the <tt class="docutils literal"><span class="pre">provided</span></tt> argument to the
<tt class="docutils literal"><span class="pre">compatible_platforms()</span></tt> function.</dd>
<dt><tt class="docutils literal"><span class="pre">compatible_platforms(provided,</span> <span class="pre">required)</span></tt></dt>
<dd>Return true if a distribution built on the <cite>provided</cite> platform may be used
on the <cite>required</cite> platform. If either platform value is <tt class="docutils literal"><span class="pre">None</span></tt>, it is
considered a wildcard, and the platforms are therefore compatible.
Likewise, if the platform strings are equal, they’re also considered
compatible, and <tt class="docutils literal"><span class="pre">True</span></tt> is returned. Currently, the only non-equal
platform strings that are considered compatible are Mac OS X platform
strings with the same hardware type (e.g. <tt class="docutils literal"><span class="pre">ppc</span></tt>) and major version
(e.g. <tt class="docutils literal"><span class="pre">10</span></tt>) with the <cite>provided</cite> platform’s minor version being less than
or equal to the <cite>required</cite> platform’s minor version.</dd>
<dt><tt class="docutils literal"><span class="pre">get_default_cache()</span></tt></dt>
<dd>Determine the default cache location for extracting resources from zipped
eggs. This routine returns the <tt class="docutils literal"><span class="pre">PYTHON_EGG_CACHE</span></tt> environment variable,
if set. Otherwise, on Windows, it returns a “Python-Eggs” subdirectory of
the user’s “Application Data” directory. On all other systems, it returns
<tt class="docutils literal"><span class="pre">os.path.expanduser("~/.python-eggs")</span></tt> if <tt class="docutils literal"><span class="pre">PYTHON_EGG_CACHE</span></tt> is not
set.</dd>
</dl>
</div>
<div class="section" id="pep-302-utilities">
<h4><a class="toc-backref" href="#id35">PEP 302 Utilities</a><a class="headerlink" href="#pep-302-utilities" title="Permalink to this headline">¶</a></h4>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">get_importer(path_item)</span></tt></dt>
<dd><p class="first">Retrieve a PEP 302 “importer” for the given path item (which need not
actually be on <tt class="docutils literal"><span class="pre">sys.path</span></tt>). This routine simulates the PEP 302 protocol
for obtaining an “importer” object. It first checks for an importer for
the path item in <tt class="docutils literal"><span class="pre">sys.path_importer_cache</span></tt>, and if not found it calls
each of the <tt class="docutils literal"><span class="pre">sys.path_hooks</span></tt> and caches the result if a good importer is
found. If no importer is found, this routine returns an <tt class="docutils literal"><span class="pre">ImpWrapper</span></tt>
instance that wraps the builtin import machinery as a PEP 302-compliant
“importer” object. This <tt class="docutils literal"><span class="pre">ImpWrapper</span></tt> is <em>not</em> cached; instead a new
instance is returned each time.</p>
<p class="last">(Note: When run under Python 2.5, this function is simply an alias for
<tt class="docutils literal"><span class="pre">pkgutil.get_importer()</span></tt>, and instead of <tt class="docutils literal"><span class="pre">pkg_resources.ImpWrapper</span></tt>
instances, it may return <tt class="docutils literal"><span class="pre">pkgutil.ImpImporter</span></tt> instances.)</p>
</dd>
</dl>
</div>
<div class="section" id="file-path-utilities">
<h4><a class="toc-backref" href="#id36">File/Path Utilities</a><a class="headerlink" href="#file-path-utilities" title="Permalink to this headline">¶</a></h4>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">ensure_directory(path)</span></tt></dt>
<dd>Ensure that the parent directory (<tt class="docutils literal"><span class="pre">os.path.dirname</span></tt>) of <cite>path</cite> actually
exists, using <tt class="docutils literal"><span class="pre">os.makedirs()</span></tt> if necessary.</dd>
<dt><tt class="docutils literal"><span class="pre">normalize_path(path)</span></tt></dt>
<dd>Return a “normalized” version of <cite>path</cite>, such that two paths represent
the same filesystem location if they have equal <tt class="docutils literal"><span class="pre">normalized_path()</span></tt>
values. Specifically, this is a shortcut for calling <tt class="docutils literal"><span class="pre">os.path.realpath</span></tt>
and <tt class="docutils literal"><span class="pre">os.path.normcase</span></tt> on <cite>path</cite>. Unfortunately, on certain platforms
(notably Cygwin and Mac OS X) the <tt class="docutils literal"><span class="pre">normcase</span></tt> function does not accurately
reflect the platform’s case-sensitivity, so there is always the possibility
of two apparently-different paths being equal on such platforms.</dd>
</dl>
</div>
<div class="section" id="history">
<h4><a class="toc-backref" href="#id37">History</a><a class="headerlink" href="#history" title="Permalink to this headline">¶</a></h4>
<dl class="docutils">
<dt>0.6c9</dt>
<dd><ul class="first last simple">
<li>Fix <tt class="docutils literal"><span class="pre">resource_listdir('')</span></tt> always returning an empty list for zipped eggs.</li>
</ul>
</dd>
<dt>0.6c7</dt>
<dd><ul class="first last simple">
<li>Fix package precedence problem where single-version eggs installed in
<tt class="docutils literal"><span class="pre">site-packages</span></tt> would take precedence over <tt class="docutils literal"><span class="pre">.egg</span></tt> files (or directories)
installed in <tt class="docutils literal"><span class="pre">site-packages</span></tt>.</li>
</ul>
</dd>
<dt>0.6c6</dt>
<dd><ul class="first last simple">
<li>Fix extracted C extensions not having executable permissions under Cygwin.</li>
<li>Allow <tt class="docutils literal"><span class="pre">.egg-link</span></tt> files to contain relative paths.</li>
<li>Fix cache dir defaults on Windows when multiple environment vars are needed
to construct a path.</li>
</ul>
</dd>
<dt>0.6c4</dt>
<dd><ul class="first last simple">
<li>Fix “dev” versions being considered newer than release candidates.</li>
</ul>
</dd>
<dt>0.6c3</dt>
<dd><ul class="first last simple">
<li>Python 2.5 compatibility fixes.</li>
</ul>
</dd>
<dt>0.6c2</dt>
<dd><ul class="first last simple">
<li>Fix a problem with eggs specified directly on <tt class="docutils literal"><span class="pre">PYTHONPATH</span></tt> on
case-insensitive filesystems possibly not showing up in the default
working set, due to differing normalizations of <tt class="docutils literal"><span class="pre">sys.path</span></tt> entries.</li>
</ul>
</dd>
<dt>0.6b3</dt>
<dd><ul class="first last simple">
<li>Fixed a duplicate path insertion problem on case-insensitive filesystems.</li>
</ul>
</dd>
<dt>0.6b1</dt>
<dd><ul class="first last simple">
<li>Split <tt class="docutils literal"><span class="pre">get_platform()</span></tt> into <tt class="docutils literal"><span class="pre">get_supported_platform()</span></tt> and
<tt class="docutils literal"><span class="pre">get_build_platform()</span></tt> to work around a Mac versioning problem that caused
the behavior of <tt class="docutils literal"><span class="pre">compatible_platforms()</span></tt> to be platform specific.</li>
<li>Fix entry point parsing when a standalone module name has whitespace
between it and the extras.</li>
</ul>
</dd>
<dt>0.6a11</dt>
<dd><ul class="first last simple">
<li>Added <tt class="docutils literal"><span class="pre">ExtractionError</span></tt> and <tt class="docutils literal"><span class="pre">ResourceManager.extraction_error()</span></tt> so that
cache permission problems get a more user-friendly explanation of the
problem, and so that programs can catch and handle extraction errors if they
need to.</li>
</ul>
</dd>
<dt>0.6a10</dt>
<dd><ul class="first last simple">
<li>Added the <tt class="docutils literal"><span class="pre">extras</span></tt> attribute to <tt class="docutils literal"><span class="pre">Distribution</span></tt>, the <tt class="docutils literal"><span class="pre">find_plugins()</span></tt>
method to <tt class="docutils literal"><span class="pre">WorkingSet</span></tt>, and the <tt class="docutils literal"><span class="pre">__add__()</span></tt> and <tt class="docutils literal"><span class="pre">__iadd__()</span></tt> methods
to <tt class="docutils literal"><span class="pre">Environment</span></tt>.</li>
<li><tt class="docutils literal"><span class="pre">safe_name()</span></tt> now allows dots in project names.</li>
<li>There is a new <tt class="docutils literal"><span class="pre">to_filename()</span></tt> function that escapes project names and
versions for safe use in constructing egg filenames from a Distribution
object’s metadata.</li>
<li>Added <tt class="docutils literal"><span class="pre">Distribution.clone()</span></tt> method, and keyword argument support to other
<tt class="docutils literal"><span class="pre">Distribution</span></tt> constructors.</li>
<li>Added the <tt class="docutils literal"><span class="pre">DEVELOP_DIST</span></tt> precedence, and automatically assign it to
eggs using <tt class="docutils literal"><span class="pre">.egg-info</span></tt> format.</li>
</ul>
</dd>
<dt>0.6a9</dt>
<dd><ul class="first last simple">
<li>Don’t raise an error when an invalid (unfinished) distribution is found
unless absolutely necessary. Warn about skipping invalid/unfinished eggs
when building an Environment.</li>
<li>Added support for <tt class="docutils literal"><span class="pre">.egg-info</span></tt> files or directories with version/platform
information embedded in the filename, so that system packagers have the
option of including <tt class="docutils literal"><span class="pre">PKG-INFO</span></tt> files to indicate the presence of a
system-installed egg, without needing to use <tt class="docutils literal"><span class="pre">.egg</span></tt> directories, zipfiles,
or <tt class="docutils literal"><span class="pre">.pth</span></tt> manipulation.</li>
<li>Changed <tt class="docutils literal"><span class="pre">parse_version()</span></tt> to remove dashes before pre-release tags, so
that <tt class="docutils literal"><span class="pre">0.2-rc1</span></tt> is considered an <em>older</em> version than <tt class="docutils literal"><span class="pre">0.2</span></tt>, and is equal
to <tt class="docutils literal"><span class="pre">0.2rc1</span></tt>. The idea that a dash <em>always</em> meant a post-release version
was highly non-intuitive to setuptools users and Python developers, who
seem to want to use <tt class="docutils literal"><span class="pre">-rc</span></tt> version numbers a lot.</li>
</ul>
</dd>
<dt>0.6a8</dt>
<dd><ul class="first last simple">
<li>Fixed a problem with <tt class="docutils literal"><span class="pre">WorkingSet.resolve()</span></tt> that prevented version
conflicts from being detected at runtime.</li>
<li>Improved runtime conflict warning message to identify a line in the user’s
program, rather than flagging the <tt class="docutils literal"><span class="pre">warn()</span></tt> call in <tt class="docutils literal"><span class="pre">pkg_resources</span></tt>.</li>
<li>Avoid giving runtime conflict warnings for namespace packages, even if they
were declared by a different package than the one currently being activated.</li>
<li>Fix path insertion algorithm for case-insensitive filesystems.</li>
<li>Fixed a problem with nested namespace packages (e.g. <tt class="docutils literal"><span class="pre">peak.util</span></tt>) not
being set as an attribute of their parent package.</li>
</ul>
</dd>
<dt>0.6a6</dt>
<dd><ul class="first last simple">
<li>Activated distributions are now inserted in <tt class="docutils literal"><span class="pre">sys.path</span></tt> (and the working
set) just before the directory that contains them, instead of at the end.
This allows e.g. eggs in <tt class="docutils literal"><span class="pre">site-packages</span></tt> to override unmanaged modules in
the same location, and allows eggs found earlier on <tt class="docutils literal"><span class="pre">sys.path</span></tt> to override
ones found later.</li>
<li>When a distribution is activated, it now checks whether any contained
non-namespace modules have already been imported and issues a warning if
a conflicting module has already been imported.</li>
<li>Changed dependency processing so that it’s breadth-first, allowing a
depender’s preferences to override those of a dependee, to prevent conflicts
when a lower version is acceptable to the dependee, but not the depender.</li>
<li>Fixed a problem extracting zipped files on Windows, when the egg in question
has had changed contents but still has the same version number.</li>
</ul>
</dd>
<dt>0.6a4</dt>
<dd><ul class="first last simple">
<li>Fix a bug in <tt class="docutils literal"><span class="pre">WorkingSet.resolve()</span></tt> that was introduced in 0.6a3.</li>
</ul>
</dd>
<dt>0.6a3</dt>
<dd><ul class="first last simple">
<li>Added <tt class="docutils literal"><span class="pre">safe_extra()</span></tt> parsing utility routine, and use it for Requirement,
EntryPoint, and Distribution objects’ extras handling.</li>
</ul>
</dd>
<dt>0.6a1</dt>
<dd><ul class="first last simple">
<li>Enhanced performance of <tt class="docutils literal"><span class="pre">require()</span></tt> and related operations when all
requirements are already in the working set, and enhanced performance of
directory scanning for distributions.</li>
<li>Fixed some problems using <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> w/PEP 302 loaders other than
<tt class="docutils literal"><span class="pre">zipimport</span></tt>, and the previously-broken “eager resource” support.</li>
<li>Fixed <tt class="docutils literal"><span class="pre">pkg_resources.resource_exists()</span></tt> not working correctly, along with
some other resource API bugs.</li>
<li>Many API changes and enhancements:<ul>
<li>Added <tt class="docutils literal"><span class="pre">EntryPoint</span></tt>, <tt class="docutils literal"><span class="pre">get_entry_map</span></tt>, <tt class="docutils literal"><span class="pre">load_entry_point</span></tt>, and
<tt class="docutils literal"><span class="pre">get_entry_info</span></tt> APIs for dynamic plugin discovery.</li>
<li><tt class="docutils literal"><span class="pre">list_resources</span></tt> is now <tt class="docutils literal"><span class="pre">resource_listdir</span></tt> (and it actually works)</li>
<li>Resource API functions like <tt class="docutils literal"><span class="pre">resource_string()</span></tt> that accepted a package
name and resource name, will now also accept a <tt class="docutils literal"><span class="pre">Requirement</span></tt> object in
place of the package name (to allow access to non-package data files in
an egg).</li>
<li><tt class="docutils literal"><span class="pre">get_provider()</span></tt> will now accept a <tt class="docutils literal"><span class="pre">Requirement</span></tt> instance or a module
name. If it is given a <tt class="docutils literal"><span class="pre">Requirement</span></tt>, it will return a corresponding
<tt class="docutils literal"><span class="pre">Distribution</span></tt> (by calling <tt class="docutils literal"><span class="pre">require()</span></tt> if a suitable distribution
isn’t already in the working set), rather than returning a metadata and
resource provider for a specific module. (The difference is in how
resource paths are interpreted; supplying a module name means resources
path will be module-relative, rather than relative to the distribution’s
root.)</li>
<li><tt class="docutils literal"><span class="pre">Distribution</span></tt> objects now implement the <tt class="docutils literal"><span class="pre">IResourceProvider</span></tt> and
<tt class="docutils literal"><span class="pre">IMetadataProvider</span></tt> interfaces, so you don’t need to reference the (no
longer available) <tt class="docutils literal"><span class="pre">metadata</span></tt> attribute to get at these interfaces.</li>
<li><tt class="docutils literal"><span class="pre">Distribution</span></tt> and <tt class="docutils literal"><span class="pre">Requirement</span></tt> both have a <tt class="docutils literal"><span class="pre">project_name</span></tt>
attribute for the project name they refer to. (Previously these were
<tt class="docutils literal"><span class="pre">name</span></tt> and <tt class="docutils literal"><span class="pre">distname</span></tt> attributes.)</li>
<li>The <tt class="docutils literal"><span class="pre">path</span></tt> attribute of <tt class="docutils literal"><span class="pre">Distribution</span></tt> objects is now <tt class="docutils literal"><span class="pre">location</span></tt>,
because it isn’t necessarily a filesystem path (and hasn’t been for some
time now). The <tt class="docutils literal"><span class="pre">location</span></tt> of <tt class="docutils literal"><span class="pre">Distribution</span></tt> objects in the filesystem
should always be normalized using <tt class="docutils literal"><span class="pre">pkg_resources.normalize_path()</span></tt>; all
of the setuptools and EasyInstall code that generates distributions from
the filesystem (including <tt class="docutils literal"><span class="pre">Distribution.from_filename()</span></tt>) ensure this
invariant, but if you use a more generic API like <tt class="docutils literal"><span class="pre">Distribution()</span></tt> or
<tt class="docutils literal"><span class="pre">Distribution.from_location()</span></tt> you should take care that you don’t
create a distribution with an un-normalized filesystem path.</li>
<li><tt class="docutils literal"><span class="pre">Distribution</span></tt> objects now have an <tt class="docutils literal"><span class="pre">as_requirement()</span></tt> method that
returns a <tt class="docutils literal"><span class="pre">Requirement</span></tt> for the distribution’s project name and version.</li>
<li>Distribution objects no longer have an <tt class="docutils literal"><span class="pre">installed_on()</span></tt> method, and the
<tt class="docutils literal"><span class="pre">install_on()</span></tt> method is now <tt class="docutils literal"><span class="pre">activate()</span></tt> (but may go away altogether
soon). The <tt class="docutils literal"><span class="pre">depends()</span></tt> method has also been renamed to <tt class="docutils literal"><span class="pre">requires()</span></tt>,
and <tt class="docutils literal"><span class="pre">InvalidOption</span></tt> is now <tt class="docutils literal"><span class="pre">UnknownExtra</span></tt>.</li>
<li><tt class="docutils literal"><span class="pre">find_distributions()</span></tt> now takes an additional argument called <tt class="docutils literal"><span class="pre">only</span></tt>,
that tells it to only yield distributions whose location is the passed-in
path. (It defaults to False, so that the default behavior is unchanged.)</li>
<li><tt class="docutils literal"><span class="pre">AvailableDistributions</span></tt> is now called <tt class="docutils literal"><span class="pre">Environment</span></tt>, and the
<tt class="docutils literal"><span class="pre">get()</span></tt>, <tt class="docutils literal"><span class="pre">__len__()</span></tt>, and <tt class="docutils literal"><span class="pre">__contains__()</span></tt> methods were removed,
because they weren’t particularly useful. <tt class="docutils literal"><span class="pre">__getitem__()</span></tt> no longer
raises <tt class="docutils literal"><span class="pre">KeyError</span></tt>; it just returns an empty list if there are no
distributions for the named project.</li>
<li>The <tt class="docutils literal"><span class="pre">resolve()</span></tt> method of <tt class="docutils literal"><span class="pre">Environment</span></tt> is now a method of
<tt class="docutils literal"><span class="pre">WorkingSet</span></tt> instead, and the <tt class="docutils literal"><span class="pre">best_match()</span></tt> method now uses a working
set instead of a path list as its second argument.</li>
<li>There is a new <tt class="docutils literal"><span class="pre">pkg_resources.add_activation_listener()</span></tt> API that lets
you register a callback for notifications about distributions added to
<tt class="docutils literal"><span class="pre">sys.path</span></tt> (including the distributions already on it). This is
basically a hook for extensible applications and frameworks to be able to
search for plugin metadata in distributions added at runtime.</li>
</ul>
</li>
</ul>
</dd>
<dt>0.5a13</dt>
<dd><ul class="first last simple">
<li>Fixed a bug in resource extraction from nested packages in a zipped egg.</li>
</ul>
</dd>
<dt>0.5a12</dt>
<dd><ul class="first last simple">
<li>Updated extraction/cache mechanism for zipped resources to avoid inter-
process and inter-thread races during extraction. The default cache
location can now be set via the <tt class="docutils literal"><span class="pre">PYTHON_EGGS_CACHE</span></tt> environment variable,
and the default Windows cache is now a <tt class="docutils literal"><span class="pre">Python-Eggs</span></tt> subdirectory of the
current user’s “Application Data” directory, if the <tt class="docutils literal"><span class="pre">PYTHON_EGGS_CACHE</span></tt>
variable isn’t set.</li>
</ul>
</dd>
<dt>0.5a10</dt>
<dd><ul class="first last simple">
<li>Fix a problem with <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> being confused by non-existent eggs on
<tt class="docutils literal"><span class="pre">sys.path</span></tt> (e.g. if a user deletes an egg without removing it from the
<tt class="docutils literal"><span class="pre">easy-install.pth</span></tt> file).</li>
<li>Fix a problem with “basket” support in <tt class="docutils literal"><span class="pre">pkg_resources</span></tt>, where egg-finding
never actually went inside <tt class="docutils literal"><span class="pre">.egg</span></tt> files.</li>
<li>Made <tt class="docutils literal"><span class="pre">pkg_resources</span></tt> import the module you request resources from, if it’s
not already imported.</li>
</ul>
</dd>
<dt>0.5a4</dt>
<dd><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">pkg_resources.AvailableDistributions.resolve()</span></tt> and related methods now
accept an <tt class="docutils literal"><span class="pre">installer</span></tt> argument: a callable taking one argument, a
<tt class="docutils literal"><span class="pre">Requirement</span></tt> instance. The callable must return a <tt class="docutils literal"><span class="pre">Distribution</span></tt>
object, or <tt class="docutils literal"><span class="pre">None</span></tt> if no distribution is found. This feature is used by
EasyInstall to resolve dependencies by recursively invoking itself.</li>
</ul>
</dd>
<dt>0.4a4</dt>
<dd><ul class="first last simple">
<li>Fix problems with <tt class="docutils literal"><span class="pre">resource_listdir()</span></tt>, <tt class="docutils literal"><span class="pre">resource_isdir()</span></tt> and resource
directory extraction for zipped eggs.</li>
</ul>
</dd>
<dt>0.4a3</dt>
<dd><ul class="first last simple">
<li>Fixed scripts not being able to see a <tt class="docutils literal"><span class="pre">__file__</span></tt> variable in <tt class="docutils literal"><span class="pre">__main__</span></tt></li>
<li>Fixed a problem with <tt class="docutils literal"><span class="pre">resource_isdir()</span></tt> implementation that was introduced
in 0.4a2.</li>
</ul>
</dd>
<dt>0.4a1</dt>
<dd><ul class="first last simple">
<li>Fixed a bug in requirements processing for exact versions (i.e. <tt class="docutils literal"><span class="pre">==</span></tt> and
<tt class="docutils literal"><span class="pre">!=</span></tt>) when only one condition was included.</li>
<li>Added <tt class="docutils literal"><span class="pre">safe_name()</span></tt> and <tt class="docutils literal"><span class="pre">safe_version()</span></tt> APIs to clean up handling of
arbitrary distribution names and versions found on PyPI.</li>
</ul>
</dd>
<dt>0.3a4</dt>
<dd><ul class="first last simple">
<li><tt class="docutils literal"><span class="pre">pkg_resources</span></tt> now supports resource directories, not just the resources
in them. In particular, there are <tt class="docutils literal"><span class="pre">resource_listdir()</span></tt> and
<tt class="docutils literal"><span class="pre">resource_isdir()</span></tt> APIs.</li>
<li><tt class="docutils literal"><span class="pre">pkg_resources</span></tt> now supports “egg baskets” – .egg zipfiles which contain
multiple distributions in subdirectories whose names end with <tt class="docutils literal"><span class="pre">.egg</span></tt>.
Having such a “basket” in a directory on <tt class="docutils literal"><span class="pre">sys.path</span></tt> is equivalent to
having the individual eggs in that directory, but the contained eggs can
be individually added (or not) to <tt class="docutils literal"><span class="pre">sys.path</span></tt>. Currently, however, there
is no automated way to create baskets.</li>
<li>Namespace package manipulation is now protected by the Python import lock.</li>
</ul>
</dd>
<dt>0.3a1</dt>
<dd><ul class="first last simple">
<li>Initial release.</li>
</ul>
</dd>
</dl>
</div>
</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="#">Package Discovery and Resource Access using <tt class="docutils literal"><span class="pre">pkg_resources</span></tt></a><ul>
<li><a class="reference internal" href="#overview">Overview</a></li>
<li><a class="reference internal" href="#api-reference">API Reference</a><ul>
<li><a class="reference internal" href="#namespace-package-support">Namespace Package Support</a></li>
<li><a class="reference internal" href="#workingset-objects"><tt class="docutils literal"><span class="pre">WorkingSet</span></tt> Objects</a><ul>
<li><a class="reference internal" href="#basic-workingset-methods">Basic <tt class="docutils literal"><span class="pre">WorkingSet</span></tt> Methods</a></li>
<li><a class="reference internal" href="#workingset-methods-and-attributes"><tt class="docutils literal"><span class="pre">WorkingSet</span></tt> Methods and Attributes</a></li>
<li><a class="reference internal" href="#receiving-change-notifications">Receiving Change Notifications</a></li>
<li><a class="reference internal" href="#locating-plugins">Locating Plugins</a></li>
</ul>
</li>
<li><a class="reference internal" href="#environment-objects"><tt class="docutils literal"><span class="pre">Environment</span></tt> Objects</a></li>
<li><a class="reference internal" href="#requirement-objects"><tt class="docutils literal"><span class="pre">Requirement</span></tt> Objects</a><ul>
<li><a class="reference internal" href="#requirements-parsing">Requirements Parsing</a></li>
<li><a class="reference internal" href="#requirement-methods-and-attributes"><tt class="docutils literal"><span class="pre">Requirement</span></tt> Methods and Attributes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#entry-points">Entry Points</a><ul>
<li><a class="reference internal" href="#convenience-api">Convenience API</a></li>
<li><a class="reference internal" href="#creating-and-parsing">Creating and Parsing</a></li>
<li><a class="reference internal" href="#entrypoint-objects"><tt class="docutils literal"><span class="pre">EntryPoint</span></tt> Objects</a></li>
</ul>
</li>
<li><a class="reference internal" href="#distribution-objects"><tt class="docutils literal"><span class="pre">Distribution</span></tt> Objects</a><ul>
<li><a class="reference internal" href="#getting-or-creating-distributions">Getting or Creating Distributions</a></li>
<li><a class="reference internal" href="#distribution-attributes"><tt class="docutils literal"><span class="pre">Distribution</span></tt> Attributes</a></li>
<li><a class="reference internal" href="#distribution-methods"><tt class="docutils literal"><span class="pre">Distribution</span></tt> Methods</a></li>
</ul>
</li>
<li><a class="reference internal" href="#resourcemanager-api"><tt class="docutils literal"><span class="pre">ResourceManager</span></tt> API</a><ul>
<li><a class="reference internal" href="#basic-resource-access">Basic Resource Access</a></li>
<li><a class="reference internal" href="#resource-extraction">Resource Extraction</a></li>
<li><a class="reference internal" href="#provider-interface">“Provider” Interface</a></li>
</ul>
</li>
<li><a class="reference internal" href="#metadata-api">Metadata API</a><ul>
<li><a class="reference internal" href="#imetadataprovider-methods"><tt class="docutils literal"><span class="pre">IMetadataProvider</span></tt> Methods</a></li>
</ul>
</li>
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
<li><a class="reference internal" href="#supporting-custom-importers">Supporting Custom Importers</a><ul>
<li><a class="reference internal" href="#iresourceprovider">IResourceProvider</a></li>
<li><a class="reference internal" href="#built-in-resource-providers">Built-in Resource Providers</a></li>
</ul>
</li>
<li><a class="reference internal" href="#utility-functions">Utility Functions</a><ul>
<li><a class="reference internal" href="#parsing-utilities">Parsing Utilities</a></li>
<li><a class="reference internal" href="#platform-utilities">Platform Utilities</a></li>
<li><a class="reference internal" href="#pep-302-utilities">PEP 302 Utilities</a></li>
<li><a class="reference internal" href="#file-path-utilities">File/Path Utilities</a></li>
<li><a class="reference internal" href="#history">History</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="easy_install.html"
title="previous chapter">Easy Install</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="development.html"
title="next chapter">Development on Setuptools</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/pkg_resources.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="development.html" title="Development on Setuptools"
>next</a></li>
<li class="right" >
<a href="easy_install.html" title="Easy Install"
>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>
|