my-pyshell 0.1.0__tar.gz

my_pyshell-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,89 @@
+# pyshell
+
+A Unix-like shell written from scratch in Python — no `shlex`, no
+`subprocess`, no `readline` shortcuts for the core logic. It has its
+own tokenizer, its own pipeline/redirection handling, and its own job
+control built on raw `os.fork`/`os.exec`/`os.pipe`.
+
+## Features
+
+- **Animated startup banner**: a gradient ASCII-art splash on launch
+  (auto-skips when piped/scripted/tested, or via `PYSHELL_NO_BANNER=1`)
+- **REPL** with a `cwd$ ` prompt
+- **Builtins**: `cd`, `pwd`, `echo`, `exit`, `type`, `export`, `unset`,
+  `env`, `history`, `jobs`, `fg`, `bg`, `help`
+- **Quoting**: single quotes (fully literal), double quotes (with
+  `\`, `$`, `"` escapes), backslash escaping outside quotes
+- **Variable expansion**: `$VAR`, `${VAR}`, `$?` (last exit status)
+- **Redirection**: `>`, `>>`, `2>`, `2>>`, `<`
+- **Pipelines**: `cmd1 | cmd2 | cmd3`, builtins and externals can be
+  mixed in a pipeline
+- **Background jobs**: `cmd &`, plus `jobs` / `fg` / `bg`, with real
+  process groups so signals target the whole pipeline
+- **History**: in-memory during the session, persisted to
+  `~/.pyshell_history` on exit (loaded back in on the next start)
+- **Tab completion**: builtins + `$PATH` executables for the first
+  word, filenames for the rest
+
+## Quick start
+
+```bash
+git clone <your-repo-url> pyshell
+cd pyshell
+python3 -m pyshell
+```
+
+Or install it as a command:
+
+```bash
+pip install -e .
+pyshell
+```
+
+## Architecture
+
+```
+pyshell/
+├── parser.py       # tokenize, split_pipeline, extract_redirections, parse_line
+├── builtins.py     # BUILTINS: name -> fn(args, shell) -> exit_status
+├── executor.py     # run_pipeline: forking, piping, redirection, backgrounding
+├── jobs.py         # JobTable: track/reap/continue background process groups
+├── history.py      # History: in-memory list + file persistence
+├── completion.py   # readline hook for tab completion
+├── banner.py       # animated ASCII-art startup splash
+├── shell.py        # Shell class: owns state, runs the REPL loop
+└── main.py         # entry point
+```
+
+**Design principle:** parsing, execution, and state are separate
+modules. A single non-backgrounded builtin runs directly in the
+shell's own process (so `cd` actually changes the shell's directory,
+and `exit` actually exits). Anything else — external programs, piped
+stages, or backgrounded commands — runs in a forked child, wired up
+with `os.pipe()`/`os.dup2()` and grouped into a process group with
+`os.setpgid()` so `jobs`/`fg`/`bg` can control the whole pipeline.
+
+## Running tests
+
+```bash
+pip install pytest
+pytest -q
+```
+
+## Known limitations / roadmap
+
+These map to natural next commits if you want to keep extending it:
+
+- No globbing (`*.txt` expansion)
+- No `&&` / `||` / `;` command chaining
+- No here-docs (`<<`)
+- No terminal-level job control (`Ctrl-Z` to suspend, `tcsetpgrp` for
+  real foreground/background terminal ownership) — `fg`/`bg` work via
+  `SIGCONT` and `waitpid` but don't hand over the controlling terminal
+- No command substitution (`` `cmd` `` / `$(cmd)`)
+- No aliasing or shell functions
+- No scripting (`if`/`for`/`while`, reading from a script file)
+
+## License
+
+MIT — do whatever you want with it.

my_pyshell-0.1.0/my_pyshell.egg-info/PKG-INFO

@@ -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/my_pyshell.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+LICENSE
+README.md
+pyproject.toml
+my_pyshell.egg-info/PKG-INFO
+my_pyshell.egg-info/SOURCES.txt
+my_pyshell.egg-info/dependency_links.txt
+my_pyshell.egg-info/entry_points.txt
+my_pyshell.egg-info/top_level.txt
+pyshell/__init__.py
+pyshell/__main__.py
+pyshell/banner.py
+pyshell/builtins.py
+pyshell/completion.py
+pyshell/executor.py
+pyshell/history.py
+pyshell/jobs.py
+pyshell/main.py
+pyshell/parser.py
+pyshell/shell.py
+tests/test_banner.py
+tests/test_parser.py
+tests/test_shell.py

my_pyshell-0.1.0/my_pyshell.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

my_pyshell-0.1.0/my_pyshell.egg-info/entry_points.txt

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

my_pyshell-0.1.0/my_pyshell.egg-info/top_level.txt

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

my_pyshell-0.1.0/pyproject.toml

@@ -0,0 +1,12 @@
+[project]
+name = "my_pyshell"
+version = "0.1.0"
+description = "A custom Unix-like shell written in Python"
+requires-python = ">=3.10"
+
+[project.scripts]
+pyshell = "pyshell.main:main"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"

my_pyshell-0.1.0/pyshell/__main__.py

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

my_pyshell-0.1.0/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()

my_pyshell-0.1.0/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,
+}

my_pyshell-0.1.0/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")

my_pyshell-0.1.0/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