docs: More readme.

README.md

@@ -1,6 +1,92 @@
-
 # titbit
-A place to dump might-be-useful-again code as an alternative of leaving in a notebook where it will never be found again
 
+A place to dump might-be-useful-again code as an alternative of leaving in a notebook where it will never be found again
 
 To install:	```pip install titbit```
+
+
+# Examples
+
+
+## git_action_on_projects
+
+Take git actions all the projects in the list of projects.
+A project can be a folder path or a module, or the name of a module/package.
+
+Tip: Use `functools.partial` to set the `action`, `on_error` and `egress` and get 
+the function you need to perform bulk actions.
+
+Usage:
+
+```python
+>>> from titbit import git_action_on_projects
+>>> projects = [
+...     some_package, "some_package_name", "some_package_dir_path"
+... ]  # doctest: +SKIP
+>>> # By default, the git action performed is to pull
+>>> git_action_on_projects(projects)  # doctest: +SKIP
+```
+
+## mermaid_to_graphviz
+
+Converts mermaid code to graphviz code.
+
+```python
+>>> from titbit import mermaid_to_graphviz
+>>> mermaid_code = '''
+... graph TD
+... A --> B & C
+... B & C --> D
+... '''
+>>> graphviz_code = mermaid_to_graphviz(mermaid_code)
+>>> print(graphviz_code)  # doctest: +NORMALIZE_WHITESPACE
+digraph G {
+<BLANKLINE>
+graph TD
+    A -> B , C
+    B , C -> D
+<BLANKLINE>
+}
+```
+## bound_properties_refactor
+
+Generate code that refactors "flat code" into a reusable "controller" class.
+Also checkout the `BoundPropertiesRefactor` class that does all the work: 
+With it, you'll be able to compute intermediate datas that may be of interest.
+
+```python
+>>> from titbit import bound_properties_refactor
+>>> code_str = '''
+... apple = banana + carrot
+... date = 'banana'
+... egg = apple * 2
+... egg = egg + 1
+... '''
+>>>
+>>> refactored_code = bound_properties_refactor(code_str)
+>>> print(refactored_code)  # doctest: +NORMALIZE_WHITESPACE
+@property
+def apple(self):
+    return banana + carrot
+<BLANKLINE>
+date = 'banana'
+<BLANKLINE>
+@property
+def egg(self):
+    egg = self.apple * 2
+    egg = egg + 1
+    return egg
+<BLANKLINE>
+```
+
+## ensure_ast
+
+```python
+def ensure_ast(code: AST) -> AST:
+    """
+    Ensures that the input is an AST node, returning it as-is if already an AST.
+
+    If input is a string, parses it as Python code and returns the resulting AST.
+    If the input is a module object, it will get the code, parse it, and return an AST.
+    """
+```

setup.cfg

@@ -19,5 +19,6 @@ include_package_data = True
 zip_safe = False
 install_requires = 
 	lkj
+	i2
 
 

titbit/__init__.py

@@ -5,6 +5,9 @@
 within the functions/objects that use them, when possible.
 """
 
+from titbit.ast_utils import (
+    rename_variables, bound_properties_refactor, BoundPropertiesRefactor, ensure_ast
+)
 
 def git_action_on_projects(
     projects,
@@ -23,6 +26,7 @@ def git_action_on_projects(
     >>> projects = [
     ...     some_package, "some_package_name", "some_package_dir_path"
     ... ]  # doctest: +SKIP
+    >>> # By default, the git action performed is to pull
     >>> git_action_on_projects(projects)  # doctest: +SKIP
 
     """

titbit/ast_utils.py

@@ -9,6 +9,7 @@
 import inspect
 from itertools import chain
 
+from i2 import Sig
 
 # -------------------------------------------------------------------------------
 # General utils
@@ -66,7 +67,10 @@ def group_values_by_key(kv_pairs: Iterable[Tuple[KT, VT]]) -> Dict[KT, List[VT]]
 @singledispatch
 def ensure_ast(code: AST) -> AST:
     """Ensures that the input is an AST node, returning it as-is if already an AST.
+
     If input is a string, parses it as Python code and returns the resulting AST.
+    If the input is a module object, it will get the code, parse it, and return an AST.
+    
     """
     assert isinstance(code, AST), "Input must be an AST node or a string."
     return code
@@ -266,6 +270,9 @@ class BoundPropertiesRefactor:
     """
     Generate code that refactors "flat code" into a reusable "controller" class.
 
+    You'd usually just use the `bound_properties_refactor` function for this, but 
+    this class's instances let's you get intermediate objects that can be useful.
+
     >>> code_str = '''
     ... apple = banana + carrot
     ... date = 'banana'
@@ -340,3 +347,34 @@ def refactored_code(self):
 
     def __call__(self):
         return self.refactored_code
+
+
+@Sig(BoundPropertiesRefactor)
+def bound_properties_refactor(*args, **kwargs):
+    """
+    Generate code that refactors "flat code" into a reusable "controller" class.
+
+    >>> code_str = '''
+    ... apple = banana + carrot
+    ... date = 'banana'
+    ... egg = apple * 2
+    ... egg = egg + 1
+    ... '''
+    >>>
+    >>> refactored_code = bound_properties_refactor(code_str)
+    >>> print(refactored_code)  # doctest: +NORMALIZE_WHITESPACE
+    @property
+    def apple(self):
+        return banana + carrot
+    <BLANKLINE>
+    date = 'banana'
+    <BLANKLINE>
+    @property
+    def egg(self):
+        egg = self.apple * 2
+        egg = egg + 1
+        return egg
+    <BLANKLINE>
+
+    """
+    return BoundPropertiesRefactor(*args, **kwargs)()