Re: [pygccxml-development] single/multiple select interface
Brought to you by:
mbaas,
roman_yakovenko
|
From: Matthias B. <ba...@ir...> - 2006-03-13 10:45:50
|
Roman Yakovenko wrote:
> 1) In [1] function name is member_function, while in [2] it is member_functions.
> I think that "s" is essential. First time when an user starts to use this API
> it could be confusing. I think he will expect one m.f. but will get some other
> class instance.
I agree that distinguishing between a "1-result" and a "n-result" query
has its merits. It's a much shorter form of the assert_count argument
which enables the query function to perform a check on the number of
declarations found.
> 2) Return type of functions depends on num_expected argument. This one
> could also confuse.
I think this is only a weak point. In my opinion, the exact type of the
result is an implementation detail that should be of no interest to the
user. The only important thing is what *interface* the resulting
object(s) provide. And here, I'm in favor of keeping the interface
identical (at least as far as decoration is concerned) no matter if the
result references one single object or several objects.
> 3) Lets see some ( == my :-) ) patterns that an user has, while exporting C++
> library:
> [...]
> If I will use [1] approach, I always will be forced to add a
> "num_expected" argument.
Why are you "forced" to do so? In my practical experience with my API
this has not been the case and I was using the explicit assertion only
in one single place.
When you do queries for anything else than methods, then the cases where
the user could be confused are rather rare. Suppose the user queries one
particular class in some namespace:
ns.Class("Foo")
I believe your concerns so far have been that this might confuse a user
when the result actually references more than one class. But when can
that happen at all? C++ doesn't allow several classes with the same name
in one namespace, so the undesired extra class must come from a
namespace that lies within the ns namespace.
In my case, I knew already in advance that all Maya classes are located
in the standard namespace and there are no children namespaces that
carry classes with the same name, so a line like the above could *never*
reference more than 1 class and that's why I didn't need to add the
assert_count argument to my queries.
Don't get me wrong, I'm not arguing against the single/multiple
interface. In fact, in a case like the above I agree that it is even
superior because pyplusplus has more information about what the user
actually intends (and it gets this information with very little effort
from the user).
I just wanted to point out that in most cases my version of the API is
not as confusing as you make it sound sometimes. ;-)
However, it does make a difference when selecting methods (more on that
below).
> 4) Small plus that I see for [1] approach is number of API user should
> see/learn.
> But I don't think that this is makes big difference.
Agreed. This is only a minor (or even irrelevant) point.
> 5) How can an user rename all overloaded functions?
> mfs = module_builder.member_functions( .... )
> mfs.rename( "......" )
> In both solutions it simple
Now that's the area where my concerns have actually been.
In the above example the user *must* know in advance that he's dealing
with a set of overloaded methods, and I think it could happen that he
isn't really aware of the fact that a method has overloads.
What if we treat a set of overloaded methods like one single method? I
might argue that conceptually they already are one single method and
it's only a syntax peculiarity of C++ that they have to be defined as
separate methods (whereas on the Python side they will be combined to
one single method again).
> 6) An other problem that I see in [1] approach. We want multi_decl_wrapper_t
> to behave, as it is an instance of some declaration decorator/wrapper. We can
> implement such behaviour only for "set" properties and functions that user
> does not care about their return values. "get" properties could not be
> implemented at all.
I was always using the result of a query for decorating the
declarations, so there was no case where I had to read attributes.
But this could still be handled as follows: If all declarations return
the same value for a particular attribute then this value is returned,
otherwise None is returned or an exception is thrown.
Basically, I'm in favor of the single/multiple result distinction
because it provides additional information to pyplusplus which can be
used for checks.
The only problematic case is the presence of overloaded methods. Maybe I
like the above exception best (i.e. to treat them as one single
declaration).
- Matthias -
|