pyconify

Python wrapper for the Iconify API.

Iconify is a versatile icon framework that includes 100+ icon sets with more than 100,000 icons from FontAwesome, Material Design Icons, DashIcons, Feather Icons, EmojiOne, Noto Emoji and many other open source icon sets.

Search for icons at: https://icon-sets.iconify.design

Installation

pip install pyconify
# or
conda install -c conda-forge pyconify

Usage

import pyconify

# Info on available collections
collections = pyconify.collections()

# Info on specific collection(s)
details = pyconify.collection("fa", "fa-brands")

# Search for icons
hits = pyconify.search("python")

# Get icon data
data = pyconify.icon_data("fa-brands", "python")

# Get SVG
svg = pyconify.svg("fa-brands", "python")

# Get path to SVG on disk
# will either return cached version, or write to temp file
file_name = pyconify.svg_path("fa-brands", "python")

# Get CSS
css = pyconify.css("fa-brands", "python")

# Keywords
pyconify.keywords('home')

# API version
pyconify.iconify_version()

See details for each of these results in the Iconify API documentation.

cache

While the first fetch of any given SVG will require internet access, pyconfiy caches svgs for faster retrieval and offline use. To see or clear cache directory:

import pyconify

# reveal location of cache
# will be ~/.cache/pyconify on linux and macos
# will be %LOCALAPPDATA%\pyconify on windows
# falls back to ~/.pyconify if none of the above are available
pyconify.get_cache_directory()

# remove the cache directory (and all its contents)
pyconify.clear_cache()

If you'd like to precache a number of svgs, the current recommendation is to use the svg() function:

import pyconify

ICONS_TO_STORE = {"mdi:bell", "mdi:bell-off", "mdi:bell-outline"}
for key in ICONS_TO_STORE:
    pyconify.svg(key)

Later calls to svg() will use the cached values.

To specify a custom cache directory, set the PYCONIFY_CACHE environment variable to your desired directory. To disable caching altogether, set the PYCONIFY_CACHE environment variable to false or 0.

freedesktop themes

pyconify includes a convenience function to generate a directory of SVG files in the freedesktop icon theme specification

It takes a mapping of names from the icon naming spec to iconify keys (e.g. "prefix:icon"). Icons will be placed in the appropriate freedesktop subdirectory based on the icon name. Unknown icons will be placed in the other subdirectory.

from pyconify import freedesktop_theme
from pyconify.api import svg
icons = {
    "edit-copy": "ic:sharp-content-copy",
    "edit-delete": {"key": "ic:sharp-delete", "color": "red"},
    "weather-overcast": "ic:sharp-cloud",
    "weather-clear": "ic:sharp-wb-sunny",
    "bell": "bi:bell",
}
folder = freedesktop_theme(
    "mytheme",
    icons,
    base_directory="~/Desktop/icons",
)

would create

~/Desktop/icons/
├── mytheme
│   ├── actions
│   │   ├── edit-copy.svg
│   │   └── edit-delete.svg
│   ├── status
│   │   ├── weather-clear.svg
│   │   └── weather-overcast.svg
│   └── other
│       └── bell.svg
└── index.theme

Development

The easiest way to get started is to use the github cli and uv:

gh repo fork pyapp-kit/pyconify --clone
# or just
# gh repo clone pyapp-kit/pyconify
cd pyconify
uv sync

Run tests:

uv run pytest

Lint and type-check files (using prek):

uv run prek run --all-files

To run the hooks automatically on every commit:

uv run prek install