Rename the 'package' parameter to 'anchor'.

Author: jaraco

CHANGES.rst

@@ -6,7 +6,9 @@ v5.10.0
   module is passed, resources will be resolved adjacent to
   those modules, even for modules not found in any package.
   For example, ``files(import_module('mod.py'))`` will
-  resolve resources found at the root.
+  resolve resources found at the root. The parameter to
+  files was renamed from 'package' to 'anchor', with a
+  compatibility shim for those passing by keyword.
 
 v5.9.0
 ======

importlib_resources/_common.py

@@ -5,6 +5,7 @@
 import contextlib
 import types
 import importlib
+import warnings
 
 from typing import Union, Optional, cast
 from .abc import ResourceReader, Traversable
@@ -15,11 +16,36 @@
 Anchor = Package
 
 
-def files(package: Anchor) -> Traversable:
+def package_to_anchor(func):
+    """
+    Replace 'package' parameter as 'anchor' and warn about the change.
+    """
+    undefined = object()
+
+    @functools.wraps(func)
+    def wrapper(anchor=undefined, package=undefined):
+        if package is not undefined:
+            if anchor is not undefined:
+                return func(anchor, package)
+            warnings.warn(
+                "First parameter to files is renamed to 'anchor'",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return func(package)
+        elif anchor is undefined:
+            return func()
+        return func(anchor)
+
+    return wrapper
+
+
+@package_to_anchor
+def files(anchor: Anchor) -> Traversable:
     """
     Get a Traversable resource for an anchor.
     """
-    return from_package(resolve(package))
+    return from_package(resolve(anchor))
 
 
 def get_resource_reader(package: types.ModuleType) -> Optional[ResourceReader]:

importlib_resources/tests/test_files.py

@@ -1,5 +1,6 @@
 import typing
 import unittest
+import warnings
 import contextlib
 
 import importlib_resources as resources
@@ -10,6 +11,13 @@
 from ._compat import os_helper, import_helper
 
 
+@contextlib.contextmanager
+def suppress_known_deprecation():
+    with warnings.catch_warnings(record=True) as ctx:
+        warnings.simplefilter('default', category=DeprecationWarning)
+        yield ctx
+
+
 class FilesTests:
     def test_read_bytes(self):
         files = resources.files(self.data)
@@ -28,6 +36,14 @@ def test_read_text(self):
     def test_traversable(self):
         assert isinstance(resources.files(self.data), Traversable)
 
+    def test_old_parameter(self):
+        """
+        Files used to take a 'package' parameter. Make sure anyone
+        passing by name is still supported.
+        """
+        with suppress_known_deprecation():
+            resources.files(package=self.data)
+
 
 class OpenDiskTests(FilesTests, unittest.TestCase):
     def setUp(self):