[DEPR]: Replace deprecated `pydocstyle` with `ruff`

[BryanttV]

Proposal Date

2025-04-10

Target Ticket Acceptance Date

2025-04-24

Earliest Open edX Named Release Without This Functionality

Ulmo - 2025-10

Rationale

The pydocstyle package has been deprecated since November 2023. The latest supported Python version is 3.11. They recommend using ruff as a replacement. These changes have already been tested in openedx-filters and openedx-events.

Removal

To completely remove pydocstyle and replace it with ruff it's necessary:

1. Remove pydocstyle from the requirements in edx-cookiecutters for new apps, libraries, and services and replace it with ruff.

2. Remove pydocstyle from all Open edX repositories and replace it with ruff. The following are the Open edX repositories currently using/installing the package:

   • api-doc-tools
   • code-annotations
   • codejail-service
   • completion
   • django-config-models
   • django-pyfs
   • django-user-tasks
   • edx-celeryutils
   • edx-django-release-util
   • edx-django-utils
   • edx-enterprise-data
   • edx-enterprise-subsidy-client
   • edx-rbac
   • edx-repo-health
   • edx-toggles
   • edx-val
   • edx-when
   • enterprise-access
   • enterprise-integrated-channels
   • enterprise-subsidy
   • event-bus-kafka
   • event-bus-redis
   • event-routing-backends
   • forum
   • help-tokens
   • openedx-learning
   • openedx-ledger
   • platform-plugin-aspects
   • super-csv
   • taxonomy-connector
   • xapi-db-load
   • xblock-google-drive
   • xblocks-contrib
   • xss-utils

   Installed but not used:

   • edx-ace
   • edx-enterprise
   • edx-proctoring
   • enterprise-catalog
   • license-manager
   • xblock-sdk

Replacement

Ruff

Deprecation

No response

Migration

1. Install and configure Ruff.
2. Remove any references to pydocstyle (from tox.ini or Makefile, depending on the repository).
3. Fix any docstring errors that were not previously reported.
4. Create a PR and merge.

Additional Info

• Maintenance Slack Channel
• Discuss Post

Task List

• Remove pydocstyle from requirements in edx-cookiecutters for new apps, libraries, and services and replace it with ruff.
• Remove pydocstyle from all Open edX repositories, and replace it with ruff.

[bmtcril]

Thanks for doing this, I'm looking forward to it! Currently we have a number of customizations for pydocstyle in the cookiecutter to try to keep things consistent across the org: https://github.com/openedx/edx-cookiecutters/blob/c63ea223f2fd2e3b408fcfcf97da6389b57304b8/python-template/%7B%7Bcookiecutter.placeholder_repo_name%7D%7D/tox.ini#L13 (and in other places in there)

Additionally most of the Django apps ignore automatically-generated code, like migrations. Is the plan to carry those settings forward and have ruff be configured as much as possible the same was as pydocstyle? Or to use the ruff defaults?

[BryanttV]

Hi @bmtcril, thanks for your comment!

Is the plan to carry those settings forward and have ruff be configured as much as possible the same was as pydocstyle?

Yes, that's the idea. The plan is to maintain the same configuration as pydocstyle in ruff. You can check these PRs in the Hooks repositories, with the needed changes.

• feat: replace deprecated pydocstyle with ruff openedx-filters#270
• feat: replace deprecated pydocstyle with ruff openedx-events#473

Additionally most of the Django apps ignore automatically-generated code, like migrations.

With ruff you can exclude specific directories in the lint check, e.g:

[lint]
exclude = ["migrations"]

[UsamaSadiq]

This seems like a useful update. I always love to work on large scale improvements like this.

Previously we've done similar large scale refactoring using the bulk repo update tool.
Since this seems like a simple enough change which can be done with a script, we can utilize this tool to generate PRs across all required packages and then review/merge the changes individually.

[robrap]

Thanks for this. Also, it seems that we're using the DEPR process more as an inform here, right? It seems like nothing will break, and this is just a refactor? It doesn't seem like there are any timing considerations, and this really could happen at any time without negatively affecting anyone? At least, it seems like that happened on openedx-events.

[BryanttV]

Hi everyone!

I have been doing some thorough testing by implementing Ruff and found a few things that should be taken into account when migrating. In the hooks repositories, corrections will also be needed, as the current configuration is not entirely correct. I created a sample PR from another repository (event-bus-redis), which can serve as a guide for the others.

1. By default, pydocstyle only checks Python files that do not start with 'test_'. It uses the flag --match='(?!test_).*\.py'. This behavior can be replicated in Ruff with:

   [lint]
   exclude = ["test_*.py"]

   However, I would like to know: Should we keep this behavior? Or should test files also be checked?

2. In pydocstyle, the current match-dir setting to ignore the migrations folder is misconfigured. It should be something like: match-dir=(?!migrations).*. The current pattern causes the linter to skip other folders that should be checked. To properly exclude the migrations folder in Ruff, you can configure it like this:

   extend-exclude = ["migrations"]

3. pydocstyle is not currently enforcing any docstring convention. Should we apply one (e.g., PEP257 or Google style)?
   If you want to enforce a convention with Ruff, you can do it like this:

   [lint]
   convention = "pep257"

Finally, the ruff.toml configuration should look like this to match the current pydocstyle behavior:

extend-exclude = ["migrations"]

[lint]
exclude = ["test_*.py"]

select = [
    "D", # pydocstyle
]

ignore = [
    "D101", # Missing docstring in public class
    "D200", # One-line docstring should fit on one line
    "D203", # 1 blank line required before class docstring
    "D212", # Multi-line docstring summary should start at the first line
    "D215", # Section underline is over-indented
    "D404", # First word of the docstring should not be "This"
    "D405", # Section name should be properly capitalized
    "D406", # Section name should end with a newline
    "D407", # Missing dashed underline after section
    "D408", # Section underline should be in the line following the section's name
    "D409", # Section underline should match the length of its name
    "D410", # Missing blank line after section
    "D411", # Missing blank line before section
    "D412", # No blank lines allowed between a section header and its content
    "D413", # Missing blank line after last section
    "D414", # Section has no content
]

Migration Steps

1. Install and configure Ruff.
2. Remove any references to pydocstyle (from tox.ini or Makefile, depending on the repository).
3. Fix any docstring errors that were not previously reported.
4. Create a PR and merge.

Additional Notes

• By using the Ruff extension in code editors like VSCode, you can automatically highlight linting errors in docstrings.

  

[timmc-edx]

I believe I've had unpleasant experiences in the past with pydocstyle insisting on certain grammatical constructions in docstrings for unit tests.

For example, a unit test might have the docstring "Regression test for invalid JSON" and pydocstyle would insist on the docstring starting with a verb in the imperative mood, like "Check that there hasn't been a regression around invalid JSON". It just makes sense to have more relaxed standards around test files since they have a different purpose. This is probably why test_ was excluded -- and probably good to keep it that way.

(It's possible I'm confusing it with another tool, though.)

[robrap]

[inform] This DEPR is in the Draft state. It can't move forward without a DEPR coordinator to help update it to match the updated DEPR template. No action is required, unless anyone wants to move this out of Draft.