phg/hosts
0
0
Fork 0
Code Issues 3 Pull requests Projects Releases Packages Wiki Activity Actions
hosts/README.md

8 KiB
Raw Blame History

hosts - /etc/hosts Manager

A modern Python TUI (Text User Interface) application for managing your system's /etc/hosts file with ease and safety.

Overview

The hosts application provides a powerful, user-friendly terminal interface for viewing, editing, and managing your /etc/hosts file. It eliminates the need for manual text editing while providing advanced features like DNS resolution, entry validation, and comprehensive backup capabilities.

Features

🔍 Read-Only Mode (Default)

  • Two-pane interface: List view with detailed entry information
  • Smart parsing: Handles all real-world hosts file formats
  • Sorting capabilities: Sort by IP address or hostname
  • Filtering options: Hide/show system default entries
  • Search functionality: Find entries by hostname, IP, or comment
  • Configuration management: Persistent settings with modal interface
  • Live reload: Automatically refresh when hosts file changes

✏️ Edit Mode (Permission-Protected)

  • Safe editing: Automatic backups before any modifications
  • Entry management: Add, delete, and modify host entries
  • Activation control: Toggle entries active/inactive
  • Reordering: Move entries up/down with keyboard shortcuts
  • Undo/Redo system: Full operation history with Ctrl+Z/Ctrl+Y
  • Atomic operations: Safe file writing with rollback capability
  • Permission management: Secure sudo handling for system file access

🛡️ Safety & Reliability

  • Automatic backups: Timestamped backups before modifications
  • Change detection: Track modifications with save confirmation
  • Input validation: Comprehensive IP and hostname validation
  • Error handling: Graceful error recovery with user feedback
  • File integrity: Preserve comments and formatting

Installation

Prerequisites

  • Python 3.13 or higher
  • uv package manager

Run with uv

uvx git+https://git.s1q.dev/phg/hosts.git

Setup alias

# Install uv if not already installed
echo "alias hosts=\"uvx git+https://git.s1q.dev/phg/hosts.git\"" >> ~/.zshrc

Usage

Basic Usage

# Launch the application
uv run hosts

# Or if installed globally
hosts

Interface Overview

User Interface

Keyboard Shortcuts

Navigation

  • ↑/↓: Navigate entries
  • Home/End: Go to first/last entry
  • Page Up/Down: Navigate by page

View Operations

  • Ctrl+e: Toggle between Read-only and Edit mode
  • Ctrl+r: Reload hosts file
  • i: Sort by IP address
  • h: Sort by hostname
  • c: Open configuration modal
  • q or Ctrl+C: Quit application

Edit Mode (requires sudo)

  • e: Toggle Entry edit mode
  • Space: Toggle entry active/inactive
  • Shift+↑/↓: Move entry up/down
  • n: Add new entry
  • d: Delete selected entry
  • r: Update the current select DNS based Entry
  • Shift+r: Update all DNS based Entries
  • Ctrl+z: Undo last operation
  • Ctrl+y: Redo operation
  • Ctrl+s: Save changes

Configuration

The application stores its configuration in ~/.config/hosts-manager/config.json:

{
  "show_default_entries": true,
  "default_sort_column": "ip",
  "default_sort_reverse": false,
  "backup_directory": "~/.config/hosts-manager/backups"
}

Configuration Options

  • show_default_entries: Show/hide system default entries (localhost, etc.)
  • default_sort_column: Default sorting column ("ip" or "hostname")
  • default_sort_reverse: Default sort direction
  • backup_directory: Location for automatic backups

Architecture

The application follows a clean, layered architecture:

src/hosts/
├── main.py              # Application entry point
├── core/                # Business logic layer
│   ├── models.py        # Data models (HostEntry, HostsFile)
│   ├── parser.py        # File parsing and writing
│   ├── manager.py       # Edit operations and permissions
│   ├── config.py        # Configuration management
│   ├── dns.py           # DNS resolution (planned)
│   ├── commands.py      # Command pattern for undo/redo
│   ├── filters.py       # Entry filtering and search
│   └── import_export.py # Data import/export utilities
└── tui/                 # User interface layer
    ├── app.py           # Main TUI application
    ├── styles.py        # Visual styling
    ├── keybindings.py   # Keyboard shortcuts
    └── *.py             # Modal dialogs and components

Key Components

  • HostEntry: Immutable data class representing a single hosts entry
  • HostsFile: Container managing collections of entries with operations
  • HostsParser: File I/O operations with atomic writing and backup
  • HostsManager: Edit mode operations with permission management
  • HostsManagerApp: Main TUI application with Textual framework

Development

Setup Development Environment

# Clone and enter directory
git clone https://github.com/yourusername/hosts.git
cd hosts

# Install development dependencies
uv sync

# Run tests
uv run pytest

# Run linting
uv run ruff check
uv run ruff format

Testing

The project maintains comprehensive test coverage with 150+ tests:

# Run all tests
uv run pytest

# Run specific test modules
uv run pytest tests/test_models.py
uv run pytest tests/test_parser.py

# Run with coverage
uv run pytest --cov=src/hosts

Test Coverage

  • Models: Data validation and serialization (27 tests)
  • Parser: File operations and parsing (15 tests)
  • Manager: Edit operations and permissions (38 tests)
  • Configuration: Settings persistence (22 tests)
  • TUI Components: User interface (28 tests)
  • Commands: Undo/redo system (43 tests)
  • Integration: End-to-end workflows (additional tests)

Code Quality

The project uses ruff for linting and formatting:

# Check code quality
uv run ruff check

# Format code
uv run ruff format

# Fix auto-fixable issues
uv run ruff check --fix

Security Considerations

  • Sudo handling: Secure elevation only when entering edit mode
  • File validation: Comprehensive input validation and sanitization
  • Atomic operations: Safe file writing to prevent corruption
  • Backup system: Automatic backups before any modifications
  • Permission boundaries: Clear separation between read and edit operations

Troubleshooting

Common Issues

Permission denied when entering edit mode:

# Ensure you can run sudo
sudo -v

# Check file permissions
ls -la /etc/hosts

Configuration not saving:

# Ensure config directory exists
mkdir -p ~/.config/hosts-manager

# Check directory permissions
ls -la ~/.config/

Application won't start:

# Check Python version
python3 --version

# Verify uv installation
uv --version

# Install dependencies
uv sync

Contributing

We welcome contributions! Please see our development setup above.

Contribution Guidelines

  1. Fork the repository and create a feature branch
  2. Write tests for new functionality
  3. Ensure all tests pass with uv run pytest
  4. Follow code style with uv run ruff check
  5. Submit a pull request with clear description

Future Enhancements

  • DNS Resolution: Automatic hostname-to-IP resolution
  • Import/Export: Support for different file formats
  • Advanced Filtering: Complex search and filter capabilities
  • Performance Optimization: Large file handling improvements

License

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

Support

  • Issues: Report bugs and feature requests on GitHub Issues
  • Documentation: See the project wiki
  • Discussions: Join community discussions on GitHub Discussions

Note: This application modifies system files. Always ensure you have proper backups and understand the implications of hosts file changes. The application includes safety features, but system administration knowledge is recommended.