docs: improve documentation and design markdown

domain/metadata/token_metadata.py

@@ -32,17 +32,17 @@ class MetaToken:
     :param id: Token unique id
     :type id: str
 
-    :param verified: If token is verified or not
-    :type verified: bool
+    :param verified: If token is verified or not. None and False are equivalent
+    :type verified: Optional[bool]
 
-    :param banned: If token is banned or not
-    :type banned: bool
+    :param banned: If token is banned or not. None and False are equivalent
+    :type banned: Optional[bool]
 
     :param reason: Bannishment reason
-    :type reason: str
+    :type reason: Optional[str]
 
     :param nft: NFT data, if any.
-    :type nft: :py:class:`domain.metadata.token_metdata.TokenNFT`
+    :type nft: Optional[:py:class:`domain.metadata.token_metdata.TokenNFT`]
     """
     id: str
     verified: Optional[bool] = False

gateways/metadata_gateway.py

@@ -1,5 +1,5 @@
 import json
-from typing import Union
+from typing import Optional
 
 from common.configuration import METADATA_BUCKET
 from domain.metadata.metadata import MetadataType
@@ -15,10 +15,10 @@
 
 class MetadataGateway:
 
-    def __init__(self, s3_client: Union[S3Client, None] = None) -> None:
+    def __init__(self, s3_client: Optional[S3Client] = None) -> None:
         self.s3_client = s3_client or S3Client()
 
-    def get_transaction_metadata(self, id: str) -> Union[TransactionMetadata, None]:
+    def get_transaction_metadata(self, id: str) -> Optional[TransactionMetadata]:
         """Retrieve transaction metadata from a json file stored in s3
 
         :param id: transaction id
@@ -35,12 +35,12 @@ def get_transaction_metadata(self, id: str) -> Union[TransactionMetadata, None]:
 
         return TransactionMetadata.from_dict(transaction_metadata)
 
-    def get_token_metadata(self, id: str) -> Union[TokenMetadata, None]:
+    def get_token_metadata(self, id: str) -> Optional[TokenMetadata]:
         """Retrieve token metadata from a json file stored in s3
 
         :param id: token id
         :type id: str
-        :raises Exception: The name of the bucket used to store the jsons must be on config
+
         :return: TokenMetadata object or None if not found
         :rtype: TokenMetadata | None
         """
@@ -52,7 +52,17 @@ def get_token_metadata(self, id: str) -> Union[TokenMetadata, None]:
 
         return TokenMetadata.from_dict(token_metadata)
 
-    def _get_metadata(self, s3_object_name: str) -> Union[dict, None]:
+    def _get_metadata(self, s3_object_name: str) -> Optional[dict]:
+        """Retrive metadata from file in s3
+
+        :param s3_object_name: name of object
+        :type s3_object_name: str
+
+        :raises Exception: The name of the bucket used to store the jsons must be on config
+
+        :return: file content as dict
+        :rtype: Optional[dict]
+        """
         metadata_bucket = self._metadata_bucket()
 
         raw_metadata = self.s3_client.load_file(metadata_bucket, s3_object_name)

text/0003-metadata-api.md

@@ -7,13 +7,14 @@
 # Summary
 [summary]: #summary
 
-Metadata APi will provide metadata information about Hathor Network Entities. It will start with Transactions and Tokens
+Metadata API will provide metadata information about Transactions, Tokens, Blocks and other things on Network.
+It will start with Transactions and Tokens
 
 # Motivation
 [motivation]: #motivation
 
-We need to have some data about Hathor Network Entities that can't be stored on the blockchain.
-So, we store somewhere else and retrieve them through MetadataAPI
+We need to have some data about Transactions, Tokens, Blocks and other things on Network that can't be stored on the
+blockchain. So, we store somewhere else and retrieve them through MetadataAPI
 
 # Guide-level explanation
 [guide-level-explanation]: #guide-level-explanation

usecases/get_metadata.py

@@ -1,14 +1,14 @@
-from typing import Union
+from typing import Optional
 
 from gateways.metadata_gateway import MetadataGateway
 
 
 class GetMetadata:
 
-    def __init__(self, metadata_gateway: Union[MetadataGateway, None] = None) -> None:
+    def __init__(self, metadata_gateway: Optional[MetadataGateway] = None) -> None:
         self.metadata_gateway = metadata_gateway or MetadataGateway()
 
-    def get(self, type: str, id: str) -> Union[dict, None]:
+    def get(self, type: str, id: str) -> Optional[dict]:
         metadata_methods = {
             'token': self.metadata_gateway.get_token_metadata,
             'transaction': self.metadata_gateway.get_transaction_metadata
@@ -18,10 +18,12 @@ def get(self, type: str, id: str) -> Union[dict, None]:
 
         method = metadata_methods.get(type, None)
 
-        if method:
-            meta = method(id)
+        if method is None:
+            return None
 
-        if meta:
-            return meta.to_dict()
+        meta = method(id)
 
-        return None
+        if meta is None:
+            return None
+
+        return meta.to_dict()

usecases/get_token_metadata.py

@@ -1,14 +1,18 @@
-from typing import Union
+from typing import Optional
 
 from gateways.metadata_gateway import MetadataGateway
 
 
 class GetTokenMetadata:
+    """Get token metadata
 
-    def __init__(self, metadata_gateway: Union[MetadataGateway, None] = None) -> None:
+    :deprecated:
+    """
+
+    def __init__(self, metadata_gateway: Optional[MetadataGateway] = None) -> None:
         self.metadata_gateway = metadata_gateway or MetadataGateway()
 
-    def get(self, id: str) -> Union[dict, None]:
+    def get(self, id: str) -> Optional[dict]:
         meta = self.metadata_gateway.get_token_metadata(id)
 
         if meta: