Reformat spacing and update comments in doctests for clarity

Author: nocarryr

README.md

@@ -29,6 +29,7 @@ pip install python-dispatch
 
 ```python
 >>> from pydispatch import Dispatcher
+
 >>> class MyEmitter(Dispatcher):
 ...     # Events are defined in classes and subclasses with the '_events_' attribute
 ...     _events_ = ['on_state', 'new_data']
@@ -37,19 +38,22 @@ pip install python-dispatch
 ...         data = {'foo':'bar'}
 ...         # Then emit the change with optional positional and keyword arguments
 ...         self.emit('new_data', data=data)
-...
+
 >>> # An observer - could inherit from Dispatcher or any other class
 >>> class MyListener(object):
 ...     def on_new_data(self, *args, **kwargs):
 ...         data = kwargs.get('data')
 ...         print('I got data: {}'.format(data))
 ...     def on_emitter_state(self, *args, **kwargs):
 ...         print('emitter state changed')
-...
+
 >>> emitter = MyEmitter()
 >>> listener = MyListener()
+
+>>> # Bind to the "on_state" and "new_data" events of emitter
 >>> emitter.bind(on_state=listener.on_emitter_state)
 >>> emitter.bind(new_data=listener.on_new_data)
+
 >>> emitter.do_some_stuff()
 I got data: {'foo': 'bar'}
 >>> emitter.emit('on_state')
@@ -61,23 +65,30 @@ emitter state changed
 
 ```python
 >>> from pydispatch import Dispatcher, Property
+
 >>> class MyEmitter(Dispatcher):
 ...     # Property objects are defined and named at the class level.
 ...     # They will become instance attributes that will emit events when their values change
 ...     name = Property()
 ...     value = Property()
-...
+
 >>> class MyListener(object):
 ...     def on_name(self, instance, value, **kwargs):
 ...         print('emitter name is {}'.format(value))
 ...     def on_value(self, instance, value, **kwargs):
 ...         print('emitter value is {}'.format(value))
-...
+
 >>> emitter = MyEmitter()
 >>> listener = MyListener()
+
+>>> # Bind to the "name" and "value" properties of emitter
 >>> emitter.bind(name=listener.on_name, value=listener.on_value)
+
+>>> # Set emitter.name property (triggering the on_name callback)
 >>> emitter.name = 'foo'
 emitter name is foo
+
+>>> # Set emitter.value (triggering the on_value callback)
 >>> emitter.value = 42
 emitter value is 42
 

doc/source/async.rst

@@ -26,11 +26,13 @@ bind_async method
 
     >>> import asyncio
     >>> from pydispatch import Dispatcher
+
     >>> class MyEmitter(Dispatcher):
     ...     _events_ = ['on_state']
     ...     async def trigger(self):
     ...         await asyncio.sleep(1)
     ...         self.emit('on_state')
+
     >>> class MyAsyncListener(object):
     ...     def __init__(self):
     ...         self.event_received = asyncio.Event()
@@ -39,11 +41,14 @@ bind_async method
     ...         self.event_received.set()
     ...     async def wait_for_event(self):
     ...         await self.event_received.wait()
+
     >>> loop = asyncio.get_event_loop()
     >>> emitter = MyEmitter()
     >>> listener = MyAsyncListener()
+
     >>> # Pass the event loop as first argument to "bind_async"
     >>> emitter.bind_async(loop, on_state=listener.on_emitter_state)
+
     >>> loop.run_until_complete(emitter.trigger())
     >>> loop.run_until_complete(listener.wait_for_event())
     received on_state event
@@ -55,11 +60,13 @@ bind (with keyword argument)
 
     >>> import asyncio
     >>> from pydispatch import Dispatcher
+
     >>> class MyEmitter(Dispatcher):
     ...     _events_ = ['on_state']
     ...     async def trigger(self):
     ...         await asyncio.sleep(1)
     ...         self.emit('on_state')
+
     >>> class MyAsyncListener(object):
     ...     def __init__(self):
     ...         self.event_received = asyncio.Event()
@@ -68,11 +75,14 @@ bind (with keyword argument)
     ...         self.event_received.set()
     ...     async def wait_for_event(self):
     ...         await self.event_received.wait()
+
     >>> loop = asyncio.get_event_loop()
     >>> emitter = MyEmitter()
     >>> listener = MyAsyncListener()
+
     >>> # Pass the event loop using __aio_loop__
     >>> emitter.bind(on_state=listener.on_emitter_state, __aio_loop__=loop)
+
     >>> loop.run_until_complete(emitter.trigger())
     >>> loop.run_until_complete(listener.wait_for_event())
     received on_state event
@@ -99,13 +109,15 @@ This can also be done with :any:`Property` objects
 
     >>> import asyncio
     >>> from pydispatch import Dispatcher, Property
+
     >>> class MyEmitter(Dispatcher):
     ...     value = Property()
     ...     async def change_values(self):
     ...         for i in range(5):
     ...             await asyncio.sleep(.1)
     ...             self.value = i
     ...         return 'done'
+
     >>> class MyAsyncListener(object):
     ...     async def wait_for_values(self, emitter):
     ...         # Get the Event object for the Property
@@ -118,6 +130,7 @@ This can also be done with :any:`Property` objects
     ...             if value >= 4:
     ...                 break
     ...         return 'done'
+
     >>> loop = asyncio.get_event_loop()
     >>> emitter = MyEmitter()
     >>> listener = MyAsyncListener()

doc/source/dispatcher.rst

@@ -10,21 +10,28 @@ Usage
 .. doctest:: dispatcher_basic
 
     >>> from pydispatch import Dispatcher
+
     >>> class MyEmitter(Dispatcher):
     ...     _events_ = ['on_state', 'new_data']
+
     >>> # An observer - could inherit from Dispatcher or any other class
     >>> class MyListener(object):
     ...     def on_new_data(self, *args, **kwargs):
     ...         data = kwargs.get('data')
     ...         print('I got data: {}'.format(data))
     ...     def on_emitter_state(self, *args, **kwargs):
     ...         print('emitter state changed')
+
     >>> emitter = MyEmitter()
     >>> listener = MyListener()
+
+    >>> # Bind to the "on_state" and "new_data" events of emitter
     >>> emitter.bind(on_state=listener.on_emitter_state)
     >>> emitter.bind(new_data=listener.on_new_data)
+
     >>> emitter.emit('new_data', data='foo')
     I got data: foo
+
     >>> emitter.emit('on_state')
     emitter state changed
 

doc/source/properties.rst

@@ -16,27 +16,35 @@ Usage
 .. doctest:: property_basic_dt
 
     >>> from pydispatch import Dispatcher, Property
+
     >>> class MyEmitter(Dispatcher):
     ...     name = Property()
     ...     value = Property()
+
     >>> class MyListener(object):
     ...     def on_name(self, instance, value, **kwargs):
     ...         print('emitter name is {}'.format(value))
     ...     def on_value(self, instance, value, **kwargs):
     ...         print('emitter value is {}'.format(value))
+
     >>> emitter = MyEmitter()
     >>> listener = MyListener()
+
     >>> # Bind to the "name" and "value" properties of emitter
     >>> emitter.bind(name=listener.on_name, value=listener.on_value)
+
     >>> # Set emitter.name property (triggering the on_name callback)
     >>> emitter.name = 'foo'
     emitter name is foo
+
     >>> # Set emitter.value (triggering the on_value callback)
     >>> emitter.value = 42
     emitter value is 42
-    >>> # If the property value assigned equals the current value:
+
+    >>> # If the property value assigned equals the current value,
+    >>> # the event isn't triggered.
     >>> emitter.value = 42
-    >>> # No event is dispatched
+
     >>> emitter.value = 43
     emitter value is 43
 
@@ -55,35 +63,48 @@ structure can trigger an event.
 .. doctest:: property_containers
 
     >>> from pydispatch import Dispatcher, ListProperty, DictProperty
+
     >>> class MyEmitter(Dispatcher):
     ...     values = ListProperty()
     ...     data = DictProperty()
+
     >>> class MyListener(object):
     ...     def on_values(self, instance, value, **kwargs):
     ...         print('emitter.values = {}'.format(value))
     ...     def on_data(self, instance, value, **kwargs):
     ...         print('emitter.data = {}'.format(value))
+
     >>> emitter = MyEmitter()
     >>> listener = MyListener()
+
+    >>> # Bind to the "values" (list) and "data" (dict) properties of emitter
     >>> emitter.bind(values=listener.on_values, data=listener.on_data)
+
     >>> emitter.values.append('foo')
     emitter.values = ['foo']
+
     >>> emitter.values.extend(['bar', 'baz'])
     emitter.values = ['foo', 'bar', 'baz']
+
     >>> # The property can be assigned directly
     >>> emitter.data = {'foo':'bar'}
     emitter.data = {'foo': 'bar'}
+
     >>> # or using item assignment
     >>> emitter.data['foo'] = 'baz'
     emitter.data = {'foo': 'baz'}
+
     >>> # also through the update() method
     >>> emitter.data.update({'spam':'eggs'})
     emitter.data = {'foo': 'baz', 'spam': 'eggs'}
+
     >>> emitter.data.clear()
     emitter.data = {}
+
     >>> # Create a nested dict
     >>> emitter.data['fruit'] = {'apple':'red'}
     emitter.data = {'fruit': {'apple': 'red'}}
+
     >>> # changes to the inner dict are propagated and dispatched
     >>> emitter.data['fruit']['banana'] = 'yellow'
     emitter.data = {'fruit': {'apple': 'red', 'banana': 'yellow'}}

pydispatch/dispatch.py

@@ -161,6 +161,7 @@ class Foo(Dispatcher):
 
             >>> class Foo(Dispatcher):
             ...     _events_ = ['test_event']
+
             >>> class Bar(object):
             ...     def __init__(self):
             ...         self.got_foo_event = asyncio.Event()
@@ -169,11 +170,13 @@ class Foo(Dispatcher):
             ...         print('got foo!')
             ...     async def on_foo_test_event(self, *args, **kwargs):
             ...         self.got_foo_event.set()
+
+            >>> loop = asyncio.get_event_loop()
             >>> foo = Foo()
             >>> bar = Bar()
-            >>> loop = asyncio.get_event_loop()
             >>> foo.bind(test_event=bar.on_foo_test_event, __aio_loop__=loop)
             >>> fut = asyncio.ensure_future(bar.wait_for_foo())
+
             >>> foo.emit('test_event')
             >>> loop.run_until_complete(fut)
             got foo!
@@ -270,8 +273,10 @@ def emission_lock(self, name):
 
         >>> class Foo(Dispatcher):
         ...     _events_ = ['my_event']
+
         >>> def on_my_event(value):
         ...     print(value)
+
         >>> foo = Foo()
         >>> foo.bind(my_event=on_my_event)
         >>> with foo.emission_lock('my_event'):

pydispatch/properties.py

@@ -6,19 +6,23 @@
 .. doctest:: properties_module
 
     >>> from pydispatch import Dispatcher, Property
+
     >>> class Foo(Dispatcher):
     ...     name = Property()
     ...     value = Property()
     ...     def __str__(self):
     ...         return self.__class__.__name__
+
     >>> class Listener(object):
     ...     def on_foo_name(self, instance, value, **kwargs):
     ...         print("{}'s name is {}".format(instance, value))
     ...     def on_foo_value(self, instance, value, **kwargs):
     ...         print('{} = {}'.format(instance, value))
+
     >>> foo_obj = Foo()
     >>> listener_obj = Listener()
     >>> foo_obj.bind(name=listener_obj.on_foo_name, value=listener_obj.on_foo_value)
+
     >>> foo_obj.name = 'bar'
     Foo's name is bar
     >>> foo_obj.value = 42