Join GitHub today
Make the tox API explicit #800
added a commit
Apr 30, 2018
While spring cleaning I got a bit carried away and though I thought this was a no brainer from what I learned since being more involved in OSS projects, I would really appreciate some feedback especially from some more experienced OSS maintainers.
My thinking was that I constantly observe projects grow implicit de-facto APIs - like e.g. the "pip API" that never existed but AFAICT still was in common use (programmatic use of pip was always actively discouraged). Same with pytest internals, although it having a very exhaustive plugin system. In a language like Python where every internal of every library you use can be accessed, monkeypatched, deleted, etc. this happens and it is o.k. - we're all consenting adults after all. Users doing this should be aware though that these internals can change without warning - even if they are not explicitly marked as private (
Introducing an explicit API is acknowledging this and for me a way of communicating where we try to keep it stable and give the user enough warning before breaking it (e.g. emit deprecation warnings for at least one minor release before breaking things).
tox has been quite stable over the last years, so this seems to be a good time for me to do this and I think it is also a good idea, because things might change more in the future to keep tox up to date with changes in packaging and new tools popping up. A clear deprecation strategy for an "official" API might cause less pain and friction then instead of breaking things without warning just because tox has no API.
So here it is for now:
The very minimum are
If introducing the constants as part of the API is a good idea I honestly don't know, but at least
I also got aware that there needs to be some more documentation around the deprection stuff than there is already, but I think this can be taken pretty much unchanged from what we introduced for pytest a while ago.