From 7dcc7d05ff12fdd73542cd88659ee83bf9c11666 Mon Sep 17 00:00:00 2001 From: slateny <46876382+slateny@users.noreply.github.com> Date: Sat, 8 Oct 2022 18:20:01 -0700 Subject: [PATCH 1/2] Fix some formatting in contextlib page --- Doc/library/contextlib.rst | 68 ++++++++++++++++++-------------------- 1 file changed, 33 insertions(+), 35 deletions(-) diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index 2d28fb35a9e316..027f4d1ff4f54a 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -66,9 +66,9 @@ Functions and classes provided: # Code to release resource, e.g.: release_resource(resource) - >>> with managed_resource(timeout=3600) as resource: - ... # Resource is released at the end of this block, - ... # even if code in the block raises an exception + with managed_resource(timeout=3600) as resource: + # Resource is released at the end of this block, + # even if code in the block raises an exception The function being decorated must return a :term:`generator`-iterator when called. This iterator must yield exactly one value, which will be bound to @@ -140,9 +140,9 @@ Functions and classes provided: finally: print(f'it took {time.monotonic() - now}s to run') - @timeit() - async def main(): - # ... async code ... + @timeit() + async def main(): + # ... async code ... When used as a decorator, a new generator instance is implicitly created on each function call. This allows the otherwise "one-shot" context managers @@ -249,15 +249,15 @@ Functions and classes provided: :ref:`asynchronous context managers `:: async def send_http(session=None): - if not session: - # If no http session, create it with aiohttp - cm = aiohttp.ClientSession() - else: - # Caller is responsible for closing the session - cm = nullcontext(session) + if not session: + # If no http session, create it with aiohttp + cm = aiohttp.ClientSession() + else: + # Caller is responsible for closing the session + cm = nullcontext(session) - async with cm as session: - # Send http requests with session + async with cm as session: + # Send http requests with session .. versionadded:: 3.7 @@ -385,17 +385,16 @@ Functions and classes provided: Example of ``ContextDecorator``:: - from contextlib import ContextDecorator - - class mycontext(ContextDecorator): - def __enter__(self): - print('Starting') - return self - - def __exit__(self, *exc): - print('Finishing') - return False + >>> from contextlib import ContextDecorator + >>> class mycontext(ContextDecorator): + ... def __enter__(self): + ... print('Starting') + ... return self + ... def __exit__(self, *exc): + ... print('Finishing') + ... return False + ... >>> @mycontext() ... def function(): ... print('The bit in the middle') @@ -454,18 +453,17 @@ Functions and classes provided: Example of ``AsyncContextDecorator``:: - from asyncio import run - from contextlib import AsyncContextDecorator - - class mycontext(AsyncContextDecorator): - async def __aenter__(self): - print('Starting') - return self - - async def __aexit__(self, *exc): - print('Finishing') - return False + >>> from asyncio import run + >>> from contextlib import AsyncContextDecorator + >>> class mycontext(AsyncContextDecorator): + ... async def __aenter__(self): + ... print('Starting') + ... return self + ... async def __aexit__(self, *exc): + ... print('Finishing') + ... return False + ... >>> @mycontext() ... async def function(): ... print('The bit in the middle') From e66f8e95e0856e939ced3eb1ed21d15828abe962 Mon Sep 17 00:00:00 2001 From: slateny <46876382+slateny@users.noreply.github.com> Date: Tue, 11 Oct 2022 20:10:50 -0700 Subject: [PATCH 2/2] Separate code definition and code execution --- Doc/library/contextlib.rst | 52 ++++++++++++++++++++++---------------- 1 file changed, 30 insertions(+), 22 deletions(-) diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index 027f4d1ff4f54a..1b55868c3aa62f 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -66,9 +66,11 @@ Functions and classes provided: # Code to release resource, e.g.: release_resource(resource) - with managed_resource(timeout=3600) as resource: - # Resource is released at the end of this block, - # even if code in the block raises an exception + The function can then be used like this:: + + >>> with managed_resource(timeout=3600) as resource: + ... # Resource is released at the end of this block, + ... # even if code in the block raises an exception The function being decorated must return a :term:`generator`-iterator when called. This iterator must yield exactly one value, which will be bound to @@ -385,16 +387,19 @@ Functions and classes provided: Example of ``ContextDecorator``:: - >>> from contextlib import ContextDecorator + from contextlib import ContextDecorator + + class mycontext(ContextDecorator): + def __enter__(self): + print('Starting') + return self + + def __exit__(self, *exc): + print('Finishing') + return False + + The class can then be used like this:: - >>> class mycontext(ContextDecorator): - ... def __enter__(self): - ... print('Starting') - ... return self - ... def __exit__(self, *exc): - ... print('Finishing') - ... return False - ... >>> @mycontext() ... def function(): ... print('The bit in the middle') @@ -453,17 +458,20 @@ Functions and classes provided: Example of ``AsyncContextDecorator``:: - >>> from asyncio import run - >>> from contextlib import AsyncContextDecorator + from asyncio import run + from contextlib import AsyncContextDecorator + + class mycontext(AsyncContextDecorator): + async def __aenter__(self): + print('Starting') + return self + + async def __aexit__(self, *exc): + print('Finishing') + return False + + The class can then be used like this:: - >>> class mycontext(AsyncContextDecorator): - ... async def __aenter__(self): - ... print('Starting') - ... return self - ... async def __aexit__(self, *exc): - ... print('Finishing') - ... return False - ... >>> @mycontext() ... async def function(): ... print('The bit in the middle')