Metadata-Version: 2.1
Name: async_stagger
Version: 0.1.3
Summary: Happy eyeballs and underlying scheduling algorithm in asyncio
Home-page: https://github.com/twisteroidambassador/async_stagger
Author: twisteroid ambassador
Author-email: twisteroid.ambassador@gmail.com
License: MIT
Project-URL: Documentation, http://async_stagger.readthedocs.io
Description: async_stagger: Happy Eyeballs in ``asyncio``
        ############################################
        
        Quick, what's the situation?
        ============================
        
        To get all the benefits of Happy Eyeballs connection establishment algorithm,
        simply use ``async_stagger.open_connection`` like you would use
        ``asyncio.open_connection``::
        
            reader, writer = await async_stagger.open_connection('www.example.com', 80)
        
        Now your connections are more dual-stack friendly and will complete faster!
        A replacement for ``loop.create_connection`` is also provided.
        
        The long version
        ================
        
        What is Happy Eyeballs, and why should I use it?
        ------------------------------------------------
        
        Happy Eyeballs is an algorithm for establishing TCP connections to destinations
        specified by host names. It is described in `RFC 6555`_ and `RFC 8305`_. The
        primary benefit is that when host name resolution returns multiple addresses,
        and some of the address are unreachable, Happy Eyeballs will establish the
        connection much faster than conventional algorithms. For more information,
        check the `Wikipedia article on Happy Eyeballs`_.
        
        .. _RFC 6555: https://tools.ietf.org/html/rfc6555
        .. _RFC 8305: https://tools.ietf.org/html/rfc8305
        .. _Wikipedia article on Happy Eyeballs: https://en.wikipedia.org/wiki/Happy_Eyeballs
        
        Python's standard library provides several high-level methods of establishing
        TCP connections towards a host name: The **socket** module has
        ``socket.create_connection``,
        and **asyncio** has ``loop.create_connection`` and ``asyncio.open_connection``.
        These methods have the same behavior when a host name resolves to several IP
        addresses: they try to connect to the first address in the list,
        and only after the attempt fails (which may take tens of seconds) will
        the second one be tried, and so on. In contrast, the Happy Eyeballs algorithm
        will start an attempt with the second IP address in parallel to the first one
        hasn't completed after some time, typically around 300 milliseconds.
        As a result several attempts may be in flight at the same time, and whenever
        one of the attempts succeed, all other connections are cancelled, and the
        winning connection is used.
        This means a much shorter wait before one of the IP addresses connect
        successfully.
        
        Happy Eyeballs is particularly important for dual-stack clients, when some hosts
        may have resolvable IPv6 addresses that are somehow unreachable.
        
        
        What does ``async_stagger`` has to offer?
        -----------------------------------------
        
        ``async_stagger`` provides ``open_connection`` and
        ``create_connection`` with Happy Eyeballs support. They are mostly drop-in
        replacements for their ``asyncio`` counterparts, and support most existing
        arguments.
        (There are small differences: ``create_connection`` takes
        a *loop* argument instead of being a method on an event loop.
        Also, these two methods do not support the *sock* argument.)
        Another public coroutine ``create_connected_sock`` returns a connected
        ``socket.socket`` object.
        
        These methods support additional optional arguments: *delay* and *interleave*
        control Happy Eyeballs behavior, and *local_addrs* allows specifying multiple
        local addresses to bind to. Check the documentation for details.
        
        
        Happy Eyeballs sounds great! I want to use similar logic somewhere else!
        ------------------------------------------------------------------------
        
        You're in luck! ``async_stagger`` actually exposes the underlying scheduling
        logic as a reusable block: ``staggered_race``. It can be use when:
        
        * There are several ways to achieve one goal. Some of the ways may fail, but
          you have to try it to find out.
        
        * Making attempts strictly in sequence is too slow.
        
        * You want to parallelize, but also don't want to start the attempts all
          at the same time. Maybe you want to give preference to some of the attempts,
          so they should be started earlier and given more time to complete. Maybe you
          want to avoid straining the system with simultaneous attempts.
        
        * An attempt done half-way can be rolled back safely.
        
        
        Where can I get it?
        -------------------
        
        ``async_stagger`` requires Python 3.6 or later. (It doesn't work on Python 3.5
        for a somewhat trivial reason: trailing commas in function definition argument
        lists. If those pesky commas are removed, the code should probably run well
        enough.)
        It does not have any external
        dependencies. Install it from PyPI the usual way::
        
            pip install async-stagger
        
        The documentation can be found here:
        http://async-stagger.readthedocs.io/en/latest/
        
        This project is licensed under the MIT license.
        
        
        Acknowledgments
        ===============
        
        The Happy Eyeballs scheduling algorithm implementation is inspired by
        `the implementation in trio`__.
        
        __ https://github.com/python-trio/trio/pull/145/files
        
        
Keywords: happy-eyeballs dual-stack tcp
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Framework :: AsyncIO
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
