Package: pylint-ignore
Pylint-IgnoreStart with silence, not with noise. But do start!Project/Repo:Code Quality/CI:NamerolesinceuntilManuel Barkhau (mbarkhau@gmail.com)author/maintainer2020-06-Developer ErgonomicsThe main issue with Pylint is developer ergonomics. The messages produced by Pylintcanbe valuable, but you have to put in some work before you can use it productively. If you have an established codebase, you'll probably have to:research configuration optionsdisable many unhelpful messagesblindly litter your code withpylint:disablecomments.Using Pylint-Ignore you can benefit from Pylint today. You won't have to wade through endless message noise first, won't have to spend time with configuration, you won't have to change anything about your code. Even though you start with all messages ignored for existing code, you can benefit from Pylint right away for any new code you write.What about the wall of messages for your existing code? Well, at least you can gradually improve your situation, as you have time for it. In other words, you may be dug into a hole right now, but at least you can stop digging yourself any deeper and gradually start climbing back out.How it WorksThepylint-ignorecommand is a thin wrapper around thepylintpackage. You can get started immediately by running the following commands:$pipinstallpylint-ignore

Installingcollectedpackages:astroid,isort,pylint,pylint-ignore
...
Successfullyinstalledpylint-ignore-2020.1006

$pylint-ignoresrc/

*************Modulesrc/mymodule.py
src/mymodule.py:290:0:W0102:Dangerousdefaultvaluesys.argv[1:](builtins.list)asargument(dangerous-default-value)...

-------------------------------------------------------------------
Yourcodehasbeenratedat9.92/10

$echo$?# exit status != 028Thepylint-ignorecommand reads a file calledpylint-ignore.md, which you should keep as part of your repository. This file contains messages that should be ignored and it is automatically updated with new entries if you specify the--update-ignorefileparameter.$pylint-ignoresrc/--update-ignorefile

-------------------------------------------------------------------
Yourcodehasbeenratedat10.00/10(previousrun:9.92/10,+0.08)$echo$?# exit status == 00The original message no longer shows up in the output, and it is instead logged in thepylint-ignore.md, which will now look something like this:...
## File src/mymodule.py - Line 290 - W0102 (dangerous-default-value)

- message: Dangerous default value sys.argv[1:] (builtins.list) as argument
- author : Manuel Barkhau <mbarkhau@gmail.com>
- date   : 2020-07-17T21:15:25

```
  289:
> 290: def main(args: Sequence[str] = sys.argv[1:]) -> ExitCode:
  291:     try:
```Ideally, you should only do this once when you start to use Pylint, and going forward the file will only get smaller. As your time permits, the recommended approach to usingpylint-ignoreis the following:If a message refers to a valid issue (errors and warnings in particular), update your code so the issue is resolved.If a message is a false positive, add a comment of this form to your code:# pylint:disable=<symbol> ; explain why this is a false positiveIf it is a useless message (e.g. a whitespace rule that conflicts with the behaviour of your code formatter) which shouldalwaysbe ignored, then do so via yourpylintrcorsetup.cfgfile.In principal these are the same options you have when using Pylint by itself. For the above example,dangerous-default-valueis a useful message in general) just not in this particular case. You might take the approach of option 2. and add apylint:disablecomment:defmain(args:Sequence[str]=sys.argv[1:])->ExitCode:# pylint:disable=dangerous-default-value;  args is not mutated# mypy prevents this because Sequence[str] does not support mutationtry:With this change, the next time you runpylint-ignore --update-ignorefile, the corresponding entry will disappear and the backlog will shrink.CLI UsageThepylint-ignorecommand has only two options, any other options on the command line are passed-through topylint. For example,pylint-ignore --helpwill behave exactly the same aspylint --help. The optionspylint-ignoreprovides are:Usage: pylint-ignore [options]

Options:
  --ignorefile=<FILE>    Path to ignore file [default: pylint-ignore.md]
  --update-ignorefile    Update the ignorefile, adds new messages,
                         removes any messages that are no longer
                         emmitted by pylint (were fixed or disabled)Normally thepylint-ignorecommand will not update thepylint-ignore.mdfile. This is appropriate forNormal development if it's your policy to not introduce any new issues.CI/CD build systems, where you want to report any issues that were newly introduced.If you fix an issue or explicitly disable a message, you can cleanup obsolete entries by adding the--update-ignorefileargument. For example:$pylint-ignore--update-ignorefilesrc/test/Caveat:If you change some code for which there is an entry in thepylint-ignore.mdfile, the entry may no longer be matched up with the message as it is generated by Pylint. Usually, changes in line numbers will be detected as long as the code itself did not change and your build will not fail if that is the case. Hopefully you will not feel the need to habitually use--update-ignorefilebut you may need to use it occasionally, simply to refresh an existing entry that became invalid. You can of course also take such an occasion as an opportunity to deal with the underlying issue.Integration withpre-commitpylint-ignorecan be used as apre-commithook, but inherits the limitations ofpylintdescribed inPre-commit integration.To includepylint-ignoreas a pre-commit hook using the provided plugin, add the following entry to a.pre-commit-config.yamlfile in the repository being linted:-repo:https://github.com/mbarkhau/pylint-ignorerev:"2021.1024"hooks:-id:pylint-ignoreIf you find thatpylintwill only function correctly when run in the local Python environment (as described inPre-commit integration) then the following local hook entry can instead be used forpylint-ignore:repos:-repo:localhooks:-id:pylint-ignorename:pylint-ignoreentry:pylint-ignorelanguage:systemtypes:[python]require_serial:true# args: [#   "--rcfile",#   "setup.cfg",#   "src/",#   "test/",#   "--ignore-paths",#   "scripts/,fixtures/,setup.py",# ]Theargs: [...]property can be added to the entries as required.To test you can use pre-commit run:$ pre-commit run pylint-ignore --all-filesConfigurationPylint's behaviour can be configured in the usual way, seeCommand-line arguments and configuration filesfor details.Thepylint-ignore.mdfileYou can view an example file here:fixtures/pylint-ignore.md. You can consider this file as a backlog of possible issues. The entries are sorted first by category, i.e. errors and warnings first then by frequency. You can change the path/filename using the--ignorefileparameter:pylint-ignore --ignorefile=etc/pylint-backlog.mdThepylint-ignore.mdfile uses a bespoke format but it is valid markdown. This choice is primarily so that you can read it and review it more easily on platforms such as github/gitlab/bitbucket. You don't have to edit the file and it is not a format that any other program has to parse, so I think this is a reasonable choice.What does this approach solve, why not just use Pylint by itself?Why use Pylint-IgnoreProblem 1: NoiseThere is a reason flake8 is used so much more often than Pylint. The problem of "noise" is acknowledgedearly in the documentationof Pylint. In fact, the frustration of using Pylint is so obvious that it is even the topic of the project's tag-line: "It's not just a linter that annoys you!".Pylint-Ignore doesn't get rid of this noise of course, but it does put in a dedicated place, rather than Spam in your terminal. Each issue with your code is one entry in a file, rather than a line that you have to scan again and again.Once you've established silence as your baseline, you can trust that you only have to deal with two states: OK and FAIL. This vastly reduces cognitive load for developers and makes it possible for you to integrate the linter into your CI system, even if you haven't yet dealt with every last Pylint message.Problem 2: Setup CostI won't belabour this point, but it's better if you can spend as little time as possible to just get started using a useful tool, rather than putting it off into the future, possibly indefinitely or only using it occasionally rather than making it a part of your regular workflow.That being said, the sooner you take the time to pay down this setup cost, and to disable messages in your configuration that are actual noise, the more useful Pylint will be for you. Every useless message will increase the likelihood that you miss one of the more important messages.Even if you've setup Pylint perfectly and are done with the initial cleanup of your codebase, there might be reason for you to continue to use Pylint-Ignore in your development workflow.Problem 3: Diligence is ScarceWithout Pylint-Ignore, chances are, you (or your teammates) will be overzealous with thedisablesection of your configuration. Sooner or later, you will be short on time and effectively turn the linter off. Who will later know or care to look if the message was disabled because it is genuinely useless or if you just had other priorities at that moment? You can try to remind yourself to review things, you can add aTODOcomment which you hopefully remember togrepfor regularly, but there is a high chance that such good intentions will sooner or later go by the wayside.With Pylint-Ignore, you have a dedicated file in your repository, which is more explicit and visible than the other options. The entries are ordered by importance, rather than appearing more or less randomly on your terminal. You can focus your diligence on other things, and deal with minor linting issues when you have time, or perhaps leave them open as a first contribution for a new member of your team, just so they can get used to your workflow.Problem 4: Malicious ComplianceYou may find some messages useful, but with an existing codebase, the work would be too much at once. You don't want to disable it, but you don't want to start with it enabled either. An example is perhaps themissing-function-docstringmessage. If you were to enabled it, you may find a pattern like this emerge:defget_author_name()->str:"""Gets the author name and returns it as a string."""In case it's not obvious, the above doc-string is redundant, it adds no new information relative to what is already contained in the function name and types. In other words, the temptation is to pacify the linter by changing the code in ways that are at best a useless waste of time and at worst they are malicious and counterproductive.You are in control, as you can just ignore and commit a change if you feel that ignoring the linter is justified by your current priorities. With Pylint-Ignore you don't have to halt the train because a delicate flower fainted in wagon 2 fainted at the sight of oil spraying all over her luggage and make your journey on-time. Thepylint-ignore.mdwill keep track of the issue and you can deal with it once you've arrived at the station, not while you're running at full steam.Problem 5: False PositivesWhile you can and should deal with most false positives usingdisablecomments, there are some cases where you'd rather not do that andsome cases where that isn't even possible. For such edge cases, you can just permanently leave an entry in thepylint-ignore.mdand still benefit from an otherwise useful message if new cases pop up.Motivation/Why use PylintIf you are not convinced of the usefulness of Pylint, linters, or static analysis in general (and perhaps think they are mostly make-work for people who are overly pedantic) let me show you what convinced me to use Pylint.Dynamic Code and Scope Related BugsSome code may syntactically valid Python and will even execute without raising an error and yet is almost certainly not what the author intended. To be sure, if you have proper testing, you will catch such bugs, but even so, static analysis may pay its dues if it can help you catch such bugs more quickly.deffrobnicate(seq:Sequence[int]):total=0forvalueinseq:total+=valuereturnvalue/len(seq)The above code will "work", depending on how you call it, it won't even throw an error and yet it is almost certainly not correct. Were the function longer than 5 lines, the bug would perhaps be less obvious. Just recently I spent at least an hour tracking down such a bug, which had made it into production. In any case, Pylint will report the following message for such code:W0631: Using possibly undefined loop variable 'value'
  (undefined-loop-variable)There are other messages, related toname shadowingand unused arguments that I have found to be particularly useful in that they have pointed to actual bugs, rather than "mere" preferences or "best-practices" according to the authors of Pylint.Supporting Code ReviewThe perhaps most important aspect of a linter, whenever working with other people, is that the feedback related to mundane issues of code styling will come from a computer rather than from another person. This is a benefit, both the reviewer and to the author:It is not fun to spend valuable time on giving repetitive feedback on mundane issues that can be automated.It's not fun, perhaps even embarrassing to have your own stupid mistakes be pointed out during review.A linter also allows you to establish a rule that will end discussions about subjective style preferences. Everybody might agree that any particular style is stupid, but the endless discussion about code style is even more stupid. So, establish this rule:If it passes the linter, the discussion is over(except of course if the linter only passes because it was maliciously disabled). This is a similar argument as is made for the use of code formatters and its main value is that it allows you to focus your review time on the actual problem related to the code.Catching Python GotchasJunior programmers and even (experienced programmers who are new to Python) may not be aware of common pitfalls of working with Python. They need every help they can get and you can look at static analysis as a form of codified knowledge and automated communication from experienced programmers. The code thatyouwrite may be perfect, but hell is other people, and Pylint can help to keep some minimum standards in your projects, even when you on-board new developers.A Nudge to ImproveWhen you're hacking away, focused entirely on solving the actual problem, getting the actual work™ done, you can end up with some code that may well work, may well pass all of your tests, may well be efficient and may even be (let's just postulate for the sake of argument) optimal and correct. That still doesn't mean, that anybody but the author can understand it.R0902 Too many instance attributes (10/7) (too-many-instance-attributes)Simple code metrics such astoo-many-locals,too-many-branches, etc. may well be subjective, pedantic, paternalistic gamification nonsense, and of course suchmetrics should not be turned into targets. The question is, how do you use them. If they are triggering very often, then the threshold may well be too low and you should increase it to a tolerable level.  If your code is perfect as it is, then there is no shame, perhaps it's even a badge of honor to add a comment such as this:classToCoolForSchool():# pylint:disable=too-many-branches# behold this glorious perfection 🤘 — rockstar@unicorn.io...Such cases aside, a common reason for complicated code is that the author wastoo lazydidn't have the time to re-factor their code so that others could also understand it. I would caution againstcode-golfingsuch cases, just to satisfy the linter. Just consider the message as a nudge to at least take a second look, to a least consider looking for obviously better ways to structure your code.AlternativesTo the extent that the excessive noise of Pylint has scared you away from using it, I hope you will findpylint-ignorehelpful to at least get started. Here is another approach you may prefer.Selective Opt-InAn alternative approach is suggested byItamar Turner-Trauring with "Why Pylint is both useful and unusable, and how you can actually use it"is in essence to do the following:First, setup Pylint to do nothing: disable all messagesSelectively enable some checks and keep them if they are valuableRepeatObviously, this is abbreviated, so I encourage you to read his article if selective whitelisting is a better approach for you. For me, this approach suffers from the diligence issue, as it requires you to revisit the configuration at least a few times, keep track of what you've found to be valuable and so you run a higher risk of neglecting it.Automated disable commentsAnother automated approach is to usepylint-silent. Be sure to use version control if you consider this approach.Changelog forhttps://github.com/mbarkhau/pylint-ignore2021.1024Add/document support forpre-commit.
Thank you James Quilty for this contributiongithub/issue/9github/pull/10:heart:.Fixgithub #11: MessagesHandlerMixIn has been removed in pylint 2.12Breaking: Drop support forPython<3.7Breaking: Drop support forpylint<2.4Due to internal API changes in pylint, older versions of pylint
are no longer supported. If you need to use an older version of
pylint, you will have to pinpylint-ignore==2021.1021.2021.1020Fixgithub #6: Issue with paths on windows.Thank you davidsheldon2021.1019Fixgithub #5: Missing fixture files in source distributionFixgithub #4: Bug related to trailing-whitespaceThank you @agraul (Alexander Graul) for finding these issues.2021.1018Fixgithub #2: Typerror2020.1014Fixgitlab #2: Bug related to invokation with invalid arguments (which caused the underlying pylint error to be hidden).2020.1013Fix: bugs related to multiprocessing on MacOSX and Windows2020.1012Fix: enable use of--jobs=<n>withn > 12020.1008 - 2020.1011Fix: compatability with python 2.7 and pylint 1.9.52020.1007Add overview section topylint-ignore.mdfile.Fix: Handling of issues not related to a specific file or line (e.g.duplicate-codeacross multiple files)Fix: parsing of--ignorefileargument.Fix: parsing of--jobsargument.Allow ignore of(E) errormessages again, prioritize entries, instead in ignorefile.2020.1006Don't ignore messages of type(E) error, for probable bugs in the code2020.1003Initial release