shellsafe 0.1.0__tar.gz → 0.1.1__tar.gz

{shellsafe-0.1.0 → shellsafe-0.1.1}/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project are documented here. Format follows
 Keep a Changelog; versioning follows SemVer.
 
+## [0.1.1] - 2026-08-24
+
+### Changed
+
+- Project description rewritten
+- README restructured for PyPI: package page now leads with the why, usage and
+  limits; contributing details stay in the repository only
+
 ## [0.1.0] - 2026-08-24
 
 ### Added

shellsafe-0.1.1/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.5
+Name: shellsafe
+Version: 0.1.1
+Summary: Run shell commands safely using Python 3.14 template strings. Values can never turn into commands.
+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
+Author-email: Rahul Sharma <rahulxsh@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: automation,command-injection,injection,pep750,security,shell,subprocess,t-strings,template-strings
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# shellsafe
+
+> Run shell commands safely using Python 3.14 template strings. Values can never
+> turn into commands.
+
+```python
+from shellsafe import run
+
+message = get_user_input()          # "fix; rm -rf ~"
+run(t"git commit -m {message}")
+# argv: ["git", "commit", "-m", "fix; rm -rf ~"]
+# one command; the scary text is just an argument
+```
+
+## Why this package exists
+
+Python 3.14 added template strings (PEP 750). Now Python keeps your fixed text
+and your values separate at the language level.
+
+Shell commands are the first place people want to use this. That is because
+f-strings inside shell commands have caused real security bugs for ten years:
+
+```python
+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 plan was postponed.
+So today there is no standard way to run shell commands safely with templates.
+This package fills that gap.
+
+## Install
+
+```bash
+pip install shellsafe
+```
+
+Needs Python 3.14 or newer.
+
+## How to use
+
+Run a command. Your values always stay one argument each:
+
+```python
+from shellsafe import run
+
+run(t"mkdir {path}")
+run(t"docker build -t {tag} .", check=True, timeout=300)
+```
+
+Get the output as text:
+
+```python
+from shellsafe import capture
+
+res = capture(t"grep {pattern} {file}")
+print(res.stdout, res.returncode)
+```
+
+Need pipes? Works on Linux and macOS. Your values are quoted safely first:
+
+```python
+from shellsafe import shx
+
+shx(t"cat {file} | wc -l")
+```
+
+Want to see exactly what will run?
+
+```python
+from shellsafe import plan
+
+print(plan(t"git commit -m {message}"))
+# argv: ["git","commit","-m","fix; rm -rf ~"]
+```
+
+## Safety rules
+
+| Case | What happens |
+|---|---|
+| Any value you pass | becomes one argument, exactly as given |
+| Value used as the program name | error: program names must be written as fixed text |
+| Shell features on Windows | error: we cannot make Windows safe this way, so we say no |
+| RAW() misuse | error: one value only, used as-is, no nesting |
+
+`RAW(...)` marks content you have already made safe by hand. It is loud and easy
+to find in code review, so trust is never hidden.
+
+## Limits
+
+- On Windows, commands with pipes do not work. Plain commands work fully.
+- Byte values are rejected. Decode them first.
+- We keep your command safe to build and run. Testing what your command does is
+  still your job.
+
+## Needs
+
+- Python 3.14 or newer
+- Linux, macOS, Windows (pipes work on Linux and macOS only)
+
+## More
+
+- Source and issues: [github.com/rahulXs/shellsafe](https://github.com/rahulXs/shellsafe)
+- Want to help? See CONTRIBUTING.md in the repository.
+
+License: MIT

shellsafe-0.1.1/README.md

@@ -0,0 +1,106 @@
+# shellsafe
+
+> Run shell commands safely using Python 3.14 template strings. Values can never
+> turn into commands.
+
+```python
+from shellsafe import run
+
+message = get_user_input()          # "fix; rm -rf ~"
+run(t"git commit -m {message}")
+# argv: ["git", "commit", "-m", "fix; rm -rf ~"]
+# one command; the scary text is just an argument
+```
+
+## Why this package exists
+
+Python 3.14 added template strings (PEP 750). Now Python keeps your fixed text
+and your values separate at the language level.
+
+Shell commands are the first place people want to use this. That is because
+f-strings inside shell commands have caused real security bugs for ten years:
+
+```python
+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 plan was postponed.
+So today there is no standard way to run shell commands safely with templates.
+This package fills that gap.
+
+## Install
+
+```bash
+pip install shellsafe
+```
+
+Needs Python 3.14 or newer.
+
+## How to use
+
+Run a command. Your values always stay one argument each:
+
+```python
+from shellsafe import run
+
+run(t"mkdir {path}")
+run(t"docker build -t {tag} .", check=True, timeout=300)
+```
+
+Get the output as text:
+
+```python
+from shellsafe import capture
+
+res = capture(t"grep {pattern} {file}")
+print(res.stdout, res.returncode)
+```
+
+Need pipes? Works on Linux and macOS. Your values are quoted safely first:
+
+```python
+from shellsafe import shx
+
+shx(t"cat {file} | wc -l")
+```
+
+Want to see exactly what will run?
+
+```python
+from shellsafe import plan
+
+print(plan(t"git commit -m {message}"))
+# argv: ["git","commit","-m","fix; rm -rf ~"]
+```
+
+## Safety rules
+
+| Case | What happens |
+|---|---|
+| Any value you pass | becomes one argument, exactly as given |
+| Value used as the program name | error: program names must be written as fixed text |
+| Shell features on Windows | error: we cannot make Windows safe this way, so we say no |
+| RAW() misuse | error: one value only, used as-is, no nesting |
+
+`RAW(...)` marks content you have already made safe by hand. It is loud and easy
+to find in code review, so trust is never hidden.
+
+## Limits
+
+- On Windows, commands with pipes do not work. Plain commands work fully.
+- Byte values are rejected. Decode them first.
+- We keep your command safe to build and run. Testing what your command does is
+  still your job.
+
+## Needs
+
+- Python 3.14 or newer
+- Linux, macOS, Windows (pipes work on Linux and macOS only)
+
+## More
+
+- Source and issues: [github.com/rahulXs/shellsafe](https://github.com/rahulXs/shellsafe)
+- Want to help? See CONTRIBUTING.md in the repository.
+
+License: MIT

{shellsafe-0.1.0 → shellsafe-0.1.1}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "shellsafe"
 dynamic = ["version"]
-description = "Safe shell commands via Python 3.14 template strings. Injection-proof by construction."
+description = "Run shell commands safely using Python 3.14 template strings. Values can never turn into commands."
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.14"

shellsafe-0.1.1/src/shellsafe/_version.py

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

shellsafe-0.1.1/tests/unit/test_raw.py

@@ -0,0 +1,15 @@
+"""RAW marker invariants: nesting refused, verbatim display, single argument."""
+
+import pytest
+
+from shellsafe import RAW
+from shellsafe.errors import RawUsageError
+
+
+def test_raw_repr_shows_trust_boundary():
+    assert "<RAW" in repr(RAW("pre-quoted"))
+
+
+def test_nested_raw_refused():
+    with pytest.raises(RawUsageError):
+        RAW(RAW(["x"]))

shellsafe-0.1.0/PKG-INFO

@@ -1,126 +0,0 @@
-Metadata-Version: 2.5
-Name: shellsafe
-Version: 0.1.0
-Summary: Safe shell commands via Python 3.14 template strings. Injection-proof by construction.
-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
-Author-email: Rahul Sharma <rahulxsh@gmail.com>
-License-Expression: MIT
-License-File: LICENSE
-Keywords: automation,command-injection,injection,pep750,security,shell,subprocess,t-strings,template-strings
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Security
-Classifier: Topic :: Software Development :: Libraries
-Classifier: Typing :: Typed
-Requires-Python: >=3.14
-Description-Content-Type: text/markdown
-
-# shellsafe
-
-> Safe shell commands via Python 3.14 template strings. Injection-proof by
-> construction.
-
-```python
-from shellsafe import run
-
-message = get_user_input()          # "fix; rm -rf ~"
-run(t"git commit -m {message}")
-# argv: ["git", "commit", "-m", "fix; rm -rf ~"]
-# one command; the scary text is just an argument
-```
-
-## Why
-
-The dominant pattern in scripts and automation is still this:
-
-```python
-subprocess.run(f"git commit -m {message}", shell=True)   # injection waiting to happen
-```
-
-Python 3.14 template strings (`t"..."`) separate static text from interpolated
-values. shellsafe turns that structure into argv lists where interpolated values
-are always data, never commands. When you genuinely need pipes, shell mode quotes
-every value with POSIX rules first.
-
-## Install
-
-```bash
-pip install shellsafe
-```
-
-Requires Python 3.14+ (template strings).
-
-## Usage
-
-Run a command. Interpolated values are always single arguments:
-
-```python
-from shellsafe import run
-
-run(t"mkdir {path}")
-run(t"docker build -t {tag} .", check=True, timeout=300)
-```
-
-Capture output as text:
-
-```python
-from shellsafe import capture
-
-res = capture(t"grep {pattern} {file}")
-print(res.stdout, res.returncode)
-```
-
-Pipes and redirections on POSIX (values are quoted with `shlex.quote` first):
-
-```python
-from shellsafe import shx
-
-shx(t"cat {file} | wc -l")
-```
-
-Inspect exactly what will execute:
-
-```python
-from shellsafe import plan  # lower-level: render without running
-
-print(plan(t"git commit -m {message}"))
-# argv: ["git","commit","-m","fix; rm -rf ~"]
-```
-
-## What it refuses
-
-| Case | Behavior |
-|---|---|
-| Interpolation as the executable | error: the command comes from static text only |
-| Shell route on Windows | error: cmd.exe quoting cannot be made injection-safe; use argv mode |
-| RAW misuse | error: one argument, verbatim, nesting refused |
-
-`RAW("...")` / `RAW(["a", "b"])` is the single explicit trust boundary for
-pre-quoted content. Every use site is greppable.
-
-## Limits
-
-- Windows: interpolated shell routes are refused rather than approximated;
-  argv-mode commands work fully.
-- Bytes interpolations are rejected: decode explicitly first.
-- Runtime behavior after import is your test suite's job, same trust model as
-  calling subprocess yourself.
-
-## Contributing
-
-Issues and PRs welcome. Security reports go privately to the maintainer, never
-through public issues.
-
-## Requirements
-
-- CPython >= 3.14 (uses template strings from PEP 750)
-- Linux, macOS, Windows (Windows supports argv mode; POSIX-only shell mode)
-
-## License
-
-MIT

shellsafe-0.1.0/README.md

@@ -1,104 +0,0 @@
-# shellsafe
-
-> Safe shell commands via Python 3.14 template strings. Injection-proof by
-> construction.
-
-```python
-from shellsafe import run
-
-message = get_user_input()          # "fix; rm -rf ~"
-run(t"git commit -m {message}")
-# argv: ["git", "commit", "-m", "fix; rm -rf ~"]
-# one command; the scary text is just an argument
-```
-
-## Why
-
-The dominant pattern in scripts and automation is still this:
-
-```python
-subprocess.run(f"git commit -m {message}", shell=True)   # injection waiting to happen
-```
-
-Python 3.14 template strings (`t"..."`) separate static text from interpolated
-values. shellsafe turns that structure into argv lists where interpolated values
-are always data, never commands. When you genuinely need pipes, shell mode quotes
-every value with POSIX rules first.
-
-## Install
-
-```bash
-pip install shellsafe
-```
-
-Requires Python 3.14+ (template strings).
-
-## Usage
-
-Run a command. Interpolated values are always single arguments:
-
-```python
-from shellsafe import run
-
-run(t"mkdir {path}")
-run(t"docker build -t {tag} .", check=True, timeout=300)
-```
-
-Capture output as text:
-
-```python
-from shellsafe import capture
-
-res = capture(t"grep {pattern} {file}")
-print(res.stdout, res.returncode)
-```
-
-Pipes and redirections on POSIX (values are quoted with `shlex.quote` first):
-
-```python
-from shellsafe import shx
-
-shx(t"cat {file} | wc -l")
-```
-
-Inspect exactly what will execute:
-
-```python
-from shellsafe import plan  # lower-level: render without running
-
-print(plan(t"git commit -m {message}"))
-# argv: ["git","commit","-m","fix; rm -rf ~"]
-```
-
-## What it refuses
-
-| Case | Behavior |
-|---|---|
-| Interpolation as the executable | error: the command comes from static text only |
-| Shell route on Windows | error: cmd.exe quoting cannot be made injection-safe; use argv mode |
-| RAW misuse | error: one argument, verbatim, nesting refused |
-
-`RAW("...")` / `RAW(["a", "b"])` is the single explicit trust boundary for
-pre-quoted content. Every use site is greppable.
-
-## Limits
-
-- Windows: interpolated shell routes are refused rather than approximated;
-  argv-mode commands work fully.
-- Bytes interpolations are rejected: decode explicitly first.
-- Runtime behavior after import is your test suite's job, same trust model as
-  calling subprocess yourself.
-
-## Contributing
-
-Issues and PRs welcome. Security reports go privately to the maintainer, never
-through public issues.
-
-## Requirements
-
-- CPython >= 3.14 (uses template strings from PEP 750)
-- Linux, macOS, Windows (Windows supports argv mode; POSIX-only shell mode)
-
-## License
-
-MIT

shellsafe-0.1.0/src/shellsafe/_version.py

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

shellsafe-0.1.0/tests/unit/test_raw.py

@@ -1,28 +0,0 @@
-"""RAW marker invariants: nesting refused, verbatim display, single argument."""
-
-import pytest
-
-from shellsafe import RAW
-from shellsafe.errors import RawUsageError
-from shellsafe.raw import Raw
-
-
-def test_raw_wraps_list_verbatim():
-    r = RAW(["git", "log", "--oneline"])
-    assert isinstance(r, Raw)
-    assert r.value == ["git", "log", "--oneline"]
-
-
-def test_raw_repr_shows_trust_boundary():
-    assert "<RAW" in repr(RAW("pre-quoted"))
-
-
-def test_nested_raw_refused():
-    with pytest.raises(RawUsageError):
-        RAW(RAW(["x"]))
-
-
-def test_raw_is_greppable():
-    # house rule: trust boundaries are greppable; this documents the pattern
-    source = 'RAW("trusted")'
-    assert "RAW(" in source