Utilities

def unpack_archive(filename, extract_dir='.', drivers=None):
    """
    Extract various archive formats to a directory.

    Automatically detects archive format and extracts using the
    appropriate method. Supports zip, tar, tar.gz, tar.bz2, and other formats.

    Parameters:
    - filename (str): Path to archive file to extract
    - extract_dir (str): Directory to extract files to (default: current directory)
    - drivers (list, optional): List of extraction drivers to try

    Returns:
    None

    Raises:
    UnpackError: If extraction fails
    """

def unpack_zipfile(filename, extract_dir='.'):
    """
    Extract ZIP archive to a directory.

    Specialized function for extracting ZIP files with proper
    handling of file permissions and directory structure.

    Parameters:
    - filename (str): Path to ZIP file
    - extract_dir (str): Directory to extract to (default: current directory)

    Returns:
    None

    Raises:
    UnpackError: If ZIP extraction fails
    """

def unpack_tarfile(filename, extract_dir='.'):
    """
    Extract TAR archive (including compressed variants) to a directory.

    Handles tar, tar.gz, tar.bz2, and tar.xz files with proper
    permission and timestamp preservation.

    Parameters:
    - filename (str): Path to TAR file
    - extract_dir (str): Directory to extract to (default: current directory)

    Returns:
    None

    Raises:
    UnpackError: If TAR extraction fails
    """

def default_filter(src, dst):
    """
    Default filter function for archive extraction.

    Provides security filtering for archive extraction to prevent
    directory traversal attacks and other security issues.

    Parameters:
    - src (str): Source path within archive
    - dst (str): Destination path for extraction

    Returns:
    str: Filtered destination path, or None to skip file

    This function is used internally by the unpack functions to
    ensure safe extraction by filtering out dangerous paths.
    """

def unpack_directory(filename, extract_dir='.'):
    """
    Process a directory as if it were an archive.
    
    Simply copies directory contents, used internally by unpack_archive
    when the "archive" is actually a directory.
    
    Parameters:
    - filename (str): Path to directory to process
    - extract_dir (str): Directory to copy contents to
    
    Returns:
    None
    """

def newer(source, target):
    """
    Check if source file is newer than target file.
    
    Parameters:
    - source (str): Path to source file
    - target (str): Path to target file
    
    Returns:
    bool: True if source is newer than target or target doesn't exist
    """

def newer_pairwise(sources_and_targets):
    """
    Check if each source is newer than its corresponding target.
    
    Parameters:
    - sources_and_targets (list): List of (source, target) tuples
    
    Returns:
    list[bool]: List of boolean results for each pair
    """

def newer_group(sources, target, missing='error'):
    """
    Check if any source file is newer than target.
    
    Parameters:
    - sources (list): List of source file paths
    - target (str): Path to target file
    - missing (str): How to handle missing source files ('error', 'ignore', 'newer')
    
    Returns:
    bool: True if any source is newer than target
    """

def newer_pairwise_group(sources_and_targets):
    """
    Check if any source is newer than any target in groups.
    
    Parameters:
    - sources_and_targets (list): List of (sources_list, targets_list) tuples
    
    Returns:
    list[bool]: List of boolean results for each group
    """

def glob(pathname, *, root_dir=None, dir_fd=None, recursive=False):
    """
    Find pathnames matching a shell-style pattern.
    
    Enhanced version of standard glob.glob with setuptools-specific behavior.
    
    Parameters:
    - pathname (str): Pattern to match (supports *, ?, [seq], **/)
    - root_dir (str, optional): Root directory for relative patterns
    - dir_fd (int, optional): File descriptor for directory
    - recursive (bool): Whether ** matches directories recursively
    
    Returns:
    list[str]: List of matching paths
    """

def iglob(pathname, *, root_dir=None, dir_fd=None, recursive=False):
    """
    Iterator version of glob().
    
    Parameters: Same as glob()
    
    Returns:
    Iterator[str]: Iterator over matching paths
    """

def escape(pathname):
    """
    Escape special characters in pathname for literal matching.
    
    Parameters:
    - pathname (str): Path that may contain special glob characters
    
    Returns:
    str: Escaped pathname for literal matching
    """

def parse_configuration(filepath):
    """
    Parse setup.cfg configuration file.
    
    DEPRECATED: Use pyproject.toml instead of setup.cfg for new projects.
    
    Parameters:
    - filepath (str): Path to setup.cfg file
    
    Returns:
    dict: Parsed configuration data
    
    Raises:
    DistutilsFileError: If configuration file cannot be read
    """

def read_configuration(filepath, find_others=False, ignore_option_errors=False):
    """
    Read and parse setup.cfg and other configuration files.
    
    DEPRECATED: Use pyproject.toml instead of setup.cfg for new projects.
    
    Parameters:
    - filepath (str): Path to main configuration file
    - find_others (bool): Whether to find and parse related config files
    - ignore_option_errors (bool): Whether to ignore invalid options
    
    Returns:
    dict: Combined configuration from all sources
    """

class sic(str):
    """
    String class for literal treatment.

    A string subclass that signals to setuptools that the string
    should be treated literally without any special processing or
    interpretation. Used internally for certain setuptools operations
    where exact string preservation is required.

    Example:
    literal_string = sic("some_literal_value")
    """

    def __new__(cls, s=''):
        """
        Create new sic string instance.

        Parameters:
        - s (str): String value to wrap

        Returns:
        sic: New sic string instance
        """

__version__: str
"""
Current setuptools version string.

Example: "68.2.2"
This can be used to check setuptools version at runtime
and implement version-specific behavior.
"""

class PackageFinder:
    """
    Standard package discovery class.

    Provides the underlying implementation for find_packages()
    with methods for discovering regular Python packages.
    """

    @staticmethod
    def find(where='.', exclude=(), include=('*',)):
        """
        Find Python packages in directory tree.

        Parameters:
        - where (str): Root directory to search
        - exclude (tuple): Patterns to exclude
        - include (tuple): Patterns to include

        Returns:
        list: List of package names
        """

class PEP420PackageFinder:
    """
    PEP 420 namespace package discovery class.

    Provides the underlying implementation for find_namespace_packages()
    with methods for discovering implicit namespace packages.
    """

    @staticmethod
    def find(where='.', exclude=(), include=('*',)):
        """
        Find PEP 420 namespace packages in directory tree.

        Parameters:
        - where (str): Root directory to search
        - exclude (tuple): Patterns to exclude
        - include (tuple): Patterns to include

        Returns:
        list: List of namespace package names
        """

class Require:
    """
    Represents a prerequisite for building or installing a distribution.

    This class encapsulates information about required packages or
    modules and provides methods to check their availability and versions.

    Attributes:
    - name (str): Requirement name
    - requested_version (str): Requested version specification
    - module_name (str): Python module name to check
    - homepage (str): Homepage URL for the requirement
    - attribute (str): Module attribute to check for version
    - format (str): Version format specification
    """

    def __init__(self, name, requested_version, module_name, homepage='', 
                 attribute=None, format=None):
        """
        Initialize requirement specification.

        Parameters:
        - name (str): Human-readable name of requirement
        - requested_version (str): Version specification (e.g., ">=1.0")
        - module_name (str): Python module name to import and check
        - homepage (str): URL for requirement homepage
        - attribute (str): Module attribute containing version info
        - format (str): Format string for version extraction
        """

    def version_ok(self, version):
        """
        Check if a version satisfies this requirement.

        Parameters:
        - version (str): Version string to check

        Returns:
        bool: True if version satisfies requirement
        """

    def get_version(self, paths=None, default='unknown'):
        """
        Get version of installed requirement.

        Parameters:
        - paths (list, optional): Paths to search for module
        - default (str): Default version if not found

        Returns:
        str: Version string of installed requirement
        """

    def is_present(self, paths=None):
        """
        Check if requirement is present (importable).

        Parameters:
        - paths (list, optional): Paths to search for module

        Returns:
        bool: True if requirement is present
        """

    def is_current(self, paths=None):
        """
        Check if requirement is present and version is current.

        Parameters:
        - paths (list, optional): Paths to search for module

        Returns:
        bool: True if requirement is present and satisfies version
        """

from setuptools.archive_util import unpack_archive, unpack_zipfile, unpack_tarfile

# Extract any supported archive format
unpack_archive('package-1.0.tar.gz', 'extracted/')

# Extract specific formats
unpack_zipfile('package-1.0.zip', 'build/zip_contents/')
unpack_tarfile('package-1.0.tar.gz', 'build/tar_contents/')

# Extract to current directory
unpack_archive('dependency.tar.bz2')

from setuptools.discovery import PackageFinder, PEP420PackageFinder

# Use package finders directly
finder = PackageFinder()
packages = finder.find(where='src', exclude=['tests*'])

namespace_finder = PEP420PackageFinder()
ns_packages = namespace_finder.find(where='src', include=['company.*'])

print(f"Regular packages: {packages}")
print(f"Namespace packages: {ns_packages}")

from setuptools.depends import Require

# Define a requirement
numpy_req = Require(
    name='NumPy',
    requested_version='>=1.19.0',
    module_name='numpy',
    homepage='https://numpy.org',
    attribute='__version__'
)

# Check if requirement is satisfied
if numpy_req.is_present():
    version = numpy_req.get_version()
    if numpy_req.version_ok(version):
        print(f"NumPy {version} is available and satisfies requirement")
    else:
        print(f"NumPy {version} is available but doesn't satisfy requirement")
else:
    print("NumPy is not available")

# Check current status
if numpy_req.is_current():
    print("NumPy requirement is fully satisfied")
else:
    print("NumPy requirement is not satisfied")

import setuptools

# Check setuptools version
print(f"Using setuptools version: {setuptools.__version__}")

# Version-specific behavior
from packaging import version
if version.parse(setuptools.__version__) >= version.parse("61.0"):
    print("Using modern setuptools with pyproject.toml support")
    # Use modern features
else:
    print("Using legacy setuptools")
    # Fall back to legacy behavior

from setuptools import sic

# Create literal strings for special setuptools processing
literal_value = sic("--global-option")
processed_value = "processed_value"

# The sic class signals that the string should not be modified
# by setuptools internal processing
options = [literal_value, processed_value]

from setuptools.archive_util import unpack_archive, default_filter
import os

def safe_extract_with_filtering(archive_path, extract_dir):
    """Safely extract archive with custom filtering."""
    
    def custom_filter(src, dst):
        """Custom filter to prevent certain extractions."""
        # Use default security filtering
        filtered_dst = default_filter(src, dst)
        if filtered_dst is None:
            return None
            
        # Additional custom filtering
        if src.startswith('dangerous/'):
            print(f"Skipping dangerous path: {src}")
            return None
            
        return filtered_dst
    
    # Extract with custom filtering
    os.makedirs(extract_dir, exist_ok=True)
    unpack_archive(archive_path, extract_dir)
    print(f"Safely extracted {archive_path} to {extract_dir}")

from setuptools import setup, Command
from setuptools.archive_util import unpack_archive
import tempfile
import shutil

class ExtractDataCommand(Command):
    """Custom command to extract data archives during build."""
    
    description = 'Extract data archives'
    user_options = [
        ('data-archive=', 'd', 'Path to data archive'),
        ('extract-dir=', 'e', 'Directory to extract to'),
    ]

    def initialize_options(self):
        self.data_archive = None
        self.extract_dir = 'data'

    def finalize_options(self):
        if self.data_archive is None:
            raise ValueError("data-archive option is required")

    def run(self):
        """Extract data archive during build."""
        self.announce(f'Extracting {self.data_archive} to {self.extract_dir}')
        
        # Create extraction directory
        os.makedirs(self.extract_dir, exist_ok=True)
        
        # Extract archive
        unpack_archive(self.data_archive, self.extract_dir)
        
        self.announce(f'Extraction completed')

setup(
    name='my-package',
    cmdclass={
        'extract_data': ExtractDataCommand,
    },
)

from setuptools import setup, find_packages
from setuptools.discovery import PackageFinder
import os

def find_packages_with_debug():
    """Find packages with debugging information."""
    finder = PackageFinder()
    
    # Find packages with detailed logging
    print("Searching for packages...")
    packages = finder.find(where='src')
    
    for package in packages:
        package_path = os.path.join('src', package.replace('.', os.sep))
        print(f"Found package: {package} at {package_path}")
    
    return packages

# Use in setup
setup(
    name='my-package',
    packages=find_packages_with_debug(),
)