# PyShell
A modular UNIX-like shell implementation in Python with a plugin architecture for custom commands.
## About
PyShell is an educational project that implements a fully functional command-line shell using pure Python. It mimics the behavior of UNIX shells while maintaining a clean, extensible architecture. The project demonstrates key concepts in operating systems, including command parsing, process management, file operations, and interactive user interfaces.
Built with a plugin-based architecture, PyShell separates core shell functionality from individual commands. Each command is a standalone Python module, making it easy to add, modify, or remove commands without touching the core shell engine. The shell maintains its own internal state, including current directory tracking and command history, providing a seamless user experience similar to bash or zsh.
## Features
- **Modular Design**: Plugin-based command system for easy extensibility
- **Command History**: Up/Down arrow navigation with persistent history across sessions
- **Pipelines & Redirections**: Full POSIX-like pipeline and I/O redirection support
- **UNIX-Compatible**: Familiar commands with UNIX-like behavior and options
- **Pure Python**: No external dependencies required - uses only standard library
- **Cross-Platform**: Works on Windows, Linux, and macOS
- **Comprehensive Testing**: Full test suite with unit tests for all commands
## Project Structure
```
PythonProjT5/
├── pyshell/
│ ├── commands/ # Plugin commands (ls, cat, grep, etc.)
│ ├── core/ # Shell engine and history management
│ │ ├── shell.py # Main shell class with event loop
│ │ ├── history.py # Command history with readline
│ │ └── pipeline.py # Pipeline and redirection handler
│ ├── utils/ # Shared utilities
│ │ ├── file_ops.py # File traversal and operations
│ │ ├── helpers.py # Path resolution utilities
│ │ └── parsers.py # Argument parsing
│ ├── resources/ # Demo and test files
│ ├── tests/ # Unit tests for all commands
│ └── main.py # Entry point
├── setup.py # Package installation
└── README.md # This file
```
## Usage
```bash
# Run the shell
python -m pyshell.main
# Or if installed
pyshell
```
## Built-in Commands
| Command | Description |
|--------------|------------------------------------------|
| `date` | Display current date and time |
| `whoami` | Print current username |
| `hostname` | Display system hostname |
| `timeit` | Measure execution time of commands |
| `exit` | Exit the shell |
## Plugin Commands
All plugin commands are dynamically loaded from the `commands/` directory. Each command supports a `-h` or `--help` flag for detailed usage information.
### File Operations
| Command | Description | Key Options |
|--------------|------------------------------------|----------------------------|
| `cat` | Concatenate and display files | `-n`, `-b`, `-s` |
| `cp` | Copy files and directories | `-r`, `-i`, `-v`, `-u` |
| `mv` | Move or rename files | `-i`, `-v`, `-f` |
| `rm` | Remove files and directories | `-r`, `-i`, `-f`, `-v` |
| `sizeof` | Display file size in bytes | - |
| `grep` | Search text patterns in files | `-i`, `-n`, `-r`, `-v` |
| `head` | Display first lines of files | `-n` |
| `tail` | Display last lines of files | `-n` |
| `find` | Search for files by name | `-i`, `-maxdepth` |
### Directory Operations
| Command | Description | Key Options |
|--------------|------------------------------------|----------------------------|
| `cd` | Change directory | Supports `.`, `..`, `~`, `-` |
| `ls` | List directory contents | `-R`, `-f` |
| `mkdir` | Create directories | `-p`, `-v` |
| `pwd` | Print working directory | `-L`, `-P` |
| `rmdir` | Remove empty directories | `-p`, `-v` |
### Utility
| Command | Description | Key Options |
|--------------|------------------------------------|----------------------------|
| `clear` | Clear terminal screen | - |
## Pipelines and Redirections
PyShell supports POSIX-like command pipelines and I/O redirections, allowing you to chain commands and redirect input/output just like in UNIX shells.
### Pipeline Operator (`|`)
Chain commands together, passing output from one command as input to the next:
```bash
PyShell> cat file.txt | grep "pattern" | head -5
PyShell> ls | grep ".py"
PyShell> cat data.txt | grep "error" | tail -10
```
### Output Redirection
**Overwrite** (`>`): Redirect output to a file, overwriting existing content
```bash
PyShell> cat file.txt > output.txt
PyShell> ls -la > directory_listing.txt
```
**Append** (`>>`): Redirect output to a file, appending to existing content
```bash
PyShell> cat file1.txt >> combined.txt
PyShell> cat file2.txt >> combined.txt
```
### Input Redirection
**Input from file** (`<`): Read input from a file instead of stdin
```bash
PyShell> cat < input.txt
PyShell> grep "pattern" < data.txt
```
### Complex Pipeline Examples
```bash
# Find all Python files and count them
PyShell> ls | grep ".py" | tail -5
# Search for pattern and save with line numbers
PyShell> cat large_file.txt | grep -n "ERROR" > errors_found.txt
# Process data through multiple filters
PyShell> cat data.txt | grep "2024" | grep "ERROR" | head -20 > recent_errors.txt
```
## Examples
```bash
# Basic file operations
PyShell> cat file.txt
PyShell> cp file.txt backup.txt
PyShell> mkdir -p new/nested/dir
# Text processing
PyShell> grep -i "pattern" file.txt
PyShell> head -n 20 file.txt
PyShell> find . -name "*.py"
# Pipelines and redirection
PyShell> cat file.txt | grep "error" | tail -10
PyShell> ls | grep ".py" > python_files.txt
PyShell> cat data.txt | head -100 | grep "pattern"
# Measure command execution time
PyShell> timeit ls -R /large/directory
# Navigation
PyShell> cd ~/projects
PyShell> pwd
PyShell> cd -
```
## Architecture
PyShell follows a clean separation of concerns:
- **Core Engine** (`core/shell.py`): Implements the main event loop, command dispatcher, and built-in commands. Handles tokenization, command lookup, and execution flow.
- **Pipeline Handler** (`core/pipeline.py`): Parses and executes command pipelines with I/O redirection. Manages stdin/stdout/stderr streams between commands in a pipeline.
- **Command Plugins** (`commands/`): Each command is a self-contained module with a `run(args, shell)` function. Commands have access to the shell instance for state management and support stdin/stdout for piping.
- **Utilities** (`utils/`): Shared functionality including argument parsing, file traversal, and path resolution used across multiple commands.
- **History Management** (`core/history.py`): Uses Python's `readline` module for persistent command history and line editing capabilities.
## Adding Custom Commands
Create a new Python file in `pyshell/commands/` with a `run(args, shell)` function:
```python
def run(args, shell):
"""
Your command implementation
Args:
args: List of command arguments
shell: Shell instance (access shell.current_dir)
Returns:
Exit code (0 for success, non-zero for error)
"""
print("Hello from custom command!")
return 0
```
The command will be automatically available in the shell with the filename as the command name.
## Testing
```bash
# Run all tests
python -m pytest pyshell/tests/
# Run specific test file
python -m pytest pyshell/tests/test_ls_command.py
```
## Requirements
- Python 3.6+
- Standard library only (no external dependencies)
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/pyshell",
"name": "pyshell-cli-PY5",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "shell, terminal, command-line, unix, bash, cli, educational",
"author": "PyShell Contributors-PrachiY,KetakiD,Deekshita",
"author_email": "PyShell Contributors <pyshell@example.com>",
"download_url": "https://files.pythonhosted.org/packages/d4/86/9707b5c936ff0bac33e3bbc6c730fe793dd893391bb52c1ee0ba971931de/pyshell_cli_py5-1.0.0.tar.gz",
"platform": null,
"description": "# PyShell\n\nA modular UNIX-like shell implementation in Python with a plugin architecture for custom commands.\n\n## About\n\nPyShell is an educational project that implements a fully functional command-line shell using pure Python. It mimics the behavior of UNIX shells while maintaining a clean, extensible architecture. The project demonstrates key concepts in operating systems, including command parsing, process management, file operations, and interactive user interfaces.\n\nBuilt with a plugin-based architecture, PyShell separates core shell functionality from individual commands. Each command is a standalone Python module, making it easy to add, modify, or remove commands without touching the core shell engine. The shell maintains its own internal state, including current directory tracking and command history, providing a seamless user experience similar to bash or zsh.\n\n## Features\n\n- **Modular Design**: Plugin-based command system for easy extensibility\n- **Command History**: Up/Down arrow navigation with persistent history across sessions\n- **Pipelines & Redirections**: Full POSIX-like pipeline and I/O redirection support\n- **UNIX-Compatible**: Familiar commands with UNIX-like behavior and options\n- **Pure Python**: No external dependencies required - uses only standard library\n- **Cross-Platform**: Works on Windows, Linux, and macOS\n- **Comprehensive Testing**: Full test suite with unit tests for all commands\n\n## Project Structure\n\n```\nPythonProjT5/\n\u251c\u2500\u2500 pyshell/\n\u2502 \u251c\u2500\u2500 commands/ # Plugin commands (ls, cat, grep, etc.)\n\u2502 \u251c\u2500\u2500 core/ # Shell engine and history management\n\u2502 \u2502 \u251c\u2500\u2500 shell.py # Main shell class with event loop\n\u2502 \u2502 \u251c\u2500\u2500 history.py # Command history with readline\n\u2502 \u2502 \u2514\u2500\u2500 pipeline.py # Pipeline and redirection handler\n\u2502 \u251c\u2500\u2500 utils/ # Shared utilities\n\u2502 \u2502 \u251c\u2500\u2500 file_ops.py # File traversal and operations\n\u2502 \u2502 \u251c\u2500\u2500 helpers.py # Path resolution utilities\n\u2502 \u2502 \u2514\u2500\u2500 parsers.py # Argument parsing\n\u2502 \u251c\u2500\u2500 resources/ # Demo and test files\n\u2502 \u251c\u2500\u2500 tests/ # Unit tests for all commands\n\u2502 \u2514\u2500\u2500 main.py # Entry point\n\u251c\u2500\u2500 setup.py # Package installation\n\u2514\u2500\u2500 README.md # This file\n```\n\n\n## Usage\n\n```bash\n# Run the shell\npython -m pyshell.main\n\n# Or if installed\npyshell\n```\n\n## Built-in Commands\n\n| Command | Description |\n|--------------|------------------------------------------|\n| `date` | Display current date and time |\n| `whoami` | Print current username |\n| `hostname` | Display system hostname |\n| `timeit` | Measure execution time of commands |\n| `exit` | Exit the shell |\n\n## Plugin Commands\n\nAll plugin commands are dynamically loaded from the `commands/` directory. Each command supports a `-h` or `--help` flag for detailed usage information.\n\n### File Operations\n\n| Command | Description | Key Options |\n|--------------|------------------------------------|----------------------------|\n| `cat` | Concatenate and display files | `-n`, `-b`, `-s` |\n| `cp` | Copy files and directories | `-r`, `-i`, `-v`, `-u` |\n| `mv` | Move or rename files | `-i`, `-v`, `-f` |\n| `rm` | Remove files and directories | `-r`, `-i`, `-f`, `-v` |\n| `sizeof` | Display file size in bytes | - |\n| `grep` | Search text patterns in files | `-i`, `-n`, `-r`, `-v` |\n| `head` | Display first lines of files | `-n` |\n| `tail` | Display last lines of files | `-n` |\n| `find` | Search for files by name | `-i`, `-maxdepth` |\n\n### Directory Operations\n\n| Command | Description | Key Options |\n|--------------|------------------------------------|----------------------------|\n| `cd` | Change directory | Supports `.`, `..`, `~`, `-` |\n| `ls` | List directory contents | `-R`, `-f` |\n| `mkdir` | Create directories | `-p`, `-v` |\n| `pwd` | Print working directory | `-L`, `-P` |\n| `rmdir` | Remove empty directories | `-p`, `-v` |\n\n### Utility\n\n| Command | Description | Key Options |\n|--------------|------------------------------------|----------------------------|\n| `clear` | Clear terminal screen | - |\n\n## Pipelines and Redirections\n\nPyShell supports POSIX-like command pipelines and I/O redirections, allowing you to chain commands and redirect input/output just like in UNIX shells.\n\n### Pipeline Operator (`|`)\n\nChain commands together, passing output from one command as input to the next:\n\n```bash\nPyShell> cat file.txt | grep \"pattern\" | head -5\nPyShell> ls | grep \".py\"\nPyShell> cat data.txt | grep \"error\" | tail -10\n```\n\n### Output Redirection\n\n**Overwrite** (`>`): Redirect output to a file, overwriting existing content\n```bash\nPyShell> cat file.txt > output.txt\nPyShell> ls -la > directory_listing.txt\n```\n\n**Append** (`>>`): Redirect output to a file, appending to existing content\n```bash\nPyShell> cat file1.txt >> combined.txt\nPyShell> cat file2.txt >> combined.txt\n```\n\n### Input Redirection\n\n**Input from file** (`<`): Read input from a file instead of stdin\n```bash\nPyShell> cat < input.txt\nPyShell> grep \"pattern\" < data.txt\n```\n\n### Complex Pipeline Examples\n\n```bash\n# Find all Python files and count them\nPyShell> ls | grep \".py\" | tail -5\n\n# Search for pattern and save with line numbers\nPyShell> cat large_file.txt | grep -n \"ERROR\" > errors_found.txt\n\n# Process data through multiple filters\nPyShell> cat data.txt | grep \"2024\" | grep \"ERROR\" | head -20 > recent_errors.txt\n```\n\n## Examples\n\n```bash\n# Basic file operations\nPyShell> cat file.txt\nPyShell> cp file.txt backup.txt\nPyShell> mkdir -p new/nested/dir\n\n# Text processing\nPyShell> grep -i \"pattern\" file.txt\nPyShell> head -n 20 file.txt\nPyShell> find . -name \"*.py\"\n\n# Pipelines and redirection\nPyShell> cat file.txt | grep \"error\" | tail -10\nPyShell> ls | grep \".py\" > python_files.txt\nPyShell> cat data.txt | head -100 | grep \"pattern\"\n\n# Measure command execution time\nPyShell> timeit ls -R /large/directory\n\n# Navigation\nPyShell> cd ~/projects\nPyShell> pwd\nPyShell> cd -\n```\n\n## Architecture\n\nPyShell follows a clean separation of concerns:\n\n- **Core Engine** (`core/shell.py`): Implements the main event loop, command dispatcher, and built-in commands. Handles tokenization, command lookup, and execution flow.\n- **Pipeline Handler** (`core/pipeline.py`): Parses and executes command pipelines with I/O redirection. Manages stdin/stdout/stderr streams between commands in a pipeline.\n- **Command Plugins** (`commands/`): Each command is a self-contained module with a `run(args, shell)` function. Commands have access to the shell instance for state management and support stdin/stdout for piping.\n- **Utilities** (`utils/`): Shared functionality including argument parsing, file traversal, and path resolution used across multiple commands.\n- **History Management** (`core/history.py`): Uses Python's `readline` module for persistent command history and line editing capabilities.\n\n## Adding Custom Commands\n\nCreate a new Python file in `pyshell/commands/` with a `run(args, shell)` function:\n\n```python\ndef run(args, shell):\n \"\"\"\n Your command implementation\n Args:\n args: List of command arguments\n shell: Shell instance (access shell.current_dir)\n Returns:\n Exit code (0 for success, non-zero for error)\n \"\"\"\n print(\"Hello from custom command!\")\n return 0\n```\n\nThe command will be automatically available in the shell with the filename as the command name.\n\n## Testing\n\n```bash\n# Run all tests\npython -m pytest pyshell/tests/\n\n# Run specific test file\npython -m pytest pyshell/tests/test_ls_command.py\n```\n\n## Requirements\n\n- Python 3.6+\n- Standard library only (no external dependencies)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A modular UNIX-like shell implementation in Python with plugin architecture",
"version": "1.0.0",
"project_urls": {
"Documentation": "https://github.com/yourusername/pyshell/blob/main/README.md",
"Homepage": "https://github.com/yourusername/pyshell",
"Issues": "https://github.com/yourusername/pyshell/issues",
"Repository": "https://github.com/yourusername/pyshell"
},
"split_keywords": [
"shell",
" terminal",
" command-line",
" unix",
" bash",
" cli",
" educational"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "06a061d6c4f051a33722df1017ad83b2fb57cd174ac084b52605e735aca34dae",
"md5": "2943fd8cfb262b7fe9b76d9ea2580bb9",
"sha256": "af9c2722ba7753c9ede5290998d01e9551a0bb974c6cd3c0b2ab8d2e47b7123b"
},
"downloads": -1,
"filename": "pyshell_cli_py5-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2943fd8cfb262b7fe9b76d9ea2580bb9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 109042,
"upload_time": "2025-10-12T13:22:17",
"upload_time_iso_8601": "2025-10-12T13:22:17.913103Z",
"url": "https://files.pythonhosted.org/packages/06/a0/61d6c4f051a33722df1017ad83b2fb57cd174ac084b52605e735aca34dae/pyshell_cli_py5-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d4869707b5c936ff0bac33e3bbc6c730fe793dd893391bb52c1ee0ba971931de",
"md5": "24b7086ef9e67f0f4c403b117076830d",
"sha256": "19431f369ffdc2062a09d6455c797cb7aa753aede14c95ceafb9dcb998b5a71c"
},
"downloads": -1,
"filename": "pyshell_cli_py5-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "24b7086ef9e67f0f4c403b117076830d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 84866,
"upload_time": "2025-10-12T13:22:19",
"upload_time_iso_8601": "2025-10-12T13:22:19.509884Z",
"url": "https://files.pythonhosted.org/packages/d4/86/9707b5c936ff0bac33e3bbc6c730fe793dd893391bb52c1ee0ba971931de/pyshell_cli_py5-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-12 13:22:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "pyshell",
"github_not_found": true,
"lcname": "pyshell-cli-py5"
}
JSON
