First draft of manual #47
Conversation
Codecov Report
@@ Coverage Diff @@
## master #47 +/- ##
=======================================
Coverage 99.34% 99.34%
=======================================
Files 19 19
Lines 457 457
Branches 44 44
=======================================
Hits 454 454
Misses 2 2
Partials 1 1Continue to review full report at Codecov.
|
Fixes python-triogh-9 Documentation in python-triogh-47
Fixes python-triogh-9 Documentation in python-triogh-47
docs/source/index.rst
Outdated
|
|
||
| * Use `Hypothesis <https://hypothesis.works/>`__? This plugin | ||
| integrates with Hypothesis, so your async tests can use | ||
| property-based testing. |
There was a problem hiding this comment.
Wouldn't it be useful here to have a word about hypothesis-trio and the fact you need it to run stateful tests ? (we could put it in the Integration with the Hypothesis library chapter for instance)
There was a problem hiding this comment.
Yeah, we should totally point to it! I've added some text to reference.rst. I don't think I understand well enough what hypothesis-trio actually does yet to figure out if we should put something in the little blurb here in index.rst, so for now I didn't – but of course we can always add it later.
docs/source/quickstart.rst
Outdated
|
|
||
| Probably our first attempt will look something like:: | ||
|
|
||
| # DON'T DO THIS, IT DOESN'T WORK |
There was a problem hiding this comment.
Not sure why you say this doesn't work, this code seems to work perfectly:
import trio
import pytest
from functools import partial
async def echo_server_handler(stream):
while True:
data = await stream.receive_some(1000)
if not data:
break
await stream.send_all(data)
@pytest.fixture
async def echo_server_connection():
async with trio.open_nursery() as nursery:
listeners = await nursery.start(
partial(trio.serve_tcp, echo_server_handler, port=0)
)
yield listeners[0]
nursery.cancel_scope.cancel()
@pytest.mark.trio
async def test_connection(echo_server_connection):
client = await trio.testing.open_stream_to_socket_listener(echo_server_connection)
async with client:
for test_byte in [b"a", b"c", b"c"]:
await client.send_all(test_byte)
assert await client.receive_some(1) == test_byteBeside that's a pattern I find extremely useful in my own tests, for instance:
with the backend_factory scope creating it own nursery to guarantee the backend in fully destroyed once we left the scope:
The great thing I find about this is you don't end up with a root nursery containing all the coroutines which make make it much harder to tell which one is responsible when your test hangs with a deadlock.
There was a problem hiding this comment.
Unfortunately, we're both right – it doesn't work, and it's extremely useful. Since the text is correct I'm going to leave it for now, and let's discuss how we can fix it over here: #55
docs/source/reference.rst
Outdated
|
|
||
| * Async tests have to be decorated with ``@pytest.mark.trio`` | ||
| * Async fixtures have to be decorated with | ||
| ``@pytest_trio.trio_fixture`` (instead of ``@pytest.fixture``). |
There was a problem hiding this comment.
But tests decorated with pytest.mark.trio can still detect and run async fixture marked with pytest.fixture, right ?
So I would say pytest_trio.trio_fixture is only useful if you want to have a synchronous fixture (with no asynchronous dependencies) running within the trio loop...
I seems you explain this lower, so I guess it's fine to have it not 100% accurate here ;-)
There was a problem hiding this comment.
Oops, right, this text got confused – I originally wrote this thinking that async fixtures would always require either trio-mode or trio_fixture, then I switched to automatically coercing async fixtures used by pytest.mark.trio-tests, but I didn't update this text.
@trio_fixture is also useful to explicitly declare that a fixture is a trio fixture, so e.g. if you accidentally try to use it with a synchronous or asyncio test then you'll get a nice error message instead of some weird crash.
After sleeping on #51 and investigating some more, I think I actually want to switch the behavior again, to the union of the two things we've talked about: if trio-mode is enabled then all async fixtures are automatically converted to trio fixtures, and even when trio-mode is disabled then all async fixtures that are used by a trio test are automatically converted to trio fixtures. That keeps the current convenience for when we're not in non-trio-mode (and is backwards compatible), and then for projects that use trio-mode it also lets us catch mistakes like bad scopes or using async fixtures with a non-trio test.
|
This is currently a little out-of-date with #50, so don't merge it yet :-)
|
The fixture setup code doesn't have convenient access to config file settings, and also keying the automagic-async-fixture-handling off of the trio-mode setting would be a compatibility break. Not the end of the world, but kind of annoying. Instead, let's continue to key the automagic-async-fixture-handling off of the requesting test being a Trio test. It's just as convenient, and while technically could be a little more error-prone – specifically, if you accidentally use an async fixture with a non-async test, then we won't be able to catch that as an error – I doubt it matters much in practice. And if people turn out to make that mistake a lot, we can always add some check for it later.
Also wrote some draft release notes
|
Updated to match the latest changes in #50, + added some draft release notes, + rebased. |
|
Once this goes in, I think we're ready to release v0.5.0. (@touilleMan, do you want to do the honors, or shall I?) This release cycle is weird: there's no newsfragments, but in this PR I manually added some news to the |
| open a nursery, pass it in to your function, and then cancel it for | ||
| you afterwards: | ||
|
|
||
| .. code-block:: python3 |
There was a problem hiding this comment.
This and other codeblocks aren't showing up in github's rst preview. Doc issue or github issue??
| trio fixture | ||
| * a number of easy-to-make mistakes are now caught and raise | ||
| informative errors | ||
| * the :data:`nursery` fixture is now 87% more magical |
There was a problem hiding this comment.
Did you round the magical percentage here ? 
There was a problem hiding this comment.
Do you think it needs more decimal points?
|
@njsmith I'll let you merge this PR and do the release |
I think this is pretty comprehensive and complete. It probably needs
some editing.
Also, we shouldn't merge it yet because it's inaccurate: it describes
the way things should work, rather than the way they actually work
right now :-). So before merging, we should:
Fixes: #5