Can't load custom pylint module - python-3.x

Question

I am following a simple tutorial that creates a custom checker/module for Pylint. The code looks like this.
bad_code.py
def func():
print("Bad code")
return
useless_return.py (This is the checker)
import astroid
from pylint import checkers
from pylint import interfaces
from pylint.checkers import utils
class UselessReturnChecker(checkers.BaseChecker):
__implements__ = interfaces.IAstroidChecker
name = 'useless-return'
msgs = {
'R2119': ("Useless return at end of function or method",
'useless-return',
'Emitted when a bare return statement is found at the end of '
'function or method definition'
),
}
#utils.check_messages('useless-return')
def visit_functiondef(self, node):
"""
Checks for presence of return statement at the end of a function
"return" or "return None" are useless because None is the default
return type if they are missing
"""
# if the function has empty body then return
if not node.body:
return
last = node.body[-1]
if isinstance(last, astroid.Return):
# e.g. "return"
if last.value is None:
self.add_message('useless-return', node=node)
# e.g. "return None"
elif isinstance(last.value, astroid.Const) and (last.value.value is None):
self.add_message('useless-return', node=node)
def register(linter):
"""required method to auto register this checker"""
linter.register_checker(UselessReturnChecker(linter))
Note that both files are in the project root.
Then I executed the following command to test it.
$ pylint --load-plugins=useless_return bad_code.py
It throws errors:
Traceback (most recent call last):
File "/path/to/my/project/venv/lib/python3.8/site-packages/pylint/lint/pylinter.py", line 609, in load_plugin_configuration
module = astroid.modutils.load_module_from_name(modname)
File "path/to/my/project/venv/lib/python3.8/site-packages/astroid/modutils.py", line 228, in load_module_from_name
return importlib.import_module(dotted_name)
File "/usr/lib/python3.8/importlib/__init__.py", line 127, in import_module
return _bootstrap._gcd_import(name[level:], package, level)
File "<frozen importlib._bootstrap>", line 1014, in _gcd_import
File "<frozen importlib._bootstrap>", line 991, in _find_and_load
File "<frozen importlib._bootstrap>", line 973, in _find_and_load_unlocked
ModuleNotFoundError: No module named 'useless_return'
During handling of the above exception, another exception occurred:
Traceback (most recent call last):
File "path/to/my/project/venv/bin/pylint", line 8, in <module>
sys.exit(run_pylint())
File "path/to/my/project/venv/lib/python3.8/site-packages/pylint/__init__.py", line 24, in run_pylint
PylintRun(sys.argv[1:])
File "path/to/my/project/venv/lib/python3.8/site-packages/pylint/lint/run.py", line 383, in __init__
linter.load_plugin_configuration()
File "path/to/my/project/venv/lib/python3.8/site-packages/pylint/lint/pylinter.py", line 613, in load_plugin_configuration
self.add_message("bad-plugin-value", args=(modname, e), line=0)
File "path/to/my/project/venv/lib/python3.8/site-packages/pylint/lint/pylinter.py", line 1519, in add_message
self._add_one_message(
File "path/to/my/project/venv/lib/python3.8/site-packages/pylint/lint/pylinter.py", line 1456, in _add_one_message
self.stats.increase_single_module_message_count(self.current_name, msg_cat, 1)
File "path/to/my/project/venv/lib/python3.8/site-packages/pylint/utils/linterstats.py", line 296, in increase_single_module_message_count
self.by_module[modname][type_name] += increase
KeyError: None
Note that I don't have pylint installed globally, only in my venv.
The command which pylint returns path/to/my/project/venv/bin/pylint.
Help is much appreciated.

Answer 1

I can't confirm this is the best way to test a custom checker. But the only way that I found is to copy the custom module into pylint/checkers and run the command. To test only the custom checker
$pylint --load-plugins=useless_return --disable=all --enable=useless-return bad_code.py

Answer 2

EDIT: Discussion with Pylint maintainers going very well, it seems like a really responsive project. The recommendation from them is definitely to install your custom checker as part of a module, like any other library you might install with pip. Expect to see some changes around this to bring more clarity soon!
I had a similar problem, and I think I've identified the root cause. I've opened an issue with pylint: PyCQA/pylint#7264
TL;DR when you specify the module using the command line, it tries to load and register it without the current directory added to the sys path (even if your init-hook does this), so cannot find the file to import.
Workarounds
Until such time as there is a fix, or this is called out in documentation, you have a couple of options:
As OP found, putting the module in pylints checkers directory does solve this. You can put it in any sys.path directory other than the current working dir. EDIT: pylint maintainers recommend installing your custom checker into your site packages as its own package.
Do not use the command line argument for --load_plugins, instead use a pylintrc file, in the same directory as your code, that specifies at least the following two things:
[MASTER]
# Python code to execute, usually for sys.path manipulation such as
# pygtk.require().
init-hook="from pylint.config import find_pylintrc; import sys; sys.path.append(os.path.dirname(find_pylintrc()))"
# List of plugins (as comma separated values of python module names) to load,
# usually to register additional checkers.
load-plugins=your_custom_checker