# -*- coding: utf-8 -*-
from distutils.core import setup


setup_kwargs = {
    'name': 'aionursery',
    'version': '0.1.1',
    'description': 'Manage background asyncio tasks',
    'long_description': "aionursery\n==========\n\nThis library implements a Nursery object, similar to trio's Nursery_ for ``asyncio``.\n\n.. _Nursery: http://trio.readthedocs.io/en/latest/reference-core.html#nurseries-and-spawning\n\n.. code-block:: python\n\n    async def child():\n        ...\n\n    async def parent():\n        async with aionursery.Nursery() as nursery:\n            # Make two concurrent calls to child\n            nursery.start_soon(child())\n            nursery.start_soon(child())\n\n\nTasks form a tree: when you run your main coroutine (via ``asyncio.get_event_loop().run_until_complete`` or ``asyncio.run``), this creates an initial task, and all your other tasks will be children, grandchildren, etc. of the main task.\n\nThe body of the ``async with`` block acts like an initial task that's running inside the nursery, and then each call to ``nursery.start_soon`` adds another task that runs in parallel.\n\nKeep in mind that:\n\n* If any task inside the nursery raises an unhandled exception, then the nursery immediately cancels all the tasks inside the nursery.\n\n* Since all of the tasks are running concurrently inside the async with block, the block does not exit until all tasks have completed. If you’ve used other concurrency frameworks, then you can think of it as, the de-indentation at the end of the async with automatically “joins” (waits for) all of the tasks in the nursery.\n\n* Once all the tasks have finished, then:\n  * The nursery is marked as “closed”, meaning that no new tasks can be started inside it.\n  * Any unhandled exceptions are re-raised inside the parent task. If there are multiple exceptions, then they’re collected up into a single MultiError exception.\n\nSince all tasks are descendents of the initial task, one consequence of this is that the parent can’t finish until all tasks have finished.\n\nPlease note that you can't reuse an already exited nursery. Trying to re-open it again, or to ``start_soon`` more tasks in it will raise ``NurseryClosed``.\n\nShielding some tasks from being cancelled\n-----------------------------------------\n\nSometimes, however, you need to have an opposite behavior: a child must execute no matter what exceptions are raised in other tasks.\nImagine a payment transaction running in one task, and an sms sending in another.\nYou certainly don't want an sms sending error to cancel a payment transaction.\n\nFor that, you can ``asyncio.shield`` your tasks before starting them in the nursery:\n\n.. code-block:: python\n\n    async def perform_payment():\n        ...\n\n    async def send_sms():\n        ...\n\n    async def parent():\n        async with Nursery() as nursery:\n            nursery.start_soon(asyncio.shield(perform_payment()))\n            nursery.start_soon(send_sms())\n\n\nGetting results from children\n-----------------------------\n\nIf your background tasks are not quite long-lived and return some useful values that you want to process, you can gather all tasks into a list and use ``asyncio.wait`` (or similar functions) as usual:\n\n.. code-block:: python\n\n    async def parent():\n        async with Nursery() as nursery:\n            task_foo = nursery.start_soon(foo())\n            task_bar = nursery.start_soon(bar())\n            results = await asyncio.wait([task_foo, task_bar])\n\n\nIf your background tasks are long-lived, you should use ``asyncio.Queue`` to pass objects between children and parent tasks:\n\n.. code-block:: python\n\n    async def child(queue):\n        while True:\n            data = await from_external_system()\n            await queue.put(data)\n\n    async def parent():\n        queue = asyncio.Queue()\n        async with Nursery() as nursery:\n            nursery.start_soon(child(queue))\n            while some_condition():\n                data = await queue.get()\n                await do_stuff_with(data)\n\n\nIntegration with ``async_timeout``\n----------------------------------\n\nYou can wrap a nursery in a ``async_timeout.timeout`` context manager.\nWhen timeout happens, the whole nursery cancels:\n\n.. code-block:: python\n\n    from async_timeout import timeout\n\n    async def child():\n        await asyncio.sleep(1000 * 1000)\n\n    async def parent():\n        async with timeout(10):\n            async with Nursery() as nursery:\n                nursery.start_soon(child())\n                await asyncio.sleep(1000 * 1000)\n",
    'author': 'Dmitry Malinovsky',
    'author_email': 'damalinov@gmail.com',
    'url': None,
    'py_modules': 'aionursery',
    'python_requires': '>=3.4,<4.0',
}


setup(**setup_kwargs)
