Reactors docs (#12)

* reactors docs

CGRtools/reactor.py

@@ -1,6 +1,7 @@
 # -*- coding: utf-8 -*-
 #
 #  Copyright 2014-2019 Ramil Nugmanov <stsouko@live.ru>
+#  Copyright 2019 Adelia Fatykhova <adelik21979@gmail.com>
 #  This file is part of CGRtools.
 #
 #  CGRtools is free software; you can redistribute it and/or modify
@@ -25,7 +26,37 @@
 
 
 class CGRreactor:
+    """
+    CGR based editor for CGRs and molecules.
+    generates transformation from input CGR/molecule
+    using template (CGRtools ReactionContainer)
+    -----------------------------------------------------
+    input: transformation template, CGR/molecule to edit
+    output: edited CGR/molecule or generator
+    -----------------------------------------------------
+    template should contain one reactant and one product:
+    CGRreactor allows only 1 -> 1 transformation
+
+    CGRreactor init prepares the reactor container:
+
+    >> reactor = CGRreactor(template, delete_atoms=True)
+
+    CGRreactor calling transforms reactants to products and
+    returns generator of all possible products if limit=0,
+    one product if limit=1, else limited to number list of products:
+
+    >> products = reactor(structure, limit=0)  # generator
+    >> product = reactor(structure, limit=1)   # one product
+    >> products = reactor(structure, limit=5)  # list with 5 products
+
+
+    """
     def __init__(self, template, delete_atoms=False):
+        """
+        :param template: CGRtools ReactionContainer
+        :param delete_atoms: if True atoms exists in reactant but
+                            not exists in product will be removed
+        """
         pattern, atom_attrs, bond_attrs, conditional_element, is_cgr, to_delete = self.__prepare_template(template)
         self.__pattern = pattern
         self.__atom_attrs = atom_attrs
@@ -50,7 +81,7 @@ def __call__(self, structure, limit=1, skip_intersection=True):
                 g = (self.patcher(structure, m) for m in mapping)
 
             if limit > 1:
-                return list(g)
+                return list(islice(g, limit))
             else:
                 return g
 
@@ -169,7 +200,40 @@ def patcher(self, structure, mapping):
 
 
 class Reactor:
+    """
+    CGR based reactor for molecules/queries.
+    generates reaction from input queries/molecules using
+    transformation template (CGRtools ReactionContainer).
+    -----------------------------------------------------
+    input: transformation template, list of reactants
+    output: reaction or list or generator of reactions
+    -----------------------------------------------------
+    reactor allows only this reaction transformations:
+         ONE to ONE   # 1 -> 1
+         ONE to MANY  # 1 -> 2
+         MANY to ONE  # 3 -> 1
+         MANY to MANY # 2 -> 2 (equal)
+
+    reactor init prepares the reactor container:
+
+    >> reactor = CGRreactor(template, delete_atoms=True)
+
+    reactor calling transforms reactants to products and
+    returns generator of reaction transformations with all
+    possible products if limit=0, one reaction if limit=1,
+    else limited to number list of reactions:
+
+    >> reactions = reactor(structure, limit=0)  # generator
+    >> reaction = reactor(structure, limit=1)   # one reaction
+    >> reactions = reactor(structure, limit=5)  # list with 5 reactions
+
+    """
     def __init__(self, template, delete_atoms=False):
+        """
+        :param template: CGRtools ReactionContainer
+        :param delete_atoms: if True atoms exists in reactants but
+                            not exists in products will be removed
+        """
         reactants, products = template.reactants, template.products
         if not reactants or not products:
             raise ValueError('empty template')
@@ -230,7 +294,8 @@ def __call__(self, structures, limit=0, skip_intersection=True):
     def __get_mapping(self, structures):
         """
         match each pattern to each molecule.
-        if all patterns matches with all molecules return generator of all possible mapping.
+        if all patterns matches with all molecules
+        return generator of all possible mapping.
 
         :param structures: disjoint molecules
         :return: mapping generator