codecoco 3.5.1__py3-none-any.whl

codecoco-3.5.1.dist-info/METADATA

@@ -0,0 +1,278 @@
+Metadata-Version: 2.4
+Name: codecoco
+Version: 3.5.1
+Summary: Library and CLI to compute the cognitive complexity of Python functions
+Home-page: https://github.com/qwhex/cococo
+Author: Mice Pápai
+Author-email: hello@micepapai.com
+License: MIT
+Keywords: cognitive-complexity cli complexity cococo codecoco
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-python
+Dynamic: summary
+
+# cococo
+
+**co**de **co**gnitive **co**mplexity — a library and CLI to compute the
+cognitive complexity of Python functions.
+
+This is a fork of [Melevir/cognitive_complexity](https://github.com/Melevir/cognitive_complexity)
+(MIT) that adds a command-line tool, modern-Python construct support, and
+Python 3.10+ packaging. Three names differ on purpose: install **`codecoco`**,
+import **`cognitive_complexity`**, run **`cococo`** (`cognitive_complexity` and
+`cococo` were both already taken on PyPI, so the distribution is published as
+`codecoco`).
+
+## Installation
+
+```bash
+pip install codecoco
+# or, with uv:
+uv pip install codecoco
+```
+
+This installs the `cococo` command and the importable `cognitive_complexity`
+package. To install the unreleased tip from the repository instead:
+
+```bash
+pip install git+https://github.com/qwhex/cococo
+```
+
+## Usage
+
+### Command line
+
+```bash
+cococo src/                  # score every function, worst first
+cococo src/ --max 20         # gate: exit non-zero if any function exceeds 20
+cococo a.py b.py --min 10    # only show functions scoring >= 10
+cococo src/ --max 20 --json  # machine-readable report for a pipeline
+cococo src/ --fix            # apply safe guard-clause rewrites in place
+cococo src/ --nested fold    # pre-2.0.0 scoring: fold nested defs into the parent
+cococo src/ --max 20 --baseline .cococo.json  # ratchet: fail only on regressions
+```
+
+`cococo` scores every function, method, and **named nested function** as its own
+unit — a nested `def` is reported on its own row with a qualified name
+(`outer.<locals>.inner`, `Klass.method.<locals>.helper`), scored from nesting
+level 0, not folded into the function that encloses it. This keeps factory and
+registry shapes (FastAPI/Flask app factories, decorator factories, dispatch
+tables of closures) honest: the trivial outer function scores low and each inner
+handler is judged on its own merits. Lambdas, being anonymous, still fold into
+their enclosing function. See
+[docs/nested-function-scoring.md](docs/nested-function-scoring.md) for the
+rationale.
+
+For gates pinned to pre-2.0.0 numbers, `--nested=fold` restores the old model
+(nested defs fold into the enclosing function; a decorator/closure factory is
+scored by its inner function) as a migration aid; the same is available in the
+library as `get_cognitive_complexity(funcdef, fold_nested=True)`. See
+[CHANGELOG.md](CHANGELOG.md).
+
+### Refactor suggestions on a failing gate
+
+When `--max` is exceeded, each offending function is reported on stderr together
+with a few concrete, mechanical refactors and an estimated complexity drop — so
+a human (or an agent) reading the failure knows what to do next:
+
+```text
+cococo: 1 function(s) exceed cognitive complexity 5
+  src/load.py:42 load = 14 (>5)
+    - Extract this block into a helper function (lines 50-61, ~-7 -> 7)
+    - Flatten nested block with a guard clause (lines 45-61, ~-3 -> 11) [--fix]
+```
+
+Suggestions tagged `[--fix]` can be applied automatically. `--fix` rewrites only
+transforms it can prove keep behavior identical (an `if` with no `else` that is
+the last statement of a function or loop body becomes an early
+`return`/`continue` guard, de-indenting its body); anything else is left
+untouched, and comments/formatting in the moved body are preserved.
+
+### Adopting the gate incrementally
+
+No real codebase passes a strict ceiling on day one, so the `--max` gate has two
+ways to grandfather existing offenders rather than be all-or-nothing:
+
+- **Per-function:** put `# cococo: ignore` on a function's `def` line to exclude
+  that one function from the gate (the listing still shows it). cococo warns when
+  an ignore is no longer needed (the function is back under the ceiling), so the
+  directives don't rot silently.
+
+  ```python
+  def legacy_handler(req):  # cococo: ignore
+      ...
+  ```
+
+- **Whole codebase:** `--baseline FILE` (requires `--max`) records every current
+  score the first time it runs, then on later runs fails only on **regressions** —
+  a function rising above its recorded score, or new code over `--max`. This lets
+  a team adopt the gate against a dirty tree in one commit and ratchet down from
+  there. Commit the baseline file; delete it to re-baseline.
+
+### Exit codes
+
+In gate mode (`--max`), the exit code distinguishes the outcomes a CI step cares
+about:
+
+- **0** — all functions within the ceiling (or, without `--max`, a successful
+  listing).
+- **1** — one or more functions exceed the ceiling (offenders printed with
+  suggestions).
+- **2** — the gate could not be trusted: no functions were scanned (a typo'd or
+  empty path), a file was skipped (unreadable, unparseable, or too deeply nested
+  to score), or a `--fix` write failed. A `2` means "fix the setup", not "code is
+  too complex".
+
+### JSON output
+
+`--json` emits the same scores, per-construct breakdowns, and suggestions as a
+single JSON document on stdout (exit code still gates on `--max`), so cococo
+drops into a pipeline:
+
+```bash
+cococo src/ --max 20 --json | jq '.functions[] | select(.over)'
+```
+
+### Library
+
+Score every function under a path (no CLI required):
+
+```python
+from cognitive_complexity.discovery import scored_functions
+
+for f in scored_functions(["src/"]):
+    print(f.qualname, f.score)
+```
+
+`scored_functions` returns a list of `ScoredFunction` named tuples with
+`.score`, `.qualname`, `.path`, `.lineno`, `.funcdef`, `.breakdown`, and
+`.ignored` fields.
+
+The suggestion engine is importable too:
+
+```python
+from cognitive_complexity.api import get_cognitive_complexity_breakdown
+from cognitive_complexity.refactor import suggest_refactors
+
+breakdown = get_cognitive_complexity_breakdown(funcdef)
+for s in suggest_refactors(funcdef, breakdown):
+    print(s.title, s.estimated_reduction)
+```
+
+The low-level AST API:
+
+```python
+>>> import ast
+>>> funcdef = ast.parse("""
+... def f(a):
+...     return a * f(a - 1)  # +1 for recursion
+... """).body[0]
+
+>>> from cognitive_complexity.api import get_cognitive_complexity
+>>> get_cognitive_complexity(funcdef)
+1
+```
+
+## What's different from upstream
+
+This fork diverges from `Melevir/cognitive_complexity` 1.3.0:
+
+- **`async for`** is counted as a loop (upstream scored it 0).
+- **`match`/`case`** is counted as a single branching structure plus a nesting
+  level (upstream did not handle it).
+- **comprehension `if` filters** each count as a decision point.
+- **method recursion** (`self.method(...)` / `cls.method(...)`) is detected, not
+  only bare-name recursion.
+- **named nested functions are scored as their own units** (reported as
+  `outer.<locals>.inner`), not folded into the enclosing function; lambdas still
+  fold. This removes the per-containment nesting surcharge on factory/registry
+  code and the old `is_decorator` special case — both still available via
+  `--nested=fold` for pre-2.0.0 compatibility. See
+  [docs/nested-function-scoring.md](docs/nested-function-scoring.md).
+- a **`cococo` command-line interface**, with **heuristic refactor suggestions**
+  on a failing gate, a **`--json`** report for pipelines, and a **`--fix`** flag
+  that applies provably safe guard-clause rewrites.
+- **Python 3.10+** only; type hints and packaging modernized.
+
+The core control-flow scoring (Campbell's rules) is unchanged — it is the
+empirically validated part of the metric.
+
+## What is cognitive complexity
+
+For a synthesis of the research and industry thinking on what makes code hard to
+understand — and how cognitive complexity fits in — see
+[docs/cognitive-complexity-of-code.md](docs/cognitive-complexity-of-code.md).
+
+Here are some readings about cognitive complexity:
+
+- [Cognitive Complexity, Because Testability != Understandability](https://blog.sonarsource.com/cognitive-complexity-because-testability-understandability);
+- [Cognitive Complexity: A new way of measuring understandability](https://www.sonarsource.com/docs/CognitiveComplexity.pdf),
+  white paper by G. Ann Campbell;
+- [Cognitive Complexity: the New Guide to Refactoring for Maintainable Code](https://www.youtube.com/watch?v=5C6AGTlKSjY);
+- [Cognitive Complexity](https://docs.codeclimate.com/docs/cognitive-complexity)
+  from CodeClimate docs;
+- [Is Your Code Readable By Humans? Cognitive Complexity Tells You](https://www.tomasvotruba.cz/blog/2018/05/21/is-your-code-readable-by-humans-cognitive-complexity-tells-you/).
+
+## Realization details
+
+This is not a precise realization of the original algorithm proposed by
+[G. Ann Campbell](https://github.com/ganncamp), but it gives rather similar
+results. The algorithm gives complexity points for breaking control flow,
+nesting, recursion, and stacked logical operations.
+
+**Known limitation:** only *direct* recursion is detected (a function calling
+itself by name, or via `self`/`cls`). Indirect/mutual recursion — `a()` calls
+`b()` calls `a()` — is not counted, since detecting it needs a whole-program
+call graph rather than the single-function AST this tool works from.
+
+## Development
+
+To develop `cococo`, first set up and activate a virtual environment so the toolchain (`python`, `pytest`, etc.) is available on your PATH:
+
+```bash
+# With standard pip/venv:
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements_dev.txt
+
+# Or with uv:
+uv venv
+uv pip install -r requirements_dev.txt
+```
+
+Once the environment is active (or by prefixing commands with `uv run`, e.g., `uv run just test`), you can use the `just` recipes:
+
+```bash
+just install-hooks  # pre-push runs `just check` (the same gate as CI)
+just check          # format-check + lint + type-check + complexity + tests + readme lint
+just test           # tests with coverage
+just bench          # performance benchmark
+```
+
+`just check` is the single gate — CI runs the exact same recipe.
+
+## License
+
+MIT. See [LICENSE](LICENSE). Original work © Ilya Lebedev and contributors.

codecoco-3.5.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+codecoco-3.5.1.dist-info/licenses/LICENSE,sha256=Lh0Xyp2No-APZG8c0516AgszsFXTAqp1rVcLJGw9gQ8,1100
+cognitive_complexity/__init__.py,sha256=q84OxOhhZQRg9QLCpRzm8ZW7aGHtGUAnNgVlGvZ9vBg,22
+cognitive_complexity/api.py,sha256=a9LDYIoBtHsrcdxIdMgO7bzhMyjppsq9xaRyeQOJ870,7338
+cognitive_complexity/autofix.py,sha256=wlct5ISkUmZ1bMJ9V9IBiftDIPyy1aRuOwDih7NxlTI,9507
+cognitive_complexity/cli.py,sha256=PjeVJvrZisMaXzLAHuM2EdZFbKNiw52J6PhSPHfcYzI,13600
+cognitive_complexity/common_types.py,sha256=TLDrkhrL5WGh0AFzITPUG-YgX5jFPpu8aC3-vb7THcE,1417
+cognitive_complexity/discovery.py,sha256=-BgOQBUt_Nq8F2I-7Z1DSmoWaW0MXPHGfJKG1ppHRYk,7831
+cognitive_complexity/refactor.py,sha256=R0aC4pWKEq8qao42iTfz3b98dtAY5nzsmM8I1DZtRjU,13247
+cognitive_complexity/report.py,sha256=LZq23V5akEsPWbUsY6Dqiy2mqyioRMrzo4d_1Zuxekg,3503
+cognitive_complexity/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cognitive_complexity/utils/ast.py,sha256=HnEMB7YPv-MhyqhZ3kDiYwGnL-IYcI1xm0iiY_yRvLk,6607
+codecoco-3.5.1.dist-info/METADATA,sha256=WjYonysp9JrSFw0XWmcL6WO9Nl9UMwh6WE68HMOcM7k,11032
+codecoco-3.5.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+codecoco-3.5.1.dist-info/entry_points.txt,sha256=enY0Xz9nOD6y2JVVhxC49eU6iotj1IutDk9r8_DTSeY,57
+codecoco-3.5.1.dist-info/top_level.txt,sha256=smc8Vi5x-0c0B0ZelyGn3R_5AKaYfRDgQsjxfWWDuZ0,21
+codecoco-3.5.1.dist-info/RECORD,,

codecoco-3.5.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

codecoco-3.5.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cococo = cognitive_complexity.cli:main

codecoco-3.5.1.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2020 Ilya Lebedev
+Copyright (c) 2026 Mice Pápai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codecoco-3.5.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+cognitive_complexity

cognitive_complexity/__init__.py

@@ -0,0 +1 @@
+__version__ = "3.5.1"

cognitive_complexity/api.py

@@ -0,0 +1,174 @@
+import ast
+from typing import NamedTuple
+
+from cognitive_complexity.common_types import AnyFuncdef, is_funcdef
+from cognitive_complexity.utils.ast import (
+    call_targets_name,
+    decorator_inner,
+    describe_node,
+    has_recursive_calls,
+    process_node_itself,
+)
+
+
+class Contribution(NamedTuple):
+    """One scored construct in a function's cognitive-complexity breakdown.
+
+    ``lineno`` is the source line, ``label`` names the construct (e.g. ``if``,
+    ``for``, ``bool-op``), and ``points`` is what this node alone added to the
+    score, so the sum of every contribution's ``points`` equals the function's
+    total complexity. ``nesting`` is the nesting depth in effect at this node.
+
+    For control-flow breakers (if/for/while/except/match/ternary) the nesting
+    penalty is *part of* ``points`` and ``nesting_counted`` is true, so the
+    structural cost is ``points - nesting``. For ``elif``/``else``, bool-ops and
+    comprehension filters ``nesting`` is only ambient context
+    (``nesting_counted`` false) and all of ``points`` is structural.
+    """
+
+    lineno: int
+    label: str
+    points: int
+    nesting: int
+    nesting_counted: bool
+
+
+def get_cognitive_complexity(funcdef: AnyFuncdef, fold_nested: bool = False) -> int:
+    """Total cognitive complexity: the sum of every scored construct's points."""
+    return sum(c.points for c in get_cognitive_complexity_breakdown(funcdef, fold_nested))
+
+
+def get_cognitive_complexity_breakdown(
+    funcdef: AnyFuncdef, fold_nested: bool = False
+) -> list[Contribution]:
+    """Per-node breakdown of a function's cognitive complexity.
+
+    Records every construct that contributed points and the nesting level in
+    effect at that point. Recursive calls add a trailing synthetic entry. The
+    ``points`` column sums to the total returned by
+    :func:`get_cognitive_complexity`. By default named nested functions are *not*
+    folded in — they are scored as their own units. With ``fold_nested=True``
+    (the pre-2.0.0 model) a nested def folds into its enclosing function as a
+    nesting level, and a decorator/closure factory is scored by its inner
+    function.
+    """
+    inner = decorator_inner(funcdef) if fold_nested else None
+    if inner is not None:
+        return get_cognitive_complexity_breakdown(inner, fold_nested)
+
+    contributions: list[Contribution] = []
+    # Detect direct recursion inline during this single walk instead of a second
+    # ast.walk. In unit mode the walk visits exactly the function's own scope, so
+    # ``rec_name`` is set and a self-call is found here. In fold mode the walk
+    # descends into folded nested defs, whose calls are NOT the outer's recursion,
+    # so inline detection is disabled and the own-scope-only ``has_recursive_calls``
+    # is used instead.
+    rec_name = None if fold_nested else funcdef.name
+    rec_found = [False]
+    for node in funcdef.body:
+        _collect_breakdown(node, 0, funcdef.lineno, contributions, fold_nested, rec_name, rec_found)
+    recursive = has_recursive_calls(funcdef) if fold_nested else rec_found[0]
+    if recursive:
+        contributions.append(Contribution(funcdef.lineno, "recursion", 1, 0, False))
+    return contributions
+
+
+def _mark_recursion(node: ast.AST, rec_name: str | None, rec_found: list[bool]) -> None:
+    """Flag direct recursion when ``node`` is a call to ``rec_name`` (None disables)."""
+    if rec_name is not None and isinstance(node, ast.Call) and call_targets_name(node, rec_name):
+        rec_found[0] = True
+
+
+def _collect_breakdown(
+    node: ast.AST,
+    increment_by: int,
+    parent_lineno: int,
+    out: list[Contribution],
+    fold_nested: bool,
+    rec_name: str | None,
+    rec_found: list[bool],
+) -> None:
+    _mark_recursion(node, rec_name, rec_found)
+    # In unit mode a named nested function is its own reporting unit (discovered
+    # separately by the CLI, scored from nesting 0): it contributes nothing here
+    # and the walk does not descend into it. In fold mode it is left to
+    # process_node_itself, which treats it as a nesting incrementer. Lambdas are
+    # anonymous and always fold.
+    if not fold_nested and is_funcdef(node):
+        return
+
+    # `if`/`elif`/`else` chains need their body and orelse scored at different
+    # nesting levels (the body nests one deeper; a trailing `elif` is a sibling
+    # at the same level), which the uniform child walk below cannot express —
+    # so they get their own handler.
+    if isinstance(node, ast.If):
+        _collect_if_breakdown(
+            node, increment_by, out, fold_nested, rec_name, rec_found, is_elif_arm=False
+        )
+        return
+
+    nesting_before = increment_by
+    increment_by, base_complexity, should_iter_children = process_node_itself(
+        node, increment_by, fold_nested
+    )
+    # Some scored nodes (ast.comprehension) carry no line of their own; fall
+    # back to the nearest ancestor that did.
+    lineno = getattr(node, "lineno", parent_lineno)
+
+    if base_complexity:
+        # Control-flow breakers bumped ``increment_by`` for their own body, so
+        # the level they sit at is the pre-bump value and their nesting penalty
+        # is baked into base_complexity. Bool-ops / comprehension filters don't
+        # bump, so they sit at the ambient level with no nesting penalty.
+        nesting_counted = increment_by != nesting_before
+        node_nesting = increment_by - 1 if nesting_counted else nesting_before
+        out.append(
+            Contribution(
+                lineno, describe_node(node), base_complexity, node_nesting, nesting_counted
+            )
+        )
+
+    if should_iter_children:
+        for child in ast.iter_child_nodes(node):
+            _collect_breakdown(child, increment_by, lineno, out, fold_nested, rec_name, rec_found)
+
+
+def _collect_if_breakdown(
+    node: ast.If,
+    increment_by: int,
+    out: list[Contribution],
+    fold_nested: bool,
+    rec_name: str | None,
+    rec_found: list[bool],
+    *,
+    is_elif_arm: bool,
+) -> None:
+    # B1: +1 for the `if`/`elif` itself. B3: a nesting penalty applies to a
+    # leading `if` (the more deeply nested, the costlier) but not to `elif` or
+    # `else`. B2: each branch body is scored one nesting level deeper.
+    penalty = 0 if is_elif_arm else increment_by
+    out.append(
+        Contribution(
+            node.lineno,
+            describe_node(node, is_elif_arm=is_elif_arm),
+            1 + penalty,
+            increment_by,
+            not is_elif_arm,
+        )
+    )
+    body_level = increment_by + 1
+    _collect_breakdown(node.test, increment_by, node.lineno, out, fold_nested, rec_name, rec_found)
+    for stmt in node.body:
+        _collect_breakdown(stmt, body_level, node.lineno, out, fold_nested, rec_name, rec_found)
+
+    orelse = node.orelse
+    if len(orelse) == 1 and isinstance(orelse[0], ast.If):
+        # `elif`: a sibling at the same nesting level, not a nested `if`.
+        _collect_if_breakdown(
+            orelse[0], increment_by, out, fold_nested, rec_name, rec_found, is_elif_arm=True
+        )
+    elif orelse:
+        # `else`: +1, no nesting penalty; its body is scored one level deeper.
+        out.append(Contribution(orelse[0].lineno, "else", 1, increment_by, False))
+        for stmt in orelse:
+            _collect_breakdown(stmt, body_level, node.lineno, out, fold_nested, rec_name, rec_found)