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)
- 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)
Installation
pip install dynamic-favicon
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()
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.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 emojicreate_icon_favicon(size=32)- Create random geometric icon faviconrotate_emoji_favicon(category=None)- Rotate to random emojirotate_icon_favicon()- Rotate to random iconget_favicon_data_url()- Get base64 data URL of current favicon
FaviconScheduler
Handles automatic favicon rotation on time intervals.
FaviconScheduler(favicon_rotator)
Methods:
schedule_rotation(interval, rotation_type, category=None)- Setup rotation schedule (triggers immediate rotation)start()- Start background schedulerstop()- Stop scheduleris_running()- Check if scheduler is active
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 icons
Emoji Categories:
"nature"- Nature emojis (🌟, 🌙, ☀️, etc.)"objects"- Object emojis (⚽, 🎮, 📱, etc.)"faces"- Face emojis (😊, 😎, 🤔, etc.)"symbols"- Symbol emojis (❤️, ⭐, 💎, etc.)None- Random from all categories
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
Publishing to PyPI
Build the Package
python -m build
Upload to PyPI
pip install twine
twine upload dist/*
Test Installation
pip install dynamic-favicon
License
MIT License - see LICENSE file for details.
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
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
dynamic_favicon-1.0.0.tar.gz
(10.8 kB
view details)
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.0.0.tar.gz.
File metadata
- Download URL: dynamic_favicon-1.0.0.tar.gz
- Upload date:
- Size: 10.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.11.9
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2009274209e5f7d2f07e36d154866536162ff72b397e5d298106ea77daa92cd5
|
|
| MD5 |
ead9f99c41abea3d2ae37660652092d1
|
|
| BLAKE2b-256 |
27b466a56cc0bbeb07b2351f6fba35952dd12885105e645757e731c0072f6426
|
File details
Details for the file dynamic_favicon-1.0.0-py3-none-any.whl.
File metadata
- Download URL: dynamic_favicon-1.0.0-py3-none-any.whl
- Upload date:
- Size: 8.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.11.9
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
5677eefc8cebe6d4d7492c199175850396759f4eab352c2561dd4f735d6a49ff
|
|
| MD5 |
ea5f20d6c22aba37a3d8d45d448e2f09
|
|
| BLAKE2b-256 |
03161d69ab92364765ac706883866b881056e3cd012fd97c5c8c346f9f68556d
|
