Typing Stubs for setuptools

Warnings

• breaking The `pkg_resources` module's type stubs are no longer included in `types-setuptools` for `setuptools` versions 71.1 and newer. This is because `setuptools` itself now ships with inline type annotations for `pkg_resources`. If you are using an older version of `setuptools` (<71.1) and require types for `pkg_resources`, `types-setuptools` will not provide them.
  Fix: Ensure you are using `setuptools >= 71.1` to get inline types for `pkg_resources`. If you must use an older `setuptools` version, you may need to provide your own stubs for `pkg_resources` or disable type checking for that module.
• gotcha Recent `setuptools` versions (e.g., 78.0.1 and later) introduced strict enforcement of naming conventions in `setup.cfg` files, disallowing dash-separated keys (e.g., `description-file`) in favor of underscore-separated ones (e.g., `description_file`). While this is a change in `setuptools` itself, `types-setuptools` reflects the current API. Using outdated `setup.cfg` syntax with newer `setuptools` and `types-setuptools` can lead to type checker errors or build failures.
  Fix: Update your `setup.cfg` files to use underscore-separated keys as required by modern `setuptools`. Refer to the `setuptools` documentation for the correct syntax. Pinning `setuptools` to an older version (e.g., `setuptools<78`) is a temporary workaround.
• deprecated The `setup.py develop` command and other direct `setup.py` invocations are deprecated in `setuptools` and will be removed. While `types-setuptools` provides stubs for these legacy APIs for compatibility, relying on them is discouraged. Type checkers may flag usage of these deprecated features based on the provided stubs.
  Fix: Migrate your project to use a `pyproject.toml` file with PEP 517/621 compatible build backends and frontends (e.g., `pip` with `setuptools.build_meta`). Avoid direct execution of `setup.py`.

Install

• pip install types-setuptools Install types-setuptools
• pip install 'setuptools<71.1' types-setuptools # For older setuptools versions needing pkg_resources types Install with older setuptools (if pkg_resources types are needed)

Imports

• setup

  from setuptools import setup

  types-setuptools provides type hints for this and other setuptools symbols.
• find_packages

  from setuptools import find_packages

  types-setuptools provides type hints for this and other setuptools symbols.

Quickstart

To leverage `types-setuptools`, simply install it in your project's environment alongside `setuptools` and your chosen type checker (e.g., MyPy, Pyright). The type checker will automatically discover and apply the provided stubs to your code that uses `setuptools` APIs, allowing for static analysis and early detection of type-related issues in your packaging configuration or custom build scripts. The example demonstrates a minimal `pyproject.toml` and a Python module using `setuptools` imports, highlighting how a type checker benefits from the stubs. Note that `setup()` is rarely called directly in modern `setuptools` workflows.

import subprocess
import sys

# Create a dummy pyproject.toml for setuptools
with open('pyproject.toml', 'w') as f:
    f.write('''
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my_package"
version = "0.1.0"
description = "A test package"
requires-python = ">=3.10"

[project.optional-dependencies]
dev = ["mypy", "types-setuptools"]
''')

# Create a dummy setup.py (optional, for demonstrating basic setup function)
with open('setup.py', 'w') as f:
    f.write('''
from setuptools import setup, find_packages

setup(
    name='my_package',
    version='0.1.0',
    packages=find_packages(where='src'),
    package_dir={'': 'src'},
)
''')

# Create a simple module for type checking
import os
os.makedirs('src', exist_ok=True)
with open('src/my_module.py', 'w') as f:
    f.write('''
from setuptools import setup # type: ignore

def build_package(name: str, version: str) -> None:
    # In a real scenario, 'setup' would be called via build tools, 
    # but here we use it to show type checking potential. 
    # 'setup' itself is not typically called directly in modern builds.
    print(f"Building {name}-{version}")

# Example of using setuptools types indirectly via a hypothetical build function
build_package("my_app", "1.0.0")
''')

# Try to run mypy (assuming it's installed in the environment)
print("\n--- Running MyPy without types-setuptools (if not in dev deps) ---")
try:
    # This assumes mypy is available. If not, this part will fail but quickstart still illustrates intent.
    subprocess.run([sys.executable, '-m', 'pip', 'install', 'mypy'], check=True, capture_output=True)
    subprocess.run([sys.executable, '-m', 'mypy', '--ignore-missing-imports', 'src/my_module.py'], check=True, capture_output=True)
    print("MyPy ran successfully (ignoring missing imports for setuptools).")
except subprocess.CalledProcessError as e:
    print(f"MyPy failed: {e.stderr.decode()}")
except FileNotFoundError:
    print("MyPy not found. Please install it with 'pip install mypy'.")

print("\n--- To fully leverage types-setuptools, ensure it's installed alongside setuptools and your type checker is configured. ---")
print("e.g. pip install setuptools types-setuptools mypy")