Add user interface screenshot to documentation
This commit is contained in:
parent
6bfd9c77e4
commit
b4a4cbec0d
2 changed files with 277 additions and 0 deletions
277
README.md
277
README.md
|
|
@ -0,0 +1,277 @@
|
|||
# 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](https://docs.astral.sh/uv/) package manager
|
||||
|
||||
### Run with uv
|
||||
```bash
|
||||
uvx git+https://git.s1q.dev/phg/hosts.git
|
||||
```
|
||||
|
||||
### Setup alias
|
||||
```bash
|
||||
# Install uv if not already installed
|
||||
echo "alias hosts=\"uvx git+https://git.s1q.dev/phg/hosts.git\"" >> ~/.zshrc
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Usage
|
||||
```bash
|
||||
# Launch the application
|
||||
uv run hosts
|
||||
|
||||
# Or if installed globally
|
||||
hosts
|
||||
```
|
||||
|
||||
### Interface Overview
|
||||
|
||||
|
||||
|
||||
### 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`:
|
||||
|
||||
```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
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# Ensure you can run sudo
|
||||
sudo -v
|
||||
|
||||
# Check file permissions
|
||||
ls -la /etc/hosts
|
||||
```
|
||||
|
||||
**Configuration not saving:**
|
||||
```bash
|
||||
# Ensure config directory exists
|
||||
mkdir -p ~/.config/hosts-manager
|
||||
|
||||
# Check directory permissions
|
||||
ls -la ~/.config/
|
||||
```
|
||||
|
||||
**Application won't start:**
|
||||
```bash
|
||||
# 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](https://github.com/yourusername/hosts/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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue