.

9030f36b · Kirill Smelkov · fc9ce782 · 9030f36b
Commit 9030f36b authored Jun 05, 2020 by Kirill Smelkov
Hide whitespace changes
Inline Side-by-side

Showing with 37 additions and 16 deletions

wcfs/testprog/treegen.py wcfs/testprog/treegen.py +37 -16

No files found.
--- a/wcfs/testprog/treegen.py
+++ b/wcfs/testprog/treegen.py
@@ -19,33 +19,48 @@
 # See COPYING file for full licensing terms.
 # See https://www.nexedi.com/licensing for rationale and options.
-# FIXME update text
-# XXX   review
 """Program treegen provides infrastructure to generate ZODB BTree states.
 It is used as helper for ΔBTree tests.
 The following subcommands are provided:
- `trees` generates trees specified as arguments,
+- `trees` transition ZODB tree through requested tree states,
- `allstructs` generates subset of all possible tree changes in between two
+- `allstructs` generates subset of all possible tree topologies for changes in
-  trees represented by two key->value dicts.
+  between two trees represented by two key->value dicts.
+Because python/pkg_resources startup is very slow(*) all subcommands can be
+used either in CLI or in server mode, where requests are continuously read from
+stdin.
+Subcommands documentation follows:
 trees
 -----
-`treegen trees` ...
+`treegen trees <zurl>` transitions in-ZODB LOBTree through requested tree states.
+Tree states are specified on stdin as topology-encoded strings, 1 state per 1 line.
+For every request the tree is changed and modifications are committed to database.
+For every made commit corresponding transaction ID is printed to stdout.
+    S: tree.srv start @<head> root=<tree-root-oid>
+    C: <tree>
+    S: <tid>
+    C: <tree>
+    S: <tid>
+    ...
-# tree1   (with values)
+for example
-# tree2
-# ...
-# | treegen
-# a zodb tree goes through tree states
+    S: tree.srv start @03d85dd71ed0d2ee root=000000000000000b
-# every state is committed as separate transaction & printed in the same
+    C: T/B1:a
-# format as treegen-allstructs does
+    S: 03d85dd84fed7844
+    C: T2/B1:a-B3:c
+    S: 03d85dd871718899
+    ...
+The tree, that `treegen trees` works on, is also accessible as zconn.root()['treegen/tree'].
 allstructs
@@ -74,6 +89,11 @@ tree <oid>
 <LF>
 XXX
+--------
+(*) 300-500ms, see https://github.com/pypa/setuptools/issues/510
 """
 from __future__ import print_function, absolute_import
@@ -114,7 +134,7 @@ class ZCtx(object):
    # .root
    # .valdict = zconn.root['treegen/values'] = {} v -> ZBlk(v)
-    # ZCtx(zstor) opens connection to zstor.
+    # ZCtx(zstor) opens connection to zstor and initializes .valdict.
    def __init__(zctx, zstor):
        zctx.db    = DB(zstor)
        zctx.zconn = zctx.db.open()
@@ -151,8 +171,9 @@ class ZCtx(object):
        raise KeyError("%r not found in value registry" % (vobj,))
-# TreesSrv generates tree structures given their topology encoding on input.
+# TreesSrv transitions ZODB tree through requested states.
 # See top-level documentation for details.
+# XXX kill TreesSrv generates tree structures given their topology encoding on input.
 @func
 def TreesSrv(zstor, r):
    zctx = ZCtx(zstor)