mm-std 0.5.4__tar.gz → 0.6.0__tar.gz

{mm_std-0.5.4 → mm_std-0.6.0}/PKG-INFO

@@ -1,4 +1,4 @@
 Metadata-Version: 2.4
 Name: mm-std
-Version: 0.5.4
+Version: 0.6.0
 Requires-Python: >=3.13

{mm_std-0.5.4 → mm_std-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mm-std"
-version = "0.5.4"
+version = "0.6.0"
 description = ""
 requires-python = ">=3.13"
 dependencies = [
@@ -12,12 +12,12 @@ build-backend = "hatchling.build"
 
 [dependency-groups]
 dev = [
-    "pytest~=8.4.2",
+    "pytest~=9.0.2",
     "pytest-xdist~=3.8.0",
-    "ruff~=0.14.0",
-    "mypy~=1.18.2",
-    "bandit~=1.8.6",
-    "pre-commit~=4.3.0",
+    "ruff~=0.14.10",
+    "mypy~=1.19.1",
+    "bandit~=1.9.2",
+    "pre-commit~=4.5.1",
 ]
 
 [tool.mypy]

{mm_std-0.5.4 → mm_std-0.6.0}/src/mm_std/__init__.py

@@ -3,19 +3,19 @@ from .dict_utils import replace_empty_dict_entries
 from .json_utils import ExtendedJSONEncoder, json_dumps
 from .random_utils import random_datetime, random_decimal
 from .str_utils import parse_lines, str_contains_any, str_ends_with_any, str_starts_with_any
-from .subprocess_utils import ShellResult, shell, ssh_shell  # nosec
+from .subprocess_utils import CmdResult, run_cmd, run_ssh_cmd  # nosec
 
 __all__ = [
+    "CmdResult",
     "ExtendedJSONEncoder",
-    "ShellResult",
     "json_dumps",
     "parse_date",
     "parse_lines",
     "random_datetime",
     "random_decimal",
     "replace_empty_dict_entries",
-    "shell",
-    "ssh_shell",
+    "run_cmd",
+    "run_ssh_cmd",
     "str_contains_any",
     "str_ends_with_any",
     "str_starts_with_any",

{mm_std-0.5.4 → mm_std-0.6.0}/src/mm_std/json_utils.py

@@ -49,17 +49,17 @@ class ExtendedJSONEncoder(json.JSONEncoder):
             raise ValueError(f"Cannot override built-in JSON type: {type_.__name__}")
         cls._type_handlers[type_] = serializer
 
-    def default(self, obj: Any) -> Any:  # noqa: ANN401
+    def default(self, o: Any) -> Any:  # noqa: ANN401
         # Check registered type handlers first
         for type_, handler in self._type_handlers.items():
-            if isinstance(obj, type_):
-                return handler(obj)
+            if isinstance(o, type_):
+                return handler(o)
 
         # Special case: dataclasses (requires is_dataclass check, not isinstance)
-        if is_dataclass(obj) and not isinstance(obj, type):
-            return asdict(obj)  # Don't need recursive serialization
+        if is_dataclass(o) and not isinstance(o, type):
+            return asdict(o)  # Don't need recursive serialization
 
-        return super().default(obj)
+        return super().default(o)
 
 
 def json_dumps(data: Any, type_handlers: dict[type[Any], Callable[[Any], Any]] | None = None, **kwargs: Any) -> str:  # noqa: ANN401

mm_std-0.6.0/src/mm_std/subprocess_utils.py

@@ -0,0 +1,96 @@
+import shlex
+import subprocess  # nosec
+from dataclasses import dataclass
+
+TIMEOUT_EXIT_CODE = 255
+
+
+@dataclass
+class CmdResult:
+    """Result of command execution."""
+
+    stdout: str
+    stderr: str
+    code: int
+
+    @property
+    def combined_output(self) -> str:
+        """Combined stdout and stderr output."""
+        result = ""
+        if self.stdout:
+            result += self.stdout
+        if self.stderr:
+            if result:
+                result += "\n"
+            result += self.stderr
+        return result
+
+
+def run_cmd(
+    cmd: str,
+    timeout: int | None = 60,
+    capture_output: bool = True,
+    echo_command: bool = False,
+    shell: bool = False,
+) -> CmdResult:
+    """Execute a command.
+
+    Args:
+        cmd: Command to execute
+        timeout: Timeout in seconds, None for no timeout
+        capture_output: Whether to capture stdout/stderr
+        echo_command: Whether to print the command before execution
+        shell: If False (default), the command is parsed with shlex.split() and
+            executed without shell interpretation. Special characters like
+            backticks, $(), pipes (|), redirects (>, <), and wildcards (*) are
+            treated as literal text. This is the safe mode for commands with
+            user input.
+            If True, the command is passed to the shell as-is, enabling pipes,
+            redirects, command substitution, and other shell features. Use this
+            only for trusted commands that need shell functionality.
+
+    Returns:
+        CmdResult with stdout, stderr and exit code
+    """
+    if echo_command:
+        print(cmd)  # noqa: T201
+    try:
+        if shell:
+            process = subprocess.run(  # noqa: S602 # nosec
+                cmd, timeout=timeout, capture_output=capture_output, shell=True, check=False
+            )
+        else:
+            process = subprocess.run(  # noqa: S603 # nosec
+                shlex.split(cmd), timeout=timeout, capture_output=capture_output, shell=False, check=False
+            )
+        stdout = process.stdout.decode("utf-8", errors="replace") if capture_output else ""
+        stderr = process.stderr.decode("utf-8", errors="replace") if capture_output else ""
+        return CmdResult(stdout=stdout, stderr=stderr, code=process.returncode)
+    except subprocess.TimeoutExpired:
+        return CmdResult(stdout="", stderr="timeout", code=TIMEOUT_EXIT_CODE)
+
+
+def run_ssh_cmd(
+    host: str,
+    cmd: str,
+    ssh_key_path: str | None = None,
+    timeout: int = 60,
+    echo_command: bool = False,
+) -> CmdResult:
+    """Execute a command on remote host via SSH.
+
+    Args:
+        host: Remote host to connect to
+        cmd: Command to execute on remote host
+        ssh_key_path: Path to SSH private key file
+        timeout: Timeout in seconds
+        echo_command: Whether to print the command before execution
+
+    Returns:
+        CmdResult with stdout, stderr and exit code
+    """
+    ssh_cmd = "ssh -o 'StrictHostKeyChecking=no' -o 'LogLevel=ERROR'"
+    if ssh_key_path:
+        ssh_cmd += f" -i {shlex.quote(ssh_key_path)}"
+    ssh_cmd += f" {shlex.quote(host)} {shlex.quote(cmd)}"
+    return run_cmd(ssh_cmd, timeout=timeout, echo_command=echo_command)

{mm_std-0.5.4 → mm_std-0.6.0}/tests/test_subprocess_utils.py

@@ -1,75 +1,75 @@
 import os
 
-from mm_std import ShellResult, shell, ssh_shell
+from mm_std import CmdResult, run_cmd, run_ssh_cmd
 from mm_std.subprocess_utils import TIMEOUT_EXIT_CODE
 
 
-class TestShellResult:
+class TestCmdResult:
     def test_combined_output_with_both_stdout_and_stderr(self):
         """Test combined output when both stdout and stderr are present."""
-        result = ShellResult(stdout="output", stderr="error", code=0)
+        result = CmdResult(stdout="output", stderr="error", code=0)
         assert result.combined_output == "output\nerror"
 
     def test_combined_output_with_only_stdout(self):
         """Test combined output when only stdout is present."""
-        result = ShellResult(stdout="output", stderr="", code=0)
+        result = CmdResult(stdout="output", stderr="", code=0)
         assert result.combined_output == "output"
 
     def test_combined_output_with_only_stderr(self):
         """Test combined output when only stderr is present."""
-        result = ShellResult(stdout="", stderr="error", code=1)
+        result = CmdResult(stdout="", stderr="error", code=1)
         assert result.combined_output == "error"
 
     def test_combined_output_with_neither(self):
         """Test combined output when both stdout and stderr are empty."""
-        result = ShellResult(stdout="", stderr="", code=0)
+        result = CmdResult(stdout="", stderr="", code=0)
         assert result.combined_output == ""
 
 
-class TestShell:
+class TestRunCmd:
     def test_successful_command(self):
         """Test execution of a successful command."""
-        result = shell("echo 'hello world'")
+        result = run_cmd("echo 'hello world'")
         assert result.code == 0
         assert result.stdout.strip() == "hello world"
         assert result.stderr == ""
 
     def test_command_with_exit_code(self):
         """Test command that returns non-zero exit code."""
-        result = shell("exit 42")
+        result = run_cmd("exit 42", shell=True)
         assert result.code == 42
         assert result.stdout == ""
 
     def test_command_with_stderr(self):
         """Test command that outputs to stderr."""
-        result = shell("echo 'error message' >&2")
+        result = run_cmd("echo 'error message' >&2", shell=True)
         assert result.code == 0
         assert result.stdout == ""
         assert result.stderr.strip() == "error message"
 
     def test_capture_output_false(self):
         """Test command execution without capturing output."""
-        result = shell("echo 'test'", capture_output=False)
+        result = run_cmd("echo 'test'", capture_output=False)
         assert result.code == 0
         assert result.stdout == ""
         assert result.stderr == ""
 
     def test_timeout_handling(self):
         """Test command timeout handling."""
-        result = shell("sleep 2", timeout=1)
+        result = run_cmd("sleep 2", timeout=1)
         assert result.code == TIMEOUT_EXIT_CODE
         assert result.stdout == ""
         assert result.stderr == "timeout"
 
     def test_echo_command(self, capsys):
         """Test echo_command parameter prints the command."""
-        shell("echo 'test'", echo_command=True)
+        run_cmd("echo 'test'", echo_command=True)
         captured = capsys.readouterr()
         assert "echo 'test'" in captured.out
 
     def test_command_with_pipes(self):
-        """Test command with pipes and complex shell operations."""
-        result = shell("echo 'line1\nline2\nline3' | grep 'line2'")
+        """Test command with pipes requires shell=True."""
+        result = run_cmd("echo 'line1\nline2\nline3' | grep 'line2'", shell=True)
         assert result.code == 0
         assert result.stdout.strip() == "line2"
 
@@ -78,51 +78,55 @@ class TestShell:
         test_file = tmp_path / "test.txt"
         test_file.write_text("test content")
 
-        result = shell(f"cat {test_file}")
+        result = run_cmd(f"cat {test_file}")
         assert result.code == 0
         assert result.stdout.strip() == "test content"
 
     def test_environment_variables(self):
-        """Test command that uses environment variables."""
-        result = shell("echo $HOME")
+        """Test command that uses environment variables requires shell=True."""
+        result = run_cmd("echo $HOME", shell=True)
         assert result.code == 0
         assert result.stdout.strip() == os.environ.get("HOME", "")
 
+    def test_safe_mode_backticks_literal(self):
+        """Test that backticks are treated as literal text in safe mode."""
+        result = run_cmd("echo 'hello `world`'")
+        assert result.code == 0
+        assert "`world`" in result.stdout
+
+    def test_safe_mode_dollar_literal(self):
+        """Test that $() is treated as literal text in safe mode."""
+        result = run_cmd("echo 'hello $(whoami)'")
+        assert result.code == 0
+        assert "$(whoami)" in result.stdout
 
-class TestSshShell:
+
+class TestRunSshCmd:
     def test_ssh_command_construction(self):
         """Test that SSH command is properly constructed and quoted."""
-        # We can't test actual SSH without a server, but we can test the command construction
-        # by checking what command gets passed to the shell function
-        result = ssh_shell("nonexistent-host", "echo 'test'", timeout=1)
+        result = run_ssh_cmd("nonexistent-host", "echo 'test'", timeout=1)
 
-        # This will fail with connection error, but that's expected
-        # We're testing that the function doesn't crash on command construction
-        assert result.code != 0  # Should fail to connect
+        assert result.code != 0
         assert "timeout" in result.stderr or "connect" in result.stderr.lower() or "resolve" in result.stderr.lower()
 
     def test_ssh_with_key_path(self):
         """Test SSH command with key path parameter."""
-        result = ssh_shell("nonexistent-host", "echo 'test'", ssh_key_path="/path/to/key", timeout=1)
+        result = run_ssh_cmd("nonexistent-host", "echo 'test'", ssh_key_path="/path/to/key", timeout=1)
 
-        # Should fail to connect but not crash
         assert result.code != 0
         assert "timeout" in result.stderr or "connect" in result.stderr.lower() or "resolve" in result.stderr.lower()
 
     def test_ssh_echo_command(self, capsys):
         """Test that SSH command echoing works."""
-        ssh_shell("nonexistent-host", "echo 'test'", echo_command=True, timeout=1)
+        run_ssh_cmd("nonexistent-host", "echo 'test'", echo_command=True, timeout=1)
         captured = capsys.readouterr()
 
-        # Should see the constructed SSH command
         assert "ssh" in captured.out
         assert "nonexistent-host" in captured.out
 
     def test_ssh_command_quoting(self):
         """Test that SSH commands with special characters are properly quoted."""
-        # Test with command that has special characters
-        result = ssh_shell("nonexistent-host", "echo 'hello; rm -rf /'", timeout=1)
+        result = run_ssh_cmd("nonexistent-host", "echo 'hello; echo world'", timeout=1)
 
-        # Should fail to connect but not execute dangerous commands locally
         assert result.code != 0
         assert "timeout" in result.stderr or "connect" in result.stderr.lower() or "resolve" in result.stderr.lower()