Normalize docstrings for better documentation generation

Author: penguinolog

exec_helpers/__init__.py

@@ -87,8 +87,8 @@
 def __getattr__(name: str) -> typing.Any:
     """Get attributes lazy.
 
-    :return: attribute by name
-    :raises AttributeError: attribute is not defined for lazy load
+    :return: Attribute by name.
+    :raises AttributeError: Attribute is not defined for the lazy load.
     """
     if name in _deprecated:
         warnings.warn(

exec_helpers/_helpers.py

@@ -12,10 +12,10 @@
 
 
 def string_bytes_bytearray_as_bytes(src: str | bytes | bytearray) -> bytes:
-    """Get bytes string from string/bytes/bytearray union.
+    """Get byte string from string/bytes/bytearray union.
 
-    :param src: source string or bytes-like object
-    :return: Byte string
+    :param src: Source string or bytes-like object.
+    :return: Byte string.
     :rtype: bytes
     :raises TypeError: unexpected source type.
     """
@@ -31,11 +31,11 @@ def string_bytes_bytearray_as_bytes(src: str | bytes | bytearray) -> bytes:
 def _mask_command(text: str, rules: str | re.Pattern[str]) -> str:
     """Mask part of text using rules.
 
-    :param text: source text
+    :param text: Source text.
     :type text: str
-    :param rules: regex rules to mask.
+    :param rules: Regex rules to mask.
     :type rules: str | re.Pattern
-    :return: source with all MATCHED groups replaced by '<*masked*>'
+    :return: Source with all MATCHED groups replaced by '<*masked*>'.
     :rtype: str
     """
     masked: list[str] = []
@@ -55,11 +55,11 @@ def _mask_command(text: str, rules: str | re.Pattern[str]) -> str:
 def mask_command(text: str, *rules: str | re.Pattern[str] | None) -> str:
     """Apply all rules to command.
 
-    :param text: source text
+    :param text: Source text.
     :type text: str
-    :param rules: regex rules to mask.
+    :param rules: Regex rules to mask.
     :type rules: str | re.Pattern[str] | None
-    :return: source with all MATCHED groups replaced by '<*masked*>'
+    :return: Source with all MATCHED groups replaced by '<*masked*>'.
     :rtype: str
     """
     return functools.reduce(_mask_command, (rule for rule in rules if rule is not None), text)
@@ -68,9 +68,9 @@ def mask_command(text: str, *rules: str | re.Pattern[str] | None) -> str:
 def cmd_to_string(command: str | Iterable[str]) -> str:
     """Convert command to string for usage with shell.
 
-    :param command: original command.
+    :param command: Original command.
     :type command: str | Iterable[str]
-    :return: command as single string
+    :return: Command as single string.
     :rtype: str
     """
     if isinstance(command, str):
@@ -81,13 +81,13 @@ def cmd_to_string(command: str | Iterable[str]) -> str:
 def chroot_command(command: str, chroot_path: str | None = None, chroot_exe: str = "chroot") -> str:
     """Prepare command for chroot execution.
 
-    :param command: original command.
+    :param command: Original command.
     :type command: str
-    :param chroot_path: chroot path
+    :param chroot_path: chroot path.
     :type chroot_path: str | None
-    :param chroot_exe: chroot executable
+    :param chroot_exe: chroot executable.
     :type chroot_exe: str
-    :return: command to be executed with chroot rules if applicable
+    :return: Command to be executed with chroot rules if applicable.
     :rtype: str
     """
     if chroot_path and chroot_path != "/":

exec_helpers/_ssh_base.py

@@ -27,9 +27,9 @@
 def _parse_ssh_config_file(file_path: pathlib.Path) -> paramiko.SSHConfig | None:
     """Parse ssh config file.
 
-    :param file_path: file path for parsing
+    :param file_path: File path for parsing.
     :type file_path: pathlib.Path
-    :return: SSH config if file found and parsed else None
+    :return: SSH config if file found and parsed else None.
     :rtype: paramiko.SSHConfig | None
     """
     if not file_path.exists():
@@ -73,21 +73,21 @@ def __init__(
     ):
         """SSH Config for creation connection.
 
-        :param hostname: hostname, which config relates
+        :param hostname: Hostname, which config relates.
         :type hostname: str
-        :param port: remote port
+        :param port: Remote port.
         :type port: str | int | None
-        :param user: remote user
+        :param user: Remote user.
         :type user: str | None
-        :param identityfile: connection ssh keys file names
+        :param identityfile: Connection ssh keys file names.
         :type identityfile: Collection[str] | None
-        :param proxycommand: proxy command for ssh connection
+        :param proxycommand: Proxy command for ssh connection.
         :type proxycommand: str | None
+        :param proxyjump: Proxy host name.
         :type proxyjump: str | None
-        :param proxyjump: proxy host name
-        :param controlpath: shared socket file path for re-using connection by multiple instances
+        :param controlpath: Shared socket file path for re-using connection by multiple instances.
         :type controlpath: str | None
-        :param controlmaster: re-use connection
+        :param controlmaster: Re-use connection.
         :type controlmaster: str | bool | None
         :raises ValueError: Invalid argument provided.
 
@@ -114,7 +114,7 @@ def __init__(
     def __hash__(self) -> int:  # pragma: no cover
         """Hash for caching possibility.
 
-        :return: hash for instance
+        :return: hash for instance.
         :rtype: int
         """
         return hash(
@@ -134,7 +134,7 @@ def __hash__(self) -> int:  # pragma: no cover
     def __repr__(self) -> str:
         """Debug support.
 
-        :return: string representation allowing to re-construct object
+        :return: String representation allowing to re-construct an object.
         :rtype: str
         """
         return (
@@ -158,13 +158,13 @@ def __pretty_repr__(
     ) -> str:
         """Make human-readable representation of object.
 
-        :param log_wrap: logwrap instance
+        :param log_wrap: Logwrap instance.
         :type log_wrap: logwrap.PrettyRepr
-        :param indent: start indentation
+        :param indent: Start indentation.
         :type indent: int
-        :param no_indent_start: do not indent open bracket and simple parameters
+        :param no_indent_start: Do not indent open bracket and simple parameters.
         :type no_indent_start: bool
-        :return: formatted string
+        :return: Formatted string.
         :rtype: str
         """
         next_indent = log_wrap.next_indent(indent)
@@ -186,9 +186,9 @@ def __pretty_repr__(
     def _parse_optional_int(value: str | int | None) -> int | None:
         """Parse optional integer field in source data.
 
-        :param value: value to process
+        :param value: Value to process.
         :type value: str | int | None
-        :return: integer value if applicable
+        :return: Integer value if applicable.
         :rtype: int | None
         """
         if value is None or isinstance(value, int):
@@ -199,9 +199,9 @@ def _parse_optional_int(value: str | int | None) -> int | None:
     def _parse_optional_bool(value: str | bool | None) -> bool | None:
         """Parse optional bool field in source data.
 
-        :param value: value to process
+        :param value: Value to process.
         :type value: str | bool | None
-        :return: boolean value if applicable
+        :return: Boolean value if applicable.
         :rtype: bool | None
         """
         if value is None or isinstance(value, bool):
@@ -215,9 +215,9 @@ def from_ssh_config(
     ) -> SSHConfig:
         """Construct config from Paramiko parsed file.
 
-        :param ssh_config: paramiko parsed ssh config or it reconstruction as a dict
+        :param ssh_config: Paramiko parsed ssh config or it reconstruction as a dict.
         :type ssh_config: paramiko.config.SSHConfigDict | dict[str, str | int | bool | list[str]]
-        :return: SSHConfig with supported values from config
+        :return: SSHConfig with supported values from config.
         :rtype: SSHConfig
         """
         return cls(
@@ -235,7 +235,7 @@ def from_ssh_config(
     def as_dict(self) -> SSHConfigDictLikeT:
         """Dictionary for rebuilding config.
 
-        :return: config as dictionary with only not None values
+        :return: Config as dictionary with only not None values.
         :rtype: dict[str, str | int | bool | list[str]]
         """
         result: SSHConfigDictLikeT = {"hostname": self.hostname}
@@ -258,9 +258,9 @@ def as_dict(self) -> SSHConfigDictLikeT:
     def overridden_by(self, ssh_config: SSHConfig) -> SSHConfig:
         """Get copy with values overridden by another config.
 
-        :param ssh_config: Other ssh config
+        :param ssh_config: Other ssh config.
         :type ssh_config: SSHConfig
-        :return: Composite from 2 configs with priority of second one
+        :return: Composite from two configs with priority of second one.
         :rtype: SSHConfig
         """
         cls: type[SSHConfig] = self.__class__
@@ -281,7 +281,7 @@ def __eq__(
     ) -> bool | type(NotImplemented):  # type: ignore[valid-type]
         """Equality check.
 
-        :return: other equals self
+        :return: Other equals self.
         :rtype: bool
         """
         if isinstance(other, SSHConfig):
@@ -306,7 +306,7 @@ def __eq__(
     def hostname(self) -> str:
         """Hostname which config relates.
 
-        :return: remote hostname
+        :return: Remote hostname.
         :rtype: str
         """
         return self.__hostname
@@ -315,7 +315,7 @@ def hostname(self) -> str:
     def port(self) -> int | None:
         """Remote port.
 
-        :return: propagated remote port for connection
+        :return: Propagated remote port for connection.
         :rtype: int | None
         """
         return self.__port
@@ -324,7 +324,7 @@ def port(self) -> int | None:
     def user(self) -> str | None:
         """Remote user.
 
-        :return: propagated username for connection
+        :return: Propagated username for connection.
         :rtype: str | None
         """
         return self.__user
@@ -333,7 +333,7 @@ def user(self) -> str | None:
     def identityfile(self) -> Collection[str]:
         """Connection ssh keys file names.
 
-        :return: list of ssh private keys names
+        :return: List of ssh private keys names.
         :rtype: Collection[str]
         """
         if self.__identityfile is None:
@@ -346,7 +346,7 @@ def identityfile(self) -> Collection[str]:
     def proxycommand(self) -> str | None:
         """Proxy command for ssh connection.
 
-        :return: command to be executed for socket creation if applicable
+        :return: Command to be executed for socket creation if applicable.
         :rtype: str | None
         """
         return self.__proxycommand
@@ -355,7 +355,7 @@ def proxycommand(self) -> str | None:
     def proxyjump(self) -> str | None:
         """Proxy host name.
 
-        :return: proxy hostname if applicable
+        :return: Proxy hostname if applicable.
         :rtype: str | None
         """
         return self.__proxyjump
@@ -364,7 +364,7 @@ def proxyjump(self) -> str | None:
     def controlpath(self) -> str | None:
         """Shared socket file path for re-using connection by multiple instances.
 
-        :return: shared socket filesystem path
+        :return: Shared socket filesystem path.
         :rtype: str | None
         """
         return self.__controlpath
@@ -373,7 +373,7 @@ def controlpath(self) -> str | None:
     def controlmaster(self) -> bool | None:
         """Re-use connection.
 
-        :return: connection should be re-used if possible
+        :return: Connection should be re-used if possible.
         :rtype: bool | None
         """
         return self.__controlmaster
@@ -382,17 +382,17 @@ def controlmaster(self) -> bool | None:
 class HostsSSHConfigs(typing.Dict[str, SSHConfig]):
     """Specific dictionary for managing SSHConfig records.
 
-    Instead of creating new record by request just generate default value and return if not exists.
+    Instead of creating a new record by request, just generate default value and return if not exists.
     """
 
     def __missing__(self, key: str) -> SSHConfig:
         """Missing key handling.
 
-        :param key: nonexistent key
+        :param key: Nonexistent key.
         :type key: str
-        :return: generated ssh config for host
+        :return: Generated ssh config for host.
         :rtype: SSHConfig
-        :raises KeyError: key is not string
+        :raises KeyError: key is not string.
         .. versionadded:: 6.0.0
         """
         if isinstance(key, str):
@@ -403,11 +403,11 @@ def __missing__(self, key: str) -> SSHConfig:
 def _parse_paramiko_ssh_config(conf: paramiko.SSHConfig, host: str) -> HostsSSHConfigs:
     """Parse Paramiko ssh config for specific host to dictionary.
 
-    :param conf: Paramiko SSHConfig instance
+    :param conf: Paramiko SSHConfig instance.
     :type conf: paramiko.SSHConfig
-    :param host: hostname to seek in config
+    :param host: Hostname to seek in config.
     :type host: str
-    :return: parsed dictionary with proxy jump path, if available
+    :return: Parsed dictionary with a proxy jump path, if available.
     :rtype: HostsSSHConfigs
     """
     config = HostsSSHConfigs({host: SSHConfig.from_ssh_config(conf.lookup(host))})
@@ -424,11 +424,11 @@ def _parse_paramiko_ssh_config(conf: paramiko.SSHConfig, host: str) -> HostsSSHC
 def _parse_dict_ssh_config(conf: SSHConfigsDictT, host: str) -> HostsSSHConfigs:
     """Extract required data from pre-parsed ssh config for specific host to dictionary.
 
-    :param conf: pre-parsed dictionary
+    :param conf: Pre-parsed dictionary.
     :type conf: dict[str, dict[str, str | int | bool | list[str]]]
-    :param host: hostname to seek in config
+    :param host: Hostname to seek in config.
     :type host: str
-    :return: parsed dictionary with proxy jump path, if available
+    :return: Parsed dictionary with a proxy jump path, if available.
     :rtype: HostsSSHConfigs
     """
     config = HostsSSHConfigs({host: SSHConfig.from_ssh_config(conf.get(host, {"hostname": host}))})
@@ -454,9 +454,9 @@ def parse_ssh_config(
         | paramiko.SSHConfig
         | dict[str, dict[str, str | int | bool | list[str]]]
         | None
-    :param host: remote hostname
+    :param host: Remote hostname.
     :type host: str
-    :return: parsed ssh config if available
+    :return: Parsed ssh config if available.
     :rtype: HostsSSHConfigs
     """
     if isinstance(ssh_config, paramiko.SSHConfig):

exec_helpers/_ssh_helpers.py

@@ -39,9 +39,9 @@ def kill_proc_tree(pid: int, including_parent: bool = True) -> None:  # pragma:
     def safe_stop(proc: psutil.Process, kill: bool = False) -> None:
         """Do not crash on already stopped process.
 
-        :param proc: target process
+        :param proc: Target process.
         :type proc: psutil.Process
-        :param kill: use SIGKILL instead of SIGTERM
+        :param kill: Use SIGKILL instead of SIGTERM.
         :type kill: bool
         """
         with contextlib.suppress(psutil.NoSuchProcess):
@@ -52,7 +52,7 @@ def safe_stop(proc: psutil.Process, kill: bool = False) -> None:
     try:
         parent = psutil.Process(pid)
     except psutil.NoSuchProcess:
-        # Process is already closed
+        # The process is already closed
         return
     children: list[psutil.Process] = parent.children(recursive=True)
     child: psutil.Process

exec_helpers/_subprocess_helpers.py

@@ -54,8 +54,8 @@
 def __getattr__(name: str) -> typing.Any:
     """Get attributes lazy.
 
-    :return: attribute by name
-    :raises AttributeError: attribute is not defined for lazy load
+    :return: Attribute by name.
+    :raises AttributeError: Attribute is not defined for the lazy load.
     """
     if name in _deprecated:
         warnings.warn(

exec_helpers/api.py

@@ -44,10 +44,10 @@ async def _poll_stream(  # type: ignore[override]  # pylint: disable=invalid-ove
     ) -> list[bytes]:
         """Stream poll helper.
 
-        :param src: source to read from
-        :param log: logger instance, if line per line logging expected
-        :param verbose: use INFO level for logging
-        :return: read result as list of bytes strings
+        :param src: Source to read from.
+        :param log: Logger instance, if line per-line logging is expected.
+        :param verbose: Use INFO level for logging.
+        :return: Read result as a list of byte strings.
         """
         dst: list[bytes] = []
         with contextlib.suppress(IOError):
@@ -68,13 +68,13 @@ async def read_stdout(  # type: ignore[override]  # pylint: disable=invalid-over
     ) -> None:
         """Read asyncio stdout transport to stdout.
 
-        :param src: source
+        :param src: Source.
         :type src: AsyncIterable[bytes] | None
-        :param log: logger
+        :param log: Logger.
         :type log: logging.Logger | None
-        :param verbose: use log.info instead of log.debug
+        :param verbose: Use log.info instead of log.debug.
         :type verbose: bool
-        :raises RuntimeError: Exit code is already received
+        :raises RuntimeError: Exit code is already received.
 
         .. versionadded:: 3.0.0
         """
@@ -95,13 +95,13 @@ async def read_stderr(  # type: ignore[override]  # pylint: disable=invalid-over
     ) -> None:
         """Read asyncio stderr transport to stdout.
 
-        :param src: source
+        :param src: Source.
         :type src: AsyncIterable[bytes] | None
-        :param log: logger
+        :param log: Logger.
         :type log: logging.Logger | None
-        :param verbose: use log.info instead of log.debug
+        :param verbose: Use log.info instead of log.debug.
         :type verbose: bool
-        :raises RuntimeError: Exit code is already received
+        :raises RuntimeError: Exit code is already received.
 
         .. versionadded:: 3.0.0
         """

exec_helpers/async_api/__init__.py

@@ -59,7 +59,7 @@ class ExecCalledProcessError(ExecHelperError):
 
 
 class ExecHelperTimeoutProcessError(ExecCalledProcessError):
-    """Timeout based errors."""
+    """Timeout-based errors."""
 
     __slots__ = ("result", "timeout")
 
@@ -72,11 +72,11 @@ def __init__(
     ) -> None:
         """Exception for error on process calls.
 
-        :param message: exception message
+        :param message: Exception message.
         :type message: str
-        :param result: execution result
+        :param result: Execution result.
         :type result: exec_result.ExecResult
-        :param timeout: timeout for command
+        :param timeout: Timeout for command.
         :type timeout: int | float
         """
         super().__init__(message)
@@ -87,23 +87,23 @@ def __init__(
     def cmd(self) -> str:
         """Failed command.
 
-        :return: command
+        :return: Command.
         """
         return self.result.cmd
 
     @property
     def stdout(self) -> str:
         """Command stdout.
 
-        :return: command stdout as string
+        :return: Command STDOUT as string.
         """
         return self.result.stdout_str
 
     @property
     def stderr(self) -> str:
         """Command stderr.
 
-        :return: command stderr as string
+        :return: Command STDERR as string.
         """
         return self.result.stderr_str
 
@@ -123,9 +123,9 @@ def __init__(
     ) -> None:
         """Exception for error on process calls.
 
-        :param result: execution result
+        :param result: Execution result.
         :type result: exec_result.ExecResult
-        :param timeout: timeout for command
+        :param timeout: Timeout for command.
         :type timeout: int | float
         """
         message: str = (
@@ -142,8 +142,8 @@ def __init__(
 class ExecHelperTimeoutError(ExecHelperTimeoutProcessError):
     """Execution timeout.
 
-    .. versionchanged:: 1.3.0 provide full result and timeout inside.
-    .. versionchanged:: 1.3.0 subclass ExecCalledProcessError
+    .. versionchanged:: 1.3.0 Provide full result and timeout inside.
+    .. versionchanged:: 1.3.0 Subclass ExecCalledProcessError
     """
 
     __slots__ = ()
@@ -155,9 +155,9 @@ def __init__(
     ) -> None:
         """Exception for error on process calls.
 
-        :param result: execution result
+        :param result: Execution result.
         :type result: exec_result.ExecResult
-        :param timeout: timeout for command
+        :param timeout: Timeout for command.
         :type timeout: int | float
         """
         message: str = _log_templates.CMD_WAIT_ERROR.format(result=result, timeout=timeout)
@@ -176,13 +176,13 @@ def __init__(
     ) -> None:
         """Exception for error on process calls.
 
-        :param result: execution result
+        :param result: Execution result.
         :type result: exec_result.ExecResult
-        :param expected: expected return codes
+        :param expected: Expected return codes.
         :type expected: Iterable[int | proc_enums.ExitCodes]
 
-        .. versionchanged:: 1.1.1 - provide full result
-        .. versionchanged:: 3.4.0 Expected is not optional, defaults os dependent
+        .. versionchanged:: 1.1.1 - provide full result.
+        .. versionchanged:: 3.4.0 Expected is not optional, defaults os dependent.
         """
         self.result: exec_result.ExecResult = result
         self.expected: Sequence[ExitCodeT] = proc_enums.exit_codes_to_enums(expected)
@@ -198,31 +198,31 @@ def __init__(
     def returncode(self) -> ExitCodeT:
         """Command return code.
 
-        :return: command return code
+        :return: Command return code.
         """
         return self.result.exit_code
 
     @property
     def cmd(self) -> str:
         """Failed command.
 
-        :return: command
+        :return: Command.
         """
         return self.result.cmd
 
     @property
     def stdout(self) -> str:
         """Command stdout.
 
-        :return: command stdout as string
+        :return: Command STDOUT as string.
         """
         return self.result.stdout_str
 
     @property
     def stderr(self) -> str:
         """Command stderr.
 
-        :return: command stderr as string
+        :return: Command STDERR as string.
         """
         return self.result.stderr_str
 
@@ -243,15 +243,15 @@ def __init__(
     ) -> None:
         """Exception during parallel execution.
 
-        :param command: command
+        :param command: Command.
         :type command: str
-        :param errors: results with errors
+        :param errors: Results with errors.
         :type errors: dict[tuple[str, int], ExecResult]
-        :param results: all results
+        :param results: All results.
         :type results: dict[tuple[str, int], ExecResult]
-        :param expected: expected return codes
+        :param expected: Expected return codes.
         :type expected: Iterable[int | proc_enums.ExitCodes]
-        :param _message: message override
+        :param _message: Message override.
         :type _message: str | None
 
         .. versionchanged:: 3.4.0 Expected is not optional, defaults os dependent
@@ -288,17 +288,17 @@ def __init__(
     ) -> None:
         """Exception raised during parallel call as result of exceptions.
 
-        :param command: command
+        :param command: Command.
         :type command: str
-        :param exceptions: Exceptions on connections
+        :param exceptions: Exceptions on connections.
         :type exceptions: dict[tuple[str, int], Exception]
-        :param errors: results with errors
+        :param errors: Results with errors.
         :type errors: dict[tuple[str, int], ExecResult]
-        :param results: all results
+        :param results: All results.
         :type results: dict[tuple[str, int], ExecResult]
-        :param expected: expected return codes
+        :param expected: Expected return codes.
         :type expected: Iterable[int | proc_enums.ExitCodes]
-        :param _message: message override
+        :param _message: Message override.
         :type _message: str | None
 
         .. versionchanged:: 3.4.0 Expected is not optional, defaults os dependent

exec_helpers/async_api/api.py

@@ -71,7 +71,7 @@ class SigNum(enum.IntEnum):
     def __str__(self) -> str:
         """Representation for logs.
 
-        :return: string with value in decimal, hex and text information
+        :return: String with value in decimal, hex and text information.
         :rtype: str
         """
         return f"{self.name}<{self.value:d}(0x{self.value:02X})>"  # pragma: no cover
@@ -177,7 +177,7 @@ class ExitCodes(enum.IntEnum):
     def __str__(self) -> str:
         """Representation for logs.
 
-        :return: string with value in decimal, hex and text information
+        :return: String with value in decimal, hex and text information.
         :rtype: str
         """
         return f"{self.name}<{self.value:d}(0x{self.value:02X})>"
@@ -191,8 +191,8 @@ def __str__(self) -> str:
 def exit_code_to_enum(code: ExitCodeT) -> ExitCodeT:  # pragma: no cover
     """Convert exit code to enum if possible.
 
-    :param code: code to convert from
-    :return: enum code if suitable else original code
+    :param code: Code to convert from.
+    :return: Enum code if suitable else original code.
     """
     if sys.platform == "win32":
         return int(code)
@@ -204,8 +204,8 @@ def exit_code_to_enum(code: ExitCodeT) -> ExitCodeT:  # pragma: no cover
 def exit_codes_to_enums(codes: Iterable[ExitCodeT] | None = None) -> Sequence[ExitCodeT]:
     """Convert integer exit codes to enums.
 
-    :param codes: exit codes to process
-    :return: exit codes as enums if suitable
+    :param codes: Exit codes to process.
+    :return: Exit codes as enums if suitable.
     """
     if codes is None:
         # noinspection PyRedundantParentheses

exec_helpers/async_api/exec_result.py

@@ -39,17 +39,17 @@ class SSHClient(_ssh_base.SSHClientBase):
     def _path_esc(path: str) -> str:
         """Escape space character in the path.
 
-        :param path: path to be escaped
+        :param path: Path to be escaped.
         :type path: str
-        :return: path with escaped spaces
+        :return: Path with escaped spaces.
         :rtype: str
         """
         return path.replace(" ", r"\ ")
 
     def mkdir(self, path: SupportPathT) -> None:
         """Run 'mkdir -p path' on remote.
 
-        :param path: path to create
+        :param path: Path to create.
         :type path: str | pathlib.PurePath
         """
         if self.exists(path):
@@ -60,7 +60,7 @@ def mkdir(self, path: SupportPathT) -> None:
     def rm_rf(self, path: SupportPathT) -> None:
         """Run 'rm -rf path' on remote.
 
-        :param path: path to remove
+        :param path: Path to remove.
         :type path: str | pathlib.PurePath
         """
         # noinspection PyTypeChecker
@@ -69,9 +69,9 @@ def rm_rf(self, path: SupportPathT) -> None:
     def upload(self, source: SupportPathT, target: SupportPathT) -> None:
         """Upload file(s) from source to target using SFTP session.
 
-        :param source: local path
+        :param source: Local path.
         :type source: str | pathlib.PurePath
-        :param target: remote path
+        :param target: Remote path.
         :type target: str | pathlib.PurePath
         """
         self.logger.debug(f"Copying '{source}' -> '{target}'")
@@ -101,11 +101,11 @@ def upload(self, source: SupportPathT, target: SupportPathT) -> None:
     def download(self, destination: SupportPathT, target: SupportPathT) -> bool:
         """Download file(s) to target from destination.
 
-        :param destination: remote path
+        :param destination: Remote path.
         :type destination: str | pathlib.PurePath
-        :param target: local path
+        :param target: Local path.
         :type target: str | pathlib.PurePath
-        :return: downloaded file present on local filesystem
+        :return: Downloaded file present on local filesystem.
         :rtype: bool
         """
         self.logger.debug(f"Copying '{destination}' -> '{target}' from remote to local host")

exec_helpers/async_api/subprocess.py

@@ -55,17 +55,17 @@ def __init__(
         Single SSHAuth object is associated with single host:port.
         Password and key is private, other data is read-only.
 
-        :param username: remote username.
+        :param username: Remote username.
         :type username: str | None
-        :param password: remote password
+        :param password: Remote password.
         :type password: str | None
-        :param key: Main connection key
+        :param key: Main connection key.
         :type key: paramiko.PKey | None
-        :param keys: Alternate connection keys
+        :param keys: Alternate connection keys.
         :type keys: Sequence[paramiko.PKey | None] | None
-        :param key_filename: filename(s) for additional key files
+        :param key_filename: Filename(s) for additional key files.
         :type key_filename: Iterable[str] | str | None
-        :param passphrase: passphrase for keys. Need, if differs from password
+        :param passphrase: Passphrase for keys. Need, if differs from password.
         :type passphrase: str | None
 
         .. versionchanged:: 1.0.0
@@ -107,7 +107,7 @@ def __init__(
     def username(self) -> str | None:
         """Username for auth.
 
-        :return: auth username
+        :return: Auth username.
         :rtype: str
         """
         return self.__username
@@ -116,9 +116,9 @@ def username(self) -> str | None:
     def __get_public_key(key: paramiko.PKey | None) -> str | None:
         """Internal method for get public key from private.
 
-        :param key: SSH private key
+        :param key: SSH private key.
         :type key: paramiko.PKey
-        :return: public key text if applicable
+        :return: Public key text if applicable.
         :rtype: str | None
         """
         if key is None:
@@ -127,9 +127,9 @@ def __get_public_key(key: paramiko.PKey | None) -> str | None:
 
     @property
     def public_key(self) -> str | None:
-        """Public key for stored private key if presents else None.
+        """Public key for the stored private key if presents else None.
 
-        :return: public key for current private key
+        :return: Public key for the current private key.
         :rtype: str
         """
         return self.__get_public_key(self.__keys[self.__key_index])
@@ -138,7 +138,7 @@ def public_key(self) -> str | None:
     def key_filename(self) -> Collection[str]:
         """Key filename(s).
 
-        :return: copy of used key filename (original should not be changed via mutability).
+        :return: Copy of used key filename (original should not be changed via mutability).
         .. versionadded:: 1.0.0
         .. versionchanged:: 7.0.5 changed type relying on paramiko sources
         """
@@ -149,7 +149,7 @@ def enter_password(self, tgt: typing.BinaryIO) -> None:
 
         Note: required for 'sudo' call
 
-        :param tgt: Target
+        :param tgt: Target.
         :type tgt: typing.BinaryIO
         """
         # noinspection PyTypeChecker
@@ -165,19 +165,19 @@ def connect(
         sock: paramiko.ProxyCommand | paramiko.Channel | socket.socket | None = None,
         allow_ssh_agent: bool = True,
     ) -> None:
-        """Connect SSH client object using credentials.
+        """Connect the SSH client object using credentials.
 
-        :param client: SSH Client (low level)
+        :param client: SSH Client (low level).
         :type client: paramiko.SSHClient
-        :param hostname: remote hostname
+        :param hostname: Remote hostname.
         :type hostname: str
-        :param port: remote ssh port
+        :param port: Remote ssh port.
         :type port: int
-        :param log: Log on generic connection failure
+        :param log: Log on generic connection failure.
         :type log: bool
-        :param sock: socket for connection. Useful for ssh proxies support
+        :param sock: Socket for connection. Useful for ssh proxies support.
         :type sock: paramiko.ProxyCommand | paramiko.Channel | socket.socket | None
-        :param allow_ssh_agent: use SSH Agent if available
+        :param allow_ssh_agent: Use SSH Agent if available.
         :type allow_ssh_agent: bool
         :raises PasswordRequiredException: No password has been set, but required.
         :raises AuthenticationException: Authentication failed.
@@ -223,7 +223,7 @@ def connect(
     def __hash__(self) -> int:
         """Hash for usage as dict keys and comparison.
 
-        :return: hash value
+        :return: Hash value.
         :rtype: int
         """
         return hash(
@@ -240,29 +240,29 @@ def __hash__(self) -> int:
     def __eq__(self, other: object) -> bool:
         """Comparison helper.
 
-        :param other: other SSHAuth instance
+        :param other: Another SSHAuth instance.
         :type other: typing.Any
-        :return: current object equals other
+        :return: Current object equals other.
         :rtype: bool
         """
         return hash(self) == hash(other)
 
     def __ne__(self, other: object) -> bool:
         """Comparison helper.
 
-        :param other: other SSHAuth instance
+        :param other: Another SSHAuth instance.
         :type other: typing.Any
-        :return: current object not equals other
+        :return: Current object doesn't equal other.
         :rtype: bool
         """
         return not self.__eq__(other)
 
     def __deepcopy__(self, memo: typing.Any) -> SSHAuth:
         """Helper for copy.deepcopy.
 
-        :param memo: copy.deepcopy() memodict
+        :param memo: copy.deepcopy() memodict.
         :type memo: typing.Any
-        :return: re-constructed copy of current class
+        :return: Re-constructed copy of the current class.
         :rtype: SSHAuth
         """
         # noinspection PyTypeChecker
@@ -278,7 +278,7 @@ def __deepcopy__(self, memo: typing.Any) -> SSHAuth:
     def __copy__(self) -> SSHAuth:
         """Copy self.
 
-        :return: re-constructed copy of current class
+        :return: Re-constructed copy of the current class.
         :rtype: SSHAuth
         """
         # noinspection PyTypeChecker
@@ -294,7 +294,7 @@ def __copy__(self) -> SSHAuth:
     def __repr__(self) -> str:
         """Representation for debug purposes.
 
-        :return: partial instance fields in human-friendly format
+        :return: Partial instance fields in human-friendly format.
         :rtype: str
         """
         if self.__keys[self.__key_index] is None:
@@ -322,16 +322,16 @@ def __repr__(self) -> str:
     def __str__(self) -> str:
         """Representation for debug purposes.
 
-        :return: user name related to class instance
+        :return: Username related to class instance.
         :rtype: str
         """
         return f"{self.__class__.__name__} for {self.username}"
 
 
 class SSHAuthMapping(typing.Dict[str, SSHAuth]):
-    """Specific dictionary for  ssh hostname - auth mapping.
+    """Specific dictionary for ssh hostname - auth mapping.
 
-    keys are always string and saved/collected lowercase.
+    Keys are always string and saved/collected lowercase.
     """
 
     __slots__ = ()
@@ -341,13 +341,13 @@ def __init__(
         auth_dict: dict[str, SSHAuth] | SSHAuthMapping | None = None,
         **auth_mapping: SSHAuth,
     ) -> None:
-        """Specific dictionary for  ssh hostname - auth mapping.
+        """Specific dictionary for ssh hostname - auth mapping.
 
-        :param auth_dict: original hostname - source ssh auth mapping (dictionary of SSHAuthMapping)
+        :param auth_dict: Original hostname - source ssh auth mapping (dictionary of SSHAuthMapping).
         :type auth_dict: dict[str, SSHAuth] | SSHAuthMapping | None
-        :param auth_mapping: SSHAuth setting via **kwargs
+        :param auth_mapping: SSHAuth setting via **kwargs.
         :type auth_mapping: SSHAuth
-        :raises TypeError: Incorrect type of auth dict or auth object
+        :raises TypeError: Incorrect type of auth dict or auth object.
         """
         super().__init__()
         if auth_dict is not None:
@@ -366,11 +366,11 @@ def __init__(
     def __setitem__(self, hostname: str, auth: SSHAuth) -> None:
         """Dict-like access.
 
-        :param hostname: key - hostname
+        :param hostname: Key - hostname.
         :type hostname: str
-        :param auth: value - SSHAuth object
+        :param auth: value - SSHAuth object.
         :type auth: SSHAuth
-        :raises TypeError: key is not string or value is not SSHAuth.
+        :raises TypeError: Key is not string or value is not SSHAuth.
         """
         if not isinstance(hostname, str):  # pragma: no cover
             raise TypeError(f"Hostname should be string only! Got: {hostname!r}")
@@ -381,11 +381,11 @@ def __setitem__(self, hostname: str, auth: SSHAuth) -> None:
     def __getitem__(self, hostname: str) -> SSHAuth:
         """Dict-like access.
 
-        :param hostname: key - hostname
+        :param hostname: Key - hostname.
         :type hostname: str
-        :return: associated SSHAuth object
+        :return: Associated SSHAuth object.
         :rtype: SSHAuth
-        :raises TypeError: key is not string.
+        :raises TypeError: Key is not a string.
         """
         if not isinstance(hostname, str):  # pragma: no cover
             raise TypeError(f"Hostname should be string only! Got: {hostname!r}")
@@ -417,17 +417,17 @@ def get_with_alt_hostname(
     ) -> SSHAuth | None:
         """Try to guess hostname with credentials.
 
-        :param hostname: expected target hostname
+        :param hostname: Expected target hostname.
         :type hostname: str
-        :param host_names: alternate host names
+        :param host_names: Alternate host names.
         :type host_names: str
-        :param default: credentials if hostname not found
+        :param default: Credentials if hostname not found.
         :type default: SSHAuth | None
-        :return: guessed credentials
+        :return: Guessed credentials.
         :rtype: SSHAuth | None
-        :raises TypeError: Default SSH Auth object is not SSHAuth
+        :raises TypeError: Default SSH Auth object is not SSHAuth.
 
-        Method used in cases, when 1 host share 2 or more names in config.
+        Method used in cases when 1 host shares two or more names in config.
         """
         if default is not None and not isinstance(default, SSHAuth):  # pragma: no cover
             raise TypeError(f"Default SSH Auth object is not SSHAuth!. (got {default!r})")
@@ -441,9 +441,9 @@ def get_with_alt_hostname(
     def __delitem__(self, hostname: str) -> None:
         """Dict-like access.
 
-        :param hostname: key - hostname
+        :param hostname: Key - hostname.
         :type hostname: str
-        :raises TypeError: key is not string.
+        :raises TypeError: Key is not a string.
         """
         if not isinstance(hostname, str):  # pragma: no cover
             raise TypeError(f"Hostname should be string only! Got: {hostname!r}")