complexipy 5.0.0, cognitive complexity tool
Posted by fexx3l@reddit | Python | View on Reddit | 25 comments
Hi r/Python! I've released the version v5.0.0. This version introduces new changes that will improve the tool adoption in existing projects and the cognitive complexity algorithm itself.
What My Project Does
complexipy is a command-line tool and library that calculates the cognitive complexity of Python code. Unlike cyclomatic complexity, which measures how complex code is to test, cognitive complexity measures how difficult code is for humans to read and understand.
Target audience
complexipy is built for:
- Python developers who care about readable, maintainable code.
- Teams who want to enforce quality standards in CI/CD pipelines.
- Open-source maintainers looking for automated complexity checks.
- Developers who want real-time feedback in their editors or pre-commit hooks.
- Researcher scientists, during this year I noticed that many researchers used
complexipyduring their investigations on LLMs generating code.
Whether you're working solo or in a team, complexipy helps you keep complexity under control.
Comparison to Alternatives
Sonar has the original version which runs online only in GitHub repos, and it's a slower workflow because you need to push your changes, wait until their scanner finishes the analysis and check the results. I inspired from them to create this tool, that's why it runs locally without having to publish anything and the analysis is really fast.
Highlights of v5.0.0
- Snapshots:
--snapshot-createwritescomplexipy-snapshot.jsonand comparisons block regressions; auto-refresh on improvements, bypass with--snapshot-ignore. - Change tracking: per-target cache in
.complexipy_cacheshows deltas/new failures for over-threshold functions using stable BLAKE2 keys. - Output controls:
--failedto show only violations;--color auto|yes|no; richer summaries of failing functions and invalid paths. - Excludes and errors: exclude entries resolved relative to the root and only applied when they match real files/dirs; missing paths reported cleanly instead of panicking.
Breaking: Conditional scoring now counts each elif/else branch as +1 complexity (plus its boolean test), aligning with Sonar’s cognitive-complexity rules; expect higher scores for branching.
GitHub Repo: https://github.com/rohaquinlop/complexipy
Scelte@reddit
How is this substantially better than https://docs.astral.sh/ruff/rules/too-many-branches/, which is already everywhere?
fexx3l@reddit (OP)
Honestly, I didn't know this rule exists so yeah, my project doesn't have value :( thank you for sharing it
Lil_SpazJoekp@reddit
Nah you still learned from it.
Routine_Ambassador71@reddit
I’m sorry - that’s gotta be a gut punch.
is_it_fun@reddit
It was still great that you did it. Thank you for sharing!
StengahBot@reddit
Happens all the time with my side projects
InspectahDave@reddit
it's a really good effort thanks for this. The code is surprisingly compact. I found a nice discussion on cognitive load [here](statics.teams.cdn.office.net/evergreen-assets/safelinks/2/atp-safelinks.html) which is worth a read and may help you flesh out your examples and why section that some posters have flagged is missing. I think understanding the power of this tool will increase your impact for sure.
Nater5000@reddit
Bumping from major version 1 to 5 within the span of a year indicates that this project is way too volatile for people to invest in.
fexx3l@reddit (OP)
I know, I was pretty new on how to handle the versions a year ago, so once I created the very first versions `0.x` then I created `1.x` and my algorithm didn't change, and later I improved the algorithm because I just followed the paper but the Python statements and had to keep changing the implementation. This was a huge mistake I did, and I still regret about it.
silvertank00@reddit
You should have bumped the minor version not the mayor then. When I saw this post, my first thought was: "wait, 5.x.x, you mean FIVE point something?? wth" Check out i.e. sqlalchemy's versioning, it makes much much more sense and you could learn a lot from it.
fexx3l@reddit (OP)
Yeah, I agree with you, only that as there was a breaking change of the algorithm therefore I thought that would be better to do it on a major. Do you think that would be bad to change the versioning of the project? like roll it back to something like 0.x? I feel a little bit lost on what to do with it
InspectahDave@reddit
I think u/silvertank00 is talking about semantic versioning which is standard afaik. So yes, if there are breaking changes, then you should update the major version as you say. pyzmq is another heavily used package and that's on v23.x.x so I think this just means you need to stay ahead of changes.
Another_mikem@reddit
Honestly it doesn’t matter. Different products use different schemes and it doesn’t actually matter.
Zireael07@reddit
Where do I find some info on how the cognitive complexity is defined/calculated?
fexx3l@reddit (OP)
Currently, on the Sonar paper: cognitive complexity. But I'm planning on adding a section on the docs to explain really well, this is something that have been taking me some time and currently my agenda is tight
99ducks@reddit
That and some code examples with their complexity scores would add a lot.
fexx3l@reddit (OP)
I’ll add them too, thank you for your help
legendarydromedary@reddit
Can you give a quick feel of how complexity is measured? What is considered complex code?
fexx3l@reddit (OP)
Sure, it's based on the G. Ann Campbell paper, in that paper the definition of a high complex code is the one which contain a bunch of nested structures. A structure would be an
if/elif/elsestatement orfor/whileloops. Each can increase the complexity if you start to nest them, let's say that the branching on a code increases the complexity because you'll need to understand for each case when/how it would be executed. Therefore, a function which should do only one thing then is doing more things than the expected, then you should split that function into multiple functions (G. Ann Campbell doesn't mention this in the paper, but this reminds of the SOLID principle, Single Responsibility). Sonar by default says that the max complexity a function can have is15, but it doesn't say why, that's whycomplexipylets the users configure their max complexities.rm-rf-rm@reddit
thats just 1 narrow measure - and its better termed as complicated instead of complex.
The human brain is complex. Navigating post office mail forwarding forms is complicated.
CzyDePL@reddit
Does it analyze all function calls from selected entry point? Just because code is split into a bunch of smaller functions with one nesting level doesn't mean it's readable and easy to reason about.
mikat7@reddit
Do you have any comparison with the mccabe complexity rule in ruff?
fexx3l@reddit (OP)
If I'm not wrong, it's on the paper the comparison vs the existing rules, but I'm not 100% sure
Inevitable-Tap-7891@reddit
Does it find the vulnerability or dependency risks in the code
fexx3l@reddit (OP)
No, I've created another tool which does this, it's immunipy