provide a rich collection object in the pytest_modifyitems hook

[RonnyPfannschmidt]

plugins that modify the collection have to consider a number of error-prone details

stable sorting/fixture order for those that reorder,
notifying of deselection for those that remove test items

a rough first idea of an potential api could be something like:

items..select_by(node_lastfailed, reason='passed the last test run')  #to run only last failed tests
items.prepend_sort_key(node_lastfailed) " run last failed tests first

the new api should be active by default, but completely revert to the old list-like behavior in case someone does a list operation

in case the behavior is reverted, a pytest warning should be issued on reverting, and in each usage of the new api

this would also help to make #1372 more nice

[RonnyPfannschmidt]

example code now:

def pytest_collection_modifyitems(config, items):
    tiers = config.getoption('tier')
    if not tiers:
        return
    keep, discard = [], []
    for item in items:
        if tier_matches(item, tiers):
            keep.append(item)
        else:
            discard.append(item)

    items[:] = keep
    config.hook.pytest_deselected(items=discard)

code wanted:

def pytest_collection_modifyitems(config, items):
    tiers = config.getoption('tier')
    if tiers:
        items.select_by(
          partial(tier_matches, tiers=tiers),
          deselect_reason='test tier not in %s' % tiers)

[RonnyPfannschmidt]

turns out YAGNI

we may eventually introduce a hook to deselect/uncollect tests based on conditions and allow those hooks to return the reasons