Registry / testing / flake8-expression-complexity

flake8-expression-complexity

JSON →
library0.0.11pypypiunverified

flake8-expression-complexity is an extension for Flake8 that enforces limits on the complexity of individual expressions within Python code. It works by analyzing abstract syntax tree (AST) nodes to score expressions and reports an `ECE001` error when a configurable threshold is exceeded. The current version is 0.0.11, and it maintains a moderate release cadence, with updates addressing new features and bug fixes.

pip install flake8-expression-complexity
INSTALL
IMPORT
SIG · FLAKE8-EXPRESSION-
F
flake8-expression-complexity
testingpythonv0.0.11
Install
2.0s avg
Import
—
Disk
15MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v0.0.11 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ timeout
✕ timeout
py 3.11
✕ timeout
✓ 1.9s
py 3.12
✓ —
✓ 1.83s
py 3.13
✓ —
✓ 2.28s
py 3.9
✕ timeout
✕ timeout
15MB installed
● package 15MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Automatic Plugin Discovery
✓ This plugin is automatically discovered by Flake8 once installed. No direct Python import is needed; it integrates directly with the `flake8` command-line tool.
Flake8 plugins are not imported directly in Python code. Instead, they extend the functionality of the `flake8` command-line tool through entry points.

After installing, `flake8-expression-complexity` automatically integrates with the `flake8` command. To use it, simply run `flake8` against your Python files. The plugin provides the `ECE001` error code. You can configure the maximum allowed expression complexity using the `--max-expression-complexity` command-line option or in a configuration file (e.g., `setup.cfg`, `tox.ini`, or `.flake8`). The example demonstrates a highly complex `if` condition that would typically trigger an `ECE001` error with a low `max-expression-complexity` setting.

import datetime class User: def __init__(self, is_authorized, credits, subscriptions): self.is_authorized = is_authorized self.total_credits_added = credits self.subscriptions = subscriptions class Subscription: def __init__(self, start_date, end_date): self.start_date = start_date self.end_date = end_date def exists(self): today = datetime.date.today() return self.start_date < today and self.end_date > today class Check: def __init__(self, user, price): self.user = user self.price = price @staticmethod def objects_filter_aggregate_sum(user_obj): # Simulate a complex ORM query result for demonstration # In a real scenario, this would involve database interaction if user_obj.is_authorized: # simplified logic return {'check__sum': 100} return {'check__sum': 0} class UserAction: def __init__(self, datetime_val): self.datetime = datetime_val @staticmethod def objects_filter_last_datetime(user_obj): # Simulate fetching last action datetime # In a real scenario, this would involve database interaction return UserAction(datetime.datetime.now()) def example_function(user): today = datetime.date.today() # This expression will likely exceed the default complexity threshold if ( (user and user.is_authorized) and user.subscriptions.exists() # Simplified to use Subscription.exists and ( user.total_credits_added - Check.objects_filter_aggregate_sum(user)['check__sum'] # Simulate aggregate ) and UserAction.objects_filter_last_datetime(user).datetime > datetime.datetime.now() - datetime.timedelta(days=10) ): print("User meets complex conditions.") # To run flake8 with this plugin, save the above code to 'test_complexity.py' # and execute in your terminal: # flake8 --max-expression-complexity=3 test_complexity.py
flake8 --version
Debug
Known issues
gotchaChained method calls can result in unexpectedly high complexity scores. The plugin's calculation might consider each method call in a chain as contributing significantly to expression complexity (e.g., `obj.method1().method2().method3()` could be flagged as complex), even if it appears readable.
fix
Review the flagged expressions carefully. If the complexity is deemed acceptable for readability, consider increasing the `--max-expression-complexity` threshold or using `# noqa: ECE001` for specific lines. Restructuring chained calls into intermediate variables might also reduce reported complexity.
affects: All versions
gotchaThe default `max-expression-complexity` is 7, which may be too strict or too lenient depending on your project's coding style and requirements.
fix
Adjust the threshold using `--max-expression-complexity=<VALUE>` on the command line or `max-expression-complexity = <VALUE>` in your Flake8 configuration file (`setup.cfg`, `tox.ini`, or `.flake8`). Experiment with values to find a suitable balance for your codebase.
affects: All versions
gotchaThis plugin specifically targets expression complexity (ECE001), which is distinct from the cyclomatic complexity of functions (C901) checked by Flake8's built-in `mccabe` plugin. Users often confuse these two, leading to misinterpretations of the reported errors.
fix
Understand the difference: ECE001 relates to the complexity of a single line/expression, while C901 relates to the number of independent paths through a function. Configure both plugins independently to manage different aspects of code complexity. `flake8-expression-complexity` adds ECE001; `mccabe` adds C901.
affects: All versions
gotchaFor projects utilizing Django ORM, queries can naturally become long and appear complex, triggering `ECE001` errors despite being semantically straightforward.
fix
Enable the `--ignore-django-orm-queries-complexity` option when running `flake8` or set `ignore-django-orm-queries-complexity = True` in your Flake8 configuration file to prevent false positives on Django ORM queries.
affects: All versions
Upgrade
Version history
0.0.11latest on PyPI · released Mar 19, 2022
Audit
Dependencies
flake8requiredThis library is a plugin for Flake8 and requires Flake8 to be installed and run.
Agent activity
4 hits · last 30 days
node
4
Resources
flake8-expression-complexity — pip install flake8-expression-complexity · libregistry