Document the setting of the ``sys/PYTHONPATH`` in our doc and on a popular stackoverflow answer

[Pierre-Sassoulas]

This is a byproduct of the approach for setting the sys/PYTHONPATH recommended here: https://stackoverflow.com/questions/1899436/pylint-unable-to-import-error-how-to-set-pythonpath. A "best practices" approach for this problem should probably be highly visible somewhere here in this Github repo.

Originally posted by @genzgd in #9105 (comment)

[elcolie]

I am trying to use pylint in pre-commit hook.
.pylintrc

[MASTER]
init-hook="from pylint.config import find_pylintrc;import os, sys; sys.path.append(os.path.dirname(find_pylintrc()))"

.pre-commit-config.yaml

  - repo: https://github.com/pycqa/pylint
    rev: v3.1.0
    hooks:
      - id: pylint

Error:

pylint...................................................................Failed
- hook id: pylint
- exit code: 1

Traceback (most recent call last):
  File "/Users/sarit/.cache/pre-commit/repofcl8gkgn/py_env-python3.12/bin/pylint", line 8, in <module>
    sys.exit(run_pylint())
             ^^^^^^^^^^^^
  File "/Users/sarit/.cache/pre-commit/repofcl8gkgn/py_env-python3.12/lib/python3.12/site-packages/pylint/__init__.py", line 34, in run_pylint
    PylintRun(argv or sys.argv[1:])
  File "/Users/sarit/.cache/pre-commit/repofcl8gkgn/py_env-python3.12/lib/python3.12/site-packages/pylint/lint/run.py", line 162, in __init__
    args = _config_initialization(
           ^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/sarit/.cache/pre-commit/repofcl8gkgn/py_env-python3.12/lib/python3.12/site-packages/pylint/config/config_initialization.py", line 57, in _config_initialization
    exec(utils._unquote(config_data["init-hook"]))  # pylint: disable=exec-used
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<string>", line 1, in <module>
ImportError: cannot import name 'find_pylintrc' from 'pylint.config' (/Users/sarit/.cache/pre-commit/repofcl8gkgn/py_env-python3.12/lib/python3.12/site-packages/pylint/config/__init__.py)

[michaelbarton]

I believe this should be something like:

[MASTER]
init-hook="from pylint.config import find_default_config_files; import sys; sys.path.append(next(find_default_config_files()).parent.as_posix())"

This worked for me similar to the removed find_pylintrc function.
I added an answer to this effect on SO: https://stackoverflow.com/a/78479645/91144

[jaymecd]

Following approach will fail if pylint was installed within difference venv, eg. with pipx.

Came with following init-hook as a workaround to support both, and VIRTUAL_ENV ennvar (for activated venv) and direct local .venv directory:

[MASTER]
init-hook="import glob, os; venv=os.getenv('VIRTUAL_ENV'); [sys.path.insert(0, p) for p in set(glob.glob(f'{venv}/lib/python*/site-packages')+glob.glob('.venv/lib/python*/site-packages'))]"

or for activated venv only:

[MASTER]
init-hook="import glob, os; venv=os.getenv('VIRTUAL_ENV'); [sys.path.insert(0, p) for p in glob.glob(f'{venv}/lib/python*/site-packages') if venv]"

it's similar to pylint-venv, but w/o external dependency.