add a top-level public api

[mmerickel]

Pyramid has never used the top-level namespace for anything other than subpackages. However, we also don't use conventions like _ prefixes to indicate private classes and functions. This means that a user exploring the pyramid package via an autocompleting IDE has no way to tell what is public and what is private.

ONE OPTION (but maybe not the best?) is to define the top-level api in pyramid as the public api. We could use something like apipkg to do this such that imports occur lazily. From there we could expose public functions, classes and attributes as pyramid.view_config, pyramid.Configurator, etc.

IDEs still have the issue that the subpackages themselves appear public, so if someone navigates into the subpackage everything looks public (pyramid.session.foo) but perhaps that's less of an issue?

[digitalresistor]

I personally am "meh" on this.

[mmerickel]

That's fine. I'd be curious to know any other ideas on how to make an easily discoverable public API by simply navigating the code. Some thoughts:

• Go through the codebase and convert everything to _prefix where private.
• Define a pyramid.private package which mirrors the public api. For example pyramid.private.session vs pyramid.session.