Re: [Modeling-users] API cleanup proposal: CustomObject and related

[Sebastien B. <sbi...@us...>]

And now for CustomObject and related APIs!

  I've thought about it quite a lot since the first proposal. Answers I
  got, including two private ones, helped me a lot. Let me summarize all
  this.

* Backward compatibility is of great concern. This means in particular
  that KeyValueCoding will remain a mix-in for CustomObject, and that
  KeyValueCoding will almost remain as-is. I say almost, because we
  should deprecate (not remove) the methods: setValueForKey(),
  setValueForKeyPath() and setStoredValueForKey(). As Mario already
  wrote in a previous post, their only presence makes it harder to
  understand the API and I fully agree.

  I don't remember when I added this but this was not a brilliant idea.

  Deprecation: means that they will issue a warning (python module
  warnings) when they are used, and they will be removed at a given
  release, to be determined (after 0.9). Note that the framework does
  not use them at all.
                            What do you think?

* I think I made a big mistake when exposing the KeyValueCoding so early
  in the User's Guide --again, Mario already pointed that out. This part
  should be moved in an 'advanced techniques' part in the guide. I
  suspect that this is /one/ of the main reasons why people tends to
  focus on this api, despite the fact that it is definitely not needed
  at first sight.

* What about the new API: I've come to the (still-to-be-discussed)
  conclusion that it should not be mixed-in to CustomObject. While
  making aliases in the framework's core is no problem, adding more
  methods to CustomObject can induce some problem because we would then
  add methods to the users' classes (this was pointed out by one of the
  private mail I got). I tend to agree with that.

  However what we can do is make an alternate module offering both the
  new methods and a mix-in class that people could use in their own
  classes when they prefer it. It seems that this solution addresses the
  request for changing the name while preventing the set of users
  classes' methods to grow unwillingly with aliased methods (no
  functionality added).

* Last, I must say that the other private msg I got supports the KVC and
  considers it better than the new props. As far as I'm concerned, I'm
  not opposed to aliases, but I must admit that my preference goes to
  the original KVC api, well, just like any former NeXTStep or EOF
  developper I guess ;)

CustomObject
------------
  We'll add globalID() in CustomObject if there is no argument
  against. That would be a handy shortcut for:
      obj.editingContext().globalIDForObject(self)
  which is a common idiom for people willing to access the primary keys'
  values while not making them class properties (this question is a
  recurrent one)

Validation
----------
> >   Do we need to change anything there? validateValueForKey() is the
> >   longest one, however I think this is not widely used, is it?
>=20
> I suggest validateProperty() instead of validateValueForKey().

  Here again, backward compatibility means that the old name will be
  kept. Again, this adds an alias and no functionality to
  CustomObject. Moreover, I suspect this is all but a commonly used
  method. I hate saying that but I feel like going one step backward and
  remove the proposal. Please shout at me if you disagree ;)


Back on the new KVC:
--------------------

  Module's name: I'd strongly prefer if it could be explicit rather than
    an acronym (opr). GenericAccess still has my preference but that's
    no strong pref., I'll probably never use it so basically _you_ have
    the lead!

  Methods names: I'm okay to use the full names, but then they will
    sensibly be of the same length than the original ones, compare:

    co.getProperty()
     --valueForKey--

    co.setProperty()
     --setValueForKey--

    co.getStoredProperty()
     --storedValueForKey--

    co.setStoredProperty()
     --setStoredValueForKey--

    co.updateProperties()
     --takeValuesFromDictionary--

    co.updateStoredProperties()
     --takeStoredValuesFromDictionary--

  Up to you, however.


BTW I'll probably extend KVC with valuesForKeys(), counterpart for
    takeValueForKey(). I was surprised to realize it was not there.
    This also means to add something like 'properties()' to the new API
    (which is maybe problematic, I've the feeling that this particular
    name could easily clash with another one defined elsewhere).


  However *if* we agree on what I said above, i.e. that the new KVC will
  not be a mix-in for CustomObject by default, then choosing the new api
  can be decorrelated to the changes made to the core. These changes
  would then only be:

    + CustomObject.globalID()
    + KeyValueCoding.

  (plus the changes made to EditingContext)

        What do you think?

  With best regards,

-- S=E9bastien.