Public vs. private API (PLEASE READ)

Pyblish Development
#1

Hi all,

I’m working on a pull-request now in which private Python modules are being moved to where they should not be touched.

Before

  • plugin.py

After

  • _plugin.py

This should not affect any of you, but I fear it will due to how we have previously communicated to you which of these modules were, in fact, public versus private.

What is changing?

In a nutshell, the only public members are:

  • api.py
  • util.py

See here for details on the exact changes.

What does “private” mean?

Public modules are api.py and util.py. These are the ones with an interface that we maintain forever. They will simply not change nor break at any point in time during the course of a major release - 1.x.x.

When the major version increases, e.g. to 2.x.x, this is when deprecated functionality is dropped, and this is the only point in time where public interfaces can change.

Private modules on the other hand may change at any point in time, without telling you about it. They are for internal use only and depending on them in your code will most likely lead to trouble. So avoid.

What can I do?

You shouldn’t have to worry, unless you know you are already using members of private modules. In this case, this is the place to talk about how to rectify this.

We can either:

  1. Make the private member public
  2. Change your code to use an equivalent public

Where (2) is not possible, it’s likely we will simply have to bite the bullet of a larger API and include it. But remember, anything included in the public API is forever. Like diamonds. And contrary to real life, the less diamonds we have the better.

1 Like