From a3af10deda986ba1011e8ed866aea031d9131706 Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Sat, 16 Dec 2023 10:21:10 -0500 Subject: [PATCH] Add a paragraph describing why context.path is not included in the example. --- Doc/library/importlib.metadata.rst | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/Doc/library/importlib.metadata.rst b/Doc/library/importlib.metadata.rst index cc12cd8b94c981a..bf3b88dfa8fbd1b 100644 --- a/Doc/library/importlib.metadata.rst +++ b/Doc/library/importlib.metadata.rst @@ -427,13 +427,23 @@ custom importer to provide metadata, it would also need to implement for dist_record in self.db.query_distributions(query): yield DatabaseDistribution(dist_record) - In this way, ``query_distributions`` would return records for each distribution served by the database matching the query. For example, if ``requests-1.0`` is in the database, ``find_distributions`` would yield a ``DatabaseDistribution`` for ``Context(name='requests')`` or ``Context(name=None)``. +For the sake of simplicity, this example ignores ``context.path``. The `path` +attribute defaults to ``sys.path`` and is the set of import paths to be +considered in the search. A ``DatabaseImporter`` could potentially function +without any concern for a search path. Assuming the importer does no +partitioning, the "path" would be irrelevant. In order to illustrate the +purpose of ``path``, the example would need to illustrate a more complex +``DatabaseImporter`` whose behavior varied depending on +``sys.path``/``PYTHONPATH``. In that case, the ``find_distributions`` should +honor the ``context.path`` and only yield ``Distribution``s pertinent to that +path. + ``DatabaseDistribution``, then, would look something like:: class DatabaseDistribution(importlib.metadata.Distributon):