icoextract 0.3.0__py3-none-any.whl

icoextract/__init__.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2015-2016 Fadhil Mandaga
+# Copyright (c) 2019-2026 James Lu <james@overdrivenetworks.com>
+"""
+Windows executable icon extractor.
+
+.. include:: ../LIB-USAGE.md
+"""
+
+from contextlib import ExitStack
+import enum
+import logging
+import mmap
+
+from .base_extractor import BaseIconExtractor
+from .exceptions import (
+    IconExtractorError,
+    IconNotFoundError,
+    NoIconsAvailableError,
+    InvalidIconDefinitionError,
+    UnknownExecutableError,
+)
+from .ne_extractor import NEIconExtractor
+from .pe_extractor import PEIconExtractor
+
+logger = logging.getLogger("icoextract")
+logging.basicConfig()
+
+try:
+    from .version import __version__
+except ImportError:
+    __version__ = 'unknown'
+    logger.info('icoextract: failed to read program version')
+
+__all__ = [
+    'IconExtractor',
+    'IconExtractorError',
+    'IconNotFoundError',
+    'NoIconsAvailableError',
+    'InvalidIconDefinitionError',
+    'UnknownExecutableError',
+    'ExecutableType',
+]
+
+class ExecutableType(enum.Enum):
+    """Enum for supported executable formats."""
+    AUTO = 0
+    PE = 1
+    NE = 2
+
+def detect_executable_type(buf: bytearray | mmap.mmap) -> ExecutableType:
+    if buf[:2] != b'MZ':
+        raise UnknownExecutableError("Unknown executable type (no MZ header)")
+
+    # Get the offset to the real header (located at 0x3C)
+    e_lfanew = int.from_bytes(buf[0x3C:0x40], byteorder='little')
+    signature = buf[e_lfanew:e_lfanew+4]
+
+    if signature.startswith(b'PE\x00\x00'):
+        return ExecutableType.PE
+    if signature.startswith(b'NE'):
+        return ExecutableType.NE
+    raise UnknownExecutableError("Unknown / unsupported executable type")
+
+def IconExtractor(filename: str | None = None,
+                  data: bytearray | mmap.mmap | None = None,
+                  exe_type: ExecutableType = ExecutableType.AUTO) -> BaseIconExtractor:
+    """
+    IconExtractor factory function.
+
+    When `exe_type` is set to *AUTO*, this will return an `icoextract.pe_extractor.PEIconExtractor`
+    for Win32/Win64 PE executables and an `icoextract.ne_extractor.NEIconExtractor` for Win16 NE
+    executables.
+    """
+    if filename is None and data is None:
+        raise ValueError("filename and data cannot both be None")
+
+    if exe_type == ExecutableType.AUTO:
+        if data is not None:
+            exe_type = detect_executable_type(data)
+        else:
+            assert filename
+            with ExitStack() as stack:
+                f = stack.enter_context(open(filename, 'rb'))
+                mm = stack.enter_context(mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_READ))
+                exe_type = detect_executable_type(mm)
+        logger.debug("Detected executable type as %s", exe_type)
+
+    if exe_type == ExecutableType.PE:
+        return PEIconExtractor(filename, data)
+    if exe_type == ExecutableType.NE:
+        return NEIconExtractor(filename, data)
+
+    raise UnknownExecutableError("Unknown executable type")
+
+__pdoc__ = {
+    'scripts': False,
+    'version': False,
+}

icoextract/base_extractor.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2019-2026 James Lu <james@overdrivenetworks.com>
+
+import abc
+import io
+import struct
+
+from .types import ExtractedGroupIcon, GroupIconWithIconOffsets, ResourceID
+
+class BaseIconExtractor(abc.ABC):
+    """Base icon extractor class containing .ico writing logic."""
+
+    @abc.abstractmethod
+    def _extract_icon(self, index: int = 0, resource_id: int | str | None = None) -> ExtractedGroupIcon:
+        """Extract an icon by its index or resource ID."""
+
+    @abc.abstractmethod
+    def list_group_icons(self) -> list[tuple[ResourceID, GroupIconWithIconOffsets]]:
+        """
+        Returns all group icon entries as a list of (resource ID, group icon dir entry) tuples.
+        """
+
+    def _write_ico(self, fd, icons: ExtractedGroupIcon):
+        """Writes ICO data to a file descriptor."""
+        fd.write(b"\x00\x00") # 2 reserved bytes
+        fd.write(struct.pack("<H", 1)) # 0x1 (little endian) specifying that this is an .ICO image
+        fd.write(struct.pack("<H", len(icons)))  # number of images
+
+        dataoffset = 6 + (len(icons) * 16)
+        # First pass: write the icon dir entries
+        for datapair in icons:
+            group_icon, icon_data = datapair
+            # Elements in ICONDIRENTRY and GRPICONDIRENTRY are all the same
+            # except the last value, which is a 2 byte ID in GRPICONDIRENTRY and
+            # the 4 byte offset from the beginning of the file in ICONDIRENTRY.
+            fd.write(bytes(group_icon)[:12])
+            fd.write(struct.pack("<I", dataoffset))
+            dataoffset += len(icon_data)  # Increase offset for next image
+
+        # Second pass: write the icon data
+        for datapair in icons:
+            group_icon, icon_data = datapair
+            fd.write(icon_data)
+
+    def export_icon(self, filename: str, num: int = 0, resource_id: int | str | None = None) -> None:
+        """
+        Exports ICO data for the requested group icon to `filename`.
+
+        Icons can be selected by index (`num`) or resource ID. By default, the first icon in the binary is exported.
+        """
+        group_icon = self._extract_icon(index=num, resource_id=resource_id)
+        with open(filename, 'wb') as f:
+            self._write_ico(f, group_icon)
+
+    def get_icon(self, num: int = 0, resource_id: int | str | None = None) -> io.BytesIO:
+        """
+        Exports ICO data for the requested group icon as a `io.BytesIO` instance.
+
+        Icons can be selected by index (`num`) or resource ID. By default, the first icon in the binary is exported.
+        """
+        group_icon = self._extract_icon(index=num, resource_id=resource_id)
+        f = io.BytesIO()
+        self._write_ico(f, group_icon)
+        return f

icoextract/exceptions.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2019-2026 James Lu <james@overdrivenetworks.com>
+
+class IconExtractorError(Exception):
+    """Superclass for exceptions raised by IconExtractor."""
+
+class IconNotFoundError(IconExtractorError):
+    """Exception raised when extracting an icon index or resource ID that does not exist."""
+
+class NoIconsAvailableError(IconExtractorError):
+    """Exception raised when the input program has no icon resources."""
+
+class InvalidIconDefinitionError(IconExtractorError):
+    """Exception raised when the input program has an invalid icon resource."""
+
+class UnknownExecutableError(IconExtractorError):
+    """Exception raised when the executable type is invalid or not supported."""

icoextract/ne_extractor.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2019-2026 James Lu <james@overdrivenetworks.com>
+
+import logging
+
+try:
+    import nefile
+except ImportError:
+    nefile = None
+
+from .base_extractor import BaseIconExtractor
+from .exceptions import (
+    IconNotFoundError,
+    NoIconsAvailableError
+)
+from .types import (
+    ExtractedGroupIcon,
+    GroupIconDirEntry,
+    GroupIconWithIconOffsets,
+    ResourceID,
+)
+
+logger = logging.getLogger("icoextract")
+
+class NEIconExtractor(BaseIconExtractor):
+    """Win16 New Executable (NE) icon extractor."""
+
+    def __init__(self, filename=None, data=None):
+        """
+        Loads an Win16 New Executable from the given `filename` or `data` (raw buffer).
+        If both `filename` and `data` are given, `filename` takes precedence.
+
+        If the executable has contains no icons, this will raise `NoIconsAvailableError`.
+        """
+        if nefile is None:
+            raise ImportError("nefile module must be installed to extract NE programs")
+        self._ne = nefile.NE(filename, data)
+
+        if not self._ne.resource_table:
+            raise NoIconsAvailableError("Executable does not have any resources")
+        if not (group_icon_resources := self._ne.resource_table.resources.get(
+                nefile.resource_table.ResourceType.RT_GROUP_ICON)):
+            raise NoIconsAvailableError("Executable does not have any group icons")
+
+        self._group_icon_resources = group_icon_resources
+
+    @staticmethod
+    def _convert_nefile_icon_dir_entry(nefile_icon_dir_entry) -> GroupIconDirEntry:
+        assert nefile is not None
+        assert isinstance(nefile_icon_dir_entry, nefile.resources.icon.IconDirectoryEntry)
+        return GroupIconDirEntry(
+            Width=nefile_icon_dir_entry.width,
+            Height=nefile_icon_dir_entry.height,
+            ColorCount=nefile_icon_dir_entry.total_palette_colors,
+            Planes=nefile_icon_dir_entry.color_planes,
+            BitCount=nefile_icon_dir_entry.bits_per_pixel,
+            BytesInRes=nefile_icon_dir_entry.icon_size_in_bytes,
+            ID=nefile_icon_dir_entry.icon_resource_id,
+        )
+
+    def list_group_icons(self) -> list[tuple[ResourceID, GroupIconWithIconOffsets]]:
+        assert nefile is not None
+        result = []
+        resources_offset = self._ne.resource_table.resource_table_start_offset
+        icon_rtt = self._ne.resource_table.resource_type_tables[
+            nefile.resource_table.ResourceType.RT_ICON
+        ]
+        icon_resource_declarations = {
+            rdecl.id: rdecl for rdecl in icon_rtt.resource_declarations
+        }
+        for resource_id, nefile_group_icon in self._group_icon_resources.items():
+            if isinstance(resource_id, str):
+                resource_id_wrapper = ResourceID(raw_id=None, name=resource_id)
+            else:
+                resource_id_wrapper = ResourceID(resource_id)
+
+            icon_infos = []
+            for nefile_icon_dir_entry in nefile_group_icon.icon_directory.directory_entries:
+                grp_icon_dir_entry = self._convert_nefile_icon_dir_entry(nefile_icon_dir_entry)
+                icon_rdecl = icon_resource_declarations[grp_icon_dir_entry.ID]
+                offset = icon_rdecl.data_start_offset
+                file_offset = offset + resources_offset
+                icon_infos.append((grp_icon_dir_entry, offset, file_offset))
+            result.append((resource_id_wrapper, icon_infos))
+        return result
+
+    def _extract_icon(self, index: int = 0, resource_id: int | str | None = None) -> ExtractedGroupIcon:
+        if resource_id is not None:
+            try:
+                nefile_group_icon = self._group_icon_resources[resource_id]
+            except KeyError:
+                raise IconNotFoundError(f"No icon exists with resource ID {resource_id!r}") from None
+        else:
+            icons_by_index = list(self._group_icon_resources.values())
+            try:
+                nefile_group_icon = icons_by_index[index]
+            except IndexError:
+                raise IconNotFoundError(f"No icon exists at index {index}") from None
+
+        results = []
+        for nefile_icon_dir_entry in nefile_group_icon.icon_directory.directory_entries:
+            resource_id = nefile_icon_dir_entry.icon_resource_id
+            grp_icon_dir_entry = self._convert_nefile_icon_dir_entry(nefile_icon_dir_entry)
+            icondata = nefile_group_icon.icons[resource_id].data
+            results.append((grp_icon_dir_entry, icondata))
+        return results

icoextract/pe_extractor.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2015-2016 Fadhil Mandaga
+# Copyright (c) 2019-2026 James Lu <james@overdrivenetworks.com>
+
+import ctypes
+import logging
+import os
+import pathlib
+import platform
+
+import pefile
+
+from .base_extractor import BaseIconExtractor
+from .exceptions import (
+    IconNotFoundError,
+    InvalidIconDefinitionError,
+    NoIconsAvailableError
+)
+from .types import (
+    ExtractedGroupIcon,
+    GroupIconDir,
+    GroupIconDirEntry,
+    GroupIconWithIconOffsets,
+    ResourceID,
+)
+
+logger = logging.getLogger("icoextract")
+
+class PEIconExtractor(BaseIconExtractor):
+    """Win32/Win64 Portable Executable (PE) icon extractor."""
+
+    def __init__(self, filename=None, data=None):
+        """
+        Loads an Win32/Win64 Portable Executable from the given `filename` or `data` (raw buffer).
+        If both `filename` and `data` are given, `filename` takes precedence.
+
+        If the executable has contains no icons, this will raise `NoIconsAvailableError`.
+        """
+        # Use fast loading and explicitly load the RESOURCE directory entry. This saves a LOT of time
+        # on larger files
+        self._pe = pefile.PE(name=filename, data=data, fast_load=True)
+        self._pe.parse_data_directories(pefile.DIRECTORY_ENTRY['IMAGE_DIRECTORY_ENTRY_RESOURCE'])
+
+        if not hasattr(self._pe, 'DIRECTORY_ENTRY_RESOURCE'):
+            raise NoIconsAvailableError("File has no resources")
+
+        # Reverse the list of entries before making the mapping so that earlier values take precedence
+        # When an executable includes multiple icon resources, we should use only the first one.
+        # pylint: disable=no-member
+        resources = {rsrc.id: rsrc for rsrc in reversed(self._pe.DIRECTORY_ENTRY_RESOURCE.entries)}
+
+        self._groupiconres = resources.get(pefile.RESOURCE_TYPE["RT_GROUP_ICON"])
+        if not self._groupiconres:
+            if filename and platform.system() == "Windows":
+                self._print_windows_usage_hint(filename)
+            raise NoIconsAvailableError("File has no group icon resources")
+        self._rticonres = resources.get(pefile.RESOURCE_TYPE["RT_ICON"])
+
+        self._group_icons = self._groupiconres.directory.entries
+        self._group_icons_by_id: dict[int | str, pefile.ResourceDirEntryData] = {}
+        for entry in self._group_icons:
+            self._group_icons_by_id[entry.struct.Name] = entry
+            # For resources with a string name, track them by both the string and the underlying
+            # numerical index
+            if entry.name:
+                self._group_icons_by_id[str(entry.name)] = entry
+
+        self._icons = {icon_entry_list.id: icon_entry_list.directory.entries[0]  # Select first language
+                       for icon_entry_list in self._rticonres.directory.entries}
+
+    def list_group_icons(self) -> list[tuple[ResourceID, GroupIconWithIconOffsets]]:
+        results = []
+        for entry in self._group_icons:
+            resource_id = ResourceID(
+                raw_id=entry.struct.Name,
+                name=str(entry.name) if entry.name else None
+            )
+            grp_icon_resource = self._group_icons_by_id[entry.struct.Name]
+            grp_icon_data_full = self._extract_from_pefile(grp_icon_resource, skip_data=True)
+            # Return only the metadata and offsets
+            grp_icon_data = [
+                (grp_icon_dir_entry, resource_offset, file_offset)
+                for (grp_icon_dir_entry, _, resource_offset, file_offset)
+                in grp_icon_data_full
+            ]
+            results.append((resource_id, grp_icon_data))
+        return results
+
+    def _extract_from_pefile(
+        self,
+        resource_dir_entry_data: pefile.ResourceDirEntryData,
+        skip_data: bool = False,
+    ) -> list[tuple[GroupIconDirEntry, bytes, int, int]]:
+        """
+        Returns the specified group icon in the binary.
+
+        Result is a list of (group icon dir entry, icon data) tuples.
+        """
+        icon_lang = None
+        if resource_dir_entry_data.struct.DataIsDirectory:
+            # Select the first language from subfolders as needed.
+            resource_dir_entry_data = resource_dir_entry_data.directory.entries[0]
+            icon_lang = resource_dir_entry_data.struct.Name
+            logger.debug("Picking first language %s", icon_lang)
+
+        # Read the data pointed to by the group icon directory (GRPICONDIR) struct.
+        rva = resource_dir_entry_data.data.struct.OffsetToData
+        grp_icon_data = self._pe.get_data(rva, resource_dir_entry_data.data.struct.Size)
+
+        grp_icon_dir = GroupIconDir.from_buffer_copy(grp_icon_data)
+        logger.debug("Group icon has %d images: %s",
+                     grp_icon_dir.Count, grp_icon_dir)
+
+        # pylint: disable=no-member
+        if grp_icon_dir.Reserved:
+            # pylint: disable=no-member
+            raise InvalidIconDefinitionError("Invalid group icon definition (got Reserved=%s instead of 0)"
+                % hex(grp_icon_dir.Reserved))
+
+        # For each group icon entry (GRPICONDIRENTRY) that immediately follows, read the struct and look up the
+        # corresponding icon image
+        extracted_grp_icons = []
+        icon_offset = ctypes.sizeof(grp_icon_dir)
+        for grp_icon_index in range(grp_icon_dir.Count):
+            grp_icon_dir_entry = GroupIconDirEntry.from_buffer_copy(grp_icon_data, icon_offset)
+            icon_offset += ctypes.sizeof(grp_icon_dir_entry)
+            logger.debug("Got group icon entry %d: %s", grp_icon_index, grp_icon_dir_entry)
+
+            icon_entry = self._icons[grp_icon_dir_entry.ID]
+            logger.debug("Got icon data for ID %d: %s", grp_icon_dir_entry.ID, icon_entry.data.struct)
+
+            icon_res_offset = icon_entry.data.struct.OffsetToData
+            icon_file_offset = self._pe.get_offset_from_rva(icon_res_offset)
+            icon_data = b''
+            if not skip_data:
+                icon_data = self._pe.get_data(icon_res_offset, icon_entry.data.struct.Size)
+            extracted_grp_icons.append((grp_icon_dir_entry, icon_data, icon_res_offset, icon_file_offset))
+        return extracted_grp_icons
+
+    def _extract_icon(self, index: int = 0, resource_id: int | str | None = None) -> ExtractedGroupIcon:
+        if resource_id is not None:
+            try:
+                resource_dir_entry_data = self._group_icons_by_id[resource_id]
+            except KeyError:
+                raise IconNotFoundError(f"No icon exists with resource ID {resource_id!r}") from None
+        else:
+            try:
+                resource_dir_entry_data = self._group_icons[index]
+            except IndexError:
+                raise IconNotFoundError(f"No icon exists at index {index}") from None
+
+        # Return only the GroupIconDirEntry metadata and icon bytes
+        return [
+            (grp_icon_dir_entry, icon_data)
+            for (grp_icon_dir_entry, icon_data, _, _)
+            in self._extract_from_pefile(resource_dir_entry_data)
+        ]
+
+    @staticmethod
+    def _print_windows_usage_hint(filename):
+        path = pathlib.Path(filename)
+        systemroot = pathlib.Path(os.getenv('SYSTEMROOT'))
+        if path.is_relative_to(systemroot / 'System32') or \
+                path.is_relative_to(systemroot / 'SysWOW64'):
+            mun_path = pathlib.Path(systemroot / 'SystemResources' / (path.name + '.mun'))
+            if mun_path.is_file():
+                logger.warning(
+                    'System DLL files in Windows 10 1903+ no longer contain icons. '
+                    'Try extracting from %s instead.', mun_path)

icoextract/scripts/__init__.py

@@ -0,0 +1 @@
+# Stub so that scripts/ is treated as a package

icoextract/scripts/extract.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2019-2026 James Lu <james@overdrivenetworks.com>
+"""
+Windows executable icon extractor.
+"""
+
+import argparse
+import logging
+import os.path
+
+from icoextract import IconExtractor, logger, __version__
+
+_WRONG_EXTENSIONS_HINT = {'.jpg', '.jpeg', '.png'}
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("-V", "--version", action='version', version=f'icoextract {__version__}')
+    parser.add_argument("-n", "--num", type=int, help="index of icon to extract", default=0)
+    parser.add_argument("-i", "--id", type=str, help="resource ID of icon to extract", default=None)
+    parser.add_argument("-v", "--verbose", action="store_true", help="enables debug logging")
+    parser.add_argument("input", help="input filename (.exe/.dll/.mun)")
+    parser.add_argument("output", help="output filename (.ico)")
+    args = parser.parse_args()
+
+    if args.verbose:
+        logger.setLevel(logging.DEBUG)
+
+    extractor = IconExtractor(args.input)
+
+    try:
+        resource_id = int(args.id)
+    except (ValueError, TypeError):
+        resource_id = args.id
+
+    extractor.export_icon(args.output, num=args.num, resource_id=resource_id)
+    file_ext = os.path.splitext(args.output)[1].lower()
+    if file_ext in _WRONG_EXTENSIONS_HINT:
+        logger.warning('This tool outputs .ico files, not %s. The resulting file will have the wrong file extension.',
+                       file_ext)

icoextract/scripts/icolist.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2019-2026 James Lu <james@overdrivenetworks.com>
+"""
+Lists group icons present in a program.
+"""
+
+import argparse
+import logging
+
+from icoextract import IconExtractor, logger, __version__
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("-V", "--version", action='version', version=f'icoextract {__version__}')
+    parser.add_argument("-v", "--verbose", action="store_true", help="enables debug logging")
+    parser.add_argument("input", help="input filename")
+    args = parser.parse_args()
+
+    if args.verbose:
+        logger.setLevel(logging.DEBUG)
+
+    extractor = IconExtractor(args.input)
+    for idx, entry in enumerate(extractor.list_group_icons()):
+        resource_id, grp_icon_dir_entries = entry
+        print(f"Group Icon Index: {idx}    ", end='')
+
+        print(f"ID: {resource_id}", end='')
+        if resource_id.raw_id:
+            print(f"({hex(resource_id.raw_id)})", end='')
+        print("    ", end='')
+
+        print(f"Count: {len(grp_icon_dir_entries)}")
+        for (grp_icon_dir_entry, resource_offset, file_offset) in grp_icon_dir_entries:
+            print(f"    Icon ID: {grp_icon_dir_entry.ID}"
+                  # Width and Height are u8 values where 0 means 256
+                  f"    Width: {grp_icon_dir_entry.Width or 256}"
+                  f"    Height: {grp_icon_dir_entry.Height or 256}"
+                  f"    Resource Offset: {hex(resource_offset)}"
+                  f"    File Offset: {hex(file_offset)}"
+                  f"    Size: {grp_icon_dir_entry.BytesInRes}")

icoextract/scripts/thumbnailer.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2019-2026 James Lu <james@overdrivenetworks.com>
+"""
+Linux (freedesktop.org) thumbnailer for Windows PE files (.exe/.dll)
+"""
+
+import argparse
+import logging
+import sys
+
+from PIL import Image
+
+from icoextract import IconExtractor, IconExtractorError, logger, __version__
+
+def generate_thumbnail(inputfile, outfile, size=256, force_resize=False):
+    """
+    Generates a thumbnail for an .exe file.
+
+    inputfile: the input file path (%i)
+    outfile: output filename (%o)
+    size: determines the thumbnail output size (%s)
+    """
+    try:
+        extractor = IconExtractor(inputfile)
+    except RuntimeError:
+        logger.debug("Failed to extract icon for %s:", inputfile, exc_info=True)
+        sys.exit(1)
+    data = extractor.get_icon()
+
+    im = Image.open(data)  # Open up the .ico from memory
+    if force_resize:
+        logger.debug("Force resizing icon to %dx%d", size, size)
+        im = im.resize((size, size))
+    else:
+        if size > 256:
+            logger.warning('Icon sizes over 256x256 are not supported')
+            size = 256
+        elif size not in (128, 256):
+            logger.warning('Unsupported size %d, falling back to 128x128', size)
+            size = 128
+
+        if size == 128:
+            # If large size thumbnail wasn't requested but one is available, pick an 128x128 icon if available;
+            # otherwise scale down from 256x256 to 128x128. 128x128 is the largest resolution allowed for
+            # "normal" size thumbnails.
+            if (128, 128) in im.info['sizes']:
+                logger.debug("Using native 128x128 icon")
+                im.size = (128, 128)
+            elif im.size > (128, 128):
+                logger.debug("Downsizing icon to 128x128")
+                im = im.resize((128, 128))
+
+    # For legacy apps, try to export the icon with the highest size & bit depth
+    # Some programs (e.g. Internet Explorer 6) put a 16 color icon earlier in the file
+    if im.size <= (48, 48):
+        ico_frames = list(enumerate(im.ico.entry))
+        best_frame_idx, ico_header = max(ico_frames, key=lambda pair: (pair[1].square, pair[1].color_depth))
+        logger.debug("Legacy app: selecting icon %s", ico_header)
+        im = im.ico.frame(best_frame_idx)
+
+    logger.debug("Writing size %s thumbnail for %s to %s", size, inputfile, outfile)
+    im.save(outfile, "PNG")
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("-V", "--version", action='version', version=f'exe-thumbnailer, part of icoextract {__version__}')
+    parser.add_argument("-s", "--size", type=int, help="size of desired thumbnail", default=256)
+    parser.add_argument("-v", "--verbose", action="store_true", help="enables debug logging")
+    parser.add_argument("-f", "--force-resize", action="store_true", help="force resize thumbnail to the specified size")
+    parser.add_argument("inputfile", help="input file name (.exe/.dll/.mun)")
+    parser.add_argument("outfile", help="output file name (.png)")
+    args = parser.parse_args()
+
+    if args.verbose:
+        logger.setLevel(logging.DEBUG)
+
+    try:
+        generate_thumbnail(args.inputfile, args.outfile, size=args.size, force_resize=args.force_resize)
+    except IconExtractorError as e:
+        logger.error("Failed to thumbnail %s: %s", args.inputfile, e)
+        logger.debug("Backtrace:", exc_info=True)

icoextract/types.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2019-2026 James Lu <james@overdrivenetworks.com>
+
+"""
+icoextract common types.
+
+See https://devblogs.microsoft.com/oldnewthing/20120720-00/?p=7083
+for a reference on ICO structures.
+"""
+
+import ctypes
+
+BYTE = ctypes.c_uint8
+WORD = ctypes.c_uint16
+DWORD = ctypes.c_uint32
+
+class ResourceID:
+    """Resource ID wrapper.
+
+    For resources with a string ID, str() will return its string value
+    (e.g. "IDI_MAIN_ICON") and int() will return its underlying numeric ID.
+
+    Numerical icon resource IDs can be accessed via int(), and str() will return
+    the number casted to a string.
+    """
+    def __init__(self, raw_id: int | None = None, name: str | None = None):
+        if raw_id is None and name is None:
+            raise ValueError("raw_id and name cannot both be None")
+        self.raw_id = raw_id
+        self.name = name
+
+    def __str__(self):
+        return self.name or str(self.raw_id)
+
+    def __int__(self):
+        if self.raw_id is not None:
+            return self.raw_id
+        raise ValueError(f"Resource ID {self.name!r} cannot be converted to an int")
+
+    def __repr__(self):
+        if self.name:
+            return f'{self.__class__.__name__}({self.name!r})'
+        return f'{self.__class__.__name__}({self.raw_id})'
+
+class GroupIconDirEntry(ctypes.LittleEndianStructure):
+    """ICO GRPICONDIRENTRY / RESDIR structure"""
+    _pack_ = 1  # Ensures tight packing (no padding)
+    _fields_ = [
+        ("Width", BYTE),
+        ("Height", BYTE),
+        ("ColorCount", BYTE),
+        ("Reserved", BYTE),
+        ("Planes", WORD),
+        ("BitCount", WORD),
+        ("BytesInRes", DWORD),
+        ("ID", WORD),
+    ]
+
+class GroupIconDir(ctypes.LittleEndianStructure):
+    """ICO GRPICONDIR / NEWHEADER structure"""
+    _pack_ = 1
+    _fields_ = [
+        ("Reserved", WORD),
+        ("Type", WORD),
+        ("Count", WORD),
+    ]
+
+ExtractedGroupIcon = list[tuple[GroupIconDirEntry, bytes]]
+GroupIconWithIconOffsets = list[tuple[GroupIconDirEntry, int, int]]

icoextract/version.py

@@ -0,0 +1 @@
+__version__ = '0.3.0'

icoextract-0.3.0.dist-info/METADATA

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: icoextract
+Version: 0.3.0
+Summary: Windows EXE icon extractor
+Author-email: James Lu <james@overdrivenetworks.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pefile
+Provides-Extra: thumbnailer
+Requires-Dist: Pillow; extra == "thumbnailer"
+Provides-Extra: win16
+Requires-Dist: nefile; extra == "win16"
+Provides-Extra: dev
+Requires-Dist: icoextract[thumbnailer]; extra == "dev"
+Requires-Dist: icoextract[win16]; extra == "dev"
+Requires-Dist: pdoc; extra == "dev"
+Dynamic: license-file
+
+# icoextract
+
+[![Build Status](https://woodpecker.overdrivenetworks.com/api/badges/5/status.svg)](https://woodpecker.overdrivenetworks.com/repos/5)
+[![Packaging status](https://repology.org/badge/tiny-repos/icoextract.svg)](https://repology.org/project/icoextract/versions)
+
+**icoextract** is an icon extractor library for Windows executables (.exe/.dll/.mun). It also includes a thumbnailer script (`exe-thumbnailer`) for Linux desktops.
+
+This project is inspired by [extract-icon-py](https://github.com/firodj/extract-icon-py), [icoutils](https://www.nongnu.org/icoutils/), and others.
+
+icoextract aims to be:
+
+- Lightweight
+- Portable (cross-platform)
+- Fast on large files
+
+## Installation
+
+### Dependencies
+
+- Python 3.10+
+- [pefile](https://github.com/erocarrera/pefile)
+- [Pillow](https://pillow.readthedocs.io/en/stable/) - optional, for exe-thumbnailer
+- [nefile](https://github.com/npjg/nefile) - optional, for Win16 / NE EXE support
+
+### Installing from source
+
+You can install the project via pip: `pip3 install icoextract[thumbnailer]`
+
+On Linux, you can activate the thumbnailer by copying [`exe-thumbnailer.thumbnailer`](/exe-thumbnailer.thumbnailer) into the thumbnailers directory:
+
+- `/usr/local/share/thumbnailers/` if you installed `icoextract` globally
+- `~/.local/share/thumbnailers` if you installed `icoextract` for your user only
+
+The thumbnailer should work with any file manager that implements the [Freedesktop Thumbnails Standard](https://specifications.freedesktop.org/thumbnail-spec/thumbnail-spec-latest.html): this includes Nautilus, Caja, Nemo, Thunar (when Tumbler is installed), and PCManFM. KDE / Dolphin uses a different architecture and is *not* supported here.
+
+### Distribution packages
+
+You can install icoextract from any of these distribution repositories:
+
+[![Packaging status](https://repology.org/badge/vertical-allrepos/icoextract.svg?columns=5)](https://repology.org/project/icoextract/versions)
+
+
+## Usage
+
+icoextract ships `icoextract` and `icolist` scripts to extract and list icon resources inside a file.
+
+**Note**: recent versions of Windows (Windows 10 1903+) have moved icons from system libraries (`shell32.dll`, etc.) into a new [`C:\Windows\SystemResources`](https://superuser.com/questions/1480268/) folder. icoextract can extract these `.mun` files natively, but the `.dll`s themselves no longer contain icons.
+
+For API docs, see https://projects.jlu5.com/icoextract.html
+
+```
+usage: icoextract [-h] [-V] [-n NUM] [-i ID] [-v] input output
+
+Windows executable icon extractor.
+
+positional arguments:
+  input          input filename (.exe/.dll/.mun)
+  output         output filename (.ico)
+
+options:
+  -h, --help     show this help message and exit
+  -V, --version  show program's version number and exit
+  -n, --num NUM  index of icon to extract
+  -i, --id ID    resource ID of icon to extract
+  -v, --verbose  enables debug logging
+```
+
+```
+usage: icolist [-h] [-V] [-v] input
+
+Lists group icons present in a program.
+
+positional arguments:
+  input          input filename
+
+options:
+  -h, --help     show this help message and exit
+  -V, --version  show program's version number and exit
+  -v, --verbose  enables debug logging
+```

icoextract-0.3.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+icoextract/__init__.py,sha256=z5OWuLNir146vZW21b3a8SOQEL8iyLbvPsrJgB9FW6Q,3042
+icoextract/base_extractor.py,sha256=hbg8gGsIvPIiSc50WINKPb-ilbhcn2lyIeLHOiTZB3w,2754
+icoextract/exceptions.py,sha256=QyQBOXh-gQIMS-lLCWN7IJ5OsECc9X0kir5S6AbBpqc,747
+icoextract/ne_extractor.py,sha256=DjpsD62HKs6vBeiBcQVkH9cJyKXEkbvIXrRulYzarsc,4530
+icoextract/pe_extractor.py,sha256=uqqS2pBz_7P7dDDoW31KsSzFjgMicPugoG5ut5QSoZo,7616
+icoextract/types.py,sha256=L9dSrbUV-kWQYQYyg7N8TowiXNIlsKw_1ZWq3rLfB6Y,2055
+icoextract/version.py,sha256=3wVEs2QD_7OcTlD97cZdCeizd2hUbJJ0GeIO8wQIjrk,22
+icoextract/scripts/__init__.py,sha256=sdmatvCNSK7IH6O60271YMOvBgiQNuGCKHMYzmpbvOE,48
+icoextract/scripts/extract.py,sha256=sdIp9lT397mJwPVZE-xHpskE-Ix7n4zqA6MhfzsGgIY,1490
+icoextract/scripts/icolist.py,sha256=JCPBWF-S-zdym52m_1Ort1Aq6v1lwmEOBM9MBJFtRAQ,1632
+icoextract/scripts/thumbnailer.py,sha256=YPELdFojgctUk1P0CV9n0iCM0fVOyhPE2G5VJzC0gRU,3425
+icoextract-0.3.0.dist-info/licenses/LICENSE,sha256=fEExFMN-Gl3DjZptI7fHEbCD8_J1ONExzTRyqyKWrkk,1149
+icoextract-0.3.0.dist-info/METADATA,sha256=2zoUdXiAR4LEFvv08I_V2FY7gd134gdT7u2s0xDFj08,4394
+icoextract-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+icoextract-0.3.0.dist-info/entry_points.txt,sha256=7D4Ml66GpVxArdjGH8FkiU6vGRuFWfcyEBnSUCEDNHo,173
+icoextract-0.3.0.dist-info/top_level.txt,sha256=vDrv1SnIBDoCSBkNAzC6EJdwNhNhWTwBXP2kMC9o3rQ,11
+icoextract-0.3.0.dist-info/RECORD,,

icoextract-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

icoextract-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+exe-thumbnailer = icoextract.scripts.thumbnailer:main [thumbnailer]
+icoextract = icoextract.scripts.extract:main
+icolist = icoextract.scripts.icolist:main

icoextract-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-2016 Fadhil Mandaga
+Copyright (c) 2019-2026 James Lu <james@overdrivenetworks.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

icoextract-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+icoextract