Skip to content

Formatting fixes in contextlib page #98111

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 12, 2022
Merged

Formatting fixes in contextlib page #98111

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7dcc7d0
Fix some formatting in contextlib page
slateny Oct 9, 2022
e66f8e9
Separate code definition and code execution
slateny Oct 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 33 additions & 35 deletions Doc/library/contextlib.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -249,15 +249,15 @@ Functions and classes provided:
:ref:`asynchronous context managers <async-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

Expand Down Expand Up @@ -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')
Expand Down Expand Up @@ -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):
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm a little sad that this makes the code harder to copy-paste, but agree that this improves consistency. I guess the idea in the existing code was to have no >>> for the code defining the sample classes, only for the code using them. I am going to look at the rest of the docs to see whether that's an established convention.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If that was the idea, then I think the code block can just be split into two with something like 'managed_resource can then be used like the following:', and have the second chunk contain the >>>

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i.e.:
image

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that would be better, thanks!

... 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')
Expand Down