"stable API" misconception giving BaseManager and Manager as examples

[Ilya Kazakevich]

Hello,

In Djnago 1.7 Manager class extends BaseManager (actually, it extends its proxy, created using from_queryset). BaseManager is not mentioned in official documentation, so it is not part of official ("stable") api, right?

"All the public APIs (everything in this documentation) " (from here https://docs.djangoproject.com/en/dev/misc/api-stability/)

But it does not start with underscore and its module (django.db.models.manager) is public module aswell. So, it should be considered as public class according to python codestyle. 

I believe this fact confuses user. May one use BaseManager or minor api change may brake such usage?

The other problem is there is no official Manager reference: there is a good manual, but no reference where all methods are listed (like we have for QuerySet, for example).

So, what is the official, stable Manager API? Most developers know answer to this question intuitively, but there is no formal way to answer it, right?

I believe that in Ideal Project there should be something like this:

1) Move all "non public" classes to "_non_public" packages (or make classes _NonPublic)

2) For each public class list all members in doc or directly in python documentation. 

What do you think?

Ilya.

[Tim Graham]

In fact, there's an open ticket to create a reference of the public manager methods. There's a detailed comment from Loic about some ideas for that: https://code.djangoproject.com/ticket/20768

I think our existing policy about stable APIs being the ones that are documented works pretty well. I don't think there would be much gain in shuffling around a lot of code to distinguish between public and private APIs, plus we'd needlessly break a lot of code that's using private APIs.