Implementation:AUTOMATIC1111 Stable diffusion webui File And Path Utilities

Knowledge Sources	AUTOMATIC1111_Stable_diffusion_webui
Domains	Utility Functions, File System
Last Updated	2025-05-15 00:00 GMT

Overview

Provides a collection of general-purpose utility functions and classes for file listing, natural sorting, HTML loading, path manipulation, cached file metadata lookups, topological sorting, and cross-platform folder opening.

Description

This module contains widely used helper functions and classes:

• natural_sort_key(s) - Generates a sort key that orders strings with embedded numbers naturally (e.g., "img2" before "img10").
• listfiles(dirname) - Lists files in a directory sorted naturally, excluding hidden files (dot-prefixed).
• html_path(filename) - Returns the absolute path to an HTML template file in the html/ directory.
• html(filename) - Reads and returns the contents of an HTML template file, returning empty string on error.
• walk_files(path, allowed_extensions) - Recursively walks a directory yielding file paths, optionally filtering by extensions and respecting the list_hidden_files option.
• ldm_print(*args, **kwargs) - Conditional print wrapper that suppresses output when hide_ldm_prints is enabled in options.
• truncate_path(target_path, base_path) - Returns a relative path if the target is under the base path, otherwise returns the absolute path.
• MassFileListerCachedDir - Caches file metadata (name, mtime, ctime) for a single directory using os.scandir for efficient repeated lookups.
• MassFileLister - Manages a collection of MassFileListerCachedDir instances, providing find(), exists(), mctime(), reset(), and update_file_entry() methods for fast batch file existence and timestamp checks.
• topological_sort(dependencies) - Performs topological sorting on a dependency dictionary, gracefully ignoring missing dependencies and cycles.
• open_folder(path) - Opens a folder in the OS file manager, supporting Windows, macOS, WSL2, and Linux (xdg-open).

Usage

Use these utilities throughout the codebase for natural sorting of file lists, efficient file metadata caching when scanning model directories, loading HTML templates, and performing safe cross-platform folder opening from the UI.

Code Reference

Source Location

• Repository: AUTOMATIC1111_Stable_diffusion_webui
• File: modules/util.py
• Lines: 1-213

Signature

def natural_sort_key(s: str, regex=re.compile('([0-9]+)')) -> list
def listfiles(dirname: str) -> list[str]
def html_path(filename: str) -> str
def html(filename: str) -> str
def walk_files(path: str, allowed_extensions: set = None) -> Iterator[str]
def ldm_print(*args, **kwargs) -> None
def truncate_path(target_path: str, base_path: str = cwd) -> str

class MassFileListerCachedDir:
    def __init__(self, dirname: str)
    def update_entry(self, filename: str) -> None

class MassFileLister:
    def __init__(self)
    def find(self, path: str) -> tuple | None
    def exists(self, path: str) -> bool
    def mctime(self, path: str) -> tuple[float, float]
    def reset(self) -> None
    def update_file_entry(self, path: str) -> None

def topological_sort(dependencies: dict) -> list
def open_folder(path: str) -> None

Import

from modules import util
# or
from modules.util import natural_sort_key, walk_files, MassFileLister, topological_sort

I/O Contract

Inputs

Name	Type	Required	Description
s	str	Yes	String to generate a natural sort key for.
dirname	str	Yes	Directory path for listfiles.
path	str	Yes	File or directory path for walk_files, truncate_path, MassFileLister.find, or open_folder.
allowed_extensions	set or None	No	Set of file extensions (with dot) to filter in walk_files; None means no filtering.
dependencies	dict	Yes	Mapping of names to lists of dependency names for topological_sort.

Outputs

Name	Type	Description
sort_key	list	Mixed list of strings and ints for natural sorting.
file_list	list[str]	Sorted list of file paths from listfiles.
file_path	str	Full path to HTML template from html_path.
html_content	str	Contents of an HTML template file from html.
file_iterator	Iterator[str]	Iterator of file paths from walk_files.
file_stats	tuple or None	Tuple of (name, mtime, ctime) or None from MassFileLister.find.
sorted_names	list	Topologically sorted list of names from topological_sort.

Usage Examples

from modules.util import natural_sort_key, MassFileLister, walk_files, topological_sort

# Natural sorting
names = ["img10.png", "img2.png", "img1.png"]
sorted_names = sorted(names, key=natural_sort_key)
# Result: ["img1.png", "img2.png", "img10.png"]

# Efficient file listing with caching
lister = MassFileLister()
if lister.exists("/models/Stable-diffusion/v1-5.safetensors"):
    mtime, ctime = lister.mctime("/models/Stable-diffusion/v1-5.safetensors")

# Walk model files
for f in walk_files("/models/Lora", allowed_extensions={".safetensors", ".pt"}):
    print(f)

# Topological sort for extension loading
deps = {"ext_a": ["ext_b"], "ext_b": [], "ext_c": ["ext_a"]}
order = topological_sort(deps)
# Result: ["ext_b", "ext_a", "ext_c"]

Related Pages

• Principle:AUTOMATIC1111_Stable_diffusion_webui_File_And_Path_Utility_Functions