Document what are resources in importlib.resources

[FFY00]

BPO	44164
Nosy	@jaraco, @FFY00
PRs	bpo-44164: document the semantic value of module resources #26280

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2021-05-18.00:05:54.175>
labels = ['3.11', 'docs']
title = 'Document what are resources in importlib.resources'
updated_at = <Date 2021-05-23.18:56:35.435>
user = 'https://github.com/FFY00'

bugs.python.org fields:

activity = <Date 2021-05-23.18:56:35.435>
actor = 'jaraco'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2021-05-18.00:05:54.175>
creator = 'FFY00'
dependencies = []
files = []
hgrepos = []
issue_num = 44164
keywords = ['patch']
message_count = 2.0
messages = ['393849', '394218']
nosy_count = 3.0
nosy_names = ['jaraco', 'docs@python', 'FFY00']
pr_nums = ['26280']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue44164'
versions = ['Python 3.11']

Linked PRs

• gh-88330: Add more detail about what is a resource. #99801

[FFY00]

It would be good to explain what constitutes a resource in the importlib.resources documentation.

As per the current implementation, they should be defined as arbitrary files contained in the package. Is this correct?

[jaraco]

I've not previously seen a definition of resources. The original implementation of importlib_resources excluded 'directories' as resources and excluded support for resources being in subdirectories (only files in packages were allowed). Now resources can be found in subdirectories that are not packages and in namesepace packages. I'd describe resources thus:

"Resources" are file-like resources associated with a module[1] or package in Python. The resources may be contained directly in a package or within a subdirectory contained in that package. Resources may be text or binary. As a result, Python module sources (.py) of a package and compilation artifacts (pycache) are technically de-facto resources of that package. In practice, however, resources are primarily those non-Python artifacts exposed specifically by the package author.

[1] Resources associated with top-level modules are not yet supported by importlib[._]resources (python/importlib_resources#203) but were supported by pkg_resources.