richpyls - A Python Implementation of the Unix ls Command

A modern, type-annotated Python implementation of the Unix ls command with beautiful Rich formatting, color-coded file types, and support for long format listings and hidden files.

Quality Metrics

Metric	Status
Test Coverage
Type Coverage
Code Quality
Security Scan
Documentation

Features

• 🎨 Rich Visual Output: Beautiful color-coded file types with emoji icons
• 📁 Directory Listing: List files and directories in the current or specified path
• 📄 Long Format: Display detailed file information in a professional table format
• 🌳 Tree View: Display directories in a tree-like hierarchical format with the -t option
• 🔍 Hidden Files: Show hidden files (starting with .) with the -a option using 🫣 emoji
• 📊 Size Sorting: Show top N largest files/directories sorted by size with the -s option
• 🏃 Fast Performance: Built with modern Python using pathlib for efficient path operations
• 🎯 Type Safety: Fully type-annotated codebase with mypy validation
• ✅ Well Tested: Comprehensive test suite with excellent coverage
• 🐍 Modern Python: Uses Python 3.13+ features and best practices

File Type Icons

The Rich output includes beautiful emoji icons for different file types:

• 🐍 Python files (.py, .pyx, .pyi)
• ⚙️ Configuration files (.toml, .json, .yaml, .yml, .ini, .cfg, .conf)
• 📄 Documentation files (.md, .rst, .txt, .doc, .docx, .pdf)
• 📦 Archive files (.zip, .tar, .gz, .bz2, .xz, .7z, .rar)
• 🖼️ Image files (.png, .jpg, .jpeg, .gif, .bmp, .svg, .ico)
• 📁 Directories
• ⚡ Executable files
• 🔗 Symbolic links
• 🫣 Hidden files (starting with .)

Installation

From PyPI (Recommended)

pip install richpyls

Once installed, you can use the richpyls command anywhere in your terminal.

From Source

Using uv (recommended)

# Clone the repository
git clone https://github.com/lpozo/richpyls.git
cd richpyls

# Install with uv
uv sync

# Run the application
uv run richpyls

Using pip

# Clone the repository
git clone https://github.com/lpozo/richpyls.git
cd richpyls

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On macOS/Linux
# or
.venv\Scripts\activate     # On Windows

# Install in editable mode
pip install -e .

# Run the application
richpyls

Usage

# List files in current directory
richpyls

# List files in specific directory
richpyls /path/to/directory

# List multiple files/directories
richpyls file1.txt directory1 file2.txt

Command Options

Examples

# Basic listing with Rich icons and colors
richpyls
📄 README.md
⚙️ pyproject.toml
📁 src
📁 tests
📄 uv.lock

# Show hidden files with special emoji
richpyls -a
🫣 .git
🫣 .gitignore
🫣 .python-version
📁 .venv
📄 README.md
⚙️ pyproject.toml
📁 src
📁 tests
📄 uv.lock

# Tree format (shows directory structure with Rich styling)
richpyls -t
├── 📄 README.md
├── ⚙️ pyproject.toml
├── 📁 src
│   └── 📁 richpyls
│       ├── 🐍 __init__.py
│       └── 🐍 __main__.py
├── 📁 tests
│   ├── 🐍 __init__.py
│   └── 🐍 test_richpyls.py
└── 📄 uv.lock

# Tree format with long listing and Rich table
richpyls -tl src
└── drwxr-xr-x  5 user staff     160B Jul 11 18:34 📁 richpyls
    ├── drwxr-xr-x  4 user staff     128B Jul 11 18:34 📁 __pycache__
    │   ├── -rw-r--r--  1 user staff     622B Jul 11 18:34 📄 __init__.cpython-313.pyc
    │   └── -rw-r--r--  1 user staff   14.8KB Jul 11 18:34 📄 __main__.cpython-313.pyc
    ├── -rw-r--r--  1 user staff     452B Jul 11 18:34 🐍 __init__.py
    └── -rw-r--r--  1 user staff   12.1KB Jul 11 18:34 🐍 __main__.py

Technologies

Dependencies

• Python 3.13+: Modern Python with type hints and advanced features
• click: Command-line interface creation toolkit
• rich: Rich text and beautiful formatting for the terminal

Development Dependencies

• pytest: Testing framework for comprehensive test coverage
• mypy: Static type checker for Python
• ruff: Fast Python linter and formatter
• bandit: Security vulnerability scanner
• pre-commit: Git hooks for automated quality checks
• uv: Fast Python package manager and resolver

Build & Deployment

Development & Contributing

Contributions are welcome! Here's how you can set up the development environment and contribute:

Setup

1. Fork the repository or clone directly:

   git clone https://github.com/lpozo/richpyls.git
   cd richpyls
   

2. Reproduce the development environment:

   uv sync --dev
   

3. Set up pre-commit hooks for code quality:

   uv run pre-commit install
   

Running Tests

# Run all tests
uv run python -m pytest

# Run tests with verbose output
uv run python -m pytest -v

# Run tests with coverage
uv run python -m pytest --cov=richpyls

Type Checking

# Check types with mypy
uv run mypy src/richpyls/

# Check all Python files
uv run mypy .

Code Quality and Formatting

The project uses automated code quality tools:

# Format code with ruff
uv run ruff format .

# Lint code with ruff
uv run ruff check . --fix

# Security scan with bandit
uv run bandit -r src/

Pre-commit hooks automatically run quality checks on every commit.

Contributing Workflow

1. Create a feature branch: git checkout -b feature/amazing-feature

2. Make your changes: Implement your feature or bug fix

3. Add tests: Ensure your changes are well-tested

4. Run quality checks:

   uv run python -m pytest          # Run tests
   uv run mypy src/richpyls/        # Type check
   uv run ruff format .             # Format code
   uv run ruff check .              # Lint code
   

5. Commit your changes: git commit -m 'Add amazing feature'

6. Push to the branch: git push origin feature/amazing-feature

7. Open a Pull Request

Development Guidelines

• Follow PEP 8 style guidelines
• Add type hints to all new code
• Write tests for new functionality
• Update documentation as needed
• Ensure all tests pass before submitting

Project Standards

The project maintains high code quality through:

• Type annotations: All functions and variables are type-annotated
• Comprehensive tests: Excellent test coverage with edge cases
• Clean architecture: Well-organized code with clear separation of concerns
• Modern Python: Uses latest Python features and best practices
• Rich UI: Beautiful terminal output with colors, icons, and professional formatting

Build & Publishing

For information about building and publishing the package, see BUILD_PUBLISHING.md.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Author

Leodanis Pozo Ramos

• GitHub: @lpozo

⭐ If you found this project helpful, please give it a star!

Acknowledgments

• Inspired by the Unix ls command
• Built with modern Python best practices
• Thanks to the Python community for excellent tools and libraries
• Special thanks to the Rich library for beautiful terminal output
• Development assisted by GitHub Copilot Chat for enhanced productivity