Python AST Unused Function Analyzer

A small, readable command-line tool that scans a Python codebase with ast and reports functions that are likely unused.

Why this project exists

Finding dead code manually is slow and error-prone. This tool gives you a fast first pass by:

• Collecting all function and method definitions.
• Collecting called identifiers from function calls.
• Reporting definitions that never appear in calls.

It is intentionally simple so teams can understand and extend it quickly.

Project structure

• main.py: CLI entrypoint and output formatting.
• analyzer.py: AST parsing, data collection, filtering, and core analysis logic.

How it works (high level)

1. Walk the target directory and collect .py files.
2. Parse each file into an AST.
3. Record:
   • function definitions (def and async def)
   • called names from ast.Call
4. Filter out entries that should not be treated as unused (for example descriptor methods and known dynamic-dispatch handlers).
5. Print likely unused functions with file and line number.

Installation

No external dependencies are required. Uses Python standard library only.

Usage

Run on the current directory:

python main.py .

Run on another project:

python main.py C:\path\to\project

Fail CI if unused functions are found:

python main.py . --fail-on-unused

CLI options

• path: project root directory (default: current directory)
• --exclude-dir <name>: exclude a directory name (can be used multiple times)
• --ignore-private: ignore names like _helper
• --include-dunder: include dunder names like __init__
• --fail-on-unused: exit with code 1 if unused functions are found

Example output

Likely unused functions:
- package/module.py:42 cleanup_data
- package/service.py:91 Worker._build_cache

When nothing is found:

No unused functions found.

Notes and limitations

This analyzer uses name-based matching. That keeps it fast, but means:

• Dynamic behavior (reflection, plugin loading, runtime attribute lookups) may hide real usage.
• Same-name functions in different scopes can produce false positives/negatives.
• A reported function is a signal for review, not guaranteed dead code.

Recommended workflow

1. Run analyzer.
2. Review reported functions manually.
3. Remove confirmed dead code.
4. Re-run with --fail-on-unused in CI to keep the codebase clean over time.