Improve django.core.serializers.get_serializer() docs

[Roy Smith]

By experimentation, it appears that calling get_serializer() with an unknown format raises KeyError, but this is not documented. It should be documented what the behavior is.

Even better (maybe this should be a separate issue), it should raise some more specific exception, which would make it easier to handle at a higher level (such as middleware).

[Mathieu Agopian <mathieu.agopian@…>]

Hello RoySmith,

I believe there's (as you mentioned) two tickets in one: doc improvement, and a feature request.

You could/should create a ticket for the feature request, but i personally don't get the need for a specific exception (a try/except KeyError should work pretty well, and it appears logical to have a KeyError in this case as you can (un)register serializers).

Regarding the documentation improvement, from what i see in the ​http://docs.djangoproject.com/en/1.3/topics/serialization/, there isn't any detailed information (reference, parameters, returns...) for the get_serializer method. I believe it's one of those multiple place where it's up to the developer to check the code if more information or advanced usage is needed (use the source, luke ;).

Being uncertain about the need for this documentation improvement, i'll just leave the ticket as is (changed component to "documentation") for someone else to decide ;)

[Roy Smith]

Hi, Mathieu, thanks for your comment.

The problem with "use the source" is that the source can change without notice. The documentation is a contract. Sure, it can change, but users would expect such changes to be called out in the release notes of the next version (where they would notice it and adapt their code accordingly). Smart programmers only rely on documented behaviors. Those who read the code (or experiment) to figure out what something does and then depend on that behavior, get burned when the behavior changes silently in some future version.

I've opened Ticket #15889 for the feature request.

[Mathieu Agopian]

This is my attempt at improving the documentation accordingly to the request.

This documentation improvement will have to be changed once/if the ticket #15889 is checked in!

[Alex Gaynor]

Closing this in favor of #15889.