Selectors2
==========
.. image:: https://img.shields.io/travis/SethMichaelLarson/selectors2/master.svg?style=flat-square
:target: https://travis-ci.org/SethMichaelLarson/selectors2
.. image:: https://img.shields.io/appveyor/ci/SethMichaelLarson/selectors2/master.svg?style=flat-square
:target: https://ci.appveyor.com/project/SethMichaelLarson/selectors2
.. image:: https://img.shields.io/pypi/v/selectors2.svg?style=flat-square
:target: https://pypi.python.org/pypi/selectors2
.. image:: https://img.shields.io/badge/say-thanks-ff69b4.svg?style=flat-square
:target: https://saythanks.io/to/SethMichaelLarson
Backported, durable, and portable selectors designed to replace
the standard library selectors module.
Features
--------
* Support for all major platforms. (Linux, Mac OS, Windows)
* Support for Python 2.6 or later and **Jython**.
* Support many different selectors
* ``select.kqueue`` (BSD, Mac OS)
* ``select.devpoll`` (Solaris)
* ``select.epoll`` (Linux 2.5.44+)
* ``select.poll`` (Linux, Mac OS)
* ``select.select`` - (Linux, Mac OS, Windows)
* Support for `PEP 475 <https://www.python.org/dev/peps/pep-0475/>`_ (Retries system calls on interrupt)
* Support for modules which monkey-patch the standard library after import (like greenlet, gevent)
* Support for systems which define a selector being available but don't actually implement it. ()
About
-----
This module was originally written by me for the `urllib3 <https://github.com/shazow/urllib3>`_ project
(history in PR `#1001 <https://github.com/shazow/urllib3/pull/1001>`_) but it was decided that it would
be beneficial for everyone to have access to this work.
All the additional features that ``selectors2`` provides are real-world problems that have occurred
and been reported during the lifetime of its maintenance and use within ``urllib3``.
If this work is useful to you, `feel free to say thanks <https://saythanks.io/to/SethMichaelLarson>`_,
takes only a little time and really brightens my day! :cake:
Can this module be used in place of ``selectors``?
--------------------------------------------------
Yes! This module is a 1-to-1 drop-in replacement for ``selectors`` and
provides all selector types that would be available in ``selectors`` including
``DevpollSelector``, ``KqueueSelector``, ``EpollSelector``, ``PollSelector``, and ``SelectSelector``.
What is different between `selectors2` and `selectors34`?
---------------------------------------------------------
This module is similar to ``selectors34`` in that it supports Python 2.6 - 3.3
but differs in that this module also implements PEP 475 for the backported selectors.
This allows similar behaviour between Python 3.5+ selectors and selectors from before PEP 475.
In ``selectors34``, an interrupted system call would result in an incorrect return of no events, which
for some use cases is not an acceptable behavior.
I will also add here that ``selectors2`` also makes large improvements on the test suite surrounding it
providing 100% test coverage for each selector. The test suite is also more robust and tests durability
of the selectors in many different situations that aren't tested in ``selectors34``.
What types of objects are supported?
------------------------------------
At this current time ``selectors2`` only support the ``SelectSelector`` for Windows which cannot select on non-socket objects.
On Linux and Mac OS, both sockets and pipes are supported (some other types may be supported as well, such as fifos or special file devices).
What if I have to support a platform without ``select.select``?
---------------------------------------------------------------
There are a few platforms that don't have a selector available, notably
Google AppEngine. When running on those platforms any call to ``DefaultSelector()``
will raise a ``RuntimeError`` explaining that there are no selectors available.
License
-------
This module is dual-licensed under MIT and PSF License.
Installation
------------
``$ python -m pip install selectors2``
Usage
-----
.. code-block:: python
import sys
import selectors2 as selectors
# Use DefaultSelector, it picks the best
# selector available for your platform! :)
s = selectors.DefaultSelector()
import socket
# We're going to use Google as an example.
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.connect(("www.google.com", 80))
# Register the file to be watched for write availibility.
s.register(sock, selectors.EVENT_WRITE)
# Give a timeout in seconds or no
# timeout to block until an event happens.
events = s.select(timeout=1.0)
# Loop over all events that happened.
for key, event in events:
if event & selectors.EVENT_WRITE:
key.fileobj.send(b'HEAD / HTTP/1.1\r\n\r\n')
# Change what event you're waiting for.
s.modify(sock, selectors.EVENT_READ)
# Timeout of None let's the selector wait as long as it needs to.
events = s.select(timeout=None)
for key, event in events:
if event & selectors.EVENT_READ:
data = key.fileobj.recv(4096)
print(data)
# Stop watching the socket.
s.unregister(sock)
sock.close()
Changelog
=========
Release 2.0.2 (July 21, 2020)
-----------------------------
* [BUGFIX] Added support for ``long`` integers in Python 2.x.
Release 2.0.1 (August 17, 2017)
-------------------------------
* [BUGFIX] Timeouts would not be properly recalculated after receiving an EINTR error.
Release 2.0.0 (May 30, 2017)
----------------------------
* [FEATURE] Add support for Jython with ``JythonSelectSelector``.
* [FEATURE] Add support for ``/dev/devpoll`` with ``DevpollSelector``.
* [CHANGE] Raises a ``RuntimeError`` instead of ``ValueError`` if there is no selector available.
* [CHANGE] No longer wraps exceptions in ``SelectorError``, raises original exception including
in timeout situations.
* [BUGFIX] Detect defects in a system that defines a selector but does not implement it.
* [BUGFIX] Can now detect a change in the ``select`` module after import such as when
``gevent.monkey.monkey_patch()`` is called before importing ``selectors2``.
Release 1.1.1 (February 6, 2017)
--------------------------------
* [BUGFIX] Platforms that define ``select.kqueue`` would not have ``KqueueSelector`` as the ``DefaultSelector``.
Release 1.1.0 (January 17, 2017)
--------------------------------
* [FEATURE] Make system calls faster for Python versions that support PEP 475.
* [FEATURE] Wheels are now universal.
Release 1.0.0 (November 3, 2016)
--------------------------------
* Initial implementation of ``selectors2``.
Raw data
{
"_id": null,
"home_page": "https://www.github.com/sethmlarson/selectors2",
"name": "selectors2",
"maintainer": "Seth Michael Larson",
"docs_url": null,
"requires_python": "",
"maintainer_email": "sethmichaellarson@gmail.com",
"keywords": "async,file,socket,select,backport",
"author": "Seth Michael Larson",
"author_email": "sethmichaellarson@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/86/72/27ccb21c1ff9fa87e1ba45e38045722b4eff345ba61760224793560638f4/selectors2-2.0.2.tar.gz",
"platform": "",
"description": "Selectors2\n==========\n\n.. image:: https://img.shields.io/travis/SethMichaelLarson/selectors2/master.svg?style=flat-square\n :target: https://travis-ci.org/SethMichaelLarson/selectors2\n.. image:: https://img.shields.io/appveyor/ci/SethMichaelLarson/selectors2/master.svg?style=flat-square\n :target: https://ci.appveyor.com/project/SethMichaelLarson/selectors2\n.. image:: https://img.shields.io/pypi/v/selectors2.svg?style=flat-square\n :target: https://pypi.python.org/pypi/selectors2\n.. image:: https://img.shields.io/badge/say-thanks-ff69b4.svg?style=flat-square\n :target: https://saythanks.io/to/SethMichaelLarson\n\nBackported, durable, and portable selectors designed to replace\nthe standard library selectors module.\n\nFeatures\n--------\n\n* Support for all major platforms. (Linux, Mac OS, Windows)\n* Support for Python 2.6 or later and **Jython**.\n* Support many different selectors\n * ``select.kqueue`` (BSD, Mac OS)\n * ``select.devpoll`` (Solaris)\n * ``select.epoll`` (Linux 2.5.44+)\n * ``select.poll`` (Linux, Mac OS)\n * ``select.select`` - (Linux, Mac OS, Windows)\n* Support for `PEP 475 <https://www.python.org/dev/peps/pep-0475/>`_ (Retries system calls on interrupt)\n* Support for modules which monkey-patch the standard library after import (like greenlet, gevent)\n* Support for systems which define a selector being available but don't actually implement it. ()\n\nAbout\n-----\n\nThis module was originally written by me for the `urllib3 <https://github.com/shazow/urllib3>`_ project\n(history in PR `#1001 <https://github.com/shazow/urllib3/pull/1001>`_) but it was decided that it would\nbe beneficial for everyone to have access to this work.\n\nAll the additional features that ``selectors2`` provides are real-world problems that have occurred\nand been reported during the lifetime of its maintenance and use within ``urllib3``.\n\nIf this work is useful to you, `feel free to say thanks <https://saythanks.io/to/SethMichaelLarson>`_,\ntakes only a little time and really brightens my day! :cake:\n\nCan this module be used in place of ``selectors``?\n--------------------------------------------------\n\nYes! This module is a 1-to-1 drop-in replacement for ``selectors`` and\nprovides all selector types that would be available in ``selectors`` including\n``DevpollSelector``, ``KqueueSelector``, ``EpollSelector``, ``PollSelector``, and ``SelectSelector``.\n\nWhat is different between `selectors2` and `selectors34`?\n---------------------------------------------------------\n\nThis module is similar to ``selectors34`` in that it supports Python 2.6 - 3.3\nbut differs in that this module also implements PEP 475 for the backported selectors.\nThis allows similar behaviour between Python 3.5+ selectors and selectors from before PEP 475.\nIn ``selectors34``, an interrupted system call would result in an incorrect return of no events, which\nfor some use cases is not an acceptable behavior.\n\nI will also add here that ``selectors2`` also makes large improvements on the test suite surrounding it\nproviding 100% test coverage for each selector. The test suite is also more robust and tests durability\nof the selectors in many different situations that aren't tested in ``selectors34``.\n\nWhat types of objects are supported?\n------------------------------------\n\nAt this current time ``selectors2`` only support the ``SelectSelector`` for Windows which cannot select on non-socket objects.\nOn Linux and Mac OS, both sockets and pipes are supported (some other types may be supported as well, such as fifos or special file devices).\n\nWhat if I have to support a platform without ``select.select``?\n---------------------------------------------------------------\n\nThere are a few platforms that don't have a selector available, notably\nGoogle AppEngine. When running on those platforms any call to ``DefaultSelector()``\nwill raise a ``RuntimeError`` explaining that there are no selectors available.\n\nLicense\n-------\n\nThis module is dual-licensed under MIT and PSF License.\n\nInstallation\n------------\n\n``$ python -m pip install selectors2``\n\nUsage\n-----\n.. code-block:: python\n\n import sys\n import selectors2 as selectors\n\n # Use DefaultSelector, it picks the best\n # selector available for your platform! :)\n s = selectors.DefaultSelector()\n\n import socket\n\n # We're going to use Google as an example.\n sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n sock.connect((\"www.google.com\", 80))\n\n # Register the file to be watched for write availibility.\n s.register(sock, selectors.EVENT_WRITE)\n\n # Give a timeout in seconds or no\n # timeout to block until an event happens.\n events = s.select(timeout=1.0)\n\n # Loop over all events that happened.\n for key, event in events:\n if event & selectors.EVENT_WRITE:\n key.fileobj.send(b'HEAD / HTTP/1.1\\r\\n\\r\\n')\n\n # Change what event you're waiting for.\n s.modify(sock, selectors.EVENT_READ)\n\n # Timeout of None let's the selector wait as long as it needs to.\n events = s.select(timeout=None)\n for key, event in events:\n if event & selectors.EVENT_READ:\n data = key.fileobj.recv(4096)\n print(data)\n\n # Stop watching the socket.\n s.unregister(sock)\n sock.close()\n\n\nChangelog\n=========\n\nRelease 2.0.2 (July 21, 2020)\n-----------------------------\n\n* [BUGFIX] Added support for ``long`` integers in Python 2.x.\n\nRelease 2.0.1 (August 17, 2017)\n-------------------------------\n\n* [BUGFIX] Timeouts would not be properly recalculated after receiving an EINTR error.\n\nRelease 2.0.0 (May 30, 2017)\n----------------------------\n\n* [FEATURE] Add support for Jython with ``JythonSelectSelector``.\n* [FEATURE] Add support for ``/dev/devpoll`` with ``DevpollSelector``.\n* [CHANGE] Raises a ``RuntimeError`` instead of ``ValueError`` if there is no selector available.\n* [CHANGE] No longer wraps exceptions in ``SelectorError``, raises original exception including\n in timeout situations.\n* [BUGFIX] Detect defects in a system that defines a selector but does not implement it.\n* [BUGFIX] Can now detect a change in the ``select`` module after import such as when\n ``gevent.monkey.monkey_patch()`` is called before importing ``selectors2``.\n\nRelease 1.1.1 (February 6, 2017)\n--------------------------------\n\n* [BUGFIX] Platforms that define ``select.kqueue`` would not have ``KqueueSelector`` as the ``DefaultSelector``.\n\nRelease 1.1.0 (January 17, 2017)\n--------------------------------\n\n* [FEATURE] Make system calls faster for Python versions that support PEP 475.\n* [FEATURE] Wheels are now universal.\n\nRelease 1.0.0 (November 3, 2016)\n--------------------------------\n\n* Initial implementation of ``selectors2``.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Back-ported, durable, and portable selectors",
"version": "2.0.2",
"split_keywords": [
"async",
"file",
"socket",
"select",
"backport"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "17dde86650dea607cca535f1785cc8a7",
"sha256": "c5092ff5d0bfb6b09e19371ba91c0e119ba61a8256c9837ca363e0c525032e16"
},
"downloads": -1,
"filename": "selectors2-2.0.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "17dde86650dea607cca535f1785cc8a7",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 11265,
"upload_time": "2020-07-21T22:40:20",
"upload_time_iso_8601": "2020-07-21T22:40:20.248491Z",
"url": "https://files.pythonhosted.org/packages/9a/4f/ea16bdfb793550c472ca4f2035337a3e90f31c1fe3f8d1a9227cd8b5542e/selectors2-2.0.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "77089bc7a640bf09f784cc029195c24a",
"sha256": "1f1bbaac203a23fbc851dc1b5a6e92c50698cc8cefa5873eb5b89eef53d1d82b"
},
"downloads": -1,
"filename": "selectors2-2.0.2.tar.gz",
"has_sig": false,
"md5_digest": "77089bc7a640bf09f784cc029195c24a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 18558,
"upload_time": "2020-07-21T22:40:21",
"upload_time_iso_8601": "2020-07-21T22:40:21.470344Z",
"url": "https://files.pythonhosted.org/packages/86/72/27ccb21c1ff9fa87e1ba45e38045722b4eff345ba61760224793560638f4/selectors2-2.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-07-21 22:40:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "sethmlarson",
"github_project": "selectors2",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"appveyor": true,
"tox": true,
"lcname": "selectors2"
}
JSON
