Merge branch 'master' into py38

Author: asvetlov

.gitignore

@@ -22,6 +22,7 @@ var/
 *.egg-info/
 .installed.cfg
 *.egg
+.hypothesis/
 
 # PyInstaller
 #  Usually these files are written by a python script from a template
@@ -55,3 +56,6 @@ docs/_build/
 
 # PyBuilder
 target/
+
+.venv*
+.idea

.travis.yml

@@ -3,18 +3,18 @@ language: python
 matrix:
   include:
     - python: 3.5
-      env: TOXENV=py35
+      env: TOX_ENV=py35
     - python: 3.6
-      env: TOXENV=py36
+      env: TOX_ENV=py36
     - python: 3.7
-      env: TOXENV=py37
+      env: TOX_ENV=py37
     - python: 3.8
-      env: TOXENV=py38
+      env: TOX_ENV=py38
 
-install:
-    - pip install tox
+install: pip install tox-travis coveralls
 
 script: tox
 
 after_success:
-    - pip install coveralls && cd tests && coveralls
+  - tox -e coverage-report
+  - coveralls

README.rst

@@ -7,6 +7,9 @@ pytest-asyncio: pytest support for asyncio
     :target: https://travis-ci.org/pytest-dev/pytest-asyncio
 .. image:: https://coveralls.io/repos/pytest-dev/pytest-asyncio/badge.svg
     :target: https://coveralls.io/r/pytest-dev/pytest-asyncio
+.. image:: https://img.shields.io/pypi/pyversions/pytest-asyncio.svg
+    :target: https://github.com/pytest-dev/pytest-asyncio
+    :alt: Supported Python versions
 
 pytest-asyncio is an Apache2 licensed library, written in Python, for testing
 asyncio code with pytest.
@@ -18,8 +21,8 @@ provides useful fixtures and markers to make testing easier.
 .. code-block:: python
 
     @pytest.mark.asyncio
-    def test_some_asyncio_code()
-        res = yield from library.do_something()
+    async def test_some_asyncio_code():
+        res = await library.do_something()
         assert b'expected result' == res
 
 pytest-asyncio has been strongly influenced by pytest-tornado_.
@@ -30,8 +33,10 @@ Features
 --------
 
 - fixtures for creating and injecting versions of the asyncio event loop
+- fixtures for injecting unused tcp ports
 - pytest markers for treating tests as asyncio coroutines
-
+- easy testing with non-default event loops
+- support for `async def` fixtures and async generator fixtures
 
 Installation
 ------------
@@ -49,46 +54,210 @@ Fixtures
 
 ``event_loop``
 ~~~~~~~~~~~~~~
-Creates and injects a new instance of the default asyncio event loop. The loop
-will be closed at the end of the test.
+Creates and injects a new instance of the default asyncio event loop. By
+default, the loop will be closed at the end of the test (i.e. the default
+fixture scope is ``function``).
 
 Note that just using the ``event_loop`` fixture won't make your test function
 a coroutine. You'll need to interact with the event loop directly, using methods
 like ``event_loop.run_until_complete``. See the ``pytest.mark.asyncio`` marker
 for treating test functions like coroutines.
 
+Simply using this fixture will not set the generated event loop as the
+default asyncio event loop, or change the asyncio event loop policy in any way.
+Use ``pytest.mark.asyncio`` for this purpose.
+
 .. code-block:: python
 
     def test_http_client(event_loop):
         url = 'http://httpbin.org/get'
         resp = event_loop.run_until_complete(http_client(url))
         assert b'HTTP/1.1 200 OK' in resp
 
-``event_loop_process_pool``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The ``event_loop_process_pool`` fixture is almost identical to the
-``event_loop`` fixture, except the created event loop will have a
-``concurrent.futures.ProcessPoolExecutor`` set as the default executor.
+This fixture can be easily overridden in any of the standard pytest locations
+(e.g. directly in the test file, or in ``conftest.py``) to use a non-default
+event loop. This will take effect even if you're using the
+``pytest.mark.asyncio`` marker and not the ``event_loop`` fixture directly.
+
+.. code-block:: python
+
+    @pytest.yield_fixture()
+    def event_loop():
+        loop = MyCustomLoop()
+        yield loop
+        loop.close()
+
+If the ``pytest.mark.asyncio`` marker is applied, a pytest hook will
+ensure the produced loop is set as the default global loop.
+Fixtures depending on the ``event_loop`` fixture can expect the policy to be properly modified when they run.
 
 ``unused_tcp_port``
 ~~~~~~~~~~~~~~~~~~~
-Finds and yields an unused TCP port on the localhost interface. Useful for
+Finds and yields a single unused TCP port on the localhost interface. Useful for
 binding temporary test servers.
 
+``unused_tcp_port_factory``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A callable which returns a different unused TCP port each invocation. Useful
+when several unused TCP ports are required in a test.
+
+.. code-block:: python
+
+    def a_test(unused_tcp_port_factory):
+        port1, port2 = unused_tcp_port_factory(), unused_tcp_port_factory()
+        ...
+
+Async fixtures
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Asynchronous fixtures are defined just like ordinary pytest fixtures, except they should be coroutines or asynchronous generators.
+
+.. code-block:: python3
+
+    @pytest.fixture
+    async def async_gen_fixture():
+        await asyncio.sleep(0.1)
+        yield 'a value'
+
+    @pytest.fixture(scope='module')
+    async def async_fixture():
+        return await asyncio.sleep(0.1)
+
+All scopes are supported, but if you use a non-function scope you will need
+to redefine the ``event_loop`` fixture to have the same or broader scope.
+Async fixtures need the event loop, and so must have the same or narrower scope
+than the ``event_loop`` fixture.
+
+If you want to do this with Python 3.5, the ``yield`` statement must be replaced with ``await yield_()`` and the coroutine
+function must be decorated with ``@async_generator``, like so:
+
+.. code-block:: python3
+
+    from async_generator import yield_, async_generator
+
+    @pytest.fixture
+    @async_generator
+    async def async_gen_fixture():
+        await asyncio.sleep(0.1)
+        await yield_('a value')
+
+
 Markers
 -------
 
 ``pytest.mark.asyncio``
-~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Mark your test coroutine with this marker and pytest will execute it as an
 asyncio task using the event loop provided by the ``event_loop`` fixture. See
 the introductory section for an example.
 
-``pytest.mark.asyncio_process_pool``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The ``asyncio_process_pool`` marker is almost identical to the ``asyncio``
-marker, except the event loop used will have a
-``concurrent.futures.ProcessPoolExecutor`` set as the default executor.
+The event loop used can be overriden by overriding the ``event_loop`` fixture
+(see above).
+
+In order to make your test code a little more concise, the pytest |pytestmark|_
+feature can be used to mark entire modules or classes with this marker.
+Only test coroutines will be affected (by default, coroutines prefixed by
+``test_``), so, for example, fixtures are safe to define.
+
+.. code-block:: python
+
+    import asyncio
+    import pytest
+
+    # All test coroutines will be treated as marked.
+    pytestmark = pytest.mark.asyncio
+
+    async def test_example(event_loop):
+        """No marker!"""
+        await asyncio.sleep(0, loop=event_loop)
+
+.. |pytestmark| replace:: ``pytestmark``
+.. _pytestmark: http://doc.pytest.org/en/latest/example/markers.html#marking-whole-classes-or-modules
+
+Changelog
+---------
+
+0.11.0 (UNRELEASED)
+~~~~~~~~~~~~~~~~~~~
+
+0.10.0 (2019-01-08)
+~~~~~~~~~~~~~~~~~~~~
+- ``pytest-asyncio`` integrates with `Hypothesis <https://hypothesis.readthedocs.io>`_
+  to support ``@given`` on async test functions using ``asyncio``.
+  `#102` <https://github.com/pytest-dev/pytest-asyncio/pull/102>
+- Pytest 4.1 support.
+  `#105` <https://github.com/pytest-dev/pytest-asyncio/pull/105>
+
+0.9.0 (2018-07-28)
+~~~~~~~~~~~~~~~~~~
+- Python 3.7 support.
+- Remove ``event_loop_process_pool`` fixture and
+  ``pytest.mark.asyncio_process_pool`` marker (see
+  https://bugs.python.org/issue34075 for deprecation and removal details)
+
+0.8.0 (2017-09-23)
+~~~~~~~~~~~~~~~~~~
+- Improve integration with other packages (like aiohttp) with more careful event loop handling.
+  `#64` <https://github.com/pytest-dev/pytest-asyncio/pull/64>
+
+0.7.0 (2017-09-08)
+~~~~~~~~~~~~~~~~~~
+- Python versions pre-3.6 can use the async_generator library for async fixtures.
+  `#62 <https://github.com/pytest-dev/pytest-asyncio/pull/62>`
+
+
+0.6.0 (2017-05-28)
+~~~~~~~~~~~~~~~~~~
+- Support for Python versions pre-3.5 has been dropped.
+- ``pytestmark`` now works on both module and class level.
+- The ``forbid_global_loop`` parameter has been removed.
+- Support for async and async gen fixtures has been added.
+  `#45 <https://github.com/pytest-dev/pytest-asyncio/pull/45>`_
+- The deprecation warning regarding ``asyncio.async()`` has been fixed.
+  `#51 <https://github.com/pytest-dev/pytest-asyncio/pull/51>`_
+
+0.5.0 (2016-09-07)
+~~~~~~~~~~~~~~~~~~
+- Introduced a changelog.
+  `#31 <https://github.com/pytest-dev/pytest-asyncio/issues/31>`_
+- The ``event_loop`` fixture is again responsible for closing itself.
+  This makes the fixture slightly harder to correctly override, but enables
+  other fixtures to depend on it correctly.
+  `#30 <https://github.com/pytest-dev/pytest-asyncio/issues/30>`_
+- Deal with the event loop policy by wrapping a special pytest hook,
+  ``pytest_fixture_setup``. This allows setting the policy before fixtures
+  dependent on the ``event_loop`` fixture run, thus allowing them to take
+  advantage of the ``forbid_global_loop`` parameter. As a consequence of this,
+  we now depend on pytest 3.0.
+  `#29 <https://github.com/pytest-dev/pytest-asyncio/issues/29>`_
+
+
+0.4.1 (2016-06-01)
+~~~~~~~~~~~~~~~~~~
+- Fix a bug preventing the propagation of exceptions from the plugin.
+  `#25 <https://github.com/pytest-dev/pytest-asyncio/issues/25>`_
+
+0.4.0 (2016-05-30)
+~~~~~~~~~~~~~~~~~~
+- Make ``event_loop`` fixtures simpler to override by closing them in the
+  plugin, instead of directly in the fixture.
+  `#21 <https://github.com/pytest-dev/pytest-asyncio/pull/21>`_
+- Introduce the ``forbid_global_loop`` parameter.
+  `#21 <https://github.com/pytest-dev/pytest-asyncio/pull/21>`_
+
+0.3.0 (2015-12-19)
+~~~~~~~~~~~~~~~~~~
+- Support for Python 3.5 ``async``/``await`` syntax.
+  `#17 <https://github.com/pytest-dev/pytest-asyncio/pull/17>`_
+
+0.2.0 (2015-08-01)
+~~~~~~~~~~~~~~~~~~
+- ``unused_tcp_port_factory`` fixture.
+  `#10 <https://github.com/pytest-dev/pytest-asyncio/issues/10>`_
+
+
+0.1.1 (2015-04-23)
+~~~~~~~~~~~~~~~~~~
+Initial release.
 
 
 Contributing

pytest_asyncio/__init__.py

@@ -1 +1,2 @@
-__version__ = '0.1.3'
+"""The main point for importing pytest-asyncio items."""
+__version__ = "0.11.0dev0"