Aluode/PerceptionLabPortable

1Pluggable Distributions of Python Software2==========================================3 4Distributions5-------------6 7A "Distribution" is a collection of files that represent a "Release" of a8"Project" as of a particular point in time, denoted by a9"Version"::10 11    >>> import sys, pkg_resources12    >>> from pkg_resources import Distribution13    >>> Distribution(project_name="Foo", version="1.2")14    Foo 1.215 16Distributions have a location, which can be a filename, URL, or really anything17else you care to use::18 19    >>> dist = Distribution(20    ...     location="http://example.com/something",21    ...     project_name="Bar", version="0.9"22    ... )23 24    >>> dist25    Bar 0.9 (http://example.com/something)26 27 28Distributions have various introspectable attributes::29 30    >>> dist.location31    'http://example.com/something'32 33    >>> dist.project_name34    'Bar'35 36    >>> dist.version37    '0.9'38 39    >>> dist.py_version == '{}.{}'.format(*sys.version_info)40    True41 42    >>> print(dist.platform)43    None44 45Including various computed attributes::46 47    >>> from pkg_resources import parse_version48    >>> dist.parsed_version == parse_version(dist.version)49    True50 51    >>> dist.key    # case-insensitive form of the project name52    'bar'53 54Distributions are compared (and hashed) by version first::55 56    >>> Distribution(version='1.0') == Distribution(version='1.0')57    True58    >>> Distribution(version='1.0') == Distribution(version='1.1')59    False60    >>> Distribution(version='1.0') <  Distribution(version='1.1')61    True62 63but also by project name (case-insensitive), platform, Python version,64location, etc.::65 66    >>> Distribution(project_name="Foo",version="1.0") == \67    ... Distribution(project_name="Foo",version="1.0")68    True69 70    >>> Distribution(project_name="Foo",version="1.0") == \71    ... Distribution(project_name="foo",version="1.0")72    True73 74    >>> Distribution(project_name="Foo",version="1.0") == \75    ... Distribution(project_name="Foo",version="1.1")76    False77 78    >>> Distribution(project_name="Foo",py_version="2.3",version="1.0") == \79    ... Distribution(project_name="Foo",py_version="2.4",version="1.0")80    False81 82    >>> Distribution(location="spam",version="1.0") == \83    ... Distribution(location="spam",version="1.0")84    True85 86    >>> Distribution(location="spam",version="1.0") == \87    ... Distribution(location="baz",version="1.0")88    False89 90 91 92Hash and compare distribution by prio/plat93 94Get version from metadata95provider capabilities96egg_name()97as_requirement()98from_location, from_filename (w/path normalization)99 100Releases may have zero or more "Requirements", which indicate101what releases of another project the release requires in order to102function.  A Requirement names the other project, expresses some criteria103as to what releases of that project are acceptable, and lists any "Extras"104that the requiring release may need from that project.  (An Extra is an105optional feature of a Release, that can only be used if its additional106Requirements are satisfied.)107 108 109 110The Working Set111---------------112 113A collection of active distributions is called a Working Set.  Note that a114Working Set can contain any importable distribution, not just pluggable ones.115For example, the Python standard library is an importable distribution that116will usually be part of the Working Set, even though it is not pluggable.117Similarly, when you are doing development work on a project, the files you are118editing are also a Distribution.  (And, with a little attention to the119directory names used,  and including some additional metadata, such a120"development distribution" can be made pluggable as well.)121 122    >>> from pkg_resources import WorkingSet123 124A working set's entries are the sys.path entries that correspond to the active125distributions.  By default, the working set's entries are the items on126``sys.path``::127 128    >>> ws = WorkingSet()129    >>> ws.entries == sys.path130    True131 132But you can also create an empty working set explicitly, and add distributions133to it::134 135    >>> ws = WorkingSet([])136    >>> ws.add(dist)137    >>> ws.entries138    ['http://example.com/something']139    >>> dist in ws140    True141    >>> Distribution('foo',version="") in ws142    False143 144And you can iterate over its distributions::145 146    >>> list(ws)147    [Bar 0.9 (http://example.com/something)]148 149Adding the same distribution more than once is a no-op::150 151    >>> ws.add(dist)152    >>> list(ws)153    [Bar 0.9 (http://example.com/something)]154 155For that matter, adding multiple distributions for the same project also does156nothing, because a working set can only hold one active distribution per157project -- the first one added to it::158 159    >>> ws.add(160    ...     Distribution(161    ...         'http://example.com/something', project_name="Bar",162    ...         version="7.2"163    ...     )164    ... )165    >>> list(ws)166    [Bar 0.9 (http://example.com/something)]167 168You can append a path entry to a working set using ``add_entry()``::169 170    >>> ws.entries171    ['http://example.com/something']172    >>> ws.add_entry(pkg_resources.__file__)173    >>> ws.entries174    ['http://example.com/something', '...pkg_resources...']175 176Multiple additions result in multiple entries, even if the entry is already in177the working set (because ``sys.path`` can contain the same entry more than178once)::179 180    >>> ws.add_entry(pkg_resources.__file__)181    >>> ws.entries182    ['...example.com...', '...pkg_resources...', '...pkg_resources...']183 184And you can specify the path entry a distribution was found under, using the185optional second parameter to ``add()``::186 187    >>> ws = WorkingSet([])188    >>> ws.add(dist,"foo")189    >>> ws.entries190    ['foo']191 192But even if a distribution is found under multiple path entries, it still only193shows up once when iterating the working set:194 195    >>> ws.add_entry(ws.entries[0])196    >>> list(ws)197    [Bar 0.9 (http://example.com/something)]198 199You can ask a WorkingSet to ``find()`` a distribution matching a requirement::200 201    >>> from pkg_resources import Requirement202    >>> print(ws.find(Requirement.parse("Foo==1.0")))   # no match, return None203    None204 205    >>> ws.find(Requirement.parse("Bar==0.9"))  # match, return distribution206    Bar 0.9 (http://example.com/something)207 208Note that asking for a conflicting version of a distribution already in a209working set triggers a ``pkg_resources.VersionConflict`` error:210 211    >>> try:212    ...     ws.find(Requirement.parse("Bar==1.0"))213    ... except pkg_resources.VersionConflict as exc:214    ...     print(str(exc))215    ... else:216    ...     raise AssertionError("VersionConflict was not raised")217    (Bar 0.9 (http://example.com/something), Requirement.parse('Bar==1.0'))218 219You can subscribe a callback function to receive notifications whenever a new220distribution is added to a working set.  The callback is immediately invoked221once for each existing distribution in the working set, and then is called222again for new distributions added thereafter::223 224    >>> def added(dist): print("Added %s" % dist)225    >>> ws.subscribe(added)226    Added Bar 0.9227    >>> foo12 = Distribution(project_name="Foo", version="1.2", location="f12")228    >>> ws.add(foo12)229    Added Foo 1.2230 231Note, however, that only the first distribution added for a given project name232will trigger a callback, even during the initial ``subscribe()`` callback::233 234    >>> foo14 = Distribution(project_name="Foo", version="1.4", location="f14")235    >>> ws.add(foo14)   # no callback, because Foo 1.2 is already active236 237    >>> ws = WorkingSet([])238    >>> ws.add(foo12)239    >>> ws.add(foo14)240    >>> ws.subscribe(added)241    Added Foo 1.2242 243And adding a callback more than once has no effect, either::244 245    >>> ws.subscribe(added)     # no callbacks246 247    # and no double-callbacks on subsequent additions, either248    >>> just_a_test = Distribution(project_name="JustATest", version="0.99")249    >>> ws.add(just_a_test)250    Added JustATest 0.99251 252 253Finding Plugins254---------------255 256``WorkingSet`` objects can be used to figure out what plugins in an257``Environment`` can be loaded without any resolution errors::258 259    >>> from pkg_resources import Environment260 261    >>> plugins = Environment([])   # normally, a list of plugin directories262    >>> plugins.add(foo12)263    >>> plugins.add(foo14)264    >>> plugins.add(just_a_test)265 266In the simplest case, we just get the newest version of each distribution in267the plugin environment::268 269    >>> ws = WorkingSet([])270    >>> ws.find_plugins(plugins)271    ([JustATest 0.99, Foo 1.4 (f14)], {})272 273But if there's a problem with a version conflict or missing requirements, the274method falls back to older versions, and the error info dict will contain an275exception instance for each unloadable plugin::276 277    >>> ws.add(foo12)   # this will conflict with Foo 1.4278    >>> ws.find_plugins(plugins)279    ([JustATest 0.99, Foo 1.2 (f12)], {Foo 1.4 (f14): VersionConflict(...)})280 281But if you disallow fallbacks, the failed plugin will be skipped instead of282trying older versions::283 284    >>> ws.find_plugins(plugins, fallback=False)285    ([JustATest 0.99], {Foo 1.4 (f14): VersionConflict(...)})286 287 288 289Platform Compatibility Rules290----------------------------291 292On the Mac, there are potential compatibility issues for modules compiled293on newer versions of macOS than what the user is running. Additionally,294macOS will soon have two platforms to contend with: Intel and PowerPC.295 296Basic equality works as on other platforms::297 298    >>> from pkg_resources import compatible_platforms as cp299    >>> reqd = 'macosx-10.4-ppc'300    >>> cp(reqd, reqd)301    True302    >>> cp("win32", reqd)303    False304 305Distributions made on other machine types are not compatible::306 307    >>> cp("macosx-10.4-i386", reqd)308    False309 310Distributions made on earlier versions of the OS are compatible, as311long as they are from the same top-level version. The patchlevel version312number does not matter::313 314    >>> cp("macosx-10.4-ppc", reqd)315    True316    >>> cp("macosx-10.3-ppc", reqd)317    True318    >>> cp("macosx-10.5-ppc", reqd)319    False320    >>> cp("macosx-9.5-ppc", reqd)321    False322 323Backwards compatibility for packages made via earlier versions of324setuptools is provided as well::325 326    >>> cp("darwin-8.2.0-Power_Macintosh", reqd)327    True328    >>> cp("darwin-7.2.0-Power_Macintosh", reqd)329    True330    >>> cp("darwin-8.2.0-Power_Macintosh", "macosx-10.3-ppc")331    False332 333 334Environment Markers335-------------------336 337    >>> from pkg_resources import invalid_marker as im, evaluate_marker as em338    >>> import os339 340    >>> print(im("sys_platform"))341    Expected marker operator, one of <=, <, !=, ==, >=, >, ~=, ===, in, not in342        sys_platform343                    ^344 345    >>> print(im("sys_platform=="))346    Expected a marker variable or quoted string347        sys_platform==348                      ^349 350    >>> print(im("sys_platform=='win32'"))351    False352 353    >>> print(im("sys=='x'"))354    Expected a marker variable or quoted string355        sys=='x'356        ^357 358    >>> print(im("(extra)"))359    Expected marker operator, one of <=, <, !=, ==, >=, >, ~=, ===, in, not in360        (extra)361              ^362 363    >>> print(im("(extra"))364    Expected marker operator, one of <=, <, !=, ==, >=, >, ~=, ===, in, not in365        (extra366              ^367 368    >>> print(im("os.open('foo')=='y'"))369    Expected a marker variable or quoted string370        os.open('foo')=='y'371        ^372 373    >>> print(im("'x'=='y' and os.open('foo')=='y'"))   # no short-circuit!374    Expected a marker variable or quoted string375        'x'=='y' and os.open('foo')=='y'376                     ^377 378    >>> print(im("'x'=='x' or os.open('foo')=='y'"))   # no short-circuit!379    Expected a marker variable or quoted string380        'x'=='x' or os.open('foo')=='y'381                    ^382 383    >>> print(im("r'x'=='x'"))384    Expected a marker variable or quoted string385        r'x'=='x'386        ^387 388    >>> print(im("'''x'''=='x'"))389    Expected marker operator, one of <=, <, !=, ==, >=, >, ~=, ===, in, not in390        '''x'''=='x'391          ^392 393    >>> print(im('"""x"""=="x"'))394    Expected marker operator, one of <=, <, !=, ==, >=, >, ~=, ===, in, not in395        """x"""=="x"396          ^397 398    >>> print(im(r"x\n=='x'"))399    Expected a marker variable or quoted string400        x\n=='x'401        ^402 403    >>> print(im("os.open=='y'"))404    Expected a marker variable or quoted string405        os.open=='y'406        ^407 408    >>> em("sys_platform=='win32'") == (sys.platform=='win32')409    True410 411    >>> em("python_version >= '2.7'")412    True413 414    >>> em("python_version > '2.6'")415    True416 417    >>> im("implementation_name=='cpython'")418    False419 420    >>> im("platform_python_implementation=='CPython'")421    False422 423    >>> im("implementation_version=='3.5.1'")424    False425