Re: [pygccxml-development] single/multiple select interface

[Matthias B. <ba...@ir...>]

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 -