cf-extractor 0.2.0

Python semantic data extractor for Context-Footprint (AST + pluggable resolvers)

cf-extractor

Python semantic data extractor for Context-Footprint. Outputs SemanticData JSON using Python AST plus a pluggable resolver backend. ty is the default backend; jedi remains available as a baseline resolver, and other LSP-backed backends can be plugged in for comparison.

As a dependency

This package is a dependency of cftool. When you install cftool via uv or pip, cf-extractor is installed automatically:

uv tool install cftool   # includes cf-extractor

Standalone usage

You can also install and use cf-extractor directly:

# From PyPI (when published)
pip install cf-extractor

# From Git
uv pip install "cf-extractor @ git+https://github.com/context-footprint/context-footprint#subdirectory=extractors/python"

# Development
cd extractors/python
uv sync

Run the extractor:

cf-extract /path/to/python/project
# or
uv run cf-extract /path/to/python/project
# or
python -m cf_extractor.main /path/to/project

Without arguments, uses the current directory (.). Output is written to stdout (valid JSON for cftool).

Resolver backend options:

cf-extract /path/to/python/project
cf-extract /path/to/python/project --resolver-backend jedi
cf-extract /path/to/python/project --resolver-backend ty --ty-path /path/to/ty
cf-extract /path/to/python/project --resolver-backend pyrefly --pyrefly-path /path/to/pyrefly

Optional metrics output for benchmarking:

cf-extract /path/to/python/project --metrics-out metrics.json
cf-extract-benchmark \
  --dataset small=tests/fixtures \
  --dataset medium=/path/to/project \
  --dataset large=/path/to/project \
  --report-out benchmark.md

Backend diffing:

cf-extract-diff /path/to/python/project --left jedi --right ty --report-out diff.md
cf-extract-diff /path/to/python/project --left ty --right pyrefly --report-out diff.md

Tests

uv run pytest tests/ -v

Requirements

• Python >= 3.9
• pydantic, ty (installed automatically)
• jedi is only needed for baseline comparison with --resolver-backend jedi
• pyrefly is only needed for comparison with --resolver-backend pyrefly