# Halstead++
A sophisticated Python library for analyzing Halstead complexity metrics of C code through AST parsing, with intelligent operator filtering for more accurate complexity assessment.
Introduction
Halstead++ is a specialized static analysis tool that calculates Halstead complexity metrics for C programming language code. Unlike traditional Halstead metric tools, Halstead++ employs intelligent filtering to exclude common syntactic operators that tend to artificially inflate complexity scores, such as semicolons, parentheses, braces, and commas. This results in more accurate and meaningful complexity measurements that better reflect the actual cognitive complexity of the code.
The tool leverages pycparser to generate Abstract Syntax Trees (AST) from preprocessed C code and performs comprehensive analysis at both file and function levels, providing detailed metrics including program vocabulary, volume, difficulty, effort, and estimated bug counts.
# Installation
### From PyPI
```
pip install halsteadpp
```
### From Source
```
git clone https://github.com/Morgadineo/Halsteadpp
cd halsteadpp
pip install -e .
```
## Dependencies
Python >= 3.8
pycparser >= 2.21
rich >= 13.0 (for formatted output)
# Usage
## Prerequisites: Code Preprocessing
Before using Halstead++, C source files must be preprocessed using the provided Makefile. This step is necessary because Halstead++ uses pycparser which requires preprocessed C code.
Using the Makefile
The repository includes a Makefile for easy preprocessing:
```
# Preprocess all .c files in the Examples directory
make DIR=Examples
# Or use the default directory
make
```
## Basic Usage
```
from halsteadpp import ParsedCode
# Analyze a C file (without .c extension)
parser = ParsedCode("example_file", "path/to/preprocessed/code/")
# Display comprehensive complexity metrics
parser.print_complexities()
# Display function-level analysis
parser.print_functions()
```
## Advanced Usage
```
from halsteadpp import ParsedCode
# Initialize parser for specific file
parser = ParsedCode(
filename="algorithm", # File name without extension
file_dir="src/complex/" # Directory containing preprocessed .i file
)
# Access metrics directly
print(f"Program Volume: {parser.volume}")
print(f"Estimated Bugs: {parser.delivered_bugs}")
print(f"Cyclomatic Complexity: {parser.total_mcc}")
# Access function-specific metrics
for function in parser.functions:
print(f"Function: {function.func_name}")
print(f" - Halstead Effort: {function.effort}")
print(f" - McCabe Complexity: {function.total_mcc}")
```
## Example 1: Simple Analysis
**hello.c inside 'Example/' folder:**
```
#include <stdio.h>
int main(void)
{
printf("Hello, World!\n");
return 0;
}
```
**Pre-compile:**
```
> make
Preprocessing Examples/hello.c...
```
**Basic main.py:**
```
from halsteadpp import ParsedCode
# Analyze a C file
hello_code = ParsedCode('hello', 'Examples/')
# Print table of complexities
hello_code.print_complexities()
```
### Outputs
#### Complexities Table
<img width="300" height="400" alt="Captura de tela de 2025-10-19 15-09-59" src="https://github.com/user-attachments/assets/13ebc988-6d05-431b-8c1b-187ffb7bba88" />
#### Functions complexity
<img width="1600" height="121" alt="Captura de tela de 2025-10-19 15-11-01" src="https://github.com/user-attachments/assets/67d64d06-00fa-4dc2-a50f-7a27729e8747" />
#### Operators
<img width="350" height="130" alt="Captura de tela de 2025-10-19 15-11-45" src="https://github.com/user-attachments/assets/d5a53b61-a27d-427e-86d7-6003b519daea" />
#### Operands
<img width="350" height="130" alt="Captura de tela de 2025-10-19 15-12-13" src="https://github.com/user-attachments/assets/4bdfe440-3ac2-4b48-9105-79f389e9136a" />
# Key Features
## Intelligent Operator Filtering
Halstead++ excludes the following syntactic operators from complexity calculations:
Semicolons (;)
Parentheses (())
Braces ({})
Commas (,)
This filtering provides more realistic complexity metrics by focusing on meaningful operators that contribute to actual cognitive load.
## Comprehensive Metrics
Halstead Metrics: n1, n2, N1, N2, vocabulary, length, volume, difficulty, level, effort, time, bugs
Cyclomatic Complexity: McCabe complexity at function and file levels
Line Metrics: Total lines, effective lines (excluding comments and empty lines)
Function Analysis: Individual metrics for each function
## Rich Visual Output
Formatted tables using the Rich library
Color-coded output for better readability
Detailed operator and operand listings
## AST-Based Analysis
Accurate parsing using Python's AST capabilities
Support for complex C constructs (pointers, structs, function calls, etc.)
Real node detection to filter out compiler-generated code
## Metric Definitions
n1: Number of distinct operators
n2: Number of distinct operands
N1: Total number of operators
N2: Total number of operands
Volume (V): Program size metric: (N1 + N2) × log₂(n1 + n2)
Difficulty (D): Program complexity: (n1 / 2) × (N2 / n2)
Effort (E): Mental effort required: D × V
Bugs (B): Estimated number of delivered bugs: E^(2/3) / 3000
# License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "halsteadpp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "halstead, complexity, metrics, c-code, pycparser, rich",
"author": null,
"author_email": "Arthur Morgado Teixeira <arthurmorgado7751@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/9f/49/2dbfe6801257230daa03f7b5051b9e8ed9a4628578275ca2a66172909e8e/halsteadpp-0.1.1.tar.gz",
"platform": null,
"description": "# Halstead++\n\nA sophisticated Python library for analyzing Halstead complexity metrics of C code through AST parsing, with intelligent operator filtering for more accurate complexity assessment.\nIntroduction\n\nHalstead++ is a specialized static analysis tool that calculates Halstead complexity metrics for C programming language code. Unlike traditional Halstead metric tools, Halstead++ employs intelligent filtering to exclude common syntactic operators that tend to artificially inflate complexity scores, such as semicolons, parentheses, braces, and commas. This results in more accurate and meaningful complexity measurements that better reflect the actual cognitive complexity of the code.\n\nThe tool leverages pycparser to generate Abstract Syntax Trees (AST) from preprocessed C code and performs comprehensive analysis at both file and function levels, providing detailed metrics including program vocabulary, volume, difficulty, effort, and estimated bug counts.\n\n# Installation\n\n### From PyPI\n```\npip install halsteadpp\n```\n\n### From Source\n```\ngit clone https://github.com/Morgadineo/Halsteadpp\ncd halsteadpp\npip install -e .\n```\n\n## Dependencies\nPython >= 3.8\n\npycparser >= 2.21\n\nrich >= 13.0 (for formatted output)\n\n# Usage\n## Prerequisites: Code Preprocessing\n\nBefore using Halstead++, C source files must be preprocessed using the provided Makefile. This step is necessary because Halstead++ uses pycparser which requires preprocessed C code.\nUsing the Makefile\n\nThe repository includes a Makefile for easy preprocessing:\n```\n# Preprocess all .c files in the Examples directory\nmake DIR=Examples\n\n# Or use the default directory\nmake\n```\n\n## Basic Usage\n```\nfrom halsteadpp import ParsedCode\n\n# Analyze a C file (without .c extension)\nparser = ParsedCode(\"example_file\", \"path/to/preprocessed/code/\")\n\n# Display comprehensive complexity metrics\nparser.print_complexities()\n\n# Display function-level analysis\nparser.print_functions()\n```\n\n## Advanced Usage\n```\nfrom halsteadpp import ParsedCode\n\n# Initialize parser for specific file\nparser = ParsedCode(\n filename=\"algorithm\", # File name without extension\n file_dir=\"src/complex/\" # Directory containing preprocessed .i file\n)\n\n# Access metrics directly\nprint(f\"Program Volume: {parser.volume}\")\nprint(f\"Estimated Bugs: {parser.delivered_bugs}\")\nprint(f\"Cyclomatic Complexity: {parser.total_mcc}\")\n\n# Access function-specific metrics\nfor function in parser.functions:\n print(f\"Function: {function.func_name}\")\n print(f\" - Halstead Effort: {function.effort}\")\n print(f\" - McCabe Complexity: {function.total_mcc}\")\n```\n\n## Example 1: Simple Analysis\n\n**hello.c inside 'Example/' folder:**\n```\n#include <stdio.h>\n\nint main(void)\n{\n printf(\"Hello, World!\\n\");\n \n return 0;\n}\n```\n\n**Pre-compile:**\n```\n> make\n\nPreprocessing Examples/hello.c...\n```\n\n**Basic main.py:**\n```\nfrom halsteadpp import ParsedCode\n\n# Analyze a C file\nhello_code = ParsedCode('hello', 'Examples/')\n\n# Print table of complexities\nhello_code.print_complexities()\n```\n\n### Outputs\n#### Complexities Table\n<img width=\"300\" height=\"400\" alt=\"Captura de tela de 2025-10-19 15-09-59\" src=\"https://github.com/user-attachments/assets/13ebc988-6d05-431b-8c1b-187ffb7bba88\" />\n\n\n#### Functions complexity\n<img width=\"1600\" height=\"121\" alt=\"Captura de tela de 2025-10-19 15-11-01\" src=\"https://github.com/user-attachments/assets/67d64d06-00fa-4dc2-a50f-7a27729e8747\" />\n\n#### Operators\n<img width=\"350\" height=\"130\" alt=\"Captura de tela de 2025-10-19 15-11-45\" src=\"https://github.com/user-attachments/assets/d5a53b61-a27d-427e-86d7-6003b519daea\" />\n\n#### Operands\n<img width=\"350\" height=\"130\" alt=\"Captura de tela de 2025-10-19 15-12-13\" src=\"https://github.com/user-attachments/assets/4bdfe440-3ac2-4b48-9105-79f389e9136a\" />\n\n\n# Key Features\n\n## Intelligent Operator Filtering\n\nHalstead++ excludes the following syntactic operators from complexity calculations:\n\nSemicolons (;)\n\nParentheses (())\n\nBraces ({})\n\nCommas (,)\n\nThis filtering provides more realistic complexity metrics by focusing on meaningful operators that contribute to actual cognitive load.\n\n## Comprehensive Metrics\n\nHalstead Metrics: n1, n2, N1, N2, vocabulary, length, volume, difficulty, level, effort, time, bugs\n\nCyclomatic Complexity: McCabe complexity at function and file levels\n\nLine Metrics: Total lines, effective lines (excluding comments and empty lines)\n\nFunction Analysis: Individual metrics for each function\n\n## Rich Visual Output\n\nFormatted tables using the Rich library\n\nColor-coded output for better readability\n\nDetailed operator and operand listings\n\n## AST-Based Analysis\n\nAccurate parsing using Python's AST capabilities\n\nSupport for complex C constructs (pointers, structs, function calls, etc.)\n\nReal node detection to filter out compiler-generated code\n\n## Metric Definitions\nn1: Number of distinct operators\n\nn2: Number of distinct operands\n\nN1: Total number of operators\n\nN2: Total number of operands\n\nVolume (V): Program size metric: (N1 + N2) \u00d7 log\u2082(n1 + n2)\n\nDifficulty (D): Program complexity: (n1 / 2) \u00d7 (N2 / n2)\n\nEffort (E): Mental effort required: D \u00d7 V\n\nBugs (B): Estimated number of delivered bugs: E^(2/3) / 3000\n\n# License\n\nMIT License - see LICENSE file for details.\n\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A Python tool for analyzing C code complexity using Halstead and Cyclomatic metrics.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/Morgadineo/Halsteadpp",
"Issues": "https://github.com/Morgadineo/Halsteadpp/issues"
},
"split_keywords": [
"halstead",
" complexity",
" metrics",
" c-code",
" pycparser",
" rich"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f0152a5f6398d5c277323762192028d08c9780cb377fa9e7b2f57cdef3ceb5aa",
"md5": "46dbdc31454064cc5e041ab13de149bb",
"sha256": "c947f563f6150edeb957eb0b204638cb2ad243998705eafee07baddf18857acc"
},
"downloads": -1,
"filename": "halsteadpp-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "46dbdc31454064cc5e041ab13de149bb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 15121,
"upload_time": "2025-10-24T11:08:40",
"upload_time_iso_8601": "2025-10-24T11:08:40.360777Z",
"url": "https://files.pythonhosted.org/packages/f0/15/2a5f6398d5c277323762192028d08c9780cb377fa9e7b2f57cdef3ceb5aa/halsteadpp-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9f492dbfe6801257230daa03f7b5051b9e8ed9a4628578275ca2a66172909e8e",
"md5": "d940e896ebe757af167670cd6e497cc0",
"sha256": "65cceddb6ebbfaf39602b54a886ab35bb8e74fdb8986d3d4579c68443411c028"
},
"downloads": -1,
"filename": "halsteadpp-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "d940e896ebe757af167670cd6e497cc0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 15617,
"upload_time": "2025-10-24T11:08:41",
"upload_time_iso_8601": "2025-10-24T11:08:41.586094Z",
"url": "https://files.pythonhosted.org/packages/9f/49/2dbfe6801257230daa03f7b5051b9e8ed9a4628578275ca2a66172909e8e/halsteadpp-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-24 11:08:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Morgadineo",
"github_project": "Halsteadpp",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "halsteadpp"
}
JSON
