Make it possible to discover enumerated values

[Leonard Richardson]

Fields like bug.status can only take on certain values, eg. "Fix Committed". These values are enumerated in the WADL file but there's no way to access this information from launchpadlib.

[Gavin Panella (allenap)]

This is also very confusing for users of searchTasks(). It accepts a
status parameter and a status_upstream parameter. The status is one of
"Fix Released", "Confirmed", etc., but status_upstream is completely
different, being one of "pending_bugwatch", "hide_upstream",
"resolved_upstream", or "open_upstream".

For status_upstream at least, the accepted parameters are not even
enumerated in the WADL. If we don't document enumerated fields there
is almost no way a user can use the API properly from launchpadlib.

The very least Launchpad could do is to return the list of valid
parameters in the error message.

[Leonard Richardson (leonardr)]

The status_upstream problem is different. status_upstream is published as a List of Choice objects. I've never seen that before. lazr.restful knows how to describe a single Choice in WADL, but not a List of Choices. Properly describing that in WADL would require publishing the choice and each of its values as a resource (so that you could have a list of references to its values), which would be a big change.

I recommend checking whether status_upstream really needs to be a List, and if so, filing a separate bug about it.

[Gavin Panella (allenap)]

IBugTaskSearchBase has three fields that are List()s of Choice()s:
status, status_upstream, and importance. They all need to be so (*),
because it's describing a search form.

[* They don't strictly need to be List()s; they could probably be
defined as zope.schema.Iterable, but it's much the same. ]

If these kinds of fields are a somewhat rare occurance, perhaps it'll
be easier to just document them by hand.

I could even apply some level of automation to it, by setting the
field description to something like:

    >>> "Choose from zero or more of: %s" % ", ".join(
    ... term.token for term in field.value_type.vocabulary)

But, there is a danger that this will leak through into the web UI
where it would be inappropriate. Is there, say, a tagged value that I
could set that the API machinery sees as a description for a field?
Then I could even write a simple decorator to generate an API-specific
description for those fields.

[Leonard Richardson (leonardr)]

It's better to solve the problem properly. I filed bug 364596 for this. I mostly focus on a resource-centric solution but I think there's also a solution where we just write a bunch of XML to go in the WADL.

[Bryce Harrington (bryce)]

I listed the four values in the description field for status_upstream. This change is up on edge right now.

(I would prefer to have these shown in the Value column, but couldn't sort out how to do that easily; anyway at least now the issue of them being impossible to discover is solved.)

[Bryce Harrington (bryce)]

Launchpad Bugs task is for addressing the lack of documentation for status_upstream in the API docs.
The launchpadlib task is for the possible values not showing up in the error message.

[Robert Collins (lifeless)]

This looks like it might be fixed in all cases now?

[Leonard Richardson (leonardr)]

Yes, this is available in lazr.restfulclient (and thus launchpadlib) as the lp_values_for attribute.