MarkItDown
Arquitectura de MarkItDown: flujos, pistas y selección de conversores
Sigue el código inspeccionado desde la entrada local y las hipótesis StreamInfo hasta las prioridades, la normalización de Markdown y las clases de error.
Qué aprenderás
- Las hipótesis StreamInfo y las prioridades determinan conjuntamente la selección.
- Los flujos sin seek se almacenan completos antes de convertir.
- Formato no compatible e intento fallido son resultados distintos.
Antes de empezar
- Conocimientos básicos de Python y terminal
- Un documento no sensible con contenido verificable
Utiliza la lista del capítulo para explicar y verificar esta parte de una ingesta documental.
Conclusiones clave
- Las hipótesis StreamInfo y las prioridades determinan conjuntamente la selección.
- Los flujos sin seek se almacenan completos antes de convertir.
- Formato no compatible e intento fallido son resultados distintos.
Las entradas convergen en flujos y metadatos
En la revisión inspeccionada, convert_local crea un StreamInfo a partir de la ruta, incluidos nombre y extensión. Abre el archivo en modo binario, obtiene hipótesis sobre la información del flujo y envía ambos a _convert. El tratamiento del formato sucede después de adquirir la entrada; no se limita al argumento del nombre del archivo.
convert_stream recibe un flujo binario. Si no permite seek, la implementación almacena todo su contenido en memoria antes de convertirlo. Esto permite repetir intentos y sondear formatos, pero afecta al dimensionamiento: suministrar una carga como flujo no implica una extracción con memoria acotada.
La selección tiene orden y varias hipótesis
El método central _convert ordena de forma estable los conversores registrados según su prioridad. Recorre las hipótesis StreamInfo, más una hipótesis vacía de respaldo, y pregunta a cada conversor si acepta la entrada. Por eso la extensión es una pista, no la única variable de decisión.
Los conversores específicos suelen utilizar prioridad cero; los genéricos de texto, HTML y ZIP utilizan diez. Los números menores se prueban primero. El registro inserta las entradas nuevas al principio, de modo que, con igual prioridad, el orden estable favorece el registro más reciente. Un complemento debe diseñar cuidadosamente tanto su aceptación como su prioridad.
Éxito y fallo tienen contratos observables
La implementación comprueba mediante una aserción que la aceptación no altere la posición del archivo. Tras intentar una conversión, un bloque finally restaura esa posición. Así, un candidato posterior puede examinar la misma entrada después de un fallo, en vez de recibir un flujo ya consumido.
Antes de devolver un resultado correcto, el núcleo elimina espacios al final de las líneas y reduce secuencias largas de líneas vacías. Si hubo intentos fallidos, lanza FileConversionException con los intentos registrados. Si ningún conversor intentó la entrada, lanza UnsupportedFormatException. Esa distinción permite diagnosticar antes de reintentar indiscriminadamente.
Pasos de implementación
- 1
Lee convert_local y convert_stream en la revisión citada.
- 2
Sigue las llamadas a _get_stream_info_guesses y _convert.
- 3
Examina las prioridades y la frontera accepts/convert.
- 4
Compara las dos clases de error terminal.
Ejemplo para copiar
Archivo local / flujo binario
-> flujo + hipótesis StreamInfo
-> orden estable por prioridad
-> accepts() -> convert() -> restaurar cursor
-> normalizar Markdown -> resultado
-> intentos fallidos o formato no compatiblePreguntas frecuentes
¿La extensión selecciona por sí sola el conversor?
No. La canalización inspeccionada prueba hipótesis StreamInfo con conversores priorizados e incluye una hipótesis de respaldo.
¿accepts puede consumir bytes?
Debe dejar el flujo en su posición original. El núcleo comprueba esa condición antes de continuar.
Fuentes
- Documentación fijadaFuente verificada 2026-09-07
- Despachador centralFuente verificada 2026-09-07
- Conversor de textoFuente verificada 2026-09-07
- Exportaciones públicasFuente verificada 2026-09-07