mimetypes.guess_file_type es una función del módulo mimetypes que estima el tipo MIME y la codificación de un archivo a partir de una ruta, una URL o un valor similar a un nombre de archivo. Es útil cuando una aplicación necesita decidir cómo servir, validar, almacenar o procesar un recurso sin leer todo su contenido.
En esta guía aprenderás a interpretar el resultado, crear fallbacks seguros e integrar la función en APIs, cargas de archivos, automatizaciones y pipelines de datos.
Qué es un tipo MIME
Un tipo MIME describe la naturaleza de un recurso. Algunos ejemplos son text/plain, image/png, application/pdf y application/json. Navegadores, servidores HTTP, clientes de correo y bibliotecas usan esta información para elegir cómo tratar el contenido.
El módulo mimetypes no inspecciona los bytes. Consulta asociaciones conocidas entre extensiones y tipos, por lo que el resultado es rápido, pero debe considerarse una estimación basada en el nombre.
Ejemplo básico
import mimetypes
tipo, codificacion = mimetypes.guess_file_type("informe.pdf")
print(tipo)
print(codificacion)
Para un PDF, el tipo suele ser application/pdf. La codificación normalmente es None.
Cómo interpretar la tupla
La función devuelve dos valores. El primero es el tipo MIME o None cuando la extensión no se reconoce. El segundo puede ser una codificación como gzip, habitual en nombres como datos.csv.gz.
tipo, codificacion = mimetypes.guess_file_type("datos.csv.gz")
print(tipo)
print(codificacion)
La codificación no es el charset del texto. No indica UTF-8. Representa una capa externa, normalmente compresión.
Rutas y URLs
La función acepta rutas y valores similares, lo que hace más clara la intención del código.
from pathlib import Path
import mimetypes
archivo = Path("uploads") / "foto.webp"
tipo, _ = mimetypes.guess_file_type(archivo)
También puede trabajar con URLs cuando la parte final contiene una extensión útil. Las URLs firmadas y los parámetros de consulta requieren normalización.
Normalizar URLs
from urllib.parse import urlparse
import mimetypes
url = "https://ejemplo.com/manual.pdf?token=abc"
ruta = urlparse(url).path
tipo, codificacion = mimetypes.guess_file_type(ruta)
Extraer el componente path evita que los parámetros interfieran. Algunos endpoints no muestran la extensión real, por lo que será necesario consultar cabeceras HTTP o inspeccionar el contenido.
Fallback para extensiones desconocidas
No asumas que siempre recibirás una cadena.
tipo, codificacion = mimetypes.guess_file_type("archivo.custom")
tipo = tipo or "application/octet-stream"
application/octet-stream es un valor genérico y conservador para datos binarios.
Uso en uploads
La función puede ayudar a aplicar un filtro inicial, pero no debe ser la única defensa. Un atacante puede renombrar un ejecutable con extensión .jpg.
permitidos = {"image/png", "image/jpeg", "image/webp"}
tipo, _ = mimetypes.guess_file_type(nombre)
if tipo not in permitidos:
raise ValueError("Tipo no permitido")
Combina este filtro con límites de tamaño, validación de firmas binarias, nombres generados por el servidor y almacenamiento no ejecutable.
APIs y respuestas HTTP
El resultado puede alimentar la cabecera Content-Type.
from pathlib import Path
import mimetypes
ruta = Path("descargas/manual.pdf")
tipo, _ = mimetypes.guess_file_type(ruta)
headers = {"Content-Type": tipo or "application/octet-stream"}
Esto funciona bien con archivos creados y nombrados por tu propia aplicación. Los archivos externos necesitan validación adicional.
Archivos comprimidos
En nombres como backup.tar.gz, el primer valor puede describir el archivo TAR y el segundo indicar gzip.
tipo, codificacion = mimetypes.guess_file_type("backup.tar.gz")
No confundas el tipo principal con la codificación. Son capas distintas.
Parámetro strict
El parámetro strict controla si se usan solo tipos oficialmente registrados o también asociaciones adicionales.
tipo, _ = mimetypes.guess_file_type("imagen.xbm", strict=False)
El modo estricto favorece interoperabilidad. El modo flexible puede ser útil en herramientas locales.
Tipos personalizados
Los proyectos internos pueden registrar extensiones propias.
import mimetypes
mimetypes.add_type("application/vnd.ejemplo", ".ejemplo")
tipo, _ = mimetypes.guess_file_type("documento.ejemplo")
Haz estos registros durante la inicialización y en un único módulo para mantener un comportamiento predecible.
Extensión frente al contenido real
El nombre es solo una convención. Un archivo llamado foto.png puede contener HTML o datos ejecutables. Los sistemas sensibles deben validar magic bytes, usar parsers confiables o procesar el archivo en un entorno aislado.
Para imágenes, Pillow puede verificar el formato. Para documentos, utiliza analizadores específicos. Las herramientas basadas en firmas son más fiables que la extensión.
Rendimiento
Como no lee el archivo, la función es rápida. En pipelines enormes, un caché puede evitar trabajo repetido.
from functools import lru_cache
import mimetypes
@lru_cache(maxsize=4096)
def detectar(nombre: str):
return mimetypes.guess_file_type(nombre)
El caché ayuda cuando se repiten patrones y extensiones.
Pruebas unitarias
Prueba extensiones conocidas, desconocidas, comprimidas y personalizadas.
def test_pdf():
tipo, codificacion = detectar("manual.pdf")
assert tipo == "application/pdf"
assert codificacion is None
No dependas de asociaciones exclusivas de un sistema operativo si el proyecto debe ser portable.
Integración con pathlib
Una función envolvente puede centralizar el fallback.
from dataclasses import dataclass
from pathlib import Path
import mimetypes
@dataclass(frozen=True)
class TipoArchivo:
mime: str
encoding: str | None
def identificar(ruta: Path) -> TipoArchivo:
mime, encoding = mimetypes.guess_file_type(ruta)
return TipoArchivo(mime or "application/octet-stream", encoding)
Este diseño evita duplicar reglas en toda la aplicación.
Guías relacionadas
Consulta también las guías de Academify sobre pathlib.Path.walk, tempfile, zipfile y archivos grandes en Python.
Referencias oficiales
Revisa la documentación oficial de mimetypes y la referencia de tipos MIME de MDN.
Errores comunes
Los errores frecuentes son confiar en la extensión como prueba, ignorar None, confundir encoding con charset, aceptar uploads solo por el nombre, no normalizar URLs y asumir mapeos idénticos en todos los sistemas.
Buenas prácticas
Usa guess_file_type para clasificación inicial, elige un fallback conservador, normaliza URLs, centraliza los tipos propios, prueba en los entornos soportados e inspecciona el contenido real cuando la seguridad dependa del resultado.
Conclusión
mimetypes.guess_file_type es una forma simple y eficiente de estimar tipos MIME en rutas y URLs. Es útil en respuestas HTTP, organización de archivos y automatización, siempre que recuerdes que el resultado proviene del nombre y no de los bytes. Para contenido no confiable, combínala con validaciones adicionales.
