Core Python API

class Project:
    """Main project implementation with 37+ configurable options."""
    
    def build(self):
        """Build the project in-situ."""
        pass
    
    def build_sdist(self, sdist_directory):
        """
        Build source distribution.
        
        Args:
            sdist_directory (str): Target directory for source distribution
            
        Returns:
            str: Path to created source distribution
        """
        pass
    
    def build_wheel(self, wheel_directory):
        """
        Build wheel distribution.
        
        Args:
            wheel_directory (str): Target directory for wheel
            
        Returns:
            str: Path to created wheel
        """
        pass
    
    def install(self):
        """Build and install the project."""
        pass

class AbstractProject:
    """Base class for projects containing bindings."""
    
    @classmethod
    def bootstrap(cls, tool, tool_description=''):
        """
        Bootstrap project from configuration.
        
        Args:
            tool (str): Tool name for specialized bootstrap (required)
            tool_description (str, optional): Description of the tool
            
        Returns:
            AbstractProject: Configured project instance
        """
        pass
    
    def build(self):
        """Build the project."""
        pass
    
    def build_sdist(self, sdist_directory):
        """Build source distribution."""
        pass
    
    def build_wheel(self, wheel_directory):
        """Build wheel distribution."""
        pass
    
    def install(self):
        """Install the project."""
        pass
    
    def import_callable(self, callable_name, expected_type):
        """
        Import callable from module.
        
        Args:
            callable_name (str): Name of callable to import
            expected_type (type): Expected type of the callable
            
        Returns:
            callable: Imported callable
        """
        pass
    
    def setup(self):
        """Setup project configuration."""
        pass

class AbstractBuilder:
    """Base class for project builders."""
    
    def build(self):
        """Build the project."""
        pass
    
    def build_sdist(self):
        """Build source distribution."""
        pass
    
    def build_wheel(self):
        """Build wheel distribution."""
        pass
    
    def install(self):
        """Install the project."""
        pass

class Bindings:
    """Encapsulates a module's bindings with 18+ configurable options."""
    
    def generate(self):
        """
        Generate binding code from .sip specification files.
        
        Processes specification files and creates optimized C/C++ source code
        for compilation into Python extension modules.
        """
        pass
    
    def is_buildable(self):
        """
        Check if bindings can be built.
        
        Returns:
            bool: True if bindings are buildable, False otherwise
        """
        pass
    
    def verify_configuration(self, tool):
        """
        Verify configuration validity.
        
        Args:
            tool (str): Tool name for context-specific validation
        
        Raises:
            UserException: If configuration is invalid
        """
        pass

class Builder:
    """Default base implementation of project builder."""
    
    def build(self):
        """
        Build the project.
        
        Handles bindings generation, script creation, and build management.
        """
        pass
    
    def install(self):
        """Install the built project."""
        pass

class DistutilsBuilder:
    """Distutils-based implementation of Builder."""
    
    def build(self):
        """
        Build using distutils.
        
        Note: Cannot build executables or static modules.
        """
        pass
    
    def install(self):
        """Install using distutils."""
        pass

class Buildable:
    """Base class for buildable components."""
    def build(self): ...
    def install(self): ...
    def is_buildable(self): ...

class BuildableBindings(Buildable):
    """Builds extension modules for bindings from .sip files."""
    def generate(self): ...
    def verify_configuration(self, tool): ...

class BuildableExecutable(Buildable):
    """Builds standalone executables."""
    def get_executable_name(self): ...

class BuildableFromSources(Buildable):
    """Base class for components built from C/C++ source files."""
    def get_sources(self): ...
    def get_include_dirs(self): ...
    def get_libraries(self): ...

class BuildableModule(BuildableFromSources):
    """Builds Python extension modules from C/C++ sources."""
    def get_module_name(self): ...

class Installable:
    """Manages file installation to target directories."""
    
    def install(self):
        """
        Install files to target locations.
        
        Copies files from build directory to installation directory
        with proper permissions and directory structure.
        """
        pass
    
    def get_full_target_dir(self):
        """
        Get full target directory path.
        
        Returns:
            str: Complete path to target directory
        """
        pass

class UserException(Exception):
    """Base exception for user-friendly errors."""
    pass

class UserFileException(UserException):
    """Base class for file-related user errors."""
    pass

class UserParseException(UserException):
    """Exception for parsing errors."""
    pass

class PyProjectException(UserFileException):
    """Exception related to pyproject.toml files."""
    pass

class PyProjectOptionException(PyProjectException):
    """Configuration option errors in pyproject.toml."""
    pass

class PyProjectUndefinedOptionException(PyProjectOptionException):
    """Exception for undefined required options in pyproject.toml."""
    pass

def handle_exception(exception):
    """
    Standard exception handler for SIP tools.
    
    Args:
        exception (Exception): Exception to handle
        
    Provides user-friendly error messages and appropriate exit codes.
    """
    pass

SIP_VERSION: int
"""Numeric version identifier."""

SIP_VERSION_STR: str
"""String version identifier (e.g., '5.5.0')."""

from sipbuild import Project, Bindings

# Create and configure a project
project = Project()

# Add bindings configuration
bindings = Bindings(
    sip_files=['mymodule.sip'],
    include_dirs=['/usr/include/mylib'],
    libraries=['mylib'],
    library_dirs=['/usr/lib']
)

# Verify configuration
bindings.verify_configuration()

# Generate and build
if bindings.is_buildable():
    bindings.generate()
    project.build()

from sipbuild import AbstractProject, AbstractBuilder

class CustomProject(AbstractProject):
    def setup(self):
        # Custom setup logic
        super().setup()

class CustomBuilder(AbstractBuilder):
    def build(self):
        # Custom build logic
        super().build()

# Bootstrap with custom classes
project = CustomProject.bootstrap()
project.build()