Merge pull request #30 from pyjanitor-devs/issue29-pr

documentation of method_call_ctx_factory

Author: asmirnov69

README.md

@@ -121,6 +121,12 @@ df.row_by_value('x', 10)
 # Name: 0, dtype: int64
 ```
 
+## Registered methods tracing
+
+The pandas_flavor 0.5.0 release introduced [tracing of the registered method calls](/docs/tracing_ext.md). Now it is possible to add additional run-time logic around registered method execution which can be used for some support tasks. This extension was introduced
+to allow visualization of [pyjanitor](https://github.com/pyjanitor-devs/pyjanitor) method chains as implemented in [pyjviz](https://github.com/pyjanitor-devs/pyjviz)
+
+
 ## Available Methods
 
 - **register_dataframe_method**: register a method directly with a pandas DataFrame.

docs/tracing_ext-demo.py

@@ -0,0 +1,51 @@
+import pandas as pd
+import pandas_flavor as pf
+import time
+
+
+@pf.register_dataframe_method
+def my_method(df: pd.DataFrame) -> pd.DataFrame:
+    print("my_method called")
+    return df.transpose()
+
+
+@pf.register_dataframe_method
+def another_method(df: pd.DataFrame, new_col_d) -> pd.DataFrame:
+    print("another_method called")
+    for col, v in new_col_d.items():
+        df[col] = v
+    return df
+
+
+class tracer:
+    @staticmethod
+    def create_tracer(*args):
+        return tracer()
+
+    def __init__(self):
+        self.method_name = None
+        self.start_ts = None
+        self.end_ts = None
+
+    def __enter__(self):
+        return self
+
+    def handle_start_method_call(
+        self, method_name, method_signature, method_args, method_kwagrs
+    ):
+        self.method_name = method_name
+        self.start_ts = time.time()
+        return method_args, method_kwagrs
+
+    def handle_end_method_call(self, ret):
+        self.end_ts = time.time()
+
+    def __exit__(self, exc_type, value, traceback):
+        call_dur = self.end_ts - self.start_ts
+        print(f"method {self.method_name} took {call_dur} secs to execute")
+
+
+pf.register.method_call_ctx_factory = tracer.create_tracer
+s_df = pd.DataFrame([[i + j for i in range(10)] for j in range(10)])
+res_df = s_df.my_method().another_method({"new_col": "new value"})
+print(res_df)

docs/tracing_ext.md

@@ -0,0 +1,32 @@
+# method_call_ctx_factory - tracing extention of pandas_flavor
+
+`method_call_ctx_factory` global var defined in [pandas_flavor/register.py](https://github.com/pyjanitor-devs/pandas_flavor/blob/c60bfd43adbcc304b3455055af73ed9fc9ac10d1/pandas_flavor/register.py#L8) is used
+to allow the methods registered via `pandas_flavors` to be traced.
+
+Default value of `method_call_ctx_factory` is None.
+
+Starting version 0.5.0 `pandas_flavor` implements the way to pass registered method name, signature and parameters to
+be handled by user-defined object when the call is made. To allow this the user of pandas_flavor must set
+`method_call_ctx_factory` to refer to function with signature `(method_name: str, method_args: list, method_kwargs: dict) -> tracing_ctx`.
+`tracing_ctx` should be class which implements methods with signatures as below:
+
+```python
+class tracing_ctx:
+    def __enter__(self) -> None: pass
+    def __exit__(self, type, value, traceback): -> None: pass
+    def handle_start_method_call(self, method_name: str,
+                                 method_signature: inspect.Signature,
+                                 method_args: list,
+                                 method_kwargs: dict) -> (list, dict): pass
+    def handle_end_method_call(self, method_ret: object) -> None: pass
+```
+
+During method call `pandas_flavor` will create object of class `tracing_ctx` then will use that object to enter *with* code block.
+`handle_start_method_call` and `handle_end_method_call` will be called before and after actual method call. The input arguments
+and return object of actual method call will be passed to corresponding `tracing_ctx` method.
+
+So `handle_start_method_call` and `handle_end_method_call` will have the chance to implement required tracing logic.
+Aslo, __exit__ method will be called if any exception would occur. This way it is possible to handle the situation of
+actual method ends by raising exception.
+
+The example of tracer class implementation and factory function registration is given in [tracing_ext-demo.py](/docs/tracing_ext-demo.py)