shellsafe 0.3.3__tar.gz → 0.3.5__tar.gz

{shellsafe-0.3.3 → shellsafe-0.3.5}/CHANGELOG.md

@@ -3,6 +3,32 @@
 All notable changes to this project are documented here. Format follows
 Keep a Changelog; versioning follows SemVer.
 
+## [0.3.5] - 2026-09-11
+
+### Fixed
+
+- `capture()` no longer renders template twice
+- `_resolve` always returns `str` (defense-in-depth)
+- Suppression comment check extended to 5 lines back (was 1)
+- AU010 now flags file-level suppressions without reasons
+- Audit scanner follows symlinks
+- Walrus operator (`:=`) tracked by AU003
+
+### Changed
+
+- Shell line length guard (128KB max)
+- Suppression `reason:` is now case-insensitive
+- `_apply_suppression` uses `dataclasses.replace` (internal cleanup)
+- PEP 787 status updated to reflect ongoing deferral
+
+## [0.3.4] - 2026-09-03
+
+### Fixed
+
+- Export `plan()` from public surface (`__init__.py`); was defined in
+  `execute.py` but not listed in `__all__`, causing `ImportError` on
+  `from shellsafe import plan`
+
 ## [0.3.3] - 2026-09-01
 
 ### Added

{shellsafe-0.3.3 → shellsafe-0.3.5}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.5
 Name: shellsafe
-Version: 0.3.3
+Version: 0.3.5
 Summary: Run shell commands safely using Python 3.14 template strings. Values can never turn into commands.
 Project-URL: Homepage, https://github.com/rahulXs/shellsafe
 Project-URL: Repository, https://github.com/rahulXs/shellsafe
 Project-URL: Issues, https://github.com/rahulXs/shellsafe/issues
 Project-URL: Changelog, https://github.com/rahulXs/shellsafe/blob/main/CHANGELOG.md
+Project-URL: Blog, https://rahulxs.github.io/shellsafe/
 Author-email: Rahul Sharma <rahulxsh@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
@@ -48,9 +49,9 @@ subprocess.run(f"git commit -m {message}", shell=True)
 # if message = "fix; rm -rf ~"  ->  two commands run. The second one is bad.
 ```
 
-Python planned to solve this officially (PEP 787), but that PEP was deferred to
-at least Python 3.15. So today there is no standard way to run shell commands
-safely with templates. This package fills that gap.
+Python planned to solve this officially (PEP 787), but that PEP is still deferred.
+It is not in the Python 3.15 release candidates. So today there is no standard
+way to run shell commands safely with templates. This package fills that gap.
 
 ## Install
 
@@ -131,6 +132,19 @@ Filter by severity:
 shellsafe audit src/ --severity warning
 ```
 
+Suppress known-safe findings inline:
+
+```python
+# shellsafe: ignore AU001 reason: tested, value is constant
+os.system(f"echo {safe_value}")
+```
+
+Suppress from the command line:
+
+```bash
+shellsafe audit src/ --ignore AU004
+```
+
 ## Limits
 
 - Shell features (pipes, redirections) work on Linux and macOS only. Windows
@@ -149,6 +163,7 @@ shellsafe audit src/ --severity warning
 ## More
 
 - Source and issues: [github.com/rahulXs/shellsafe](https://github.com/rahulXs/shellsafe)
+- Blog: [rahulxs.github.io/shellsafe](https://rahulxs.github.io/shellsafe/)
 - Want to help? See CONTRIBUTING.md in the repository.
 
 License: MIT

{shellsafe-0.3.3 → shellsafe-0.3.5}/README.md

@@ -25,9 +25,9 @@ subprocess.run(f"git commit -m {message}", shell=True)
 # if message = "fix; rm -rf ~"  ->  two commands run. The second one is bad.
 ```
 
-Python planned to solve this officially (PEP 787), but that PEP was deferred to
-at least Python 3.15. So today there is no standard way to run shell commands
-safely with templates. This package fills that gap.
+Python planned to solve this officially (PEP 787), but that PEP is still deferred.
+It is not in the Python 3.15 release candidates. So today there is no standard
+way to run shell commands safely with templates. This package fills that gap.
 
 ## Install
 
@@ -108,6 +108,19 @@ Filter by severity:
 shellsafe audit src/ --severity warning
 ```
 
+Suppress known-safe findings inline:
+
+```python
+# shellsafe: ignore AU001 reason: tested, value is constant
+os.system(f"echo {safe_value}")
+```
+
+Suppress from the command line:
+
+```bash
+shellsafe audit src/ --ignore AU004
+```
+
 ## Limits
 
 - Shell features (pipes, redirections) work on Linux and macOS only. Windows
@@ -126,6 +139,7 @@ shellsafe audit src/ --severity warning
 ## More
 
 - Source and issues: [github.com/rahulXs/shellsafe](https://github.com/rahulXs/shellsafe)
+- Blog: [rahulxs.github.io/shellsafe](https://rahulxs.github.io/shellsafe/)
 - Want to help? See CONTRIBUTING.md in the repository.
 
 License: MIT

{shellsafe-0.3.3 → shellsafe-0.3.5}/pyproject.toml

@@ -34,6 +34,7 @@ Homepage = "https://github.com/rahulXs/shellsafe"
 Repository = "https://github.com/rahulXs/shellsafe"
 Issues = "https://github.com/rahulXs/shellsafe/issues"
 Changelog = "https://github.com/rahulXs/shellsafe/blob/main/CHANGELOG.md"
+Blog = "https://rahulxs.github.io/shellsafe/"
 
 [tool.hatch.version]
 path = "src/shellsafe/_version.py"

{shellsafe-0.3.3 → shellsafe-0.3.5}/src/shellsafe/__init__.py

@@ -1,11 +1,11 @@
 """shellsafe: safe shell commands via Python 3.14 template strings.
 
 Public surface (stable names, additive only through 1.0):
-run, capture, shx, RAW, CaptureResult.
+run, capture, shx, plan, RAW, CaptureResult.
 """
 
 from ._version import __version__
-from .execute import CaptureResult, capture, run, shx
+from .execute import CaptureResult, capture, plan, run, shx
 from .raw import RAW
 
 __all__ = [
@@ -13,6 +13,7 @@ __all__ = [
     "CaptureResult",
     "__version__",
     "capture",
+    "plan",
     "run",
     "shx",
 ]

shellsafe-0.3.5/src/shellsafe/_version.py

@@ -0,0 +1 @@
+__version__ = "0.3.5"

{shellsafe-0.3.3 → shellsafe-0.3.5}/src/shellsafe/audit/scanner.py

@@ -7,7 +7,7 @@ import ast
 import json
 import sys
 import time
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from pathlib import Path
 from typing import Any
 
@@ -158,13 +158,15 @@ def _track_dynamic_vars(tree: ast.Module):
     """Find variables assigned dynamic string expressions."""
     dynamic = set()
     for node in ast.walk(tree):
-        if not isinstance(node, ast.Assign):
-            continue
-        if not _is_dynamic_string(node.value):
-            continue
-        for target in node.targets:
-            if isinstance(target, ast.Name):
-                dynamic.add(target.id)
+        if isinstance(node, ast.Assign):
+            if not _is_dynamic_string(node.value):
+                continue
+            for target in node.targets:
+                if isinstance(target, ast.Name):
+                    dynamic.add(target.id)
+        elif isinstance(node, ast.NamedExpr):
+            if _is_dynamic_string(node.value) and isinstance(node.target, ast.Name):
+                dynamic.add(node.target.id)
     return dynamic
 
 
@@ -300,11 +302,17 @@ def _discover(paths: list[str]):
         if p.is_file() and p.suffix == ".py":
             files.append(p)
         elif p.is_dir():
-            files.extend(
-                f
-                for f in sorted(p.rglob("*.py"))
-                if not any(part.startswith(".") or part == "__pycache__" for part in f.parts)
-            )
+            import os
+
+            for dirpath, dirnames, filenames in os.walk(p, followlinks=True):
+                dirnames[:] = [
+                    d for d in dirnames
+                    if not d.startswith(".") and d != "__pycache__"
+                ]
+                for name in filenames:
+                    if name.endswith(".py"):
+                        files.append(Path(dirpath) / name)
+            files.sort()
     return files
 
 
@@ -341,10 +349,11 @@ def _parse_suppression_comment(comment: str) -> tuple[list[str], str | None]:
         return [], None
     rest = directive[len("ignore "):]
     reason = None
-    reason_match = rest.split(" reason:", 1)
-    if len(reason_match) == 2:
-        rest = reason_match[0]
-        reason = reason_match[1].strip() or None
+    reason_lower = rest.lower()
+    reason_idx = reason_lower.find(" reason:")
+    if reason_idx != -1:
+        reason = rest[reason_idx + 8:].strip() or None
+        rest = rest[:reason_idx]
     rule_ids = [r.strip().upper() for r in rest.split(",") if r.strip()]
     return rule_ids, reason
 
@@ -386,11 +395,14 @@ def _find_suppressed_line(
 ) -> tuple[set[str], str | None] | None:
     """Find which rules suppress findings at target_line.
 
-    Checks previous non-blank, non-comment line, then target line itself.
+    Checks up to 5 previous non-blank lines, then the target line itself.
     """
-    for candidate in (target_line - 1, target_line):
+    for offset in range(1, 6):
+        candidate = target_line - offset
         if candidate in line_suppressions:
             return line_suppressions[candidate]
+    if target_line in line_suppressions:
+        return line_suppressions[target_line]
     return None
 
 
@@ -402,24 +414,13 @@ def _apply_suppression(
 ) -> Finding:
     """Apply suppression rules to a finding. Returns new Finding with ignored flag."""
     rule_id = result.rule_id
+
+    if ignore and rule_id in ignore:
+        return replace(result, ignored=True, ignore_reason="CLI --ignore")
+
     suppressed = False
     ignore_reason = None
 
-    if ignore and rule_id in ignore:
-        return Finding(
-            rule_id=result.rule_id,
-            title=result.title,
-            severity=result.severity,
-            confidence=result.confidence,
-            path=result.path,
-            lineno=result.lineno,
-            col=result.col,
-            message=result.message,
-            evidence=result.evidence,
-            fix_hint=result.fix_hint,
-            ignored=True,
-            ignore_reason="CLI --ignore",
-        )
     if rule_id in file_rules or "*" in file_rules:
         suppressed = True
         ignore_reason = "file-level suppression"
@@ -433,24 +434,12 @@ def _apply_suppression(
 
     if not suppressed:
         return result
-    return Finding(
-        rule_id=result.rule_id,
-        title=result.title,
-        severity=result.severity,
-        confidence=result.confidence,
-        path=result.path,
-        lineno=result.lineno,
-        col=result.col,
-        message=result.message,
-        evidence=result.evidence,
-        fix_hint=result.fix_hint,
-        ignored=True,
-        ignore_reason=ignore_reason,
-    )
+    return replace(result, ignored=True, ignore_reason=ignore_reason)
 
 
 def _emit_au010(
     line_suppressions: dict[int, tuple[set[str], str | None]],
+    file_rules: set[str],
     rel: str,
 ) -> list[Finding]:
     """Emit AU010 warnings for suppression comments without reasons."""
@@ -477,6 +466,24 @@ def _emit_au010(
                     evidence={"rules": sorted(suppressed_rules)},
                 )
             )
+    if file_rules and "*" not in file_rules:
+        for rule in sorted(file_rules):
+            results.append(
+                Finding(
+                    rule_id="AU010",
+                    title="suppression comment without reason",
+                    severity="info",
+                    confidence=1.0,
+                    path=rel,
+                    lineno=1,
+                    col=0,
+                    message=(
+                        f"File-level suppression for {rule} "
+                        f"has no reason. Add: reason: <why>"
+                    ),
+                    evidence={"rules": [rule], "file_level": True},
+                )
+            )
     return results
 
 
@@ -506,7 +513,7 @@ def scan(paths: list[str], ignore: set[str] | None = None) -> list[Finding]:
                         findings.append(
                             _apply_suppression(result, ignore, file_rules, line_suppressions)
                         )
-        findings.extend(_emit_au010(line_suppressions, rel))
+        findings.extend(_emit_au010(line_suppressions, file_rules, rel))
 
     findings.sort(key=lambda f: (f.severity != "error", f.path, f.lineno))
     return findings

{shellsafe-0.3.3 → shellsafe-0.3.5}/src/shellsafe/execute.py

@@ -51,15 +51,14 @@ def _pass_through(kwargs: dict[str, object]):
     return {k: v for k, v in kwargs.items() if k in _ALLOWED_KWARGS}
 
 
-def run(template: object, /, **kwargs: object) -> subprocess.CompletedProcess[str]:
-    """Render the template and execute it.
+def _render(
+    template: object, kwargs: dict[str, object]
+) -> tuple[ExecutionPlan, subprocess.CompletedProcess[str]]:
+    """Render template and execute, returning both plan and result."""
+    from .render import plan as render_plan
 
-    Interpolated values always arrive as single argv elements. Keyword arguments
-    pass through to subprocess.run with one exception: shell is rejected by
-    design.
-    """
     _validate_kwargs(kwargs)
-    rendered = plan(template)
+    rendered = render_plan(template)
     if rendered.mode == "shell":
         if sys.platform.startswith("win"):
             raise ShellSafeError(
@@ -71,7 +70,19 @@ def run(template: object, /, **kwargs: object) -> subprocess.CompletedProcess[st
             "run() to execute pipes and redirections"
         )
     assert rendered.argv is not None
-    return subprocess.run(rendered.argv, **_pass_through(kwargs))
+    completed = subprocess.run(rendered.argv, **_pass_through(kwargs))
+    return rendered, completed
+
+
+def run(template: object, /, **kwargs: object) -> subprocess.CompletedProcess[str]:
+    """Render the template and execute it.
+
+    Interpolated values always arrive as single argv elements. Keyword arguments
+    pass through to subprocess.run with one exception: shell is rejected by
+    design.
+    """
+    _, completed = _render(template, kwargs)
+    return completed
 
 
 @dataclass(frozen=True, slots=True)
@@ -83,18 +94,24 @@ class CaptureResult:
     returncode: int
     plan: ExecutionPlan
 
+    def __repr__(self) -> str:
+        return (
+            f"CaptureResult(returncode={self.returncode}, "
+            f"stdout={self.stdout!r}, stderr={self.stderr!r})"
+        )
+
 
 def capture(template: object, /, **kwargs: object) -> CaptureResult:
     """Run with captured utf-8 stdout/stderr and return a CaptureResult."""
     kwargs["capture_output"] = True
     kwargs["text"] = True
     kwargs["encoding"] = "utf-8"
-    completed = run(template, **kwargs)
+    rendered, completed = _render(template, kwargs)
     return CaptureResult(
         stdout=completed.stdout,
         stderr=completed.stderr,
         returncode=completed.returncode,
-        plan=plan(template),
+        plan=rendered,
     )
 
 

{shellsafe-0.3.3 → shellsafe-0.3.5}/src/shellsafe/render.py

@@ -83,10 +83,15 @@ def _resolve(interpolation: Interpolation[str]) -> str:
         )
 
     if format_spec:
-        return format(converted, format_spec)
-    if conversion is None:
-        return str(converted)
-    return converted
+        result = format(converted, format_spec)
+    elif conversion is None:
+        result = str(converted)
+    else:
+        result = converted
+
+    if not isinstance(result, str):
+        result = str(result)
+    return result
 
 
 def _reject_nul(resolved: str):
@@ -176,4 +181,9 @@ def _render_shell(parts: list[Segment]) -> ExecutionPlan:
     line = "".join(line_parts).strip()
     if not line:
         raise ShellSafeTypeError("empty command")
+    if len(line) > 131072:
+        raise ShellSafeTypeError(
+            f"shell line exceeds 128KB ({len(line)} bytes); "
+            "use argv mode or shorten the command"
+        )
     return ExecutionPlan(mode="shell", shell_line=line)

{shellsafe-0.3.3 → shellsafe-0.3.5}/tests/unit/test_public_surface.py

@@ -4,7 +4,7 @@ import shellsafe
 
 
 def test_public_names_exist():
-    for name in ("run", "capture", "shx", "RAW", "CaptureResult", "__version__"):
+    for name in ("run", "capture", "shx", "plan", "RAW", "CaptureResult", "__version__"):
         assert hasattr(shellsafe, name), name
 
 
@@ -13,6 +13,7 @@ def test_all_is_exact():
         "run",
         "capture",
         "shx",
+        "plan",
         "RAW",
         "CaptureResult",
         "__version__",

shellsafe-0.3.3/src/shellsafe/_version.py

@@ -1 +0,0 @@
-__version__ = "0.3.3"