fn_registry/python/functions/datascience/compute_text_readability.md

id, name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, example, tested, tests, test_file_path, file_path, params, output

id	name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	example	tested	tests	test_file_path	file_path	params	output
compute_text_readability_py_datascience	compute_text_readability	function	py	datascience	1.0.0	pure	def compute_text_readability(texts, sample_max=500) -> dict	Calcula la legibilidad Flesch Reading Ease de un corpus de texto usando textstat con import perezoso y degradación. Filtra None/no-str/vacíos, muestrea hasta sample_max documentos (los primeros) y agrega los scores Flesch en {mean, p50, min, max}. Si textstat no está instalada devuelve available=False sin lanzar. Estilo dict-no-throw del grupo eda — nunca lanza.	eda datascience text nlp readability flesch textstat pure python				false		math textstat	from datascience.compute_text_readability import compute_text_readability out = compute_text_readability(["The cat sat on the mat. It was warm and sunny."]) # {"available": True, "n_scored": 1, "flesch": {"mean": 109.0, "p50": 109.0, "min": 108.96..., "max": 108.96...}}	true	test_prosa_ingles test_vacio test_degradacion	python/functions/datascience/compute_text_readability_test.py	python/functions/datascience/compute_text_readability.py	name desc texts Lista de str (documentos del corpus). Los elementos None, no-str o vacíos tras strip() se descartan silenciosamente. El orden se respeta: el muestreo toma los primeros documentos válidos. name desc sample_max Número máximo de documentos válidos a puntuar (los primeros). Default 500. Acota el coste en corpus grandes. Valores no convertibles a int caen a 500; negativos se tratan como 0.	Dict con exactamente 3 claves siempre presentes: available (bool: True si textstat se pudo importar), n_scored (int: nº de documentos efectivamente puntuados), flesch (dict con mean, p50, min, max). mean y p50 redondeados a 1 decimal; p50 por nearest-rank sobre los scores ordenados; min/max son los scores extremos sin redondear. Todos los valores de flesch son None cuando n_scored es 0. La función nunca lanza: cualquier excepción global (incluida ImportError de textstat) degrada a available=False, n_scored=0 y flesch todo None.

Ejemplo

from datascience.compute_text_readability import compute_text_readability

textos = [
    "The cat sat on the mat. It was a warm and sunny day in the park.",
    "Reading is a wonderful habit. Books open doors to new worlds and ideas.",
    "He ran quickly to the store to buy some fresh bread and a bottle of milk.",
]

compute_text_readability(textos)
# {
#   "available": True,
#   "n_scored": 3,
#   "flesch": {"mean": 91.4, "p50": 95.4, "min": 70.08..., "max": 108.83...}
# }

# Corpus vacío (textstat presente): available True pero nada que puntuar.
compute_text_readability([])
# {"available": True, "n_scored": 0,
#  "flesch": {"mean": None, "p50": None, "min": None, "max": None}}

Cuando usarla

Úsala en un EDA de texto cuando necesites una métrica única y comparable de lo fácil que es de leer un corpus de documentos (descripciones, reviews, artículos, tickets). Devuelve el resumen Flesch Reading Ease agregado (mean/p50/min/max) listo para un report o un bloque del notebook, sin tener que iterar textstat a mano. Pásale la lista de textos crudos y, si el corpus es grande, limita el coste con sample_max. El estilo dict-no-throw permite incrustarla en pipelines del grupo eda sin envolver en try/except.

Gotchas

• textstat es una dependencia opcional. Si no está instalada (o falla al importar) la función NO lanza: devuelve available=False, n_scored=0 y flesch todo None. Comprueba available antes de interpretar los números.
• Flesch Reading Ease está pensado para prosa en inglés. Aplicado a otros idiomas o a texto no-prosa (código, listas, tablas, cadenas muy cortas) los scores no son interpretables, aunque se calculen sin error.
• Escala Flesch: valores altos = más fácil de leer (≈90–100 muy fácil), valores bajos = más difícil (puede ser negativo en texto muy denso). No se recortan a ningún rango: se reportan tal cual los devuelve textstat.
• available=True con n_scored=0 significa que textstat está presente pero el corpus no aportó documentos puntuables (vacío, solo None/no-str, o todos los docs fallaron al puntuar). Es distinto de available=False.
• Muestreo = los primeros sample_max, no aleatorio. Si el orden del corpus está sesgado, el resumen reflejará ese sesgo.
• mean y p50 redondean a 1 decimal; min/max se devuelven sin redondear (los scores extremos reales).