Re: [Modeling-users] API cleanup proposal

[Mario R. <ma...@ru...>]

Hi,

sorry about this reply being so late...  I agree with most of
  what is summarized below, but have a few comments.

A general comment is about the "new" method being an alias
for the "old" method (this may only be a lingo issue). It seems
sensible to me to give the "new" or preferred method the
code, and other methods that need to be supported for
bw compatibility are the aliases (plus an appropriate docstring).
This also helps clarify which methods are to be standardized on.

On mardi, juin 24, 2003, at 11:43 Europe/Amsterdam, Sebastien Bigaret=20
wrote:
>
>         Hi,
>
>   Time to summarize the changes we discussed here:
>
> EditingContext
> --------------
>
>   - insert() is an alias for insertObject()
>
>   - delete() is an alias for 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=20=

> string
>                  isDeep=3D0,       # should subentities be fetched as=20=

> well?
>                 )
>
>     Note that parameters orderBy, limit/page/offset, lock and rawRows
>     have been removed since they are unsupported yet (they will be
>     introduced when support is available).

OK.

>   - make fetchCount() an alias for =
objectsCountWithFetchSpecification()
>       [same API as fetch()]

Hmmn, I would not introduce such a specialized method (will become
clutter even in the short term). As suggested earlier, it may be more
flexible to just have a fetchSql() open method for now (that is not
necessarily db-independent) and that returns whatever the dbapi
returns.  For me nothing is gained by having fetchCount('customobjname')
over fetchSql('select count(*) from tblname') -- it is jn fact less=20
flexibe.
When the time comes to generailize this to be db-independant, either
the fetch() method will gain new parameters to allow this, or other
generic methods introduced, such as fetchRaw, fetchTuples, fetchDicts,
or whatever. fetchSql can always have a use, though, so it it not likely
to become clutter.

>   - make (set)autoInsertion() aliases for
>                             =
(set)propagatesInsertionForRelatedObjects()

OK

> CustomObject
> ------------
>
>   - add globalID()

Yes. The scope of gloabl here is the EditingContext (and children)
or all EditingContexts in this python session, or the current model,
the db, ...

>
> KeyValueCoding
> --------------
>
>   - deprecate methods setValueForKey(), setValueForKeyPath() and
>     setStoredValueForKey()
>
>     I propose to set the removal time for these deprecated methods at
>     version 0.9.1

OK.

>   - add valuesForKeys(), counterpart for takeValuesFromDictionary()
>
>   Additionally, I propose to move the chapter dealing with KVC to an
>   other part in the User's Guide, in some 'advanced techniques'=20
> chapter,
>   so that it is not exposed as it is today.

OK, we can discuss this more (where to move this to in the guide).

> Validation
> ----------
>
>   No changes (because of backward compatibility issues, mainly)
>
>
> About the ``new'' KVC module:
> -----------------------------
>
>   Do we agree that it can be separatedly defined so that users can use
>   it as a mix-in for their classes, at their will? If so, does anyone
>   want to take the lead for this? (meaning at least continuing the
>   discussion and coming to a decision)

I was under the impression that you said it will **not** be a mix-in=20
(as per:
http://sourceforge.net/mailarchive/message.php?msg_id=3D5250043 ).
The interface described in the archive message above is OK for me.
However, if it is to be a mix-in, discussion on this can continue=20
independently
of these changes? In any case, I will be happy to continue to be a part=20=

of
this discussion.


> Future enhancements
> -------------------
>
>   Interesting future features (NOT included in this proposal) have =
been
>   proposed in this thread, including:
>
>     - fetchSQL(): the possibility to pass a raw sql query to build
>       objects,
>
>     - the ability to fetch raw rows (i.e. raw dict) rather than
>       fully-initialized objects,
>
>     - fetchSummary(): adds access to sum()/avg()/... and group=20
> by/having
>       to the fetching API
>
>   We'll probably need to discuss some of these points a bit more,
>   however if you think you'll need one or more of these for the coming
>   releases please fill in a RFE on sourceforge's page and announce it
>   here --this is definitely the best way to make it happen sooner.

OK, except for fetchSQL. I think this should be not so difficult to add=20=

as
a generic method, and will take off the pressure on other premature
additions.

> I'd like to validate the API change proposal for the end of the week,=20=

> if
> possible, so I'd appreciate if you could comment on this in the coming
> days. And BTW thanks a lot for the attention you already paid to this
> topic.
>
>
> -- S=E9bastien.

Also, what about the renaming of =20
addObjectToBothSidesOfRelationshipWithKey()
and removeObjectFromBothSidesOfRelationshipWithKey(), respectively with
addViaRelation() and removeViaRelation() ?

And, yes I think RelationshipManipulation should be combined with KVC
(or whatever this is renamed to --  how about "Access" module
within a CustomObject sub-package ?)


mario