ci: Replace redbaron with griffe in docstring scripts (#678)

## Summary

- Replace `redbaron` with `griffe` for parsing Python source in
`check_docstrings.py` and `fix_docstrings.py`.
- Use `ast` module for precise docstring source locations in the fix
script.
- Remove all RedBaron bug workarounds (indentation, whitespace,
except/finally formatting).
- Remove `redbaron` from dev dependencies.
- Complete rewrite of these scripts.

## Reasoning

- `redbaron` is more than 6 years non-maintained

## Test plan

- [x] Checked the scripts manually
- [x] CI passes

Author: vdusek

.github/workflows/_check_docstrings.yaml

@@ -36,4 +36,4 @@ jobs:
         run: uv run poe install-dev
 
       - name: Async docstrings check
-        run: uv run poe check-async-docstrings
+        run: uv run poe check-docstrings

.pre-commit-config.yaml

@@ -15,6 +15,6 @@ repos:
 
       - id: docstrings-check
         name: Docstrings check
-        entry: uv run poe check-async-docstrings
+        entry: uv run poe check-docstrings
         language: system
         pass_filenames: false

.rules.md

@@ -17,8 +17,8 @@ uv run poe lint                     # Ruff format check + ruff check
 uv run poe format                   # Auto-fix lint issues and format
 uv run poe type-check               # Run ty type checker
 uv run poe unit-tests               # Run unit tests
-uv run poe check-async-docstrings   # Verify async docstrings match sync
-uv run poe fix-async-docstrings     # Auto-fix async docstrings
+uv run poe check-docstrings         # Verify async docstrings match sync
+uv run poe fix-docstrings           # Auto-fix async docstrings
 
 # Run a single test
 uv run pytest tests/unit/test_file.py
@@ -50,7 +50,7 @@ Each resource client can create child clients (e.g., `ActorClient.builds()` →
 
 Every resource client has both sync and async variants in the **same file**. For example, `actor.py` contains both `ActorClient` and `ActorClientAsync`. Both share the same interface — async versions use `async/await`.
 
-Docstrings are written on sync clients and **automatically copied** to async clients via `scripts/check_async_docstrings.py`. When modifying docstrings, edit only the sync client and run `uv run poe fix-async-docstrings`.
+Docstrings are written on sync clients and **automatically copied** to async clients via `scripts/check_docstrings.py`. When modifying docstrings, edit only the sync client and run `uv run poe fix-docstrings`.
 
 ### Dependency Injection via ClientRegistry
 

CONTRIBUTING.md

@@ -24,8 +24,8 @@ All tasks are defined in `pyproject.toml` under `[tool.poe.tasks]` and can be ru
 | `unit-tests-cov` | Run unit tests with coverage |
 | `integration-tests` | Run integration tests |
 | `integration-tests-cov` | Run integration tests with coverage |
-| `check-async-docstrings` | Check async client docstrings |
-| `fix-async-docstrings` | Fix async client docstrings |
+| `check-docstrings` | Check async client docstrings |
+| `fix-docstrings` | Fix async client docstrings |
 | `build-docs` | Build documentation website |
 | `run-docs` | Run documentation website locally |
 | `build` | Build package |

pyproject.toml

@@ -48,7 +48,7 @@ dev = [
     "black>=24.3.0",
     "datamodel-code-generator[http,ruff]<1.0.0",
     "dycw-pytest-only<3.0.0",
-    "griffe",
+    "griffe<3.0.0",
     "poethepoet<1.0.0",
     "pre-commit<5.0.0",
     "pydoc-markdown<5.0.0",
@@ -58,7 +58,6 @@ dev = [
     "pytest-timeout<3.0.0",
     "pytest-xdist<4.0.0",
     "pytest<9.0.0",
-    "redbaron<1.0.0",
     "ruff~=0.15.0",
     "setuptools", # setuptools are used by pytest but not explicitly required
     "types-colorama<0.5.0",
@@ -240,9 +239,9 @@ unit-tests = "uv run pytest --numprocesses=${TESTS_CONCURRENCY:-auto} tests/unit
 unit-tests-cov = "uv run pytest --numprocesses=${TESTS_CONCURRENCY:-auto} --cov=src/apify_client --cov-report=xml:coverage-unit.xml tests/unit"
 integration-tests = "uv run pytest --numprocesses=${TESTS_CONCURRENCY:-auto} tests/integration"
 integration-tests-cov = "uv run pytest --numprocesses=${TESTS_CONCURRENCY:-auto} --cov=src/apify_client --cov-report=xml:coverage-integration.xml tests/integration"
-check-async-docstrings = "uv run python scripts/check_async_docstrings.py"
-fix-async-docstrings = "uv run python scripts/fix_async_docstrings.py"
-check-code = ["lint", "type-check", "unit-tests", "check-async-docstrings"]
+check-docstrings = "uv run python -m scripts.check_docstrings"
+fix-docstrings = "uv run python -m scripts.fix_docstrings"
+check-code = ["lint", "type-check", "check-docstrings", "unit-tests"]
 
 [tool.poe.tasks.install-dev]
 shell = "uv sync --all-extras && uv run pre-commit install"

scripts/__init__.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from griffe import Module, load
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from griffe import Class, Function
+
+SKIPPED_METHODS = {
+    'with_custom_http_client',
+}
+"""Methods where the async and sync docstrings are intentionally different."""
+
+SRC_PATH = Path(__file__).resolve().parent.parent / 'src'
+"""Path to the source code of the apify_client package."""
+
+_SUBSTITUTIONS = [
+    (re.compile(r'Client'), 'ClientAsync'),
+    (re.compile(r'\bsynchronously\b'), 'asynchronously'),
+    (re.compile(r'\bSynchronously\b'), 'Asynchronously'),
+    (re.compile(r'\bsynchronous\b'), 'asynchronous'),
+    (re.compile(r'\bSynchronous\b'), 'Asynchronous'),
+    (re.compile(r'Retry a function'), 'Retry an async function'),
+    (re.compile(r'Function to retry'), 'Async function to retry'),
+]
+"""Patterns for converting sync docstrings to async docstrings."""
+
+
+def load_package() -> Module:
+    """Load the apify_client package using griffe."""
+    package = load('apify_client', search_paths=[str(SRC_PATH)])
+    if not isinstance(package, Module):
+        raise TypeError('Expected griffe to load a Module')
+    return package
+
+
+def walk_modules(module: Module) -> Generator[Module]:
+    """Recursively yield all modules in the package."""
+    yield module
+    for submodule in module.modules.values():
+        yield from walk_modules(submodule)
+
+
+def iter_docstring_mismatches(package: Module) -> Generator[tuple[Class, Function, Class, Function, str, bool]]:
+    """Yield docstring mismatches between sync and async client methods.
+
+    Yields (async_class, async_method, sync_class, sync_method, expected_docstring, has_existing).
+    """
+    for module in walk_modules(package):
+        for async_class in module.classes.values():
+            if not async_class.name.endswith('ClientAsync'):
+                continue
+
+            sync_class = module.classes.get(async_class.name.replace('ClientAsync', 'Client'))
+            if not sync_class:
+                continue
+
+            for async_method in async_class.functions.values():
+                if any(str(d.value) == 'ignore_docs' for d in async_method.decorators):
+                    continue
+
+                if async_method.name in SKIPPED_METHODS:
+                    continue
+
+                sync_method = sync_class.functions.get(async_method.name)
+                if not sync_method or not sync_method.docstring:
+                    continue
+
+                expected_docstring = _sync_to_async_docstring(sync_method.docstring.value)
+
+                if not async_method.docstring:
+                    yield async_class, async_method, sync_class, sync_method, expected_docstring, False
+                elif async_method.docstring.value != expected_docstring:
+                    yield async_class, async_method, sync_class, sync_method, expected_docstring, True
+
+
+def _sync_to_async_docstring(docstring: str) -> str:
+    """Convert a docstring from a sync component version into a docstring for its async analogue."""
+    result = docstring
+    for pattern, replacement in _SUBSTITUTIONS:
+        result = pattern.sub(replacement, result)
+    return result

scripts/_utils.py

@@ -0,0 +1,41 @@
+"""Check that async client docstrings are in sync with their sync counterparts."""
+
+from __future__ import annotations
+
+import sys
+
+from ._utils import iter_docstring_mismatches, load_package
+
+
+def main() -> None:
+    """Check all async client methods for docstring mismatches."""
+    package = load_package()
+    found_issues = False
+
+    for (
+        async_class,
+        async_method,
+        sync_class,
+        sync_method,
+        _expected_docstring,
+        has_existing,
+    ) in iter_docstring_mismatches(package):
+        found_issues = True
+        if has_existing:
+            print(
+                f'Docstring mismatch: "{async_class.name}.{async_method.name}"'
+                f' vs "{sync_class.name}.{sync_method.name}"'
+            )
+        else:
+            print(f'Missing docstring for "{async_class.name}.{async_method.name}"!')
+
+    if found_issues:
+        print()
+        print('Issues with async docstrings found. Fix them by running `uv run poe fix-docstrings`.')
+        sys.exit(1)
+    else:
+        print('Success: async method docstrings are in sync with sync method docstrings.')
+
+
+if __name__ == '__main__':
+    main()