New syntax: Forks & merge polishing

Author: hartym

bin/update_apidoc.py

@@ -31,7 +31,6 @@ def get_path(self):
         return os.path.join(__path__, apidoc_root, *self.name.split(".")) + ".rst"
 
 
-
 bonobo = __import__("bonobo")
 assert bonobo.__version__
 

bonobo/structs/graphs.py

@@ -104,6 +104,13 @@ def get_cursor(self, ref=BEGIN):
         """
         return GraphCursor(self, last=self.index_of(ref))
 
+    def orphan(self):
+        """
+        Create a `GraphCursor` attached to nothing.
+
+        """
+        return self.get_cursor(None)
+
     def index_of(self, mixed):
         """
         Find the index based on various strategies for a node, probably an input or output of chain. Supported

docs/guide/graphs.rst

@@ -396,6 +396,33 @@ You can also create single nodes, and the api provide the same capability on sin
     graph.add_chain(..., _output="foo")
 
 
+Orphan nodes / chains
+:::::::::::::::::::::
+
+The default behaviour of `add_chain` (or `get_cursor`) is to connect the first node to the special `BEGIN` token, which
+instruct |bonobo| to call the connected node once without parameter to kickstart the data stream.
+
+This is normally what you want, but there are ways to override it, as you may want to add "orphan" nodes or chains to your graph.
+
+.. code-block:: python
+
+    import bonobo
+
+    graph = bonobo.Graph()
+
+    # using add_node will naturally add a node as "orphan"   
+    graph.add_node(a)
+
+    # using add_chain with "None" as the input will create an orphan chain
+    graph.add_chain(a, b, c, _input=None)
+
+    # using the new syntax, you can use either get_cursor(None) or the orphan() shortcut
+    graph.get_cursor(None) >> a >> b >> c
+    
+    # ... using the shortcut ...
+    graph.orphan() >> a >> b >> c
+
+
 Connecting two nodes
 ::::::::::::::::::::
 

tests/structs/test_graphs_new_syntax.py

@@ -120,3 +120,23 @@ def test_cursor_merge():
     assert g.outputs_of(c) == set()
 
     assert c1 == c2
+
+
+def test_cursor_merge_orphan_in_between():
+    a, b, c, v, w, x, y = get_pseudo_nodes(*"abcdefg")
+    g = Graph()
+    g >> a >> b >> c
+    assert len(g) == 3
+    g.orphan() >> v >> w >> b
+    assert len(g) == 5
+    g.orphan() >> x >> y >> b
+    assert len(g) == 7
+
+    assert g.outputs_of(BEGIN) == g.indexes_of(a)
+    assert g.outputs_of(a) == g.indexes_of(b)
+    assert g.outputs_of(b) == g.indexes_of(c)
+    assert g.outputs_of(c) == set()
+    assert g.outputs_of(v) == g.indexes_of(w)
+    assert g.outputs_of(w) == g.indexes_of(b)
+    assert g.outputs_of(x) == g.indexes_of(y)
+    assert g.outputs_of(y) == g.indexes_of(b)