pyconify

0.2.1 · active · verified Thu Apr 16

pyconify is a Python wrapper for the universal Iconify API, providing access to over 100 icon sets and more than 100,000 icons from popular collections like FontAwesome and Material Design Icons. It allows fetching icon data, SVGs, and CSS, and includes caching for faster retrieval. The library is actively maintained, with its current version being 0.2.1, and receives irregular but ongoing updates.

Common errors

```
NameError: name 'pyconify' is not defined
```
cause The `pyconify` module was used without being imported first.

fix Add `import pyconify` at the beginning of your script or function where `pyconify` is used.
```
KeyError: 'icon_name' (e.g., 'KeyError: 'fa-brands:nonexistent-icon'')
```
cause Attempted to retrieve data for an icon that does not exist or whose name is misspelled in the specified collection. While not an explicit error string found, this is common for libraries retrieving data by key from a remote source.

fix Verify the icon name and collection prefix (e.g., `fa-brands:python`). Use `pyconify.search()` to find available icons or consult the Iconify website (`https://icon-sets.iconify.design`) to confirm valid icon IDs.
```
requests.exceptions.ConnectionError: ('Connection aborted.', ConnectionResetError(104, 'Connection reset by peer'))
```
cause The application failed to connect to the Iconify API due to network issues, firewall restrictions, or the API being temporarily unavailable. `pyconify` relies on the `requests` library for network communication.

fix Check your internet connection and proxy settings. Ensure no firewall is blocking access to `https://api.iconify.design`. If the problem persists, the Iconify API might be experiencing downtime, or your environment might have stricter network policies. Consider pre-caching icons if network reliability is a concern.

Warnings

gotcha pyconify caches fetched SVGs for offline use and faster retrieval. While convenient, this means the first fetch of any new icon will require an internet connection.
Fix: Be aware that initial icon fetches require network access. To pre-cache icons for offline deployment, explicitly call `pyconify.svg()` for all desired icons during application build or setup. To manage caching, set the `PYCONIFY_CACHE` environment variable to a custom path or to `0` or `false` to disable caching entirely.
gotcha Bundling `pyconify` with tools like PyInstaller for standalone applications can be tricky, as the library relies on 'last-minute icon lookups and caching'.
Fix: For applications bundled with PyInstaller or similar tools, it is recommended to pre-fetch all required icons using `pyconify.svg()` and ensure they are included as data files in the application bundle. This is an active area of development, as noted in GitHub issues.

Install

pip install pyconify Install with pip

Imports

pyconify
wrong:
```
from pyconify import icon_data # or similar direct function import
```
correct:
```
import pyconify
```
While specific functions can be imported, the common pattern in examples is to import the `pyconify` module and call its methods (e.g., `pyconify.icon_data`).

Quickstart

This quickstart demonstrates how to import `pyconify`, search for icons, retrieve SVG data for a specific icon, and get the local file path for a cached SVG. It also highlights the caching mechanism and how to configure or clear it.

import pyconify
import os

# Note: pyconify makes network requests to fetch icon data.
# Initial fetches require internet access. Data is then cached.

# Get info on available collections (requires network access initially)
# collections = pyconify.collections()
# print(f"Available collections: {list(collections.keys())[:5]}...")

# Search for icons (e.g., 'python')
hits = pyconify.search("python")
if hits:
    print(f"Found {len(hits)} icons for 'python'. First one: {hits[0]['icon']}")
    # Get SVG for a specific icon (e.g., 'fa-brands:python')
    icon_name = 'fa-brands:python'
    svg_data = pyconify.svg(icon_name)
    print(f"SVG for {icon_name} (first 100 chars):\n{svg_data[:100]}...")

    # Get path to cached SVG on disk
    # This will either return a path to an existing cached file or write to a temp file.
    svg_file_path = pyconify.svg_path(icon_name)
    print(f"SVG file path for {icon_name}: {svg_file_path}")

    # You can configure the cache directory using an environment variable
    # os.environ['PYCONIFY_CACHE'] = '/path/to/custom/cache'
    # To disable caching:
    # os.environ['PYCONIFY_CACHE'] = '0'

# Example of clearing the cache
# pyconify.clear_cache()
# print("Cache cleared.")

view raw JSON →