README.rst
1Eventlet is a concurrent networking library for Python that allows you to change how you run your code, not how you write it.
2
3It uses epoll or libevent for highly scalable non-blocking I/O. Coroutines ensure that the developer uses a blocking style of programming that is similar to threading, but provide the benefits of non-blocking I/O. The event dispatch is implicit, which means you can easily use Eventlet from the Python interpreter, or as a small part of a larger application.
4
5It's easy to get started using Eventlet, and easy to convert existing
6applications to use it. Start off by looking at the `examples`_,
7`common design patterns`_, and the list of `basic API primitives`_.
8
9.. _examples: http://eventlet.net/doc/examples.html
10.. _common design patterns: http://eventlet.net/doc/design_patterns.html
11.. _basic API primitives: http://eventlet.net/doc/basic_usage.html
12
13
14Quick Example
15===============
16
17Here's something you can try right on the command line::
18
19 % python3
20 >>> import eventlet
21 >>> from eventlet.green.urllib.request import urlopen
22 >>> gt = eventlet.spawn(urlopen, 'http://eventlet.net')
23 >>> gt2 = eventlet.spawn(urlopen, 'http://secondlife.com')
24 >>> gt2.wait()
25 >>> gt.wait()
26
27
28Getting Eventlet
29==================
30
31The easiest way to get Eventlet is to use pip::
32
33 pip install -U eventlet
34
35To install latest development version once::
36
37 pip install -U https://github.com/eventlet/eventlet/archive/master.zip
38
39
40Building the Docs Locally
41=========================
42
43To build a complete set of HTML documentation, you must have Sphinx, which can be found at http://sphinx.pocoo.org/ (or installed with `pip install Sphinx`)::
44
45 cd doc
46 make html
47
48The built html files can be found in doc/_build/html afterward.
49
50
51Twisted
52=======
53
54Eventlet had Twisted hub in the past, but community interest to this integration has dropped over time,
55now it is not supported, so with apologies for any inconvenience we discontinue Twisted integration.
56
57If you have a project that uses Eventlet with Twisted, your options are:
58
59* use last working release eventlet==0.14
60* start a new project with only Twisted hub code, identify and fix problems. As of eventlet 0.13, `EVENTLET_HUB` environment variable can point to external modules.
61* fork Eventlet, revert Twisted removal, identify and fix problems. This work may be merged back into main project.
62
63Apologies for any inconvenience.
64
65Supported Python versions
66=========================
67
68Currently CPython 2.7 and 3.4+ are supported, but **2.7 and 3.4 support is deprecated and will be removed in the future**, only CPython 3.5+ support will remain.
69
70Flair
71=====
72
73.. image:: https://img.shields.io/pypi/v/eventlet
74 :target: https://pypi.org/project/eventlet/
75
76.. image:: https://img.shields.io/github/workflow/status/eventlet/eventlet/test/master
77 :target: https://github.com/eventlet/eventlet/actions?query=workflow%3Atest+branch%3Amaster
78
79.. image:: https://codecov.io/gh/eventlet/eventlet/branch/master/graph/badge.svg
80 :target: https://codecov.io/gh/eventlet/eventlet
81
