This is absolutely like JSON in that respect. Applications are often going 
to want to load any of many types of key we support so I'm not sure there's 
a much more sensible way of doing this than documenting the types they can 
get. Having one method per type requires loading the key over and over 
until you get the right thing and a visitor pattern setup seems more 
complex than needed too.

I'll give the docs some updates :-)


On 31 March 2014 22:15:13 Glyph <notifications@github.com> wrote:

> > +                            structure could not be decoded successfully.
> > +
> > +        :raises TypeError: If a ``password`` was given and the private 
> key was
> > +                           not encrypted. Or if the key was encrypted but no
> > +                           password was supplied.
> > +
> > +        :raises UnsupportedAlgorithm: If the serialized key is of a type 
> that
> > +                                      is not supported by the backend.
> > +
> > +        :raises UnsupportedCipher: If the serialized key is encrypted with a
> > +                                   cipher that is not supported by the 
> backend.
> > +
> > +    .. attribute:: private_key
> > +
> > +        The deserialized private key object. An instance of any of the 
> private
> > +        key types supported by ``cryptography``.
>
> If users need to use `isinstance` then you still need to say what types you 
> might return so they might know what types they need to check instanceness of.
>
> However, interfaces that require the user to call `isinstance` seem like a 
> cop-out to me.  Sometimes you really can't get away from it (i.e. when you 
> have to load some JSON) but that doesn't seem like the case here.  To 
> further the analogy to JSON, the "right" way to expose JSON-loading to 
> *applications* is to have some kind of schema in front of the loading, so 
> that the application only gets data in a shape that it declares it expects. 
>  If an application needs a DSA key, it should ask for one, and if the file 
> is in the wrong format that's an error.
>
> Maybe this concern belongs above the hazmat layer, but definitely 
> documenting what *might* get returned (since it's more than one thing) 
> seems like a must.
>
> ---
> Reply to this email directly or view it on GitHub:
> https://github.com/pyca/cryptography/pull/627/files#r11137228