Typing Stubs for pkg_resources

0.1.3 · active · verified Tue Apr 14

This library provides static type checking stubs for the `pkg_resources` module, which is primarily distributed as part of `setuptools`. It enables type checkers like MyPy and pyright to analyze code using `pkg_resources` for package metadata and resource management. While `pkg_resources` itself is considered a legacy API, these stubs are actively maintained as part of the `typeshed` project to support existing Python codebases. New versions are released periodically as stub definitions are updated or improved.

Warnings

gotcha The `pkg_resources` module, for which these stubs are provided, is considered a legacy API. For new Python projects (especially Python 3.8+), it's highly recommended to use `importlib.metadata` for package metadata access. For older Python versions, `setuptools.metadata` offers a more modern alternative within the setuptools ecosystem.
Fix: For new projects, prefer `importlib.metadata` (Python 3.8+) or `setuptools.metadata`. Only use `types-pkg-resources` if you are maintaining an existing codebase that relies on `pkg_resources`.
gotcha Type stubs (`types-pkg-resources`) do not provide any runtime functionality. They are solely for static analysis by type checkers. Your project must have the actual `pkg_resources` module (typically bundled with `setuptools`) installed to run the code at runtime.
Fix: Ensure `setuptools` is installed in your runtime environment alongside `types-pkg-resources` for development-time type checking. For example: `pip install setuptools types-pkg-resources`.
gotcha The version of `types-pkg-resources` tracks the evolution of the *stub definitions* for `pkg_resources`, not the `pkg_resources` module's actual version or functionality. The `pkg_resources` module's behavior is tied to the `setuptools` library version it's shipped with.
Fix: When troubleshooting runtime issues related to `pkg_resources`, focus on the `setuptools` version. When troubleshooting type checking issues, refer to the `types-pkg-resources` version and the `typeshed` project.

Install

pip install types-pkg-resources Install only stubs (for type checking)
pip install types-pkg-resources setuptools Install stubs and the runtime library

Imports

pkg_resources
```
import pkg_resources
```
You import the runtime library `pkg_resources`. The `types-pkg-resources` package provides the type hints that type checkers use when analyzing this import.
Distribution
```
from pkg_resources import Distribution
```
Specific types like `Distribution` are imported directly from `pkg_resources`.

Quickstart

This example demonstrates how to use `pkg_resources` to list installed packages and how `types-pkg-resources` provides type hints for this usage. For type checking to work, both `types-pkg-resources` and `setuptools` (which contains `pkg_resources`) must be installed in your environment, along with a type checker like MyPy.

import pkg_resources
from typing import List

# Example function using pkg_resources to list installed packages
def get_installed_package_names() -> List[str]:
    """Returns a sorted list of project names for installed packages."""
    # pkg_resources.working_set provides access to the active distributions
    distributions = pkg_resources.working_set
    return sorted([d.project_name for d in distributions])

if __name__ == "__main__":
    print("--- Listing installed packages via pkg_resources ---")
    packages = get_installed_package_names()
    print(f"Found {len(packages)} packages. First 5:")
    for p in packages[:5]:
        print(f"- {p}")

# To type-check this code:
# 1. Install necessary packages: `pip install types-pkg-resources setuptools mypy`
# 2. Run mypy: `mypy your_script_name.py`

view raw JSON →