<commit_before>.. _async_usage:

==================
Asynchronous Usage
==================

The asynchronous Kazoo API relies on the
:class:`~kazoo.interfaces.IAsyncResult` object which is returned by all the
asynchronous methods. Callbacks can be added with the
:meth:`~kazoo.interfaces.IAsyncResult.rawlink` method which works in a
consistent manner whether threads or an asynchronous framework like gevent is
used.

Kazoo utilizes a pluggable :class:`~kazoo.interfaces.IHandler` interface which
abstracts the callback system to ensure it works consistently.

Connection Handling
===================

Creating a connection:

.. code-block:: python

    from kazoo.client import KazooClient
    from kazoo.handlers.gevent import SequentialGeventHandler

    zk = KazooClient(handler=SequentialGeventHandler())

    # returns immediately
    async_obj = zk.connect_async()

    # Wait for the connection to be established, this will throw
    # an exception if there's one during the connection attempt
    async_obj.get()

In this example, the :meth:`~kazoo.interfaces.IAsyncResult.get` method is used
to wait and get the value which is set when a connection is established. In the
event the connection has failed than an exception is raised. The
:class:`~kazoo.handlers.gevent.SequentialGeventHandler` is used when you want
to use gevent, kazoo doesn't rely on gevents monkey patching and requires that
you pass in the appropriate handler.


Chaining a connection callback:

.. code-block:: python

    import sys

    from kazoo.exceptions import ConnectionLossException
    from kazoo.exceptions import NoAuthException

    def my_handler(async_obj):
        try:
            async_obj.get()
            do_something()
        except (ConnectionLossException, NoAuthException):
            sys.exit(1)

    # Both of these statements return immediately
    async_obj = zk.connect_async()
    async_obj.rawlink(my_handler)

For the :meth:`~kazoo.client.KazooClient.connect_async` method, the resulting
value when the connection succeeds isn't relevant. For other asynchronous<commit_msg>Show proper async connect example with timeout and connection checking. Fixes #10.<commit_after>.. _async_usage:

==================
Asynchronous Usage
==================

The asynchronous Kazoo API relies on the
:class:`~kazoo.interfaces.IAsyncResult` object which is returned by all the
asynchronous methods. Callbacks can be added with the
:meth:`~kazoo.interfaces.IAsyncResult.rawlink` method which works in a
consistent manner whether threads or an asynchronous framework like gevent is
used.

Kazoo utilizes a pluggable :class:`~kazoo.interfaces.IHandler` interface which
abstracts the callback system to ensure it works consistently.

Connection Handling
===================

Creating a connection:

.. code-block:: python

    from kazoo.client import KazooClient
    from kazoo.handlers.gevent import SequentialGeventHandler

    zk = KazooClient(handler=SequentialGeventHandler())

    # returns immediately
    event = zk.connect_async()

    # Wait for 30 seconds and see if we're connected
    event.wait(timeout=30)

    if not zk.connected:
        # Not connected, stop trying to connect
        zk.stop()
        raise Exception("Unable to connect.")

In this example, the `wait` method is used on the event object returned by the
:meth:`~kazoo.client.KazooClient.connect_async` method. A timeout is **always**
used because its possible that we might never connect and that should be
handled gracefully. 

The :class:`~kazoo.handlers.gevent.SequentialGeventHandler` is used when you
want to use gevent, kazoo doesn't rely on gevents monkey patching and requires
that you pass in the appropriate handler.


Chaining a connection callback:

.. code-block:: python

    import sys

    from kazoo.exceptions import ConnectionLossException
    from kazoo.exceptions import NoAuthException

    def my_handler(async_obj):
        try:
            async_obj.get()
            do_something()
        except (ConnectionLossException, NoAuthException):
            sys.exit(1)

    # Both of these statements return immediately
    async_obj = zk.connect_async()
    async_obj.rawlink(my_handler)

For the :meth:`~kazoo.client.KazooClient.connect_async` method, the resulting
value when the connection succeeds isn't relevant. For other asynchronous
{'fraction_non_alphanumeric': 0.08651633686148182, 'fraction_numerical': 0.0018407731247123793, 'mean_word_length': 4.16270783847981, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4399013', 'n_tokens_mistral': 1224, 'n_tokens_neox': 1148, 'n_words': 440}