Guide

Scell is a very simple library that is comprised of two main components- the core library, which implements wrappers around monitored file objects and the select.select() function, and the wrapper which implements a scell.wrapper.Selector object atop a dictionary. To get started with the rest of the guide first create a scell.wrapper.Selector instance:

selector = Selector()

Registering File Objects

The recommended way to register file objects for their interests is using the scell.wrapper.Selector.scoped() context manager:

with selector.scoped([fp1, fp2]) as (m1, m2):
    pass

Within the body of the with block, the file objects are registered but once the block exits the selector automatically unregisters them. This ensures that file objects are automatically cleaned up and that unneeded resources can be freed. You can also use the alternative forms:

# more verbose but more control
from scell.core import Monitored
selector[fp] = Monitored(
    fp,
    wants_read=True,
    wants_write=True,
)

# easier but less control
selector.register(fp, mode='rw')

You can also attach callbacks or other form of data alongside the registered file object:

monitor = selector.register(fp, mode='rw')
monitor.callback = lambda x: x

Querying Events

You can query for readability or writability of each file object by simply using the scell.wrapper.Selector.select() method:

for event in selector.select():
    assert event.readable
    assert event.writable

The select method returns an iterable of scell.core.Event objects that represents the readability and writability of the monitored file objects. A code example of the attributes and what they are:

event.readable     # whether the file object is readable
event.writable     # whether the file object is writable
event.ready        # whether the monitored meets are met
event.fp           # underlying file object
event.callback     # callback associated with the file object
event.monitored    # monitored interests of file object

To only select file objects which are ready, use the scell.wrapper.Selector.ready() method. For example:

for event in selector.ready():
    assert event.ready

Cleaning Up

Cleaning up after ourselves is important- that is, to unregister file objects that have already been closed or unregister file objects that we are no longer interested in. If you used the scell.wrapper.Selector.scoped() you don’t need to unregister any file objects.

To unregister file objects use the scell.wrapper.Selector.unregister() method:

selector.unregister(fp)

Note that it raises a KeyError if you unregister file objects that are not present.