A Python module for automatically rotating website favicons based on time intervals
Project description
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.svgoutput for modern browsers, with.icofallback
- 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 bothfavicon.icoandfavicon.svgcreate_svg_favicon(name=None, color=None)- Write onlyfavicon.svgcreate_custom_favicon(image_path, size=32)- Create favicon from any local image (PNG, JPG, etc.)rotate_emoji_favicon(category=None)- Rotate to random emojirotate_icon_favicon()- Rotate to random iconget_favicon_data_url()- Get base64 data URL of current faviconget_current_favicon_path()- Get path to current faviconcleanup()- 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 schedulerclear_schedule()- Remove all scheduled rotationsget_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/Falseto 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
cairolibrary)
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.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file dynamic_favicon-1.1.0.tar.gz.
File metadata
- Download URL: dynamic_favicon-1.1.0.tar.gz
- Upload date:
- Size: 13.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.12.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2c99830f7ee63a3cfda2845bf1e93d7e6128ba9f54024143bc021ccb864a2440
|
|
| MD5 |
f2646129c95579a603ccc6fdd85dc105
|
|
| BLAKE2b-256 |
d35b49881e5b5fb9ea0c38ab3525bb3430e34fb4dd3f02dbdd4d722713251a41
|
File details
Details for the file dynamic_favicon-1.1.0-py3-none-any.whl.
File metadata
- Download URL: dynamic_favicon-1.1.0-py3-none-any.whl
- Upload date:
- Size: 11.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.12.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
eeee72d4510b88c7321b147a8d72aebc1cd8d48a1c7bf1921d364e91d3d8fb53
|
|
| MD5 |
7c06e60f4cad7e88a9d43b8976d811fc
|
|
| BLAKE2b-256 |
30ddc96d54dce29879e66689b646e2da470eaac9a32ef00a643b13be0c8364e8
|
