Core Setup Functions

def setup(**attrs):
    """
    Configure and build a Python package.

    This is the main function that replaces distutils.setup() with enhanced
    functionality for modern Python packaging.

    Parameters:
    - name (str): Package name
    - version (str): Package version (e.g., '1.0.0')
    - description (str): Short one-line package description
    - long_description (str): Detailed package description (often README content)
    - long_description_content_type (str): Content type ('text/markdown', 'text/x-rst', etc.)
    - author (str): Package author name
    - author_email (str): Author email address
    - maintainer (str): Package maintainer name
    - maintainer_email (str): Maintainer email address
    - url (str): Package homepage URL
    - download_url (str): Package download URL
    - project_urls (dict): Additional project URLs ('Bug Tracker', 'Documentation', etc.)
    - packages (list): List of packages to include (use find_packages() for auto-discovery)
    - py_modules (list): List of individual Python modules to include
    - install_requires (list): List of required dependencies
    - extras_require (dict): Optional dependencies grouped by feature
    - python_requires (str): Python version requirements (e.g., '>=3.8')
    - entry_points (dict): Console scripts and plugin entry points
    - console_scripts (list): Deprecated, use entry_points instead
    - scripts (list): Executable script files
    - classifiers (list): PyPI trove classifiers
    - keywords (str or list): Package keywords for search
    - license (str): License name
    - license_file (str): License file path
    - license_files (list): Multiple license file paths
    - platforms (list): Supported platforms
    - package_dir (dict): Package directory mapping
    - package_data (dict): Package data files to include
    - data_files (list): Data files to install outside package
    - include_package_data (bool): Include files specified in MANIFEST.in
    - exclude_package_data (dict): Package data files to exclude
    - zip_safe (bool): Whether package can be run from a zip file
    - ext_modules (list): C/C++ extension modules (Extension objects)
    - libraries (list): C/C++ libraries to build (Library objects)
    - cmdclass (dict): Custom command classes
    - distclass (class): Custom Distribution class
    - options (dict): Options for specific commands
    - setup_requires (list): Dependencies needed during setup (deprecated)
    - dependency_links (list): Additional dependency URLs (deprecated)
    - namespace_packages (list): Namespace packages (deprecated, use PEP 420)
    - test_suite (str): Test discovery specification (deprecated)
    - tests_require (list): Test dependencies (deprecated, use extras_require)

    Returns:
    None (configures package for building/installation)

    Raises:
    SetupError: If configuration is invalid
    DistutilsError: If distutils operations fail
    """

def find_packages(where='.', exclude=(), include=('*',)):
    """
    Automatically discover Python packages in a directory tree.

    Recursively searches for Python packages (directories containing __init__.py)
    and returns a list of package names suitable for the setup() 'packages' parameter.

    Parameters:
    - where (str): Root directory to search for packages (default: '.')
    - exclude (tuple): Glob patterns for package names to exclude (default: ())
    - include (tuple): Glob patterns for package names to include (default: ('*',))

    Returns:
    list: List of discovered package names (e.g., ['mypackage', 'mypackage.subpackage'])

    Example:
    packages = find_packages(exclude=['tests*', 'docs*'])
    packages = find_packages(where='src')
    packages = find_packages(include=['mypackage*'])
    """

def find_namespace_packages(where='.', exclude=(), include=('*',)):
    """
    Discover PEP 420 implicit namespace packages.

    Similar to find_packages() but finds implicit namespace packages
    (directories without __init__.py that should be treated as packages).

    Parameters:
    - where (str): Root directory to search for packages (default: '.')
    - exclude (tuple): Glob patterns for package names to exclude (default: ())
    - include (tuple): Glob patterns for package names to include (default: ('*',))

    Returns:
    list: List of discovered namespace package names

    Example:
    namespace_packages = find_namespace_packages()
    namespace_packages = find_namespace_packages(where='src', exclude=['tests*'])
    """

def findall(dir='.'):
    """
    Find all files under a directory, recursively.

    Parameters:
    - dir (str): Directory to search (default: current directory)

    Returns:
    list: List of file paths relative to the search directory

    Example:
    all_files = findall('src')
    data_files = findall('data')
    """

from setuptools import setup, find_packages

setup(
    name="my-awesome-package",
    version="1.2.3",
    description="An awesome Python package",
    long_description=open("README.md").read(),
    long_description_content_type="text/markdown",
    author="Your Name",
    author_email="you@example.com",
    url="https://github.com/yourusername/my-awesome-package",
    packages=find_packages(),
    python_requires=">=3.8",
    install_requires=[
        "requests>=2.25.0",
        "click>=8.0.0",
    ],
    classifiers=[
        "Development Status :: 4 - Beta",
        "Intended Audience :: Developers",
        "License :: OSI Approved :: MIT License",
        "Programming Language :: Python :: 3",
        "Programming Language :: Python :: 3.8",
        "Programming Language :: Python :: 3.9",
        "Programming Language :: Python :: 3.10",
        "Programming Language :: Python :: 3.11",
        "Programming Language :: Python :: 3.12",
    ],
)

from setuptools import setup, find_packages

# Find packages but exclude test and documentation packages
packages = find_packages(exclude=['tests*', 'docs*', '*.tests', '*.tests.*'])

# Find packages in a specific source directory
src_packages = find_packages(where='src')

# Find packages with specific include patterns
specific_packages = find_packages(include=['mypackage*'])

setup(
    name="my-package",
    packages=packages,
    # ... other configuration
)

from setuptools import setup, find_packages

setup(
    name="my-cli-tool",
    packages=find_packages(),
    entry_points={
        'console_scripts': [
            'my-command=my_package.cli:main',
            'my-tool=my_package.tools:run',
        ],
        'my_package.plugins': [
            'plugin1=my_package.plugins:Plugin1',
            'plugin2=my_package.plugins:Plugin2',
        ],
    },
)

from setuptools import setup, find_packages, Extension

ext_modules = [
    Extension(
        'my_package.fast_module',
        sources=['src/fast_module.c'],
        include_dirs=['src/include'],
        libraries=['m'],  # Link against math library
    )
]

setup(
    name="my-package-with-c",
    packages=find_packages(),
    ext_modules=ext_modules,
    zip_safe=False,  # C extensions can't be run from zip
)

from setuptools import setup, find_namespace_packages

# For PEP 420 namespace packages (no __init__.py files)
namespace_packages = find_namespace_packages(include=['mycompany.*'])

setup(
    name="mycompany-plugin",
    packages=namespace_packages,
    # ... other configuration
)