add comments on native_libs.py

"""Runtime hints for native libraries that Python wheels load with ctypes.

Import this module before importing libraries such as pyvips. It only changes

process-local environment variables and currently exists for macOS/Homebrew

installations where the dynamic loader may not see libvips automatically.

"""

import ctypes.util

import os

import sys

        paths = existing.split(os.pathsep)

        if path_value in paths:

            return

        # Prefer paths discovered from the active executable over broader defaults.

        os.environ[name] = os.pathsep.join([path_value, *paths])

        return

    os.environ[name] = path_value

    prefixes: list[Path] = []

    vips_executable = which("vips")

    if vips_executable:

        # The vips CLI is the best signal for the Homebrew prefix actually in use.

        prefixes.append(Path(vips_executable).resolve().parent.parent)

    prefixes.extend([Path("/opt/homebrew"), Path("/usr/local")])

    lib_dirs: list[Path] = []

    for prefix in prefixes:

        lib_dir = prefix / "lib"

        # libvips.42 is the ABI pyvips expects; do not add unrelated library dirs.

        if lib_dir not in lib_dirs and (lib_dir / "libvips.42.dylib").exists():

            lib_dirs.append(lib_dir)

    return lib_dirs

    if sys.platform != "darwin" or ctypes.util.find_library("vips"):

        return

    for lib_dir in _homebrew_library_dirs():

        # Set both variables: subprocesses and ctypes lookups do not always agree.

        _prepend_env_path("DYLD_LIBRARY_PATH", lib_dir)

        _prepend_env_path("DYLD_FALLBACK_LIBRARY_PATH", lib_dir)

# Imported for its side effect by RPC and resource views before pyvips is used.

configure_macos_homebrew_library_paths()