vastly improve entity_to_dict() speed

1 files changed, 9 insertions, 1 deletions

diff --git a/python/fatcat_tools/transforms.py b/python/fatcat_tools/transforms.py
index 37cbf1d2..9cb557ad 100644
--- a/python/fatcat_tools/transforms.py
+++ b/python/fatcat_tools/transforms.py
@@ -5,7 +5,13 @@ from fatcat_client import ApiClient
 
 def entity_to_dict(entity, api_client=None):
     """
-    Hack to take advantage of the code-generated serialization code
+    Hack to take advantage of the code-generated serialization code.
+
+    Initializing/destroying ApiClient objects is surprisingly expensive
+    (because it involves a threadpool), so we allow passing an existing
+    instance. If you already have a full-on API connection `api`, you can
+    access the ApiClient object as `api.api_client`. This is such a speed-up
+    that this argument may become mandatory.
     """
     if not api_client:
         api_client = ApiClient()
@@ -14,6 +20,8 @@ def entity_to_dict(entity, api_client=None):
 def entity_from_json(json_str, entity_type, api_client=None):
     """
     Hack to take advantage of the code-generated deserialization code
+
+    See not on `entity_to_dict()` about api_client argument.
     """
     if not api_client:
         api_client = ApiClient()