Re: [Modeling-users] API cleanup proposal

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

        Hi,

Mario Ruggier <ma...@ru...> wrote:
> On mercredi, juil 2, 2003, at 11:05 Europe/Amsterdam, Jerome Kerdreux wro=
te:
> > Mario Ruggier wrote:
> >
> > 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 standardiz=
ed
> > on.
> > Hum .. A general note about aliasing methods: In fact
> > I use a couple of tools for test (SQLObject / MiddleKit/
> > and Modeling) so as MiddleKit and Modeling try to
> > monkey EOF, it use the same method names like
> > insertObject() .. so for me staying closer to EOF is a good
> > thing .
>=20
> That would be fine. My point was that whatever method
> name is preferred, then this should be the "master" and
> others that do same thing are aliases. This is irrespective of
> whether the preferred method name is the same as in the
> EOF or not.

I see your points here, both; I have no definitive answer, my point of
view is a bit different.

- real aliases, i.e. methods w/ different name but w/ the very same
  functionality as the aliased methods (insert(), delete(),
  setAutoInsertion), all these have in my mind the very same status.

    In the code point of view, they'll be made by simple assignments:
  'insert=3DinsertObject'; they'll actually *be* the very same method,
  sharing code and docstrings.

    In a developer's point of view, I guess the preference will go here
  or there; if you're used to sql, 'insert' will probably be natural,
  while 'insertObject' will come up more easily if you already know
  SQLObject or the EOF.

    So I won't say there will be a preference in itself between these,
  only a personal preference. Even if they appear in different
  circumstances, historical or at users' request, they are, and probably
  will remain, identical.

- Framework's enhancements: fetch(), fetchCount()

  These are not just aliases: you can think of the fa=E7ade design
  pattern. They alleviate the developer's work by offering a simpler and
  handier API to fetch objects.

    Here again, I won't say that there will be a preferred one in the
  absolute. fetch() is a real enhancement and I'm glad it's showing up,
  because having to import modules, then instanciate a Qualifier and a
  FetchSpecification just to fetch some objects is just more painful
  than simply call fetch with the needed parameters.

    However, the "old way" remains meaningful --and different, because
  it offers plain control over the different objects collaborating
  within the framework at some point (here, when fetching). It will
  eventually be moved into an 'advanced techniques' section, of course,
  and handier methods will be introduced first; after all, the framework
  is supposed to make it easy to access to objects stored in a db!


An other slighty-different question to which Mario was probably
referring to is what are the methods you need to know at first sight,
and what are those that you can safely ignore if you do not want to
fine-tune the framework, or if you don't have time to dive too deeply
into it. This is an important issue I'm aware of. I already said here
that I'm looking for a solution to distinguish the one from the others
in the documentation. I haven't spent on it, still, but this *will* be
addressed in the future.


  Sorry, I leave the other interesting points pending --mostly because
  they are out of the scope of the actual API changes, and because I
  need some rest now ;) But we'll get back to these for sure, and maybe
  Soif could elaborate a bit further on his CustomSearch example? It
  would be interesting to see how this compares to the other approaches
  we already discussed here.

        Cheers,

-- S=E9bastien.