From 9c929fb4d9a5e745782fc14fb59a40ecddb26634 Mon Sep 17 00:00:00 2001 From: Adrian Herrmann Date: Fri, 19 Jul 2024 12:45:03 +0200 Subject: QtAsyncio: Add developer notes Add a few developer notes for QtAsyncio to our corresponding docs section. Pick-to: 6.7 Task-number: PYSIDE-769 Change-Id: I33cf5e1580fc93c9c90fd4e9573ad6c08d13ef13 Reviewed-by: Shyamnath Premnadh --- sources/pyside6/doc/developer/index.rst | 1 + sources/pyside6/doc/developer/qtasyncio.rst | 67 +++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+) create mode 100644 sources/pyside6/doc/developer/qtasyncio.rst (limited to 'sources/pyside6/doc/developer') diff --git a/sources/pyside6/doc/developer/index.rst b/sources/pyside6/doc/developer/index.rst index 92c84259d..88247a962 100644 --- a/sources/pyside6/doc/developer/index.rst +++ b/sources/pyside6/doc/developer/index.rst @@ -19,6 +19,7 @@ Development Topics documentation.rst adapt_qt.rst extras.rst + qtasyncio.rst Implementation details ---------------------- diff --git a/sources/pyside6/doc/developer/qtasyncio.rst b/sources/pyside6/doc/developer/qtasyncio.rst new file mode 100644 index 000000000..75196d83c --- /dev/null +++ b/sources/pyside6/doc/developer/qtasyncio.rst @@ -0,0 +1,67 @@ +.. _developer-qtasyncio: + +QtAsyncio developer notes +========================= + +QtAsyncio is a module that provides integration between Qt and Python's +`asyncio`_ module. It allows you to run `asyncio` event loops in a Qt +application, and to use Qt APIs from `asyncio` coroutines. + +.. _asyncio: https://docs.python.org/3/library/asyncio.html + +As a pure Python module that integrates deeply with another Python +module, developing for QtAsyncio has some interesting aspects that +differ from other parts of Qt for Python. + +QtAsyncio vs asyncio +-------------------- + +QtAsyncio has an interesting property from a developer perspective. As +one of its purposes is to be a transparent replacement to asyncio's own +event loop, for any given code that uses asyncio APIs, QtAsyncio will +(or should!) behave identically to asyncio. (Note that the reverse does +not apply if we also have Qt code). This is especially handy when +debugging, as one can run the asyncio code to compare and to check the +expected behavior. It also helps to debug both QtAsyncio and asyncio +step by step and compare the program flow to find where QtAsyncio might +go wrong (as far as their code differences allow). Often, one will also +be able to implement a unit test by asserting that QtAsyncio's output is +identical to asyncio's. (Note that a limitation to this is the fact that +Qt's event loop does not guarantee the order of execution of callbacks, +while asyncio does.) + +The step function +----------------- + +When debugging, a significant amount of time will likely be spent inside +the ``_step`` method of the ``QAsyncioTask`` class, as it is called +often and it is where coroutines are executed. You will find that it is +similar to asyncio's equivalent method, but with some differences. Read +the in-line comments carefully. Some variables and associated lines of +code might seem innocuous or even unnecessary, but provide important bug +fixes. + +Keeping QtAsyncio in sync with asyncio +-------------------------------------- + +QtAsyncio implements `asyncio's API `_, +which can change with new releases. As it is part of the standard +library, this lines up with new Python versions. It is therefore good +practice to check whether the API has changed for every new Python +version. This can include new classes or methods, changed signatures for +existing functions, deprecations or outright removals. For example, +event loop policies are expected to be deprecated with Python 3.13, with +subsequent removal in Python 3.15. This removal will in turn require a +small refactoring to make sure the ``QtAsyncio.run()`` function no +longer uses the policy mechanism. + +asyncio developer guidance +-------------------------- + +asyncio's resources go beyond the pure API documentation. E.g., asyncio +provides its own `developer guidance `_ +that is worth following when developing for QtAsyncio. In addition, +there is documentation for +`extending asyncio `_ +that details a few essential points to keep in mind when building your +own event loop. -- cgit v1.2.3