iris

iris copied to clipboard

📰 Custom Issue

As #5623 has been merged, we're now in the position where we can slowly adopt incremental compliance of the ruff linter rules.

Our ruff configuration is defined in two files:

• pyproject.toml: this contains the main ruff configuration for the linter (and formatter, when adopted) and permanent rule exclusions
• .ruff.toml: this configuration extends the pyproject.toml and contains temporary rule exclusions

The goal of our ruff adoption is two-fold:

1. Tackle individual rule categories defined in the .ruff.toml on a piecemeal basis e.g., "F" or "ANN" etc
2. Drop third-party packages replaced by ruff.

Tackling Rules

We need to agree on a general way forward here.

However, essentially it will involve the following steps:

1. Comment out a rule in the .ruff.toml.
2. Install ruff in your development environment e.g., pip install ruff.
3. Run ruff e.g., ruff .
4. Address the non-compliances:
   • Consider using ruff --fix . to auto-fix.
   • Manually address the other non-compliances.
5. Either:
   • Remove the rule from .ruff.toml, as we are now compliant.
   • Replace the rule category with one or more exact rules that still require to be addressed e.g., replace "F" (Pyflakes), which represents all pyflakes rules, with exact "Fxxx" rule instances that still require to be ignored.

Note that, rules can be ignored across all of iris by using the [tool.ruff.lint.ignore] in the pyproject.toml or the lint.ignore in the .ruff.toml.

Rules can also be ignored on a per file basis:

• Use [tool.ruff.lint.per-file-ignores] in pyproject.toml.
• Use lint.extend-per-file-ignores in the .ruff.toml.

As a result of tackling the temporary rule exceptions in .ruff.toml we may uncover permanent rule exceptions that we want to adopt. These should be discussed, and if agreed, added and documented in the pyproject.toml.

Drop Third-Party Packages

The ruff linter and formatter replace the following packages, which we can now drop:

• [x] black (#5634)
  • [x] Adopt ruff formatter
  • [x] Remove tool.black section from pyproject.toml
  • [x] Remove pre-commit hook from .pre-commit-config.yaml
  • [x] Remove badge from the README.md
• [x] isort (#5633)
  • [x] Remove tool.isort section from pyproject.toml
  • [x] Remove pre-commit hook from .pre-commit-config.yaml
  • [x] Remove "I" rule ignore from .ruff.toml
• [ ] flake8
  • [ ] Remove .flake8 configuration file
  • [ ] Update MANIFEST.in
  • [ ] Remove pre-commit hook from .pre-commit-config.yaml

numpydoc adoption tick list https://github.com/SciTools/iris/issues/4721 will address the pydocstyle (D) section in https://github.com/SciTools/iris/blob/c11d8bbffa65e3bc8ed2306b6fd6099984ed8ba1/.ruff.toml#L28-L30

We need to agree on a general way forward here.

See #5612

Now https://github.com/SciTools/iris/pull/5636 is merged there is now a list of rules that are in the ignore section explicitly can now be addressed one by one in separate PR's.

Rules look here here https://docs.astral.sh/ruff/rules/#pydocstyle-d

• [x] "D100", # Missing docstring in public module (@tkknight #5678)
• [ ] "D101", # Missing docstring in public class : ~1313 ruff errors.
• [ ] "D102", # Missing docstring in public method : ~7429 ruff errors.
• [ ] "D103", # Missing docstring in public function : ~179 ruff errors.
• [x] "D104", # Missing docstring in public package (@tkknight #5677)
• [x] "D106", # : Missing docstring in public nested class (@tkknight #5676)
• [x] "D200", # One-line docstring should fit on one line (@tkknight #5675)
• [x] "D202", # No blank lines allowed after function docstring (@tkknight #5674)
• [x] "D205", # 1 blank line required between summary line and description (@tkknight #5681)
• [x] "D208", # Docstring is over-indented (@tkknight #5656)
• [x] "D209", # Multi-line docstring closing quotes should be on a separate line (@tkknight #5663)
• [x] "D211", # No blank lines allowed before class docstring (@tkknight #5661)
• [x] "D214", # Section is over-indented (@tkknight #5654)
• [x] "D300", # triple double quotes """ / Use triple single quotes '''` (@tkknight #5661)
• [x] "D301", # Use r""" if any backslashes in a docstring (@tkknight #5646)
• [x] "D400", # First line should end with a period (@tkknight #5647)
• [x] "D401", # First line of docstring should be in imperative mood: ... (@tkknight #5687)
• [x] "D403", # First word of the first line should be capitalized (@tkknight #5661)
• [x] "D404", # First word of the docstring should not be "This" (@tkknight #5671)
• [x] "D405", # Section name should be properly capitalized (@tkknight #5666)
• [x] "D406", # Section name should end with a newline (@tkknight #5670)
• [x] "D407", # Missing dashed underline after section (@tkknight #pull/5666)
• [x] "D409", # Section underline should match the length of its name (@tkknight #5662)
• [x] "D410", # Missing blank line after section (@tkknight #5662)
• [x] "D411", # Missing blank line before section (@tkknight #5657)
• [x] "D412", # No blank lines allowed between a section header and its content (@tkknight #5660)
• [x] "D417", # Missing argument descriptions in the docstring (@tkknight #5677)

See also #5780 DOCS: Adopt the numpydoc validation rules.