glossary improvements, rename some rules, add some intersphinx links

Author: jakkdl

docs/glossary.rst

@@ -74,27 +74,51 @@ A collection of child Tasks that can run concurrently. Internally contains a :re
   * :class:`asyncio.TaskGroup` (since python 3.11)
 
 
+.. _cancellation:
 .. _cancelled:
 
 Cancelled / CancelledError
 --------------------------
 
 Handling cancellation is very sensitive, and you generally never want to catch a cancellation exception without letting it propagate to the library.
 
-  * Trio: :class:`trio.Cancelled`. `Documentation <https://trio.readthedocs.io/en/stable/reference-core.html#cancellation-and-timeouts>`__
-  * AnyIO: :func:`anyio.get_cancelled_exc_class`. `Documentation <https://anyio.readthedocs.io/en/stable/cancellation.html>`__
-  * asyncio: :class:`asyncio.CancelledError`. `Documentation <https://docs.python.org/3/library/asyncio-task.html#task-cancellation>`__
+General documentation on cancellation in the different async libraries:
+
+* `Trio <https://trio.readthedocs.io/en/stable/reference-core.html#cancellation-and-timeouts>`__
+* `AnyIO <https://anyio.readthedocs.io/en/stable/cancellation.html>`__
+* `asyncio <https://docs.python.org/3/library/asyncio-task.html#task-cancellation>`__
+
+Exception classes:
+
+* :class:`trio.Cancelled`
+* :func:`anyio.get_cancelled_exc_class`
+* :class:`asyncio.CancelledError`
 
 .. _checkpoint:
 
 Checkpoint
 ----------
-Checkpoints are ``await``, ``async for``, and ``async with`` (on at least one of enter/exit). TODO write more and link stuff
+Checkpoints are points where the async backend checks for cancellation and invokes scheduling checks. Possible checkpoints are ``await``, ``async for`` (before each iteration, and when exhausting the iterator), and ``async with`` (on at least one of enter/exit).
+
+Trio has extensive and detailed documentation on the concept of :external+trio:ref:`checkpoints <checkpoints>`, and guarantees that all trio async functions will checkpoint (unless they raised an exception).
+
+anyio does not currently have any documentation on checkpoints.
+
+asyncio will checkpoint... ???
+
+To make it easier to reason about checkpoints the :ref:`ASYNC91x <ASYNC910>` rules enforces the same rules as trio for your own project - i.e. all async functions must guarantee a checkpoint (or exception). To make it possible to reason the rules will also assume that all other async functions also adhere to those rules. This means you must be careful if you're using 3rd-party async libraries.
+
 
 .. _channel_stream_queue:
 
 Channel / Stream / Queue
 ------------------------
-* Trio: `channel <https://trio.readthedocs.io/en/stable/reference-core.html#channels>`__
-* AnyIO: `stream <https://anyio.readthedocs.io/en/stable/streams.html#streams>`__
-* asyncio: `queue <https://docs.python.org/3/library/asyncio-queue.html>`__
+Interfaces used for communicating between tasks, processes, the network, etc.
+
+.. anyio streams is a :doc: and not a :label:, so we can't link with intersphinx :(
+
+.. _anyio_streams: https://anyio.readthedocs.io/en/stable/streams.html#streams
+
+* Trio has :ref:`channels <channels>` for python objects and :ref:`streams <abstract-stream-api>` for bytes.
+* AnyIO has ``byte`` and ``object`` `streams <anyio_streams>`_
+* asyncio has :ref:`queues <asyncio-queues>` for python objects and :ref:`streams <asyncio-streams>` for bytes.

docs/rules.rst

@@ -1,6 +1,6 @@
-****************
-List of rules
-****************
+*****
+Rules
+*****
 
 
 General rules
@@ -40,7 +40,7 @@ ASYNC109 : async-function-with-timeout
     Async function definition with a ``timeout`` parameter.
     In structured concurrency the caller should instead use :ref:`timeout context managers <timeout_context>`.
 
-ASYNC110 : busy-wait
+ASYNC110 : async-busy-wait
     ``while ...: await [trio/anyio].sleep()`` should be replaced by a :class:`trio.Event`/:class:`anyio.Event`.
 
 ASYNC111 : variable-from-cm-in-start-soon
@@ -57,7 +57,7 @@ ASYNC113 : start-soon-in-aenter
 ASYNC114 : startable-not-in-config
     Startable function (i.e. has a ``task_status`` keyword parameter) not in :ref:`--startable-in-context-manager <--startable-in-context-manager>` parameter list, please add it so ASYNC113 can catch errors when using it.
 
-ASYNC115 : sleep-zero
+ASYNC115 : async-zero-sleep
     Replace :func:`trio.sleep(0) <trio.sleep>`/:func:`anyio.sleep(0) <anyio.sleep>` with the more suggestive :func:`trio.lowlevel.checkpoint`/:func:`anyio.lowlevel.checkpoint`.
 
 ASYNC116 : long-sleep-not-forever
@@ -78,44 +78,44 @@ Blocking sync calls in async functions
 .. _httpx.Client: https://www.python-httpx.org/api/#client
 .. _httpx.AsyncClient: https://www.python-httpx.org/api/#asyncclient
 .. _urllib3: https://github.com/urllib3/urllib3
-
-Note: 22X, 23X and 24X has not had asyncio-specific suggestions written.
+.. _aiofiles: https://pypi.org/project/aiofiles/
+.. _anyio: https://github.com/agronholm/anyio
 
 ASYNC200 : blocking-configured-call
     User-configured error for blocking sync calls in async functions.
     Does nothing by default, see :ref:`async200-blocking-calls` for how to configure it.
 
 ASYNC210 : blocking-http-call
     Sync HTTP call in async function, use `httpx.AsyncClient`_.
-    This and the other ASYNC21x checks look for usage of `urllib3`_ and `httpx.Client`_, and recommend using `httpx.AsyncClient`_ as that's the largest http client supporting anyio/trio.
+    This and the other :ref:`ASYNC21x <ASYNC211>` checks look for usage of `urllib3`_ and `httpx.Client`_, and recommend using `httpx.AsyncClient`_ as that's the largest http client supporting anyio/trio.
 
-ASYNC211 : blocking-http-call-pool
+_`ASYNC211` : blocking-http-call-pool
     Likely sync HTTP call in async function, use `httpx.AsyncClient`_.
     Looks for `urllib3`_ method calls on pool objects, but only matching on the method signature and not the object.
 
 ASYNC212 : blocking-http-call-httpx
     Blocking sync HTTP call on httpx object, use `httpx.AsyncClient`_.
 
 ASYNC220 : blocking-create-subprocess
-    Sync call to :class:`subprocess.Popen` (or equivalent) in async function, use :func:`trio.run_process`/:func:`anyio.run_process` in a :ref:`taskgroup_nursery`. ``asyncio`` users can use `asyncio.create_subprocess_[exec/shell] <https://docs.python.org/3/library/asyncio-subprocess.html>`_.
+    Sync call to :class:`subprocess.Popen` (or equivalent) in async function, use :func:`trio.run_process`/:func:`anyio.run_process`/:ref:`asyncio.create_subprocess_[exec/shell] <asyncio-subprocess>` in a :ref:`taskgroup_nursery`.
 
 ASYNC221 : blocking-run-process
-    Sync call to :func:`subprocess.run` (or equivalent) in async function, use :func:`trio.run_process`/:func:`anyio.run_process`. ``asyncio`` users can use `asyncio.create_subprocess_[exec/shell] <https://docs.python.org/3/library/asyncio-subprocess.html>`_.
+    Sync call to :func:`subprocess.run` (or equivalent) in async function, use :func:`trio.run_process`/:func:`anyio.run_process`/:ref:`asyncio.create_subprocess_[exec/shell] <asyncio-subprocess>`.
 
 ASYNC222 : blocking-process-wait
-    Sync call to :func:`os.wait` (or equivalent) in async function, wrap in :func:`trio.to_thread.run_sync`/:func:`anyio.to_thread.run_sync`. ``asyncio`` users can use `asyncio.loop.run_in_executor <https://docs.python.org/3/library/asyncio-subprocess.html>`_.
+    Sync call to :func:`os.wait` (or equivalent) in async function, wrap in :func:`trio.to_thread.run_sync`/:func:`anyio.to_thread.run_sync`/:meth:`asyncio.loop.run_in_executor`.
 
 ASYNC230 : blocking-open-call
-    Sync call to :func:`open` in async function, use :func:`trio.open_file`/:func:`anyio.open_file`. ``asyncio`` users need to use a library such as `aiofiles <https://pypi.org/project/aiofiles/>`_, or switch to `anyio <https://github.com/agronholm/anyio>`_.
+    Sync call to :func:`open` in async function, use :func:`trio.open_file`/:func:`anyio.open_file`. ``asyncio`` users need to use a library such as `aiofiles`_, or switch to `anyio`_.
 
 ASYNC231 : blocking-fdopen-call
-    Sync call to :func:`os.fdopen` in async function, use :func:`trio.wrap_file`/:func:`anyio.wrap_file`. ``asyncio`` users need to use a library such as `aiofiles <https://pypi.org/project/aiofiles/>`_, or switch to `anyio <https://github.com/agronholm/anyio>`_.
+    Sync call to :func:`os.fdopen` in async function, use :func:`trio.wrap_file`/:func:`anyio.wrap_file`. ``asyncio`` users need to use a library such as `aiofiles`_, or switch to `anyio`_.
 
 ASYNC232 : blocking-file-call
     Blocking sync call on file object, wrap the file object in :func:`trio.wrap_file`/:func:`anyio.wrap_file` to get an async file object.
 
 ASYNC240 : blocking-path-usage
-    Avoid using :mod:`os.path` in async functions, prefer using :class:`trio.Path`/:class:`anyio.Path` objects. ``asyncio`` users should consider `aiopath <https://pypi.org/project/aiopath>`__ or `anyio <https://github.com/agronholm/anyio>`__.
+    Avoid using :mod:`os.path` in async functions, prefer using :class:`trio.Path`/:class:`anyio.Path` objects. ``asyncio`` users should consider `aiopath <https://pypi.org/project/aiopath>`__ or `anyio`_.
 
 ASYNC250 : blocking-input
     Builtin :func:`input` should not be called from async function.