iconfilters

Class info

Classes

Name	Children	Inherits
AsciiIcon jinjarope.iconfilters ASCII icons for different file types.		StrEnum
AsciiIconMapping jinjarope.iconfilters		dict

🛈 DocStrings

AsciiIcon

Bases: StrEnum

ASCII icons for different file types.

Source code in src/jinjarope/iconfilters.py

class AsciiIcon(StrEnum):
    """ASCII icons for different file types."""

    # Default icons
    FOLDER = "📁"
    FILE = "📄"
    HIDDEN = "🔒"
    SYMLINK = "🔗"

    # Documents
    PDF = "📕"
    DOC = "📘"
    TXT = "📝"
    PRESENTATION = "📊"
    SPREADSHEET = "📈"
    EBOOK = "📚"

    # Code
    PYTHON = "🐍"
    JAVA = "☕"
    JS = "📜"
    HTML = "🌐"
    CSS = "🎨"
    CPP = "⚡"
    RUST = "🦀"
    GO = "🐹"
    RUBY = "💎"
    PHP = "🐘"
    SWIFT = "🎯"
    KOTLIN = "🎳"

    # Config & Data
    JSON = "📊"
    CSV = "📑"
    XML = "📐"
    YAML = "⚙️"
    INI = "🔧"
    ENV = "🔐"
    SQL = "🗄️"
    TOML = "⚡"

    # Media
    IMAGE = "🖼️"
    VIDEO = "🎥"
    AUDIO = "🎵"
    FONT = "🔤"
    MODEL_3D = "💠"

    # Design
    PSD = "🎨"
    AI = "🖌️"
    SKETCH = "✏️"
    FIGMA = "🎯"

    # Archives
    ARCHIVE = "📦"
    BACKUP = "💾"

    # Executables & Binaries
    EXECUTABLE = "⚙️"
    DLL = "🔌"
    BINARY = "👾"

    # Development
    GIT = "🌿"
    DOCKERFILE = "🐋"
    LOG = "📋"
    TEST = "🧪"

    # Special
    TEMP = "⌛"
    TRASH = "🗑️"
    LOCK = "🔒"

get_favicon

get_favicon(
    url: str,
    provider: Literal[
        "google", "duckduckgo", "iconhorse", "yandex", "favicon_io", "favicon_ninja"
    ] = "duckduckgo",
    size: int = 32,
)

Return a favicon URL for the given URL.

Parameters:

Name	Type	Description	Default
url	str	The URL to get the favicon for.	required
provider	Literal['google', 'duckduckgo', 'iconhorse', 'yandex', 'favicon_io', 'favicon_ninja']	The provider to use for the favicon.	'duckduckgo'
size	int	Size of the favicon in pixels (not supported by all providers)	32

Source code in src/jinjarope/iconfilters.py

def get_favicon(
    url: str,
    provider: Literal[
        "google", "duckduckgo", "iconhorse", "yandex", "favicon_io", "favicon_ninja"
    ] = "duckduckgo",
    size: int = 32,
):
    """Return a favicon URL for the given URL.

    Args:
        url: The URL to get the favicon for.
        provider: The provider to use for the favicon.
        size: Size of the favicon in pixels (not supported by all providers)
    """
    from urllib.parse import urlparse

    # Parse the URL to get the domain
    domain = urlparse(url).netloc or url

    match provider:
        case "google":
            return f"https://www.google.com/s2/favicons?domain={domain}&sz={size}"
        case "duckduckgo":
            return f"https://icons.duckduckgo.com/ip3/{domain}.ico"
        case "iconhorse":
            return f"https://icon.horse/icon/{domain}?size={size}"
        case "yandex":
            # Yandex supports sizes: 16, 32, 76, 120, 180, 192, 256
            valid_sizes = [16, 32, 76, 120, 180, 192, 256]
            closest_size = min(valid_sizes, key=lambda x: abs(x - size))
            return f"https://favicon.yandex.net/favicon/{domain}?size={closest_size}"
        case "favicon_io":
            return f"https://favicon.io/favicon/{domain}"
        case "favicon_ninja":
            return f"https://favicon.ninja/icon?url={domain}&size={size}"
        case _:
            msg = f"Invalid provider: {provider}"
            raise ValueError(msg)

get_icon_svg

get_icon_svg(
    icon: str,
    color: str | None = None,
    height: str | int | None = None,
    width: str | int | None = None,
    flip: Flip | None = None,
    rotate: Rotation | None = None,
    box: bool | None = None,
) -> str

Return svg for given pyconify icon key.

Key should look like "mdi:file" For compatibility, this method also supports compatibility for emoji-slugs (":material-file:") as well as material-paths ("material/file")

If no icon group is supplied as part of the string, mdi is assumed as group.

When passing a string with "|" delimiters, the returned string will contain multiple icons.

Parameters:

Name	Type	Description	Default
icon	str	Pyconify icon name	required
color	str | None	Icon color. Replaces currentColor with specific color, resulting in icon with hardcoded palette.	None
height	str | int | None	Icon height. If only one dimension is specified, such as height, other dimension will be automatically set to match it.	None
width	str | int | None	Icon width. If only one dimension is specified, such as height, other dimension will be automatically set to match it.	None
flip	Flip | None	Flip icon.	None
rotate	Rotation | None	Rotate icon. If an integer is provided, it is assumed to be in degrees.	None
box	bool | None	Adds an empty rectangle to SVG that matches the icon's viewBox. It is needed when importing SVG to various UI design tools that ignore viewBox. Those tools, such as Sketch, create layer groups that automatically resize to fit content. Icons usually have empty pixels around icon, so such software crops those empty pixels and icon's group ends up being smaller than actual icon, making it harder to align it in design.	None

Example

get_icon_svg("file")  # implicit mdi group
get_icon_svg("mdi:file")  # pyconify key
get_icon_svg("material/file")  # Material-style path
get_icon_svg(":material-file:")  # material-style emoji slug
get_icon_svg("mdi:file|:material-file:")  # returns a string with two svgs

Source code in src/jinjarope/iconfilters.py

def get_icon_svg(
    icon: str,
    color: str | None = None,
    height: str | int | None = None,
    width: str | int | None = None,
    flip: Flip | None = None,
    rotate: Rotation | None = None,
    box: bool | None = None,
) -> str:
    """Return svg for given pyconify icon key.

    Key should look like "mdi:file"
    For compatibility, this method also supports compatibility for
    emoji-slugs (":material-file:") as well as material-paths ("material/file")

    If no icon group is supplied as part of the string, mdi is assumed as group.

    When passing a string with "|" delimiters, the returned string will contain multiple
    icons.

    Args:
        icon: Pyconify icon name
        color: Icon color. Replaces currentColor with specific color, resulting in icon
               with hardcoded palette.
        height: Icon height. If only one dimension is specified, such as height, other
                dimension will be automatically set to match it.
        width: Icon width. If only one dimension is specified, such as height, other
               dimension will be automatically set to match it.
        flip: Flip icon.
        rotate: Rotate icon. If an integer is provided, it is assumed to be in degrees.
        box: Adds an empty rectangle to SVG that matches the icon's viewBox. It is needed
            when importing SVG to various UI design tools that ignore viewBox. Those
            tools, such as Sketch, create layer groups that automatically resize to fit
            content. Icons usually have empty pixels around icon, so such software crops
            those empty pixels and icon's group ends up being smaller than actual icon,
            making it harder to align it in design.

    Example:
        ``` py
        get_icon_svg("file")  # implicit mdi group
        get_icon_svg("mdi:file")  # pyconify key
        get_icon_svg("material/file")  # Material-style path
        get_icon_svg(":material-file:")  # material-style emoji slug
        get_icon_svg("mdi:file|:material-file:")  # returns a string with two svgs
        ```
    """
    label = ""
    for splitted in icon.split("|"):
        key = get_pyconify_key(splitted)
        import pyconify

        label += pyconify.svg(
            key,
            color=color,
            height=height,
            width=width,
            flip=flip,
            rotate=rotate,
            box=box,
        ).decode()
    return label

get_path_ascii_icon

get_path_ascii_icon(path: str | PathLike[str]) -> str

Get an ASCII icon for a given file path based on its type.

Parameters:

Name	Type	Description	Default
path	str | PathLike[str]	File path as string or Path object	required

Returns:

Type	Description
str	ASCII icon representing the file type

Source code in src/jinjarope/iconfilters.py

def get_path_ascii_icon(path: str | os.PathLike[str]) -> str:
    """Get an ASCII icon for a given file path based on its type.

    Args:
        path: File path as string or Path object

    Returns:
        ASCII icon representing the file type
    """
    path_obj = upath.UPath(path)

    # Handle symbolic links
    if path_obj.is_symlink():
        return AsciiIcon.SYMLINK

    # Handle folders
    if path_obj.is_dir():
        return AsciiIcon.FOLDER

    # Handle hidden files (Unix-style)
    if path_obj.name.startswith("."):
        return AsciiIcon.HIDDEN

    # Get extension and return corresponding icon or default
    extension = path_obj.suffix.lower()
    name_lower = path_obj.name.lower()

    # Check full filename for special cases
    if name_lower in EXTENSION_MAP:
        return EXTENSION_MAP[name_lower]

    return EXTENSION_MAP.get(extension, AsciiIcon.FILE)

get_path_icon

get_path_icon(path: str | PathLike[str]) -> str

Get the icon mapping for a given file path or directory.

Parameters:

Name	Type	Description	Default
path	str | PathLike[str]	Path to the file or directory	required

Returns:

Type	Description
str	iconify icon slug

Source code in src/jinjarope/iconfilters.py

def get_path_icon(path: str | os.PathLike[str]) -> str:
    """Get the icon mapping for a given file path or directory.

    Args:
        path: Path to the file or directory

    Returns:
        iconify icon slug
    """
    path_obj = upath.UPath(path)

    # Handle directories
    if path_obj.is_dir():
        return {"icon": "vscode-icons:default-folder", "color": "#90A4AE"}["icon"]

    # Special cases for specific filenames
    if path_obj.name.lower() in ICONIFY_ICONS:
        return ICONIFY_ICONS[path_obj.name.lower()]["icon"]

    # Handle files by extension
    extension = path_obj.suffix.lower().lstrip(".")
    return ICONIFY_ICONS.get(
        extension, {"icon": "vscode-icons:default-file", "color": "#000000"}
    )["icon"]

get_pyconify_key

get_pyconify_key(icon: str) -> str

Convert given string to a pyconify key.

Converts the keys from MkDocs-Material ("material/sth" or ":material-sth:") to their pyconify equivalent.

Parameters:

Name	Type	Description	Default
icon	str	The string which should be converted to a pyconify key.	required

Source code in src/jinjarope/iconfilters.py

def get_pyconify_key(icon: str) -> str:
    """Convert given string to a pyconify key.

    Converts the keys from MkDocs-Material ("material/sth" or ":material-sth:")
    to their pyconify equivalent.

    Args:
        icon: The string which should be converted to a pyconify key.
    """
    for k, v in icons.PYCONIFY_TO_PREFIXES.items():
        path = f"{v.replace('-', '/')}/"
        icon = icon.replace(path, f"{k}:")
        icon = icon.replace(f":{v}-", f"{k}:")
    icon = icon.strip(":")
    mapping = {k: v[0] for k, v in icons._get_collection_map().items()}
    for prefix in mapping:
        if icon.startswith(f"{prefix}-"):
            icon = icon.replace(f"{prefix}-", f"{prefix}:")
            break
    if (count := icon.count(":")) > 1:
        icon = icon.replace(":", "-", count - 1)
    if ":" not in icon:
        icon = f"mdi:{icon}"
    return icon