René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Implement `usethis tool ruff`","articleBody":"**Motivation**\r\n`ruff` is probably the most popular linter as of late (for good reason) so it's essential we include it in `usethis`.\r\n\r\n**Summary of desired feature**\r\nSupport the addition of `ruff` to a project using the `usethis tool ruff` command\r\n\r\n**Design**\r\nBasically, the tool would be handled identically to `deptry` but there are some additional complications from needing `pyproject.toml` config. In particular, there needs to be some logic to add the new configuration sections to the `pyproject.toml`, if they don't already exist. This should be inserted alphabetically within the `tool` section - in cases where the order is not already alphabetical, place it as low as possible while still retaining order in terms of the subsequent sections.\r\n\r\nThere will be two hooks corresponding to formatting and checks, which is also different to the `deptry` case where there is only one hook.\r\n\r\nWe need to decide which rules to enable. To simplify things, we can just use `ruff`'s defaults, i.e. `[\"E4\", \"E7\", \"E9\", \"F\"]`, plus a collection of others which are mostly autofixable and relatively uncontroversial:\r\n`[\"I\", \"UP\", \"C4\", \"SIM\", \"PLE\", \"PLR\", \"FURB\", \"RUF\"]`\r\n\r\nLater, the user could opt-in to a more aggressive approach with a  `--strict` command which tries to enable as many rules as is reasonable (perhaps avoiding the especially controversial ones or ones with too many false positives). For now, we won't implement the `--strict` flag, so there would be minimal `ruff` configuration to add in `pyproject.toml`.\r\n\r\nAlso, later, for tools managed by `usethis`, we could ensure particular rules are enabled, e.g. `\"PT\"` when the user is using `pytest`.\r\n\r\nWhen making the strict flag later, here are some thoughts for reference:\r\n- Some rules are \"under-specified\" without further configuration, e.g. docstring checking. We should adopt an opinionated default even for controversial points like docstring format. Later, deviations from the defaults could be handled `usethis` interfaces.\r\n- We should name each rule family explicitly. We can keep track of new rules added to ruff via the `ruff rule --all --output-format json`, and have a version test which ensures we haven't missed anything. It is tempting to use `\"ALL\"` but this obscures which rules are actually being used. In my view, it is better to name each rule family explicitly, even if this makes the config section longer.  This also means we can manually go through each family of rules systematically and not just uncritically adopt new additions.\r\n- We could include rules conditionally based on whether the framework is being used; for example, `NPY` rules could be enabled only when `numpy` is a dependency. The issue with this is that dependencies might change. Even if the framework isn't being used, it doesn't hurt to have the rule enabled. So it's probably not a good idea.\r\n\r\n**Describe alternatives you've considered**\r\nRather than having a strict flag, we could have the strict behaviour by default. The issue with this is that it is probably too much of a departure from people's expectations and might have too many false positives. Compliance with too many rules is burdensome for users who are not familiar with linters, especially if there is not autofix. It is also potentially very controversial regaring which rules to enable, and a maintenance burden. A strict mode would need a good philosophy on rule inclusion/exclusion so it's not just a fully manual process of constantly reviewing new rules and changes to rules.\r\n\r\nI considered the possibility of just using the `ruff` defaults only without any extra rules, but there are just too many useful linters and it seems a shame not to enable them by default, especially when they are mostly autofix and relatively uncontroversial.\r\n\r\n**Testing Strategy**\r\nSame as for `deptry` but also include tests relating to the `pyproject.toml` file contents:\r\n- checking the contents are correct\r\n- checking that `ruff` is able to run in a way that proves it is using the file contents\r\n- checking the associated messages\r\n\r\nAny functions which add/remove contents to/from the `pyproject.toml` file should be tested too.\r\n\r\n**Steps**\r\n- Copy `deptry`'s Tool definition, mutatis mutandis.\r\n- Also copy the `deptry` CLI function, but add a new call to create `pyproject.toml` sections, testing along the way.\r\n\r\n**Acceptance Criteria**\r\nNew `usethis tool ruff` CLI interface is available to add `ruff` including configuration.\r\n","author":{"url":"https://github.com/nathanjmcdougall","@type":"Person","name":"nathanjmcdougall"},"datePublished":"2024-10-18T05:30:21.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/27/usethis-python/issues/27"}