Metadata-Version: 2.4
Name: dynamic-favicon
Version: 1.1.0
Summary: A Python module for automatically rotating website favicons based on time intervals
Author-email: Dynamic Favicon <contact@dynamicfavicon.com>
License: MIT
Project-URL: Homepage, https://github.com/dynamic-favicon/dynamic-favicon
Project-URL: Bug Reports, https://github.com/dynamic-favicon/dynamic-favicon/issues
Project-URL: Source, https://github.com/dynamic-favicon/dynamic-favicon
Project-URL: Documentation, https://github.com/dynamic-favicon/dynamic-favicon#readme
Keywords: favicon,dynamic,rotation,website,emoji,icons
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: schedule>=1.2.0
Requires-Dist: Pillow>=9.1.0
Requires-Dist: requests>=2.25.0
Provides-Extra: svg
Requires-Dist: cairosvg>=2.7.0; extra == "svg"
Provides-Extra: dev
Requires-Dist: cairosvg>=2.7.0; extra == "dev"
Requires-Dist: flask>=2.0.0; extra == "dev"
Requires-Dist: build>=0.8.0; extra == "dev"
Requires-Dist: setuptools>=61.0; extra == "dev"
Requires-Dist: wheel>=0.37.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install dynamic-favicon
```

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

```bash
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

```python
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

```python
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

```python
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.

```python
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.

```python
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

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

### Multiple Scheduled Rotations

```python
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

```python
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

```python
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

```bash
python -m build
```

### Upload to PyPI

```bash
pip install twine
twine upload dist/*
```

### Test Installation

```bash
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.
