Xenon Python Code Metrics Tool

0.9.3 · active · verified Tue Apr 14

Xenon is a Python code complexity tool that analyzes source code for various metrics like cyclomatic complexity, raw LOC, and maintainability index, leveraging the `radon` library. It's designed for integration into CI pipelines to monitor code quality against defined thresholds. The current version is 0.9.3, with updates occurring periodically, often tied to `radon` releases.

Warnings

breaking Version 0.9.0 introduced significant breaking changes in configuration handling, default file filtering (now only Python files by default), and the JSON report output format.
Fix: Review release notes for 0.9.0 regarding configuration (`pyproject.toml`, `.xenon.ini`), file inclusions, and adapt any automated parsing of JSON reports. Explicitly specify `--include` or `--pattern` for non-Python files if needed.
gotcha Xenon is primarily a command-line tool. Its Python 'library' usage involves calling `xenon.main.main(args)` directly, which mimics `sys.argv` and can call `sys.exit()` (raising `SystemExit`). It does not provide a high-level, object-oriented API for analysis results.
Fix: Wrap calls to `xenon.main.main` in a `try...except SystemExit` block to handle its exit behavior. Process results by capturing `stdout` or parsing JSON reports saved to a file, rather than expecting direct return values.
gotcha Xenon's default behavior changed in 0.9.0 to only analyze Python files (`*.py`). If you need to analyze other file types (e.g., Jupyter notebooks with `--max-nb-complexity`), you must explicitly specify `--include` or `--pattern`.
Fix: Add `--include` or `--pattern` arguments to your CLI command or configuration to match the desired files, for example, `--pattern '*.py,*.ipynb'`.

Install

pip install xenon Install Xenon

Imports

main
```
from xenon.main import main
```
Xenon is primarily a CLI tool. Its library usage involves calling `xenon.main.main` with an argument list similar to `sys.argv`. It does not expose a high-level Python object API for analysis, so attempting to `import xenon` and call methods directly will not work as expected.

Quickstart

Demonstrates how to run `xenon` programmatically by calling its `main` function, simulating a command-line invocation. This allows capturing its output and exit code for integration into Python scripts or build systems. Note that `main` can raise `SystemExit`, which should be handled.

import sys
from io import StringIO
from contextlib import redirect_stdout
from xenon.main import main

# Simulate running xenon from the command line
# This will write output to stdout, so we capture it.
args = [
    '--max-complexity', '10', 
    '--max-blocks', '50', 
    '.'
]

# Capture stdout to see the results
old_stdout = sys.stdout
redirected_output = StringIO()
sys.stdout = redirected_output

try:
    # main() returns 0 for success, non-zero for failure (thresholds exceeded)
    result_code = main(args)
    output = redirected_output.getvalue()
    print("Xenon Analysis Output:")
    print(output)
    if result_code != 0:
        print(f"Xenon found issues (exit code: {result_code}).")
    else:
        print("Xenon analysis passed all thresholds.")
except SystemExit as e:
    # main() uses sys.exit(), which raises SystemExit in Python.
    # The exit code is in e.code
    output = redirected_output.getvalue()
    print("Xenon Analysis Output:")
    print(output)
    print(f"Xenon exited with code: {e.code}")
finally:
    sys.stdout = old_stdout # Restore stdout

# For a real-world scenario, you might run it on a specific file/directory.
# Example: args = ['--max-complexity', '10', 'your_project_dir/your_file.py']

view raw JSON →