Poll: Public/internal handling — what behavior do we want?

Ideas
32

Going beyond that, we may even need to concisely summarize the status quo first so that we have a shared full understanding, which may help pinning down the problems.

Relevant docs:

  1. 9. Classes — Python 3.14.7 documentation - defines single.leading-underscore semantics (in the context of classes, but also applying this to functions). It also defines double underscore name mangling
  2. 7. Simple statements — Python 3.14.7 documentation The import docs define what public names
  3. Distributing type information — typing documentation Typing docs

Some remarks:

  • Terminology is a bit sloppy. There is

    • private
    • “private”
    • class-private
    • non-public

    in particular private is used with variing meaning. Exactly defining the terms may help preventing misunderstands.

  • 2 and 3 have conflicting statements on whether imported symbols are public; see PEP 843: Export Statement for DRY Re-exports - #33 by timhoffm

  • The summary should also include patterns such as hub-and-spoke or import x as _x which build on the language convention but are not part of the docs.

3 Likes