Updating docs.

docs/chainz.Chain.txt

@@ -66,6 +66,21 @@ chainz.Chain = class Chain
  |      The return value of f is ignored.
  |      Note that this is a sink; it entirely consumes the iterable.
  |  
+ |  join_on_key(self, key, other)
+ |      Merge other iterable into this chain, on shared key.
+ |      
+ |      This assumes that key is unique in both iterables.
+ |      It will yield an object merging the object for the key
+ |      from each iterable.  It will yield in the order that
+ |      it completes each.  It will drop all objects that
+ |      don't have a mate.
+ |      
+ |      Note that this stores the unpaired objects, so it can
+ |      potentially use up a lot of memory.  It will consume
+ |      from each queue until it has a match, so in the worst
+ |      case (no matching objects) it will consume and store
+ |      in memory each realized iterable.
+ |  
  |  keep_keys(self, keys)
  |      Keep only the provided keys in each object.
  |      
@@ -96,8 +111,6 @@ chainz.Chain = class Chain
  |      print list(chain)
  |      # ['0a', '0b', '1a', '1b', '2a', '2b']
  |  
- |  merge_on_key(self, key, other)
- |  
  |  next(self)
  |      x.next() -> the next value, or raise StopIteration
  |  
@@ -132,6 +145,12 @@ chainz.Chain = class Chain
  |      
  |      Note that this is a sink; it entirely consumes the iterable.
  |  
+ |  rename_key(self, old_key, new_key, strict=True)
+ |      Rename old_key to new_key.
+ |      
+ |      If strict=True, throw an error if the object does not have old_key.
+ |      If strict=False, ignore such objects.
+ |  
  |  set_key(self, key, value)
  |      Set a key `key` with value `value` to each object.
  |      
@@ -152,4 +171,20 @@ chainz.Chain = class Chain
  |      slice(end): slice first `end` elements
  |      slice(beg, end, [step]): start slice at `beg`, end at `end`, with step
  |          `step` if provided.
+ |  
+ |  transform(self, trans)
+ |      Pass the iterator through the transform f.
+ |      
+ |      This is a lower-level method.  A transform does not get each individual
+ |      object, rather it gets the original iterator.  It must return an
+ |      iterator.  For example,
+ |      def f(in_iterator):
+ |          with open('filename', 'w') as output:
+ |              for x in in_iterator:
+ |                  output.write(x)
+ |                  yield x
+ |      
+ |      This will keep the output open throughout the iteration.
+ |      Note that the transform is responsible for calling on_error, if
+ |      appropriate.  Please see the examples in the above functions.
 

docs/chainz.txt

@@ -9,8 +9,11 @@ FILE
 DESCRIPTION
     It includes:
     chainz.Chain: A wrapper class for iterables with chaining, functional methods.
+    chainz.utils: A set of helper functions that can be used with Chain.
 
 PACKAGE CONTENTS
+    chain
     chainz
+    utils
 
 

docs/chainz.utils.txt

@@ -0,0 +1,63 @@
+Help on module chainz.utils in chainz:
+
+NAME
+    chainz.utils - A set of utility functions for chainz.
+
+FILE
+    /Users/jag/dev/chainz/chainz/utils.py
+
+DESCRIPTION
+    These help with common tasks like reading a file, searching a directory, etc.
+
+FUNCTIONS
+    counter(callback)
+        Will count the items that pass by, returning the count to the callback.
+
+        >>> def log(ct):
+        >>>     print('Count %d' % ct)
+        >>> Chain(xrange(4)).counter(log)    >>>     .filter(lambda x: x % 2 == 0).counter(log)    >>>     .sink()
+        Count 4
+        Count 2
+
+    read_csv_dict_file(filepath, dialect=None)
+        Iterates over a csv file, yielding each line as a dict.
+
+        This uses csv.DictReader, so the file should be in a form appropriate to
+        that. The dialect argument is supplied to the csv reader.
+
+    read_csv_file(filepath, dialect=None)
+        Iterates over a csv file, yielding each line as a tuple.
+
+        The dialect argument is supplied to the csv reader.
+
+    read_file_lines(filepath)
+        Iterates over a file, line by line.
+
+        This generator will yield each line in turn, without the linebreak.
+
+    read_jsonl_file(filepath)
+        Iterates over a jsonl file, yielding the JSON objects.
+
+    walk_files(root_dir)
+        Iterates under all the files under root_dir, yielding their filepath.
+
+    walk_leaf_dirs(root_dir)
+        Yield the paths of the leaf directories under root_dir.
+
+        Leaf directories are those dirs that don't have any subdirectories.
+
+    write_json_lines_to_filepath(filepath, append=False)
+        A transform that writes the incoming objects as JSON objects, one per
+        line, to the filepath.
+
+        Use like chain.transform(transform_write_json_lines_to_filepath(the_filepath))
+        If append == True, append to the file instead of overwriting it.
+
+    write_lines_to_filepath(filepath, append=False)
+        A transform that writes the incoming objects, one per line, to
+        the filepath.
+
+        Use like chain.transform(transform_write_lines_to_filepath(the_filepath))
+        If append == True, append to the file instead of overwriting it.
+
+