Opened 13 years ago

Closed 13 years ago

#15886 closed New feature (duplicate)

Improve django.core.serializers.get_serializer() docs

Reported by: Roy Smith Owned by: nobody
Component: Documentation Version: 1.3
Severity: Normal Keywords:
Cc: mathieu.agopian@… Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

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).

Attachments (1)

get_serializer_key_error_doc.diff (578 bytes ) - added by Mathieu Agopian 13 years ago.

Download all attachments as: .zip

Change History (7)

comment:1 by Mathieu Agopian <mathieu.agopian@…>, 13 years ago

Component: Core (Serialization)Documentation

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 ;)

comment:2 by Roy Smith, 13 years ago

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.

comment:3 by Jacob, 13 years ago

Easy pickings: set
Triage Stage: UnreviewedAccepted

comment:4 by Mathieu Agopian, 13 years ago

Cc: mathieu.agopian@… added

by Mathieu Agopian, 13 years ago

comment:5 by Mathieu Agopian, 13 years ago

Has patch: set
Type: BugNew feature

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!

comment:6 by Alex Gaynor, 13 years ago

Resolution: duplicate
Status: newclosed

Closing this in favor of #15889.

Note: See TracTickets for help on using tickets.
Back to Top