Skip to main content

LogoHunter 🎯

An async Python library and CLI for discovering and processing high-quality customer logos from websites.

  • Library: programmatic API to find, score, and fetch the best logo for a domain
  • CLI: quick, pretty terminal tool to inspect candidates and save the best logo

Features

  • Async discovery with httpx and selectolax (fast, non-blocking)
  • Multi-source discovery:
    • Web App Manifest icons
    • Apple Touch icons
    • Standard favicon declarations (including SVG)
    • Open Graph / social tags
    • Heuristics for logo images in the DOM (classes/ids/alt)
    • Common fallback paths
  • Rule-based scoring engine (modular bonuses/penalties under src/logohunter/rules)
  • Image validation and basic processing with Pillow (LANCZOS resizing)
  • Rich-powered CLI for inspecting candidates and scores

Requirements

  • Python 3.12+
  • Dependencies (installed automatically): httpx, selectolax, Pillow, rich

Installation

From source (recommended for now):

# clone and install in editable mode
git clone <repository-url>
cd logohunter
pip install -e .

After install, the CLI command logohunt is available. You can also run it with uv:

uv run logohunt github.com

Note: If this project is published on PyPI under the same name, you can install with:

pip install logohunter

Quick Start (Library)

import asyncio
from logohunter import LogoHunter

async def main():
    hunter = LogoHunter()

    # Get the best logo as bytes (PNG/JPEG/WebP for raster images, raw SVG bytes for SVG)
    logo_bytes = await hunter.get_customer_logo(
        "github.com",
        output_format="PNG",
        resize_to=(128, 128),
    )

    if logo_bytes:
        # Note: If the selected logo is SVG, you'll receive SVG bytes regardless of output_format
        with open("github_logo", "wb") as f:
            f.write(logo_bytes)
        print("Logo saved (extension depends on content: add .png/.svg accordingly)!")
    else:
        print("No logo found")

asyncio.run(main())

If you specifically need to rasterize SVG to PNG, install a converter (e.g., cairosvg) and perform that step yourself. The library currently returns raw SVG bytes when the best logo is an SVG.

Quick Start (CLI)

Inspect candidates, see scores, and optionally save the best one.

# Basic usage
logohunt github.com

# Save best logo to current directory (logo.png/svg)
logohunt github.com --save

# Save to a directory and show all scoring details
logohunt github.com --save logos/ --all-scores

# Verbose mode will also show exceptions if they occur
logohunt github.com --verbose

Example CLI output (truncated):

LogoHunt • Analyzing github.com

📊 Found 5 logo candidates
#1 • Score: 1240 • SVG
https://github.com/favicon.svg
#2 • Score: 860 • PNG (180×180)
https://github.com/apple-touch-icon.png
...
✅ Successfully fetched logo
💾 Saved to: /path/to/logos/logo.svg

Discovery Strategy

LogoHunter collects potential logo icons from multiple sources:

  1. Web App Manifest (<link rel="manifest" href="..."> → icons array)
  2. Apple Touch icons (<link rel="apple-touch-icon" ...>, including precomposed)
  3. Standard favicon declarations (<link rel="icon" ...>, SVG preferred when available)
  4. Social/preview images (og:image, twitter:image) with penalties applied via scoring
  5. Heuristics for DOM images that look like logos
    • Looks for img elements in containers with classes/ids like logo, brand, header-logo, site-logo, navbar-brand, etc.
    • Also considers alt, class, id, and filename keywords containing logo
  6. Common fallback paths like /favicon.svg, /logo.svg, /favicon.ico, etc.

All discovered candidates are de-duplicated and then scored.

Scoring System (Rule-based)

Scoring is modular and data-driven:

  • Rules live under src/logohunter/rules/ and are grouped by category (e.g., html, dimensions).
  • Each category has bonuses.txt and penalties.txt that define weights, and Python functions that implement the checks.
  • The engine loads all rules and computes a cumulative score with per-rule breakdowns.

Examples of current rules and weights (abbreviated):

  • HTML bonuses (rules/html/bonuses.txt):
    • +100 logo_in_filename, +100 logo_in_css_classes, +100 logo_in_element_id, +40 logo_in_alt_text
    • +80 header_proximity, +80 parent_logo_context, +50 brand_keywords
  • HTML penalties (rules/html/penalties.txt):
    • -200 social_media_context, -200 single_color_svg, -150 generic_image_names
    • -100 deep_dom_nesting, -75 advertisement_context, -60 content_area_context
  • Dimension rules (rules/dimensions/*.txt):
    • +60 apple_touch_icon_sizes
    • -300 social_media_dimensions, -200 banner_dimensions, -150 very_small_images
    • -80 extremely_wide_aspect_ratio, -50 small_images, -20 odd_dimensions

The CLI can show a detailed rule breakdown for the top candidates (--all-scores).

API Reference

Instantiate the hunter and use its async methods.

  • await hunter.get_customer_logo(domain, output_format="PNG", resize_to=None, logger=None) -> bytes | None

    • Discovers, fetches, validates, and processes the best logo.
    • Returns image bytes. If the best logo is SVG, returns the raw SVG bytes.
  • await hunter.find_logo_urls(domain) -> list[str]

    • Returns a list of candidate logo URLs sorted by score (best first).
  • await hunter.find_logo_candidates(domain) -> list[Icon]

    • Returns full candidate objects with scoring details.
  • await hunter.fetch_best_logo(urls) -> PIL.Image.Image | str | None

    • Fetches and validates the best workable logo from the provided URLs.
    • Returns a PIL Image for raster formats, or an SVG string for vector logos.
  • LogoHunter.process_image(image, output_format="PNG", resize_to=None) -> bytes

    • Static method. For PIL images, resizes and encodes to the requested format.
    • For SVG strings, returns the SVG content as UTF‑8 bytes (no rasterization).

Logging

  • The library logs summary information at INFO and detailed steps at DEBUG.
  • You can pass a custom logger to get_customer_logo(..., logger=my_logger) to control output.

Example:

import logging
from logohunter import LogoHunter

logger = logging.getLogger("my_app")
logger.setLevel(logging.INFO)

hunter = LogoHunter()
logo_bytes = await hunter.get_customer_logo("github.com", logger=logger)

Contributing

  • Issues and PRs are welcome.
  • The scoring system is designed to be extensible — contributions to rules are appreciated.
  • Run tests with pytest (see pyproject.toml for dev dependencies).

License

MIT License - see LICENSE file for details.

Changelog

0.1.0

  • Initial async library and CLI
  • Modular rule-based scoring engine
  • Rich CLI for candidate inspection and saving

Metadata

Release files for logohunter 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for logohunter 0.1.2
File Size Uploaded Provenance Actions
logohunter-0.1.2.tar.gz 23.8 kB Without provenance Details for logohunter-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for logohunter 0.1.2
File Interpreter ABI Platform Actions
logohunter-0.1.2-py3-none-any.whl Python 3 none any Details for logohunter-0.1.2-py3-none-any.whl

Total release size: 49.3 kB

Release files / logohunter-0.1.2.tar.gz

Download URL logohunter-0.1.2.tar.gz
Size 23.8 kB
Tags Source
SHA-256 checksum
How to use checksums
eb4736a8d2b63d5c60e195d5bfaa3be13c963c841d9d7335150b81c77009591e
BLAKE2b-256 checksum
How to use checksums
9e48f94198a0a387d825b0182e44d86a67b59fa61af7615ae4e4a923460dfa2a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.0

Release files / logohunter-0.1.2-py3-none-any.whl

Download URL logohunter-0.1.2-py3-none-any.whl
Size 25.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3f8cb46c7155944c6cc3f46aebc08d4b00576b8a913503906e98784ea92b21d5
BLAKE2b-256 checksum
How to use checksums
e6d18f7f2cc3dde46aadeed6e29d998be7b5981a16c4ae456ca05deddb67841c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.0

Security for logohunter 0.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.2 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page