londiste/handlers: updated docs / help

7 files changed, 50 insertions, 42 deletions

diff --git a/python/londiste/handler.py b/python/londiste/handler.py
index ad4239ff..42187158 100644
--- a/python/londiste/handler.py
+++ b/python/londiste/handler.py
@@ -106,7 +106,7 @@ class BaseHandler:
         """Called when batch finishes."""
         pass
 
-    def get_copy_condition(self, src_curs, dst_curs):        
+    def get_copy_condition(self, src_curs, dst_curs):
         """ Use if you want to filter data """
         return ''
 
@@ -125,7 +125,7 @@ class BaseHandler:
 
 class TableHandler(BaseHandler):
     """Default Londiste handler, inserts events into tables with plain SQL.
-    
+
     Parameters:
       encoding=ENC - Validate and fix incoming data from encoding.
                      Only 'utf8' is supported at the moment.
@@ -172,13 +172,13 @@ class TableHandler(BaseHandler):
 
     def parse_row_data(self, ev):
         """Extract row data from event, with optional encoding fixes.
-        
+
         Returns either string (sql event) or dict (urlenc event).
         """
 
         if len(ev.type) == 1:
             if not self.allow_sql_event:
-                raise Exception('SQL events not suppoted by this handler')
+                raise Exception('SQL events not supported by this handler')
             if self.enc:
                 return self.enc.validate_string(ev.data, self.table_name)
             return ev.data
@@ -190,9 +190,9 @@ class TableHandler(BaseHandler):
 
     def real_copy(self, src_tablename, src_curs, dst_curs, column_list):
         """do actual table copy and return tuple with number of bytes and rows
-        copyed
+        copied
         """
-	
+
         if self.enc:
             def _write_hook(obj, data):
                 return self.enc.validate_copy(data, column_list, src_tablename)
@@ -211,7 +211,7 @@ class TableHandler(BaseHandler):
 
 class EncodingValidator:
     def __init__(self, log, encoding = 'utf-8', replacement = u'\ufffd'):
-        """validates the correctness of given encoding. when data contains 
+        """validates the correctness of given encoding. when data contains
         illegal symbols, replaces them with <replacement> and logs the
         incident
         """
@@ -352,13 +352,12 @@ def show(mods):
             kls = _handler_map[n]
             desc = kls.__doc__ or ''
             if desc:
-                desc = desc.split('\n', 1)[0]
+                desc = desc.strip().split('\n', 1)[0]
             print("%s - %s" % (n, desc))
     else:
         for n in mods:
             kls = _handler_map[n]
             desc = kls.__doc__ or ''
             if desc:
-                desc = desc.rstrip()
+                desc = desc.strip()
             print("%s - %s" % (n, desc))
-
diff --git a/python/londiste/handlers/applyfn.py b/python/londiste/handlers/applyfn.py
index 23529c49..b7b1173c 100644
--- a/python/londiste/handlers/applyfn.py
+++ b/python/londiste/handlers/applyfn.py
@@ -1,5 +1,5 @@
 """
-Send all events to a db function.
+Send all events to a DB function.
 """
 
 import skytools
@@ -8,7 +8,12 @@ from londiste.handler import BaseHandler
 __all__ = ['ApplyFuncHandler']
 
 class ApplyFuncHandler(BaseHandler):
-    """Call db function to apply event"""
+    """Call DB function to apply event.
+
+    Parameters:
+      func_name=NAME - database function name
+      func_conf=CONF - database function conf
+    """
     handler_name = 'applyfn'
 
     def prepare_batch(self, batch_info, dst_curs):
@@ -37,5 +42,3 @@ class ApplyFuncHandler(BaseHandler):
 #------------------------------------------------------------------------------
 
 __londiste_handlers__ = [ApplyFuncHandler]
-
-
diff --git a/python/londiste/handlers/bulk.py b/python/londiste/handlers/bulk.py
index 7bc3797b..0c0167ac 100644
--- a/python/londiste/handlers/bulk.py
+++ b/python/londiste/handlers/bulk.py
@@ -8,8 +8,7 @@ To use set in londiste.ini:
 then add table with:
   londiste3 add-table xx --handler="bulk"
 
-or
-
+or:
   londiste3 add-table xx --handler="bulk(method=X)"
 
 Methods:
@@ -52,11 +51,23 @@ class BulkEvent(object):
         self.pk_data = pk_data
 
 class BulkLoader(BaseHandler):
-    """Instead of statement-per-event, load all data with one
-    big COPY, UPDATE or DELETE statement.
+    """Bulk loading into OLAP database.
+    Instead of statement-per-event, load all data with one big COPY, UPDATE
+    or DELETE statement.
+
+    Parameters:
+      method=TYPE - method to use for copying [0..2] (default: 0)
+
+    Methods:
+      0 (correct) - inserts as COPY into table,
+                    update as COPY into temp table and single UPDATE from there
+                    delete as COPY into temp table and single DELETE from there
+      1 (delete)  - as 'correct', but do update as DELETE + COPY
+      2 (merged)  - as 'delete', but merge insert rows with update rows
     """
     handler_name = 'bulk'
     fake_seq = 0
+
     def __init__(self, table_name, args, dest_table):
         """Init per-batch table data cache."""
 
@@ -361,4 +372,3 @@ class BulkLoader(BaseHandler):
 
 # register handler class
 __londiste_handlers__ = [BulkLoader]
-
diff --git a/python/londiste/handlers/multimaster.py b/python/londiste/handlers/multimaster.py
index 872b77e1..f28535e8 100644
--- a/python/londiste/handlers/multimaster.py
+++ b/python/londiste/handlers/multimaster.py
@@ -16,7 +16,7 @@ from londiste.handlers import update
 __all__ = ['MultimasterHandler']
 
 class MultimasterHandler(ApplyFuncHandler):
-    """Handle multimaster replicas"""
+    __doc__ = __doc__
     handler_name = 'multimaster'
 
     def __init__(self, table_name, args, dest_table):
@@ -27,9 +27,9 @@ class MultimasterHandler(ApplyFuncHandler):
             if name in conf:
                 conf.pop(name)
         conf = skytools.db_urlencode(conf)
-        args = update(args, {'func_name': 'merge_on_time', 'func_conf': conf})  
+        args = update(args, {'func_name': 'merge_on_time', 'func_conf': conf})
         ApplyFuncHandler.__init__(self, table_name, args, dest_table)
-    
+
     def add(self, trigger_arg_list):
         """Create SKIP and BEFORE INSERT trigger"""
         trigger_arg_list.append('no_merge')
diff --git a/python/londiste/handlers/part.py b/python/londiste/handlers/part.py
index 6864c64f..bdabb3e6 100644
--- a/python/londiste/handlers/part.py
+++ b/python/londiste/handlers/part.py
@@ -2,14 +2,13 @@
 
 Parameters:
   key=COLUMN: column name to use for hashing
-  hashfunc=FUNCNAME: function to use for hashing. (default: partconf.get_hash_raw)
+  hashfunc=NAME: function to use for hashing (default: partconf.get_hash_raw)
   hashexpr=EXPR: full expression to use for hashing (deprecated)
   encoding=ENC: validate and fix incoming data (only utf8 supported atm)
 
 On root node:
 * Hash of key field will be added to ev_extra3.
   This is implemented by adding additional trigger argument:
-
         ev_extra3='hash='||partconf.get_hash_raw(key_column)
 
 On branch/leaf node:
@@ -41,7 +40,7 @@ class PartHandler(TableHandler):
         # primary key columns
         self.key = args.get('key')
         if self.key is None:
-            raise Exception('Specify key field as key agument')
+            raise Exception('Specify key field as key argument')
 
         # hash function & full expression
         hashfunc = args.get('hashfunc', self.DEFAULT_HASHFUNC)
@@ -60,7 +59,7 @@ class PartHandler(TableHandler):
         """Let trigger put hash into extra3"""
 
         arg = "ev_extra3='hash='||%s" % self.hashexpr
-        trigger_arg_list.append(arg)        
+        trigger_arg_list.append(arg)
         TableHandler.add(self, trigger_arg_list)
 
     def prepare_batch(self, batch_info, dst_curs):
@@ -98,4 +97,3 @@ class PartHandler(TableHandler):
 
 # register handler class
 __londiste_handlers__ = [PartHandler]
-
diff --git a/python/londiste/handlers/qtable.py b/python/londiste/handlers/qtable.py
index 13ca4099..87ce263b 100644
--- a/python/londiste/handlers/qtable.py
+++ b/python/londiste/handlers/qtable.py
@@ -2,13 +2,13 @@
 
 Handlers:
 
-qtable      - dummy handler to setup queue tables. All events are ignored. use in 
-              root node
-fake_local  - dummy handler to setup queue tables. All events are ignored. Table
-              structure is not required. Use in branch/leaf
-qsplitter  -  dummy handler to setup queue tables. All events are ignored. Table
-              structure is not required. All table events are inserted to
-              destination queue, specified with handler arg 'queue'.
+qtable     - dummy handler to setup queue tables. All events are ignored. Use in
+             root node.
+fake_local - dummy handler to setup queue tables. All events are ignored. Table
+             structure is not required. Use in branch/leaf.
+qsplitter  - dummy handler to setup queue tables. All events are ignored. Table
+             structure is not required. All table events are inserted to
+             destination queue, specified with handler arg 'queue'.
 
 """
 
@@ -21,7 +21,7 @@ __all__ = ['QueueTableHandler', 'QueueSplitterHandler']
 
 class QueueTableHandler(BaseHandler):
     """Queue table handler. Do nothing.
-    
+
     Trigger: before-insert, skip trigger.
     Event-processing: do nothing.
     """
@@ -44,7 +44,7 @@ class QueueSplitterHandler(BaseHandler):
     """Send events for one table to another queue.
 
     Parameters:
-      queue=QUEUE   Queue name.
+      queue=QUEUE - Queue name.
     """
     handler_name = 'qsplitter'
 
diff --git a/python/londiste/handlers/vtable.py b/python/londiste/handlers/vtable.py
index 19e5df0f..20a73f40 100644
--- a/python/londiste/handlers/vtable.py
+++ b/python/londiste/handlers/vtable.py
@@ -1,4 +1,6 @@
-"""Virtual Table.
+"""Virtual Table handler.
+
+Hack to get local=t for a table, but without processing any events.
 """
 
 from londiste.handler import BaseHandler
@@ -6,10 +8,7 @@ from londiste.handler import BaseHandler
 __all__ = ['VirtualTableHandler', 'FakeLocalHandler']
 
 class VirtualTableHandler(BaseHandler):
-    """Virtual Table.
-
-    Hack to get local=t for a table, but without processing any events.
-    """
+    __doc__ = __doc__
     handler_name = 'vtable'
 
     def add(self, trigger_arg_list):
@@ -23,4 +22,3 @@ class FakeLocalHandler(VirtualTableHandler):
     handler_name = 'fake_local'
 
 __londiste_handlers__ = [VirtualTableHandler, FakeLocalHandler]
-