{"id":16338172,"url":"https://github.com/rohaquinlop/complexipy","last_synced_at":"2025-05-16T04:02:38.397Z","repository":{"id":221203482,"uuid":"746140707","full_name":"rohaquinlop/complexipy","owner":"rohaquinlop","description":"An extremely fast Python library to calculate the cognitive complexity of Python files, written in Rust.","archived":false,"fork":false,"pushed_at":"2025-04-24T15:27:48.000Z","size":474,"stargazers_count":165,"open_issues_count":3,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-11T07:56:22.404Z","etag":null,"topics":["clean-code","cognitve-complexity","linter","linters","maintainability","metrics","python","rust","sonar-scan","understandability"],"latest_commit_sha":null,"homepage":"https://rohaquinlop.github.io/complexipy/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rohaquinlop.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"rohaquinlop"}},"created_at":"2024-01-21T07:11:09.000Z","updated_at":"2025-05-10T21:02:22.000Z","dependencies_parsed_at":"2024-04-13T19:47:45.628Z","dependency_job_id":"58bbc67f-6888-4b44-912e-4dcf6375d0a4","html_url":"https://github.com/rohaquinlop/complexipy","commit_stats":null,"previous_names":["rohaquinlop/complexipy"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rohaquinlop%2Fcomplexipy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rohaquinlop%2Fcomplexipy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rohaquinlop%2Fcomplexipy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rohaquinlop%2Fcomplexipy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rohaquinlop","download_url":"https://codeload.github.com/rohaquinlop/complexipy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254464891,"owners_count":22075570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clean-code","cognitve-complexity","linter","linters","maintainability","metrics","python","rust","sonar-scan","understandability"],"created_at":"2024-10-10T23:49:50.604Z","updated_at":"2025-05-16T04:02:38.390Z","avatar_url":"https://github.com/rohaquinlop.png","language":"Rust","funding_links":["https://github.com/sponsors/rohaquinlop"],"categories":["Python","Static Checks","📦 Additional Python Libraries"],"sub_categories":["Code Quality \u0026 Development"],"readme":"# complexipy\n\n\u003ca href=\"https://sonarcloud.io/summary/new_code?id=rohaquinlop_complexipy\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://sonarcloud.io/api/project_badges/measure?project=rohaquinlop_complexipy\u0026metric=alert_status\" alt=\"Quality Gate\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/complexipy\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/pypi/v/complexipy?color=%2334D058\u0026label=pypi%20package\" alt=\"Package version\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://pepy.tech/project/complexipy\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://static.pepy.tech/badge/complexipy\" alt=\"Downloads\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://github.com/rohaquinlop/complexipy/blob/main/LICENSE\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/rohaquinlop/complexipy\" alt=\"License\"\u003e\n\u003c/a\u003e\n\nAn extremely fast Python library to calculate the cognitive complexity of Python files, written in Rust.\n\n## Table of Contents\n- [complexipy](#complexipy)\n  - [Table of Contents](#table-of-contents)\n  - [What is Cognitive Complexity?](#what-is-cognitive-complexity)\n  - [Documentation](#documentation)\n  - [Requirements](#requirements)\n  - [Installation](#installation)\n  - [Usage](#usage)\n    - [Command Line Interface](#command-line-interface)\n    - [Options](#options)\n  - [Use the library from python code](#use-the-library-from-python-code)\n    - [Example](#example)\n  - [Example](#example-1)\n    - [Analyzing a file](#analyzing-a-file)\n      - [From the CLI](#from-the-cli)\n      - [Using the library](#using-the-library)\n      - [Understanding the Analysis](#understanding-the-analysis)\n    - [Output to a CSV file](#output-to-a-csv-file)\n    - [Analyzing a directory](#analyzing-a-directory)\n    - [Analyzing a git repository](#analyzing-a-git-repository)\n  - [Contributors](#contributors)\n  - [License](#license)\n  - [Acknowledgments](#acknowledgments)\n  - [References](#references)\n\n## What is Cognitive Complexity?\n\nCognitive Complexity breaks from using mathematical models to assess software\nmaintainability by combining Cyclomatic Complexity precedents with human\nassessment. It yields method complexity scores that align well with how\ndevelopers perceive maintainability.\n\nUnlike traditional complexity metrics, cognitive complexity focuses on how difficult code is to *understand* by humans, making it more relevant for maintaining and reviewing code.\n\n**Key benefits:**\n- Identifies hard-to-understand code sections\n- Helps improve code quality and maintainability\n- Provides a more intuitive metric than traditional complexity measures\n\n📄 Read the white paper: [Cognitive Complexity, a new way of measuring understandability](https://www.sonarsource.com/resources/cognitive-complexity/)\n\n## Documentation\n\n**Documentation**: \u003ca href=\"https://rohaquinlop.github.io/complexipy/\" target=\"_blank\"\u003ehttps://rohaquinlop.github.io/complexipy/\u003c/a\u003e\n\n**Source Code**: \u003ca href=\"https://github.com/rohaquinlop/complexipy\" target=\"_blank\"\u003ehttps://github.com/rohaquinlop/complexipy\u003c/a\u003e\n\n**PyPI**: \u003ca href=\"https://pypi.org/project/complexipy/\" target=\"_blank\"\u003ehttps://pypi.org/project/complexipy/\u003c/a\u003e\n\n## Requirements\n\n- Python \u003e= 3.8\n- Git (optional) - required only if you want to analyze a git repository\n\n## Installation\n\n```bash\npip install complexipy\n```\n\n## Usage\n\n### Command Line Interface\n\n```shell\n# Analyze the current directory and subdirectories\ncomplexipy .\n\n# Analyze a specific directory and subdirectories\ncomplexipy path/to/directory\n\n# Analyze a git repository\ncomplexipy git_repository_url\n\n# Analyze a specific file\ncomplexipy path/to/file.py\n\n# Set maximum cognitive complexity (default: 15)\ncomplexipy path/to/file.py -c 20\n\n# Disable exit with error (by setting max complexity to 0)\ncomplexipy path/to/directory -c 0\n\n# Output results to a CSV file\ncomplexipy path/to/directory -o\n\n# Show only files exceeding maximum complexity\ncomplexipy path/to/directory -d low\n\n# Disable console output\ncomplexipy path/to/directory -q\n\n# Sort results in descending order\ncomplexipy path/to/directory -s desc\n```\n\n### Options\n\n- `-c` or `--max-complexity`: Set the maximum cognitive complexity (default: 15).\n  If the cognitive complexity of a file exceeds this value, the program will exit with error code 1.\n  Set to 0 to disable this behavior.\n\n- `-o` or `--output`: Output results to a CSV file named `complexipy.csv` in the current directory.\n\n- `-d` or `--details`: Set detail level:\n  - `normal` (default): Show all files and functions\n  - `low`: Show only files/functions exceeding the maximum complexity\n\n- `-q` or `--quiet`: Disable console output.\n\n- `-s` or `--sort`: Set sort order:\n  - `asc` (default): Sort by complexity (ascending)\n  - `desc`: Sort by complexity (descending)\n  - `name`: Sort by name (ascending)\n\n## Use the library from python code\n\nThe library provides two main functions:\n\n- `complexipy.file_complexity`: Analyze a Python file at a specified path\n- `complexipy.code_complexity`: Analyze a string containing Python code\n\n### Example\n\n```python\n# Analyze a file\nfrom complexipy import file_complexity\nresult = file_complexity(\"path/to/your/file.py\")\nprint(f\"File complexity: {result.complexity}\")\n\n# Analyze a code snippet\nfrom complexipy import code_complexity\ncode = \"\"\"\ndef example_function(x):\n    if x \u003e 0:\n        for i in range(x):\n            print(i)\n\"\"\"\nresult = code_complexity(code)\nprint(f\"Code complexity: {result.complexity}\")\n```\n\n## Example\n\n### Analyzing a file\n\nGiven the following Python file:\n\n```python\ndef a_decorator(a, b):\n    def inner(func):\n        return func\n    return inner\n\ndef b_decorator(a, b):\n    def inner(func):\n        if func:\n            return None\n        return func\n    return inner\n```\n\n#### From the CLI\n\nRunning `complexipy path/to/file.py` produces:\n\n```txt\n───────────────────────────── 🐙 complexipy 2.1.1 ──────────────────────────────\n                                    Summary\n      ┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━┓\n      ┃ Path              ┃ File              ┃ Function    ┃ Complexity ┃\n      ┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━┩\n      │ test_decorator.py │ test_decorator.py │ a_decorator │ 0          │\n      ├───────────────────┼───────────────────┼─────────────┼────────────┤\n      │ test_decorator.py │ test_decorator.py │ b_decorator │ 1          │\n      └───────────────────┴───────────────────┴─────────────┴────────────┘\n🧠 Total Cognitive Complexity: 1\n1 file analyzed in 0.0092 seconds\n────────────────────────── 🎉 Analysis completed! 🎉 ───────────────────────────\n```\n\n#### Using the library\n\nWith `file_complexity`:\n```python\n\u003e\u003e\u003e from complexipy import file_complexity\n\u003e\u003e\u003e fc = file_complexity(\"path/to/file.py\")\n\u003e\u003e\u003e fc.complexity\n1\n```\n\nWith `code_complexity`:\n```python\n\u003e\u003e\u003e from complexipy import code_complexity\n\u003e\u003e\u003e snippet = \"\"\"for x in range(0, 10):\n    print(x)\n\"\"\"\n\u003e\u003e\u003e cc = code_complexity(snippet)\n\u003e\u003e\u003e cc.complexity\n1\n```\n\n#### Understanding the Analysis\n\n```python\ndef a_decorator(a, b): # 0\n    def inner(func): # 0\n        return func # 0\n    return inner # 0\n\ndef b_decorator(a, b): # 0\n    def inner(func): # 0\n        if func: # 1 (nested = 0), total 1\n            return None # 0\n        return func # 0\n    return inner # 0\n```\n\nThe cognitive complexity of the file is 1, with function `b_decorator` having a complexity of 1 due to the if statement.\n\n### Output to a CSV file\n\nUsing the `-o` option outputs results to `complexipy.csv` in the current directory:\n\n```bash\ncomplexipy path/to/file.py -o\n```\n\nCSV content:\n```csv\nPath,File Name,Function Name,Cognitive Complexity\ntest_decorator.py,test_decorator.py,a_decorator,0\ntest_decorator.py,test_decorator.py,b_decorator,1\n```\n\n### Analyzing a directory\n\nAnalyze all Python files in the current directory and subdirectories:\n\n```bash\ncomplexipy .\n```\n\n### Analyzing a git repository\n\nAnalyze a remote repository:\n\n```bash\n# Analyze repository\ncomplexipy https://github.com/rohaquinlop/complexipy\n\n# With CSV output\ncomplexipy https://github.com/rohaquinlop/complexipy -o\n```\n\n## Contributors\n\n\u003cp align=\"center\"\u003e\n    \u003ca href = \"https://github.com/rohaquinlop/complexipy/graphs/contributors\"\u003e\n    \u003cimg src = \"https://contrib.rocks/image?repo=rohaquinlop/complexipy\"/\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\nMade with [contributors-img](https://contrib.rocks)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](https://github.com/rohaquinlop/complexipy/blob/main/LICENSE) file for details.\n\n## Acknowledgments\n\n- Thanks to G. Ann Campbell for publishing the paper \"Cognitive Complexity a new way to measure understandability\".\n- This project is inspired by the Sonar way to calculate cognitive complexity.\n\n## References\n\n- [Cognitive Complexity](https://www.sonarsource.com/resources/cognitive-complexity/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frohaquinlop%2Fcomplexipy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frohaquinlop%2Fcomplexipy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frohaquinlop%2Fcomplexipy/lists"}