pyesh 1.0.0__py3-none-any.whl

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/__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/_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/_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/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)

pyesh/backends.py

@@ -0,0 +1,247 @@
+# backends.py
+
+import os
+import shlex
+import shutil
+import sys
+from pathlib import Path
+from typing import Iterable, List, Optional
+
+class RuntimeUnavailableError(RuntimeError):
+    """Raised when a script requires an interpreter that is not installed."""
+
+def active_virtual_environment(environment=None) -> Optional[Path]:
+    """Resolve the virtual environment active for this pyesh process.
+
+    Args:
+        environment: Optional session environment mapping.
+
+    Returns:
+        The environment root reported by the running interpreter or
+        ``VIRTUAL_ENV``, or ``None`` when neither identifies a directory.
+    """
+    if sys.prefix != getattr(sys, "base_prefix", sys.prefix):
+        prefix = Path(sys.prefix)
+        if prefix.is_dir():
+            return prefix.resolve()
+    configured = (os.environ if environment is None else environment).get("VIRTUAL_ENV")
+    if configured:
+        root = Path(configured).expanduser()
+        if root.is_dir():
+            return root.resolve()
+    return None
+
+def virtual_environment_scripts(root: Path) -> Path:
+    """Return the executable directory for a virtual environment.
+
+    Args:
+        root: Virtual-environment root.
+
+    Returns:
+        ``Scripts`` on Windows or ``bin`` on other platforms.
+    """
+    return root / ("Scripts" if os.name == "nt" else "bin")
+
+def active_python_executable(environment=None) -> str:
+    """Choose the active venv Python, falling back to this interpreter.
+
+    Args:
+        environment: Optional session environment mapping.
+
+    Returns:
+        Resolved Python executable path.
+    """
+    root = active_virtual_environment(environment)
+    if root is not None:
+        scripts = virtual_environment_scripts(root)
+        names = (
+            ("python.exe", "python")
+            if os.name == "nt"
+            else ("python", "python3")
+        )
+        for name in names:
+            candidate = scripts / name
+            if candidate.is_file() and os.access(str(candidate), os.X_OK):
+                # Preserve the venv launcher path instead of resolving its
+                # symlink to the base interpreter. Python uses that path to
+                # locate the environment's adjacent pyvenv.cfg.
+                return str(candidate.absolute())
+    return str(Path(sys.executable).resolve())
+
+def is_explicit_path(value: str) -> bool:
+    """Determine whether command text explicitly addresses a filesystem path.
+
+    Args:
+        value: Command name or path as entered after parsing.
+
+    Returns:
+        ``True`` for absolute paths and values containing a platform path
+        separator. A bare filename is deliberately not a local path.
+    """
+    path = Path(value)
+    separators = [separator for separator in (os.sep, os.altsep) if separator]
+    return path.is_absolute() or any(separator in value for separator in separators)
+
+def _first_executable(candidates: Iterable[Optional[str]], environment=None) -> Optional[str]:
+    """Return the first existing executable from candidate names or paths.
+
+    Args:
+        candidates: Executable names, absolute paths, or missing values.
+
+    Returns:
+        The resolved executable path, or ``None`` when none can be used.
+    """
+    for candidate in candidates:
+        if not candidate:
+            continue
+        discovered = shutil.which(candidate, path=(environment or os.environ).get("PATH"))
+        if discovered:
+            return discovered
+        path = Path(candidate).expanduser()
+        if path.is_file() and os.access(str(path), os.X_OK):
+            return str(path)
+    return None
+
+def discover_bash(environment=None) -> Optional[str]:
+    """Discover Bash, including common Git for Windows installations.
+
+    Args:
+        environment: Optional environment used for lookup.
+
+    Returns:
+        An executable path, or ``None`` when Bash is unavailable.
+    """
+    values = os.environ if environment is None else environment
+    program_files = values.get("ProgramFiles")
+    program_files_x86 = values.get("ProgramFiles(x86)")
+    local_app_data = values.get("LOCALAPPDATA")
+    return _first_executable(
+        [
+            "bash",
+            str(Path(program_files) / "Git" / "bin" / "bash.exe")
+            if program_files
+            else None,
+            str(Path(program_files_x86) / "Git" / "bin" / "bash.exe")
+            if program_files_x86
+            else None,
+            str(Path(local_app_data) / "Programs" / "Git" / "bin" / "bash.exe")
+            if local_app_data
+            else None,
+        ], values
+    )
+
+def discover_powershell(environment=None) -> Optional[str]:
+    """Discover PowerShell Core or Windows PowerShell.
+
+    Args:
+        environment: Optional environment used for lookup.
+
+    Returns:
+        An executable path, preferring cross-platform ``pwsh``, or ``None``.
+    """
+    values = os.environ if environment is None else environment
+    system_root = values.get("SystemRoot")
+    windows_powershell = (
+        str(Path(system_root) / "System32" / "WindowsPowerShell" / "v1.0" / "powershell.exe")
+        if system_root
+        else None
+    )
+    return _first_executable(["pwsh", "powershell", windows_powershell], values)
+
+def _read_shebang(script: Path) -> Optional[List[str]]:
+    """Read an interpreter argument vector from a script's first line.
+
+    Args:
+        script: Candidate script path.
+
+    Returns:
+        Parsed shebang arguments, or ``None``.
+    """
+    try:
+        with script.open("rb") as source:
+            first_line = source.readline(4097)
+    except OSError:
+        return None
+    if not first_line.startswith(b"#!") or len(first_line) > 4096:
+        return None
+    try:
+        return shlex.split(first_line[2:].decode("utf-8").strip(), posix=True) or None
+    except (UnicodeDecodeError, ValueError):
+        return None
+
+def _known_shebang_command(shebang: List[str], script: Path, environment=None) -> Optional[List[str]]:
+    """Prepare a portable command for a recognized shebang interpreter.
+
+    Args:
+        shebang: Parsed interpreter and arguments.
+        script: Script path.
+        environment: Optional lookup environment.
+
+    Returns:
+        Prepared argv, or ``None`` for an unknown interpreter.
+    """
+    interpreter = Path(shebang[0]).name.lower()
+    interpreter_arguments = shebang[1:]
+    if interpreter in ("env", "env.exe") and len(interpreter_arguments) == 1:
+        interpreter = Path(interpreter_arguments[0]).name.lower()
+        interpreter_arguments = []
+
+    if interpreter in ("python", "python3", "python.exe", "python3.exe"):
+        return [active_python_executable(environment)] + interpreter_arguments + [str(script)]
+    if interpreter in ("bash", "bash.exe"):
+        bash = discover_bash(environment)
+        if bash is None:
+            raise RuntimeUnavailableError("Bash is required for {0}; install Bash or Git for Windows".format(script))
+        return [bash] + interpreter_arguments + [str(script)]
+    if interpreter in ("pwsh", "pwsh.exe", "powershell", "powershell.exe"):
+        powershell = discover_powershell(environment)
+        if powershell is None:
+            raise RuntimeUnavailableError("PowerShell is required for {0}; install pwsh or Windows PowerShell".format(script))
+        return [powershell] + interpreter_arguments + [str(script)]
+    return None
+
+def prepare_command(arguments: List[str], environment=None) -> List[str]:
+    """Select an explicit interpreter for a recognized script file.
+
+    Args:
+        arguments: Program or script path followed by arguments.
+
+    Returns:
+        A new direct-execution argument list. Non-script commands are returned
+        unchanged in a new list.
+
+    Raises:
+        RuntimeUnavailableError: If a Bash or PowerShell script is requested
+            and its real runtime cannot be discovered.
+    """
+    if not arguments:
+        return []
+    script = Path(arguments[0])
+    if not is_explicit_path(arguments[0]):
+        # Bare names belong to PATH lookup. This prevents an untrusted file in
+        # the current directory from silently becoming executable shell input.
+        return list(arguments)
+    if not script.is_file():
+        return list(arguments)
+
+    shebang = _read_shebang(script)
+    if shebang is not None:
+        prepared = _known_shebang_command(shebang, script, environment)
+        if prepared is not None:
+            return prepared + arguments[1:]
+        return shebang + [str(script)] + arguments[1:]
+
+    suffix = script.suffix.lower()
+    if suffix == ".py":
+        return [active_python_executable(environment), str(script)] + arguments[1:]
+    if suffix == ".sh":
+        bash = discover_bash(environment)
+        if bash is None:
+            raise RuntimeUnavailableError("Bash is required for {0}; install Bash or Git for Windows".format(script))
+        return [bash, str(script)] + arguments[1:]
+    if suffix == ".ps1":
+        powershell = discover_powershell(environment)
+        if powershell is None:
+            raise RuntimeUnavailableError("PowerShell is required for {0}; install pwsh or Windows PowerShell".format(script))
+        return [powershell, "-NoProfile", "-File", str(script)] + arguments[1:]
+    return list(arguments)