[Freeipa-devel] [PATCH] jderose 027 Extensible return values

[Jason Gerard DeRose]

This patch is big.  There are some significant changes, but easily 50%
of this patch is made up of small changes to plugins and their unit
tests to port them to the lower-level API changes.  All unit tests pass
assuming you install without the --ca option.  I didn't touch the
cert/ra plugins as I know John has pending changes there.

Here's a summary:

1. Our standard return value is now a dict, which gives us a nice way to
extend the API without breaking clients/code.  So in this respect, the
return values are more deeply nested.  Basically if you returned 'foo'
before, now you return {'result': 'foo'}.


2. Previously nested data-structures have been flattened.  Most
importantly, these have been changed:

  Entry: [dn, entry] => {'result': entry}
  Entries: [entries, truncated] => {'result': entries, 'truncated': truncated}

This was mostly done so that an entry/row/object/whatever can be
consistently represented as a dict... whether it's from LDAP, or a
database, or whatever else IPA might get glued into.  Likewise, lists
are now consistently used to represent lists of things, rather than also
a struct-like pair, triple, etc.


3. We now have a way to specify a return value schema, and this schema
is enforced.  The top-level schema of the return value dict is described
using the Param-like classes in ipalib/output.py.  For example:

  from ipalib import output

  class user_add(LDAPCreate):

      has_output = (
          output.Entry('result'),
          output.Output('primary_key', unicode, 'The user uid')
      )

This hypothetical `user_add` expects you to return something like this:

  dict(
      result=dict(givenname=u'Foo', sn=u'Bar', uid=u'fbar'),
      primary_key=u'fbar',
  )

A few commands have C clients whose API would break with these changes.
If your command is one of them, you can disable the return value
validation for now by setting the 'use_output_validation' attribute to
False, like this:

  class join(Command):
      use_output_validation = False

I already did this for join so the installer doesn't break.

The plugin browser now shows the output schema.  Just fire up the
in-tree server like this:

  ./lite-server.py

And then go to http://localhost:8888/ipa/ui/Command


4. I'm using the return values themselves to drive CLI and webUI output.
As I've worked on extending meta-data for the webUI, I've realized a lot
of it can be delivered in the return values themselves.  This is good
because we display the output more on what the commands actually return,
less on what they merely say they will return... this keeps us honest
and is another way to ensure we live up to our API contracts.

My goal is to have a single base output_for_cli() implementation, and
this patch get's us 90% there already.  Not all the commands have been
updated, but this will continue in additional patches (or be delegated).

More webUI functionality has been enabled also, but not as much as I
hoped for as work on the command plugins took so much time.  The
commands return a page now instead of JSON.


5. I stubbed out the remained missing gettext features we need.  They
aren't hooked up to gettext yet, but for plugin writers, the API is now
complete.  See ipalib/text.py for the implementation and
ipalib/plugins/user.py for a good example of how they are used.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: freeipa-jderose-027-Extensible-return-values.patch
Type: text/x-patch
Size: 177821 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/freeipa-devel/attachments/20091125/96b0c9b4/attachment.bin>