Support non-package modules.

[jaraco]

• Add test capturing current behavior and missed expectation. Ref Unable to load resources for modules #203.
• Remove restriction that a 'package' cannot be a module. Allows resolution of resources from adjacent modules, even those not found in a package. Fixes Unable to load resources for modules #203.
• Update changelog. Ref Unable to load resources for modules #203.

[jaraco]

@warsaw I'd appreciate your review of this change, especially since you were involved so much in the discussion on #60. The behavior change is entirely in the second commit ecffc07. Note how it simplifies the code, aligns with pkg_resources behavior, and enables use-cases that were otherwise unreachable (resources for non-package modules). Is there any reason we shouldn't allow users to supply a module as an indicator for where to locate resources?

[jaraco]

See jaraco/openpack@82a5d0b for an illustration of how this change simplifies and harmonizes resource loading.

[FFY00]

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.

[jaraco]

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.

[jaraco]

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'

[jaraco]

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