Skip to content

[doc] Explicitly note that meta_path is not empty #74720

Closed
#94098
Closed
[doc] Explicitly note that meta_path is not empty#74720
#94098
Labels
3.10 (EOL)end of life3.11only security fixes3.12only security fixesdocsDocumentation in the Doc direasytype-bugAn unexpected behavior, bug, or error

Description

@masklinn
masklinn
mannequin
opened on Jun 1, 2017
BPO 30535
Nosy @brettcannon, @ncoghlan, @pitrou, @masklinn, @ericsnowcurrently, @Windsooon
PRs
  • bpo-30535: Explicitly note that sys.meta_path is not empty #13300
    		•

    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 2017-06-01.08:59:10.759>
labels = ['easy', 'type-bug', '3.9', '3.10', '3.11', 'docs']
title = '[doc] Explicitly note that meta_path is not empty'
updated_at = <Date 2021-11-26.23:16:18.508>
user = 'https://github.com/masklinn'

    bugs.python.org fields:

    activity = <Date 2021-11-26.23:16:18.508>
actor = 'iritkatriel'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2017-06-01.08:59:10.759>
creator = 'xmorel'
dependencies = []
files = []
hgrepos = []
issue_num = 30535
keywords = ['patch', 'easy']
message_count = 12.0
messages = ['294919', '294924', '294927', '294928', '294967', '295007', '295008', '295010', '295012', '295049', '295065', '342405']
nosy_count = 7.0
nosy_names = ['brett.cannon', 'ncoghlan', 'pitrou', 'xmorel', 'docs@python', 'eric.snow', 'Windson Yang']
pr_nums = ['13300']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue30535'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

    Activity

    1. masklinn commented on Jun 1, 2017

      @masklinn
      masklinnmannequin
      on Jun 1, 2017
      MannequinAuthor

      Encountered this issue porting Python 2 code manipulating meta_path to Python 3.

      In Python 2, meta_path is empty by default and its documentation specifically notes that:

      sys.meta_path is searched before any implicit default finders or sys.path.

      As a result, sys.meta_path.append() works perfectly well and is overwhelmingly common[0].

      In Python 3, this note was removed but the documentation does not specifically state default finders are present in meta_path, and the old code using sys.meta_path.append may now break as the default finders will silently take precedence on the custom ones if they believe they can do the job.

      I'd like to add a warning to the Python 3 documentation (3.5+?) noting the presence of existing default loaders, and to the Python 2 documentation suggesting sys.meta_path.insert(0, finder) for future-proofing, would there be objections or issues?

      [0] https://github.com/search?q=meta_path.append&type=Code&utf8=✓

    2. masklinn
      assigned
      docspython
      on Jun 1, 2017
    3. masklinn
      added
      docsDocumentation in the Doc dir
      type-bugAn unexpected behavior, bug, or error
      on Jun 1, 2017

    4. masklinn commented on Jun 1, 2017

      @masklinn
      masklinnmannequin
      on Jun 1, 2017
      MannequinAuthor

      Addendum: the warning was present (in the documentation) until Python 3.5, even though Python 3.3 is apparently where the "default finders" were moved to meta_path:

      \> python3.2 -c 'import sys;print(sys.meta_path)'
[]

      python3.3 -c 'import sys;print(sys.meta_path)'
      [<class '_frozen_importlib.BuiltinImporter'>, <class '_frozen_importlib.FrozenImporter'>, <class '_frozen_importlib.PathFinder'>]

    5. masklinn commented on Jun 1, 2017

      @masklinn
      masklinnmannequin
      on Jun 1, 2017
      MannequinAuthor

      And it turns out the change was noted in the Python 3.3 release notes[0] though not all the consequences were spelled out (and the meta_path and path_hooks documentations were not changed)

      [0] https://docs.python.org/3/whatsnew/3.3.html#visible-changes

    6. pitrou commented on Jun 1, 2017

      @pitrou
      pitrou
      on Jun 1, 2017
      Member

      A warning is probably too strong. Also, it's easy to check sys.meta_path at the interpreter prompt, so I'm not sure it's worth mentioning at all.

    7. brettcannon commented on Jun 1, 2017

      @brettcannon
      brettcannon
      on Jun 1, 2017
      Member

      I'm fine with adding a note to the Python 2 docs, but putting it in Python 3 seems to be going in the wrong direction as having sys.meta_path not be empty is how Python will be going forward.

    8. masklinn commented on Jun 2, 2017

      @masklinn
      masklinnmannequin
      on Jun 2, 2017
      MannequinAuthor

      I'm fine with adding a note to the Python 2 docs, but putting it in Python 3 seems to be going in the wrong direction as having sys.meta_path not be empty is how Python will be going forward.

      I don't think putting a note is any hint that the Python 3 behaviour (which I appreciate) would change, it would simply tell the reader that the list is not empty by default and they ought decide whether they want their finders to take precedence over (and insert at head) or be fallback to (and append) the builtin finders.

      It could also link to the standard/builtin finders.

    9. masklinn commented on Jun 2, 2017

      @masklinn
      masklinnmannequin
      on Jun 2, 2017
      MannequinAuthor

      A warning is probably too strong. Also, it's easy to check sys.meta_path at the interpreter prompt, so I'm not sure it's worth mentioning at all.

      It's easy if you think of it and did not miss a small bit of the Python 3.3 release note indicating that the *documented guarantees* of Python 2.x, 3.0, 3.1 and 3.2 had been dropped, even as they were incorrectly still present in the official documentation itself.

      I spent a few hours trying to understand why our import hooks did not work correctly anymore in 3.5, and I never even considered printing sys.meta_path in an open interpreter, I realised the behavioural change because I ended up printing meta_path after the addition of our custom hooks to make sure they were actually there.

    10. pitrou commented on Jun 2, 2017

      @pitrou
      pitrou
      on Jun 2, 2017
      Member

      Le 02/06/2017 à 13:21, Xavier Morel a écrit :

      I spent a few hours trying to understand why our import hooks did not work correctly anymore in 3.5, and I never even considered printing sys.meta_path in an open interpreter, I realised the behavioural change because I ended up printing meta_path after the addition of our custom hooks to make sure they were actually there.

      Fair enough. So we can just add a sentence informing readers that
      meta_path, by default, holds entries to handle the standard kinds of
      modules (.py files, extension modules...).

    11. masklinn commented on Jun 2, 2017

      @masklinn
      masklinnmannequin
      on Jun 2, 2017
      MannequinAuthor

      Fair enough. So we can just add a sentence informing readers that
      meta_path, by default, holds entries to handle the standard kinds of
      modules (.py files, extension modules…).

      Yeah that's basically what I meant, talking about a "warning" in python 3 may have been the wrong wording or given an incorrect impression, sorry about that.

    12. ericsnowcurrently
      added
      easy
      on Jun 2, 2017

    13. brettcannon commented on Jun 2, 2017

      @brettcannon
      brettcannon
      on Jun 2, 2017
      Member

      Yeah, there's actually a specific 'warning' directive which puts text in the docs in a red box to make it a full-blown warning which is what I thought you wanted, having it say "this is different than Python 2!". Having a sentence that just states how things are without referring to Python 2 is totally fine.

    14. ncoghlan commented on Jun 3, 2017

      @ncoghlan
      ncoghlan
      on Jun 3, 2017
      Contributor

      s/Warn/Explicitly note/ in the issue title :)

      I think this is actually both important enough and subtle enough to warrant a ".. note::" callout in the docs.

      In Python 3, it would say to use sys.meta_path.insert(0, finder) if you want your finder to take precedence over the default search locations, and sys.meta_path.append(finder) if you only want it handle cases that aren't already handled by the default machine.

      In Python 2, it would say that custom finders on sys.meta_path will always take precedence over the default machinery, and if you want to do otherwise, you'll need to use importlib2 and install its loaders into sys.meta_path ahead of your own.

    15. ncoghlan
      changed the title [-]Warn that meta_path is not empty[/-] [+]Explicitly note that meta_path is not empty[/+] on Jun 3, 2017

    16. Windsooon commented on May 14, 2019

      @Windsooon
      Windsooonmannequin
      on May 14, 2019
      Mannequin

      I created a PR for it. TBO, meta_path is not a good name since it doesn't contain any *path* at all.

    17. iritkatriel
      added
      3.9 (EOL)end of life
      3.10 (EOL)end of life
      3.11only security fixes
      on Nov 26, 2021
    18. iritkatriel
      changed the title [-]Explicitly note that meta_path is not empty[/-] [+][doc] Explicitly note that meta_path is not empty[/+] on Nov 26, 2021
    19. ezio-melotti
      transferred this issue fromon Apr 10, 2022
    20. iritkatriel
      added
      3.12only security fixes
      and removed
      3.9 (EOL)end of life
      on Jun 21, 2022
    21. iritkatriel
      closed this as completedin #94098on Jun 21, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

    Metadata

    Metadata

    Assignees

    No one assigned

      Labels

      3.10 (EOL)end of life3.11only security fixes3.12only security fixesdocsDocumentation in the Doc direasytype-bugAn unexpected behavior, bug, or error

      Projects

      No projects

        Milestone

        No milestone

        Relationships

        None yet

        Development

        No branches or pull requests

        Issue actions