gavel-team team mailing list archive

[Joshua Gardner <mellowcellofellow@xxxxxxxxx>]

I'm having second thoughts about using REST as an architecture for
Gavel, and here's why: not enough verbs.

While there are more HTTP verbs, the ones that REST normally uses, and
piston is set up by default for, are GET (Read without modifying), POST
(create a new item), PUT (modify an existing item), and DELETE (remove
an existing item). Like I said, there are others. The as-yet
unstandardized PATCH looks promising, use it mean Amend in parli-pro
speak.

But I'm not sure even that's enough. In parliamentary procedure, a
motion is both a noun and a verb. The language of a motion is verbal,
it specifies something that the body will do. Resolutions are also
verbal. Only debate includes purely factual data, and even then it's
generally structured in a persuasive argument. But at the same time
that a motion or a resolution is verbal, it is also a noun that can be
acted upon, using other motions.

So, a motion is itself a verb, and a noun. Of course, what a motion
actually does is outside of the Gavel software, so we can treat a
motion as purely a noun. But that's just main motions. An amendment is
a noun, but its purpose is to amend (verb) a motion, even another
amendment.

So, I'm just wondering if that can be squeezed into a RESTful API.
Naturally, if amend is a verb on a motion, the syntax should be
motion.amend("Text of amendment"). Attached (amendment.py) is an
example of how it might work.

I'm sure we can make this work, just not sure if REST fits, unless we
can find enough HTTP verbs to get the job done. We could easily switch
to JSON-RPC (which fits nicely with Pyjamas anyway) and then have all
the verbs we could ever want.

-Josh


#!/usr/bin/env python
from difflib import ndiff

class Motion(object):
    def __init__(self, text):
        self.text = text
    
    def amend(self, amend_text):
        self.amendment = Amendment(self, amend_text)
        return self.amendment

class Amendment(Motion):
    def __init__(self, motion, text):
        self.motion = motion
        super(Amendment, self).__init__(text)

    def speak(self):
        """
        Returns the amendment in the language of an amendment motion.
        Example: "I move to strike foo and insert bar."

        This will take some work.
        """
        return ''

    def diff(self):
        """
        Returns the amendment in the form of a patch.
        """
        diff = ndiff(self.motion.text.splitlines(1),
                     self.text.splitlines(1))
        return '\n'.join(diff)
    
    def commit(self):
        """
        Commits the amendment to the parent motion.
        """
        self.motion.text = self.text
        del self.motion.amendment


def main():
    motion = Motion("Write a parliamentary procedure program.")
    motion.amend("Write a web-based parliamentary procedure program.")
    print motion.amendment.diff()
    motion.amendment.commit()
    print motion.text

if __name__ == '__main__':
    main()