[Modeling-users] API cleanup proposal

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

        Hi all,

  Here is a proposal to change some of the most commonly used methods;
the general idea is to improve developers' experience with the framework
by providing better, cleaner, shorter names for existing functionalities.

 [Note on "most commonly used methods": I do not plan to change every
  method's name when it's too long: they are mostly for the framework's
  use, or at best for advanced usage]


EditingContext (remember: an EC can be thought as a transaction)
--------------

  - insert() instead of insertObject()

  - delete() instead of deleteObject()

  - fetching: remove the need to import FetchSpecification and
    Qualifier, and propose an alternate for
    objectsWithFetchSpecification()

       def fetch(self, entityName,
                 qualifier=3DNone, # either a Qualifier instance or a string
                 orderBy=3DNone,   # either a SortOrdering or a string
                 isDeep=3D0,       # should subentities be fetched as well?
                 refresh=3D0,      # unsupported yet
                 lock=3D0,         # unsupported yet
                 limit=3DNone,     # \
                 page=3DNone,      #  > slice parameters, not in core yet
                 offset=3DNone,    # /  (page/offset: mutually exclusive)
                )
=20=20=20=20
    Typical usage:

      ec.fetch('Writer', 'lastName ilike "hu?o"')
      ec.fetch('Writer', 'age>=3D80"')
      ec.fetch('Writer', 'author.pygmalion.lastName caseInsensitiveLike "r*=
"')
      ec.fetch('Writer', orderBy=3D'firstName asc, lastName desc', isDeep=
=3D1)
      ec.fetch('Books', orderBy=3D'title', limit=3D10, page=3D1)

  - replace objectsCountWithFetchSpecification() with fetchCount() ?
      [same API as fetch()]

  - replace (set)propagatesInsertionForRelatedObjects() with
    autoInsertion() and setAutoInsertion()


CustomObject
------------

  I don't see any methods to change here. Maybe we could add globalID()?
  However, the name itself 'CustomObject' could be changed if you have
  some ideas (I admit it is not very representative of what it does,
  i.e. defining generic methods for an object to be bound w/ the
  framework)


Validation
----------

  Do we need to change anything there? validateValueForKey() is the
  longest one, however I think this is not widely used, is it?


KeyValueCoding
--------------

  As Mario repeatedly pointed it out some time ago, this module needs to
  be cleaned.

  Core methods:


          |   [public access]         |    [private access]
    ------+---------------------------+----------------------------------
    [get] |valueForKey()              | storedValueForKey()
          |valueForKeyPath()          |
    ------+---------------------------+----------------------------------
    [set] |takeValueForKey()          | takeStoredValueForKey()
          |takeValueForKeyPath()      |
    ------+---------------------------+----------------------------------
    [dict]|takeValuesFromDictionary() | takeStoredValuesFromDictionary()
=20=20
  Quick reminder: KVC is intensively used by the framework to get & set
                  an object's values without knowing where it is
                  actually stored (for example, attribute 'name' can be
                  stored in name, _name, and/or can be accessed/set via
                  getters/setters name/getName()/setName())

  The framework *always* uses the so-called "private" access
  methods. The reason is that e.g. a public setter can have some
  side-effect that should be triggered from a user's point of view (at
  creation or modification time), but shouldn't be triggered when
  object's data are fetched from the db (this is not very common,
  though, hence I think we need a simplified and more efficient KVC for
  the common cases --off-topic here).

  This is my proposal:

  * getProp(name, path):

       getProp(key)          replaces valueForKey(key)
       getProp(path=3DkeyPath) replaces valueForKeyPath(keyPath)

  * setProp(name, path):

       setProp(key)          replaces takeValueForKey(key)
       setProp(path=3DkeyPath) replaces takeValueForKeyPath(keyPath)

  * same for getStoredProp() and setStoredProp() which replace
    (take)storedValueForKey
=20=20
 Notes: - parameters name & path are obviously mutually exclusive,
        - get/setStoredProp shouldn't be needed from a developer's point
          of view.

  * updateProps()       replaces takeValuesFromDictionary()
    updateStoredProps() replaces takeValuesFromStoredDictionary()


  Along with that, we also need an other module/class name for
  KeyValueCoding.

  Mario proposed PropValueAccess. Any ideas?
                                            GenericAccess? PropHandling?


RelationshipManipulation
------------------------

  Any thoughts about how addObjectToBothSidesOfRelationshipWithKey() and
  removeObjectFromBothSidesOfRelationshipWithKey() can be renamed?=20



=3D> An other solution could be: gather KVC and RelationshipManipulation
   in a single module, since they both address the same thing: generic
   manipulation of an object, given its definition in the model. What do
   you think?


BTW this is not a definitive list, just the things I know that need to
be changed. If you feel like changing other names please tell.


  Your feedback is greatly appreciated!-)


-- S=E9bastien.