scylladb
Clearly document our API
It's the 2nd time I'm hitting 'this is an API change' - once I seemingly suggested and once a public function that was used (by Siren) was removed. From the code, it's impossible to know what is a public API and what isn't. Let's think of a way to clearly mark the public API.
The problem is that Python doesn't really have a notion of privacy. We can't prevent users of the library from calling any internal function. There is a convention that things that have name starting with underscore are private and should not be called by users, but it does not prevent them from being called, and I think users of the driver (even Scylla-internal) do this anyway. Driver has API docs: https://python-driver.docs.scylladb.com/stable/api/index.html , but they may be missing some stuff, and even include stuff intended to be private - I honestly have no idea, I'd have to check.
I'm not sure what is the best way forward. Two of the probably many possible ones:
- Treat API docs as a source of truth (after we review it). We keep compatiblity with stuff described in the docs, and we are totally free to break anything else. If it breaks some callers, that's on them and they need to fix their code.
- Try not to intentionally break stuff that someone may call. If we break someone, revert. This keeps the line between public and private blurred, as it is now.
Ideally, docs should be written from the source, not the source relying on docs written half a century ago. I think it does boil down to good Docstring methodology and enforcement.
Ideally, docs should be written from the source, not the source relying on docs written half a century ago. I think it does boil down to good Docstring methodology and enforcement.
afaict those API docs are generated from source. .rst files in docs/api list the classes and methods which should be included in API docs, but the contents themselves are taken from code and docstrings.
@Lorak-mmk is right, but also Python is quite "forgiving" with some changes as long as people aren't using bad practices like positional arguments.
@mykaul what was the change you wanted to introduce?
