Skip to content

MIME Detection Implementation Guide

Overview

The SSF Tools project now provides multiple MIME detection implementations with clear, descriptive names to help developers choose the right tool for their needs.

Available Detectors

1. PureMagicMimeDetector

  • What it uses: puremagic Python library
  • Pros: Pure Python, lightweight, no external dependencies
  • Cons: Less accurate than libmagic-based solutions
  • Best for: Simple applications, environments where native libraries are problematic

2. LibmagicMimeDetector

  • What it uses: python-magic library (wraps libmagic)
  • Pros: More accurate, comprehensive file type detection
  • Cons: Requires native libmagic library
  • Best for: Applications requiring high accuracy
  • Windows: Automatically supported via python-magic-bin package
  • What it uses: Automatically chooses the best available detector
  • Logic: Prefers LibmagicMimeDetector → falls back to PureMagicMimeDetector → optional extension fallback
  • Pros: Best accuracy with maximum compatibility
  • Best for: Most applications - provides optimal balance

Configuration Examples

from kp_ssf_tools.core.services.file_processing.mime_detection import (
    AutoMimeDetector,
    LibmagicMimeDetector,
    PureMagicMimeDetector,
)

# Recommended: Automatic selection with fallbacks
detector = AutoMimeDetector()

# Force use of libmagic only (will fail if not available)
detector = LibmagicMimeDetector()

# Force use of puremagic only
detector = PureMagicMimeDetector()

# Auto with extension fallback enabled
detector = AutoMimeDetector(enable_extension_fallback=True)

# Auto but prefer puremagic over libmagic
detector = AutoMimeDetector(prefer_python_magic=False)

Dependency Injection

The project's dependency injection container now uses AutoMimeDetector by default:

# In containers/core.py
mime_detector: providers.Singleton[AutoMimeDetector] = providers.Singleton(
    AutoMimeDetector,
)

This means all services that depend on MIME detection will automatically get the best available implementation.

Windows Support

Windows support is fully automated: - The python-magic-bin package is conditionally installed only on Windows - This provides the necessary libmagic.dll file - No manual configuration required

Performance Characteristics

Detector Accuracy Performance Dependencies Windows Support
PureMagicMimeDetector Good Fast Pure Python ✅
LibmagicMimeDetector Excellent Very Fast Native libmagic ✅ (auto)
AutoMimeDetector Best Available Optimal Adaptive ✅

Recommendation

For most use cases, use AutoMimeDetector. It provides the best balance of accuracy, performance, and compatibility across different environments.