app.py Reference Documentation
This document provides a comprehensive reference for all methods, variables, and configurations in app.py (540 lines). It is designed for agent systems to understand and interact with the e621tagger Flask application.
File Overview
| Attribute |
Value |
| Location |
app.py |
| Lines |
540 |
| Framework |
Flask |
| Purpose |
Web application for e621 image tagging |
| Dependencies |
flask, flask-limiter, torch, PIL, ua-parser |
File Structure Flow
1. Global Constants
Tag Categories
| Usage |
Map tag category string keys to e621 category display names |
Note: The Label class in hydra/label.py uses integer category IDs (0-8, 100-111). The TAG_CATEGORIES dict here maps string keys for the 9 base categories. Subcategories (100-111) are handled via SUBCATEGORY_DISPLAY_NAMES.
Subcategory Display Names
| Usage |
Map internal subcategory codes to display names for the API response and UI |
Application Configuration
| Variable |
Default |
Description |
APP_VERSION |
test |
Version string (set by Docker build) |
LOG_LEVEL |
DEBUG/test, INFO/prod |
Logging level based on version |
Flask Application
| Config |
Value |
Description |
MAX_CONTENT_LENGTH |
20MB |
Maximum upload file size |
Rate Limiter
| Limit |
Scope |
| 500/hour |
All endpoints |
| 20/minute |
/predict (decorated) |
Model Configuration
| Variable |
Default |
Description |
MODEL_PATH |
models/hydra-3.5.safetensors |
Model file location |
DEVICE |
cuda/cpu |
PyTorch device |
MAX_SEQ_LEN |
1024 |
Max patches for input |
PATCH_SIZE |
16 |
Patch size (pixels) |
Prediction Settings
| Variable |
Value |
Description |
DEFAULT_TOP_K |
200 |
Default tag count |
ALLOWED_TOP_K |
{50,75,100,150,200,300} |
Valid top_k values |
File Handling
| Variable |
Default |
Description |
SAVE_UPLOADS |
false |
Save uploads to disk |
UPLOAD_DIR |
/app/uploads |
Upload save directory |
ALLOWED_EXTENSIONS |
7 formats |
Valid file extensions |
ALLOWED_MIME_TYPES |
7 MIME types |
Valid MIME types |
Blocked Tags
| Variable |
Default |
Description |
BLOCKED_TAGS |
{'mature'} |
Set of tag names to exclude from API response. Add deprecated/undesired tags here to prevent them from being returned to clients. |
2. Helper Functions
secure_log(s: str | None) -> str
| Location |
app.py:84-89 |
| Input |
`s: str |
| Output |
str - Sanitized string |
| Purpose |
Remove control characters and newlines from log strings |
status_emoji(status_code) -> str
| Location |
app.py:91-97 |
| Input |
status_code: int - HTTP status code |
| Output |
str - Emoji (🟢/🟡/🔴) |
| Purpose |
Get status emoji for logging |
| Status Range |
Emoji |
| 200-299 |
🟢 |
| 300-399 |
🟡 |
| 400+ |
🔴 |
get_country_flag(accept_lang) -> str
| Location |
app.py:99-107 |
| Input |
accept_lang: str - Accept-Language header |
| Output |
str - Country flag emoji |
| Purpose |
Extract country code from Accept-Language header |
get_ip_identifier(ip: str | None) -> str
| Location |
app.py:109-119 |
| Input |
ip: str - IP address string |
| Output |
str - Colored IP identifier (e.g., "🟪 192.168.1.1") |
| Purpose |
Generate consistent color + IP string for logging |
The function uses a simple hash of the IP's octets to generate a consistent color. Same IP always maps to same color.
| Hash Index |
Emoji |
Color |
| 0 |
⬛️ |
Black |
| 1 |
🟫 |
Brown |
| 2 |
🟪 |
Purple |
| 3 |
🟦 |
Blue |
| 4 |
🟩 |
Green |
| 5 |
⬜ |
White |
| 6 |
🟨 |
Yellow |
| 7 |
🟧 |
Orange |
| 8 |
🟥 |
Red |
parse_user_agent(ua_str: str) -> tuple[str, str]
| Location |
app.py:121-163 |
| Input |
ua_str: str - User-Agent string |
| Output |
tuple[str, str] - (device_type, ua_string) |
| Purpose |
Parse User-Agent string into device type and short UA |
| Device Type |
Detection |
| bot |
spider, bot, crawler |
| mobile |
smartphone, or "mobile" in UA |
| tablet |
tablet |
| desktop |
default |
3. Request Hooks
@app.before_request
| Location |
app.py:165-167 |
| Purpose |
Start request timing for duration tracking |
| Sets |
g.start_time - Request start timestamp |
@app.after_request
| Location |
app.py:169-227 |
| Purpose |
Add security headers and request logging |
| Headers Added |
HSTS, X-Frame-Options, CSP, etc. |
Security Headers Added:
| Header |
Value |
| Strict-Transport-Security |
max-age=31536000; includeSubDomains |
| X-Frame-Options |
DENY |
| X-Content-Type-Options |
nosniff |
| Referrer-Policy |
strict-origin-when-cross-origin |
| Permissions-Policy |
geolocation=(), microphone=(), camera=() |
| Content-Security-Policy |
default-src 'self'; img-src 'self' data: blob:; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self' https://e621.net; object-src 'none'; base-uri 'self'; |
4. Image Validation Functions
is_valid_image(file) -> bool
| Location |
app.py:253-261 |
| Input |
file - File-like object |
| Output |
bool - True if valid image |
| Purpose |
Verify file is a valid image |
is_allowed_file(filename: str, content_type: str) -> bool
| Location |
app.py:263-265 |
| Input |
filename: str, content_type: str |
| Output |
bool - True if allowed |
| Purpose |
Check file extension and MIME type |
5. Processing Functions
detect_meta_tags_for_image_path(image_path: str) -> set[str]
| Location |
app.py:267-323 |
| Input |
image_path: str - Path to image file |
| Output |
set[str] - Auto-detected meta tags |
| Purpose |
Generate meta tags from image properties |
| Tag |
Condition |
| animated |
GIF with n_frames > 1 |
| thumbnail |
w ≤ 250 and h ≤ 250 |
| low_res |
w ≤ 500 and h ≤ 500 |
| hi_res |
w ≥ 1600 or h ≥ 1200 |
| absurd_res |
w ≥ 3200 or h ≥ 2400 |
| 4k |
Exact 3840x2160/4096x2160 variants |
| superabsurd_res |
w ≥ 10000 and h ≥ 10000 |
| long_image |
ratio ≥ 4:1 or ≤ 1:4 |
| tall_image |
ratio ≤ 1:4 |
| 1:1, 2:1, 16:9, etc. |
Exact aspect ratios |
| widescreen |
16:9 or ~16:10 |
Note: The current year tag (e.g., 2025, 2026) is added separately in the /predict endpoint after calling this function. It is not part of detect_meta_tags_for_image_path().
save_upload(file, original_filename) -> str | None
| Location |
app.py:325-341 |
| Input |
file, original_filename: str |
| Output |
str - Save path, or None on failure |
| Purpose |
Save uploaded file to disk |
| Requirement |
SAVE_UPLOADS=true |
6. Flask Routes
index() -> str
| Location |
app.py:348-350 |
| Route |
GET / |
| Output |
HTML - Rendered index.html |
| Purpose |
Main UI page |
favicon() -> Response
| Location |
app.py:352-356 |
| Route |
GET /favicon.ico |
| Output |
ICO file with 24h caching |
| Purpose |
Serve favicon |
static_files(filename: str) -> Response
| Location |
app.py:358-362 |
| Route |
GET /static/<path> |
| Input |
filename: str - File path |
| Output |
Static file with 24h caching |
| Purpose |
Serve CSS, JS, icons |
service_worker() -> Response
| Location |
app.py:364-371 |
| Route |
GET /service-worker.js |
| Output |
JS with no-cache headers |
| Purpose |
PWA service worker |
health() -> tuple
| Location |
app.py:373-389 |
| Route |
GET /health |
| Output |
JSON - Health status |
| Purpose |
Health check endpoint |
Healthy Response:
Unhealthy Response (503):
predict() -> tuple
| Location |
app.py:391-509 |
| Route |
POST /predict |
| Rate Limit |
20/minute |
| Input |
image file (multipart/form-data), optional top_k |
| Output |
JSON - Tag predictions |
Request Parameters:
| Parameter |
Type |
Required |
Description |
| image |
file |
Yes |
Image file |
| top_k |
int |
No |
Number of tags (50-300, default 200) |
Success Response:
Note: The auto_meta array includes the current year (e.g., 2025, 2026) as a meta tag with 1.0 confidence. Frontend can filter this via the addCurrentYearTag setting (default: true).
Error Responses:
| Status |
Error Message |
| 400 |
"No image provided" |
| 400 |
"Empty filename" |
| 400 |
"File type not allowed" |
| 400 |
"Invalid or corrupted image file" |
| 413 |
"File too large. Maximum size is 20MB." |
| 500 |
"Internal server error" |
robots() -> Response
| Location |
app.py:514-523 |
| Route |
GET /robots.txt |
| Output |
Robots.txt content |
| Purpose |
Search engine instructions |
Content:
sitemap() -> Response
| Location |
app.py:525-537 |
| Route |
GET /sitemap.xml |
| Output |
XML sitemap |
| Purpose |
SEO sitemap |
handle_file_too_large(e) -> tuple
| Location |
app.py:343-346 |
| Handler |
413 errors |
| Purpose |
Handle file too large |
7. Runtime Initialization
These run at module load time (lines 229-251):
Global Runtime Objects
| Object |
Type |
Description |
model |
Hydra |
Loaded ML model |
tag_list |
list[str] |
All tag names (8,888 in Hydra 3.5) |
_SUBCATEGORY_MAP |
dict |
6,263 general → subcategory mappings (in _subcat.py) |
8. Entry Point
| Setting |
Value |
Description |
| Host |
0.0.0.0 |
Accept all interfaces |
| Port |
5000 |
Default port |
| debug |
False |
Production mode |
Quick Reference for Agents
Calling the API
Environment Variables
| Variable |
Required |
Description |
| APP_VERSION |
No |
Version string |
| MODEL_PATH |
No |
Model file path |
| DEVICE |
No |
cuda or cpu |
| MAX_SEQ_LEN |
No |
Max patches |
Error Handling
The app returns different HTTP status codes:
- 200: Success
- 400: Bad request (missing file, invalid type)
- 413: File too large
- 429: Rate limit exceeded
- 500: Internal error
Logging
All logs include timestamp, level, and emoji prefix:
- 🚀 - Startup/version
- ⚙️ - Loading
- ✅ - Success
- ⚠️ - Warning
- ❌ - Error
- 📥 - Upload
- 📤 - Prediction request
- 👤 - Page view