On Sun, Apr 3, 2011 at 6:58 AM, DaNmarner <danmar...@gmail.com> wrote:
> I've got some more crystalized details about my proposal.
>
> Here are the target result if this proposal is implementated:
>
> 1. User could configure serialization for each model.
>
> 2. In fact, user could configure the serialization details down to
> each field
> of each model. That means:
>
> 3. The key name of each field would be freely defined, the value would
> be
> freely and dynamically defined.
>
> 4. Nested structure could be represented as either fk or get
> serialized as
> substructures in the result.
>
> 5. The depth of serializaton can be defined, again, down to each
> field.
>
> 6. Various bonuses. e.g. "sorters" for serialized result, values
> that's not
> from the query set, etc.
>
>
> First off, the current assumption on the structure of a Model, as far
> as
> serialization is concerned, should be changed. I propose that we look
> at the
> model as a flat key-value structure, that is, pk and model name (and
> potentially other metadata) are no different to a user-defined field.
>
> That is the base of everything below. So from now on, I'll stop
> distinguishing
> user-defined fields, pk and metadata in my discussion, and call them
> "fields"
> instead.
>
> I want to add APIs targeting two level of abstraction:
>
> "class SerializedModel": used to customize how each model is
> serialized.
>
> "class SerializedField": used to customize how each field is
> serialized.
>
> They are to be subclassed by user, serving as configuration for
> serialization.
> SerializedModel will be passed as options to the actual serializaton
> module and
> be referenced to through out the process.
>
> How to achieved those goals in my claim? Let's see what's in those
> classes.
>
> The meat of things lies in the SerializedField class, I want to
> introduce the
> proposed attributes of this class one by one, along each I'll try
> explain my
> reasoning behind it and it's relevance to my goals.
>
> Some "regular" parts of a field:
>
> "key_name": the name to be used for this field, defaults to the field
> name(pk,
> model, album). This allows user to represent the field in whatever
> name they
> want.
>
> "with_type": a boolean, this let user deside whether the type of this
> field
> should be part of the result.
>
> "value_format": default to string repr of the field value, but if the
> user
> want, she can assign a function to value_format to twist the value
> however she
> like and return. More on this attr below.
>
> "belongs_to": where in the result does the field go, default to top
> level. If
> we were to mimic the current serialization format, this value for all
> the
> user-defined fields would be "field".
>
> "as_tag": a boolean. This is here specifically for XMLSerializer. If
> set false,
> it causes the field to be rendered as attrs. There's more on this part
> below.
>
> If the field references to other models, these addtional attrs for
> SerializedField would be used:
>
> "rel_name": similar to "key_name", but it is for the relation type, if
> renderd.
> defaults to "rel", as it would be if we were to mimic current XML
> format.
>
> "rel_to_name": similar to "key_name" and "rel_name", the key in the
> result
> whose value is the model this field points to.
>
> "with_rel": boolean, determines whether the two fields above shoud be
> part of
> the result.
>
> "embed_level": an integer. This is my answer to the question "how to
> handle
> nested objects?". And it deserves its own paragraph.
>
> For a reference-typed field, the value of SerializedField.value_format
> should
> be an instance of SerializedField. If "embed_level" is 0, then only
> the foreign
> key will be rendered. If it is greater than 0, then the serializer
> should go
> ahead and serialize whatever this field points to according to the
> info
> contained in "value_format". "embed_level" would be initialized each
> time an
> instance of SerializedField is instantiated, which happens when the
> serializer
> discovers embed_level > 0. Another related note is, when "embed_level"
>> 0,
> "as_tag" would be forced to be True.
>
>
> Compare to SerializedField, SerializedModel is much simpler. It's
> function is
> no more than holding info about which field should be included in the
> serialization, and mapping the wanted field to its SerializedField
> instance.
> Inspired by contrib.admin.ModelAdmin, SerializedModel has two
> attributes:
>
> "exclude": a list of unwelcomed fields referenced by their str names.
>
> "fields": a dict whose keys are str names of wanted fields, and the
> values are
> SerializedField instances.
>
> If nessacery, a "sorter" fields which accept a sorter function for the
> result
> serialization might be included as well.
>
> The new serialization framework would include default
> SerializationField for
> all the "native" field types, so that users don't have to create one
> for each
> fields.
>
> Here's an illustration of how a simple use case looks like, taking the
> models
> from the tutorial as an example:
>
> class SerializedChoiceText(DefaultSerializedCharField): key_name =
> "choice_text" value_fmt = lambda x: x.lowercase() as_tag = True #
> default value
> belongs_to = "field"
>
> class SerializedChoice(DefaultSerializedModel): exclude = ["votes"]
> fields = {
> 'pk': DefaultSerialiazedPkField(), 'classname':
> DefaultClassnameSeializedField(), 'choice': SerializedChoiceText(),
> 'poll':
> DefaultSerializedFkField( embed_level=1,
> value_fmt=DefaultSerializedModel()) }
>
> data = serializer.serialize('xml', Choice.objects.all(),
> SerializedChoice())
>
> data would contain something similar to what the current XMLSerializer
> yields
> except:
>
> 1. No votes number.
>
> 2. The tag for poll now contains a sublevel tag that has a
> serialized poll
> object in it.
>
> 3. The text of the choise is in lowercase.
>
> And that roughly covers the API design in my proposal.
>
> In implementation, the structure of the serializers should be somewhat
> similar
> to the current ones, since the whole idea is to add more
> configurations.
While I don't doubt you've put a lot of thought into this proposal, it
has two major drawbacks:
1) It's almost illegible. Between your mail client's munging of line
wrapping, and the completely unreadable code samples, it's very
difficult to tell if you have presented a good idea.
2) You haven't done the one thing that the Django GSoC wiki recommends
-- provide, as a proof of your concept, an expression of Django's own
serializers using your proposed serialization syntax.
If you'd done any research on the topic, you'd find that I've raised
the second point every single time this topic is proposed -- in fact,
there's a currently active django-dev discussion with another student
proposing a serialization project.
If you're serious about pursuing serialization as a GSoC project, I
suggest you provide the proof of concept that has been asked for. If
you want to really impress, find the other currently active discussion
and use the pathological serialization case that I've provided there
as a further demonstration that your proposed API will work.
(And just to make sure there isn't confusion -- the example you've
provided *isn't* what is required. Django's existing serializer
doesn't need any per-model configuration in order to operate. It is
able to work on any model and provide a consistent serialized output.
While a good serialization proposal will allow for customization, this
baseline -- without customization, working on any model without to
produce the current format -- is the absolute minimum proof of
concept).
Yours,
Russ Magee %-)
--
You received this message because you are subscribed to the Google Groups
"Django developers" group.
To post to this group, send email to django-developers@googlegroups.com.
To unsubscribe from this group, send email to
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/django-developers?hl=en.
