Opened 6 years ago

Closed 6 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:


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 6 years ago.

Download all attachments as: .zip

Change History (7)

comment:1 Changed 6 years ago by Mathieu Agopian <mathieu.agopian@…>

Component: Core (Serialization)Documentation
Needs documentation: unset
Needs tests: unset
Patch needs improvement: unset

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, 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 Changed 6 years ago by 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.

comment:3 Changed 6 years ago by Jacob

Easy pickings: set
Triage Stage: UnreviewedAccepted

comment:4 Changed 6 years ago by Mathieu Agopian

Cc: mathieu.agopian@… added

Changed 6 years ago by Mathieu Agopian

comment:5 Changed 6 years ago by Mathieu Agopian

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 Changed 6 years ago by Alex Gaynor

Resolution: duplicate
Status: newclosed

Closing this in favor of #15889.

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