Skip to content

refactor: update docstrings to use 'data container' #289

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 13, 2025
Merged

refactor: update docstrings to use 'data container' #289

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions cardano_clusterlib/address_group.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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)])
Expand All @@ -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(
Expand Down
2 changes: 1 addition & 1 deletion cardano_clusterlib/clusterlib_klass.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]

Expand Down
2 changes: 1 addition & 1 deletion cardano_clusterlib/conway_gov_drep_group.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
2 changes: 1 addition & 1 deletion cardano_clusterlib/genesis_group.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion cardano_clusterlib/governance_group.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down
6 changes: 3 additions & 3 deletions cardano_clusterlib/node_group.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -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"
Expand Down
4 changes: 2 additions & 2 deletions cardano_clusterlib/query_group.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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)
Expand Down
11 changes: 7 additions & 4 deletions cardano_clusterlib/stake_address_group.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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).
Expand Down
16 changes: 9 additions & 7 deletions cardano_clusterlib/stake_pool_group.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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).
Expand Down Expand Up @@ -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"
Expand Down
30 changes: 16 additions & 14 deletions cardano_clusterlib/transaction_group.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 = (
Expand Down Expand Up @@ -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).
Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -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).
Expand Down Expand Up @@ -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."
Expand Down Expand Up @@ -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).
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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).
Expand Down Expand Up @@ -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()

Expand Down Expand Up @@ -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).
Expand Down Expand Up @@ -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
Expand All @@ -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",
Expand Down
10 changes: 5 additions & 5 deletions cardano_clusterlib/txtools.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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).
Expand Down Expand Up @@ -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).
Expand All @@ -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()

Expand Down Expand Up @@ -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)
Expand Down
Loading