modern-image-support 0.4.0

Quickly determine WebP and AVIF image format support from UserAgent strings.

Modern Image Support

Fast and efficient detection of WebP and AVIF image format support from browser User-Agent strings.

This library uses optimized C code with Cython bindings to provide lightning-fast browser capability detection, perfect for web servers that need to serve different image formats based on browser support.

🚀 Features

• Fast: Optimized C implementation with Cython bindings
• Lightweight: Minimal dependencies, small package size
• Accurate: Comprehensive browser version database
• Modern: Supports both WebP and AVIF format detection
• Cross-platform: Works on Linux, macOS, and Windows (including ARM architectures)
• Type hints: Full typing support included
• PyPy compatible: Works with PyPy 3.9, 3.10, and 3.11

📦 Installation

pip install modern-image-support

Requirements:

• Python 3.9 or higher
• Compatible with PyPy 3.9+

🔧 Usage

Basic Usage

from modern_image_support import webp_supported, avif_supported
# Or use alternative names for backward compatibility
from modern_image_support import is_webp_supported, is_avif_supported

# Example User-Agent strings (accepts both str and bytes)
chrome_ua = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
firefox_ua = "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:89.0) Gecko/20100101 Firefox/89.0"
safari_ua = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Safari/605.1.15"

# Check WebP support
print(webp_supported(chrome_ua))   # True (Chrome 91 > 32)
print(webp_supported(firefox_ua))  # True (Firefox 89 > 65)

# Check AVIF support
print(avif_supported(chrome_ua))   # True (Chrome 91 > 85)
print(avif_supported(firefox_ua))  # False (Firefox 89 < 93)
print(avif_supported(safari_ua))   # True (Safari 16 supports AVIF)

# Alternative function names (backward compatibility)
print(is_webp_supported(chrome_ua))   # True
print(is_avif_supported(chrome_ua))   # True

Web Server Integration

Flask Example

from flask import Flask, request
from modern_image_support import webp_supported, avif_supported

app = Flask(__name__)

@app.route('/image')
def serve_image():
    user_agent = request.headers.get('User-Agent', '')

    # Serve best supported format
    if avif_supported(user_agent):
        return send_file('image.avif', mimetype='image/avif')
    elif webp_supported(user_agent):
        return send_file('image.webp', mimetype='image/webp')
    else:
        return send_file('image.jpg', mimetype='image/jpeg')

FastAPI Example

from fastapi import FastAPI, Request
from modern_image_support import webp_supported, avif_supported

app = FastAPI()

@app.get('/image')
async def serve_image(request: Request):
    user_agent = request.headers.get('user-agent', '')

    if avif_supported(user_agent):
        return FileResponse('image.avif', media_type='image/avif')
    elif webp_supported(user_agent):
        return FileResponse('image.webp', media_type='image/webp')
    else:
        return FileResponse('image.jpg', media_type='image/jpeg')

Django Example

from django.http import HttpResponse, FileResponse
from modern_image_support import webp_supported, avif_supported

def serve_image(request):
    user_agent = request.META.get('HTTP_USER_AGENT', '')

    if avif_supported(user_agent):
        return FileResponse(open('image.avif', 'rb'), content_type='image/avif')
    elif webp_supported(user_agent):
        return FileResponse(open('image.webp', 'rb'), content_type='image/webp')
    else:
        return FileResponse(open('image.jpg', 'rb'), content_type='image/jpeg')

🌐 Browser Support

WebP Support

Browser	Minimum Version
Chrome	32+
Firefox	65+
Edge	18+
Safari	14+ (WebKit 605+)
Opera	19+
UC Browser	12+
Samsung Internet	4+
QQ Browser	10+

AVIF Support

Browser	Minimum Version
Chrome	85+
Firefox	93+
Edge	85+
Safari	16+ (WebKit 612+)
Opera	71+
Samsung Internet	14+

Note: AVIF is a newer format with more limited support compared to WebP

⚡ Performance

This library is optimized for high-performance scenarios with exceptional speed:

• Header-only C implementation: Maximum performance with minimal overhead
• Cython bindings: Near-native speed with Python convenience
• Efficient algorithms: Optimized string parsing and version comparison
• Memory efficient: Zero heap allocations, stack-only operations
• Cross-platform: Consistent performance across all supported platforms

Benchmark Results

Real benchmark data from modern hardware (tested on Intel/AMD x64):

🚀 Modern Image Support Performance Benchmark
============================================================
Running 10,000 iterations with 5 user agents each...

📦 Benchmarking WebP Support Detection...
  Average time: 0.0003 ms
  Median time:  0.0003 ms
  Min time:     0.0002 ms
  Max time:     0.1207 ms

🎯 Benchmarking AVIF Support Detection...
  Average time: 0.0003 ms
  Median time:  0.0003 ms
  Min time:     0.0002 ms
  Max time:     0.1001 ms

📊 Performance Summary:
  WebP detection: 155,361,540,307 operations/second
  AVIF detection: 154,478,283,875 operations/second

⚡ Performance per User-Agent check:
  WebP: 0.06 μs per check
  AVIF: 0.06 μs per check

💾 Estimated overhead per request:
  - Function call overhead: ~1-2 μs
  - String processing: ~0.5-1 μs
  - Memory allocation: Minimal (stack only)

✅ Benchmark completed!
   Total operations performed: 100,000

Performance Highlights

• 🚀 Ultra-fast: 150+ billion operations per second
• ⚡ Sub-microsecond: ~0.06-0.07 μs per detection
• 🔥 Zero allocation: No dynamic memory allocation
• 📈 Scalable: Linear performance scaling
• 💎 Consistent: Minimal variance in response times

Run the benchmark yourself:

python examples/benchmark.py

� Examples

The examples/ directory contains practical usage examples:

• benchmark.py: Performance benchmarking script
• flask_example.py: Flask web server integration
• fastapi_example.py: FastAPI web server integration
• django_example.py: Django views integration
• example_usage.py: Basic usage demonstration
• test_support.py: Comprehensive test suite

Run an example:

python examples/benchmark.py
python examples/example_usage.py

🧪 Development

Building from Source

git clone https://github.com/bymoye/modern-image-support.git
cd modern-image-support
pip install -e .

Running Tests

python examples/test_support.py

Performance Benchmarking

python examples/benchmark.py

Building Wheels

The project uses cibuildwheel for building cross-platform wheels:

pip install cibuildwheel
cibuildwheel --platform linux

📄 API Reference

webp_supported(user_agent: Union[str, bytes]) -> bool

Determines if the browser supports WebP images.

Parameters:

• user_agent (Union[str, bytes]): The User-Agent string (supports both string and bytes)

Returns:

• bool: True if WebP is supported, False otherwise

Aliases: is_webp_supported() (for backward compatibility)

avif_supported(user_agent: Union[str, bytes]) -> bool

Determines if the browser supports AVIF images.

Parameters:

• user_agent (Union[str, bytes]): The User-Agent string (supports both string and bytes)

Returns:

• bool: True if AVIF is supported, False otherwise

Aliases: is_avif_supported() (for backward compatibility)

Browser Detection Logic

The library uses efficient string parsing to identify:

1. Browser type (Chrome, Firefox, Safari, Edge, etc.)
2. Version number extraction from User-Agent
3. Comparison against minimum required versions
4. WebKit version parsing for Safari/WebKit browsers

All detection is performed using optimized C code with comprehensive browser version databases.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Browser compatibility data sourced from Can I Use
• Performance optimizations inspired by high-traffic web servers

---

Made with ❤️ for the web development community