PyBash 0.3.5__tar.gz → 0.4.0__tar.gz

pybash-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14", "3.15"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - run: uv sync
+      - run: make lint
+      - run: make test

pybash-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,18 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write # PyPI trusted publishing
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.0
+      - run: uv build
+      - run: uv publish

pybash-0.4.0/.gitignore

@@ -0,0 +1,129 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/

pybash-0.4.0/Makefile

@@ -0,0 +1,30 @@
+check: format lint test
+
+SOURCE_FILES=pybash tests
+
+install:
+	uv sync
+
+test:
+	uv run pytest -vv -rs
+
+format:
+	uv run ruff format ${SOURCE_FILES}
+	uv run ruff check ${SOURCE_FILES} --fix
+
+lint:
+	uv run ruff format --check --diff ${SOURCE_FILES}
+	uv run ruff check ${SOURCE_FILES}
+	uv run mypy
+
+demo:
+	cd examples && uv run pybash demo.py
+
+clean:
+	rm -rf build/ dist/ *.egg-info .pytest_cache .mypy_cache .ruff_cache
+	find . -name '__pycache__' -exec rm -rf {} +
+
+package: clean
+	uv build
+
+.PHONY: check install test format lint demo clean package

pybash-0.4.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.5
+Name: PyBash
+Version: 0.4.0
+Summary: >execute bash commands from python easily
+Project-URL: Repository, https://github.com/jaykv/PyBash
+Author-email: Jay <jay.github0@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bash,shell,subprocess,transpiler
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: System :: Shells
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: script
+Description-Content-Type: text/markdown
+
+# PyBash
+
+![GitHub Workflow Status (with branch)](https://img.shields.io/github/actions/workflow/status/jaykv/pybash/ci.yml?branch=main)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/pybash)
+![PyPI](https://img.shields.io/pypi/v/pybash)
+![GitHub](https://img.shields.io/github/license/jaykv/pybash)
+
+Write shell commands directly in Python. PyBash rewrites lines that start with `$` or `>` into
+`subprocess` calls, so you get the brevity of a shell script with the rest of Python around it.
+
+```python
+branch = ($git rev-parse --abbrev-ref HEAD).decode().strip()
+$git fetch origin && git rebase origin/{{branch}} || echo "rebase failed"
+count = $git log --oneline | wc -l
+print(f"{branch}: {int(count)} commits")
+```
+
+- `$` commands never go through a shell. Arguments are split at transform time, and pipes, redirects
+  and `&&` / `||` / `;` are run by PyBash itself, so a value can never turn into shell syntax.
+- `>` commands are handed to the shell as written, for globbing and expansion. Interpolated values are
+  quoted for you.
+- One line in, one line out: tracebacks point at the line you wrote.
+- No dependencies. Python 3.11+.
+
+## Install
+
+```bash
+pip install pybash
+```
+
+## Use
+
+### Run a script
+
+```bash
+pybash script.py [args...]      # or: python -m pybash script.py
+pybash --show script.py         # print the generated Python instead of running it
+pybash -c '$echo hello'
+```
+
+Modules the script imports from its own project may use the syntax too.
+
+### Transform source yourself
+
+```python
+from pybash import transform
+
+transform("$echo hello world")   # 'subprocess.run(["echo", "hello", "world"])'
+```
+
+Plain commands compile to bare `subprocess` calls. Commands with operators call a small helper in
+`pybash.runtime`; by default the generated code imports it in place, so the output only needs
+`import subprocess`. For tidier output, name the helper yourself and add the header:
+
+```python
+import pybash
+
+body = pybash.transform(source, runtime=pybash.RUNTIME_NAME)
+code = pybash.header() + body                   # imports pybash.runtime
+code = pybash.header(standalone=True) + body    # pastes the helper in: no pybash needed at run time
+```
+
+`pybash.compile_source(source, filename)` returns a code object ready for `exec`, and
+`pybash.add_hook()` installs an import hook for the current process.
+
+Mistakes raise `PybashSyntaxError`, a `SyntaxError` whose `filename`, `lineno`, `offset` and `text`
+point at the original line.
+
+## Syntax
+
+### Run: `$command`
+
+```python
+$python --version
+$cp test.txt test_copy.txt
+```
+
+Returns the `subprocess.CompletedProcess`. A non-zero exit does not raise.
+
+### Capture: `x = $command`, `($command)`, `$(command)`
+
+```python
+out = $cat test.txt
+print(($cat test.txt).decode().strip())
+lines = $(wc -l test.txt).decode().split()[0]
+```
+
+Captures are `bytes`, and raise `subprocess.CalledProcessError` on a non-zero exit.
+A capture not wrapped in brackets runs to the end of the line.
+
+### Operators
+
+| Operator | Meaning |
+|---|---|
+| `a \| b` | pipe stdout of `a` into `b` |
+| `a \|& b` | pipe stdout and stderr |
+| `a && b`, `a \|\| b`, `a ; b` | run `b` if `a` succeeded / failed / either way |
+| `< file` | read stdin from a file |
+| `> file`, `>> file` | write / append stdout |
+| `2> file`, `2>> file` | write / append stderr |
+| `&> file`, `&>> file` | write / append both |
+| `2>&1`, `>&2` | send stderr to stdout / stdout to stderr |
+
+```python
+$sort < in.txt | uniq -c | sort -rn > counts.txt
+$make build > build.log 2>&1 && echo ok || echo failed
+newest = $ls -t | head -n 1
+```
+
+Operators work without surrounding spaces (`a|b`, `2>err.log`). Quote or escape one to pass it as
+text: `$echo 'a && b' \| c`. Several output files on one command all receive the output
+(`$echo hi > a.txt >> b.txt`).
+
+Background jobs (`&`), here-documents (`<<`) and other file descriptors are not supported in `$`
+commands; use a `>` shell command for those.
+
+### Quoting
+
+`$` commands follow POSIX shell quoting: single quotes are literal, double quotes allow `\"` and `\\`,
+and a backslash escapes the next character. An unquoted `#` at the start of a word begins a comment.
+There is no globbing, `~` or `$VAR` expansion; use `>` when you need the shell.
+
+A trailing backslash continues the command on the next line.
+
+### Interpolation
+
+| Form | Meaning |
+|---|---|
+| `{{ expr }}` | the value of any Python expression, converted with `str()` |
+| `f{ expr }` | the same, with f-string formatting available: `f{n:03d}`, `f{name!r}` |
+
+```python
+$git {{command}} {{get_option(command)}}
+$kubectl get pods --show-{{display_type}}=true -n f{namespace}
+$echo "{{user}} has f{count:,} files"
+```
+
+In a `$` command an interpolated value is always exactly one argument, whatever it contains.
+Interpolation also applies inside quotes. To write the markers literally, escape them: `\{{` and `\f{`.
+
+### Shell: `>command`
+
+```python
+>ls .github/* | wc -l
+>echo "hello {{name}}" > out.txt
+```
+
+The line is passed to the shell untouched. Interpolated values are quoted for where they appear
+(bare, inside `"..."` or inside `'...'`), so they are always data. To splice shell syntax in on
+purpose, use `{{! expr }}`:
+
+```python
+pattern = "*.txt"
+>ls {{! pattern }}
+```
+
+## Upgrading from 0.3
+
+- Python 3.11+ is required; the `ideas` and `token-utils` dependencies are gone.
+- Arguments reach the command exactly as a shell would pass them. Previously backslashes were
+  re-interpreted by Python (`'a\\nb'` became a newline) and a `"` inside an argument produced invalid code.
+- `{{ x }}` is converted with `str()`, may contain spaces and quotes, and no longer raises `InvalidInterpolation`
+  for them.
+- Interpolated values in `>` commands are now quoted. Use `{{! x }}` for the old raw behavior.
+- `>` commands keep their quoting; previously quotes were stripped before the shell saw them.
+- `a = $x | y` now captures the pipeline's output instead of assigning a process object, and no
+  `cmd1` / `fout` variables leak into your code.
+- `$a > f1 > f2` writes the output to both files; previously the second file received a copy of the first.
+- `&&`, `||`, `;`, `2>`, `&>`, `2>&1`, `|&` and `$( )` are new. `&&` used to raise `NotImplementedError`.
+- Generated lists are formatted `["ls", "-la"]` and the result no longer ends with an added newline.
+- Text such as `"total = $5"` or `"($x)"` inside a Python string is no longer mistaken for a command.
+
+## Development
+
+```bash
+uv sync
+make check     # format, lint (ruff + mypy), test
+make demo
+```

pybash-0.4.0/README.md

@@ -0,0 +1,179 @@
+# PyBash
+
+![GitHub Workflow Status (with branch)](https://img.shields.io/github/actions/workflow/status/jaykv/pybash/ci.yml?branch=main)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/pybash)
+![PyPI](https://img.shields.io/pypi/v/pybash)
+![GitHub](https://img.shields.io/github/license/jaykv/pybash)
+
+Write shell commands directly in Python. PyBash rewrites lines that start with `$` or `>` into
+`subprocess` calls, so you get the brevity of a shell script with the rest of Python around it.
+
+```python
+branch = ($git rev-parse --abbrev-ref HEAD).decode().strip()
+$git fetch origin && git rebase origin/{{branch}} || echo "rebase failed"
+count = $git log --oneline | wc -l
+print(f"{branch}: {int(count)} commits")
+```
+
+- `$` commands never go through a shell. Arguments are split at transform time, and pipes, redirects
+  and `&&` / `||` / `;` are run by PyBash itself, so a value can never turn into shell syntax.
+- `>` commands are handed to the shell as written, for globbing and expansion. Interpolated values are
+  quoted for you.
+- One line in, one line out: tracebacks point at the line you wrote.
+- No dependencies. Python 3.11+.
+
+## Install
+
+```bash
+pip install pybash
+```
+
+## Use
+
+### Run a script
+
+```bash
+pybash script.py [args...]      # or: python -m pybash script.py
+pybash --show script.py         # print the generated Python instead of running it
+pybash -c '$echo hello'
+```
+
+Modules the script imports from its own project may use the syntax too.
+
+### Transform source yourself
+
+```python
+from pybash import transform
+
+transform("$echo hello world")   # 'subprocess.run(["echo", "hello", "world"])'
+```
+
+Plain commands compile to bare `subprocess` calls. Commands with operators call a small helper in
+`pybash.runtime`; by default the generated code imports it in place, so the output only needs
+`import subprocess`. For tidier output, name the helper yourself and add the header:
+
+```python
+import pybash
+
+body = pybash.transform(source, runtime=pybash.RUNTIME_NAME)
+code = pybash.header() + body                   # imports pybash.runtime
+code = pybash.header(standalone=True) + body    # pastes the helper in: no pybash needed at run time
+```
+
+`pybash.compile_source(source, filename)` returns a code object ready for `exec`, and
+`pybash.add_hook()` installs an import hook for the current process.
+
+Mistakes raise `PybashSyntaxError`, a `SyntaxError` whose `filename`, `lineno`, `offset` and `text`
+point at the original line.
+
+## Syntax
+
+### Run: `$command`
+
+```python
+$python --version
+$cp test.txt test_copy.txt
+```
+
+Returns the `subprocess.CompletedProcess`. A non-zero exit does not raise.
+
+### Capture: `x = $command`, `($command)`, `$(command)`
+
+```python
+out = $cat test.txt
+print(($cat test.txt).decode().strip())
+lines = $(wc -l test.txt).decode().split()[0]
+```
+
+Captures are `bytes`, and raise `subprocess.CalledProcessError` on a non-zero exit.
+A capture not wrapped in brackets runs to the end of the line.
+
+### Operators
+
+| Operator | Meaning |
+|---|---|
+| `a \| b` | pipe stdout of `a` into `b` |
+| `a \|& b` | pipe stdout and stderr |
+| `a && b`, `a \|\| b`, `a ; b` | run `b` if `a` succeeded / failed / either way |
+| `< file` | read stdin from a file |
+| `> file`, `>> file` | write / append stdout |
+| `2> file`, `2>> file` | write / append stderr |
+| `&> file`, `&>> file` | write / append both |
+| `2>&1`, `>&2` | send stderr to stdout / stdout to stderr |
+
+```python
+$sort < in.txt | uniq -c | sort -rn > counts.txt
+$make build > build.log 2>&1 && echo ok || echo failed
+newest = $ls -t | head -n 1
+```
+
+Operators work without surrounding spaces (`a|b`, `2>err.log`). Quote or escape one to pass it as
+text: `$echo 'a && b' \| c`. Several output files on one command all receive the output
+(`$echo hi > a.txt >> b.txt`).
+
+Background jobs (`&`), here-documents (`<<`) and other file descriptors are not supported in `$`
+commands; use a `>` shell command for those.
+
+### Quoting
+
+`$` commands follow POSIX shell quoting: single quotes are literal, double quotes allow `\"` and `\\`,
+and a backslash escapes the next character. An unquoted `#` at the start of a word begins a comment.
+There is no globbing, `~` or `$VAR` expansion; use `>` when you need the shell.
+
+A trailing backslash continues the command on the next line.
+
+### Interpolation
+
+| Form | Meaning |
+|---|---|
+| `{{ expr }}` | the value of any Python expression, converted with `str()` |
+| `f{ expr }` | the same, with f-string formatting available: `f{n:03d}`, `f{name!r}` |
+
+```python
+$git {{command}} {{get_option(command)}}
+$kubectl get pods --show-{{display_type}}=true -n f{namespace}
+$echo "{{user}} has f{count:,} files"
+```
+
+In a `$` command an interpolated value is always exactly one argument, whatever it contains.
+Interpolation also applies inside quotes. To write the markers literally, escape them: `\{{` and `\f{`.
+
+### Shell: `>command`
+
+```python
+>ls .github/* | wc -l
+>echo "hello {{name}}" > out.txt
+```
+
+The line is passed to the shell untouched. Interpolated values are quoted for where they appear
+(bare, inside `"..."` or inside `'...'`), so they are always data. To splice shell syntax in on
+purpose, use `{{! expr }}`:
+
+```python
+pattern = "*.txt"
+>ls {{! pattern }}
+```
+
+## Upgrading from 0.3
+
+- Python 3.11+ is required; the `ideas` and `token-utils` dependencies are gone.
+- Arguments reach the command exactly as a shell would pass them. Previously backslashes were
+  re-interpreted by Python (`'a\\nb'` became a newline) and a `"` inside an argument produced invalid code.
+- `{{ x }}` is converted with `str()`, may contain spaces and quotes, and no longer raises `InvalidInterpolation`
+  for them.
+- Interpolated values in `>` commands are now quoted. Use `{{! x }}` for the old raw behavior.
+- `>` commands keep their quoting; previously quotes were stripped before the shell saw them.
+- `a = $x | y` now captures the pipeline's output instead of assigning a process object, and no
+  `cmd1` / `fout` variables leak into your code.
+- `$a > f1 > f2` writes the output to both files; previously the second file received a copy of the first.
+- `&&`, `||`, `;`, `2>`, `&>`, `2>&1`, `|&` and `$( )` are new. `&&` used to raise `NotImplementedError`.
+- Generated lists are formatted `["ls", "-la"]` and the result no longer ends with an added newline.
+- Text such as `"total = $5"` or `"($x)"` inside a Python string is no longer mistaken for a command.
+
+## Development
+
+```bash
+uv sync
+make check     # format, lint (ruff + mypy), test
+make demo
+```

pybash-0.4.0/examples/demo.py

@@ -0,0 +1,40 @@
+# PYBASH DEMO #
+# run with: pybash demo.py   (or: python -m pybash demo.py)
+# see the generated Python with: pybash --show demo.py
+
+# 1. run a command; works anywhere a statement does
+$printf 'SORT TEST\nHELLO WORLD\n' > test.txt
+
+def cp_test():
+    $cp test.txt test_copy.txt
+
+cp_test()
+
+# 2. capture output as bytes
+out = $cat test.txt
+print(out.decode().strip().replace("HELLO", "HOWDY"))
+
+# 3. capture inline, with ($ ...) or $(...)
+print(($cat test.txt).decode().strip())
+print($(wc -l test.txt).decode().split()[0], "lines")
+
+# 4. pipes, redirects and && || ; run without a shell
+$cat test.txt | sed 's/HELLO/HOWDY/g' | sed 's/HOW/WHY/g'
+$sort < test.txt >> sorted_test.txt
+$test -f sorted_test.txt && echo "sorted" || echo "not sorted"
+$ls no-such-file 2> errors.txt; echo "kept going"
+count = $sort test.txt | uniq | wc -l
+print("unique lines:", int(count))
+
+# 5. interpolate Python values; each one is always a single argument
+name = "world; echo not-a-second-command"
+$echo hello {{name}}
+$echo f{len(name):04d} chars
+
+# 6. a real shell when you want globbing or expansion: start the line with >
+>ls ./*.txt | head -n 3
+>echo "safely quoted: {{name}}"
+
+# 7. long commands can continue onto the next line
+$rm -f test.txt test_copy.txt \
+    sorted_test.txt errors.txt

pybash-0.4.0/examples/hello.py

@@ -0,0 +1,2 @@
+text = "HELLO WORLD"
+$ echo f{text}

pybash-0.4.0/pybash/__init__.py

@@ -0,0 +1,41 @@
+"""Run shell commands from Python source with `$` and `>` lines."""
+
+from __future__ import annotations
+
+import inspect
+
+from pybash import runtime as _runtime
+from pybash.errors import InvalidInterpolation, PybashSyntaxError
+from pybash.hook import add_hook, compile_source, remove_hook
+from pybash.transformer import transform
+
+__all__ = [
+    "RUNTIME_NAME",
+    "InvalidInterpolation",
+    "PybashSyntaxError",
+    "add_hook",
+    "compile_source",
+    "header",
+    "remove_hook",
+    "runtime_source",
+    "transform",
+]
+
+#: Pass as `transform(..., runtime=RUNTIME_NAME)` when the output is prefixed with `header()`.
+RUNTIME_NAME = "_pybash"
+
+
+def runtime_source() -> str:
+    """Source of the stdlib-only helper class that generated code calls for operators."""
+    return inspect.getsource(_runtime._pybash)
+
+
+def header(*, standalone: bool = False) -> str:
+    """Lines to put above code produced by `transform(..., runtime=RUNTIME_NAME)`.
+
+    With `standalone=True` the helper is pasted in, so the result runs without
+    pybash installed.
+    """
+    if standalone:
+        return f"import subprocess\nfrom typing import Any\n\n\n{runtime_source()}\n"
+    return f"import subprocess\n\nimport pybash.runtime as {RUNTIME_NAME}\n"