pyesh 1.0.0__tar.gz

pyesh-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PiSaucer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyesh-1.0.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: pyesh
+Version: 1.0.0
+Summary: Cross-platform, Python-oriented interactive and scripting shell.
+Author: PiSaucer
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pisaucer/pyesh
+Project-URL: Repository, https://github.com/PiSaucer/pyesh
+Project-URL: Issues, https://github.com/PiSaucer/pyesh/issues
+Keywords: cli,shell,interactive,scripting,python
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: prompt-toolkit<4,>=3.0.52
+Requires-Dist: rich<15,>=13.7
+Provides-Extra: dev
+Requires-Dist: build<2,>=1; extra == "dev"
+Requires-Dist: twine<7,>=5; extra == "dev"
+Provides-Extra: windows-executable
+Requires-Dist: pyinstaller<7,>=6; extra == "windows-executable"
+Dynamic: license-file
+
+# pyesh
+
+Python Expanded Shell: a cross-platform, Python-oriented interactive and scripting shell with direct process execution, typed Python pipelines, configurable user files, and command plugins.
+
+pyesh is its own shell language rather than a Bash interpreter. Explicit `.sh` and `.ps1` files continue to run through installed Bash and PowerShell runtimes.
+
+## Highlights
+
+* Job tracking with `jobs`, `wait`, `fg`, `bg`, `kill`, and `disown`; POSIX terminal job control.
+* Environment, aliases, history, directory stacks, portable output, and input built-ins.
+* Pipelines, conditions, per-stage redirection, heredocs, and `pipefail`.
+* Session variables, special parameters, command substitution, home expansion, and globs.
+* Stateful native Python at the prompt.
+* Typed `@variable:datatype` pipeline input and capture.
+* Explicit Python, Bash, and PowerShell script dispatch.
+* `source`/`deactivate` support for Python virtual environments.
+* Colorful live syntax highlighting, arrow-key history, and Tab completion.
+* Custom prompt, environment, PATH, startup, history, and plugin files.
+* Named JSON profiles for complete terminal and session customization.
+* Persistent Rich-powered customizable welcome splash.
+* Active-venv Python selection and optional venv-local pyesh startup files.
+* Stateful Python automation API.
+
+## Install and run
+
+Requires Python 3.9 or newer:
+
+```bash
+python -m pip install -e .
+pyesh --init
+pyesh
+pyesh -c 'echo "hello $(printf world)"'
+pyesh automation.pyesh one two
+printf 'echo from-stdin\n' | pyesh -
+```
+
+`pyesh` and `python -m pyesh` are equivalent.
+
+```plaintext
+user@machine project (main) % echo "hello"
+hello
+user@machine project (main) % numbers = [1, 2, 3]
+user@machine project (main) % @numbers:lines | @copy:lines
+user@machine project (main) % copy
+['1', '2', '3']
+```
+
+Run `help` or `man` inside the shell. Use `pyesh --help` for command-line options and `pyesh --version` for package and interpreter locations. Run `welcome` for a customizable splash summarizing the current runtime and session. Configure its template and automatic startup in `~/.pyesh_welcome`.
+
+## Documentation
+
+The [documentation](docs/README.md) links the complete project guides. See the [Changelog](CHANGELOG.md) and [development guide](docs/development.md) for project history and development workflow.
+
+## Quick examples
+
+Operators and scripts:
+
+```plaintext
+./examples/hello.py
+./examples/hello.sh | grep Bash
+failing-command || echo fallback
+echo first > output.txt ; echo second >> output.txt
+```
+
+Virtual environment:
+
+```plaintext
+python -m venv .venv
+source .venv/bin/activate
+deactivate
+```
+
+Python automation:
+
+```python
+from pyesh import PyeshSession
+
+session = PyeshSession(verbose=True)
+status = session.run_argv(["python", "./examples/hello.py"])
+```
+
+## Language boundary
+
+Python syntax supplies control flow and reusable functions. Bash functions, Bash parameter-expansion extensions, process substitution, and arbitrary file descriptor manipulation are not implemented. POSIX interactive job control is supported; Windows cannot suspend/resume jobs. Plugin capabilities beyond commands remain planned.
+
+## License
+
+Distributed under the **MIT License**. See [LICENSE](LICENSE) for more information.

pyesh-1.0.0/README.md

@@ -0,0 +1,88 @@
+# pyesh
+
+Python Expanded Shell: a cross-platform, Python-oriented interactive and scripting shell with direct process execution, typed Python pipelines, configurable user files, and command plugins.
+
+pyesh is its own shell language rather than a Bash interpreter. Explicit `.sh` and `.ps1` files continue to run through installed Bash and PowerShell runtimes.
+
+## Highlights
+
+* Job tracking with `jobs`, `wait`, `fg`, `bg`, `kill`, and `disown`; POSIX terminal job control.
+* Environment, aliases, history, directory stacks, portable output, and input built-ins.
+* Pipelines, conditions, per-stage redirection, heredocs, and `pipefail`.
+* Session variables, special parameters, command substitution, home expansion, and globs.
+* Stateful native Python at the prompt.
+* Typed `@variable:datatype` pipeline input and capture.
+* Explicit Python, Bash, and PowerShell script dispatch.
+* `source`/`deactivate` support for Python virtual environments.
+* Colorful live syntax highlighting, arrow-key history, and Tab completion.
+* Custom prompt, environment, PATH, startup, history, and plugin files.
+* Named JSON profiles for complete terminal and session customization.
+* Persistent Rich-powered customizable welcome splash.
+* Active-venv Python selection and optional venv-local pyesh startup files.
+* Stateful Python automation API.
+
+## Install and run
+
+Requires Python 3.9 or newer:
+
+```bash
+python -m pip install -e .
+pyesh --init
+pyesh
+pyesh -c 'echo "hello $(printf world)"'
+pyesh automation.pyesh one two
+printf 'echo from-stdin\n' | pyesh -
+```
+
+`pyesh` and `python -m pyesh` are equivalent.
+
+```plaintext
+user@machine project (main) % echo "hello"
+hello
+user@machine project (main) % numbers = [1, 2, 3]
+user@machine project (main) % @numbers:lines | @copy:lines
+user@machine project (main) % copy
+['1', '2', '3']
+```
+
+Run `help` or `man` inside the shell. Use `pyesh --help` for command-line options and `pyesh --version` for package and interpreter locations. Run `welcome` for a customizable splash summarizing the current runtime and session. Configure its template and automatic startup in `~/.pyesh_welcome`.
+
+## Documentation
+
+The [documentation](docs/README.md) links the complete project guides. See the [Changelog](CHANGELOG.md) and [development guide](docs/development.md) for project history and development workflow.
+
+## Quick examples
+
+Operators and scripts:
+
+```plaintext
+./examples/hello.py
+./examples/hello.sh | grep Bash
+failing-command || echo fallback
+echo first > output.txt ; echo second >> output.txt
+```
+
+Virtual environment:
+
+```plaintext
+python -m venv .venv
+source .venv/bin/activate
+deactivate
+```
+
+Python automation:
+
+```python
+from pyesh import PyeshSession
+
+session = PyeshSession(verbose=True)
+status = session.run_argv(["python", "./examples/hello.py"])
+```
+
+## Language boundary
+
+Python syntax supplies control flow and reusable functions. Bash functions, Bash parameter-expansion extensions, process substitution, and arbitrary file descriptor manipulation are not implemented. POSIX interactive job control is supported; Windows cannot suspend/resume jobs. Plugin capabilities beyond commands remain planned.
+
+## License
+
+Distributed under the **MIT License**. See [LICENSE](LICENSE) for more information.

pyesh-1.0.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "pyesh"
+dynamic = ["version"]
+description = "Cross-platform, Python-oriented interactive and scripting shell."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "PiSaucer" },
+]
+keywords = ["cli", "shell", "interactive", "scripting", "python"]
+dependencies = [
+    "prompt-toolkit>=3.0.52,<4",
+    "rich>=13.7,<15",
+]
+
+[project.optional-dependencies]
+dev = [
+    "build>=1,<2",
+    "twine>=5,<7",
+]
+windows-executable = [
+    "pyinstaller>=6,<7",
+]
+
+[project.urls]
+Homepage = "https://github.com/pisaucer/pyesh"
+Repository = "https://github.com/PiSaucer/pyesh"
+Issues = "https://github.com/PiSaucer/pyesh/issues"
+
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project.scripts]
+pyesh = "pyesh.cli:main"
+
+[tool.setuptools.dynamic]
+version = {attr = "pyesh.__version__"}
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]

pyesh-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyesh-1.0.0/src/pyesh/__init__.py

@@ -0,0 +1,6 @@
+# __init__.py
+__version__ = "1.0.0"
+
+# Expose api for importing as package
+from .api import PyeshSession, run_command
+__all__ = ["PyeshSession", "__version__", "run_command"]

pyesh-1.0.0/src/pyesh/__main__.py

@@ -0,0 +1,8 @@
+# __main__.py
+# Entry point for the pyesh command-line application
+# python -m pyesh
+
+import sys
+from .cli import main
+if __name__ == "__main__":
+    sys.exit(main())

pyesh-1.0.0/src/pyesh/_builtin_child.py

@@ -0,0 +1,24 @@
+# _builtin_child.py
+
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+# Resolve the installed/source package beside this file, independent of cwd.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+from pyesh.builtins import run_builtin
+from pyesh.plugins import PluginManager
+
+def main(arguments: Optional[List[str]] = None) -> Optional[int]:
+    """Run a stateless built-in or an explicitly selected plugin command."""
+    values = sys.argv[1:] if arguments is None else arguments
+    if len(values) >= 3 and values[0] == "--plugin":
+        manager = PluginManager()
+        manager.load_enabled([values[1]])
+        return manager.run(values[2:]) if not manager.errors else 1
+    if not values or values[0] not in ("echo", "printf", "pwd"):
+        return 2
+    return run_builtin(values)
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pyesh-1.0.0/src/pyesh/_job_child.py

@@ -0,0 +1,25 @@
+# _job_child.py
+
+import os
+import signal
+import sys
+
+def main() -> None:
+    """Configure the requested process group and execute the child.
+
+    Returns:
+        None. A successful call replaces the helper process.
+    """
+    group, error_fd = int(sys.argv[1]), int(sys.argv[2])
+    os.set_inheritable(error_fd, False)
+    try:
+        os.setpgid(0, group)
+        for name in ("SIGINT", "SIGQUIT", "SIGTSTP", "SIGTTIN", "SIGTTOU", "SIGPIPE"):
+            signal.signal(getattr(signal, name), signal.SIG_DFL)
+        os.execvpe(sys.argv[3], sys.argv[3:], os.environ)
+    except OSError as error:
+        os.write(error_fd, str(error.errno).encode("ascii"))
+        os._exit(127)
+
+if __name__ == "__main__":
+    main()

pyesh-1.0.0/src/pyesh/api.py

@@ -0,0 +1,246 @@
+# api.py
+
+from pathlib import Path
+from typing import Iterable, Mapping, Optional, Sequence
+from .execution import run_pipeline
+from .parsing import Command
+from .shell import SessionState, execute_command_line, execute_script
+
+class PyeshSession:
+    """A reusable command-execution session for Python applications.
+
+    The session preserves controls changed by built-ins, such as verbose mode,
+    across calls. Commands use the hosting Python process's working directory,
+    environment, and standard streams.
+    """
+    def __init__(self, verbose: bool = False, plugins: Optional[Iterable[str]] = None) -> None:
+        """Create an automation session.
+
+        Args:
+            verbose: Whether to trace resolved built-ins and process launches.
+            plugins: Installed plugin entry-point names to load explicitly.
+        """
+        self._state = SessionState(verbose=verbose)
+        if plugins is not None:
+            self._state.plugins.load_enabled(plugins)
+
+    @property
+    def plugin_errors(self) -> Mapping[str, str]:
+        """Return plugin loading failures keyed by plugin name.
+
+        Returns:
+            A copy of loading error messages.
+        """
+        return self._state.plugins.errors
+
+    @property
+    def verbose(self) -> bool:
+        """Return whether execution tracing is enabled.
+
+        Returns:
+            The current verbose setting.
+        """
+        return self._state.verbose
+
+    @property
+    def exit_requested(self) -> bool:
+        """Return whether the session received the ``exit`` built-in.
+
+        Returns:
+            ``True`` after an exit request.
+        """
+        return self._state.exit_requested
+
+    @property
+    def exit_status(self) -> int:
+        """Return the status retained by an explicit exit request.
+
+        Returns:
+            The normalized process exit status.
+        """
+        return self._state.exit_status
+
+    @property
+    def cwd(self) -> Path:
+        """Return the session working directory.
+
+        Returns:
+            The absolute session working directory.
+        """
+        return self._state.cwd
+
+    @property
+    def environment(self) -> Mapping[str, str]:
+        """Return a copy of the session child environment.
+
+        Returns:
+            Environment variables keyed by name.
+        """
+        return dict(self._state.environment)
+
+    @property
+    def variables(self) -> Mapping[str, object]:
+        """Return a copy of user-visible session variables.
+
+        Returns:
+            Python-backed values keyed by variable name.
+        """
+        return {key: value for key, value in self._state.python.namespace.items()
+                if not key.startswith("__") and key not in ("sh", "capture", "env", "argv")}
+
+    def set_cwd(self, path) -> None:
+        """Set the isolated session working directory.
+
+        Args:
+            path: Existing directory to use.
+
+        Returns:
+            None.
+        """
+        candidate = Path(path).expanduser().resolve(strict=True)
+        if not candidate.is_dir():
+            raise NotADirectoryError(str(candidate))
+        self._state.cwd = candidate
+        self._state.environment["PWD"] = str(candidate)
+
+    def set_environment(self, name: str, value: Optional[str]) -> None:
+        """Set or remove one session environment variable.
+
+        Args:
+            name: Environment variable name.
+            value: String value, or ``None`` to remove the name.
+
+        Returns:
+            None.
+        """
+        if value is None:
+            self._state.environment.pop(name, None)
+        else:
+            self._state.environment[name] = str(value)
+
+    def run(self, command_line: str) -> int:
+        """Execute one pyesh command line.
+
+        Args:
+            command_line: Commands and supported pyesh operators to execute.
+
+        Returns:
+            The final executed job's exit status. The ``exit`` built-in returns
+            the requested status and sets ``exit_requested``.
+
+        Raises:
+            ValueError: If the command line has invalid syntax.
+        """
+        if self._state.exit_requested:
+            return self._state.exit_status
+        return execute_command_line(command_line, state=self._state)
+
+    def run_all(self, command_lines: Iterable[str], stop_on_error: bool = False) -> int:
+        """Execute command lines in order.
+
+        Args:
+            command_lines: Command lines to execute.
+            stop_on_error: Stop after the first nonzero status when true.
+
+        Returns:
+            The final executed status, or zero for an empty iterable. Execution
+            also stops when a command requests session exit.
+
+        Raises:
+            ValueError: If any command line has invalid syntax.
+        """
+        status = 0
+        for command_line in command_lines:
+            status = self.run(command_line)
+            if self.exit_requested or (stop_on_error and status != 0):
+                break
+        return status
+
+    def run_script(self, source: str, filename: str = "<string>", argv: Iterable[str] = ()) -> int:
+        """Execute native pyesh source in this session.
+
+        Args:
+            source: Complete pyesh source text.
+            filename: Diagnostic name and ``$0`` value.
+            argv: Positional arguments exposed through ``argv`` and ``$1`` onward.
+
+        Returns:
+            The final command or explicit exit status.
+        """
+        self._state.argv0 = filename
+        self._state.argv[:] = list(argv)
+        return execute_script(source, self._state, filename)
+
+    def run_file(self, path, argv: Iterable[str] = ()) -> int:
+        """Read and execute a UTF-8 pyesh script.
+
+        Args:
+            path: Script path.
+            argv: Positional script arguments.
+
+        Returns:
+            The final command or explicit exit status.
+        """
+        source_path = Path(path).expanduser().resolve(strict=True)
+        return self.run_script(source_path.read_text(encoding="utf-8"), str(source_path), argv)
+
+    def run_argv(self, arguments: Sequence[str]) -> int:
+        """Execute an argument vector without parsing shell syntax.
+
+        Args:
+            arguments: Program followed by literal arguments.
+
+        Returns:
+            The child process exit status.
+        """
+        if not arguments:
+            return 0
+        status = run_pipeline([Command(arguments=list(arguments))], jobs=self._state.jobs,
+                              cwd=self._state.cwd, environment=self._state.environment,
+                              verbose=self._state.verbose, pipefail=self._state.pipefail)
+        self._state.last_status = status
+        return status
+
+    def close(self) -> None:
+        """Hang up jobs still managed by this session.
+
+        Returns:
+            None.
+        """
+        self._state.jobs.shutdown()
+
+    def __enter__(self):
+        """Enter a managed session context.
+
+        Returns:
+            This session.
+        """
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        """Close the session when leaving a managed context.
+
+        Args:
+            exc_type: Active exception type, when present.
+            exc_value: Active exception value, when present.
+            traceback: Active exception traceback, when present.
+
+        Returns:
+            None.
+        """
+        self.close()
+
+def run_command(command_line: str, verbose: bool = False) -> int:
+    """Execute one command line in a new pyesh automation session.
+
+    Args:
+        command_line: Commands and supported pyesh operators to execute.
+        verbose: Whether to trace resolved execution.
+
+    Returns:
+        The final command status.
+
+    Raises:
+        ValueError: If the command line has invalid syntax.
+    """
+    return PyeshSession(verbose=verbose).run(command_line)