cloudru-qa-ssh-client 1.0.0__py3-none-any.whl

cloudru_qa_ssh_client-1.0.0.dist-info/METADATA

@@ -0,0 +1,492 @@
+Metadata-Version: 2.5
+Name: cloudru-qa-ssh-client
+Version: 1.0.0
+Summary: Простой SSH-клиент для автотестов
+Project-URL: Repository, https://github.com/cloud-ru-tech/qa-libraries
+Project-URL: Issues, https://github.com/cloud-ru-tech/qa-libraries/issues
+Author-email: akfernatii <akfernatii@cloud.ru>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: asyncssh<3,>=2.14.0
+Requires-Dist: paramiko<5.2,>=5.1.0
+Provides-Extra: structlog
+Requires-Dist: structlog>=26.1.0; extra == 'structlog'
+Description-Content-Type: text/markdown
+
+# SSH client
+
+[![PyPI](https://img.shields.io/pypi/v/cloudru-qa-ssh-client)](https://pypi.org/project/cloudru-qa-ssh-client/)
+[![Python](https://img.shields.io/pypi/pyversions/cloudru-qa-ssh-client)](https://pypi.org/project/cloudru-qa-ssh-client/)
+[![License](https://img.shields.io/pypi/l/cloudru-qa-ssh-client)](https://github.com/cloud-ru-tech/qa-libraries/blob/master/LICENSE)
+
+English | [Русский](README.ru.md)
+
+A simple SSH client library for automated tests: synchronous and asynchronous clients with
+constructor options, command decorators, and logging.
+
+## Installation
+
+Requires Python 3.13 or later.
+
+```shell
+pip install cloudru-qa-ssh-client
+```
+
+For structured logging with structlog, install the `structlog` extra:
+
+```shell
+pip install "cloudru-qa-ssh-client[structlog]"
+```
+
+Import the library as the module `ssh_client`.
+
+## Skills for AI agents
+
+This library does not have its own skill yet. If your project uses other
+libraries from this suite with [skills for AI agents](https://github.com/cloud-ru-tech/qa-libraries#skills-for-ai-agents),
+select and enable them from your project root (requires [`uv`](https://docs.astral.sh/uv/)):
+
+```shell
+uvx library-skills
+```
+
+For Claude Code, add `--claude`.
+
+## Main features
+
+1. Connect to remote hosts using a password or a key
+2. Run commands as strings or lists of shell command fragments
+3. Set timeouts for the client and individual requests
+4. Check exit codes with `raise_for_status=True` for individual commands
+5. Configure retry counts and intervals
+6. Retry connection and command failures
+7. Get result objects with stdout, stderr, and exit code fields
+8. Log requests and responses with a supplied logger
+9. Mask request and response logs using strings or regular expressions
+10. Use asynchronous clients through asyncssh
+11. Receive output in real time for interactive commands
+12. Interrupt commands with conditional callbacks
+
+## Usage example
+
+### Synchronous client
+
+```python
+import logging
+from ssh_client import SyncSSHClient, options
+
+# Create a logger
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+# Create a client
+client = SyncSSHClient(
+    "example.com",
+    22,
+    options.with_password("user", "password"),
+    options.with_request_timeout(30),
+    options.with_logger(logger),
+)
+
+# Run a command
+result = client.execute(["ls", "-la"])
+print(f"Exit code: {result.exit_code}")
+print(f"Stdout: {result.stdout}")
+print(f"Stderr: {result.stderr}")
+
+# Close the connection
+client.close()
+```
+
+### Asynchronous client
+
+```python
+import asyncio
+import logging
+from ssh_client import AsyncSSHClient, options
+
+
+async def main():
+    # Create a logger
+    logger = logging.getLogger(__name__)
+    logger.setLevel(logging.INFO)
+
+    # Create a client
+    client = AsyncSSHClient(
+        "example.com",
+        22,
+        options.with_private_key("user", "/path/to/private/key"),
+        options.with_request_timeout(30),
+        options.with_logger(logger),
+    )
+
+    # Run a command
+    result = await client.execute(["ls", "-la"])
+    print(f"Exit code: {result.exit_code}")
+    print(f"Stdout: {result.stdout}")
+    print(f"Stderr: {result.stderr}")
+
+    # Close the connection
+    await client.aclose()
+
+
+# Run the asynchronous function
+asyncio.run(main())
+```
+
+## Configuration
+
+Configure the client using `ClientOption` options. Built-in options are in the `options` module.
+
+By default, both clients verify server keys against the standard `~/.ssh/known_hosts` file.
+Unknown or changed keys are rejected. To use a separate file, set
+`options.with_known_hosts("/path/to/known_hosts")`; the file must contain a previously verified server key.
+
+### Available options
+
+* `with_request_timeout`: set the SSH request timeout
+* `with_connection_timeout`: set the SSH connection timeout
+* `with_password`: set the username and password for authentication
+* `with_private_key`: set the username and private key path for authentication
+* `with_known_hosts`: choose a trusted server keys file
+* `with_logger`: set a logger for SSH requests and responses
+* `with_structlogger`: set a structured logger for SSH requests and responses (requires the structlog extra)
+* `retry_if_connection_fails`: retry failed connections
+* `retry_if_command_fails`: retry failed commands
+* `with_connect_decorators`: add custom decorators to the connection method
+* `with_execute_decorators`: add custom decorators to the command execution method
+* `with_live_execute_callback`: add callbacks to process stdout and stderr lines in real time
+
+### Using with_live_execute_callback
+
+```python
+import logging
+from ssh_client import SyncSSHClient, options
+
+
+# Define callbacks for live output
+def stdout_callback(line):
+    print(f"STDOUT: {line}")
+
+
+def stderr_callback(line):
+    print(f"STDERR: {line}")
+
+
+# Create a client with callbacks
+client = SyncSSHClient(
+    "example.com",
+    22,
+    options.with_password("user", "password"),
+    options.with_live_execute_callback(stdout_callback, stderr_callback),
+)
+
+# Run a command with live output
+result = client.execute_live(["ping", "-c", "3", "google.com"])
+
+# Callbacks print all lines in real time
+print(f"Exit code: {result.exit_code}")
+
+# Close the connection
+client.close()
+```
+
+### Interrupting commands with callbacks
+
+Interrupt a command when a condition is met. This is useful for long-running commands that should stop when particular text appears in the output.
+
+#### Interrupting on stdout (synchronous client)
+
+```python
+import logging
+from ssh_client import SyncSSHClient, options
+
+
+# Define a conditional interrupt callback
+def interrupt_on_keyword(line):
+    """Interrupt execution if the line contains 'ERROR'."""
+    print(f"Processing line: {line}")
+    return "ERROR" in line
+
+
+# Create a client
+client = SyncSSHClient(
+    "example.com",
+    22,
+    options.with_password("user", "password"),
+)
+
+try:
+    # Run a command with conditional interruption
+    result = client.execute_live(
+        ["tail", "-f", "/var/log/application.log"], interrupt_stdout_callback=interrupt_on_keyword
+    )
+
+    print(f"Command was interrupted with exit code: {result.exit_code}")
+    print("Captured output:")
+    for line in result.stdout_lines:
+        print(f"  {line}")
+finally:
+    client.close()
+```
+
+#### Interrupting on stderr (asynchronous client)
+
+```python
+import asyncio
+from ssh_client import AsyncSSHClient, options
+
+
+async def main():
+    # Define a stderr interrupt callback
+    def interrupt_on_error(line):
+        """Interrupt execution if stderr contains a critical error."""
+        print(f"Error detected: {line}")
+        return "CRITICAL" in line or "FATAL" in line
+
+    # Create a client
+    client = AsyncSSHClient(
+        "example.com",
+        22,
+        options.with_private_key("user", "/path/to/private/key"),
+    )
+
+    try:
+        # Run a command with stderr interruption
+        result = await client.execute_live(["some-long-running-command"], interrupt_stderr_callback=interrupt_on_error)
+
+        print(f"Command was interrupted with exit code: {result.exit_code}")
+        print("Captured stderr:")
+        for line in result.stderr_lines:
+            print(f"  {line}")
+    finally:
+        await client.aclose()
+
+
+# Run the asynchronous function
+asyncio.run(main())
+```
+
+Synchronous `execute_live` merges stdout and stderr through a terminal. Separate stderr callbacks are available on the asynchronous client.
+
+When an interrupt callback fires, the command stops and `execute_live` returns a result with a negative exit code (-1 for the synchronous client, -2 for the asynchronous client), including all lines received before the interruption.
+
+## Advanced features
+
+### Temporary options with with_options
+
+Use `with_options` to create temporary clients with additional options for a single command:
+
+```python
+import logging
+from ssh_client import SyncSSHClient, options
+
+# Create the base client
+client = SyncSSHClient(
+    "example.com",
+    22,
+    options.with_password("user", "password"),
+    options.with_request_timeout(30),
+    options.with_logger(logging.getLogger(__name__)),
+)
+
+# Use with_options for a command with custom settings
+result = client.with_options(
+    options.with_request_timeout(60),  # Longer timeout for this command only
+    options.retry_if_command_fails(
+        retries_attempts_number=3, retries_interval_in_seconds=1
+    ),  # Retries for this command only
+).execute(["sleep", "10", "&&", "echo", "Done"])
+
+# The base client stays unchanged
+client.close()
+```
+
+### Structured logging
+
+Install the `structlog` extra to use structured logging:
+
+```shell
+pip install "cloudru-qa-ssh-client[structlog]"
+```
+
+Structured logging example:
+
+```python
+import structlog
+from ssh_client import SyncSSHClient, options
+
+# Configure structlog
+structlog.configure(
+    processors=[structlog.processors.TimeStamper(fmt="iso"), structlog.processors.JSONRenderer()],
+    context_class=dict,
+    logger_factory=structlog.PrintLoggerFactory(),
+)
+
+# Create a client with a structured logger
+client = SyncSSHClient(
+    "example.com",
+    22,
+    options.with_password("user", "password"),
+    options.with_structlogger(structlog.get_logger()),
+)
+
+# Run a command with structured logging
+result = client.execute(["ls", "-la"])
+print(f"Exit code: {result.exit_code}")
+
+# Close the connection
+client.close()
+```
+
+### Retries
+
+Configure retries for both connections and command execution:
+
+```python
+from ssh_client import SyncSSHClient, options
+
+client = SyncSSHClient(
+    "unstable-server.com",
+    22,
+    options.with_password("user", "password"),
+    # Connection retries
+    options.retry_if_connection_fails(
+        retries_attempts_number=5, retries_interval_in_seconds=10.0, reraise_exception=True
+    ),
+    # Command retries
+    options.retry_if_command_fails(retries_attempts_number=3, retries_interval_in_seconds=5.0, reraise_exception=True),
+)
+
+# Run a command with retries
+result = client.execute(["some-unstable-command"])
+
+# Close the connection
+client.close()
+```
+
+### Masking log data
+
+Mask confidential data in logs:
+
+```python
+import logging
+import re
+from ssh_client import SyncSSHClient, options
+
+# Configure a logger
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+client = SyncSSHClient(
+    "example.com",
+    22,
+    options.with_password("user", "password"),
+    # Mask confidential log data
+    options.with_logger(
+        logger,
+        mask_patterns=[
+            "password",  # String to replace
+            "secret",  # Another string to replace
+            re.compile(r"token=\w+"),  # Regular expression
+        ],
+    ),
+)
+
+# Run a command with confidential data
+# The data is masked in logs
+result = client.execute(["echo", "password=secret123", "token=abc123def456"])
+
+# Close the connection
+client.close()
+```
+
+### Custom decorators
+
+Add custom decorators to connection and command execution methods:
+
+```python
+import time
+from functools import wraps
+from ssh_client import SyncSSHClient, options
+
+
+# Decorator to measure execution time
+def timing_decorator(func):
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        start_time = time.time()
+        result = func(*args, **kwargs)
+        end_time = time.time()
+        print(f"{func.__name__} took {end_time - start_time:.2f} seconds")
+        return result
+
+    return wrapper
+
+
+# Decorator to handle errors
+def error_handler_decorator(func):
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except Exception as e:
+            print(f"Error in {func.__name__}: {e}")
+            # Retry or take another action here
+            raise
+
+    return wrapper
+
+
+client = SyncSSHClient(
+    "example.com",
+    22,
+    options.with_password("user", "password"),
+    # Add connection decorators
+    options.with_connect_decorators(timing_decorator, error_handler_decorator),
+    # Add command execution decorators
+    options.with_execute_decorators(timing_decorator),
+)
+
+# Run a command with decorators
+result = client.execute(["ls", "-la"])
+
+# Close the connection
+client.close()
+```
+
+## Development
+
+This library is developed in the [qa-libraries](https://github.com/cloud-ru-tech/qa-libraries) monorepo
+alongside the other `cloudru-qa-*` libraries. You need [`uv`](https://docs.astral.sh/uv/), GNU Make
+and [`checkmake`](https://github.com/checkmake/checkmake);
+run the commands from the repository root:
+
+```shell
+make sync                   # dependencies for all libraries from uv.lock
+make test-ssh-client        # tests for this library
+make typecheck-ssh-client   # mypy for this library
+make check                  # formatting, Ruff, mypy, and tests for the whole suite
+```
+
+Tests require Docker to be running: the SSH server starts in a container automatically. Server
+and client keys are generated for each run and are not stored in the repository.
+
+Tests run on Python 3.13 and 3.14. Each version uses a separate environment:
+`make sync test-ssh-client PYTHON_VERSION=3.14`.
+
+Create a release with the Git tag `ssh-client/v<version>`. The tag version must match the version
+in `packages/ssh-client/pyproject.toml`.
+
+## License
+
+[Apache-2.0](https://github.com/cloud-ru-tech/qa-libraries/blob/master/LICENSE)

cloudru_qa_ssh_client-1.0.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+ssh_client/__init__.py,sha256=USdulJKVyGRgxgQaltU_gVISv9ZxGzAGOX6IhGsXLfQ,473
+ssh_client/client.py,sha256=pkvpU-tMipDl0dEU8ICI8i_c15IXmKiVxkis0-0maQk,11419
+ssh_client/config.py,sha256=lKz-nVMTV8-Xxd2N7yk3I3RYztnFRNtVqACe36JmGR4,1113
+ssh_client/event_hooks.py,sha256=voDafOJXYtfH6oi2HqIFXcFv2XyP6SzrAlSEq-jIFIE,3601
+ssh_client/options.py,sha256=m-Sb-cEprz8sG82rX7RjH_ls78YSFK12nPc18JEmW5k,6080
+ssh_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ssh_client/results.py,sha256=UL8_7w5M9XXhswvEF4TSbzVdA27PHzIExnX5jj3Uh18,896
+ssh_client/types.py,sha256=CllecsyNY91UJb2bV8L8fnOMTNPoT_fH6dWLTeUns9k,2204
+ssh_client/clients/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ssh_client/clients/asyncssh_client.py,sha256=dYdNaJeXNCqR-OqsKqHnTdgCGHRrbI9JZsZ_ZDttbBs,6705
+ssh_client/clients/exceptions.py,sha256=-iohyrEYqjcAwMd2KTRXMJXGZolliZYxa7v5RstYPzM,1035
+ssh_client/clients/paramiko_client.py,sha256=CfzW27U_0HYHN6ASaAimTOfn9NkiiCUqqGU1jHg_IKM,7927
+ssh_client/examples/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ssh_client/examples/basic_usage.py,sha256=AxRTnTN4EpqTzleyy_mz_eXiT_XKINfyC7gzQ6GYOdM,3076
+ssh_client/utils/__init__.py,sha256=ERR092hr_in0zmtazHQQQjl279nlZoaNMbujw8Y-0YI,259
+ssh_client/utils/masking.py,sha256=oacicWLdAObiSLUW61M38K9iF9_1q3nEYAbu3pD7k6k,1455
+ssh_client/utils/retries.py,sha256=sjJWCVXQM7zTzNQe2ktB8bYVAjXDUbzrrLfnv93y5o4,6237
+cloudru_qa_ssh_client-1.0.0.dist-info/METADATA,sha256=vpc5Kjs8nwiE5AO2vpKQ3z3b_3wk84KET_IXJjldTEQ,14166
+cloudru_qa_ssh_client-1.0.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+cloudru_qa_ssh_client-1.0.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+cloudru_qa_ssh_client-1.0.0.dist-info/RECORD,,

cloudru_qa_ssh_client-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any