Flake8 does not find user config as documentation claims (4.0+ docs are wrong)

[justin-f-perez]

Please describe how you installed Flake8

$ pipx install flake8
# but it doesnt matter; docs are wrong

Please provide the exact, unmodified output of flake8 --bug-report

N/A (docs are wrong) but here it is anyway

{
  "dependencies": [],
  "platform": {
    "python_implementation": "CPython",
    "python_version": "3.9.7",
    "system": "Darwin"
  },
  "plugins": [
    {
      "is_local": false,
      "plugin": "mccabe",
      "version": "0.6.1"
    },
    {
      "is_local": false,
      "plugin": "pycodestyle",
      "version": "2.8.0"
    },
    {
      "is_local": false,
      "plugin": "pyflakes",
      "version": "2.4.0"
    }
  ],
  "version": "4.0.1"
}

Please describe the problem or feature

The documentation for 4+ claims global user configuration is loaded on *nix systems from ~/.config/flake8.

Note that Flake8 looks for ~.flake8 on Windows and ~/.config/flake8 on Linux and other Unix systems

As of 4.0, this is no longer true.

If this is a bug report, please explain with examples (and example code) what you expected to happen and what actually happened.

#!/usr/bin/env bash
# WARNING: if you have anything in ~/.config/flake8 or ~/.flake8, this script will delete it

TEST_PROJ_DIR=~/the-docs-are-a-lie
mkdir -p $TEST_PROJ_DIR
# note: over 80 chars, under 100
echo '"23456789012345678901234567890123456789012345678901234567890123456789012345678901234567890"' > $TEST_PROJ_DIR/test.py

# make a virtual environment to pip install flake8 into
python3 -m venv $TEST_PROJ_DIR/.venv
source $TEST_PROJ_DIR/.venv/bin/activate
pip install flake8

# "Note that Flake8 looks for ~\.flake8 on Windows and ~/.config/flake8 on Linux and other Unix systems"
# https://flake8.pycqa.org/en/4.0.1/user/configuration.html#user-configuration
mkdir -p ~/.config
echo '[flake8]' > ~/.config/flake8
echo 'max-line-length=100' >> ~/.config/flake8

echo "This following gives an E501 because flake8 doesn't load config from ~/.config/flake8 as the docs claim"
flake8 $TEST_PROJ_DIR/test.py

mv ~/.config/flake8 ~/.flake8
echo "No more line length error because we moved the config to ~/.flake8, where flake8 does manage to find it"
flake8 $TEST_PROJ_DIR/test.py

deactivate
rm -r $TEST_PROJ_DIR
rm ~/.flake8

note: flake8 only happened to find the config file in the home directory because it was a parent of the 'test proj dir'

[justin-f-perez]

ok after some more digging I realize the docs didn't got updated to reflect this breaking change. Ironically, this change was made to drop support for a feature that confused folks who didn't bother to read the docs, but I was confused by flake8's behavior because I did read them...

These incorrect bits should be removed, and I think this change would be less punishing if this change of behavior were easier to find without digging into the change log. I think it would be best to put a notice that support for this feature was dropped in the same place that describes where flake8 looks for configs (i.e., replace the user config section with "DEPRECATED: As of 4.0 flake8 no longer supports...")

I'll submit a PR when I have time to familiarize myself with editing the docs but as of now I'm working 80 hours/week and debugging this cost half a night of sleep

[asottile]

this was already fixed, you're looking at an old version of the docs -- make sure you're looking at latest

[justin-f-perez]

@asottile Thanks! I didn't notice it was fixed on latest. i usually check stable docs for anything not installed from source... Maybe worth cutting a minor release to reflect doc changes there? Hate to see this eat up any more of your or anyone else's time.

in the future ill check in on latest even if installed from pypi

thx for all your hard work

[asottile]

a release would create a lot of toil despite no code changes so that's not going to happen

[madrover]

In case that you miss that feature, as I did :), a shell alias can be convenient alternative:

alias flake8='flake8 --config ~/.config/flake8'