Opened 4 years ago

Closed 4 years ago

#15886 closed New feature (duplicate)

Improve django.core.serializers.get_serializer() docs

Reported by: RoySmith 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 magopian 4 years ago.

Download all attachments as: .zip

Change History (7)

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

  • Component changed from Core (Serialization) to 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 4 years ago by RoySmith

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 4 years ago by jacob

  • Easy pickings set
  • Triage Stage changed from Unreviewed to Accepted

comment:4 Changed 4 years ago by magopian

  • Cc mathieu.agopian@… added

Changed 4 years ago by magopian

comment:5 Changed 4 years ago by magopian

  • Has patch set
  • Type changed from Bug to New 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 4 years ago by Alex

  • Resolution set to duplicate
  • Status changed from new to closed

Closing this in favor of #15889.

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