my-pyshell 0.1.0__py3-none-any.whl

my_pyshell-0.1.0.dist-info/METADATA

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: my_pyshell
+Version: 0.1.0
+Summary: A custom Unix-like shell written in Python
+Requires-Python: >=3.10
+License-File: LICENSE
+Dynamic: license-file

my_pyshell-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+my_pyshell-0.1.0.dist-info/licenses/LICENSE,sha256=ESYyLizI0WWtxMeS7rGVcX3ivMezm-HOd5WdeOh-9oU,1056
+pyshell/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyshell/__main__.py,sha256=CA1H9WLtwsdEFT4nO86ePUdxjPAmx6QH-E9fQyizEU8,83
+pyshell/banner.py,sha256=u2imeNo8ecjAUVXIRC201GRzKtBG-1W_BgdHiN3gXoQ,2427
+pyshell/builtins.py,sha256=QK87fUfRq-im7C_HqIlRGrycLgL3vgK2u683C_-6I_k,4476
+pyshell/completion.py,sha256=3CiTnvxQ0XSYVOStxU5c_dd47dMR4d_GGce8qBWgOes,2120
+pyshell/executor.py,sha256=-ztmvK7oKxMCutYJts9pnmuohDzVrBWpUAaiGZXYToE,6784
+pyshell/history.py,sha256=JjQURTWp4dNIasophMST-asVKkxJGCAqAftA14FV-p4,1646
+pyshell/jobs.py,sha256=M5DTo5FN48RUuFUNyY_HI5dLNaWEF_Gf-m545n--xZ0,2393
+pyshell/main.py,sha256=FrxhNUaMZ_wB9XQgxL_mNQk0g_3ydAS0OvDdutcloI4,329
+pyshell/parser.py,sha256=sNgUpLEsnXjTpV1JTm_ovwER0zREqE514wSqF7d3Ago,7630
+pyshell/shell.py,sha256=E6KmRoQ-QIBHQC8uZbYKCYPNJ-a1I3IaBfOos5YMMnc,3075
+my_pyshell-0.1.0.dist-info/METADATA,sha256=zgLavDIv7IxlJp-4dxHQruANY_oN5ewptY-ZRsH5CLs,181
+my_pyshell-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+my_pyshell-0.1.0.dist-info/entry_points.txt,sha256=3SaEQUstZJocAiUjvV4aXZOBLG26qfr2y3Fidtne4t0,46
+my_pyshell-0.1.0.dist-info/top_level.txt,sha256=mqLMJYn_chB2OkoBIa-6xciUBr3gcua8ncfr3vq8W94,8
+my_pyshell-0.1.0.dist-info/RECORD,,

my_pyshell-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

my_pyshell-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyshell = pyshell.main:main

my_pyshell-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

my_pyshell-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyshell

pyshell/__main__.py

@@ -0,0 +1,5 @@
+from .main import main
+import sys
+
+if __name__ == "__main__":
+    sys.exit(main())

pyshell/banner.py

@@ -0,0 +1,87 @@
+"""Startup banner: an animated ASCII-art splash shown when pyshell launches.
+
+Skips itself automatically when stdout isn't a real terminal (piped
+input, CI, tests) so it never interferes with scripting or pytest.
+Can also be disabled explicitly with PYSHELL_NO_BANNER=1.
+"""
+from __future__ import annotations
+
+import getpass
+import os
+import platform
+import shutil
+import sys
+import time
+
+RESET = "\033[0m"
+BOLD = "\033[1m"
+DIM = "\033[2m"
+
+# A gradient of 256-color codes, cyan -> blue -> magenta, one per art line.
+_GRADIENT = [51, 45, 39, 33, 27, 63, 99, 135]
+
+_ART = [
+    r"    ____        _____ __         ____",
+    r"   / __ \__  __/ ___// /_  ___  / / /",
+    r"  / /_/ / / / /\__ \/ __ \/ _ \/ / / ",
+    r" / ____/ /_/ /___/ / / / /  __/ / /  ",
+    r"/_/    \__, //____/_/ /_/\___/_/_/   ",
+    r"      /____/                         ",
+]
+
+
+def _color(code: int) -> str:
+    return f"\033[38;5;{code}m"
+
+
+def _supports_color() -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    return sys.stdout.isatty()
+
+
+def _type_out(text: str, delay: float = 0.012) -> None:
+    for ch in text:
+        sys.stdout.write(ch)
+        sys.stdout.flush()
+        time.sleep(delay)
+    sys.stdout.write("\n")
+
+
+def show(version: str = "0.1.0") -> None:
+    """Print the animated banner. No-op when not attached to a real tty."""
+    if not sys.stdout.isatty() or os.environ.get("PYSHELL_NO_BANNER"):
+        return
+
+    color = _supports_color()
+    width = shutil.get_terminal_size(fallback=(80, 24)).columns
+
+    # Draw the ASCII-art logo one line at a time, gradient-colored,
+    # each line sliding in with a tiny delay for a "build up" feel.
+    for i, line in enumerate(_ART):
+        prefix = _color(_GRADIENT[i % len(_GRADIENT)]) if color else ""
+        suffix = RESET if color else ""
+        sys.stdout.write(prefix + line + suffix + "\n")
+        sys.stdout.flush()
+        time.sleep(0.05)
+
+    print()
+
+    user = getpass.getuser()
+    py_ver = platform.python_version()
+    tagline = f"welcome back, {user} — pyshell v{version} (python {py_ver})"
+    if color:
+        sys.stdout.write(DIM)
+    _type_out(tagline, delay=0.01)
+    if color:
+        sys.stdout.write(RESET)
+
+    hint = "type 'help' to see builtins, or 'exit' to leave"
+    if color:
+        sys.stdout.write(DIM)
+    print(hint)
+    if color:
+        sys.stdout.write(RESET)
+
+    print("-" * min(width, 60))
+    sys.stdout.flush()

pyshell/builtins.py

@@ -0,0 +1,173 @@
+"""Builtin shell commands.
+
+Each builtin has the signature: fn(args: list[str], shell: "Shell") -> int
+and returns an exit status (0 for success), writing to shell.stdout/stderr
+streams so redirection works uniformly for builtins and external commands.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+
+def bi_exit(args, shell) -> int:
+    code = 0
+    if args:
+        try:
+            code = int(args[0])
+        except ValueError:
+            code = 0
+    raise SystemExit(code)
+
+
+def bi_echo(args, shell) -> int:
+    print(" ".join(args), file=shell.stdout)
+    return 0
+
+
+def bi_pwd(args, shell) -> int:
+    print(os.getcwd(), file=shell.stdout)
+    return 0
+
+
+def bi_cd(args, shell) -> int:
+    target = args[0] if args else os.environ.get("HOME", os.path.expanduser("~"))
+    if target == "-":
+        target = os.environ.get("OLDPWD", os.getcwd())
+        print(target, file=shell.stdout)
+    target = os.path.expanduser(target)
+    old = os.getcwd()
+    try:
+        os.chdir(target)
+        os.environ["OLDPWD"] = old
+        os.environ["PWD"] = os.getcwd()
+        return 0
+    except FileNotFoundError:
+        print(f"cd: {args[0] if args else target}: No such file or directory", file=shell.stderr)
+        return 1
+    except NotADirectoryError:
+        print(f"cd: {args[0] if args else target}: Not a directory", file=shell.stderr)
+        return 1
+    except PermissionError:
+        print(f"cd: {args[0] if args else target}: Permission denied", file=shell.stderr)
+        return 1
+
+
+def bi_type(args, shell) -> int:
+    if not args:
+        return 0
+    status = 0
+    for cmd in args:
+        if cmd in BUILTINS:
+            print(f"{cmd} is a shell builtin", file=shell.stdout)
+        else:
+            path = shell.find_executable(cmd)
+            if path:
+                print(f"{cmd} is {path}", file=shell.stdout)
+            else:
+                print(f"{cmd}: not found", file=shell.stderr)
+                status = 1
+    return status
+
+
+def bi_export(args, shell) -> int:
+    if not args:
+        for k, v in sorted(os.environ.items()):
+            print(f"export {k}={v}", file=shell.stdout)
+        return 0
+    for arg in args:
+        if "=" in arg:
+            key, _, value = arg.partition("=")
+            os.environ[key] = value
+        else:
+            os.environ.setdefault(arg, "")
+    return 0
+
+
+def bi_unset(args, shell) -> int:
+    for arg in args:
+        os.environ.pop(arg, None)
+    return 0
+
+
+def bi_env(args, shell) -> int:
+    for k, v in sorted(os.environ.items()):
+        print(f"{k}={v}", file=shell.stdout)
+    return 0
+
+
+def bi_help(args, shell) -> int:
+    print("pyshell builtins:", file=shell.stdout)
+    for name in sorted(BUILTINS):
+        print(f"  {name}", file=shell.stdout)
+    return 0
+
+
+def bi_history(args, shell) -> int:
+    count = None
+    if args:
+        try:
+            count = int(args[0])
+        except ValueError:
+            print(f"history: {args[0]}: numeric argument required", file=shell.stderr)
+            return 1
+    for idx, entry in shell.history.show(count):
+        print(f"{idx:>5}  {entry}", file=shell.stdout)
+    return 0
+
+
+def bi_jobs(args, shell) -> int:
+    shell.jobs.reap_finished()
+    latest = shell.jobs.latest()
+    latest_id = latest.job_id if latest else None
+    for job in shell.jobs.all_sorted():
+        print(shell.jobs.format_line(job, latest_id), file=shell.stdout)
+    return 0
+
+
+def _resolve_job(args, shell):
+    if not args:
+        return shell.jobs.latest()
+    spec = args[0].lstrip("%")
+    try:
+        job_id = int(spec)
+    except ValueError:
+        return None
+    return shell.jobs.get(job_id)
+
+
+def bi_fg(args, shell) -> int:
+    job = _resolve_job(args, shell)
+    if job is None:
+        print("fg: no such job", file=shell.stderr)
+        return 1
+    print(job.command, file=shell.stdout)
+    shell.jobs.continue_job(job, foreground=True)
+    return 0
+
+
+def bi_bg(args, shell) -> int:
+    job = _resolve_job(args, shell)
+    if job is None:
+        print("bg: no such job", file=shell.stderr)
+        return 1
+    shell.jobs.continue_job(job, foreground=False)
+    print(f"[{job.job_id}]+ {job.command} &", file=shell.stdout)
+    return 0
+
+
+BUILTINS = {
+    "exit": bi_exit,
+    "echo": bi_echo,
+    "pwd": bi_pwd,
+    "cd": bi_cd,
+    "type": bi_type,
+    "export": bi_export,
+    "unset": bi_unset,
+    "env": bi_env,
+    "help": bi_help,
+    "history": bi_history,
+    "jobs": bi_jobs,
+    "fg": bi_fg,
+    "bg": bi_bg,
+}

pyshell/completion.py

@@ -0,0 +1,67 @@
+"""Tab completion, hooked into GNU readline.
+
+Completes the first word of a line against builtins + everything on
+PATH. Falls back to filename completion for later words (readline
+does this itself once we return None enough times).
+"""
+from __future__ import annotations
+
+import os
+
+from .builtins import BUILTINS
+
+
+def _path_executables() -> set[str]:
+    names = set()
+    for directory in os.environ.get("PATH", "").split(os.pathsep):
+        if not directory or not os.path.isdir(directory):
+            continue
+        try:
+            for entry in os.scandir(directory):
+                if entry.is_file() and os.access(entry.path, os.X_OK):
+                    names.add(entry.name)
+        except PermissionError:
+            continue
+    return names
+
+
+class Completer:
+    def __init__(self):
+        self._matches: list[str] = []
+
+    def complete(self, text: str, state: int) -> str | None:
+        import readline
+
+        buf = readline.get_line_buffer()
+        is_first_word = buf[:readline.get_begidx()].strip() == ""
+
+        if state == 0:
+            if is_first_word:
+                candidates = set(BUILTINS) | _path_executables()
+            else:
+                # filename completion for later words
+                dirname, _, prefix = text.rpartition(os.sep)
+                search_dir = dirname or "."
+                try:
+                    candidates = {
+                        os.path.join(dirname, e) if dirname else e
+                        for e in os.listdir(search_dir)
+                        if e.startswith(prefix)
+                    }
+                except OSError:
+                    candidates = set()
+            self._matches = sorted(c for c in candidates if c.startswith(text))
+        try:
+            return self._matches[state]
+        except IndexError:
+            return None
+
+
+def install() -> None:
+    try:
+        import readline
+    except ImportError:
+        return  # e.g. some minimal/windows builds lack readline
+    readline.set_completer(Completer().complete)
+    readline.parse_and_bind("tab: complete")
+    readline.set_completer_delims(" \t\n")

pyshell/executor.py

@@ -0,0 +1,181 @@
+"""Turns parsed Commands into running processes.
+
+Design:
+  - A single, non-backgrounded builtin runs in-process (the shell's
+    own process). This is required for state-mutating builtins like
+    cd/export/unset/exit, and it's also what makes output correctly
+    visible whether the shell's stdout is a real fd or a Python
+    object (as in tests). Everything else - external programs, piped
+    builtins, backgrounded commands - runs in a forked child so pipe
+    plumbing and job control work uniformly.
+  - Each pipeline gets its own process group so `jobs`/`fg`/`bg` and
+    signals (Ctrl-C, Ctrl-Z equivalents) can target the whole pipeline.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+from .builtins import BUILTINS
+from .parser import Command, Redirections
+
+
+def _open_redirections(redirs: Redirections):
+    """Open any files a Command's redirection targets, returning fds to dup2."""
+    stdin_fd = stdout_fd = stderr_fd = None
+    if redirs.stdin_path:
+        stdin_fd = os.open(redirs.stdin_path, os.O_RDONLY)
+    if redirs.stdout_path:
+        flags = os.O_WRONLY | os.O_CREAT | (os.O_APPEND if redirs.stdout_append else os.O_TRUNC)
+        stdout_fd = os.open(redirs.stdout_path, flags, 0o644)
+    if redirs.stderr_path:
+        flags = os.O_WRONLY | os.O_CREAT | (os.O_APPEND if redirs.stderr_append else os.O_TRUNC)
+        stderr_fd = os.open(redirs.stderr_path, flags, 0o644)
+    return stdin_fd, stdout_fd, stderr_fd
+
+
+def _run_builtin_child(command: Command, shell) -> None:
+    """Run a builtin inside a forked child, then _exit."""
+    fn = BUILTINS[command.args[0]]
+    try:
+        status = fn(command.args[1:], shell)
+    except SystemExit as e:
+        status = e.code or 0
+    except Exception as e:  # noqa: BLE001 - last line of defense in a child process
+        print(f"{command.args[0]}: {e}", file=sys.stderr)
+        status = 1
+    sys.stdout.flush()
+    sys.stderr.flush()
+    os._exit(status if isinstance(status, int) else 0)
+
+
+def _exec_external(command: Command, shell) -> None:
+    """Replace the current (forked) process image with an external program."""
+    path = shell.find_executable(command.args[0])
+    if path is None:
+        print(f"{command.args[0]}: command not found", file=sys.stderr)
+        os._exit(127)
+    try:
+        os.execv(path, command.args)
+    except OSError as e:
+        print(f"{command.args[0]}: {e}", file=sys.stderr)
+        os._exit(126)
+
+
+def run_pipeline(commands: list[Command], background: bool, raw_line: str, shell) -> int:
+    if not commands:
+        return 0
+
+    # Fast path: a single builtin with no pipe and not backgrounded runs
+    # inline, in the shell's own process. Redirection is applied by
+    # temporarily swapping shell.stdout/stderr to a file handle so it
+    # works whether the shell writes to real fds or a Python stream.
+    if len(commands) == 1 and not background and commands[0].args[0] in BUILTINS:
+        command = commands[0]
+        saved_stdout, saved_stderr = shell.stdout, shell.stderr
+        opened_files = []
+        try:
+            if command.redirs.stdin_path:
+                # Builtins in this shell don't read stdin from a file;
+                # open+close to validate the path and surface errors.
+                fd = os.open(command.redirs.stdin_path, os.O_RDONLY)
+                os.close(fd)
+            if command.redirs.stdout_path:
+                mode = "a" if command.redirs.stdout_append else "w"
+                f = open(command.redirs.stdout_path, mode)
+                opened_files.append(f)
+                shell.stdout = f
+            if command.redirs.stderr_path:
+                mode = "a" if command.redirs.stderr_append else "w"
+                f = open(command.redirs.stderr_path, mode)
+                opened_files.append(f)
+                shell.stderr = f
+            fn = BUILTINS[command.args[0]]
+            return fn(command.args[1:], shell)
+        finally:
+            shell.stdout, shell.stderr = saved_stdout, saved_stderr
+            for f in opened_files:
+                f.close()
+
+    # If it's a single external command, resolve it in the parent first.
+    # This lets "command not found" be reported through shell.stderr
+    # (correct even when shell.stderr is a non-fd Python stream, e.g.
+    # in tests) instead of only ever reaching a real fd 2 in a child.
+    if len(commands) == 1 and commands[0].args[0] not in BUILTINS:
+        if shell.find_executable(commands[0].args[0]) is None:
+            print(f"{commands[0].args[0]}: command not found", file=shell.stderr)
+            return 127
+
+    n = len(commands)
+    prev_read = None
+    pids: list[int] = []
+    pgid = None
+
+    for i, command in enumerate(commands):
+        is_last = i == n - 1
+        pipe_read, pipe_write = (None, None)
+        if not is_last:
+            pipe_read, pipe_write = os.pipe()
+
+        pid = os.fork()
+        if pid == 0:
+            # ---- child ----
+            if pgid is not None:
+                os.setpgid(0, pgid)
+            else:
+                os.setpgid(0, 0)
+
+            if prev_read is not None:
+                os.dup2(prev_read, 0)
+                os.close(prev_read)
+            if pipe_write is not None:
+                os.dup2(pipe_write, 1)
+                os.close(pipe_write)
+            if pipe_read is not None:
+                os.close(pipe_read)
+
+            stdin_fd, stdout_fd, stderr_fd = _open_redirections(command.redirs)
+            if stdin_fd is not None:
+                os.dup2(stdin_fd, 0)
+                os.close(stdin_fd)
+            if stdout_fd is not None:
+                os.dup2(stdout_fd, 1)
+                os.close(stdout_fd)
+            if stderr_fd is not None:
+                os.dup2(stderr_fd, 2)
+                os.close(stderr_fd)
+
+            if command.args[0] in BUILTINS:
+                _run_builtin_child(command, shell)
+            else:
+                _exec_external(command, shell)
+            os._exit(1)  # unreachable
+
+        # ---- parent ----
+        if pgid is None:
+            pgid = pid
+        try:
+            os.setpgid(pid, pgid)
+        except OSError:
+            pass  # child may have already done it / already exited
+        pids.append(pid)
+
+        if prev_read is not None:
+            os.close(prev_read)
+        if pipe_write is not None:
+            os.close(pipe_write)
+        prev_read = pipe_read
+
+    if background:
+        job = shell.jobs.add(pgid, pids, raw_line.strip())
+        print(f"[{job.job_id}] {pgid}", file=shell.stdout)
+        return 0
+
+    status = 0
+    for pid in pids:
+        _, wstatus = os.waitpid(pid, 0)
+        if os.WIFEXITED(wstatus):
+            status = os.WEXITSTATUS(wstatus)
+        elif os.WIFSIGNALED(wstatus):
+            status = 128 + os.WTERMSIG(wstatus)
+    return status

pyshell/history.py

@@ -0,0 +1,44 @@
+"""Command history: in-memory list plus file persistence."""
+from __future__ import annotations
+
+import os
+
+
+class History:
+    def __init__(self, path: str | None = None):
+        self.path = path or os.path.expanduser("~/.pyshell_history")
+        self.entries: list[str] = []
+        self._loaded_count = 0  # entries present at load time, for "append new only"
+
+    def load(self) -> None:
+        if os.path.isfile(self.path):
+            with open(self.path, "r", encoding="utf-8", errors="replace") as f:
+                self.entries = [line.rstrip("\n") for line in f if line.strip()]
+        self._loaded_count = len(self.entries)
+
+    def add(self, line: str) -> None:
+        if line.strip() == "":
+            return
+        self.entries.append(line)
+
+    def write_all(self, path: str | None = None) -> None:
+        target = path or self.path
+        with open(target, "w", encoding="utf-8") as f:
+            for entry in self.entries:
+                f.write(entry + "\n")
+
+    def append_new(self, path: str | None = None) -> None:
+        """Append only entries added since load() to the history file."""
+        target = path or self.path
+        new_entries = self.entries[self._loaded_count:]
+        if not new_entries:
+            return
+        with open(target, "a", encoding="utf-8") as f:
+            for entry in new_entries:
+                f.write(entry + "\n")
+        self._loaded_count = len(self.entries)
+
+    def show(self, count: int | None = None) -> list[str]:
+        if count is None:
+            return list(enumerate(self.entries, start=1))
+        return list(enumerate(self.entries, start=1))[-count:]

pyshell/jobs.py

@@ -0,0 +1,78 @@
+"""Background job tracking."""
+from __future__ import annotations
+
+import os
+import signal
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Job:
+    job_id: int
+    pgid: int
+    pids: list[int]
+    command: str
+    status: str = "Running"  # Running, Stopped, Done
+
+
+class JobTable:
+    def __init__(self):
+        self._jobs: dict[int, Job] = {}
+        self._next_id = 1
+
+    def add(self, pgid: int, pids: list[int], command: str) -> Job:
+        job = Job(job_id=self._next_id, pgid=pgid, pids=pids, command=command)
+        self._jobs[job.job_id] = job
+        self._next_id += 1
+        return job
+
+    def get(self, job_id: int) -> Job | None:
+        return self._jobs.get(job_id)
+
+    def latest(self) -> Job | None:
+        running = [j for j in self._jobs.values() if j.status != "Done"]
+        return running[-1] if running else None
+
+    def all_sorted(self) -> list[Job]:
+        return sorted(self._jobs.values(), key=lambda j: j.job_id)
+
+    def remove(self, job_id: int) -> None:
+        self._jobs.pop(job_id, None)
+
+    def reap_finished(self) -> list[Job]:
+        """Non-blocking check for finished background jobs. Returns newly-done jobs."""
+        finished = []
+        for job in list(self._jobs.values()):
+            if job.status == "Done":
+                continue
+            all_done = True
+            for pid in job.pids:
+                try:
+                    wpid, _ = os.waitpid(pid, os.WNOHANG)
+                    if wpid == 0:
+                        all_done = False
+                except ChildProcessError:
+                    pass  # already reaped
+            if all_done:
+                job.status = "Done"
+                finished.append(job)
+        return finished
+
+    def format_line(self, job: Job, latest_id: int | None = None) -> str:
+        marker = "+" if job.job_id == latest_id else " "
+        return f"[{job.job_id}]{marker}  {job.status:<10} {job.command}"
+
+    def continue_job(self, job: Job, foreground: bool) -> None:
+        job.status = "Running"
+        try:
+            os.killpg(job.pgid, signal.SIGCONT)
+        except ProcessLookupError:
+            job.status = "Done"
+            return
+        if foreground:
+            for pid in job.pids:
+                try:
+                    os.waitpid(pid, 0)
+                except ChildProcessError:
+                    pass
+            job.status = "Done"

pyshell/main.py

@@ -0,0 +1,17 @@
+"""Entry point: `python -m pyshell` or the installed `pyshell` command."""
+import sys
+
+from .shell import Shell
+
+
+def main() -> int:
+    shell = Shell()
+    try:
+        return shell.run()
+    except SystemExit as e:
+        shell.history.append_new()
+        return e.code or 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pyshell/parser.py

@@ -0,0 +1,256 @@
+"""
+Tokenizing and parsing for pyshell.
+
+Responsibilities:
+  - split_pipeline: split a raw line into pipeline stages on unquoted `|`
+  - tokenize:       turn a single stage into word tokens, honoring
+                     single quotes, double quotes, and backslash escapes
+  - extract_redirections: pull `>`, `>>`, `2>`, `2>>`, `<` out of a token
+                     list, returning the remaining command tokens plus
+                     a Redirections object describing file targets
+"""
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+
+_VAR_RE = re.compile(r"\$(\{(\w+)\}|(\w+)|\?)")
+
+
+def _expand_vars(text: str) -> str:
+    """Expand $VAR, ${VAR}, and $? using the current environment."""
+    def repl(m: re.Match) -> str:
+        if m.group(0) == "$?":
+            return os.environ.get("?", "0")
+        name = m.group(2) or m.group(3)
+        return os.environ.get(name, "")
+
+    return _VAR_RE.sub(repl, text)
+
+
+class ParseError(Exception):
+    pass
+
+
+def split_pipeline(line: str) -> list[str]:
+    """Split a line into stages on unquoted, unescaped `|`.
+
+    `echo "a|b"` must NOT be split; `echo a | wc` must be split into
+    two stages: 'echo a' and ' wc'.
+    """
+    stages = []
+    current = []
+    in_single = in_double = False
+    i = 0
+    while i < len(line):
+        c = line[i]
+        if in_single:
+            current.append(c)
+            if c == "'":
+                in_single = False
+        elif in_double:
+            current.append(c)
+            if c == '"':
+                in_double = False
+            elif c == "\\" and i + 1 < len(line):
+                current.append(line[i + 1])
+                i += 1
+        else:
+            if c == "'":
+                in_single = True
+                current.append(c)
+            elif c == '"':
+                in_double = True
+                current.append(c)
+            elif c == "\\" and i + 1 < len(line):
+                current.append(c)
+                current.append(line[i + 1])
+                i += 1
+            elif c == "|":
+                stages.append("".join(current))
+                current = []
+            else:
+                current.append(c)
+        i += 1
+    stages.append("".join(current))
+    if in_single or in_double:
+        raise ParseError("unmatched quote")
+    return stages
+
+
+def tokenize(line: str) -> list[str]:
+    """Split a single command stage into word tokens.
+
+    Rules (bash-like subset):
+      - Outside quotes, backslash escapes the next character literally.
+      - Inside single quotes, everything is literal (no escapes).
+      - Inside double quotes, backslash only escapes \\, $, ", ` and
+        newline; otherwise the backslash is kept literally.
+      - Unquoted whitespace separates tokens; runs of whitespace collapse.
+      - Adjacent quoted/unquoted chunks glue into a single token, e.g.
+        foo"bar baz"qux -> one token: foobar bazqux
+    """
+    tokens: list[str] = []
+    # A token is built from segments; each segment is either literal
+    # (single-quoted -> never variable-expanded) or expandable
+    # (unquoted / double-quoted -> $VAR gets expanded).
+    segments: list[tuple[str, bool]] = []
+    current: list[str] = []
+    expandable = True
+    have_token = False
+    in_single = in_double = False
+    i = 0
+    n = len(line)
+
+    def flush_segment():
+        nonlocal current
+        if current:
+            segments.append(("".join(current), expandable))
+            current = []
+
+    while i < n:
+        c = line[i]
+
+        if in_single:
+            if c == "'":
+                in_single = False
+                flush_segment()
+                expandable = True
+            else:
+                current.append(c)
+
+        elif in_double:
+            if c == '"':
+                in_double = False
+            elif c == "\\" and i + 1 < n and line[i + 1] in ('\\', "$", '"', "`", "\n"):
+                current.append(line[i + 1])
+                i += 1
+            else:
+                current.append(c)
+
+        else:
+            if c.isspace():
+                if have_token:
+                    flush_segment()
+                    tokens.append("".join(
+                        text if not exp else _expand_vars(text)
+                        for text, exp in segments
+                    ))
+                    segments = []
+                    have_token = False
+                i += 1
+                continue
+            elif c == "'":
+                flush_segment()
+                in_single = True
+                expandable = False
+                have_token = True
+            elif c == '"':
+                flush_segment()
+                in_double = True
+                expandable = True
+                have_token = True
+            elif c == "\\" and i + 1 < n:
+                current.append(line[i + 1])
+                have_token = True
+                i += 1
+            else:
+                current.append(c)
+                have_token = True
+
+        i += 1
+
+    if in_single or in_double:
+        raise ParseError("unmatched quote")
+
+    if have_token:
+        flush_segment()
+        tokens.append("".join(
+            text if not exp else _expand_vars(text)
+            for text, exp in segments
+        ))
+
+    return tokens
+
+
+@dataclass
+class Redirections:
+    stdout_path: str | None = None
+    stdout_append: bool = False
+    stderr_path: str | None = None
+    stderr_append: bool = False
+    stdin_path: str | None = None
+
+
+_REDIR_OPS = {
+    ">": ("stdout", False),
+    "1>": ("stdout", False),
+    ">>": ("stdout", True),
+    "1>>": ("stdout", True),
+    "2>": ("stderr", False),
+    "2>>": ("stderr", True),
+    "<": ("stdin", False),
+}
+
+
+def extract_redirections(tokens: list[str]) -> tuple[list[str], Redirections]:
+    """Remove redirection operators + targets from a token list."""
+    out_tokens: list[str] = []
+    redirs = Redirections()
+    i = 0
+    while i < len(tokens):
+        tok = tokens[i]
+        if tok in _REDIR_OPS:
+            if i + 1 >= len(tokens):
+                raise ParseError(f"syntax error near unexpected token `newline' after `{tok}'")
+            target = tokens[i + 1]
+            kind, append = _REDIR_OPS[tok]
+            if kind == "stdout":
+                redirs.stdout_path = target
+                redirs.stdout_append = append
+            elif kind == "stderr":
+                redirs.stderr_path = target
+                redirs.stderr_append = append
+            else:
+                redirs.stdin_path = target
+            i += 2
+        else:
+            out_tokens.append(tok)
+            i += 1
+    return out_tokens, redirs
+
+
+@dataclass
+class Command:
+    args: list[str]
+    redirs: Redirections
+
+
+def parse_line(line: str) -> tuple[list[Command], bool]:
+    """Parse a full input line into a pipeline of Commands.
+
+    Returns (commands, background) where background is True if the
+    line ended with an unquoted `&`.
+    """
+    stripped = line.rstrip()
+    background = False
+    # Detect trailing unquoted `&`
+    stage_check = split_pipeline(stripped)
+    last = stage_check[-1].rstrip()
+    if last.endswith("&") and not last.endswith("\\&"):
+        background = True
+        stripped = stripped.rstrip()[:-1].rstrip()
+
+    commands = []
+    for stage in split_pipeline(stripped):
+        stage = stage.strip()
+        if stage == "":
+            continue
+        tokens = tokenize(stage)
+        cmd_tokens, redirs = extract_redirections(tokens)
+        if not cmd_tokens:
+            raise ParseError("syntax error: empty command")
+        commands.append(Command(args=cmd_tokens, redirs=redirs))
+
+    return commands, background

pyshell/shell.py

@@ -0,0 +1,95 @@
+"""The Shell class: owns state and runs the read-eval-print loop."""
+from __future__ import annotations
+
+import os
+import sys
+
+from . import banner, completion
+from .executor import run_pipeline
+from .history import History
+from .jobs import JobTable
+from .parser import ParseError, parse_line
+
+
+class Shell:
+    def __init__(self, history_path: str | None = None):
+        self.jobs = JobTable()
+        self.history = History(path=history_path)
+        self.stdout = sys.stdout
+        self.stderr = sys.stderr
+        self.last_status = 0
+        self._path_cache: dict[str, str | None] = {}
+
+    # -- PATH lookup -----------------------------------------------------
+    def find_executable(self, cmd: str) -> str | None:
+        if os.sep in cmd:
+            return cmd if os.path.isfile(cmd) and os.access(cmd, os.X_OK) else None
+        if cmd in self._path_cache:
+            return self._path_cache[cmd]
+        result = None
+        for directory in os.environ.get("PATH", "").split(os.pathsep):
+            if not directory:
+                continue
+            candidate = os.path.join(directory, cmd)
+            if os.path.isfile(candidate) and os.access(candidate, os.X_OK):
+                result = candidate
+                break
+        self._path_cache[cmd] = result
+        return result
+
+    # -- prompt ------------------------------------------------------------
+    def prompt(self) -> str:
+        cwd = os.getcwd()
+        home = os.path.expanduser("~")
+        if cwd.startswith(home):
+            cwd = "~" + cwd[len(home):]
+        return f"{os.path.basename(cwd) and cwd}$ "
+
+    # -- main loop -----------------------------------------------------
+    def run(self) -> int:
+        self.history.load()
+        completion.install()
+        banner.show()
+        try:
+            while True:
+                self.jobs.reap_finished()
+                try:
+                    sys.stdout.write(self.prompt())
+                    sys.stdout.flush()
+                    line = input()
+                except EOFError:
+                    print()
+                    break
+                except KeyboardInterrupt:
+                    print()
+                    continue
+
+                if line.strip() == "":
+                    continue
+
+                self.history.add(line)
+                self.execute(line)
+                os.environ["?"] = str(self.last_status)
+        finally:
+            self.history.append_new()
+        return self.last_status
+
+    def execute(self, line: str) -> int:
+        try:
+            commands, background = parse_line(line)
+        except ParseError as e:
+            print(f"pyshell: {e}", file=self.stderr)
+            self.last_status = 2
+            return self.last_status
+
+        if not commands:
+            return 0
+
+        try:
+            self.last_status = run_pipeline(commands, background, line, self)
+        except SystemExit:
+            raise
+        except OSError as e:
+            print(f"pyshell: {e}", file=self.stderr)
+            self.last_status = 1
+        return self.last_status