What is the status of the __subclasses__ method?

[Ruud de Jong]

The question I have is: how safe / future proof / portable is the
use of the __subclasses__ method that exists for new-style classes?

Background: I thought I had found an easy-to-understand
application for metaclasses: making classes instantly aware
of their subclasses. The context was that I needed a class
hierarchy, and I wanted to be able to instantiate subclasses
by calling the root class. Which exact subclass would be
instantiated would depend on the arguments with which the root
class would be called. In effect using the root class as a factory.

I did not want to build the logic of argument-to-subclass
mapping in the root class. Instead I wanted the root class
to pass the argument (recursively) to its subclasses, and if
a subclass would accept the argument then an object instantiation
of that subclass would be returned. To do this, each class
in the hierarchy obviously needs to be aware of its subclasses.

I also did not want to revisit the base classes each time
I would create a new subclass -- I wanted the mere act
of subclassing a base class to be enough for the base class
to be aware of the subclass. So, being the  kind of lazy
person who prefers to spend several hours on an interesting
problem to avoid 5 minutes of routine work, I wrote a metaclass
that would do this for me. Quite straightforward really.
Only after playing around with this for a while, and inspecting
the results, I happened to notice that new-style classes in
Python have a __subclasses__ method. This method does what
the name implies: Klass.__subclasses__() returns a list of
the direct subclasses of Klass.

I don't really mind the lost time for the creation of the
metaclass -- that was fun, and I learned some new things
along the way. But what bothers me is that there's absolutely
nothing about this method in the Python documentation.
The excellent "Python in a Nutshell" book also does not
mention it. It's almost as if this method is not meant
to be used by mortals.

When I searched python.org for "__subclasses__" I found
some more information. The __subclasses__ method appears
to exist to allow modifications of the superclass to be
percolated down to its children, mainly for speed reasons,
if I understand Tim Peter's explanation correctly 
(http://mail.python.org/pipermail/python-list/2003-August/176360.html). 
I also found several warnings that the __subclasses__ method
only returns classes that have been accessed previously (which
would defeat my purpose) See e.g. 
http://mail.python.org/pipermail/python-bugs-list/2003-June/018299.html. 
However, when I experimented with the __subclasses__ method
for my application, I always found that the subclass was known
as soon as it was defined.

So again, my question. Is it safe to use the __subclasses__
method for the purpose I described above? Or would it be safer
to revert to my home-grown metaclass solution?

Ruud de Jong