Skip to content

Commit

Permalink
update doc strings and type hints
Browse files Browse the repository at this point in the history
  • Loading branch information
@royari
royari committed Feb 22, 2023
1 parent a5d6e48 commit d6aafcb
Show file tree
Hide file tree
Showing 3 changed files with 93 additions and 75 deletions.
106 changes: 59 additions & 47 deletions resdb_driver/driver.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,38 +67,43 @@ def transport(self):
def transactions(self):
""":class:`~resdb_driver.driver.TransactionsEndpoint`:
Exposes functionalities of the ``'/transactions'`` endpoint.
TODO: check
"""
return self._transactions

@property
def outputs(self):
""":class:`~resdb_driver.driver.OutputsEndpoint`:
Exposes functionalities of the ``'/outputs'`` endpoint.
TODO: check
"""
return self._outputs

@property
def assets(self):
""":class:`~resdb_driver.driver.AssetsEndpoint`:
Exposes functionalities of the ``'/assets'`` endpoint.
TODO: check
"""
return self._assets

@property
def metadata(self):
""":class:`~resdb_driver.driver.MetadataEndpoint`:
Exposes functionalities of the ``'/metadata'`` endpoint.
TODO: check
"""
return self._metadata

@property
def blocks(self):
""":class:`~resdb_driver.driver.BlocksEndpoint`:
Exposes functionalities of the ``'/blocks'`` endpoint.
TODO: check
"""
return self._blocks

def info(self, headers=None):
def info(self, headers=None) -> dict:
"""Retrieves information of the node being connected to via the
root endpoint ``'/'``.
Expand All @@ -113,14 +118,12 @@ def info(self, headers=None):
* an overview of all the endpoints
Note:
Currently limited to one node, and will be expanded to
return information for each node that this instance is
connected to.
TODO: implement the endpoin in the node (Single node)
"""
return self.transport.forward_request(method="GET", path="/", headers=headers)

def api_info(self, headers=None):
def api_info(self, headers=None) -> dict:
"""Retrieves information provided by the API root endpoint
``'/api/v1'``.
Expand All @@ -131,6 +134,8 @@ def api_info(self, headers=None):
dict: Details of the HTTP API provided by the Resdb
server.
TODO: implement the endpoin in the node
"""
return self.transport.forward_request(
method="GET",
Expand All @@ -140,6 +145,8 @@ def api_info(self, headers=None):

def get_transaction(self, txid):
# TODO
# use transactions.retieve() instead
# return self._transactions.retrieve(txid=txid)
raise NotImplementedError


Expand All @@ -162,15 +169,15 @@ def __init__(self, driver: Resdb):
self.driver = driver

@property
def transport(self):
def transport(self) -> Transport:
return self.driver.transport

@property
def api_prefix(self):
def api_prefix(self) -> str:
return self.driver.api_prefix

@property
def path(self):
def path(self) -> str:
return self.api_prefix + self.PATH


Expand All @@ -193,7 +200,7 @@ def prepare(
asset=None,
metadata=None,
inputs=None
):
) -> dict:
"""Prepares a transaction payload, ready to be fulfilled.
Args:
Expand Down Expand Up @@ -291,7 +298,7 @@ def fulfill(
"""
return fulfill_transaction(transaction, private_keys=private_keys)

def get(self, *, asset_id, operation=None, headers=None):
def get(self, *, asset_id, operation=None, headers=None) -> list:
"""Given an asset id, get its list of transactions (and
optionally filter for only ``'CREATE'`` or ``'TRANSFER'``
transactions).
Expand Down Expand Up @@ -334,7 +341,10 @@ def get(self, *, asset_id, operation=None, headers=None):
)

def send_async(self, transaction, headers=None):
"""Submit a transaction to the Federation with the mode `async`.
"""
Note:
Not used in resdb
Submit a transaction to the Federation with the mode `async`.
Args:
transaction (dict): the transaction to be sent
Expand All @@ -345,16 +355,20 @@ def send_async(self, transaction, headers=None):
dict: The transaction sent to the Federation node(s).
"""
return self.transport.forward_request(
method="POST",
path=self.path,
json=transaction,
params={"mode": "async"},
headers=headers,
)
# return self.transport.forward_request(
# method="POST",
# path=self.path,
# json=transaction,
# params={"mode": "async"},
# headers=headers,
# )
raise NotImplementedError

def send_sync(self, transaction, headers=None):
"""Submit a transaction to the Federation with the mode `sync`.
"""
Note:
Not used in resdb
Submit a transaction to the Federation with the mode `sync`.
Args:
transaction (dict): the transaction to be sent
Expand All @@ -365,13 +379,14 @@ def send_sync(self, transaction, headers=None):
dict: The transaction sent to the Federation node(s).
"""
return self.transport.forward_request(
method="POST",
path=self.path,
json=transaction,
params={"mode": "sync"},
headers=headers,
)
# return self.transport.forward_request(
# method="POST",
# path=self.path,
# json=transaction,
# params={"mode": "sync"},
# headers=headers,
# )
raise NotImplementedError

def send_commit(self, transaction: dict, headers: dict = None) -> dict:
"""Submit a transaction to the Federation with the mode `commit`.
Expand All @@ -391,7 +406,8 @@ def send_commit(self, transaction: dict, headers: dict = None) -> dict:
# json=transaction,
# params={'mode': 'commit'},
# headers=headers)
path = self.path + "commit"
function = "commit"
path = self.path + function
return self.transport.forward_request(
method="POST", path=path, json=transaction, headers=headers
)
Expand All @@ -412,7 +428,10 @@ def retrieve(self, txid: str, headers: dict = None) -> dict:


class OutputsEndpoint(NamespacedDriver):
"""Exposes functionality of the ``'/outputs'`` endpoint.
"""
TODO:
add endpoint in nodes
Exposes functionality of the ``'/outputs'`` endpoint.
Attributes:
path (str): The path of the endpoint.
Expand All @@ -421,7 +440,7 @@ class OutputsEndpoint(NamespacedDriver):

PATH = "/outputs/"

def get(self, public_key, spent=None, headers=None):
def get(self, public_key, spent=None, headers=None) -> list[dict]:
"""Get transaction outputs by public key. The public_key parameter
must be a base58 encoded ed25519 public key associated with
transaction output ownership.
Expand Down Expand Up @@ -466,8 +485,11 @@ class BlocksEndpoint(NamespacedDriver):

PATH = "/blocks/"

def get(self, *, txid, headers=None):
"""Get the block that contains the given transaction id (``txid``)
def get(self, *, txid, headers=None) -> list[dict]:
"""
TODO:
add endpoints in nodes. transaction_id is a query parameter here
Get the block that contains the given transaction id (``txid``)
else return ``None``
Args:
Expand All @@ -486,19 +508,6 @@ def get(self, *, txid, headers=None):
)
return block_list[0] if len(block_list) else None

def retrieve(self, block_height, headers=None):
"""Retrieves the block with the given ``block_height``.
Args:
block_height (str): height of the block to retrieve.
headers (dict): Optional headers to pass to the request.
Returns:
dict: The block with the given ``block_height``.
"""
path = self.path + block_height
return self.transport.forward_request(method="GET", path=path, headers=None)


class AssetsEndpoint(NamespacedDriver):
Expand All @@ -511,8 +520,11 @@ class AssetsEndpoint(NamespacedDriver):

PATH = "/assets/"

def get(self, *, search, limit=0, headers=None):
"""Retrieves the assets that match a given text search string.
def get(self, *, search, limit=0, headers=None) -> list[dict]:
"""
TODO:
add endpoints in nodes. transaction_id is a query parameter here
Retrieves the assets that match a given text search string.
Args:
search (str): Text search string.
Expand Down Expand Up @@ -542,7 +554,7 @@ class MetadataEndpoint(NamespacedDriver):

PATH = "/metadata/"

def get(self, *, search, limit=0, headers=None):
def get(self, *, search, limit=0, headers=None) -> list[dict]:
"""Retrieves the metadata that match a given text search string.
Args:
Expand Down
8 changes: 4 additions & 4 deletions resdb_driver/offchain.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ def prepare_transaction(
asset=None,
metadata=None,
inputs=None
):
) -> dict:
"""Prepares a transaction payload, ready to be fulfilled. Depending on
the value of ``operation``, simply dispatches to either
:func:`~.prepare_create_transaction` or
Expand Down Expand Up @@ -221,7 +221,7 @@ def prepare_transfer_transaction(*, inputs, recipients, asset, metadata=None):
Example:
.. todo:: Replace this section with docs.
# .. todo:: Replace this section with docs.
In case it may not be clear what an input should look like, say
Alice (public key: ``'3Cxh1eKZk3Wp9KGBWFS7iVde465UvqUKnEqTg2MW4wNf'``)
Expand Down Expand Up @@ -257,7 +257,7 @@ def prepare_transfer_transaction(*, inputs, recipients, asset, metadata=None):
'output_index': output_index,
'transaction_id': tx['id'],
},
'owners_before': output['owners_after'],
'owners_before': output['public_keys'],
}
Displaying the input on the prompt would look like::
Expand Down Expand Up @@ -311,7 +311,7 @@ def prepare_transfer_transaction(*, inputs, recipients, asset, metadata=None):
return transaction.to_dict()


def fulfill_transaction(transaction, *, private_keys):
def fulfill_transaction(transaction, *, private_keys) -> dict:
"""Fulfills the given transaction.
Args:
Expand Down
Loading

0 comments on commit d6aafcb

Please sign in to comment.