8000 Add Documentation for `__aenter__` and `__aexit__` Methods (#3907) · guillemap/python-telegram-bot@af130ef · GitHub
[go: up one dir, main page]
Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit af130ef

Browse files
clot27Aditya
clot27
and
Aditya
authored
Add Documentation for __aenter__ and __aexit__ Methods (python-telegram-bot#3907)
Co-authored-by: Aditya <clot27@apx_managed.vanilla>
1 parent 9ef8826 commit af130ef

File tree

7 files changed

+87
-6
lines changed

7 files changed

+87
-6
lines changed

‎docs/source/conf.py

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,12 @@
7777
# and we document the types anyway
7878
autodoc_typehints = "none"
7979

80+
# Show docstring for special members
81+
autodoc_default_options = {
82+
"special-members": True,
83+
"exclude-members": "__init__",
84+
}
85+
8086
# Fail on warnings & unresolved references etc
8187
nitpicky = True
8288

‎docs/substitutions/global.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,3 +61,5 @@
6161
.. |removed_thumb_url_note| replace:: Removed the deprecated argument and attribute ``thumb_url``.
6262

6363
.. |removed_thumb_wildcard_note| replace:: Removed the deprecated arguments and attributes ``thumb_*``.
64+
65+
.. |async_context_manager| replace:: Asynchronous context manager which

‎telegram/_bot.py

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,8 @@ class Bot(TelegramObject, AsyncContextManager["Bot"]):
149149
finally:
150150
await bot.shutdown()
151151
152+
.. seealso:: :meth:`__aenter__` and :meth:`__aexit__`.
153+
152154
Note:
153155
* Most bot methods have the argument ``api_kwargs`` which allows passing arbitrary keywords
154156
to th 10000 e Telegram API. This can be used to access new features of the API before they are
@@ -310,6 +312,16 @@ def __init__(
310312
self._freeze()
311313

312314
async def __aenter__(self: BT) -> BT:
315+
"""
316+
|async_context_manager| :meth:`initializes <initialize>` the Bot.
317+
318+
Returns:
319+
The initialized Bot instance.
320+
321+
Raises:
322+
:exc:`Exception`: If an exception is raised during initialization, :meth:`shutdown`
323+
is called in this case.
324+
"""
313325
try:
314326
await self.initialize()
315327
return self
@@ -323,6 +335,7 @@ async def __aexit__(
323335
exc_val: Optional[BaseException],
324336
exc_tb: Optional[TracebackType],
325337
) -> None:
338+
"""|async_context_manager| :meth:`shuts down <shutdown>` the Bot."""
326339
# Make sure not to return `True` so that exceptions are not suppressed
327340
# https://docs.python.org/3/reference/datamodel.html?#object.__aexit__
328341
await self.shutdown()

‎telegram/ext/_application.py

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,8 @@ class Application(Generic[BT, CCT, UD, CD, BD, JQ], AsyncContextManager["Applica
149149
finally:
150150
await application.shutdown()
151151
152+
.. seealso:: :meth:`__aenter__` and :meth:`__aexit__`.
153+
152154
Examples:
153155
:any:`Echo Bot <examples.echobot>`
154156
@@ -345,7 +347,15 @@ def __init__(
345347
self.__create_task_tasks: Set[asyncio.Task] = set() # Used for awaiting tasks upon exit
346348

347349
async def __aenter__(self: _AppType) -> _AppType: # noqa: PYI019
348-
"""Simple context manager which initializes the App."""
350+
"""|async_context_manager| :meth:`initializes <initialize>` the App.
351+
352+
Returns:
353+
The initialized App instance.
354+
355+
Raises:
356+
:exc:`Exception`: If an exception is raised during initialization, :meth:`shutdown`
357+
is called in this case.
358+
"""
349359
try:
350360
await self.initialize()
351361
return self
@@ -359,7 +369,7 @@ async def __aexit__(
359369
exc_val: Optional[BaseException],
360370
exc_tb: Optional[TracebackType],
361371
) -> None:
362-
"""Shutdown the App from the context manager."""
372+
"""|async_context_manager| :meth:`shuts down <shutdown>` the App."""
363373
# Make sure not to return `True` so that exceptions are not suppressed
364374
# https://docs.python.org/3/reference/datamodel.html?#object.__aexit__
365375
await self.shutdown()

‎telegram/ext/_baseupdateprocessor.py

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,25 @@ class BaseUpdateProcessor(ABC):
2727
"""An abstract base class for update processors. You can use this class to implement
2828
your own update processor.
2929
30+
Instances of this class can be used as asyncio context managers, where
31+
32+
.. code:: python
33+
34+
async with processor:
35+
# code
36+
37+
is roughly equivalent to
38+
39+
.. code:: python
40+
41+
try:
42+
await processor.initialize()
43+
# code
44+
finally:
45+
await processor.shutdown()
46+
47+
.. seealso:: :meth:`__aenter__` and :meth:`__aexit__`.
48+
3049
.. seealso:: :wiki:`Concurrency`
3150
3251
.. versionadded:: 20.4
@@ -49,7 +68,15 @@ def __init__(self, max_concurrent_updates: int):
4968
self._semaphore = BoundedSemaphore(self.max_concurrent_updates)
5069

5170
async def __aenter__(self) -> "BaseUpdateProcessor":
52-
"""Simple context manager which initializes the Processor."""
71+
"""|async_context_manager| :meth:`initializes <initialize>` the Processor.
72+
73+
Returns:
74+
The initialized Processor instance.
75+
76+
Raises:
77+
:exc:`Exception`: If an exception is raised during initialization, :meth:`shutdown`
78+
is called in this case.
79+
"""
5380
try:
5481
await self.initialize()
5582
return self
@@ -63,7 +90,7 @@ async def __aexit__(
6390
exc_val: Optional[BaseException],
6491
exc_tb: Optional[TracebackType],
6592
) -> None:
66-
"""Simple context manager which shuts down the Processor."""
93+
"""|async_context_manager| :meth:`shuts down <shutdown>` the Processor."""
6794
await self.shutdown()
6895

6996
@property

‎telegram/ext/_updater.py

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,8 @@ class Updater(AsyncContextManager["Updater"]):
7878
finally:
7979
await updater.shutdown()
8080
81+
.. seealso:: :meth:`__aenter__` and :meth:`__aexit__`.
82+
8183
.. seealso:: :wiki:`Architecture Overview <Architecture>`,
8284
:wiki:`Builder Pattern <Builder-Pattern>`
8385
@@ -126,7 +128,16 @@ def __init__(
126128
self.__polling_cleanup_cb: Optional[Callable[[], Coroutine[Any, Any, None]]] = None
127129

128130
async def __aenter__(self: _UpdaterType) -> _UpdaterType: # noqa: PYI019
129-
"""Simple context manager which initializes the Updater."""
131+
"""
132+
|async_context_manager| :meth:`initializes <initialize>` the Updater.
133+
134+
Returns:
135+
The initialized Updater instance.
136+
137+
Raises:
138+
:exc:`Exception`: If an exception is raised during initialization, :meth:`shutdown`
139+
is called in this case.
140+
"""
130141
try:
131142
await self.initialize()
132143
return self
@@ -140,7 +151,7 @@ async def __aexit__(
140151
exc_val: Optional[BaseException],
141152
exc_tb: Optional[TracebackType],
142153
) -> None:
143-
"""Shutdown the Updater from the context manager."""
154+
"""|async_context_manager| :meth:`shuts down <shutdown>` the Updater."""
144155
# Make sure not to return `True` so that exceptions are not suppressed
145156
# https://docs.python.org/3/reference/datamodel.html?#object.__aexit__
146157
await self.shutdown()

‎telegram/request/_baserequest.py

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,8 @@ class BaseRequest(
7070
finally:
7171
await request_object.shutdown()
7272
73+
.. seealso:: :meth:`__aenter__` and :meth:`__aexit__`.
74+
7375
Tip:
7476
JSON encoding and decoding is done with the standard library's :mod:`json` by default.
7577
To use a custom library for this, you can override :meth:`parse_json_payload` and implement
@@ -99,6 +101,15 @@ class BaseRequest(
99101
"""
100102

101103
async def __aenter__(self: RT) -> RT:
104+
"""|async_context_manager| :meth:`initializes <initialize>` the Request.
105+
106+
Returns:
107+
The initialized Request instance.
108+
109+
Raises:
110+
:exc:`Exception`: If an exception is raised during initialization, :meth:`shutdown`
111+
is called in this case.
112+
"""
102113
try:
103114
await self.initialize()
104115
return self
@@ -112,6 +123,7 @@ async def __aexit__(
112123
exc_val: Optional[BaseException],
113124
exc_tb: Optional[TracebackType],
114125
) -> None:
126+
"""|async_context_manager| :meth:`shuts down <shutdown>` the Request."""
115127
# Make sure not to return `True` so that exceptions are not suppressed
116128
# https://docs.python.org/3/reference/datamodel.html?#object.__aexit__
117129
await self.shutdown()

0 commit comments

Comments
 (0)
0