object wrapper for query includes

[alastair]

Python-musicbrainz2 has classes for encapsulating what entities to include with a query, e.g. http://users.musicbrainz.org/~matt/python-musicbrainz2/html/musicbrainz2.webservice.TrackIncludes-class.html

We could consider having the same for queries

[sampsyo]

I'm not sure how other people have experienced it, but I personally found this particular facet of py-mb2 to be quite cumbersome -- instead of just making a list, I had to construct a special object that had its own separate documentation page. Maybe there's a way this could be more succinct and clear, but I'm not certain making a plethora of special classes for each entity type is the most elegant solution.

[alastair]

I suppose I like it because it's (relatively) explicit as to what things you're allowed to ask for in a query. Alternate ways of asking for the same information:

• A parameter that's a list of options (hard to discover correct options to put, other than reading docs)
• Explicit parameters: inc-artists=True, inc-releases=True (explicit, but lots of parameters for each method)
• **kwargs wrapper around explicit parameters (still hard to discover valid options without looking at docs)

[sampsyo]

You're right that the bunch-of-classes approach does make everything very explicit. I'm just not sure if that actually helps programmers (especially in a dynamic language like Python). For example, here's a possible thought process of someone trying to use the library:

I'd like to look up an artist and it looks like get_artist_by_id is the thing I need. Hmm, I wonder what the options are for includes with that? I'll just try:

$ pydoc musicbrainz.get_artist_by_id

(Or look at the HTML documentation for the function.)

At this point, if there's a special class, I still don't know what to do -- I have to look at the documentation for that class, whose constructor eventually just has a bunch of keyword parameters itself (presumably). With "real" keyword arguments or **kwargs, the possible values are right there, either in the function signature or the docstring.

(As an aside, having special objects would probably be the right way to go with a static language -- there, you'd want to get a compile-time error for using the wrong values. But in Python, the error happens at run time anyway.)

[JonnyJD]

Since the possible includes can be represented in a simple list, we can document these in the docstrings. I would go that way.

[JonnyJD]

@alastair: close as this isn't something that will happen?