Release branch for 4.0.0

[Pierre-Sassoulas]

What's new in Pylint 4.0.0?

Release date: 2025-10-12

• Pylint now supports Python 3.14.

• Pylint's inference engine (astroid) is now much more precise,
  understanding implicit booleanness and ternary expressions. (Thanks @zenlyj!)

Consider this example:

class Result:
    errors: dict | None = None

result = Result()
if result.errors:
    result.errors[field_key]
    # inference engine understands result.errors cannot be None
    # pylint no longer raises unsubscriptable-object

The required astroid version is now 4.0.0. See the astroid changelog for additional fixes, features, and performance improvements applicable to pylint.

• Handling of invalid-name at the module level was patchy. Now,
  module-level constants that are reassigned are treated as variables and checked
  against --variable-rgx rather than --const-rgx. Module-level lists,
  sets, and objects can pass against either regex.

Here, LIMIT is reassigned, so pylint only uses --variable-rgx:

LIMIT = 500  # [invalid-name]
if sometimes:
    LIMIT = 1  # [invalid-name]

If this is undesired, refactor using exclusive assignment so that it is
evident that this assignment happens only once:

if sometimes:
    LIMIT = 1
else:
    LIMIT = 500  # exclusive assignment: uses const regex, no warning

Lists, sets, and objects still pass against either const-rgx or variable-rgx
even if reassigned, but are no longer completely skipped:

MY_LIST = []
my_list = []
My_List = []  # [invalid-name]

Remember to adjust the regexes and allow lists to your liking.

Breaking Changes

• invalid-name now distinguishes module-level constants that are assigned only once
  from those that are reassigned and now applies --variable-rgx to the latter. Values
  other than literals (lists, sets, objects) can pass against either the constant or
  variable regexes (e.g. "LOGGER" or "logger" but not "LoGgEr").

  Remember that --good-names or --good-names-rgxs can be provided to explicitly
  allow good names.

  Closes Make invalid-name distinguish between module constants and module variables #3585

• The unused pylintrc argument to PyLinter.__init__() is deprecated
  and will be removed.

  Refs Some refactors of configuration file discovery #6052

• Commented out code blocks such as # bar() # TODO: remove dead code will no longer emit fixme.

  Refs W0511: Doesn't detect TODO in docstrings #9255

• pyreverse Run was changed to no longer call sys.exit() in its __init__.
  You should now call Run(args).run() which will return the exit code instead.
  Having a class that always raised a SystemExit exception was considered a bug.

  Normal usage of pyreverse through the CLI will not be affected by this change.

  Refs False positive E0601: used-before-assignment in try and while block #9689

• The suggestion-mode option was removed, as pylint now always emits user-friendly hints instead
  of false-positive error messages. You should remove it from your conf if it's defined.

  Refs Always use the suggestion mode for no-member / c-extension-no-member #9962

• The async.py checker module has been renamed to async_checker.py since async is a Python keyword
  and cannot be imported directly. This allows for better testing and extensibility of the async checker functionality.

  Refs Checker async.py couldn't be imported anywhere because it uses reserved word. #10071

• The message-id of continue-in-finally was changed from E0116 to W0136. The warning is
  now emitted for every Python version since it will raise a syntax warning in Python 3.14.
  See PEP 765 - Disallow return/break/continue that exit a finally block <https://peps.python.org/pep-0765/>_.

  Refs Update checks for PEP 765 - return/break/continue in finally block #10480

• Removed support for nmp.NaN alias for numpy.NaN being recognized in ':ref:nan-comparison'. Use np or numpy instead.

  Refs Remove support for nmp as import alias for numpy #10583

• Version requirement for isort has been bumped to >=5.0.0.
  The internal compatibility for older isort versions exposed via pylint.utils.IsortDriver has
  been removed.

  Refs Removal of mandatory isort dependency for import position check #10637

New Features

• comparison-of-constants now uses the unicode from the ast instead of reformatting from
  the node's values preventing some bad formatting due to utf-8 limitation. The message now uses
  " instead of ' to better work with what the python ast returns.

  Refs Pylint crashes with "'\U00010000' == '\ud800\udc00'" #8736

• Enhanced pyreverse to properly distinguish between UML relationship types (association, aggregation, composition) based on object ownership semantics. Type annotations without assignment are now treated as associations, parameter assignments as aggregations, and object instantiation as compositions.

  Closes Pyreverse: composition / aggregation arrow strange behavior (and field annotation bug) #9045
  Closes Pyreverse: Duplicate arrows when class attribute is assigned more than once #9267

• The fixme check can now search through docstrings as well as comments, by using
  check-fixme-in-docstring = true in the [tool.pylint.miscellaneous] section.

  Closes W0511: Doesn't detect TODO in docstrings #9255

• The use-implicit-booleaness-not-x checks now distinguish between comparisons
  used in boolean contexts and those that are not, enabling them to provide more accurate refactoring suggestions.

  Closes Suggested change for use-implicit-booleaness-not-comparison doesn't seem right #9353

• The verbose option now outputs the filenames of the files that have been checked.
  Previously, it only included the number of checked and skipped files.

  Closes Print the filepaths of checked files when the verbose option is activated #9357

• colorized reporter now colorizes messages/categories that have been configured as fail-on in red inverse.
  This makes it easier to quickly find the errors that are causing pylint CI job failures.

  Closes Dynamic color mapping for "fail-on" messages/categories in ColorizedTextReporter #9898

• Enhanced support for @Property decorator in pyreverse to correctly display return types of annotated properties when generating class diagrams.

  Closes Enhanced support for @Property decorator in pyreverse #10057

• Add --max-depth option to pyreverse to control diagram complexity. A depth of 0 shows only top-level packages, 1 shows one level of subpackages, etc.
  This helps manage visualization of large codebases by limiting the depth of displayed packages and classes.

  Refs Add --max-depth option to control diagram complexity #10077

• Handle deferred evaluation of annotations in Python 3.14.

  Closes 3.14 annotation evaluation is deferred #10149

• Enhanced pyreverse to properly detect aggregations for comprehensions (list, dict, set, generator).

  Closes Composition not detected correctly in list comprehension #10236

• pyreverse: add support for colorized output when using output format mmd (MermaidJS) and html.

  Closes pyreverse: colored classes and packages in HTML generated diagrams #10242

• pypy 3.11 is now officially supported.

  Refs GH Actions: Add pypy3.11 to testing matrix #10287

• Add support for Python 3.14.

  Refs Add support for Python 3.14 #10467

• Add naming styles for ParamSpec and TypeVarTuple that align with the TypeVar style.

  Refs Add naming styles for ParamSpec and TypeVarTuple #10541

New Checks

• Add match-statements checker and the following message:
  bare-name-capture-pattern.
  This will emit an error message when a name capture pattern is used in a match statement which would make the remaining patterns unreachable.
  This code is a SyntaxError at runtime.

  Closes Check for name capture syntax errors #7128

• Add new check async-context-manager-with-regular-with to detect async context managers used with regular with statements instead of async with.

  Refs False Context manager 'async_generator' doesn't implement __enter__ and __exit__ #10408

• Add break-in-finally warning. Using break inside the finally clause
  will raise a syntax warning in Python 3.14.
  See PEP 765 - Disallow return/break/continue that exit a finally block <https://peps.python.org/pep-0765/>_.

  Refs Update checks for PEP 765 - return/break/continue in finally block #10480

• Add new checks for invalid uses of class patterns in :keyword:match.

  • :ref:invalid-match-args-definition is emitted if :py:data:object.__match_args__ isn't a tuple of strings.
  • :ref:too-many-positional-sub-patterns if there are more positional sub-patterns than specified in :py:data:object.__match_args__.
  • :ref:multiple-class-sub-patterns if there are multiple sub-patterns for the same attribute.

  Refs Add new checks for match class patterns #10559

• Add additional checks for suboptimal uses of class patterns in :keyword:match.

  • :ref:match-class-bind-self is emitted if a name is bound to self instead of
    using an as pattern.
  • :ref:match-class-positional-attributes is emitted if a class pattern has positional
    attributes when keywords could be used.

  Refs R0903:too-few-public-methods for private methods #10586

• Add a consider-math-not-float message. float("nan") and float("inf") are slower
  than their counterpart math.inf and math.nan by a factor of 4 (notwithstanding
  the initial import of math) and they are also not well typed when using mypy.
  This check also catches typos in float calls as a side effect.

  The :ref:pylint.extensions.code_style need to be activated for this check to work.

  Refs [consider-math-not-float] Add a check for float("inf"), float("nan") and float("typos") #10621

False Positives Fixed

• Fix a false positive for used-before-assignment when a variable defined under
  an if and via a named expression (walrus operator) is used later when guarded
  under the same if test.

  Closes [used-before-assignment] False positive for "same test" exception when test is a walrus operator #10061

• Fix :ref:no-name-in-module for members of concurrent.futures with Python 3.14.

  Closes False positive no-name-in-module for ProcessPoolExecutor in python 3.14 #10632

False Negatives Fixed

• Fix false negative for used-before-assignment when a TYPE_CHECKING import is used as a type annotation prior to erroneous usage.

  Refs false negative: used-before-assignment w/ TYPE_CHECKING guard #8893

• Match cases are now counted as edges in the McCabe graph and will increase the complexity accordingly.

  Refs [mccabe - too-complex] Add each match case as an edge in the graph #9667

• Check module-level constants with type annotations for invalid-name.
  Remember to adjust const-naming-style or const-rgx to your liking.

  Closes Annotated module level constant not checked for invalid-name #9770

• Fix false negative where function-redefined (E0102) was not reported for functions with a leading underscore.

  Closes False Negative function-redefined when function named with leading underscore #9894

• We now raise a logging-too-few-args for format string with no
  interpolation arguments at all (i.e. for something like logging.debug("Awaiting process %s")
  or logging.debug("Awaiting process {pid}")). Previously we did not raise for such case.

  Closes Detect missing arguments in logging format strings #9999

• Fix false negative for used-before-assignment when a function is defined inside a TYPE_CHECKING guard block and used later.

  Closes [used-before-assignment] Functions defined in type-checking guard not flagged when used later #10028

• Fix a false negative for possibly-used-before-assignment when a variable is conditionally defined
  and later assigned to a type-annotated variable.

  Closes False negative: possibly-used-before-assignment with type annotation after assignment in conditional/loop #10421

• Fix false negative for deprecated-module when a __import__ method is used instead of import sentence.

  Refs False negative for deprecated-module when a __import__ method is used instead of import sentence. #10453

• Count match cases for too-many-branches check.

  Refs Count match cases for too-many-branches #10542

• Fix false-negative where :ref:unused-import was not reported for names referenced in a preceding global statement.

  Refs Update astroid to 4.0.1 #10633

Other Bug Fixes

• When displaying unicode with surrogates (or other potential UnicodeEncodeError),
  pylint will now display a '?' character (using encode(encoding="utf-8", errors="replace"))
  instead of crashing. The functional tests classes are also updated to handle this case.

  Closes Pylint crashes with "'\U00010000' == '\ud800\udc00'" #8736

• Fixed unidiomatic-typecheck only checking left-hand side.

  Closes unidiomatic-typecheck only checks left-hand side #10217

• Fix a crash caused by malformed format strings when using .format with keyword arguments.

  Closes AstroidError when checking against sample bad-format-string code #10282

• Fix false positive inconsistent-return-statements when using quit() or exit() functions.

  Closes Inconsistent report of inconsistent-return-statements when using exit / quit #10508

• Fix a crash in :ref:nested-min-max when using builtins.min or builtins.max
  instead of min or max directly.

  Closes AttributeError: 'Attribute' object has no attribute 'name' in nested-min-max checker #10626

• Fixed a crash in :ref:unnecessary-dict-index-lookup when the index of an enumerated list
  was deleted inside a for loop.

  Closes IndexError: list index out of range in unnecessary-list-index-lookup checker #10627

Other Changes

• Remove support for launching pylint with Python 3.9.
  Code that supports Python 3.9 can still be linted with the --py-version=3.9 setting.

  Refs Drop support for Python 3.9 #10405

Internal Changes

• Modified test framework to allow for different test output for different Python versions.

  Refs Allow different test output for different Python versions #10382

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.96%. Comparing base (ea25969) to head (8729244).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #10639   +/-   ##
=======================================
  Coverage   95.96%   95.96%           
=======================================
  Files         176      176           
  Lines       19502    19502           
=======================================
  Hits        18715    18715           
  Misses        787      787           

Files with missing lines	Coverage Δ
pylint/__pkginfo__.py	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[cdce8p]

Aiming for tomorrow.

I'm working on some last minute multithreading fixes. It would address #10037 and remove the duplicate messages for dynamic plugins with -j2. The change works already, testing it properly might be a different story though. I hop that I can open the PR for it tomorrow.

[DanielNoord]

Would be nice to merge #10641 as well as it technically contains a breaking change to our API and version constraints. User impact should be minimal though and a net positive as there won't be issues with installing pylint and the latest version of isort.

[cdce8p]

@Pierre-Sassoulas Could you run tox -e docs? I do get a small whitespace / line break change here. Not sure if that's just on my system.

pylint/doc/user_guide/checkers/features.rst

Lines 691 to 696 in ea25969

	:too-many-positional-sub-patterns (E1903): *%s expects %d positional sub-patterns (given %d)*
	Emitted when the number of allowed positional sub-patterns exceeds the number
	of allowed sub-patterns specified in `__match_args__`.
	:multiple-class-sub-patterns (E1904): *Multiple sub-patterns for attribute %s*
	Emitted when there is more than one sub-pattern for a specific attribute in a
	class pattern.

[Pierre-Sassoulas]

@Pierre-Sassoulas Could you run tox -e docs? I do get a small whitespace / line break change here. Not sure if that's just on my system.

I just did for 4.1.0-dev0, no changes using python 3.12 / ubuntu 24.04 / the enchant system lib I have currently installed. I have those small changes too when it was generated by someone else though.

[Pierre-Sassoulas]

I'm not that good at reading and following the release documentation. (And will need a new approval 😄)

[jacobtylerwalls]

I get these errors:

/Users/jwalls/pylint/doc/user_guide/messages/error/continue-in-finally.rst:26: WARNING: Include file '/Users/jwalls/pylint/doc/data/messages/c/continue-in-finally/pylintrc' not found or reading it failed [docutils]
/Users/jwalls/pylint/doc/user_guide/messages/warning/continue-in-finally.rst:4: WARNING: duplicate label continue-in-finally, other instance in /Users/jwalls/pylint/doc/user_guide/messages/error/continue-in-finally.rst
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/jwalls/pylint/doc/user_guide/messages/error/continue-in-finally.rst: WARNING: document isn't included in any toctree [toc.not_included]

[cdce8p]

I get these errors: [...]

@jacobtylerwalls Try removing the docs cache. I just deleted the whole doc folder and restored it from git. That seemed to work.

[Pierre-Sassoulas]

I get these errors:

The data message directory keeps old generated messages, after a tox -e docs there's no removal. This morning I had fail for the scientific format checker (not yet merged, work in progress in a local branch), I solved with git clean -dfX (it probably work and it's probably cleaner / safer to just apply make clean from the doc/ directory) (edit: or what Marc said)

[github-actions]

🤖 According to the primer, this change has no effect on the checked open source code. 🤖🎉

This comment was generated for commit 8729244

[Pierre-Sassoulas]

It's done : https://pypi.org/project/pylint/4.0.0/ 🎉 ! Congratulation everyone involved !

[cdce8p]

It's done : https://pypi.org/project/pylint/4.0.0/ 🎉 ! Congratulation everyone involved !

Thanks @Pierre-Sassoulas for doing the actual release 🚀