# Module `selector`

Mock of `selectors` and compatible objects performing asynchronous IO.

This module provides classes to mock objects performing IO (files, sockets, etc). These mocks are compatible with `TestSelector`, which can simulate the behavior of a selector on the mock objects, or forward actual work to a real selector.

## Mocking file-like objects

class `asynctest.``FileMock`(*args, **kwargs)

  Mock a file-like object.

  A FileMock is an intelligent mock which can work with TestSelector to simulate IO events during tests.

  `fileno`()

    Return a `FileDescriptor` object.

class `asynctest.``SocketMock`(side_effect=None, return_value=sentinel.DEFAULT, wraps=None, name=None, spec_set=None, parent=None, **kwargs)

  Bases: `asynctest.selector.FileMock`

  Mock a socket.

  See `FileMock`.

class `asynctest.``SSLSocketMock`(side_effect=None, return_value=sentinel.DEFAULT, wraps=None, name=None, spec_set=None, parent=None, **kwargs)

  Bases: `asynctest.selector.SocketMock`

  Mock a socket wrapped by the `ssl` module.

  See `FileMock`.

  New in version 0.5.

class `asynctest.``FileDescriptor`

  Bases: `int`

  A subclass of int which allows to identify the virtual file-descriptor of a `FileMock`.

  If `FileDescriptor()` without argument, its value will be the value of `next_fd`.

  When an object is created, `next_fd` is set to the highest value for a `FileDescriptor` object + 1.

  `next_fd` = 0

### Helpers

`asynctest.``fd`(fileobj)

  Return the `FileDescriptor` value of `fileobj`.

  If `fileobj` is a `FileDescriptor`, `fileobj` is returned, else `fileobj.fileno()` is returned instead.

  Note that if fileobj is an int, `ValueError` is raised.

  Raises: | ValueError – if `fileobj` is not a `FileMock`, a file-like object or a `FileDescriptor`.

`asynctest.``isfilemock`(obj)

  Return `True` if the `obj` or `obj.fileno()` is a `asynctest.FileDescriptor`.

## Mocking the selector

class `asynctest.``TestSelector`(selector=None)

  A selector which supports IOMock objects.

  It can wrap an actual implementation of a selector, so the selector will work both with mocks and real file-like objects.

  A common use case is to patch the selector loop:

      loop._selector = asynctest.TestSelector(loop._selector)

  Parameters: | selector – optional, if provided, this selector will be used to work with real file-like objects.

  `close`()

    Close the selector.

    Close the actual selector if supplied, unregister all mocks.

    See `selectors.BaseSelector.close()`.

  `modify`(fileobj, events, data=None)

    Shortcut when calling `TestSelector.unregister()` then `TestSelector.register()` to update the registration of a an object to the selector.

    See `selectors.BaseSelector.modify()`.

  `register`(fileobj, events, data=None)

    Register a file object or a `FileMock`.

    If a real selector object has been supplied to the `TestSelector` object and `fileobj` is not a `FileMock` or a `FileDescriptor` returned by `FileMock.fileno()`, the object will be registered to the real selector.

    See `selectors.BaseSelector.register()`.

  `select`(timeout=None)

    Perform the selection.

    This method is a no-op if no actual selector has been supplied.

    See `selectors.BaseSelector.select()`.

  `unregister`(fileobj)

    Unregister a file object or a `FileMock`.

    See `selectors.BaseSelector.unregister()`.

### Helpers

`asynctest.``set_read_ready`(fileobj, loop)

  Schedule callbacks registered on `loop` as if the selector notified that data is ready to be read on `fileobj`.

  Parameters:

  - fileobj – file object or `FileMock` on which the event is mocked.
  - loop – `asyncio.SelectorEventLoop` watching for events on `fileobj`.

      mock = asynctest.SocketMock()
      mock.recv.return_value = b"Data"

      def read_ready(sock):
          print("received:", sock.recv(1024))

      loop.add_reader(mock, read_ready, mock)

      set_read_ready(mock, loop)

      loop.run_forever() # prints received: b"Data"

  New in version 0.4.

`asynctest.``set_write_ready`(fileobj, loop)

  Schedule callbacks registered on `loop` as if the selector notified that data can be written to `fileobj`.

  Parameters:

  - fileobj – file object or `FileMock` on which th event is mocked.
  - loop – `asyncio.SelectorEventLoop` watching for events on `fileobj`.

  New in version 0.4.