1The basics
2==========
3
4.. py:currentmodule:: anyio
5
6AnyIO requires Python 3.6.2 or later to run. It is recommended that you set up a virtualenv_ when
7developing or playing around with AnyIO.
8
9Installation
10------------
11
12To install AnyIO, run:
13
14.. code-block:: bash
15
16    pip install anyio
17
18To install a supported version of trio_, you can install it as an extra like this:
19
20.. code-block:: bash
21
22    pip install anyio[trio]
23
24Running async programs
25----------------------
26
27The simplest possible AnyIO program looks like this::
28
29    from anyio import run
30
31
32    async def main():
33        print('Hello, world!')
34
35    run(main)
36
37This will run the program above on the default backend (asyncio). To run it on another supported
38backend, say trio_, you can use the ``backend`` argument, like so::
39
40    run(main, backend='trio')
41
42But AnyIO code is not required to be run via :func:`run`. You can just as well use the native
43``run()`` function of the backend library::
44
45    import sniffio
46    import trio
47    from anyio import sleep
48
49
50    async def main():
51        print('Hello')
52        await sleep(1)
53        print("I'm running on", sniffio.current_async_library())
54
55    trio.run(main)
56
57.. _backend options:
58
59Backend specific options
60------------------------
61
62Asyncio:
63
64* ``debug`` (``bool``, default=False): Enables `debug mode`_ in the event loop
65* ``use_uvloop`` (``bool``, default=False): Use the faster uvloop_ event loop implementation, if
66  available
67* ``policy`` (``AbstractEventLoopPolicy``, default=None): the event loop policy instance to use
68  for creating a new event loop (overrides ``use_uvloop``)
69
70Trio: options covered in the
71`official documentation <https://trio.readthedocs.io/en/stable/reference-core.html#trio.run>`_
72
73.. note:: The default value of ``use_uvloop`` was ``True`` before v3.2.0.
74
75.. _debug mode: https://docs.python.org/3/library/asyncio-eventloop.html#enabling-debug-mode
76.. _uvloop: https://pypi.org/project/uvloop/
77
78Using native async libraries
79----------------------------
80
81AnyIO lets you mix and match code written for AnyIO and code written for the asynchronous framework
82of your choice. There are a few rules to keep in mind however:
83
84* You can only use "native" libraries for the backend you're running, so you cannot, for example,
85  use a library written for trio together with a library written for asyncio.
86* Tasks spawned by these "native" libraries on backends other than trio_ are not subject to the
87  cancellation rules enforced by AnyIO
88* Threads spawned outside of AnyIO cannot use :func:`.from_thread.run` to call asynchronous code
89
90.. _virtualenv: https://docs.python-guide.org/dev/virtualenvs/
91.. _trio: https://github.com/python-trio/trio
92