search

nebari-dev / governance

āœØ Governance-related work for Nebari-dev
BSD 3-Clause "New" or "Revised" License
0 stars 2 forks source link

RFD - Make `nebari` internals aggressively private #37

Closed pmeier closed 1 year ago

pmeier commented 1 year ago
Status Open for comments šŸ’¬
Author(s) @pmeier
Date Created 07-04-2023
Date Last updated 07-04-2023
Decision deadline xx

Make nebari internals aggressively private

Summary

Currently, all internals of nebari are public and with that there comes a set of expectations from the users with the main one being backwards compatibility. Although there is no such thing as true private functionality in Python, it is the canonical understanding of the community that a leading underscore in a module / function / class name implies privacy and thus no BC guarantees.

AFAIK, nebari does not have an API. Thus, I propose to "prefix" everything with a leading underscore to avoid needing to keep BC for that.

User benefit

This proposal brings no benefit for the user, but rather for the developers. As explained above, having a fully public API brings BC guarantees with it. At least that is what users expect. With them in place it can be really hard to refactor / change internals later on although we never intended that to happen.

Design Proposal

The canonical understanding for privacy in Python is that it is implied by a leading underscore somewhere in the "path". For example

are all considered private. This gives us multiple options to approach this:

  1. Make all endpoints private: prefix every function / method / class with an underscore. This is fairly tedious also somewhat impacts the readability.
  2. Make all namespaces under the main nebari package private, e.g. nebari._schema rather than nebari.schema. Since we aren't exposing anything from the main namespace this would effectively make everything private.
  3. Inject an intermediate private namespace into the package, i.e. create nebari._internal and move everything under that. This is what pip does.
  4. Rename the main package to _nebari, but still provide the script under the nebari name. This makes it a little awkward for invoking it through Python, i.e. python -m _nebari. If this is something we want to support, we can also create a coexisting nebari package that does nothing else but importing the CLI functionality from _nebari. This is what pytest does.

These are ordered in increasing order of my preference.

Alternatives or approaches considered (if any)

Instead of fixing our code to be private, we could also put a disclaimer in the documentation that we consider all internals private and thus there are no BC guarantees. However, we need to be honest with ourselves here. Although this would suffice from a governance stand point, we are making it easier for users to shoot themselves in the foot. And that is rarely a good thing.

User impact

If we want to adapt this proposal or something similar, we need to do it sooner than later. Since this change is BC breaking for everyone who is already importing our internals, we should do it as long as the user base is fairly small and thus even fewer people (hopefully none) are doing something we don't want for the the future.

Depending on how much disruption we anticipate, we could also go through a deprecation cycle with the prompt to get in touch with us in case a user depends on our internals. Maybe there is actually a use case for a public API?

Adam-D-Lewis commented 1 year ago

My two cents is that you're right. Most internals should be private. We don't intend people to depend on them and we don't guarantee backwards compatibility of the API. It seems like quite a bit of work so I also like the disclaimer somewhere in the README that says all internals are private it the meantime.

costrouc commented 1 year ago

My thoughts.

To me I see Nebari is an application.But with that said conda also thought they were just a cli and then they are now used as an api. I would like to get ahead on this.

pavithraes commented 1 year ago

Notes from discussion on 2nd May:

This RFD is accepted, unanimously. :)

pmeier commented 1 year ago

Closed in nebari-dev/nebari#1778.