From 9499c74ec40d59c42272453f262ac9ee256146e0 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Tue, 23 Jun 2026 12:40:20 +0300 Subject: [PATCH 1/3] gh-151950: Document `async.BaseEventLoop` and fix `asyncio-extending.rst` --- Doc/library/asyncio-eventloop.rst | 10 ++++++++++ Doc/library/asyncio-extending.rst | 7 +++++-- Doc/tools/.nitignore | 1 - 3 files changed, 15 insertions(+), 3 deletions(-) diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 79c9516cda2d60..54f42aec487620 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -1917,6 +1917,16 @@ By default asyncio is configured to use :class:`EventLoop`. methods that an alternative implementation of ``AbstractEventLoop`` should have defined. +.. class:: BaseEventLoop + + Abstract base class for asyncio-compliant event loops. + Inherits from :class:`AbstractEventLoop` directly. + + Has many methods of ``AbstractEventLoop`` implemented, so end users + would have less methods to implement themselfs. + But, instead forces to implement some internal protected API methods. + See :ref:`writting_custom_event_loop` for more information. + Examples ======== diff --git a/Doc/library/asyncio-extending.rst b/Doc/library/asyncio-extending.rst index e7b293f484f8de..8f94c79a03569a 100644 --- a/Doc/library/asyncio-extending.rst +++ b/Doc/library/asyncio-extending.rst @@ -15,11 +15,14 @@ classes. Asyncio has helpers that could be used to simplify this task. in *internal* part of API. +.. _writting_custom_event_loop: + Writing a Custom Event Loop =========================== -:class:`asyncio.AbstractEventLoop` declares very many methods. Implementing all them -from scratch is a tedious job. +:class:`asyncio.AbstractEventLoop` declares very many methods. +See :ref:`asyncio-event-loop-methods` for the full list. +Implementing all them from scratch is a tedious job. A loop can get many common methods implementation for free by inheriting from :class:`asyncio.BaseEventLoop`. diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 2255c745c00383..8845bfb143d808 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -6,7 +6,6 @@ Doc/c-api/init_config.rst Doc/c-api/intro.rst Doc/c-api/stable.rst Doc/library/ast.rst -Doc/library/asyncio-extending.rst Doc/library/email.charset.rst Doc/library/email.parser.rst Doc/library/http.cookiejar.rst From 842bc138e1257d5c9dc025be40f970388ba6afe5 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Tue, 23 Jun 2026 13:35:10 +0300 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Stan Ulbrych --- Doc/library/asyncio-eventloop.rst | 15 ++++++++------- Doc/library/asyncio-extending.rst | 6 +++--- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 54f42aec487620..d9d421d7a8f5c3 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -1919,13 +1919,14 @@ By default asyncio is configured to use :class:`EventLoop`. .. class:: BaseEventLoop - Abstract base class for asyncio-compliant event loops. - Inherits from :class:`AbstractEventLoop` directly. - - Has many methods of ``AbstractEventLoop`` implemented, so end users - would have less methods to implement themselfs. - But, instead forces to implement some internal protected API methods. - See :ref:`writting_custom_event_loop` for more information. + A base class that partially implements :class:`AbstractEventLoop` + to simplify writing custom event loops. + + It provides default implementations of many :class:`AbstractEventLoop` + methods, so subclasses have fewer methods to implement themselves. + In return, a subclass is expected to implement a number of internal, + protected methods. + See :ref:`writing_custom_event_loop` for more information. Examples diff --git a/Doc/library/asyncio-extending.rst b/Doc/library/asyncio-extending.rst index 8f94c79a03569a..7b5dcab4ad1ee3 100644 --- a/Doc/library/asyncio-extending.rst +++ b/Doc/library/asyncio-extending.rst @@ -12,17 +12,17 @@ classes. Asyncio has helpers that could be used to simplify this task. Third-parties should reuse existing asyncio code with caution, a new Python version is free to break backward compatibility - in *internal* part of API. + in the *internal* part of the API. -.. _writting_custom_event_loop: +.. _writing_custom_event_loop: Writing a Custom Event Loop =========================== :class:`asyncio.AbstractEventLoop` declares very many methods. See :ref:`asyncio-event-loop-methods` for the full list. -Implementing all them from scratch is a tedious job. +Implementing them all from scratch is a tedious job. A loop can get many common methods implementation for free by inheriting from :class:`asyncio.BaseEventLoop`. From d068d193120c1b51b3a16f48c95c315aef66be8e Mon Sep 17 00:00:00 2001 From: sobolevn Date: Tue, 23 Jun 2026 13:47:03 +0300 Subject: [PATCH 3/3] Update Doc/library/asyncio-extending.rst Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- Doc/library/asyncio-extending.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/asyncio-extending.rst b/Doc/library/asyncio-extending.rst index 7b5dcab4ad1ee3..0be79359b75e32 100644 --- a/Doc/library/asyncio-extending.rst +++ b/Doc/library/asyncio-extending.rst @@ -17,7 +17,7 @@ classes. Asyncio has helpers that could be used to simplify this task. .. _writing_custom_event_loop: -Writing a Custom Event Loop +Writing a custom event loop =========================== :class:`asyncio.AbstractEventLoop` declares very many methods.