Constants and Utilities

def SKBUILD_DIR() -> str:
    """
    Return top-level directory for build artifacts (_skbuild).
    
    This directory contains all scikit-build generated files including
    CMake build directory, installation directory, and configuration files.
    
    Returns:
    Path to _skbuild directory
    """

def CMAKE_BUILD_DIR() -> str:
    """
    Return CMake build directory path.
    
    Directory where CMake performs the actual build process,
    containing generated makefiles, object files, and build artifacts.
    
    Returns:
    Path to CMake build directory within _skbuild
    """

def CMAKE_INSTALL_DIR() -> str:
    """
    Return CMake installation directory path.
    
    Directory where CMake installs built artifacts before they are
    copied to their final package locations.
    
    Returns:
    Path to CMake installation directory within _skbuild
    """

def CMAKE_SPEC_FILE() -> str:
    """
    Return path to CMake specification file.
    
    File that stores CMake version and configuration information
    from the build process for reuse in subsequent builds.
    
    Returns:
    Path to cmake-spec.json file
    """

def SETUPTOOLS_INSTALL_DIR() -> str:
    """
    Return setuptools installation directory path.
    
    Directory where setuptools installs Python files and packages
    during the build process.
    
    Returns:
    Path to setuptools installation directory within _skbuild
    """

def SKBUILD_MARKER_FILE() -> str:
    """
    Return path to scikit-build marker file.
    
    Marker file used by generate_source_manifest command to track
    scikit-build generated files.
    
    Returns:
    Path to marker file
    """

def skbuild_plat_name() -> str:
    """
    Get platform name formatted for scikit-build.
    
    Returns platform name in the format:
    <operating_system>[-<operating_system_version>]-<machine_architecture>
    
    Examples:
    - linux-x86_64
    - win-amd64  
    - macosx-10.15-x86_64
    
    Returns:
    Formatted platform name string
    """

def set_skbuild_plat_name(plat_name: str) -> None:
    """
    Set platform name for scikit-build operations.
    
    Override the automatically detected platform name with a custom
    value for cross-compilation or specific platform targeting.
    
    Parameters:
    - plat_name: Platform name string to use
    """

def get_cmake_version(cmake_path: os.PathLike[str] | str) -> Version:
    """
    Extract CMake version from executable path.
    
    Executes the CMake binary to determine its version and returns
    a parsed Version object for comparison and validation.
    
    Parameters:
    - cmake_path: Path to cmake executable
    
    Returns:
    packaging.version.Version object representing CMake version
    
    Raises:
    SKBuildError: If cmake executable not found or version extraction fails
    """

def mkdir_p(path: str) -> None:
    """
    Create directory and parent directories if they don't exist.
    
    Equivalent to 'mkdir -p' command - creates the target directory
    and any missing parent directories in the path.
    
    Parameters:
    - path: Directory path to create
    
    Raises:
    OSError: If directory creation fails due to permissions or other errors
    """

def to_platform_path(path: OptStr) -> OptStr:
    """
    Convert path separators to platform-specific format.
    
    Converts all path separators in the given path to the format
    appropriate for the current operating system (os.sep).
    
    Parameters:
    - path: Path string to convert, or None
    
    Returns:
    Path with platform-specific separators, or None if input was None
    """

def to_unix_path(path: OptStr) -> OptStr:
    """
    Convert path separators to forward slashes.
    
    Converts all path separators to forward slashes ('/') regardless
    of the current platform, useful for CMake paths and cross-platform scripts.
    
    Parameters:
    - path: Path string to convert, or None
    
    Returns:
    Path with forward slash separators, or None if input was None
    """

class Distribution(NamedTuple):
    """Distribution information container."""
    script_name: str

class push_dir:
    """
    Context manager for temporarily changing directory.
    
    Changes to the specified directory for the duration of the
    context and restores the original directory when exiting.
    """
    def __init__(self, new_dir: str) -> None: ...
    def __enter__(self) -> str: ...
    def __exit__(self, exc_type, exc_val, exc_tb) -> None: ...

class PythonModuleFinder:
    """
    Utility class for finding Python modules in packages.
    
    Extends distutils build_py functionality to locate Python
    modules within package structures for installation.
    """
    def find_all_modules(self) -> list[tuple[str, str, str]]: ...
    def find_modules_in_package(self, package: str) -> list[tuple[str, str, str]]: ...

def parse_manifestin(template: str) -> list[str]:
    """
    Parse MANIFEST.in template files and return file patterns.
    
    Processes MANIFEST.in template syntax and returns a list of
    file patterns that match the template rules.
    
    Parameters:
    - template: MANIFEST.in template content string
    
    Returns:
    List of file pattern strings derived from template
    
    Raises:
    ValueError: If template syntax is invalid
    """

def distribution_hide_listing(
    distribution: setuptools._distutils.dist.Distribution | Distribution
) -> Iterator[bool | int]:
    """
    Context manager to temporarily suppress distribution listing output.
    
    Temporarily hides verbose output from setuptools distribution
    operations to reduce noise during the build process.
    
    Parameters:
    - distribution: Setuptools distribution object
    
    Yields:
    Previous listing state value
    """

CMAKE_DEFAULT_EXECUTABLE: str = "cmake"
"""Default CMake executable name for platform detection and execution."""

from skbuild.constants import SKBUILD_DIR, CMAKE_BUILD_DIR, CMAKE_INSTALL_DIR
from skbuild.utils import mkdir_p, push_dir
import os

# Get standard build directories
skbuild_dir = SKBUILD_DIR()
build_dir = CMAKE_BUILD_DIR()
install_dir = CMAKE_INSTALL_DIR()

print(f"Build artifacts in: {skbuild_dir}")
print(f"CMake build in: {build_dir}")
print(f"Installation in: {install_dir}")

# Create directories if needed
mkdir_p(build_dir)
mkdir_p(install_dir)

# Change directory temporarily
with push_dir(build_dir):
    print(f"Now in: {os.getcwd()}")
    # Perform build operations
print(f"Back in: {os.getcwd()}")

from skbuild.constants import skbuild_plat_name, set_skbuild_plat_name

# Get current platform
current_platform = skbuild_plat_name()
print(f"Current platform: {current_platform}")

# Override for cross-compilation
set_skbuild_plat_name("linux-aarch64")
cross_platform = skbuild_plat_name()
print(f"Cross-compile platform: {cross_platform}")

from skbuild.utils import to_platform_path, to_unix_path

# Convert paths for current platform
unix_path = "src/native/lib/module.cpp"
platform_path = to_platform_path(unix_path)
print(f"Platform path: {platform_path}")

# Convert to Unix format for CMake
windows_path = r"src\native\lib\module.cpp"
unix_format = to_unix_path(windows_path)
print(f"Unix path: {unix_format}")

from skbuild.constants import get_cmake_version, CMAKE_DEFAULT_EXECUTABLE
from packaging.version import Version

# Check CMake version
cmake_version = get_cmake_version(CMAKE_DEFAULT_EXECUTABLE)
print(f"CMake version: {cmake_version}")

# Version comparison
min_version = Version("3.15.0")
if cmake_version >= min_version:
    print("CMake version is sufficient")
else:
    print(f"CMake {min_version} or later required")

from skbuild.utils import PythonModuleFinder

# Find Python modules in package
finder = PythonModuleFinder()
modules = finder.find_all_modules()

for package, module, file_path in modules:
    print(f"Package: {package}, Module: {module}, File: {file_path}")