Feature better linting

[irm-codebase]

607 / #611 mostly happened because inputs and docstrings were not being evaluated by the linter.

I propose to activate additional linting. Docstring linting tends to be annoying, but in our case I think it'll help. It's very likely that this will trigger some hassle when modifying code at the start, but in the long run it will make our lives easier.

Additional linting is not always well received, though. Please let me know what you think!

Summary of changes in this pull request

• I am activating two additional tests: "D" (docstyle) and "PT" (pytest-style).
• Added editor config for additional consistency in .YAML files

Reviewer checklist

• [ ] Test(s) added to cover contribution
• [ ] Documentation updated
• [x] Changelog updated
• [ ] Coverage maintained or improved

[codecov[bot]]

Codecov Report

Attention: Patch coverage is 79.34783% with 19 lines in your changes missing coverage. Please review.

Project coverage is 95.33%. Comparing base (872978d) to head (00efb50). Report is 14 commits behind head on main.

Additional details and impacted files

```diff @@ Coverage Diff @@ ## main #620 +/- ## ========================================== - Coverage 95.85% 95.33% -0.52% ========================================== Files 24 24 Lines 3619 3647 +28 Branches 788 733 -55 ========================================== + Hits 3469 3477 +8 + Misses 86 82 -4 - Partials 64 88 +24 ``` | [Files](https://app.codecov.io/gh/calliope-project/calliope/pull/620?dropdown=coverage&src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=calliope-project) | Coverage Δ | | |---|---|---| | [src/calliope/\_\_init\_\_.py](https://app.codecov.io/gh/calliope-project/calliope/pull/620?src=pr&el=tree&filepath=src%2Fcalliope%2F__init__.py&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=calliope-project#diff-c3JjL2NhbGxpb3BlL19faW5pdF9fLnB5) | `100.00% <ø> (ø)` | | | [src/calliope/attrdict.py](https://app.codecov.io/gh/calliope-project/calliope/pull/620?src=pr&el=tree&filepath=src%2Fcalliope%2Fattrdict.py&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=calliope-project#diff-c3JjL2NhbGxpb3BlL2F0dHJkaWN0LnB5) | `96.50% <ø> (-0.02%)` | :arrow_down: | | [src/calliope/backend/backend\_model.py](https://app.codecov.io/gh/calliope-project/calliope/pull/620?src=pr&el=tree&filepath=src%2Fcalliope%2Fbackend%2Fbackend_model.py&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=calliope-project#diff-c3JjL2NhbGxpb3BlL2JhY2tlbmQvYmFja2VuZF9tb2RlbC5weQ==) | `98.06% <100.00%> (+0.16%)` | :arrow_up: | | [src/calliope/backend/parsing.py](https://app.codecov.io/gh/calliope-project/calliope/pull/620?src=pr&el=tree&filepath=src%2Fcalliope%2Fbackend%2Fparsing.py&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=calliope-project#diff-c3JjL2NhbGxpb3BlL2JhY2tlbmQvcGFyc2luZy5weQ==) | `95.98% <ø> (-1.79%)` | :arrow_down: | | [src/calliope/backend/pyomo\_backend\_model.py](https://app.codecov.io/gh/calliope-project/calliope/pull/620?src=pr&el=tree&filepath=src%2Fcalliope%2Fbackend%2Fpyomo_backend_model.py&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=calliope-project#diff-c3JjL2NhbGxpb3BlL2JhY2tlbmQvcHlvbW9fYmFja2VuZF9tb2RlbC5weQ==) | `95.57% <100.00%> (+0.15%)` | :arrow_up: | | [src/calliope/backend/where\_parser.py](https://app.codecov.io/gh/calliope-project/calliope/pull/620?src=pr&el=tree&filepath=src%2Fcalliope%2Fbackend%2Fwhere_parser.py&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=calliope-project#diff-c3JjL2NhbGxpb3BlL2JhY2tlbmQvd2hlcmVfcGFyc2VyLnB5) | `97.29% <100.00%> (ø)` | | | [src/calliope/cli.py](https://app.codecov.io/gh/calliope-project/calliope/pull/620?src=pr&el=tree&filepath=src%2Fcalliope%2Fcli.py&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=calliope-project#diff-c3JjL2NhbGxpb3BlL2NsaS5weQ==) | `81.57% <ø> (-0.10%)` | :arrow_down: | | [src/calliope/examples.py](https://app.codecov.io/gh/calliope-project/calliope/pull/620?src=pr&el=tree&filepath=src%2Fcalliope%2Fexamples.py&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=calliope-project#diff-c3JjL2NhbGxpb3BlL2V4YW1wbGVzLnB5) | `100.00% <ø> (ø)` | | | [src/calliope/exceptions.py](https://app.codecov.io/gh/calliope-project/calliope/pull/620?src=pr&el=tree&filepath=src%2Fcalliope%2Fexceptions.py&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=calliope-project#diff-c3JjL2NhbGxpb3BlL2V4Y2VwdGlvbnMucHk=) | `97.05% <ø> (-2.95%)` | :arrow_down: | | [src/calliope/io.py](https://app.codecov.io/gh/calliope-project/calliope/pull/620?src=pr&el=tree&filepath=src%2Fcalliope%2Fio.py&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=calliope-project#diff-c3JjL2NhbGxpb3BlL2lvLnB5) | `96.77% <ø> (+1.98%)` | :arrow_up: | | ... and [13 more](https://app.codecov.io/gh/calliope-project/calliope/pull/620?src=pr&el=tree-more&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=calliope-project) | |

[irm-codebase]

pre-commit breaking is expected. I will fix these issues before merging this PR, but only after confirming these new lints are desired.

[irm-codebase]

If you're happy to fix the issues raised by precommit.ci then I'm strongly in favour of this!

Happy is a strong word for linting fixes... but I will do it hahaha.

[brynpickering]

@irm-codebase don't forget to add yourself to the list in AUTHORS during this PR

[irm-codebase]

@brynpickering good chuck of files done. Most of these are minor changes. I am not completely re-working the documentation (I think it's better/safer to do that as we go on).

Question though: is it possible to configure pre-commit to only run "D" (pydocstrings) for merges? I think it makes sense to allow people to develop their code with docstring flexiblity, and only enforce it before bringing it into main.

I've read a bit of pre-commit's configuration, and it seems possible, but I am not experienced enough with setting hooks to know how to achieve it.

[irm-codebase]

This additional setting in pr-ci.yml could do the trick. It should only run pydocstyle on changed files, and ignore all others. I tried testing it, but with no luck. I'm probably missing something.

Advantages: should request updated dostrings as we develop, making this PR a bit easier. Disadvantages: if you modify a test file, you are in for a nasty surprise since you need to add docstrings to all tests.

  ruff-pydocstyle:
    runs-on: ubuntu-latest
    if: startsWith(github.event.pull_request.title, 'Release v')
    steps:
      - uses: tj-actions/changed-files@v44
      - uses: chartboost/ruff-action@v1
        with:
          args: check --select D

[brynpickering]

I think I prefer it being there by default. Hopefully shouldn't be too much effort to keep pre-commit / ruff happy with additions once you have the fixes done in this PR. It instills good documenting practice from our development team, which is no bad thing ;)

[brynpickering]

@irm-codebase while you're here, could you also remove our dependence on Black and move entirely to Ruff (as we do in euro-calliope)?

[irm-codebase]

@brynpickering corrections implemented! Sadly the only way to avoid the @abstractmethod issue is to deactivate linting for those functions. We could implement the @override decorator to avoid this, but it's python 3.12 exclusive, and will break our tests for 3.10 / 3.11.

[irm-codebase]

No idea why codeconv does not like this update, there is nothing added to the code :shrug:

edit: it's because of the added ... in some @abstractmethod cases. But without it we get linter issues.

[brynpickering]

edit: it's because of the added ... in some @abstractmethod cases. But without it we get linter issues.

Yeah, I think that's why I had docstrings in them to begin with, to keep codecov happy. I'm not sure there's much to be done about it (or, at least, I can't find an obvious answer online).

[irm-codebase]

Thanks for the help @brynpickering! I went through your changes and I agree to them. Is there anything else left to do for this PR?