brush up developer/data.rst

master/docs/developer/data.rst

@@ -11,16 +11,17 @@ Sections
 
 The data api is divided into four sections:
 
- * getters - fetching data from the db API, and
- * subscriptions - subscribing to messages from the mq layer;
- * control -  allows state to be changed in specific ways by sending appropriate messages (e.g., stopping a build); and
- * updates - direct updates to state appropriate messages.
+* getters - fetching data from the db API, and
+* subscriptions - subscribing to messages from the mq layer;
+* control - allows state to be changed in specific ways by sending appropriate messages (e.g., stopping a build); and
+* updates - direct updates to state appropriate messages.
 
 The getters and subscriptions are exposed everywhere.
 Access to the control section should be authenticated at higher levels, as the data layer does no authentication.
 The updates section is for use only by the process layer.
 
-The interfaces for all sections but the updates sections are intended to be language-agnostic.  That is, they should be callable from JavaScript via HTTP, or via some other interface added to Buildbot after the fact.
+The interfaces for all sections but the updates sections are intended to be language-agnostic.
+That is, they should be callable from JavaScript via HTTP, or via some other interface added to Buildbot after the fact.
 
 Getter
 ++++++
@@ -66,7 +67,7 @@ Within the buildmaster process, the root of the data API is available at `self.m
     This class implements the root of the data API.
     Within the buildmaster process, the data connector is available at `self.master.data`.
     The first three sections are implemented with the :py:meth:`get`, :py:meth:`startConsuming`, and :py:meth:`control` methods, respectively, while the updates section is implemented using the :py:attr:`updates` attribute.
-    The ``path`` arguments to these methods should always be tuples.  Integer arguments can be presented as either integers or strings that can be parsed by ``int``; all other arguments must be strings.
+    The ``path`` arguments to these methods should always be tuples.
     Integer arguments can be presented as either integers or strings that can be parsed by ``int``; all other arguments must be strings.
 
     .. py:method:: get(path, filters=None, fields=None, order=None, limit=None, offset=None):
@@ -118,11 +119,10 @@ Within the buildmaster process, the root of the data API is available at `self.m
         :param msg: a dictionary describing the msg to send
         :param event: the event to produce
 
-        This method implements the production of an event, for the rtype identified by its name string
-        Usually, this is the role of the data layer to produce the events inside the update methods
-        For the potencial use cases where it would make sense to solely produce and event, and not update
-        data, please use this API, rather than directly call mq.
-        It ensures the event is sent to all the routingkeys specified by eventPathPatterns
+        This method implements the production of an event, for the rtype identified by its name string.
+        Usually, this is the role of the data layer to produce the events inside the update methods.
+        For the potential use cases where it would make sense to solely produce an event, and not update data, please use this API, rather than directly call mq.
+        It ensures the event is sent to all the routingkeys specified by eventPathPatterns.
 
     .. py:method:: control(action, args, path)
 
@@ -165,7 +165,7 @@ Exceptions
 
 .. py:exception:: DataException
 
-    This is a base class for all other Data API exceptions
+    This is a base class for all other Data API exceptions.
 
 .. py:exception:: InvalidPathError
 
@@ -207,16 +207,18 @@ You can also follow an existing file, like :src:`master/buildbot/data/changes.py
 In :src:`master/buildbot/data/pubs.py`, create a subclass of :py:class:`ResourceType`::
 
     from buildbot.data import base
+
     class Pub(base.ResourceType):
         name = "pub"
         endpoints = []
-        keyFields = [ 'pubid' ]
+        keyFields = ['pubid']
 
         class EntityType(types.Entity):
             pubid = types.Integer()
             name = types.String()
             num_taps = types.Integer()
             closes_at = types.Integer()
+
         entityType = EntityType(name)
 
 .. py:class:: ResourceType
@@ -249,7 +251,7 @@ In :src:`master/buildbot/data/pubs.py`, create a subclass of :py:class:`Resource
 
         ``pub/:pubid``
 
-        In the example above, a call to ``produceEvent({ 'pubid' : 10, 'name' : 'Winchester' }, 'opened')`` would result in a message with routing key ``('pub', '10', 'opened')``.
+        In the example above, a call to ``produceEvent({'pubid': 10, 'name': 'Winchester'}, 'opened')`` would result in a message with routing key ``('pub', '10', 'opened')``.
 
         Several paths can be specified in order to be consistent with rest endpoints.
 
@@ -371,7 +373,8 @@ See that module's description for details.
 Continuing the pub example, a simple endpoint would look like this::
 
     class PubEndpoint(base.Endpoint):
-        pathPattern = ( 'pub', 'i:pubid' )
+        pathPattern = ('pub', 'i:pubid')
+
         def get(self, resultSpec, kwargs):
             return self.master.db.pubs.getPub(kwargs['pubid'])
 
@@ -451,33 +454,43 @@ Basic Types
 
 .. py:class:: Integer()
 
-    An integer. ::
+    An integer.
+
+    ::
 
         myid = types.Integer()
 
 .. py:class:: String()
 
     A string.
-    Strings must always be Unicode. ::
+    Strings must always be Unicode.
+
+    ::
 
         name = types.String()
 
 .. py:class:: Binary()
 
-    A binary bytestring. ::
+    A binary bytestring.
+
+    ::
 
         data = types.Binary()
 
 .. py:class:: Boolean()
 
-    A boolean value. ::
+    A boolean value.
+
+    ::
 
         complete = types.Boolean()
 
 .. py:class:: Identifier(length)
 
     An identifier; see :ref:`Identifier <type-identifier>`.
-    The constructor argument specifies the maximum length. ::
+    The constructor argument specifies the maximum length.
+
+    ::
 
         ident = types.Identifier(25)
 
@@ -486,21 +499,27 @@ Compound Types
 
 .. py:class:: NoneOk(nestedType)
 
-    Either the nested type, or None. ::
+    Either the nested type, or None.
+
+    ::
 
         category = types.NoneOk(types.String())
 
 .. py:class:: List(of)
 
     An list of objects.
-    The named constructor argument ``of`` specifies the type of the list elements. ::
+    The named constructor argument ``of`` specifies the type of the list elements.
+
+    ::
 
         tags = types.List(of=types.String())
 
 .. py:class:: SourcedProperties()
 
     A data structure representing properties with their sources, in the form ``{name: (value, source)}``.
-    The property name and source must be Unicode, and the value must be JSON-able. ::
+    The property name and source must be Unicode, and the value must be JSON-able.
+
+    ::
 
         props = types.SourcedProperties()
 
@@ -525,7 +544,7 @@ Entity Type
                 tags = types.List(of=types.String())
                 props = types.SourcedProperties()
 
-    Then instantiate the class with the resource type name ::
+    Then instantiate the class with the resource type name::
 
         entityType = EntityType(name)
 
@@ -542,12 +561,12 @@ The data api enforces a strong and well-defined model on Buildbot's data.
 This model is influenced by REST, in the sense that it defines resources, representations for resources, and identifiers for resources.
 For each resource type, the API specifies
 
- * the attributes of the resource and their types (e.g., changes have a string specifying their project);
- * the format of links to other resources (e.g., buildsets to sourcestamp sets);
- * the paths relating to the resource type;
- * the format of routing keys for messages relating to the resource type;
- * the events that can occur on that resource (e.g., a buildrequest can be claimed); and
- * options and filters for getting resources.
+* the attributes of the resource and their types (e.g., changes have a string specifying their project);
+* the format of links to other resources (e.g., buildsets to sourcestamp sets);
+* the paths relating to the resource type;
+* the format of routing keys for messages relating to the resource type;
+* the events that can occur on that resource (e.g., a buildrequest can be claimed); and
+* options and filters for getting resources.
 
 Some resource type attributes only appear in certain formats, as noted in the documentation for the resource types.
 In general, messages do not include any optional attributes, nor links.