A two-namespace model for Python modules to distinguish public/internal

Depending on the characteristics one wants to achieve, there could be different implementation strategies.

One would be to add __internal_dict__ and add names to it based on a keyword, decorator or function (conceptually the same markers as proposed in PEP 842/844, but rather marking the private parts, not the public/exported ones).names without that go into __dict__ as before. For name lookup in modules, one would extend the lookup order LEGB to LEGIB. The I standing for the internal namespace.
The nice property here is that nothing changes for external users: __dict__ and all related functionality stay as is. It would be an opt-in decision of module owners to move selected names out of the publicly visible namespace into the internal one. If desired, we could still make the internal names easily accessible through something like mymodule.__internal__.internal_name.

There are other possible choices, like having everything that is added to __dict__ also being added to __internal_dict__ so that for name lookup, you’d internally only look at __internal_dict__.
Another degree of choice: Instead of marking the private names, you could also mark the public names as in @public / export.

But these are nuances and we can choose the model we like best. Distribution of names to the respective namespace and where to look would be handled through the language, so that the exact content of the namespaces and public/private markers can be designed as needed.

2 Likes