pkg_resources: Expose the type of imports and re-exports

pkg_resources/__init__.py

@@ -27,7 +27,8 @@
 import time
 import re
 import types
-from typing import Protocol
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Protocol
+from collections.abc import Callable, Iterator
 import zipfile
 import zipimport
 import warnings
@@ -65,40 +66,44 @@
 from os import open as os_open
 from os.path import isdir, split
 
-from pkg_resources.extern.jaraco.text import (
-    yield_lines,
-    drop_comment,
-    join_continuation,
-)
+if not TYPE_CHECKING:
+    from pkg_resources.extern.jaraco.text import (
+        yield_lines,
+        drop_comment,
+        join_continuation,
+    )
 
-from pkg_resources.extern import platformdirs
-from pkg_resources.extern import packaging
-
-__import__('pkg_resources.extern.packaging.version')
-__import__('pkg_resources.extern.packaging.specifiers')
-__import__('pkg_resources.extern.packaging.requirements')
-__import__('pkg_resources.extern.packaging.markers')
-__import__('pkg_resources.extern.packaging.utils')
-
-# declare some globals that will be defined later to
-# satisfy the linters.
-require = None
-working_set = None
-add_activation_listener = None
-resources_stream = None
-cleanup_resources = None
-resource_dir = None
-resource_stream = None
-set_extraction_path = None
-resource_isdir = None
-resource_string = None
-iter_entry_points = None
-resource_listdir = None
-resource_filename = None
-resource_exists = None
-_distribution_finders = None
-_namespace_handlers = None
-_namespace_packages = None
+    from pkg_resources.extern import platformdirs
+    from pkg_resources.extern import packaging
+
+    __import__('pkg_resources.extern.packaging.version')
+    __import__('pkg_resources.extern.packaging.specifiers')
+    __import__('pkg_resources.extern.packaging.requirements')
+    __import__('pkg_resources.extern.packaging.markers')
+    __import__('pkg_resources.extern.packaging.utils')
+else:
+    # Replicates the imports above in a way that can be understood by type-checkers
+    from jaraco.text import (
+        yield_lines,
+        drop_comment,
+        join_continuation,
+    )
+    import platformdirs
+    import packaging
+    import packaging.version
+    import packaging.specifiers
+    import packaging.requirements
+    import packaging.markers
+    import packaging.utils
+
+    # Declare some globals that will be defined by calls to _declare_state so checkers know they exist and their type
+    _distribution_finders: Dict[
+        type, Callable[[Any, str, bool], Iterator["Distribution"]]
+    ] = {}
+    _namespace_handlers: Dict[
+        type, Callable[[Any, str, str, types.ModuleType], Optional[str]]
+    ] = {}
+    _namespace_packages: Dict[Optional[str], List[str]] = {}
 
 
 warnings.warn(
@@ -491,19 +496,6 @@ def compatible_platforms(provided, required):
     return False
 
 
-def run_script(dist_spec, script_name):
-    """Locate distribution `dist_spec` and run its `script_name` script"""
-    ns = sys._getframe(1).f_globals
-    name = ns['__name__']
-    ns.clear()
-    ns['__name__'] = name
-    require(dist_spec)[0].run_script(script_name, ns)
-
-
-# backward compatibility
-run_main = run_script
-
-
 def get_distribution(dist):
     """Return a current distribution object for a Requirement or string"""
     if isinstance(dist, str):
@@ -3273,6 +3265,15 @@ def _mkstemp(*args, **kw):
 warnings.filterwarnings("ignore", category=PEP440Warning, append=True)
 
 
+class PkgResourcesDeprecationWarning(Warning):
+    """
+    Base class for warning about deprecations in ``pkg_resources``
+
+    This class is not derived from ``DeprecationWarning``, and as such is
+    visible by default.
+    """
+
+
 # from jaraco.functools 1.3
 def _call_aside(f, *args, **kwargs):
     f(*args, **kwargs)
@@ -3291,15 +3292,6 @@ def _initialize(g=globals()):
     )
 
 
-class PkgResourcesDeprecationWarning(Warning):
-    """
-    Base class for warning about deprecations in ``pkg_resources``
-
-    This class is not derived from ``DeprecationWarning``, and as such is
-    visible by default.
-    """
-
-
 @_call_aside
 def _initialize_master_working_set():
     """
@@ -3335,3 +3327,23 @@ def _initialize_master_working_set():
     # match order
     list(map(working_set.add_entry, sys.path))
     globals().update(locals())
+
+
+if TYPE_CHECKING:
+    # All of these are set by the @_call_aside methods above
+    __resource_manager: ResourceManager = ...  # Won't exist at runtime
+    resource_exists = __resource_manager.resource_exists
+    resource_isdir = __resource_manager.resource_isdir
+    resource_filename = __resource_manager.resource_filename
+    resource_stream = __resource_manager.resource_stream
+    resource_string = __resource_manager.resource_string
+    resource_listdir = __resource_manager.resource_listdir
+    set_extraction_path = __resource_manager.set_extraction_path
+    cleanup_resources = __resource_manager.cleanup_resources
+
+    working_set: WorkingSet = ...
+    require = working_set.require
+    iter_entry_points = working_set.iter_entry_points
+    add_activation_listener = working_set.subscribe
+    run_script = working_set.run_script
+    run_main = run_script