---
name: detect_headings_by_font
kind: function
lang: py
domain: core
version: "1.0.0"
purity: impure
signature: "def detect_headings_by_font(pdf, min_delta: float = 2.0, max_levels: int = 4) -> list[dict]"
description: "Detecta headings en un PDF analizando la distribucion de font sizes. El font size mas comun es el body; sizes significativamente mayores se clasifican como heading levels. Filtra headers/footers repetitivos."
tags: [pdf, headings, font, detection, parsing, pdfplumber]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [pdfplumber, collections]
params:
  - name: pdf
    desc: "objeto pdfplumber.PDF abierto con which_pages="
  - name: min_delta
    desc: "diferencia minima de font size para clasificar como heading"
  - name: max_levels
    desc: "numero maximo de heading levels a detectar"
output: "lista de dicts con campos page_num, level, title para cada heading detectado"
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/core/detect_headings_by_font.py"
---

## Ejemplo

```python
import pdfplumber
from detect_headings_by_font import detect_headings_by_font

with pdfplumber.open("document.pdf") as pdf:
    headings = detect_headings_by_font(pdf, min_delta=2.0, max_levels=4)
    for h in headings:
        print(f"Page {h['page_num']}: {'#' * h['level']} {h['title']}")
```

## Notas

Samplea cada 5ta pagina para construir el Counter de font sizes (optimizacion de rendimiento). El body_size es el font size mas frecuente. Los heading sizes deben ser >= body_size + min_delta Y tener frecuencia < 50% del body. Se limita a max_levels heading sizes ordenados desc (el mas grande = nivel 1). Titulos que aparecen en >30% de paginas son considerados headers/footers y se eliminan. Impure porque accede al estado interno de un objeto PDF ya abierto.
