This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Separate resources docs from other importlib docs
Type: Stage: resolved
Components: Documentation Versions: Python 3.11
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: jaraco Nosy List: eric.snow, jaraco
Priority: normal Keywords: patch

Created on 2021-12-17 02:10 by jaraco, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 30160 merged jaraco, 2021-12-17 02:14
Messages (11)
msg408749 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2021-12-17 02:10
The `importlib` documentation is fairly long and covers a number of topics. Furthermore, the `importlib.metadata` is separately documented and presents a good example of breaking out major aspects. Let's do the same with `.abc` and `.resources`.
msg408798 - (view) Author: Eric Snow (eric.snow) * (Python committer) Date: 2021-12-17 16:34
+1 to splitting out the importlib.resources docs

I'm mostly +1 for splitting out the others (.abc, .machinery, .util) too, not just .abc.

Regardless, a ToC at the top of the main page which identifies the submodules (and provides a brief summary for each) would be extra helpful.  I suppose that could be helpful regardless of whether or not we move submodule docs out.
msg408799 - (view) Author: Eric Snow (eric.snow) * (Python committer) Date: 2021-12-17 16:35
FWIW, one benefit to having everything in one doc (instead of one doc per submodule) is that it's a little easier to see the bigger picture.  This is particularly important for folks interested in customizing the import system (rather than just interacting with it).

However, they would probably be better served by an explicit section on how to customize the import system.  The language reference provides the info but its focus is to specify rather than to guide.  So it may make sense to have a dedicated section to at least cover the supported customization approaches (at a high level).

This would definitely be covered by a separate issue but it makes less sense if we don't move the submodules to their own docs.
msg408814 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2021-12-17 20:42
My main motivation for moving `.abc` was because it contains classes exclusively relevant to `.resources` (those also present in `importlib_resources.abc`. I want to explore moving those classes to the resources documentation so they're available together and maintained independently.

Other classes in `.abc` are relevant to the import system more generally, so maybe should stay in the main docs.
msg408816 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2021-12-17 20:55
I wonder if maybe it's more important to address issue46118 first.
msg408913 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2021-12-19 17:02
The reason I wanted to consider issue46118 first was because I wanted to explore whether the ABCs from `importlib_resources.abc` should be _documented_ as `importlib.resources.abc` or `importlib.abc` (as they are now).

After filing the issue and exploring the concerns (namely, should users be directed _away_ from `importlib.abc` for these classes), I'm uncertain whether it's worth the effort to make that transition, and certainly not in haste, so this effort can proceed to document the status quo (ABCs presented primarily in `importlib.abc`).
msg408914 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2021-12-19 17:04
> a ToC at the top of the main page which identifies the submodules (and provides a brief summary for each) would be extra helpful. 

I've added this in the latest commit (1adefaf552).
msg408915 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2021-12-19 17:19
As I'm exploring this issue, I notice that currently, the docs refer to :class:`importlib.resources.abc.Traversable` (even though that doesn't currently exist) (https://github.com/python/cpython/blame/main/Doc/library/importlib.rst#L948).
msg408918 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2021-12-19 17:29
I realize, I can limit the scope of this issue to address 'resources' alone, leaving ABCs where they are except for resource-related ones, allowing us to defer a larger refactoring to a separate issue/effort.
msg409234 - (view) Author: Eric Snow (eric.snow) * (Python committer) Date: 2021-12-27 17:24
+1
msg409399 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2021-12-31 02:17
New changeset 99945c6b5cf280bd90075cffae942af44941abcc by Jason R. Coombs in branch 'main':
bpo-46109: Separate out files relating to importlib.resources (GH-30160)
https://github.com/python/cpython/commit/99945c6b5cf280bd90075cffae942af44941abcc
History
Date User Action Args
2022-04-11 14:59:53adminsetgithub: 90267
2021-12-31 13:40:47jaracosetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2021-12-31 02:17:18jaracosetmessages: + msg409399
2021-12-27 17:24:47eric.snowsetmessages: + msg409234
2021-12-19 17:29:23jaracosetmessages: + msg408918
title: Separate resources and abc docs from other importlib docs -> Separate resources docs from other importlib docs
2021-12-19 17:19:47jaracosetmessages: + msg408915
2021-12-19 17:04:20jaracosetmessages: + msg408914
2021-12-19 17:02:57jaracosetmessages: + msg408913
2021-12-17 20:55:32jaracosetmessages: + msg408816
2021-12-17 20:42:08jaracosetmessages: + msg408814
2021-12-17 16:35:04eric.snowsetmessages: + msg408799
2021-12-17 16:34:58eric.snowsetnosy: + eric.snow
messages: + msg408798
2021-12-17 02:14:48jaracosetkeywords: + patch
stage: patch review
pull_requests: + pull_request28379
2021-12-17 02:10:06jaracocreate