Merge pull request input-output-hk#289 from input-output-hk/fix_docstrings

mkoura · mkoura · commit 6474a932063b · 2025-02-21T15:44:56.000+01:00
refactor: update docstrings to use 'data container'
diff --git a/cardano_clusterlib/address_group.py b/cardano_clusterlib/address_group.py
@@ -93,7 +93,7 @@ def gen_payment_key_pair(
             destination_dir: A path to directory for storing artifacts (optional).
 
         Returns:
-            structs.KeyPair: A tuple containing the key pair.
+            structs.KeyPair: A data container containing the key pair.
         """
         destination_dir = pl.Path(destination_dir).expanduser()
         vkey = destination_dir / f"{key_name}.vkey"
@@ -155,7 +155,7 @@ def get_address_info(
             address: A Cardano address.
 
         Returns:
-            structs.AddressInfo: A tuple containing address info.
+            structs.AddressInfo: A data container containing address info.
         """
         addr_dict: dict[str, str] = json.loads(
             self._clusterlib_obj.cli(["address", "info", "--address", str(address)])
@@ -180,7 +180,8 @@ def gen_payment_addr_and_keys(
             destination_dir: A path to directory for storing artifacts (optional).
 
         Returns:
-            structs.AddressRecord: A tuple containing the address and key pair / script file.
+            structs.AddressRecord: A data container containing the address and
+                key pair / script file.
         """
         key_pair = self.gen_payment_key_pair(key_name=name, destination_dir=destination_dir)
         addr = self.gen_payment_addr(
diff --git a/cardano_clusterlib/clusterlib_klass.py b/cardano_clusterlib/clusterlib_klass.py
@@ -249,7 +249,7 @@ def cli(
             add_default_args: Whether to add default arguments to the command (optional).
 
         Returns:
-            structs.CLIOut: A tuple containing command stdout and stderr.
+            structs.CLIOut: A data container containing command stdout and stderr.
         """
         cli_args_strs_all = [str(arg) for arg in cli_args]
 
diff --git a/cardano_clusterlib/conway_gov_drep_group.py b/cardano_clusterlib/conway_gov_drep_group.py
@@ -68,7 +68,7 @@ def gen_key_pair(self, key_name: str, destination_dir: itp.FileType = ".") -> st
             destination_dir: A path to directory for storing artifacts (optional).
 
         Returns:
-            structs.KeyPair: A tuple containing the key pair.
+            structs.KeyPair: A data container containing the key pair.
         """
         destination_dir = pl.Path(destination_dir).expanduser()
         vkey = destination_dir / f"{key_name}_drep.vkey"
diff --git a/cardano_clusterlib/genesis_group.py b/cardano_clusterlib/genesis_group.py
@@ -22,7 +22,7 @@ def __init__(self, clusterlib_obj: "itp.ClusterLib") -> None:
 
     @property
     def genesis_keys(self) -> structs.GenesisKeys:
-        """Return tuple with genesis-related keys."""
+        """Return data container with genesis-related keys."""
         if self._genesis_keys:
             return self._genesis_keys
 
diff --git a/cardano_clusterlib/governance_group.py b/cardano_clusterlib/governance_group.py
@@ -194,7 +194,7 @@ def submit_update_proposal(
             destination_dir: A path to directory for storing artifacts (optional).
 
         Returns:
-            structs.TxRawOutput: A tuple with transaction output details.
+            structs.TxRawOutput: A data container with transaction output details.
         """
         # TODO: assumption is update proposals submitted near beginning of epoch
         epoch = epoch if epoch is not None else self._clusterlib_obj.g_query.get_epoch()
diff --git a/cardano_clusterlib/node_group.py b/cardano_clusterlib/node_group.py
@@ -25,7 +25,7 @@ def gen_kes_key_pair(
             destination_dir: A path to directory for storing artifacts (optional).
 
         Returns:
-            structs.KeyPair: A tuple containing the key pair.
+            structs.KeyPair: A data container containing the key pair.
         """
         destination_dir = pl.Path(destination_dir).expanduser()
         vkey = destination_dir / f"{node_name}_kes.vkey"
@@ -56,7 +56,7 @@ def gen_vrf_key_pair(
             destination_dir: A path to directory for storing artifacts (optional).
 
         Returns:
-            structs.KeyPair: A tuple containing the key pair.
+            structs.KeyPair: A data container containing the key pair.
         """
         destination_dir = pl.Path(destination_dir).expanduser()
         vkey = destination_dir / f"{node_name}_vrf.vkey"
@@ -87,7 +87,7 @@ def gen_cold_key_pair_and_counter(
             destination_dir: A path to directory for storing artifacts (optional).
 
         Returns:
-            structs.ColdKeyPair: A tuple containing the key pair and the counter.
+            structs.ColdKeyPair: A data container containing the key pair and the counter.
         """
         destination_dir = pl.Path(destination_dir).expanduser()
         vkey = destination_dir / f"{node_name}_cold.vkey"
diff --git a/cardano_clusterlib/query_group.py b/cardano_clusterlib/query_group.py
@@ -248,7 +248,7 @@ def get_stake_addr_info(self, stake_addr: str) -> structs.StakeAddrInfo:
             stake_addr: A stake address string.
 
         Returns:
-            structs.StakeAddrInfo: A tuple containing stake address info.
+            structs.StakeAddrInfo: A data container containing stake address info.
         """
         output_json = json.loads(self.query_cli(["stake-address-info", "--address", stake_addr]))
         if not output_json:
@@ -433,7 +433,7 @@ def get_utxo_with_highest_amount(
             coin: A coin name (asset IDs).
 
         Returns:
-            structs.UTXOData: An UTxO record with the highest amount.
+            structs.UTXOData: A UTxO record with the highest amount.
         """
         utxo = self.get_utxo(address=address, coins=[coin])
         highest_amount_rec = max(utxo, key=lambda x: x.amount)
diff --git a/cardano_clusterlib/stake_address_group.py b/cardano_clusterlib/stake_address_group.py
@@ -139,7 +139,7 @@ def gen_stake_key_pair(
             destination_dir: A path to directory for storing artifacts (optional).
 
         Returns:
-            structs.KeyPair: A tuple containing the key pair.
+            structs.KeyPair: A data container containing the key pair.
         """
         destination_dir = pl.Path(destination_dir).expanduser()
         vkey = destination_dir / f"{key_name}_stake.vkey"
@@ -485,7 +485,8 @@ def gen_stake_addr_and_keys(
             destination_dir: A path to directory for storing artifacts (optional).
 
         Returns:
-            structs.AddressRecord: A tuple containing the address and key pair / script file.
+            structs.AddressRecord: A data container containing the address
+                and key pair / script file.
         """
         key_pair = self.gen_stake_key_pair(key_name=name, destination_dir=destination_dir)
         addr = self.gen_stake_addr(
@@ -535,8 +536,10 @@ def withdraw_reward(
         """Withdraw reward to payment address.
 
         Args:
-            stake_addr_record: An `structs.AddressRecord` tuple for the stake address with reward.
-            dst_addr_record: An `structs.AddressRecord` tuple for the destination payment address.
+            stake_addr_record: A `structs.AddressRecord` data container for the stake address
+                with reward.
+            dst_addr_record: A `structs.AddressRecord` data container for the destination
+                payment address.
             tx_name: A name of the transaction.
             verify: A bool indicating whether to verify that the reward was transferred correctly.
             destination_dir: A path to directory for storing artifacts (optional).
diff --git a/cardano_clusterlib/stake_pool_group.py b/cardano_clusterlib/stake_pool_group.py
@@ -44,7 +44,7 @@ def gen_pool_registration_cert(
         """Generate a stake pool registration certificate.
 
         Args:
-            pool_data: A `structs.PoolData` tuple containing info about the stake pool.
+            pool_data: A `structs.PoolData` data container containing info about the stake pool.
             vrf_vkey_file: A path to node VRF vkey file.
             cold_vkey_file: A path to pool cold vkey file.
             owner_stake_vkey_files: A list of paths to pool owner stake vkey files.
@@ -182,14 +182,14 @@ def create_stake_pool(
         """Create and register a stake pool.
 
         Args:
-            pool_data: A `structs.PoolData` tuple containing info about the stake pool.
+            pool_data: A `structs.PoolData` data container containing info about the stake pool.
             pool_owners: A list of `structs.PoolUser` structures containing pool user addresses
                 and keys.
             tx_name: A name of the transaction.
             destination_dir: A path to directory for storing artifacts (optional).
 
         Returns:
-            structs.PoolCreationOutput: A tuple containing pool creation output.
+            structs.PoolCreationOutput: A data container containing pool creation output.
         """
         # Create the KES key pair
         node_kes = self._clusterlib_obj.g_node.gen_kes_key_pair(
@@ -249,11 +249,12 @@ def register_stake_pool(
         """Register a stake pool.
 
         Args:
-            pool_data: A `structs.PoolData` tuple containing info about the stake pool.
+            pool_data: A `structs.PoolData` data container containing info about the stake pool.
             pool_owners: A list of `structs.PoolUser` structures containing pool user addresses
                 and keys.
             vrf_vkey_file: A path to node VRF vkey file.
-            cold_key_pair: A `structs.ColdKeyPair` tuple containing the key pair and the counter.
+            cold_key_pair: A `structs.ColdKeyPair` data container containing the key pair
+                and the counter.
             tx_name: A name of the transaction.
             reward_account_vkey_file: A path to reward account vkey file (optional).
             deposit: A deposit amount needed by the transaction (optional).
@@ -307,14 +308,15 @@ def deregister_stake_pool(
         Args:
             pool_owners: A list of `structs.PoolUser` structures containing pool user addresses
                 and keys.
-            cold_key_pair: A `structs.ColdKeyPair` tuple containing the key pair and the counter.
+            cold_key_pair: A `structs.ColdKeyPair` data container containing the key pair
+                and the counter.
             epoch: An epoch where the update proposal will take effect (optional).
             pool_name: A name of the stake pool.
             tx_name: A name of the transaction.
             destination_dir: A path to directory for storing artifacts (optional).
 
         Returns:
-            Tuple[Path, structs.TxRawOutput]: A tuple with pool registration cert file and
+            Tuple[Path, structs.TxRawOutput]: A data container with pool registration cert file and
                 transaction output details.
         """
         tx_name = f"{tx_name}_dereg_pool"
diff --git a/cardano_clusterlib/transaction_group.py b/cardano_clusterlib/transaction_group.py
@@ -139,7 +139,8 @@ def get_tx_deposit(self, tx_files: structs.TxFiles) -> int:
         """Get deposit amount for a transaction (based on certificates used for the TX).
 
         Args:
-            tx_files: A `structs.TxFiles` tuple containing files needed for the transaction.
+            tx_files: A `structs.TxFiles` data container containing files needed
+                for the transaction.
 
         Returns:
             int: A total deposit amount needed for the transaction.
@@ -205,7 +206,8 @@ def build_raw_tx_bare(  # noqa: C901
         Args:
             out_file: An output file.
             txouts: A list (iterable) of `TxOuts`, specifying transaction outputs.
-            tx_files: A `structs.TxFiles` tuple containing files needed for the transaction.
+            tx_files: A `structs.TxFiles` data container containing files needed
+                for the transaction.
             fee: A fee amount.
             txins: An iterable of `structs.UTXOData`, specifying input UTxOs (optional).
             readonly_reference_txins: An iterable of `structs.UTXOData`, specifying input
@@ -239,7 +241,7 @@ def build_raw_tx_bare(  # noqa: C901
                 by payment address (True by default).
 
         Returns:
-            structs.TxRawOutput: A tuple with transaction output details.
+            structs.TxRawOutput: A data container with transaction output details.
         """
         if (treasury_donation is not None) != (current_treasury_value is not None):
             msg = (
@@ -444,7 +446,7 @@ def build_raw_tx(
             total_collateral_amount: An integer indicating the total amount of collateral
                 (optional).
             mint: An iterable of `Mint`, specifying script minting data (optional).
-            tx_files: A `structs.TxFiles` tuple containing files needed for the transaction
+            tx_files: A `structs.TxFiles` data container containing files needed for the transaction
                 (optional).
             complex_certs: An iterable of `ComplexCert`, specifying certificates script data
                 (optional).
@@ -472,7 +474,7 @@ def build_raw_tx(
             destination_dir: A path to directory for storing artifacts (optional).
 
         Returns:
-            structs.TxRawOutput: A tuple with transaction output details.
+            structs.TxRawOutput: A data container with transaction output details.
         """
         destination_dir = pl.Path(destination_dir).expanduser()
         out_file = destination_dir / f"{tx_name}_tx.body"
@@ -631,7 +633,7 @@ def calculate_tx_fee(
             total_collateral_amount: An integer indicating the total amount of collateral
                 (optional).
             mint: An iterable of `Mint`, specifying script minting data (optional).
-            tx_files: A `structs.TxFiles` tuple containing files needed for the transaction
+            tx_files: A `structs.TxFiles` data container containing files needed for the transaction
                 (optional).
             complex_certs: An iterable of `ComplexCert`, specifying certificates script data
                 (optional).
@@ -723,7 +725,7 @@ def calculate_min_req_utxo(
             txouts: A list of `TxOut` records that correspond to a single transaction output (UTxO).
 
         Returns:
-            structs.Value: A tuple describing the value.
+            structs.Value: A data container describing the value.
         """
         if not txouts:
             msg = "No txout was specified."
@@ -798,7 +800,7 @@ def build_tx(  # noqa: C901
             total_collateral_amount: An integer indicating the total amount of collateral
                 (optional).
             mint: An iterable of `Mint`, specifying script minting data (optional).
-            tx_files: A `structs.TxFiles` tuple containing files needed for the transaction
+            tx_files: A `structs.TxFiles` data container containing files needed for the transaction
                 (optional).
             complex_certs: An iterable of `ComplexCert`, specifying certificates script data
                 (optional).
@@ -831,7 +833,7 @@ def build_tx(  # noqa: C901
                 (`build` command balance the assets automatically in newer versions).
 
         Returns:
-            structs.TxRawOutput: A tuple with transaction output details.
+            structs.TxRawOutput: A data container with transaction output details.
         """
         max_txout = [o for o in txouts if o.amount == -1 and o.coin in ("", consts.DEFAULT_COIN)]
         if max_txout:
@@ -1266,7 +1268,7 @@ def send_tx(
             total_collateral_amount: An integer indicating the total amount of collateral
                 (optional).
             mint: An iterable of `Mint`, specifying script minting data (optional).
-            tx_files: A `structs.TxFiles` tuple containing files needed for the transaction
+            tx_files: A `structs.TxFiles` data container containing files needed for the transaction
                 (optional).
             complex_certs: An iterable of `ComplexCert`, specifying certificates script data
                 (optional).
@@ -1297,7 +1299,7 @@ def send_tx(
             destination_dir: A path to directory for storing artifacts (optional).
 
         Returns:
-            structs.TxRawOutput: A tuple with transaction output details.
+            structs.TxRawOutput: A data container with transaction output details.
         """
         tx_files = tx_files or structs.TxFiles()
 
@@ -1512,7 +1514,7 @@ def calculate_plutus_script_cost(
             total_collateral_amount: An integer indicating the total amount of collateral
                 (optional).
             mint: An iterable of `Mint`, specifying script minting data (optional).
-            tx_files: A `structs.TxFiles` tuple containing files needed for the transaction
+            tx_files: A `structs.TxFiles` data container containing files needed for the transaction
                 (optional).
             complex_certs: An iterable of `ComplexCert`, specifying certificates script data
                 (optional).
@@ -1578,7 +1580,7 @@ def send_funds(
             src_address: An address used for fee and inputs.
             destinations: A list (iterable) of `TxOuts`, specifying transaction outputs.
             tx_name: A name of the transaction.
-            tx_files: A `structs.TxFiles` tuple containing files needed for the transaction
+            tx_files: A `structs.TxFiles` data container containing files needed for the transaction
                 (optional).
             fee: A fee amount (optional).
             ttl: A last block when the transaction is still valid
@@ -1590,7 +1592,7 @@ def send_funds(
             destination_dir: A path to directory for storing artifacts (optional).
 
         Returns:
-            structs.TxRawOutput: A tuple with transaction output details.
+            structs.TxRawOutput: A data container with transaction output details.
         """
         warnings.warn(
             "`send_funds` is deprecated, use `send_tx` instead",
diff --git a/cardano_clusterlib/txtools.py b/cardano_clusterlib/txtools.py
@@ -131,7 +131,7 @@ def _pick_utxos_with_defragmentation(
     """Pick UTxOs to meet or exceed the target amount while prioritizing defragmentation.
 
     Args:
-        utxos (list of tuple): A list of tuples (utxo_id, coin_amount).
+        utxos (list of tuples): A list of tuples (utxo_id, coin_amount).
         target_amount (int): The desired amount.
         target_with_change (int): The desired amount with minimal change.
         accumulated_amount (int): The accumulated amount.
@@ -645,7 +645,7 @@ def _get_tx_ins_outs(
     Args:
         clusterlib_obj: An instance of `ClusterLib`.
         src_address: An address used for fee and inputs (if inputs not specified by `txins`).
-        tx_files: A `structs.TxFiles` tuple containing files needed for the transaction.
+        tx_files: A `structs.TxFiles` data container containing files needed for the transaction.
         txins: An iterable of `structs.UTXOData`, specifying input UTxOs (optional).
         txouts: A list (iterable) of `TxOuts`, specifying transaction outputs (optional).
         fee: A fee amount (optional).
@@ -771,7 +771,7 @@ def collect_data_for_build(
         txouts: A list (iterable) of `TxOuts`, specifying transaction outputs (optional).
         script_txins: An iterable of `ScriptTxIn`, specifying input script UTxOs (optional).
         mint: An iterable of `Mint`, specifying script minting data (optional).
-        tx_files: A `structs.TxFiles` tuple containing files needed for the transaction
+        tx_files: A `structs.TxFiles` data container containing files needed for the transaction
             (optional).
         complex_certs: An iterable of `ComplexCert`, specifying certificates script data
             (optional).
@@ -788,7 +788,7 @@ def collect_data_for_build(
             (`build` command balance the assets automatically in newer versions).
 
     Returns:
-        structs.DataForBuild: A tuple with data for build(-raw) commands.
+        structs.DataForBuild: A data container with data for build(-raw) commands.
     """
     tx_files = tx_files or structs.TxFiles()
 
@@ -960,7 +960,7 @@ def filter_utxo_with_highest_amount(
         coin: A coin name (asset IDs).
 
     Returns:
-        structs.UTXOData: An UTxO record with the highest amount.
+        structs.UTXOData: A UTxO record with the highest amount.
     """
     filtered_utxos = [u for u in utxos if u.coin == coin]
     highest_amount_rec = max(filtered_utxos, key=lambda x: x.amount)
