Docstrings

Author: thewhaleking

async_substrate_interface/async_substrate.py

@@ -1059,6 +1059,15 @@ async def init_runtime(
     async def get_runtime_for_version(
         self, runtime_version: int, block_hash: Optional[str] = None
     ) -> Runtime:
+        """
+        Retrieves the `Runtime` for a given runtime version at a given block hash.
+        Args:
+            runtime_version: version of the runtime (from `get_block_runtime_version_for`)
+            block_hash: hash of the block to query
+
+        Returns:
+            Runtime object for the given runtime version
+        """
         return await self._get_runtime_for_version(runtime_version, block_hash)
 
     async def _get_runtime_for_version(
@@ -1927,10 +1936,18 @@ async def get_metadata(self, block_hash=None) -> MetadataV15:
         return runtime.metadata_v15
 
     @cached_fetcher(max_size=512)
-    async def get_parent_block_hash(self, block_hash):
+    async def get_parent_block_hash(self, block_hash) -> str:
+        """
+        Retrieves the block hash of the parent of the given block hash
+        Args:
+            block_hash: hash of the block to query
+
+        Returns:
+            Hash of the parent block hash, or the original block hash (if it has not parent)
+        """
         return await self._get_parent_block_hash(block_hash)
 
-    async def _get_parent_block_hash(self, block_hash):
+    async def _get_parent_block_hash(self, block_hash) -> str:
         block_header = await self.rpc_request("chain_getHeader", [block_hash])
 
         if block_header["result"] is None:
@@ -1975,25 +1992,25 @@ async def get_storage_by_key(self, block_hash: str, storage_key: str) -> Any:
 
     @cached_fetcher(max_size=16)
     async def get_block_runtime_info(self, block_hash: str) -> dict:
+        """
+        Retrieve the runtime info of given block_hash
+        """
         return await self._get_block_runtime_info(block_hash)
 
     get_block_runtime_version = get_block_runtime_info
 
     async def _get_block_runtime_info(self, block_hash: str) -> dict:
-        """
-        Retrieve the runtime info of given block_hash
-        """
         response = await self.rpc_request("state_getRuntimeVersion", [block_hash])
         return response.get("result")
 
     @cached_fetcher(max_size=512)
     async def get_block_runtime_version_for(self, block_hash: str):
-        return await self._get_block_runtime_version_for(block_hash)
-
-    async def _get_block_runtime_version_for(self, block_hash: str):
         """
         Retrieve the runtime version of the parent of a given block_hash
         """
+        return await self._get_block_runtime_version_for(block_hash)
+
+    async def _get_block_runtime_version_for(self, block_hash: str):
         parent_block_hash = await self.get_parent_block_hash(block_hash)
         runtime_info = await self.get_block_runtime_info(parent_block_hash)
         if runtime_info is None:
@@ -2306,6 +2323,14 @@ async def rpc_request(
 
     @cached_fetcher(max_size=512)
     async def get_block_hash(self, block_id: int) -> str:
+        """
+        Retrieves the hash of the specified block number
+        Args:
+            block_id: block number
+
+        Returns:
+            Hash of the block
+        """
         return await self._get_block_hash(block_id)
 
     async def _get_block_hash(self, block_id: int) -> str:

async_substrate_interface/utils/cache.py

@@ -148,6 +148,10 @@ async def inner(self, *args, **kwargs):
 
 
 class LRUCache:
+    """
+    Basic Least-Recently-Used Cache, with simple methods `set` and `get`
+    """
+
     def __init__(self, max_size: int):
         self.max_size = max_size
         self.cache = OrderedDict()
@@ -168,12 +172,51 @@ def get(self, key):
 
 
 class CachedFetcher:
+    """
+    Async caching class that allows the standard async LRU cache system, but also allows for concurrent
+    asyncio calls (with the same args) to use the same result of a single call.
+
+    This should only be used for asyncio calls where the result is immutable.
+
+    Concept and usage:
+        ```
+        async def fetch(self, block_hash: str) -> str:
+            return await some_resource(block_hash)
+
+        a1, a2, b = await asyncio.gather(fetch("a"), fetch("a"), fetch("b"))
+        ```
+
+        Here, you are making three requests, but you really only need to make two I/O requests
+        (one for "a", one for "b"), and while you wouldn't typically make a request like this directly, it's very
+        common in using this library to inadvertently make these requests y gathering multiple resources that depend
+        on the calls like this under the hood.
+
+        By using
+
+        ```
+        @cached_fetcher(max_size=512)
+        async def fetch(self, block_hash: str) -> str:
+            return await some_resource(block_hash)
+
+        a1, a2, b = await asyncio.gather(fetch("a"), fetch("a"), fetch("b"))
+        ```
+
+        You are only making two I/O calls, and a2 will simply use the result of a1 when it lands.
+    """
+
     def __init__(
         self,
         max_size: int,
         method: Callable[..., Awaitable[Any]],
         cache_key_index: int = 0,
     ):
+        """
+        Args:
+            max_size: max size of the cache (in items)
+            method: the function to cache
+            cache_key_index: if the method takes multiple args, only one will be used as the cache key. This is the
+                index of that cache key in the args list (default is the first arg)
+        """
         self._inflight: dict[Hashable, asyncio.Future] = {}
         self._method = method
         self._cache = LRUCache(max_size=max_size)
@@ -203,7 +246,11 @@ async def __call__(self, *args: Any) -> Any:
             self._inflight.pop(key, None)
 
 
-class CachedFetcherMethod:
+class _CachedFetcherMethod:
+    """
+    Helper class for using CachedFetcher with method caches (rather than functions)
+    """
+
     def __init__(self, method, max_size: int, cache_key_index: int):
         self.method = method
         self.max_size = max_size
@@ -226,7 +273,9 @@ def __get__(self, instance, owner):
 
 
 def cached_fetcher(max_size: int, cache_key_index: int = 0):
+    """Wrapper for CachedFetcher. See example in CachedFetcher docstring."""
+
     def wrapper(method):
-        return CachedFetcherMethod(method, max_size, cache_key_index)
+        return _CachedFetcherMethod(method, max_size, cache_key_index)
 
     return wrapper