PEP 842: Module Exports (new revision)

As a library author, I don’t think this will help me particularly much with defining a public API. If the reason is to prevent IDEs from suggesting non-public names, then this doesn’t go far enough and must include class members as well. But there’s also so much more complexity to the question of what is public API in Flask, Click, etc.

We use a policy of “if it’s named in the documentation, it’s public and will go through a deprecation if it changes, otherwise it’s private and could change at any time.” Honestly, beyond an initial period years ago where most people weren’t aware of how to pin dependencies and test with deprecation warnings, this seems to have worked out for us. I can’t remember the last time we had a reported issue regarding this.

We have many classes where some attributes and methods should be public, and others private. For the most part, we did a good job in the past of using a _ prefix, but it’s not completely consistent.

We also need to deal with “public” classes, where access is public but creation is not. For example, an informational method returns an instance with some public attributes and methods that need to be documented so the user knows what’s available, but where we want to control how it’s created and don’t expect users to need to do so. It would be good to be able to mark the __new__ or __init__ methods as not public. Currently we add “this class has the following public methods, but should not be created directly” to its docs.

If this PEP passed, we would probably use it, but it won’t solve the majority of what we need.

10 Likes