Tidy up docstrings to follow the PEP-257 docstring convention0.0.2

http://www.python.org/dev/peps/pep-0257/

Change-Id: I1469a94f01660ef00aac196a5ca8995b3803a4bd

6 files changed, 110 insertions, 126 deletions

diff --git a/pygerrit/error.py b/pygerrit/error.py
index 51ab039..d52eb6c 100644
--- a/pygerrit/error.py
+++ b/pygerrit/error.py
@@ -2,4 +2,7 @@
 
 
 class GerritError(Exception):
-    ''' Raised when something goes wrong in Gerrit handling. '''
+
+    """ Raised when something goes wrong in Gerrit handling. """
+
+    pass
diff --git a/pygerrit/events.py b/pygerrit/events.py
index 96085c0..90459f4 100644
--- a/pygerrit/events.py
+++ b/pygerrit/events.py
@@ -5,18 +5,16 @@ from pygerrit.models import Account, Approval, Change, Patchset, RefUpdate
 
 
 class GerritEvent(object):
-    ''' Gerrit event base class.
-    '''
+
+    """ Gerrit event base class. """
 
     def __init__(self):
         pass
 
 
 class PatchsetCreatedEvent(GerritEvent):
-    ''' Representation of the Gerrit "patchset-created" event described in
-    `json_data`.
-    Raise GerritError if any of the required fields is missing.
-    '''
+
+    """ Gerrit "patchset-created" event. """
 
     def __init__(self, json_data):
         super(PatchsetCreatedEvent, self).__init__()
@@ -29,10 +27,8 @@ class PatchsetCreatedEvent(GerritEvent):
 
 
 class DraftPublishedEvent(GerritEvent):
-    ''' Representation of the Gerrit "draft-published" event described in
-    `json_data`.
-    Raise GerritError if any of the required fields is missing.
-    '''
+
+    """ Gerrit "draft-published" event. """
 
     def __init__(self, json_data):
         super(DraftPublishedEvent, self).__init__()
@@ -45,10 +41,8 @@ class DraftPublishedEvent(GerritEvent):
 
 
 class CommentAddedEvent(GerritEvent):
-    ''' Representation of the Gerrit "comment-added" event described in
-    `json_data`.
-    Raise GerritError if any of the required fields is missing.
-    '''
+
+    """ Gerrit "comment-added" event. """
 
     def __init__(self, json_data):
         super(CommentAddedEvent, self).__init__()
@@ -66,10 +60,8 @@ class CommentAddedEvent(GerritEvent):
 
 
 class ChangeMergedEvent(GerritEvent):
-    ''' Representation of the Gerrit "change-merged" event described in
-    `json_data`.
-    Raise GerritError if any of the required fields is missing.
-    '''
+
+    """ Gerrit "change-merged" event. """
 
     def __init__(self, json_data):
         super(ChangeMergedEvent, self).__init__()
@@ -82,10 +74,8 @@ class ChangeMergedEvent(GerritEvent):
 
 
 class ChangeAbandonedEvent(GerritEvent):
-    ''' Representation of the Gerrit "change-abandoned" event described in
-    `json_data`.
-    Raise GerritError if any of the required fields is missing.
-    '''
+
+    """ Gerrit "change-abandoned" event. """
 
     def __init__(self, json_data):
         super(ChangeAbandonedEvent, self).__init__()
@@ -102,10 +92,8 @@ class ChangeAbandonedEvent(GerritEvent):
 
 
 class ChangeRestoredEvent(GerritEvent):
-    ''' Representation of the Gerrit "change-restored" event described in
-    `json_data`.
-    Raise GerritError if any of the required fields is missing.
-    '''
+
+    """ Gerrit "change-restored" event. """
 
     def __init__(self, json_data):
         super(ChangeRestoredEvent, self).__init__()
@@ -122,10 +110,8 @@ class ChangeRestoredEvent(GerritEvent):
 
 
 class RefUpdatedEvent(GerritEvent):
-    ''' Representation of the Gerrit "ref-updated" event described in
-    `json_data`.
-    Raise GerritError if any of the required fields is missing.
-    '''
+
+    """ Gerrit "ref-updated" event. """
 
     def __init__(self, json_data):
         super(RefUpdatedEvent, self).__init__()
diff --git a/pygerrit/models.py b/pygerrit/models.py
index 9f3b787..c8c70d5 100644
--- a/pygerrit/models.py
+++ b/pygerrit/models.py
@@ -4,10 +4,8 @@ from pygerrit.error import GerritError
 
 
 class Account(object):
-    ''' Representation of the Gerrit user account (name and email address)
-    described in `json_data`.
-    Raise GerritError if name or email address field is missing.
-    '''
+
+    """ Gerrit user account (name and email address). """
 
     def __init__(self, json_data):
         try:
@@ -21,9 +19,8 @@ class Account(object):
 
 
 class Change(object):
-    ''' Representation of the Gerrit change described in `json_data`.
-    Raise GerritError if any of the required fields is missing.
-    '''
+
+    """ Gerrit change. """
 
     def __init__(self, json_data):
         try:
@@ -39,9 +36,8 @@ class Change(object):
 
 
 class Patchset(object):
-    ''' Representation of the Gerrit patch set described in `json_data`.
-    Raise GerritError if any of the required fields is missing.
-    '''
+
+    """ Gerrit patch set. """
 
     def __init__(self, json_data):
         try:
@@ -54,11 +50,8 @@ class Patchset(object):
 
 
 class Approval(object):
-    ''' Representation of a Gerrit approval (verification, code review, etc)
-    described in `json_data`.
-    Raise GerritError if a required field is missing or has an
-    unexpected value.
-    '''
+
+    """ Gerrit approval (verified, code review, etc). """
 
     def __init__(self, json_data):
         if "type" not in json_data:
@@ -74,9 +67,8 @@ class Approval(object):
 
 
 class RefUpdate(object):
-    ''' Representation of the Gerrit ref update described in `json_data`.
-    Raise GerritError if any of the required fields is missing.
-    '''
+
+    """ Gerrit ref update. """
 
     def __init__(self, json_data):
         try:
diff --git a/pygerrit/stream.py b/pygerrit/stream.py
index 97daca6..d59dbb8 100644
--- a/pygerrit/stream.py
+++ b/pygerrit/stream.py
@@ -6,7 +6,7 @@ Class to listen to the Gerrit event stream and dispatch events.
 
 import json
 
-from events import PatchsetCreatedEvent, \
+from pygerrit.events import PatchsetCreatedEvent, \
     RefUpdatedEvent, ChangeMergedEvent, CommentAddedEvent, \
     ChangeAbandonedEvent, ChangeRestoredEvent, \
     DraftPublishedEvent
@@ -23,14 +23,15 @@ REF_UPDATED = "ref-updated"
 
 
 class GerritStreamError(Exception):
-    ''' GerritStreamError is raised when an error occurs while
-    reading the Gerrit events stream.
-    '''
+
+    """ Raised when an error occurs while reading the Gerrit events stream. """
+
+    pass
 
 
 class GerritStream(object):
-    ''' Gerrit stream handler.
-    '''
+
+    """ Gerrit events stream handler. """
 
     # Map the event types to class names.
     _event_dict = {CHANGE_MERGED: "ChangeMergedEvent",
@@ -45,10 +46,12 @@ class GerritStream(object):
         self.listeners = []
 
     def attach(self, listener):
-        ''' Attach the `listener` to the list of listeners.
+        """ Attach the `listener` to the list of listeners.
+
         Raise GerritStreamError if the listener does not match the
         expected signature, or if its event handler is not callable.
-        '''
+
+        """
         if not hasattr(listener, "on_gerrit_event"):
             raise GerritStreamError("Listener must have `on_gerrit_event` "
                                     "event handler method")
@@ -60,8 +63,7 @@ class GerritStream(object):
             self.listeners.append(listener)
 
     def detach(self, listener):
-        ''' Remove the `listener` from the list of listeners.
-        '''
+        """ Remove the `listener` from the list of listeners. """
         if listener in self.listeners:
             try:
                 self.listeners.remove(listener)
@@ -69,11 +71,12 @@ class GerritStream(object):
                 pass
 
     def _get_event(self, json_data):
-        ''' Create a new 'GerritEvent' from the JSON object
-        described in `json_data`.
-        Return an instance of one of the GerritEvent subclasses.
+        """ Create a new event from `json_data`.
+
+        Return an instance of one of the `GerritEvent` subclasses.
         Raise GerritStreamError if any error occurs.
-        '''
+
+        """
         event_type = json_data["type"]
         if event_type in self._event_dict:
             classname = self._event_dict[event_type]
@@ -85,14 +88,12 @@ class GerritStream(object):
         raise GerritStreamError("Unexpected event type `%s`" % event_type)
 
     def _dispatch_event(self, event):
-        ''' Dispatch the `event` to the listeners.
-        '''
+        """ Dispatch the `event` to the listeners. """
         for listener in self.listeners:
             listener.on_gerrit_event(event)
 
     def stream(self, inputstream):
-        ''' Listen to the `inputstream` and handle JSON objects.
-        '''
+        """ Listen to the `inputstream` and handle JSON objects. """
         try:
             done = 0
             while not done:
diff --git a/tests/gerrit_stream/unittest_gerrit_stream_attach_detach/unittests.py b/tests/gerrit_stream/unittest_gerrit_stream_attach_detach/unittests.py
index 5b2db25..c6cc3ca 100755
--- a/tests/gerrit_stream/unittest_gerrit_stream_attach_detach/unittests.py
+++ b/tests/gerrit_stream/unittest_gerrit_stream_attach_detach/unittests.py
@@ -1,21 +1,25 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
+""" Unit tests for the stream attach/detach functionality. """
+
 import unittest
 
 from pygerrit.stream import GerritStream, GerritStreamError
 
 
 class ListenerWithNoHandler():
-    """ Dummy listener class with no event handler.
-    """
+
+    """ Dummy listener class with no event handler. """
+
     def __init__(self):
         pass
 
 
 class ListenerWithInvalidHandler():
-    """ Dummy listener class with invalid event handler.
-    """
+
+    """ Dummy listener class with invalid event handler. """
+
     def __init__(self):
         pass
 
@@ -24,9 +28,8 @@ class ListenerWithInvalidHandler():
 
 
 class ListenerWithInvalidHandlerNotCallable():
-    """ Dummy listener class with invalid event handler
-    that is not callable.
-    """
+
+    """ Dummy listener class with event handler that is not callable. """
 
     on_gerrit_event = "this is a string"
 
@@ -35,8 +38,9 @@ class ListenerWithInvalidHandlerNotCallable():
 
 
 class ListenerWithValidHandler():
-    """ Dummy listener class.
-    """
+
+    """ Dummy listener class. """
+
     def __init__(self):
         pass
 
@@ -45,37 +49,44 @@ class ListenerWithValidHandler():
 
 
 class TestGerritStreamAttachDetach(unittest.TestCase):
-    """ Test that the attach and detach methods in the GerritStream
-    class behave correctly.
-    """
+
+    """ Test that the attach and detach methods behave correctly. """
 
     def test_listener_no_handler(self):
-        """ Test that an exception is raised if a listener is
-        attached without an event handler method.
+        """ Listener without event handler.
+
+        Test that an exception is raised if a listener is attached without
+        an event handler method.
+
         """
         g = GerritStream()
         l = ListenerWithNoHandler()
         self.assertRaises(GerritStreamError, g.attach, l)
 
     def test_listener_invalid_handler(self):
-        """ Test that an exception is raised if a listener is
-        attached with an invalid event handler method.
+        """ Listener with invalid handler method.
+
+        Test that an exception is raised if a listener is attached with an
+        invalid event handler method (does not have correct signature).
+
         """
         g = GerritStream()
         l = ListenerWithInvalidHandler()
         self.assertRaises(GerritStreamError, g.attach, l)
 
     def test_listener_non_callable_handler(self):
-        """ Test that an exception is raised if a listener with
-        non-callable event handler is added.
+        """ Listener with non-callable handler.
+
+        Test that an exception is raised if a listener with non-callable
+        event handler is added.
+
         """
         g = GerritStream()
         l = ListenerWithInvalidHandlerNotCallable()
         self.assertRaises(GerritStreamError, g.attach, l)
 
     def test_listener_valid_handler(self):
-        """ Test that a valid listener can be added.
-        """
+        """ Test that a valid listener can be added. """
         g = GerritStream()
         l = ListenerWithValidHandler()
         self.assertEquals(len(g.listeners), 0)
@@ -84,8 +95,7 @@ class TestGerritStreamAttachDetach(unittest.TestCase):
         self.assertEquals(g.listeners[0], l)
 
     def test_add_same_listener_multiple_times(self):
-        """ Test that the same listener will only be added once.
-        """
+        """ Test that the same listener will only be added once. """
         g = GerritStream()
         l = ListenerWithValidHandler()
         self.assertEquals(len(g.listeners), 0)
@@ -97,8 +107,7 @@ class TestGerritStreamAttachDetach(unittest.TestCase):
         self.assertEquals(g.listeners[0], l)
 
     def test_add_multiple_listeners(self):
-        """ Test that multiple listeners can be added.
-        """
+        """ Test that multiple listeners can be added. """
         g = GerritStream()
         l = ListenerWithValidHandler()
         self.assertEquals(len(g.listeners), 0)
@@ -112,8 +121,7 @@ class TestGerritStreamAttachDetach(unittest.TestCase):
         self.assertEquals(g.listeners[1], l2)
 
     def test_detach_listener(self):
-        """ Test that a listener can be detached.
-        """
+        """ Test that a listener can be detached. """
         g = GerritStream()
         l = ListenerWithValidHandler()
         self.assertEquals(len(g.listeners), 0)
@@ -124,8 +132,11 @@ class TestGerritStreamAttachDetach(unittest.TestCase):
         self.assertEquals(len(g.listeners), 0)
 
     def test_detach_not_attached_listener(self):
-        """ Test that the class behaves correctly if a not-attached
+        """ Detach non-attached listener.
+
+        Test that the class behaves correctly if a not-attached
         listener is detached.
+
         """
         g = GerritStream()
         l = ListenerWithValidHandler()
diff --git a/tests/gerrit_stream/unittest_gerrit_stream_events/unittests.py b/tests/gerrit_stream/unittest_gerrit_stream_events/unittests.py
index 4cb3804..10805e5 100755
--- a/tests/gerrit_stream/unittest_gerrit_stream_events/unittests.py
+++ b/tests/gerrit_stream/unittest_gerrit_stream_events/unittests.py
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
-"""Unit tests for the Gerrit event stream events objects."""
+""" Unit tests for the Gerrit event stream events objects. """
 
 import json
 import os
@@ -15,24 +15,27 @@ from pygerrit.stream import GerritStream
 
 
 class TestGerritStreamEvents(unittest.TestCase):
-    """ Test that the event handling works properly in the GerritStream
-    class.
-    """
+
+    """ Test that the event handling works properly. """
 
     def setUp(self):
-        """Set up the gerrit stream object."""
+        """ Set up the gerrit stream object. """
         self.stream = GerritStream()
 
     def _get_event(self, name):
-        """Instantiate an event from data in the file specified by `name`.
-        Return some form of `GerritEvent`."""
+        """ Instantiate an event from data in the file specified by `name`.
+
+        Return some form of `GerritEvent`.
+
+        """
         data = open(os.path.join(os.environ["TESTDIR"], name))
         return self.stream._get_event(json.loads(data.read()))
 
     def test_patchset_created_event(self):
-        """Tests that the `PatchsetCreatedEvent` event is properly
-        generated.  Also implicitly tests that the `Change`,
-        `Account`, and `Patchset` classes behave properly.
+        """ Test that `PatchsetCreatedEvent` is properly generated.
+
+        Also implicitly tests that the `Change`, `Account`, and `Patchset`
+        classes behave properly.
 
         """
         event = self._get_event("patchset-created-event.txt")
@@ -56,10 +59,7 @@ class TestGerritStreamEvents(unittest.TestCase):
         self.assertEquals(event.uploader.email, "uploader@example.com")
 
     def test_draft_published_event(self):
-        """Tests that the `DraftPublishedEvent` event is properly
-        generated.
-
-        """
+        """ Test that `DraftPublishedEvent` is properly generated. """
         event = self._get_event("draft-published-event.txt")
         self.assertTrue(isinstance(event, DraftPublishedEvent))
         self.assertEquals(event.change.project, "project-name")
@@ -81,9 +81,9 @@ class TestGerritStreamEvents(unittest.TestCase):
         self.assertEquals(event.uploader.email, "uploader@example.com")
 
     def test_ref_updated_event(self):
-        """Tests that the `RefUpdatedEvent` event is properly
-        generated.  Also implicitly tests that the `RefUpdate`,
-        class behaves properly.
+        """ Test that `RefUpdatedEvent` is properly generated.
+
+        Also implicitly tests that the `RefUpdate` class behaves properly.
 
         """
         event = self._get_event("ref-updated-event.txt")
@@ -98,10 +98,7 @@ class TestGerritStreamEvents(unittest.TestCase):
         self.assertEquals(event.submitter.email, "submitter@example.com")
 
     def test_change_merged_event(self):
-        """Tests that the `ChangeMergedEvent` event is properly
-        generated.
-
-        """
+        """ Test that the `ChangeMergedEvent` event is properly generated. """
         event = self._get_event("change-merged-event.txt")
         self.assertTrue(isinstance(event, ChangeMergedEvent))
         self.assertEquals(event.change.project, "project-name")
@@ -123,9 +120,9 @@ class TestGerritStreamEvents(unittest.TestCase):
         self.assertEquals(event.submitter.email, "submitter@example.com")
 
     def test_comment_added_event(self):
-        """Tests that the `CommentAddedEvent` event is properly
-        generated.  Also implicitly tests that the `Approval` class
-        behaves properly.
+        """ Test that `CommentAddedEvent` is properly generated.
+
+        Also implicitly tests that the `Approval` class behaves properly.
 
         """
         event = self._get_event("comment-added-event.txt")
@@ -156,10 +153,7 @@ class TestGerritStreamEvents(unittest.TestCase):
         self.assertEquals(event.author.email, "author@example.com")
 
     def test_change_abandoned_event(self):
-        """Tests that the `ChangeAbandonedEvent` event is properly
-        generated.
-
-        """
+        """ Test that `ChangeAbandonedEvent` is properly generated. """
         event = self._get_event("change-abandoned-event.txt")
         self.assertTrue(isinstance(event, ChangeAbandonedEvent))
         self.assertEquals(event.change.project, "project-name")
@@ -176,10 +170,7 @@ class TestGerritStreamEvents(unittest.TestCase):
         self.assertEquals(event.reason, "Abandon reason")
 
     def test_change_restored_event(self):
-        """Tests that the `ChangeRestoredEvent` event is properly
-        generated.
-
-        """
+        """ Test that `ChangeRestoredEvent` is properly generated. """
         event = self._get_event("change-restored-event.txt")
         self.assertTrue(isinstance(event, ChangeRestoredEvent))
         self.assertEquals(event.change.project, "project-name")