Merge remote-tracking branch 'origin/main' into async_fun_could_be_sync

Author: jakkdl

.github/workflows/ci.yml

@@ -30,7 +30,7 @@ jobs:
         runs-on: ubuntu-latest
         strategy:
             matrix:
-                python-version: ['3.9', '3.10', '3.11', '3.12', 3.13-dev]
+                python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
             fail-fast: false
         steps:
             - uses: actions/checkout@v4
@@ -62,10 +62,21 @@ jobs:
             - name: Run tests
               run: python -m tox -e flake8_7 -- --onlyfuzz --no-cov -n auto
 
+    check_release:
+        runs-on: ubuntu-latest
+        strategy:
+            fail-fast: false
+        steps:
+            - uses: actions/checkout@v4
+            - name: Set up Python 3
+              uses: actions/setup-python@v5
+            - name: Test changelog & version
+              run: python tests/check_changelog_and_version.py
+
     release:
         runs-on: ubuntu-latest
-        needs: [pyright, test]
-        if: github.repository == 'python-trio/flake8-async' &&  github.ref == 'refs/heads/main'
+        needs: [pyright, test, check_release]
+        if: github.repository == 'python-trio/flake8-async' && github.ref == 'refs/heads/main'
         steps:
             - uses: actions/checkout@v4
             - name: Set up Python 3
@@ -77,5 +88,4 @@ jobs:
                   TWINE_USERNAME: __token__
                   TWINE_PASSWORD: ${{ secrets.TWINE_PASSWORD }}
               run: |
-                  python tests/test_changelog_and_version.py --ensure-tag
                   python -m build && twine upload --skip-existing dist/*

.pre-commit-config.yaml

@@ -3,12 +3,13 @@ default_language_version:
     python: python3.12
 # pyright requires internet connection to run, which the pre-commit ci app doesn't have.
 # it instead runs in a github action
+# check-release-changelog is run as a dedicated job
 ci:
-    skip: [pyright]
+    skip: [pyright, check-release-changelog]
 
 repos:
     - repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.7.1
+      rev: v0.9.2
       hooks:
           - id: ruff
             args: [--fix]
@@ -25,7 +26,7 @@ repos:
           - id: autoflake
 
     - repo: https://github.com/asottile/pyupgrade
-      rev: v3.19.0
+      rev: v3.19.1
       hooks:
           - id: pyupgrade
             args: [--py39-plus]
@@ -37,14 +38,14 @@ repos:
           - id: isort
 
     - repo: https://github.com/pre-commit/mirrors-mypy
-      rev: v1.13.0
+      rev: v1.14.1
       hooks:
           - id: mypy
             # uses py311 syntax, mypy configured for py39
             exclude: tests/eval_files/.*_py311.py
 
     - repo: https://github.com/RobertCraigie/pyright-python
-      rev: v1.1.386
+      rev: v1.1.392.post0
       hooks:
           - id: pyright
             # ignore warnings about new version being available, no other warnings
@@ -100,3 +101,16 @@ repos:
       rev: v1.0.0
       hooks:
           - id: sphinx-lint
+
+    - repo: local
+      hooks:
+          - id: check-release-changelog
+            name: check-release-changelog
+            language: system
+            entry: python3 tests/check_changelog_and_version.py --allow-future-in-changelog
+            files: flake8_async/__init__.py|docs/changelog.rst
+
+    - repo: meta
+      hooks:
+          - id: check-hooks-apply
+          - id: check-useless-excludes

docs/changelog.rst

@@ -4,19 +4,38 @@ Changelog
 
 `CalVer, YY.month.patch <https://calver.org/>`_
 
-24.10.3
+25.1.1
 =======
 - Add :ref:`ASYNC124 <async124>` async-function-could-be-sync
 - :ref:`ASYNC91x <ASYNC910>` now correctly handles ``await()`` in parameter lists.
 - Fixed a bug with :ref:`ASYNC91x <ASYNC910>` and nested empty functions.
 
+24.11.4
+=======
+- :ref:`ASYNC100 <async100>` once again ignores :func:`trio.open_nursery` and :func:`anyio.create_task_group`, unless we find a call to ``.start_soon()``.
+
+24.11.3
+=======
+- Revert :ref:`ASYNC100 <async100>` ignoring :func:`trio.open_nursery` and :func:`anyio.create_task_group` due to it not viewing ``.start_soon()`` as introducing a :ref:`cancel point <cancel_point>`.
+
+24.11.2
+=======
+- Fix crash in ``Visitor91x`` on ``async with a().b():``.
+
+24.11.1
+=======
+- :ref:`ASYNC100 <async100>` now ignores :func:`trio.open_nursery` and :func:`anyio.create_task_group`
+  as cancellation sources, because they are :ref:`schedule points <schedule_point>` but not
+  :ref:`cancellation points <cancel_point>`.
+- :ref:`ASYNC101 <async101>` and :ref:`ASYNC119 <async119>` are now silenced for decorators in :ref:`transform-async-generator-decorators`.
+
 24.10.2
 =======
 - :ref:`ASYNC102 <async102>` now also warns about ``await()`` inside ``__aexit__``.
 
 24.10.1
 =======
-- Add :ref:`ASYNC123 <async123>` bad-exception-group-flattening
+- Add :ref:`ASYNC123 <async123>` bad-exception-group-flattening.
 
 24.9.5
 ======
@@ -45,7 +64,7 @@ Changelog
 
 24.8.1
 ======
-- Add config option ``transform-async-generator-decorators``, to list decorators which
+- Add config option :ref:`transform-async-generator-decorators`, to list decorators which
   suppress :ref:`ASYNC900 <async900>`.
 
 24.6.1

docs/glossary.rst

@@ -88,8 +88,8 @@ Exception classes:
 
 Checkpoint
 ----------
-Checkpoints are points where the async backend checks for cancellation and
-can switch which task is running, in an ``await``, ``async for``, or ``async with``
+Checkpoints are points where the async backend checks for :ref:`cancellation <cancel_point>` and
+:ref:`can switch which task is running <schedule_point>`, in an ``await``, ``async for``, or ``async with``
 expression.  Regular checkpoints can be important for both performance and correctness.
 
 Trio has extensive and detailed documentation on the concept of
@@ -99,11 +99,11 @@ functions defined by Trio will either checkpoint or raise an exception when
 iteration, and when exhausting the iterator, and ``async with`` will checkpoint
 on at least one of enter/exit.
 
+The one exception is :func:`trio.open_nursery` and :func:`anyio.create_task_group`. They do not checkpoint on entry, and on exit they insert a :ref:`schedule point <schedule_point>`. However, if sub-tasks are cancelled they will be propagated on exit, so if you're starting tasks you can usually treat the exit as a :ref:`cancel point <cancel_point>`.
+
 asyncio does not place any guarantees on if or when asyncio functions will
 checkpoint. This means that enabling and adhering to :ref:`ASYNC91x <ASYNC910>`
-will still not guarantee checkpoints.
-
-For anyio it will depend on the current backend.
+will still not guarantee checkpoints on asyncio (even if used via anyio).
 
 When using Trio (or an AnyIO library that people might use on Trio), it can be
 very helpful to ensure that your own code adheres to the same guarantees as
@@ -116,6 +116,33 @@ To insert a checkpoint with no other side effects, you can use
 :func:`trio.lowlevel.checkpoint`/:func:`anyio.lowlevel.checkpoint`/:func:`asyncio.sleep(0)
 <asyncio.sleep>`
 
+.. _schedule_point:
+
+Schedule Point
+--------------
+A schedule point is half of a full :ref:`checkpoint`, which allows the async backend to switch the running task, but doesn't check for cancellation (the other half is a :ref:`cancel_point`).
+While you are unlikely to need one, they are available as :func:`trio.lowlevel.cancel_shielded_checkpoint`/:func:`anyio.lowlevel.cancel_shielded_checkpoint`, and equivalent to
+
+.. code-block:: python
+
+   from trio import CancelScope, lowlevel
+   # or
+   # from anyio import CancelScope, lowlevel
+
+   with CancelScope(shield=True):
+       await lowlevel.checkpoint()
+
+asyncio does not have any direct equivalents due to their cancellation model being different.
+
+
+.. _cancel_point:
+
+Cancel Point
+------------
+A schedule point is half of a full :ref:`checkpoint`, which will raise :ref:`cancelled` if the enclosing cancel scope has been cancelled, but does not allow the scheduler to switch to a different task (the other half is a :ref:`schedule_point`).
+While you are unlikely to need one, they are available as :func:`trio.lowlevel.checkpoint_if_cancelled`/:func:`anyio.lowlevel.checkpoint_if_cancelled`.
+Users of asyncio might want to use :meth:`asyncio.Task.cancelled`.
+
 .. _channel_stream_queue:
 
 Channel / Stream / Queue

docs/rules.rst

@@ -13,9 +13,10 @@ _`ASYNC100` : cancel-scope-no-checkpoint
     A :ref:`timeout_context` does not contain any :ref:`checkpoints <checkpoint>`.
     This makes it pointless, as the timeout can only be triggered by a checkpoint.
     This check also treats ``yield`` as a checkpoint, since checkpoints can happen in the caller we yield to.
+    :func:`trio.open_nursery` and :func:`anyio.create_task_group` are excluded, as they are :ref:`schedule points <schedule_point>` but not :ref:`cancel points <cancel_point>` (unless they have tasks started in them).
     See :ref:`ASYNC912 <async912>` which will in addition guarantee checkpoints on every code path.
 
-ASYNC101 : yield-in-cancel-scope
+_`ASYNC101` : yield-in-cancel-scope
     ``yield`` inside a :ref:`taskgroup_nursery` or :ref:`timeout_context` is only safe when implementing a context manager - otherwise, it breaks exception handling.
     See `this thread <https://discuss.python.org/t/preventing-yield-inside-certain-context-managers/1091/23>`_ for discussion of a future PEP.
     This has substantial overlap with :ref:`ASYNC119 <ASYNC119>`, which will warn on almost all instances of ASYNC101, but ASYNC101 is about a conceptually different problem that will not get resolved by :pep:`533`.

docs/usage.rst

@@ -33,7 +33,7 @@ adding the following to your ``.pre-commit-config.yaml``:
    minimum_pre_commit_version: '2.9.0'
    repos:
    - repo: https://github.com/python-trio/flake8-async
-     rev: 23.2.5
+     rev: 25.1.1
      hooks:
        - id: flake8-async
          # args: [--enable=ASYNC, --disable=ASYNC9, --autofix=ASYNC]
@@ -318,3 +318,21 @@ Specified patterns must not have parentheses, and will only match when the patte
        def my_blocking_call():  # it's also safe to use the name in other contexts
            ...
        arbitrary_other_function(my_blocking_call=None)
+
+.. _transform-async-generator-decorators:
+
+``transform-async-generator-decorators``
+----------------------------------------
+Comma-separated list of decorators that make async generators safe, disabling
+:ref:`ASYNC900 <ASYNC900>`, :ref:`ASYNC101 <ASYNC101>`, and :ref:`ASYNC119 <ASYNC119>` warnings for functions decorated with any of them.
+``[pytest.]fixture`` and ``[contextlib.]asynccontextmanager`` are always considered safe.
+Decorators can be dotted or not, as well as support * as a wildcard.
+
+Example
+^^^^^^^
+
+.. code-block:: none
+
+   transform-async-generator-decorators =
+     fastapi.Depends
+     trio_util.trio_async_generator

flake8_async/__init__.py

@@ -38,7 +38,7 @@
 
 
 # CalVer: YY.month.patch, e.g. first release of July 2022 == "22.7.1"
-__version__ = "24.10.3"
+__version__ = "25.1.1"
 
 
 # taken from https://github.com/Zac-HD/shed

flake8_async/visitors/helpers.py

@@ -337,15 +337,20 @@ def build_cst_matcher(attr: str) -> m.BaseExpression:
     return m.Attribute(value=build_cst_matcher(body), attr=m.Name(value=tail))
 
 
-def identifier_to_string(attr: cst.Name | cst.Attribute) -> str | None:
-    if isinstance(attr, cst.Name):
-        return attr.value
-    if not isinstance(attr.value, (cst.Attribute, cst.Name)):
-        return None
-    lhs = identifier_to_string(attr.value)
-    if lhs is None:
-        return None
-    return lhs + "." + attr.attr.value
+def identifier_to_string(node: cst.CSTNode) -> str | None:
+    """Convert a simple identifier to a string.
+
+    If the node is composed of anything but cst.Name + cst.Attribute it returns None.
+    """
+    if isinstance(node, cst.Name):
+        return node.value
+    if (
+        isinstance(node, cst.Attribute)
+        and (lhs := identifier_to_string(node.value)) is not None
+    ):
+        return lhs + "." + node.attr.value
+
+    return None
 
 
 def with_has_call(

flake8_async/visitors/visitor101.py

@@ -70,7 +70,11 @@ def visit_FunctionDef(self, node: cst.FunctionDef):
         self.save_state(node, "_yield_is_error", "_safe_decorator")
         self._yield_is_error = False
         self._safe_decorator = func_has_decorator(
-            node, "contextmanager", "asynccontextmanager", "fixture"
+            node,
+            "contextmanager",
+            "asynccontextmanager",
+            "fixture",
+            *self.options.transform_async_generator_decorators,
         )
 
     # trigger on leaving yield so any comments are parsed for noqas

flake8_async/visitors/visitor103_104.py

@@ -51,9 +51,9 @@
     "ASYNC103": _async103_common_msg,
     "ASYNC104": "Cancelled (and therefore BaseException) must be re-raised.",
 }
-for poss_library in _suggestion_dict:
+for poss_library, _lib_suggest in _suggestion_dict.items():
     _error_codes[f"ASYNC103_{'_'.join(poss_library)}"] = (
-        _async103_common_msg + _suggestion.format(_suggestion_dict[poss_library])
+        _async103_common_msg + _suggestion.format(_lib_suggest)
     )