Dynamic Favicon

A Python module for automatically rotating website favicons based on configurable time intervals. Perfect for adding dynamic visual elements to your web applications without any external API dependencies.

Features

• Time-based favicon rotation (1 hour, 1 day, custom intervals)
• Multiple favicon sources:
  • Unicode emojis
  • Twemoji (Twitter's emoji set)
  • Geometric icons (circles, squares, triangles, diamonds, stars)
  • Curated SVG icon set rendered to crisp PNG/ICO via cairosvg
  • Standalone favicon.svg output for modern browsers, with .ico fallback
• No API keys required - works offline with automatic fallback to geometric icons
• Robust error handling - never breaks your website
• Simple integration - just a few lines of code
• Automatic ICO generation with multiple sizes (16x16, 32x32, 48x48)
• Generates multi-size ICO files (16x16, 32x32, 48x48)

Installation

pip install dynamic-favicon

To enable SVG rasterization (recommended), install with the svg extra. This pulls in cairosvg, which requires the system cairo library.

pip install "dynamic-favicon[svg]"

If cairosvg is unavailable, the rotator still works and falls back to a simple PIL renderer.

Quick Start

Basic Usage

from dynamic_favicon import FaviconRotator, FaviconScheduler

# Initialize the favicon rotator
rotator = FaviconRotator(output_dir="static", favicon_name="favicon.ico")

# Create a favicon from an emoji
rotator.create_emoji_favicon("🚀")

# Or create a random geometric icon
rotator.create_icon_favicon()

# Create a specific SVG icon with color
rotator.create_icon_favicon(name="bolt", color="#f59e0b")

# Write standalone SVG favicon
rotator.create_svg_favicon(name="hexagon", color="#6366f1")

Automated Rotation

from dynamic_favicon import FaviconRotator, FaviconScheduler

# Setup favicon rotation
rotator = FaviconRotator(output_dir="static")
scheduler = FaviconScheduler(rotator)

# Rotate emoji favicons every hour
scheduler.schedule_rotation(interval="1hour", rotation_type="emoji", category="nature")

# Start the scheduler (runs in background)
scheduler.start()

# Your web server code here...
# The favicon will automatically update every hour

# Stop when needed
scheduler.stop()

Flask Integration

from flask import Flask
from dynamic_favicon import FaviconRotator, FaviconScheduler

app = Flask(__name__)

# Setup favicon rotation
rotator = FaviconRotator(output_dir="static")
scheduler = FaviconScheduler(rotator)

# Rotate every 30 minutes with random icons
scheduler.schedule_rotation(interval="30min", rotation_type="icon")
scheduler.start()

@app.route('/')
def home():
    return '<html><head><link rel="icon" href="/static/favicon.svg" type="image/svg+xml"><link rel="alternate icon" href="/static/favicon.ico"></head><body><h1>Dynamic Favicon Demo</h1></body></html>'

if __name__ == '__main__':
    app.run()

API Reference

FaviconRotator

Main class for creating and managing favicons.

FaviconRotator(output_dir="static", favicon_name="favicon.ico")

Methods:

• create_emoji_favicon(emoji, size=32) - Create favicon from emoji (uses Twemoji)
• create_icon_favicon(size=32, name=None, color=None) - Create random geometric/SVG icon favicon, writes both favicon.ico and favicon.svg
• create_svg_favicon(name=None, color=None) - Write only favicon.svg
• create_custom_favicon(image_path, size=32) - Create favicon from any local image (PNG, JPG, etc.)
• rotate_emoji_favicon(category=None) - Rotate to random emoji
• rotate_icon_favicon() - Rotate to random icon
• get_favicon_data_url() - Get base64 data URL of current favicon
• get_current_favicon_path() - Get path to current favicon
• cleanup() - Remove generated favicon files

FaviconScheduler

Handles automatic favicon rotation on time intervals.

FaviconScheduler(favicon_rotator)

Methods:

• schedule_rotation(interval, rotation_type, category=None, run_immediately=True) - Setup rotation schedule (triggers immediate rotation)
• start() / stop() / is_running() - Control scheduler
• clear_schedule() - Remove all scheduled rotations
• get_next_run_time() - Get datetime of next rotation

Intervals:

• "1hour" or "hourly" - Every hour
• "1day" or "daily" - Every day
• "30min" - Every 30 minutes
• "15min" - Every 15 minutes
• "5min" - Every 5 minutes
• "10s", "30s", etc. - Custom seconds (append 's')
• Integer < 60 - Seconds interval
• Integer >= 60 - Minutes interval

Rotation Types:

• "emoji" - Use emoji favicons
• "icon" - Use geometric/SVG icons

Emoji Categories:

• "nature" - Nature emojis (🌟, 🌙, ☀️, etc.)
• "objects" - Object emojis (⚽, 🎮, 📱, etc.)
• "faces" - Face emojis (😊, 😎, 🤔, etc.)
• "symbols" - Symbol emojis (❤️, ⭐, 💎, etc.)
• None - Random from all categories

Bundled SVG icons

Available via dynamic_favicon.SVG_ICONS:

circle, ring, square, triangle, diamond, hexagon, star, heart, bolt, droplet, leaf, moon, spark, compass, shield, cube.

Default palette is exposed as dynamic_favicon.PALETTE.

Advanced Usage

Custom Favicon from Image

rotator = FaviconRotator()
rotator.create_custom_favicon("path/to/your/image.png")

Multiple Scheduled Rotations

scheduler = FaviconScheduler(rotator)

# Nature emojis every hour
scheduler.schedule_rotation("1hour", "emoji", "nature")

# Geometric icons every 30 minutes
scheduler.schedule_rotation("30min", "icon")

scheduler.start()

Get Favicon as Data URL

data_url = rotator.get_favicon_data_url()
# Returns: "data:image/x-icon;base64,AAABAAEAEBAAAAEAIABoBAAAFgAAA..."

# Use in HTML
html = f'<link rel="icon" href="{data_url}">'

Error Handling

The module is designed with robust error handling to ensure your website never breaks:

• All methods return True/False to indicate success
• Failed favicon creation falls back gracefully
• Network errors (for Twemoji) don't crash the application
• Scheduler continues running even if individual rotations fail

Safe error handling example

if not rotator.create_emoji_favicon("🚀"):
    # Fallback to geometric icon
    rotator.create_icon_favicon()

Requirements

• Python 3.8+
• Pillow (PIL) for image processing
• requests for fetching Twemoji images
• schedule for time-based automation
• cairosvg (optional, for SVG rasterization; requires the system cairo library)

Publishing to PyPI

Build the Package

python -m build

Upload to PyPI

pip install twine
twine upload dist/*

Test Installation

pip install dynamic-favicon

Contributing

Fork the repository Create a feature branch Make your changes Add tests Submit a pull request

Support

For issues and questions:

• Create an issue on GitHub
• Check existing documentation
• Review the examples above

Methods:

• schedule_rotation(interval, rotation_type, category=None, run_immediately=True)
• start() / stop() / is_running()
• clear_schedule()
• get_next_run_time()

Intervals: "1hour", "hourly", "1day", "daily", "30min", "10s", integers (seconds when < 60, minutes otherwise).

Rotation types: "emoji", "icon".

Emoji categories: "nature", "objects", "faces", "symbols", or None for any.

Bundled SVG icons

Available via dynamic_favicon.SVG_ICONS:

circle, ring, square, triangle, diamond, hexagon, star, heart, bolt, droplet, leaf, moon, spark, compass, shield, cube.

Default palette is exposed as dynamic_favicon.PALETTE.

Error Handling

Every public method returns a boolean and swallows internal failures so the host application stays up. Network failures fetching Twemoji fall back to a bundled SVG icon. If cairosvg is missing or the C library is not present, a simple PIL renderer is used instead.

External Dependencies

PIL/Pillow: Core image processing library for resizing rasterized SVGs and writing multi-size ICO files.

cairosvg (optional): Rasterizes bundled SVG icons to PNG bytes for high-quality favicon generation. Requires the system cairo library. The module degrades gracefully to a simple PIL fallback when unavailable.

requests: HTTP client for fetching Twemoji images from Twitter's CDN. Includes timeout handling and error management for network requests.

schedule: Task scheduling library that manages time-based favicon rotations. Provides flexible interval configuration and thread-safe execution.

threading: Python standard library used to run the scheduler in background threads, preventing blocking of the main application.

Twemoji CDN: External service providing high-quality emoji images via HTTP requests. System gracefully handles API unavailability by falling back to local geometric icon generation.

[!NOTE] The module is designed to work offline when external services are unavailable, ensuring reliability in various deployment environments.