Skip to content

Commit

Permalink
Add ruff, adjust pyugprade, autoflake in docs (Cherry-pick of #19555) (…
Browse files Browse the repository at this point in the history 
…#19577)

Fixes #19273 by adding ruff to the docs, both the auto-generated backend
docs and the manual pages that list out backends. This doesn't try to
solve the general problem of reminding us to add backends to docs.

While I was there, I noticed the pyupgrade and autoflake backends were
referring to the `experimental` paths, but they've now graduated to
non-experimental, so this switches them over.
  • Loading branch information
@huonw
huonw authored Aug 9, 2023
1 parent 6183f10 commit fb4ad81
Show file tree
Hide file tree
Showing 3 changed files with 20 additions and 23 deletions.
5 changes: 3 additions & 2 deletions build-support/bin/generate_docs.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -196,8 +196,7 @@ def run_pants_help_all() -> dict[str, Any]:
"pants.backend.experimental.python",
"pants.backend.experimental.python.framework.stevedore",
"pants.backend.experimental.python.lint.add_trailing_comma",
"pants.backend.experimental.python.lint.autoflake",
"pants.backend.experimental.python.lint.pyupgrade",
"pants.backend.experimental.python.lint.ruff",
"pants.backend.experimental.python.packaging.pyoxidizer",
"pants.backend.experimental.scala",
"pants.backend.experimental.scala.lint.scalafmt",
Expand All @@ -206,13 +205,15 @@ def run_pants_help_all() -> dict[str, Any]:
"pants.backend.google_cloud_function.python",
"pants.backend.plugin_development",
"pants.backend.python",
"pants.backend.python.lint.autoflake",
"pants.backend.python.lint.bandit",
"pants.backend.python.lint.black",
"pants.backend.python.lint.docformatter",
"pants.backend.python.lint.flake8",
"pants.backend.python.lint.isort",
"pants.backend.python.lint.pydocstyle",
"pants.backend.python.lint.pylint",
"pants.backend.python.lint.pyupgrade",
"pants.backend.python.lint.yapf",
"pants.backend.python.mixed_interpreter_constraints",
"pants.backend.python.typecheck.mypy",
Expand Down
31 changes: 13 additions & 18 deletions docs/markdown/Python/python/python-linters-and-formatters.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,18 +24,19 @@ Activating linters and formatters

Linter/formatter support is implemented in separate [backends](doc:enabling-backends) so that they are easy to opt in to individually:

| Backend | Tool |
| :------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- |
| `pants.backend.python.lint.bandit` | [Bandit](https://bandit.readthedocs.io/en/latest/): security linter |
| `pants.backend.python.lint.black` | [Black](https://black.readthedocs.io/en/stable/): code formatter |
| `pants.backend.python.lint.docformatter` | [Docformatter](https://pypi.org/project/docformatter/): docstring formatter |
| `pants.backend.python.lint.flake8` | [Flake8](https://flake8.pycqa.org/en/latest/): style and bug linter |
| `pants.backend.python.lint.isort` | [isort](https://readthedocs.org/projects/isort/): import statement formatter |
| `pants.backend.python.lint.pydocstyle` | [Pydocstyle](https://pypi.org/project/pydocstyle/): docstring linter |
| `pants.backend.python.lint.pylint` | [Pylint](https://pylint.pycqa.org/): style and bug linter |
| `pants.backend.python.lint.yapf` | [Yapf](https://github.com/google/yapf): code formatter |
| `pants.backend.experimental.python.lint.autoflake` | [Autoflake](https://github.com/myint/autoflake): remove unused imports |
| `pants.backend.experimental.python.lint.pyupgrade` | [Pyupgrade](https://github.com/asottile/pyupgrade): automatically update code to use modern Python idioms like `f-strings` |
| Backend | Tool |
|:----------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------|
| `pants.backend.python.lint.bandit` | [Bandit](https://bandit.readthedocs.io/en/latest/): security linter |
| `pants.backend.python.lint.black` | [Black](https://black.readthedocs.io/en/stable/): code formatter |
| `pants.backend.python.lint.docformatter` | [Docformatter](https://pypi.org/project/docformatter/): docstring formatter |
| `pants.backend.python.lint.flake8` | [Flake8](https://flake8.pycqa.org/en/latest/): style and bug linter |
| `pants.backend.python.lint.isort` | [isort](https://readthedocs.org/projects/isort/): import statement formatter |
| `pants.backend.python.lint.pydocstyle` | [Pydocstyle](https://pypi.org/project/pydocstyle/): docstring linter |
| `pants.backend.python.lint.pylint` | [Pylint](https://pylint.pycqa.org/): style and bug linter |
| `pants.backend.python.lint.yapf` | [Yapf](https://github.com/google/yapf): code formatter |
| `pants.backend.python.lint.autoflake` | [Autoflake](https://github.com/myint/autoflake): remove unused imports |
| `pants.backend.python.lint.pyupgrade` | [Pyupgrade](https://github.com/asottile/pyupgrade): automatically update code to use modern Python idioms like `f-strings` |
| `pants.backend.experimental.python.lint.ruff` | [Ruff](https://beta.ruff.rs/docs/): an extremely fast Python linter, written in Rust. |

To enable, add the appropriate backends in `pants.toml`:

Expand Down Expand Up @@ -267,12 +268,6 @@ You must tell Pyupgrade which version of Python to target, like this:
args = ["--py36-plus"]
```

### Autoflake and Pyupgrade are experimental

These tools are marked experimental because we are debating adding a new goal called `fix` and running them with `fix` rather than `fmt`. The tools are safe to use, other than possibly changing how you invoke them in the future.

We invite you to [weigh in with what you think](https://github.com/pantsbuild/pants/issues/13504)!

### isort: possible issues with its import classifier algorithm

Some Pants users had to explicitly set `default_section = "THIRDPARTY"` to get iSort 5 to correctly classify their first-party imports, even though this is the default value.
Expand Down
7 changes: 4 additions & 3 deletions docs/markdown/Using Pants/concepts/enabling-backends.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,22 +36,23 @@ Available backends
| `pants.backend.experimental.java.lint.google_java_format` | Enables Google Java Format. | [Java & Scala overview](doc:jvm-overview) |
| `pants.backend.experimental.scala` | Enables core Scala support. | [Java & Scala overview](doc:jvm-overview) |
| `pants.backend.experimental.scala.lint.scalafmt` | Enables the Scalafmt formatter. | [Java & Scala overview](doc:jvm-overview) |
| `pants.backend.experimental.python.lint.autoflake` | Enables Autoflake, which removes unused Python imports: <https://pypi.org/project/autoflake/> | [Linters and formatters](doc:python-linters-and-formatters) |
| `pants.backend.experimental.python.lint.pyupgrade` | Enables Pyupgrade, which upgrades to new Python syntax: <https://pypi.org/project/pyupgrade/> | [Linters and formatters](doc:python-linters-and-formatters) |
| `pants.backend.experimental.python.lint.ruff` | Enables Ruff, an extremely fast Python linter: <https://beta.ruff.rs/docs/> | [Linters and formatters](doc:python-linters-and-formatters) |
| `pants.backend.experimental.python.packaging.pyoxidizer` | Enables `pyoxidizer_binary` target. | [PyOxidizer](doc:pyoxidizer) |
| `pants.backend.experimental.visibility` | Enables `__dependencies_rules__` and `__dependents_rules__` | [Visibility](doc:targets#visibility) |
| `pants.backend.google_cloud_function.python` | Enables generating a Google Cloud Function from Python code. | [Google Cloud Function](doc:google-cloud-function-python) |
| `pants.backend.plugin_development` | Enables `pants_requirements` target. | [Plugins overview](doc:plugins-overview) |
| `pants.backend.python` | Core Python support. | [Enabling Python support](doc:python-backend) |
| `pants.backend.python.mixed_interpreter_constraints` | Adds the `py-constraints` goal for insights on Python interpreter constraints. | [Interpreter compatibility](doc:python-interpreter-compatibility) |
| `pants.backend.python.lint.autoflake` | Enables Autoflake, which removes unused Python imports: <https://pypi.org/project/autoflake/> | [Linters and formatters](doc:python-linters-and-formatters) |
| `pants.backend.python.lint.bandit` | Enables Bandit, the Python security linter: <https://bandit.readthedocs.io/en/latest/>. | [Linters and formatters](doc:python-linters-and-formatters) |
| `pants.backend.python.lint.black` | Enables Black, the Python autoformatter: <https://black.readthedocs.io/en/stable/>. | [Linters and formatters](doc:python-linters-and-formatters) |
| `pants.backend.python.lint.docformatter` | Enables Docformatter, the Python docstring autoformatter: <https://github.com/myint/docformatter>. | [Linters and formatters](doc:python-linters-and-formatters) |
| `pants.backend.python.lint.flake8` | Enables Flake8, the Python linter: <https://flake8.pycqa.org/en/latest/>. | [Linters and formatters](doc:python-linters-and-formatters) |
| `pants.backend.python.lint.isort` | Enables isort, the Python import autoformatter: <https://timothycrosley.github.io/isort/>. | [Linters and formatters](doc:python-linters-and-formatters) |
| `pants.backend.python.lint.pylint` | Enables Pylint, the Python linter: <https://www.pylint.org> | [Linters and formatters](doc:python-linters-and-formatters) |
| `pants.backend.python.lint.pyupgrade` | Enables Pyupgrade, which upgrades to new Python syntax: <https://pypi.org/project/pyupgrade/> | [Linters and formatters](doc:python-linters-and-formatters) |
| `pants.backend.python.lint.yapf` | Enables Yapf, the Python formatter: <https://pypi.org/project/yapf/> | [Linters and formatters](doc:python-linters-and-formatters) |
| `pants.backend.python.typecheck.mypy` | Enables MyPy, the Python type checker: <https://mypy.readthedocs.io/en/stable/>. | [typecheck](doc:python-typecheck-goal) |
| `pants.backend.python.typecheck.mypy` | Enables MyPy, the Python type checker: <https://mypy.readthedocs.io/en/stable/>. | [typecheck](doc:python-check-goal) |
| `pants.backend.shell` | Core Shell support, including shUnit2 test runner. | [Shell overview](doc:shell) |
| `pants.backend.shell.lint.shfmt` | Enables shfmt, a Shell autoformatter: <https://github.com/mvdan/sh>. | [Shell overview](doc:shell) |
| `pants.backend.shell.lint.shellcheck` | Enables Shellcheck, a Shell linter: <https://www.shellcheck.net/>. | [Shell overview](doc:shell) |

0 comments on commit fb4ad81

Please sign in to comment.