GeezerVison

This is surprising to me. I would expect, a pathlib.Path('...', 'mod.py') to be returned, requiring resources.files(mod).parent.joinpath('res.txt'). res.txt is not a resource of mod, but rather of the parent module, which might not even exist if mod is top level.

Thanks for sharing your surprise. Surely this would need some improved documentation to illustrate how files() now accepts an Anchor (instead of Package), where the anchor indicates:

• the container (importer) from where resources can be discovered,
• if a module is indicated, that's equivalent to indicating the container of that module,
• if a top-level module is indicated, that will anchor on resources reachable at the top level by that same importer.

This is the behavior indicated by pkg_resources:

Note that if a module name is used, then the resource name is relative to the package immediately containing the named module.

However, I've also observed that the pkg_resources implementation also allows for loading resources against unpackaged modules. And while that behavior may have been unintentional, it works because it's a natural consequence of relying on the importer/loader to resolve the resources from the same location as the indicated package/module. That is, because the importlib mechanism supports loading modules from outside packages, so too should resources be loadable from that location.

res.txt is not a resource of mod, but rather of the parent module, which might not even exist if mod is top level.

A parent module may not exist, but a loader for that module does exist and can load resources adjacent to that module:

 importlib_resources feature/203-non-package-modules $ touch setup.py
 importlib_resources feature/203-non-package-modules $ .tox/python/bin/python -iq
>>> import importlib_resources as res
>>> files = res.files('setup')
>>> files
PosixPath('/Users/jaraco/code/public/importlib_resources')
>>> files.joinpath('pyproject.toml').read_text()[:10]
'[build-sys'

In 1f3c226, I've updated the documentation to honor an Anchor type which need not be a package.