From d3f51ee398ca6302a2a87f61a14f7b47198f616a Mon Sep 17 00:00:00 2001 From: Vladimir Domnich Date: Wed, 5 Oct 2022 13:14:51 +0400 Subject: [PATCH] [#7] Add contribution guideline with code style Signed-off-by: Vladimir Domnich --- CONTRIBUTING.md | 214 +++++++++++++++++ README.md | 72 +----- src/neofs_testlib/cli/neofs_adm/config.py | 6 +- src/neofs_testlib/cli/neofs_adm/morph.py | 170 ++++++-------- .../cli/neofs_adm/storage_config.py | 8 +- src/neofs_testlib/cli/neofs_adm/subnet.py | 122 +++++----- src/neofs_testlib/cli/neofs_adm/version.py | 3 +- .../cli/neofs_authmate/secret.py | 59 +++-- .../cli/neofs_authmate/version.py | 3 +- src/neofs_testlib/cli/neogo/candidate.py | 65 +++--- src/neofs_testlib/cli/neogo/contract.py | 218 ++++++++---------- src/neofs_testlib/cli/neogo/db.py | 34 ++- src/neofs_testlib/cli/neogo/nep17.py | 150 ++++++------ src/neofs_testlib/cli/neogo/node.py | 7 +- src/neofs_testlib/cli/neogo/query.py | 78 +++---- src/neofs_testlib/cli/neogo/version.py | 5 +- src/neofs_testlib/cli/neogo/wallet.py | 203 ++++++++-------- src/neofs_testlib/reporter/dummy_reporter.py | 4 +- src/neofs_testlib/reporter/interfaces.py | 24 +- src/neofs_testlib/shell/interfaces.py | 49 ++-- src/neofs_testlib/shell/local_shell.py | 7 +- src/neofs_testlib/shell/ssh_shell.py | 9 +- tests/helpers.py | 26 ++- 23 files changed, 770 insertions(+), 766 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..da8ea41 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,214 @@ +# Contribution guide + +First, thank you for contributing! We love and encourage pull requests from +everyone. Please follow the guidelines: + +- Check the open [issues](https://github.com/nspcc-dev/neofs-testlib/issues) and + [pull requests](https://github.com/nspcc-dev/neofs-testlib/pulls) for existing + discussions. + +- Open an issue first, to discuss a new feature or enhancement. + +- Write tests, and make sure the test suite passes locally. + +- Open a pull request, and reference the relevant issue(s). + +- Make sure your commits are logically separated and have good comments + explaining the details of your change. + +- After receiving feedback, amend your commits or add new ones as appropriate. + +- **Have fun!** + +## Development Workflow + +Start by forking the `neofs-testlib` repository, make changes in a branch and then +send a pull request. We encourage pull requests to discuss code changes. Here +are the steps in details: + +### Set up your GitHub Repository +Fork [NeoFS testlib upstream](https://github.com/nspcc-dev/neofs-testlib/fork) source +repository to your own personal repository. Copy the URL of your fork and clone it: + +```shell +$ git clone +``` + +### Set up git remote as ``upstream`` +```shell +$ cd neofs-testlib +$ git remote add upstream https://github.com/nspcc-dev/neofs-testlib +$ git fetch upstream +``` + +### Set up development environment +To setup development environment for `neofs-testlib`, please, take the following steps: +1. Prepare virtualenv + +```shell +$ virtualenv --python=python3.9 venv +$ source venv/bin/activate +``` + +2. Install all dependencies: + +```shell +$ pip install -r requirements.txt +``` + +3. Setup pre-commit hooks to run code formatters on staged files before you run a `git commit` command: + +```shell +$ pre-commit install +``` + +Optionally you might want to integrate code formatters with your code editor to apply formatters to code files as you go: +* isort is supported by [PyCharm](https://plugins.jetbrains.com/plugin/15434-isortconnect), [VS Code](https://cereblanco.medium.com/setup-black-and-isort-in-vscode-514804590bf9). Plugins exist for other IDEs/editors as well. +* black can be integrated with multiple editors, please, instructions are available [here](https://black.readthedocs.io/en/stable/integrations/editors.html). + +### Create your feature branch +Before making code changes, make sure you create a separate branch for these +changes. Maybe you will find it convenient to name branch in +`/-` format. + +```shell +$ git checkout -b feature/123-something_awesome +``` + +### Test your changes +Before submitting any changes to the library, please, make sure that all unit tests are passing. To run the tests, please, use the following command: +```shell +$ python -m unittest discover --start-directory tests +``` + +To enable tests that interact with SSH server, please, setup SSH server and set the following environment variables before running the tests: +``` +SSH_SHELL_HOST =
+SSH_SHELL_LOGIN = +SSH_SHELL_PRIVATE_KEY_PATH = +SSH_SHELL_PRIVATE_KEY_PASSPHRASE = +``` + +### Commit changes +After verification, commit your changes. There is a [great +post](https://chris.beams.io/posts/git-commit/) on how to write useful commit +messages. Try following this template: + +``` +[#Issue] Summary +Description + + +``` + +```shell +$ git commit -am '[#123] Add some feature' +``` + +### Push to the branch +Push your locally committed changes to the remote origin (your fork): +```shell +$ git push origin feature/123-something_awesome +``` + +### Create a Pull Request +Pull requests can be created via GitHub. Refer to [this +document](https://help.github.com/articles/creating-a-pull-request/) for +detailed steps on how to create a pull request. After a Pull Request gets peer +reviewed and approved, it will be merged. + +## DCO Sign off + +All authors to the project retain copyright to their work. However, to ensure +that they are only submitting work that they have rights to, we are requiring +everyone to acknowledge this by signing their work. + +Any copyright notices in this repository should specify the authors as "the +contributors". + +To sign your work, just add a line like this at the end of your commit message: + +``` +Signed-off-by: Samii Sakisaka +``` + +This can easily be done with the `--signoff` option to `git commit`. + +By doing this you state that you can certify the following (from [The Developer +Certificate of Origin](https://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +1 Letterman Drive +Suite D4700 +San Francisco, CA, 94129 +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. +Developer's Certificate of Origin 1.1 +By making a contribution to this project, I certify that: +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +## Code Style +We use `black` and `isort` for code formatting. Please, refer to [Black code style](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html) for details. + +Type hints are mandatory for library's code: + - class attributes; + - function or method's parameters; + - function or method's return type. + +The only exception is return type of test functions or methods - there's no much use in specifying `None` as return type for each test function. + +Do not use relative imports. Even if the module is in the same package, use the full package name. + +To format docstrings, please, use [Google Style Docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). Type annotations should be specified in the code and not in docstrings (please, refer to [this sample](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/index.html#type-annotations)). + +## Editable installation +If you would like to modify code of the library in the integration with your test suite, you can use editable installation. For that, in virtual environment of your test suite (not in the virtual environment of the testlib itself!) run the following command (path to `neofs-testlib` directory might be different on your machine): +```shell +$ pip install -e ../neofs-testlib +``` + +## Building and publishing package +To build Python package of the library, please run the following command in the library root directory: +```shell +$ python -m build +``` + +This command will put wheel file and source archive under `dist` directory. + +To check that package description will be correctly rendered at PyPI, please, use command: +```shell +$ twine check dist/* +``` + +To upload package to [test PyPI](https://test.pypi.org/project/neofs-testlib/), please, use command: +```shell +$ twine upload -r testpypi dist/* +``` +It will prompt for your username and password. You would need to [create test PyPI account](https://test.pypi.org/account/register/) in order to execute it. + +To upload package to actual PyPI, please, use command: +```shell +$ twine upload dist/* +``` +It will prompt for your username and password. You would need to [create PyPI account](https://pypi.org/account/register/) in order to execute it. diff --git a/README.md b/README.md index bd92d6e..f097eee 100644 --- a/README.md +++ b/README.md @@ -14,74 +14,4 @@ The library provides the following primary components: * `shell` - shells that can be used to execute commands. Currently library provides local shell (on machine that runs the code) or SSH shell that connects to a remote machine via SSH. ## Contributing -Any contributions to the library should conform to the [contribution guideline](https://github.com/nspcc-dev/neofs-node/blob/master/CONTRIBUTING.md). - -### Development Environment -To setup development environment for `neofs-testlib`, please, take the following steps: -1. Prepare virtualenv - -```shell -$ virtualenv --python=python3.9 venv -$ source venv/bin/activate -``` - -2. Install all dependencies: - -```shell -$ pip install -r requirements.txt -``` - -3. Setup pre-commit hooks to run code formatters on staged files before you run a `git commit` command: - -```shell -$ pre-commit install -``` - -Optionally you might want to integrate code formatters with your code editor to apply formatters to code files as you go: -* isort is supported by [PyCharm](https://plugins.jetbrains.com/plugin/15434-isortconnect), [VS Code](https://cereblanco.medium.com/setup-black-and-isort-in-vscode-514804590bf9). Plugins exist for other IDEs/editors as well. -* black can be integrated with multiple editors, please, instructions are available [here](https://black.readthedocs.io/en/stable/integrations/editors.html). - -### Unit Tests -Before submitting any changes to the library, please, make sure that all unit tests are passing. To run the tests, please, use the following command: -```shell -$ python -m unittest discover --start-directory tests -``` - -To enable tests that interact with SSH server, please, setup SSH server and set the following environment variables before running the tests: -``` -SSH_SHELL_HOST =
-SSH_SHELL_LOGIN = -SSH_SHELL_PRIVATE_KEY_PATH = -SSH_SHELL_PRIVATE_KEY_PASSPHRASE = -``` - -### Editable installation -If you would like to modify code of the library in the integration with your test suite, you can use editable installation. For that, in virtual environment of your test suite (not in the virtual environment of the testlib itself!) run the following command (path to `neofs-testlib` directory might be different on your machine): -```shell -$ pip install -e ../neofs-testlib -``` - -### Building and publishing package -To build Python package of the library, please run the following command in the library root directory: -```shell -$ python -m build -``` - -This command will put wheel file and source archive under `dist` directory. - -To check that package description will be correctly rendered at PyPI, please, use command: -```shell -$ twine check dist/* -``` - -To upload package to [test PyPI](https://test.pypi.org/project/neofs-testlib/), please, use command: -```shell -$ twine upload -r testpypi dist/* -``` -It will prompt for your username and password. You would need to [create test PyPI account](https://test.pypi.org/account/register/) in order to execute it. - -To upload package to actual PyPI, please, use command: -```shell -$ twine upload dist/* -``` -It will prompt for your username and password. You would need to [create PyPI account](https://pypi.org/account/register/) in order to execute it. +Any contributions to the library should conform to the [contribution guideline](https://github.com/nspcc-dev/neofs-testlib/blob/master/CONTRIBUTING.md). diff --git a/src/neofs_testlib/cli/neofs_adm/config.py b/src/neofs_testlib/cli/neofs_adm/config.py index f8acfd8..86d684b 100644 --- a/src/neofs_testlib/cli/neofs_adm/config.py +++ b/src/neofs_testlib/cli/neofs_adm/config.py @@ -7,12 +7,10 @@ class NeofsAdmConfig(CliCommand): """Initialize basic neofs-adm configuration file. Args: - path (str): path to config (default ~/.neofs/adm/config.yml) - + path: Path to config (default ~/.neofs/adm/config.yml). Returns: - str: Command string - + Command's result. """ return self._execute( "config init", diff --git a/src/neofs_testlib/cli/neofs_adm/morph.py b/src/neofs_testlib/cli/neofs_adm/morph.py index 93c545b..6c67d79 100644 --- a/src/neofs_testlib/cli/neofs_adm/morph.py +++ b/src/neofs_testlib/cli/neofs_adm/morph.py @@ -16,16 +16,14 @@ class NeofsAdmMorph(CliCommand): """Deposit GAS for notary service. Args: - account (str): wallet account address - gas (str): amount of GAS to deposit - rpc_endpoint (str): N3 RPC node endpoint - storage_wallet (str): path to storage node wallet - till (str): notary deposit duration in blocks - + account: Wallet account address. + gas: Amount of GAS to deposit. + rpc_endpoint: N3 RPC node endpoint. + storage_wallet: Path to storage node wallet. + till: Notary deposit duration in blocks. Returns: - str: Command string - + Command's result. """ return self._execute( "morph deposit-notary", @@ -44,19 +42,17 @@ class NeofsAdmMorph(CliCommand): script_hash: Optional[str] = None, storage: Optional[str] = None, ) -> CommandResult: - """Dump GAS balances + """Dump GAS balances. Args: - alphabet (str): dump balances of alphabet contracts - proxy (str): dump balances of the proxy contract - rpc_endpoint (str): N3 RPC node endpoint - script_hash (str): use script-hash format for addresses - storage (str): dump balances of storage nodes from the current netmap - + alphabet: Dump balances of alphabet contracts. + proxy: Dump balances of the proxy contract. + rpc_endpoint: N3 RPC node endpoint. + script_hash: Use script-hash format for addresses. + storage: Dump balances of storage nodes from the current netmap. Returns: - str: Command string - + Command's result. """ return self._execute( "morph dump-balances", @@ -71,12 +67,10 @@ class NeofsAdmMorph(CliCommand): """Section for morph network configuration commands. Args: - rpc_endpoint (str): N3 RPC node endpoint - + rpc_endpoint: N3 RPC node endpoint Returns: - str: Command string - + Command's result. """ return self._execute( "morph dump-config", @@ -97,16 +91,13 @@ class NeofsAdmMorph(CliCommand): """Dump NeoFS containers to file. Args: - cid (str): containers to dump - container_contract (str): container contract hash (for networks without NNS) - dump (str): file where to save dumped containers - (default: ./testlib_dump_container) - rpc_endpoint (str): N3 RPC node endpoint - + cid: Containers to dump. + container_contract: Container contract hash (for networks without NNS). + dump: File where to save dumped containers (default: ./testlib_dump_container). + rpc_endpoint: N3 RPC node endpoint. Returns: - str: Command string - + Command's result. """ return self._execute( "morph dump-containers", @@ -121,12 +112,10 @@ class NeofsAdmMorph(CliCommand): """Dump deployed contract hashes. Args: - rpc_endpoint (str): N3 RPC node endpoint - + rpc_endpoint: N3 RPC node endpoint. Returns: - str: Command string - + Command's result. """ return self._execute( "morph dump-hashes", @@ -140,16 +129,14 @@ class NeofsAdmMorph(CliCommand): def force_new_epoch( self, rpc_endpoint: Optional[str] = None, alphabet: Optional[str] = None ) -> CommandResult: - """Create new NeoFS epoch event in the side chain + """Create new NeoFS epoch event in the side chain. Args: - alphabet (str): path to alphabet wallets dir - rpc_endpoint (str): N3 RPC node endpoint - + alphabet: Path to alphabet wallets dir. + rpc_endpoint: N3 RPC node endpoint. Returns: - str: Command string - + Command's result. """ return self._execute( "morph force-new-epoch", @@ -166,17 +153,15 @@ class NeofsAdmMorph(CliCommand): alphabet_wallets: str, size: int = 7, ) -> CommandResult: - """Generate alphabet wallets for consensus nodes of the morph network + """Generate alphabet wallets for consensus nodes of the morph network. Args: - alphabet_wallets (str): path to alphabet wallets dir - size (int): amount of alphabet wallets to generate (default 7) - rpc_endpoint (str): N3 RPC node endpoint - + alphabet_wallets: Path to alphabet wallets dir. + size: Amount of alphabet wallets to generate (default 7). + rpc_endpoint: N3 RPC node endpoint. Returns: - str: Command string - + Command's result. """ return self._execute( "morph generate-alphabet", @@ -194,18 +179,16 @@ class NeofsAdmMorph(CliCommand): storage_wallet: str, initial_gas: Optional[str] = None, ) -> CommandResult: - """Generate storage node wallet for the morph network + """Generate storage node wallet for the morph network. Args: - alphabet_wallets (str): path to alphabet wallets dir - initial_gas (str): initial amount of GAS to transfer - rpc_endpoint (str): N3 RPC node endpoint - storage_wallet (str): path to new storage node wallet - + alphabet_wallets: Path to alphabet wallets dir. + initial_gas: Initial amount of GAS to transfer. + rpc_endpoint: N3 RPC node endpoint. + storage_wallet: Path to new storage node wallet. Returns: - str: Command string - + Command's result. """ return self._execute( "morph generate-storage-wallet", @@ -232,23 +215,20 @@ class NeofsAdmMorph(CliCommand): """Section for morph network configuration commands. Args: - alphabet_wallets (str): path to alphabet wallets dir - container_alias_fee (int): container alias fee (default 500) - container_fee (int): container registration fee (default 1000) - contracts (str): path to archive with compiled NeoFS contracts - (default fetched from latest github release) - epoch_duration (int): amount of side chain blocks in one NeoFS epoch - (default 240) - homomorphic_disabled: (bool): disable object homomorphic hashing - local_dump (str): path to the blocks dump file - max_object_size (int): max single object size in bytes (default 67108864) - protocol (str): path to the consensus node configuration - rpc_endpoint (str): N3 RPC node endpoint - + alphabet_wallets: Path to alphabet wallets dir. + container_alias_fee: Container alias fee (default 500). + container_fee: Container registration fee (default 1000). + contracts: Path to archive with compiled NeoFS contracts + (default fetched from latest github release). + epoch_duration: Amount of side chain blocks in one NeoFS epoch (default 240). + homomorphic_disabled: Disable object homomorphic hashing. + local_dump: Path to the blocks dump file. + max_object_size: Max single object size in bytes (default 67108864). + protocol: Path to the consensus node configuration. + rpc_endpoint: N3 RPC node endpoint. Returns: - str: Command string - + Command's result. """ return self._execute( "morph init", @@ -269,15 +249,13 @@ class NeofsAdmMorph(CliCommand): """Refill GAS of storage node's wallet in the morph network Args: - alphabet_wallets (str): path to alphabet wallets dir - gas (str): additional amount of GAS to transfer - rpc_endpoint (str): N3 RPC node endpoint - storage_wallet (str): path to new storage node wallet - + alphabet_wallets: Path to alphabet wallets dir. + gas: Additional amount of GAS to transfer. + rpc_endpoint: N3 RPC node endpoint. + storage_wallet: Path to new storage node wallet. Returns: - str: Command string - + Command's result. """ return self._execute( "morph refill-gas", @@ -298,15 +276,13 @@ class NeofsAdmMorph(CliCommand): """Restore NeoFS containers from file. Args: - alphabet_wallets (str): path to alphabet wallets dir - cid (str): containers to restore - dump (str): file to restore containers from - rpc_endpoint (str): N3 RPC node endpoint - + alphabet_wallets: Path to alphabet wallets dir. + cid: Containers to restore. + dump: File to restore containers from. + rpc_endpoint: N3 RPC node endpoint. Returns: - str: Command string - + Command's result. """ return self._execute( "morph restore-containers", @@ -325,19 +301,17 @@ class NeofsAdmMorph(CliCommand): storage_price: Optional[int] = None, fee_per_byte: Optional[int] = None, ) -> CommandResult: - """Set global policy values + """Set global policy values. Args: - alphabet_wallets (str): path to alphabet wallets dir - exec_fee_factor (int): ExecFeeFactor= - storage_price (int): StoragePrice= - fee_per_byte (int): FeePerByte= - rpc_endpoint (str): N3 RPC node endpoint - + alphabet_wallets: Path to alphabet wallets dir. + exec_fee_factor: ExecFeeFactor=. + storage_price: StoragePrice=. + fee_per_byte: FeePerByte=. + rpc_endpoint: N3 RPC node endpoint. Returns: - str: Command string - + Command's result. """ non_param_attribute = "" if exec_fee_factor: @@ -364,15 +338,13 @@ class NeofsAdmMorph(CliCommand): """Update NeoFS contracts. Args: - alphabet_wallets (str): path to alphabet wallets dir - contracts (str): path to archive with compiled NeoFS contracts - (default fetched from latest github release) - rpc_endpoint (str): N3 RPC node endpoint - + alphabet_wallets: Path to alphabet wallets dir. + contracts: Path to archive with compiled NeoFS contracts + (default fetched from latest github release). + rpc_endpoint: N3 RPC node endpoint. Returns: - str: Command string - + Command's result. """ return self._execute( "morph update-contracts", diff --git a/src/neofs_testlib/cli/neofs_adm/storage_config.py b/src/neofs_testlib/cli/neofs_adm/storage_config.py index aa48f6d..75e3e06 100644 --- a/src/neofs_testlib/cli/neofs_adm/storage_config.py +++ b/src/neofs_testlib/cli/neofs_adm/storage_config.py @@ -7,13 +7,11 @@ class NeofsAdmStorageConfig(CliCommand): """Initialize basic neofs-adm configuration file. Args: - account (str): wallet account - wallet (str): path to wallet - + account: Wallet account. + wallet: Path to wallet. Returns: - str: Command string - + Command's result. """ return self._execute( "storage-config", diff --git a/src/neofs_testlib/cli/neofs_adm/subnet.py b/src/neofs_testlib/cli/neofs_adm/subnet.py index 47a1757..127136d 100644 --- a/src/neofs_testlib/cli/neofs_adm/subnet.py +++ b/src/neofs_testlib/cli/neofs_adm/subnet.py @@ -11,15 +11,13 @@ class NeofsAdmMorphSubnet(CliCommand): """Create NeoFS subnet. Args: - address (str): Address in the wallet, optional - notary (bool): Flag to create subnet in notary environment - rpc_endpoint (str): N3 RPC node endpoint - wallet (str): Path to file with wallet - + address: Address in the wallet, optional. + notary: Flag to create subnet in notary environment. + rpc_endpoint: N3 RPC node endpoint. + wallet: Path to file with wallet. Returns: - str: Command string - + Command's result. """ return self._execute( "morph subnet create", @@ -34,13 +32,11 @@ class NeofsAdmMorphSubnet(CliCommand): """Read information about the NeoFS subnet. Args: - rpc_endpoint (str): N3 RPC node endpoint - subnet (str): ID of the subnet to read - + rpc_endpoint: N3 RPC node endpoint. + subnet: ID of the subnet to read. Returns: - str: Command string - + Command's result. """ return self._execute( "morph subnet get", @@ -57,15 +53,13 @@ class NeofsAdmMorphSubnet(CliCommand): """Remove NeoFS subnet. Args: - address (str): Address in the wallet, optional - rpc_endpoint (str): N3 RPC node endpoint - subnet (str): ID of the subnet to read - wallet (str): Path to file with wallet - + address: Address in the wallet, optional. + rpc_endpoint: N3 RPC node endpoint. + subnet: ID of the subnet to read. + wallet: Path to file with wallet. Returns: - str: Command string - + Command's result. """ return self._execute( "morph subnet remove", @@ -89,18 +83,16 @@ class NeofsAdmMorphSubnet(CliCommand): """Add admin to the NeoFS subnet. Args: - address (str): Address in the wallet, optional - admin (str): Hex-encoded public key of the admin - client (str): Add client admin instead of node one - group (str): Client group ID in text format (needed with --client only) - rpc_endpoint (str): N3 RPC node endpoint - subnet (str): ID of the subnet to read - wallet (str): Path to file with wallet - + address: Address in the wallet, optional. + admin: Hex-encoded public key of the admin. + client: Add client admin instead of node one. + group: Client group ID in text format (needed with --client only). + rpc_endpoint: N3 RPC node endpoint. + subnet: ID of the subnet to read. + wallet: Path to file with wallet. Returns: - str: Command string - + Command's result. """ return self._execute( "morph subnet admin add", @@ -123,17 +115,15 @@ class NeofsAdmMorphSubnet(CliCommand): """Remove admin of the NeoFS subnet. Args: - address (str): Address in the wallet, optional - admin (str): Hex-encoded public key of the admin - client (str): Remove client admin instead of node one - rpc_endpoint (str): N3 RPC node endpoint - subnet (str): ID of the subnet to read - wallet (str): Path to file with wallet - + address: Address in the wallet, optional. + admin: Hex-encoded public key of the admin. + client: Remove client admin instead of node one. + rpc_endpoint: N3 RPC node endpoint. + subnet: ID of the subnet to read. + wallet: Path to file with wallet. Returns: - str: Command string - + Command's result. """ return self._execute( "morph subnet admin remove", @@ -156,17 +146,15 @@ class NeofsAdmMorphSubnet(CliCommand): """Add client to the NeoFS subnet. Args: - address (str): Address in the wallet, optional - client (str): Add client admin instead of node one - group (str): Client group ID in text format (needed with --client only) - rpc_endpoint (str): N3 RPC node endpoint - subnet (str): ID of the subnet to read - wallet (str): Path to file with wallet - + address: Address in the wallet, optional. + client: Add client admin instead of node one. + group: Client group ID in text format (needed with --client only). + rpc_endpoint: N3 RPC node endpoint. + subnet: ID of the subnet to read. + wallet: Path to file with wallet. Returns: - str: Command string - + Command's result. """ return self._execute( "morph subnet client add", @@ -189,17 +177,15 @@ class NeofsAdmMorphSubnet(CliCommand): """Remove client of the NeoFS subnet. Args: - address (str): Address in the wallet, optional - client (str): Remove client admin instead of node one - group (str): ID of the client group to work with - rpc_endpoint (str): N3 RPC node endpoint - subnet (str): ID of the subnet to read - wallet (str): Path to file with wallet - + address: Address in the wallet, optional. + client: Remove client admin instead of node one. + group: ID of the client group to work with. + rpc_endpoint: N3 RPC node endpoint. + subnet: ID of the subnet to read. + wallet: Path to file with wallet. Returns: - str: Command string - + Command's result. """ return self._execute( "morph subnet client remove", @@ -214,15 +200,13 @@ class NeofsAdmMorphSubnet(CliCommand): """Add node to the NeoFS subnet. Args: - node (str): Hex-encoded public key of the node - rpc_endpoint (str): N3 RPC node endpoint - subnet (str): ID of the subnet to read - wallet (str): Path to file with wallet - + node: Hex-encoded public key of the node. + rpc_endpoint: N3 RPC node endpoint. + subnet: ID of the subnet to read. + wallet: Path to file with wallet. Returns: - str: Command string - + Command's result. """ return self._execute( "morph subnet node add", @@ -237,15 +221,13 @@ class NeofsAdmMorphSubnet(CliCommand): """Remove node from the NeoFS subnet. Args: - node (str): Hex-encoded public key of the node - rpc_endpoint (str): N3 RPC node endpoint - subnet (str): ID of the subnet to read - wallet (str): Path to file with wallet - + node: Hex-encoded public key of the node. + rpc_endpoint: N3 RPC node endpoint. + subnet: ID of the subnet to read. + wallet: Path to file with wallet. Returns: - str: Command string - + Command's result. """ return self._execute( "morph subnet node remove", diff --git a/src/neofs_testlib/cli/neofs_adm/version.py b/src/neofs_testlib/cli/neofs_adm/version.py index 8d7c02d..502d578 100644 --- a/src/neofs_testlib/cli/neofs_adm/version.py +++ b/src/neofs_testlib/cli/neofs_adm/version.py @@ -7,7 +7,6 @@ class NeofsAdmVersion(CliCommand): """Application version Returns: - str: Command string - + Command's result. """ return self._execute("", version=True) diff --git a/src/neofs_testlib/cli/neofs_authmate/secret.py b/src/neofs_testlib/cli/neofs_authmate/secret.py index 12871c8..8826249 100644 --- a/src/neofs_testlib/cli/neofs_authmate/secret.py +++ b/src/neofs_testlib/cli/neofs_authmate/secret.py @@ -14,19 +14,18 @@ class NeofsAuthmateSecret(CliCommand): address: Optional[str] = None, gate_address: Optional[str] = None, ) -> CommandResult: - """Obtain a secret from NeoFS network + """Obtain a secret from NeoFS network. Args: - wallet (str): path to the wallet - address (str): address of wallet account - peer (str): address of neofs peer to connect to - gate_wallet (str): path to the wallet - gate_address (str): address of wallet account - access_key_id (str): access key id for s3 + wallet: Path to the wallet. + address: Address of wallet account. + peer: Address of neofs peer to connect to. + gate_wallet: Path to the wallet. + gate_address: Address of wallet account. + access_key_id: Access key id for s3. Returns: - str: Command string - + Command's result. """ return self._execute( "obtain-secret", @@ -55,32 +54,26 @@ class NeofsAuthmateSecret(CliCommand): """Obtain a secret from NeoFS network Args: - wallet (str): path to the wallet - address (str): address of wallet account - peer (str): address of a neofs peer to connect to - bearer_rules (str): rules for bearer token as plain json string - gate_public_key (str): public 256r1 key of a gate (use flags repeatedly for - multiple gates) - container_id (str): auth container id to put the secret into - container_friendly_name (str): friendly name of auth container to put the - secret into - container_placement_policy (str): placement policy of auth container to put the - secret into - (default: "REP 2 IN X CBF 3 SELECT 2 FROM * AS X") - session_tokens (str): create session tokens with rules, if the rules are - set as 'none', no session tokens will be created - lifetime (str): Lifetime of tokens. For example 50h30m - (note: max time unit is an hour so to set a day you - should use 24h). It will be ceil rounded to the - nearest amount of epoch. (default: 720h0m0s) - container_policy (str): mapping AWS storage class to NeoFS storage policy as - plain json string or path to json file - aws_cli_credentials (str): path to the aws cli credential file - + wallet: Path to the wallet. + address: Address of wallet account. + peer: Address of a neofs peer to connect to. + bearer_rules: Rules for bearer token as plain json string. + gate_public_key: Public 256r1 key of a gate (use flags repeatedly for multiple gates). + container_id: Auth container id to put the secret into. + container_friendly_name: Friendly name of auth container to put the secret into. + container_placement_policy: Placement policy of auth container to put the secret into + (default: "REP 2 IN X CBF 3 SELECT 2 FROM * AS X"). + session_tokens: Create session tokens with rules, if the rules are set as 'none', no + session tokens will be created. + lifetime: Lifetime of tokens. For example 50h30m (note: max time unit is an hour so to + set a day you should use 24h). It will be ceil rounded to the nearest amount of + epoch. (default: 720h0m0s). + container_policy: Mapping AWS storage class to NeoFS storage policy as plain json string + or path to json file. + aws_cli_credentials: Path to the aws cli credential file. Returns: - str: Command string - + Command's result. """ return self._execute( "issue-secret", diff --git a/src/neofs_testlib/cli/neofs_authmate/version.py b/src/neofs_testlib/cli/neofs_authmate/version.py index e146f52..ec336dc 100644 --- a/src/neofs_testlib/cli/neofs_authmate/version.py +++ b/src/neofs_testlib/cli/neofs_authmate/version.py @@ -7,7 +7,6 @@ class NeofsAuthmateVersion(CliCommand): """Application version Returns: - str: Command string - + Command's result. """ return self._execute("", version=True) diff --git a/src/neofs_testlib/cli/neogo/candidate.py b/src/neofs_testlib/cli/neogo/candidate.py index 4e796cc..50200bb 100644 --- a/src/neofs_testlib/cli/neogo/candidate.py +++ b/src/neofs_testlib/cli/neogo/candidate.py @@ -14,22 +14,19 @@ class NeoGoCandidate(CliCommand): gas: Optional[float] = None, timeout: int = 10, ) -> CommandResult: - """Register as a new candidate + """Register as a new candidate. Args: - address (str): Address to register - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. - gas (float): network fee to add to the transaction (prioritizing it) - rpc_endpoint (str): RPC node address - timeout (int): Timeout for the operation (default: 10s) - + address: Address to register. + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. + gas: Network fee to add to the transaction (prioritizing it). + rpc_endpoint: RPC node address. + timeout: Timeout for the operation (default: 10s). Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG @@ -51,22 +48,19 @@ class NeoGoCandidate(CliCommand): gas: Optional[float] = None, timeout: int = 10, ) -> CommandResult: - """Unregister self as a candidate + """Unregister self as a candidate. Args: - address (str): Address to unregister - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. - gas (float): network fee to add to the transaction (prioritizing it) - rpc_endpoint (str): RPC node address - timeout (int): Timeout for the operation (default: 10s) - + address: Address to unregister. + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. + gas: Network fee to add to the transaction (prioritizing it). + rpc_endpoint: RPC node address. + timeout: Timeout for the operation (default: 10s). Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG @@ -88,23 +82,22 @@ class NeoGoCandidate(CliCommand): gas: Optional[float] = None, timeout: int = 10, ) -> CommandResult: - """Votes for a validator by calling "vote" method of a NEO native - contract. Do not provide candidate argument to perform unvoting. + """Votes for a validator. + Voting happens by calling "vote" method of a NEO native contract. Do not provide + candidate argument to perform unvoting. Args: - candidate (str): Public key of candidate to vote for - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. - gas (float): network fee to add to the transaction (prioritizing it) - rpc_endpoint (str): RPC node address - timeout (int): Timeout for the operation (default: 10s) + candidate: Public key of candidate to vote for. + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. + gas: Network fee to add to the transaction (prioritizing it). + rpc_endpoint: RPC node address. + timeout: Timeout for the operation (default: 10s). Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG diff --git a/src/neofs_testlib/cli/neogo/contract.py b/src/neofs_testlib/cli/neogo/contract.py index a097e4d..5329978 100644 --- a/src/neofs_testlib/cli/neogo/contract.py +++ b/src/neofs_testlib/cli/neogo/contract.py @@ -16,22 +16,21 @@ class NeoGoContract(CliCommand): no_permissions: bool = False, bindings: Optional[str] = None, ) -> CommandResult: - """Compile a smart contract to a .nef file + """Compile a smart contract to a .nef file. Args: - input_file (str): Input file for the smart contract to be compiled - out (str): Output of the compiled contract - manifest (str): Emit contract manifest (*.manifest.json) file into separate - file using configuration input file (*.yml) - config (str): Configuration input file (*.yml) - no_standards (bool): do not check compliance with supported standards - no_events (bool): do not check emitted events with the manifest - no_permissions (bool): do not check if invoked contracts are allowed in manifest - bindings (str): output file for smart-contract bindings configuration + input_file: Input file for the smart contract to be compiled. + out: Output of the compiled contract. + manifest: Emit contract manifest (*.manifest.json) file into separate file using + configuration input file (*.yml). + config: Configuration input file (*.yml). + no_standards: Do not check compliance with supported standards. + no_events: Do not check emitted events with the manifest. + no_permissions: Do not check if invoked contracts are allowed in manifest. + bindings: Output file for smart-contract bindings configuration. Returns: - str: Command string - + Command's result. """ return self._execute( "contract compile", @@ -59,24 +58,23 @@ class NeoGoContract(CliCommand): """Deploy a smart contract (.nef with description) Args: - wallet (str): wallet to use to get the key for transaction signing; - conflicts with wallet_config - wallet_config (str): path to wallet config to use to get the key for transaction - signing; conflicts with wallet - address (str): address to use as transaction signee (and gas source) - gas (float): network fee to add to the transaction (prioritizing it) - sysgas (float): system fee to add to transaction (compensating for execution) - out (str): file to put JSON transaction to - force (bool): Do not ask for a confirmation - rpc_endpoint (str): RPC node address - timeout (int): Timeout for the operation (default: 10s) - input_file (str): Input file for the smart contract (*.nef) - manifest (str): Emit contract manifest (*.manifest.json) file into separate - file using configuration input file (*.yml) + wallet: Wallet to use to get the key for transaction signing; + conflicts with wallet_config. + wallet_config: Path to wallet config to use to get the key for transaction signing; + conflicts with wallet. + address: Address to use as transaction signee (and gas source). + gas: Network fee to add to the transaction (prioritizing it). + sysgas: System fee to add to transaction (compensating for execution). + out: File to put JSON transaction to. + force: Do not ask for a confirmation. + rpc_endpoint: RPC node address. + timeout: Timeout for the operation (default: 10s). + input_file: Input file for the smart contract (*.nef). + manifest: Emit contract manifest (*.manifest.json) file into separate file using + configuration input file (*.yml). Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG @@ -96,17 +94,16 @@ class NeoGoContract(CliCommand): config: Optional[str] = None, manifest: Optional[str] = None, ) -> CommandResult: - """Generate wrapper to use in other contracts + """Generate wrapper to use in other contracts. Args: - config (str): Configuration file to use - manifest (str): Read contract manifest (*.manifest.json) file - out (str): Output of the compiled contract - hash (str): Smart-contract hash + config: Configuration file to use. + manifest: Read contract manifest (*.manifest.json) file. + out: Output of the compiled contract. + hash: Smart-contract hash. Returns: - str: Command string - + Command's result. """ return self._execute( "contract generate-wrapper", @@ -133,34 +130,33 @@ class NeoGoContract(CliCommand): rpc_endpoint: Optional[str] = None, timeout: int = 10, ) -> CommandResult: - """Executes given (as a script hash) deployed script with the given method, - arguments and signers. Sender is included in the list of signers by default - with None witness scope. If you'd like to change default sender's scope, - specify it via signers parameter. See testinvokefunction documentation for - the details about parameters. It differs from testinvokefunction in that this - command sends an invocation transaction to the network. + """Executes given (as a script hash) deployed script. + + Script is executed with the given method, arguments and signers. Sender is included in + the list of signers by default with None witness scope. If you'd like to change default + sender's scope, specify it via signers parameter. See testinvokefunction documentation + for the details about parameters. It differs from testinvokefunction in that this command + sends an invocation transaction to the network. Args: - scripthash (str): Function hash - method (str): Call method - arguments (str): Method arguments - multisig_hash (str): Multisig hash - wallet (str): wallet to use to get the key for transaction signing; - conflicts with wallet_config - wallet_config (str): path to wallet config to use to get the key for transaction - signing; conflicts with wallet - address (str): address to use as transaction signee (and gas source) - gas (float): network fee to add to the transaction (prioritizing it) - sysgas (float): system fee to add to transaction (compensating for execution) - out (str): file to put JSON transaction to - force (bool): force-push the transaction in case of bad VM state after - test script invocation - rpc_endpoint (str): RPC node address - timeout (int): Timeout for the operation (default: 10s) + scripthash: Function hash. + method: Call method. + arguments: Method arguments. + multisig_hash: Multisig hash. + wallet: Wallet to use to get the key for transaction signing; + conflicts with wallet_config. + wallet_config: Path to wallet config to use to get the key for transaction signing; + conflicts with wallet. + address: Address to use as transaction signee (and gas source). + gas: Network fee to add to the transaction (prioritizing it). + sysgas: System fee to add to transaction (compensating for execution). + out: File to put JSON transaction to. + force: Force-push the transaction in case of bad VM state after test script invocation. + rpc_endpoint: RPC node address. + timeout: Timeout for the operation (default: 10s). Returns: - str: Command string - + Command's result. """ multisig_hash = f"-- {multisig_hash}" or "" return self._execute( @@ -183,28 +179,27 @@ class NeoGoContract(CliCommand): rpc_endpoint: Optional[str] = None, timeout: int = 10, ) -> CommandResult: - """Executes given (as a script hash) deployed script with the given method, - arguments and signers (sender is not included by default). If no method is given - "" is passed to the script, if no arguments are given, an empty array is - passed, if no signers are given no array is passed. If signers are specified, - the first one of them is treated as a sender. All of the given arguments are - encapsulated into array before invoking the script. The script thus should - follow the regular convention of smart contract arguments (method string and - an array of other arguments). + """Executes given (as a script hash) deployed script. - See more information and samples in `neo-go contract testinvokefunction --help` + Script is executed with the given method, arguments and signers (sender is not included + by default). If no method is given "" is passed to the script, if no arguments are given, + an empty array is passed, if no signers are given no array is passed. If signers are + specified, the first one of them is treated as a sender. All of the given arguments are + encapsulated into array before invoking the script. The script thus should follow the + regular convention of smart contract arguments (method string and an array of other + arguments). + See more information and samples in `neo-go contract testinvokefunction --help`. Args: - scripthash (str): Function hash - method (str): Call method - arguments (str): Method arguments - multisig_hash (str): Multisig hash - rpc_endpoint (str): RPC node address - timeout (int): Timeout for the operation (default: 10s) + scripthash: Function hash. + method: Call method. + arguments: Method arguments. + multisig_hash: Multisig hash. + rpc_endpoint: RPC node address. + timeout: Timeout for the operation (default: 10s). Returns: - str: Command string - + Command's result. """ multisig_hash = f"-- {multisig_hash}" or "" return self._execute( @@ -223,20 +218,18 @@ class NeoGoContract(CliCommand): rpc_endpoint: Optional[str] = None, timeout: int = 10, ) -> CommandResult: - """Executes given compiled AVM instructions in NEF format with the given set of - signers not included sender by default. See testinvokefunction documentation - for the details about parameters. + """Executes given compiled AVM instructions in NEF format. + Instructions are executed with the given set of signers not including sender by default. + See testinvokefunction documentation for the details about parameters. Args: - input_file (str): Input location of the .nef file that needs to be invoked - conflicts with wallet_config - rpc_endpoint (str): RPC node address - timeout (int): Timeout for the operation (default: 10s) + input_file: Input location of the .nef file that needs to be invoked. + rpc_endpoint: RPC node address. + timeout: Timeout for the operation (default: 10s). Returns: - str: Command string - + Command's result. """ return self._execute( f"contract testinvokescript", @@ -247,20 +240,15 @@ class NeoGoContract(CliCommand): }, ) - def init( - self, - name: str, - skip_details: bool = False, - ) -> CommandResult: - """Initialize a new smart-contract in a directory with boiler plate code + def init(self, name: str, skip_details: bool = False) -> CommandResult: + """Initialize a new smart-contract in a directory with boiler plate code. Args: - name (str): name of the smart-contract to be initialized - skip_details (bool): skip filling in the projects and contract details + name: Name of the smart-contract to be initialized. + skip_details: Skip filling in the projects and contract details. Returns: - str: Command string - + Command's result. """ return self._execute( "contract init", @@ -276,15 +264,14 @@ class NeoGoContract(CliCommand): input_file: Optional[str] = None, compile: Optional[str] = None, ) -> CommandResult: - """Creates a user readable dump of the program instructions + """Creates a user readable dump of the program instructions. Args: - input_file (str): input file of the program (either .go or .nef) - compile (str): compile input file (it should be go code then) + input_file: Input file of the program (either .go or .nef). + compile: Compile input file (it should be go code then). Returns: - str: Command string - + Command's result. """ return self._execute( "contract inspect", @@ -301,16 +288,15 @@ class NeoGoContract(CliCommand): manifest: str, sender: Optional[str] = None, ) -> CommandResult: - """Calculates hash of a contract after deployment + """Calculates hash of a contract after deployment. Args: - input_file (str): path to NEF file - sender (str): sender script hash or address - manifest (str): path to manifest file + input_file: Path to NEF file. + sender: Sender script hash or address. + manifest: Path to manifest file. Returns: - str: Command string - + Command's result. """ return self._execute( "contract calc-hash", @@ -330,22 +316,18 @@ class NeoGoContract(CliCommand): sender: Optional[str] = None, nef: Optional[str] = None, ) -> CommandResult: - """Adds group to the manifest + """Adds group to the manifest. Args: - wallet (str): wallet to use to get the key for transaction signing; - conflicts with wallet_config - wallet_config (str): path to wallet config to use to get the key for transaction - signing; conflicts with wallet - sender (str): deploy transaction sender - address (str): account to sign group with - nef (str): path to the NEF file - manifest (str): path to the manifest - + wallet: Wallet to use to get the key for transaction signing; conflicts with wallet_config. + wallet_config: Path to wallet config to use to get the key for transaction signing; conflicts with wallet. + sender: Deploy transaction sender. + address: Account to sign group with. + nef: Path to the NEF file. + manifest: Path to the manifest. Returns: - str: Command string - + Command's result. """ return self._execute( "contract manifest add-group", diff --git a/src/neofs_testlib/cli/neogo/db.py b/src/neofs_testlib/cli/neogo/db.py index 05bece2..ae3185d 100644 --- a/src/neofs_testlib/cli/neogo/db.py +++ b/src/neofs_testlib/cli/neogo/db.py @@ -14,19 +14,17 @@ class NeoGoDb(CliCommand): count: int = 0, start: int = 0, ) -> CommandResult: - """Dump blocks (starting with block #1) to the file + """Dump blocks (starting with block #1) to the file. Args: - config_path (str): path to config - network (NetworkType): Select network type (default: private) - count (int): number of blocks to be processed (default or 0: all chain) - (default: 0) - start (int): block number to start from (default: 0) (default: 0) - out (srt): Output file (stdout if not given) + config_path: Path to config. + network: Select network type (default: private). + count: Number of blocks to be processed (default or 0: all chain) (default: 0). + start: Block number to start from (default: 0) (default: 0). + out: Output file (stdout if not given). Returns: - str: Command string - + Command's result. """ return self._execute( "db dump", @@ -47,20 +45,18 @@ class NeoGoDb(CliCommand): dump: Optional[str] = None, incremental: bool = False, ) -> CommandResult: - """Dump blocks (starting with block #1) to the file + """Dump blocks (starting with block #1) to the file. Args: - config_path (str): path to config - network (NetworkType): Select network type (default: private) - count (int): number of blocks to be processed (default or 0: all chain) - (default: 0) - input_file (str): Input file (stdin if not given) - dump (str): directory for storing JSON dumps - incremental (bool): use if dump is incremental + config_path: Path to config. + network: Select network type (default: private). + count: Number of blocks to be processed (default or 0: all chain) (default: 0). + input_file: Input file (stdin if not given). + dump: Directory for storing JSON dumps. + incremental: Use if dump is incremental. Returns: - str: Command string - + Command's result. """ return self._execute( "db restore", diff --git a/src/neofs_testlib/cli/neogo/nep17.py b/src/neofs_testlib/cli/neogo/nep17.py index 8d89c25..edd65eb 100644 --- a/src/neofs_testlib/cli/neogo/nep17.py +++ b/src/neofs_testlib/cli/neogo/nep17.py @@ -14,21 +14,19 @@ class NeoGoNep17(CliCommand): wallet_config: Optional[str] = None, timeout: int = 10, ) -> CommandResult: - """Get address balance + """Get address balance. Args: - address (str): Address to use - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. - token (str): Token to use (hash or name (for NEO/GAS or imported tokens)) - rpc_endpoint (str): RPC node address - timeout (int): Timeout for the operation (default: 10s) + address: Address to use. + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. + token: Token to use (hash or name (for NEO/GAS or imported tokens)). + rpc_endpoint: RPC node address. + timeout: Timeout for the operation (default: 10s). Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG @@ -50,21 +48,19 @@ class NeoGoNep17(CliCommand): rpc_endpoint: Optional[str] = None, timeout: int = 10, ) -> CommandResult: - """import NEP-17 token to a wallet + """Import NEP-17 token to a wallet. Args: - address (str): Token contract address or hash in LE - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. - token (str): Token to use (hash or name (for NEO/GAS or imported tokens)) - rpc_endpoint (str): RPC node address - timeout (int): Timeout for the operation (default: 10s) + address: Token contract address or hash in LE. + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. + token: Token to use (hash or name (for NEO/GAS or imported tokens)). + rpc_endpoint: RPC node address. + timeout: Timeout for the operation (default: 10s). Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG @@ -83,18 +79,16 @@ class NeoGoNep17(CliCommand): wallet: Optional[str] = None, wallet_config: Optional[str] = None, ) -> CommandResult: - """print imported NEP-17 token info + """Print imported NEP-17 token info. Args: - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. - token (str): Token to use (hash or name (for NEO/GAS or imported tokens)) + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. + token: Token to use (hash or name (for NEO/GAS or imported tokens)). Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG @@ -114,19 +108,17 @@ class NeoGoNep17(CliCommand): wallet_config: Optional[str] = None, force: bool = False, ) -> CommandResult: - """remove NEP-17 token from the wallet + """Remove NEP-17 token from the wallet. Args: - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. - token (str): Token to use (hash or name (for NEO/GAS or imported tokens)) - force (bool): Do not ask for a confirmation + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. + token: Token to use (hash or name (for NEO/GAS or imported tokens)). + force: Do not ask for a confirmation. Returns: - str: Command string - + Command's result. """ return self._execute( "wallet nep17 remove", @@ -152,33 +144,32 @@ class NeoGoNep17(CliCommand): amount: float = 0, timeout: int = 10, ) -> CommandResult: - """Transfers specified NEP-17 token amount with optional 'data' parameter and cosigners - list attached to the transfer. See 'contract testinvokefunction' documentation - for the details about 'data' parameter and cosigners syntax. If no 'data' is - given then default nil value will be used. If no cosigners are given then the - sender with CalledByEntry scope will be used as the only signer. + """Transfers specified NEP-17 token amount. + + Transfer is executed with optional 'data' parameter and cosigners list attached to the + transfer. See 'contract testinvokefunction' documentation for the details about 'data' + parameter and cosigners syntax. If no 'data' is given then default nil value will be used. + If no cosigners are given then the sender with CalledByEntry scope will be used as the only + signer. Args: - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. - out (str): file to put JSON transaction to - from_address (str): Address to send an asset from - to_address (str): Address to send an asset to - token (str): Token to use (hash or name (for NEO/GAS or imported tokens)) - force (bool): Do not ask for a confirmation - gas (float): network fee to add to the transaction (prioritizing it) - sysgas (float): system fee to add to transaction (compensating for execution) - force (bool): Do not ask for a confirmation - amount (float) Amount of asset to send - rpc_endpoint (str): RPC node address - timeout (int): Timeout for the operation (default: 10s) - + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. + out: File to put JSON transaction to. + from_address: Address to send an asset from. + to_address: Address to send an asset to. + token: Token to use (hash or name (for NEO/GAS or imported tokens)). + force: Do not ask for a confirmation. + gas: Network fee to add to the transaction (prioritizing it). + sysgas: System fee to add to transaction (compensating for execution). + force: Do not ask for a confirmation. + amount: Amount of asset to send. + rpc_endpoint: RPC node address. + timeout: Timeout for the operation (default: 10s). Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG @@ -206,29 +197,26 @@ class NeoGoNep17(CliCommand): amount: float = 0, timeout: int = 10, ) -> CommandResult: - """transfer NEP-17 tokens to multiple recipients + """Transfer NEP-17 tokens to multiple recipients. Args: - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. - out (str): file to put JSON transaction to - from_address (str): Address to send an asset from - to_address (str): Address to send an asset to - token (str): Token to use (hash or name (for NEO/GAS or imported tokens)) - force (bool): Do not ask for a confirmation - gas (float): network fee to add to the transaction (prioritizing it) - sysgas (float): system fee to add to transaction (compensating for execution) - force (bool): Do not ask for a confirmation - amount (float) Amount of asset to send - rpc_endpoint (str): RPC node address - timeout (int): Timeout for the operation (default: 10s) - + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. + out: File to put JSON transaction to. + from_address: Address to send an asset from. + to_address: Address to send an asset to. + token: Token to use (hash or name (for NEO/GAS or imported tokens)). + force: Do not ask for a confirmation. + gas: Network fee to add to the transaction (prioritizing it). + sysgas: System fee to add to transaction (compensating for execution). + force: Do not ask for a confirmation. + amount: Amount of asset to send. + rpc_endpoint: RPC node address. + timeout: Timeout for the operation (default: 10s). Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG diff --git a/src/neofs_testlib/cli/neogo/node.py b/src/neofs_testlib/cli/neogo/node.py index 0d79561..8fe4d28 100644 --- a/src/neofs_testlib/cli/neogo/node.py +++ b/src/neofs_testlib/cli/neogo/node.py @@ -5,13 +5,12 @@ from neofs_testlib.shell import CommandResult class NeoGoNode(CliCommand): def start(self, network: NetworkType = NetworkType.PRIVATE) -> CommandResult: - """Start a NEO node + """Start a NEO node. Args: - network (NetworkType): Select network type (default: private) + network: Select network type (default: private). Returns: - str: Command string - + Command's result. """ return self._execute("start", **{network.value: True}) diff --git a/src/neofs_testlib/cli/neogo/query.py b/src/neofs_testlib/cli/neogo/query.py index 1567026..6d93799 100644 --- a/src/neofs_testlib/cli/neogo/query.py +++ b/src/neofs_testlib/cli/neogo/query.py @@ -3,20 +3,15 @@ from neofs_testlib.shell import CommandResult class NeoGoQuery(CliCommand): - def candidates( - self, - rpc_endpoint: str, - timeout: int = 10, - ) -> CommandResult: - """Get candidates and votes + def candidates(self, rpc_endpoint: str, timeout: int = 10) -> CommandResult: + """Get candidates and votes. Args: - rpc_endpoint (str): RPC node address - timeout (int): Timeout for the operation (default: 10s) + rpc_endpoint: RPC node address. + timeout: Timeout for the operation (default: 10s). Returns: - str: Command string - + Command's result. """ return self._execute( "query candidates", @@ -27,20 +22,15 @@ class NeoGoQuery(CliCommand): }, ) - def committee( - self, - rpc_endpoint: str, - timeout: int = 10, - ) -> CommandResult: - """Get committee list + def committee(self, rpc_endpoint: str, timeout: int = 10) -> CommandResult: + """Get committee list. Args: - rpc_endpoint (str): RPC node address - timeout (int): Timeout for the operation (default: 10s) + rpc_endpoint: RPC node address. + timeout: Timeout for the operation (default: 10s). Returns: - str: Command string - + Command's result. """ return self._execute( "query committee", @@ -51,20 +41,15 @@ class NeoGoQuery(CliCommand): }, ) - def height( - self, - rpc_endpoint: str, - timeout: int = 10, - ) -> CommandResult: - """Get node height + def height(self, rpc_endpoint: str, timeout: int = 10) -> CommandResult: + """Get node height. Args: - rpc_endpoint (str): RPC node address - timeout (int): Timeout for the operation (default: 10s) + rpc_endpoint: RPC node address. + timeout: Timeout for the operation (default: 10s). Returns: - str: Command string - + Command's result. """ return self._execute( "query height", @@ -75,22 +60,16 @@ class NeoGoQuery(CliCommand): }, ) - def tx( - self, - tx_hash: str, - rpc_endpoint: str, - timeout: int = 10, - ) -> CommandResult: - """Query transaction status + def tx(self, tx_hash: str, rpc_endpoint: str, timeout: int = 10) -> CommandResult: + """Query transaction status. Args: - tx_hash (str): Hash of transaction - rpc_endpoint (str): RPC node address - timeout (int): Timeout for the operation (default: 10s) + tx_hash: Hash of transaction. + rpc_endpoint: RPC node address. + timeout: Timeout for the operation (default: 10s). Returns: - str: Command string - + Command's result. """ return self._execute( f"query tx {tx_hash}", @@ -101,20 +80,15 @@ class NeoGoQuery(CliCommand): }, ) - def voter( - self, - rpc_endpoint: str, - timeout: int = 10, - ) -> CommandResult: - """Print NEO holder account state + def voter(self, rpc_endpoint: str, timeout: int = 10) -> CommandResult: + """Print NEO holder account state. Args: - rpc_endpoint (str): RPC node address - timeout (int): Timeout for the operation (default: 10s) + rpc_endpoint: RPC node address. + timeout: Timeout for the operation (default: 10s). Returns: - str: Command string - + Command's result. """ return self._execute( "query voter", diff --git a/src/neofs_testlib/cli/neogo/version.py b/src/neofs_testlib/cli/neogo/version.py index 18f52bd..0d56bdb 100644 --- a/src/neofs_testlib/cli/neogo/version.py +++ b/src/neofs_testlib/cli/neogo/version.py @@ -4,10 +4,9 @@ from neofs_testlib.shell import CommandResult class NeoGoVersion(CliCommand): def get(self) -> CommandResult: - """Application version + """Application version. Returns: - str: Command string - + Command's result. """ return self._execute("", version=True) diff --git a/src/neofs_testlib/cli/neogo/wallet.py b/src/neofs_testlib/cli/neogo/wallet.py index c5cf012..e327fb5 100644 --- a/src/neofs_testlib/cli/neogo/wallet.py +++ b/src/neofs_testlib/cli/neogo/wallet.py @@ -13,20 +13,18 @@ class NeoGoWallet(CliCommand): wallet_config: Optional[str] = None, timeout: int = 10, ) -> CommandResult: - """claim GAS + """Claim GAS. Args: - address (str): Address to claim GAS for - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. - rpc_endpoint (str): RPC node address - timeout (int): Timeout for the operation (default: 10s) + address: Address to claim GAS for. + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. + rpc_endpoint: RPC node address. + timeout: Timeout for the operation (default: 10s). Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG @@ -45,18 +43,16 @@ class NeoGoWallet(CliCommand): wallet_config: Optional[str] = None, account: bool = False, ) -> CommandResult: - """create a new wallet + """Create a new wallet. Args: - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. - account (bool): Create a new account + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. + account: Create a new account. Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG @@ -75,18 +71,16 @@ class NeoGoWallet(CliCommand): wallet: Optional[str] = None, wallet_config: Optional[str] = None, ) -> CommandResult: - """convert addresses from existing NEO2 NEP6-wallet to NEO3 format + """Convert addresses from existing NEO2 NEP6-wallet to NEO3 format. Args: - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. - out (str): where to write converted wallet + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. + out: Where to write converted wallet. Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG @@ -104,17 +98,15 @@ class NeoGoWallet(CliCommand): wallet: Optional[str] = None, wallet_config: Optional[str] = None, ) -> CommandResult: - """add an account to the existing wallet + """Add an account to the existing wallet. Args: - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG @@ -133,18 +125,16 @@ class NeoGoWallet(CliCommand): wallet_config: Optional[str] = None, decrypt: bool = False, ) -> CommandResult: - """check and dump an existing NEO wallet + """Check and dump an existing NEO wallet. Args: - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. - decrypt (bool): Decrypt encrypted keys. + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. + decrypt: Decrypt encrypted keys. Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG @@ -163,18 +153,16 @@ class NeoGoWallet(CliCommand): wallet: Optional[str] = None, wallet_config: Optional[str] = None, ) -> CommandResult: - """check and dump an existing NEO wallet + """Check and dump an existing NEO wallet. Args: - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. - address (str): address to print public keys for + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. + address: Address to print public keys for. Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG @@ -193,18 +181,16 @@ class NeoGoWallet(CliCommand): wallet_config: Optional[str] = None, decrypt: bool = False, ) -> CommandResult: - """export keys for address + """Export keys for address. Args: - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. - decrypt (bool): Decrypt encrypted keys. + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. + decrypt: Decrypt encrypted keys. Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG @@ -225,20 +211,18 @@ class NeoGoWallet(CliCommand): wallet: Optional[str] = None, wallet_config: Optional[str] = None, ) -> CommandResult: - """import WIF of a standard signature contract + """Import WIF of a standard signature contract. Args: - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. - wif (str): WIF to import - name (str): Optional account name - contract (str): Verification script for custom contracts + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. + wif: WIF to import. + name: Optional account name. + contract: Verification script for custom contracts. Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG @@ -259,20 +243,18 @@ class NeoGoWallet(CliCommand): wallet: Optional[str] = None, wallet_config: Optional[str] = None, ) -> CommandResult: - """import multisig contract + """Import multisig contract. Args: - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. - wif (str): WIF to import - name (str): Optional account name - min_number (int): Minimal number of signatures (default: 0) + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. + wif: WIF to import. + name: Optional account name. + min_number: Minimal number of signatures (default: 0). Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG @@ -295,22 +277,20 @@ class NeoGoWallet(CliCommand): contract: Optional[str] = None, timeout: int = 10, ) -> CommandResult: - """import multisig contract + """Import deployed contract. Args: - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. - wif (str): WIF to import - name (str): Optional account name - contract (str): Contract hash or address - rpc_endpoint (str): RPC node address - timeout (int): Timeout for the operation (default: 10s) + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. + wif: WIF to import. + name: Optional account name. + contract: Contract hash or address. + rpc_endpoint: RPC node address. + timeout: Timeout for the operation (default: 10s). Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG @@ -330,19 +310,17 @@ class NeoGoWallet(CliCommand): wallet_config: Optional[str] = None, force: bool = False, ) -> CommandResult: - """check and dump an existing NEO wallet + """Remove an account from the wallet. Args: - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. - address (str): Account address or hash in LE form to be removed - force (bool): Do not ask for a confirmation + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. + address: Account address or hash in LE form to be removed. + force: Do not ask for a confirmation. Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG @@ -365,22 +343,27 @@ class NeoGoWallet(CliCommand): out: Optional[str] = None, timeout: int = 10, ) -> CommandResult: - """import multisig contract + """Cosign transaction with multisig/contract/additional account. + + Signs the given (in the input file) context (which must be a transaction signing context) + for the given address using the given wallet. This command can output the resulting JSON + (with additional signature added) right to the console (if no output file and no RPC + endpoint specified) or into a file (which can be the same as input one). If an RPC endpoint + is given it'll also try to construct a complete transaction and send it via RPC (printing + its hash if everything is OK). Args: - wallet (str): Target location of the wallet file ('-' to read from stdin); - conflicts with --wallet-config flag. - wallet_config (str): Target location of the wallet config file; - conflicts with --wallet flag. - out (str): file to put JSON transaction to - input_file (str): file with JSON transaction - address (str): Address to use - rpc_endpoint (str): RPC node address - timeout (int): Timeout for the operation (default: 10s) + wallet: Target location of the wallet file ('-' to read from stdin); + conflicts with --wallet-config flag. + wallet_config: Target location of the wallet config file; conflicts with --wallet flag. + out: File to put JSON transaction to. + input_file: File with JSON transaction. + address: Address to use. + rpc_endpoint: RPC node address. + timeout: Timeout for the operation (default: 10s). Returns: - str: Command string - + Command's result. """ assert bool(wallet) ^ bool(wallet_config), self.WALLET_SOURCE_ERROR_MSG diff --git a/src/neofs_testlib/reporter/dummy_reporter.py b/src/neofs_testlib/reporter/dummy_reporter.py index 1d8cfde..9ca206b 100644 --- a/src/neofs_testlib/reporter/dummy_reporter.py +++ b/src/neofs_testlib/reporter/dummy_reporter.py @@ -10,9 +10,7 @@ def _dummy_step(): class DummyReporter(Reporter): - """ - Dummy implementation of reporter, does not store artifacts anywhere. - """ + """Dummy implementation of reporter, does not store artifacts anywhere.""" def step(self, name: str) -> AbstractContextManager: return _dummy_step() diff --git a/src/neofs_testlib/reporter/interfaces.py b/src/neofs_testlib/reporter/interfaces.py index 347f71f..5343678 100644 --- a/src/neofs_testlib/reporter/interfaces.py +++ b/src/neofs_testlib/reporter/interfaces.py @@ -4,25 +4,25 @@ from typing import Any class Reporter(ABC): - """ - Interface that supports storage of test artifacts in some reporting tool. - """ + """Interface that supports storage of test artifacts in some reporting tool.""" @abstractmethod def step(self, name: str) -> AbstractContextManager: - """ - Register a new step in test execution. + """Register a new step in test execution. - :param str name: Name of the step - :return: step context + Args: + name: Name of the step. + + Returns: + Step context. """ @abstractmethod def attach(self, content: Any, file_name: str) -> None: - """ - Attach specified content with given file name to the test report. + """Attach specified content with given file name to the test report. - :param any content: content to attach. If content value is not a string, it will be - converted to a string. - :param str file_name: file name of attachment. + Args: + content: Content to attach. If content value is not a string, it will be + converted to a string. + file_name: File name of attachment. """ diff --git a/src/neofs_testlib/shell/interfaces.py b/src/neofs_testlib/shell/interfaces.py index 97ba7cc..4d6e8ac 100644 --- a/src/neofs_testlib/shell/interfaces.py +++ b/src/neofs_testlib/shell/interfaces.py @@ -5,11 +5,11 @@ from typing import Optional @dataclass class InteractiveInput: - """ - Interactive input for a shell command. + """Interactive input for a shell command. - :attr str prompt_pattern: regular expression that defines expected prompt from the command. - :attr str input: user input that should be supplied to the command in response to the prompt. + Attributes: + prompt_pattern: regular expression that defines expected prompt from the command. + input: user input that should be supplied to the command in response to the prompt. """ prompt_pattern: str @@ -18,14 +18,14 @@ class InteractiveInput: @dataclass class CommandOptions: - """ - Options that control command execution. + """Options that control command execution. - :attr list interactive_inputs: user inputs that should be interactively supplied to - the command during execution. - :attr int timeout: timeout for command execution (in seconds). - :attr bool check: controls whether to check return code of the command. Set to False to - ignore non-zero return codes. + Attributes: + interactive_inputs: user inputs that should be interactively supplied to + the command during execution. + timeout: timeout for command execution (in seconds). + check: controls whether to check return code of the command. Set to False to + ignore non-zero return codes. """ interactive_inputs: Optional[list[InteractiveInput]] = None @@ -35,8 +35,12 @@ class CommandOptions: @dataclass class CommandResult: - """ - Represents a result of a command executed via shell. + """Represents a result of a command executed via shell. + + Attributes: + stdout: complete content of stdout stream. + stderr: complete content of stderr stream. + return_code: return code (or exit code) of the command's process. """ stdout: str @@ -45,17 +49,18 @@ class CommandResult: class Shell(ABC): - """ - Interface of a command shell on some system (local or remote). - """ + """Interface of a command shell on some system (local or remote).""" @abstractmethod def exec(self, command: str, options: Optional[CommandOptions] = None) -> CommandResult: - """ - Executes specified command on this shell. To execute interactive command, user inputs - should be specified in *options*. + """Executes specified command on this shell. - :param str command: command to execute on the shell. - :param CommandOptions options: options that control command execution. - :return command result. + To execute interactive command, user inputs should be specified in *options*. + + Args: + command: Command to execute on the shell. + options: Options that control command execution. + + Returns: + Command's result. """ diff --git a/src/neofs_testlib/shell/local_shell.py b/src/neofs_testlib/shell/local_shell.py index 0b8681a..a329990 100644 --- a/src/neofs_testlib/shell/local_shell.py +++ b/src/neofs_testlib/shell/local_shell.py @@ -14,9 +14,7 @@ reporter = get_reporter() class LocalShell(Shell): - """ - Implements command shell on a local machine. - """ + """Implements command shell on a local machine.""" def exec(self, command: str, options: Optional[CommandOptions] = None) -> CommandResult: # If no options were provided, use default options @@ -122,7 +120,8 @@ class LocalShell(Shell): def _get_pexpect_process_result( self, command_process: Optional[pexpect.spawn], command: str ) -> CommandResult: - """ + """Captures output of the process. + If command process is not None, captures output of this process. If command process is None, then command fails when we attempt to start it, in this case we use regular non-interactive process to get it's output. diff --git a/src/neofs_testlib/shell/ssh_shell.py b/src/neofs_testlib/shell/ssh_shell.py index 6ed4f7a..967fbbf 100644 --- a/src/neofs_testlib/shell/ssh_shell.py +++ b/src/neofs_testlib/shell/ssh_shell.py @@ -26,7 +26,7 @@ reporter = get_reporter() class HostIsNotAvailable(Exception): - """Raised when host is not reachable via SSH connection""" + """Raised when host is not reachable via SSH connection.""" def __init__(self, host: str = None): msg = f"Host {host} is not available" @@ -63,8 +63,7 @@ def log_command(func): @lru_cache def _load_private_key(file_path: str, password: Optional[str]) -> PKey: - """ - Loads private key from specified file. + """Loads private key from specified file. We support several type formats, however paramiko doesn't provide functionality to determine key type in advance. So we attempt to load file with each of the supported formats and then @@ -81,9 +80,7 @@ def _load_private_key(file_path: str, password: Optional[str]) -> PKey: class SSHShell(Shell): - """ - Implements command shell on a remote machine via SSH connection. - """ + """Implements command shell on a remote machine via SSH connection.""" # Time in seconds to delay after remote command has completed. The delay is required # to allow remote command to flush its output buffer diff --git a/tests/helpers.py b/tests/helpers.py index 1cb393a..8ee11b0 100644 --- a/tests/helpers.py +++ b/tests/helpers.py @@ -4,12 +4,15 @@ from neofs_testlib.shell.interfaces import CommandResult def format_error_details(error: Exception) -> str: - """ - Converts specified exception instance into a string that includes error message - and full stack trace. + """Converts specified exception instance into a string. - :param Exception error: exception to convert. - :return: string containing exception details. + The resulting string includes error message and the full stack trace. + + Args: + error: Exception to convert. + + Returns: + String containing exception details. """ detail_lines = traceback.format_exception( etype=type(error), @@ -20,11 +23,14 @@ def format_error_details(error: Exception) -> str: def get_output_lines(result: CommandResult) -> list[str]: - """ - Converts output of specified command result into separate lines trimmed from whitespaces. - Empty lines are excluded. + """Converts output of specified command result into separate lines. - :param CommandResult result: result which output should be converted. - :return: list of lines extracted from the output. + Whitespaces are trimmed, empty lines are excluded. + + Args: + result: Command result which output should be converted. + + Returns: + List of lines extracted from the output. """ return [line.strip() for line in result.stdout.split("\n") if line.strip()]