110 lines
4 KiB
Markdown
110 lines
4 KiB
Markdown
# Technical Context: hosts
|
|
|
|
## Technologies Used
|
|
|
|
### Core Technologies
|
|
- **Python 3.13+**: Modern Python with latest features and performance improvements
|
|
- **Textual**: Rich TUI framework for building terminal applications with modern UI components
|
|
- **uv**: Fast Python package manager and runtime for dependency management and execution
|
|
|
|
### Development Tools
|
|
- **ruff**: Lightning-fast Python linter and formatter for code quality
|
|
- **pytest**: Testing framework for comprehensive test coverage
|
|
- **textual.testing**: Built-in testing utilities for TUI components
|
|
|
|
## Development Setup
|
|
|
|
### Project Structure
|
|
```
|
|
hosts/
|
|
├── pyproject.toml # uv-managed project configuration
|
|
├── README.md
|
|
├── main.py # Current entry point (temporary)
|
|
├── src/hosts/ # Main package (planned)
|
|
│ ├── __init__.py
|
|
│ ├── main.py # Application entry point
|
|
│ ├── tui/ # UI components
|
|
│ ├── core/ # Business logic
|
|
│ └── utils.py
|
|
└── tests/ # Test suite
|
|
```
|
|
|
|
### Current State
|
|
- Basic uv project initialized with Python 3.13
|
|
- Minimal main.py with placeholder implementation
|
|
- ruff configured as dependency for code quality
|
|
- Project structure planned but not yet implemented
|
|
|
|
### Runtime Management
|
|
- **uv run hosts**: Planned command to execute the application
|
|
- **uv**: Handles all dependency management and virtual environment
|
|
- **Python 3.13**: Required minimum version for modern features
|
|
|
|
## Technical Constraints
|
|
|
|
### System Integration
|
|
- **Root access required**: Must handle `/etc/hosts` file modifications
|
|
- **Sudo permission management**: Request permissions only in edit mode
|
|
- **File integrity**: Must preserve existing hosts file structure and comments
|
|
- **Cross-platform compatibility**: Focus on Unix-like systems (Linux, macOS)
|
|
|
|
### Performance Requirements
|
|
- **Fast startup**: TUI should load quickly even with large hosts files
|
|
- **Responsive UI**: No blocking operations in the main UI thread
|
|
- **Memory efficient**: Handle large hosts files without excessive memory usage
|
|
|
|
### Security Considerations
|
|
- **Privilege escalation**: Only request sudo when entering edit mode
|
|
- **Input validation**: Validate all IP addresses and hostnames before writing
|
|
- **Backup strategy**: Consider creating backups before modifications
|
|
- **Permission dropping**: Release sudo permissions when exiting edit mode
|
|
|
|
## Dependencies
|
|
|
|
### Current Dependencies
|
|
```toml
|
|
[project]
|
|
requires-python = ">=3.13"
|
|
dependencies = [
|
|
"ruff>=0.12.5",
|
|
]
|
|
```
|
|
|
|
### Planned Dependencies
|
|
- **textual**: TUI framework (to be added)
|
|
- **pytest**: Testing framework (to be added)
|
|
- **ipaddress**: Built-in Python module for IP validation
|
|
- **socket**: Built-in Python module for DNS resolution
|
|
|
|
## Tool Usage Patterns
|
|
|
|
### Development Workflow
|
|
1. **uv run**: Execute the application during development
|
|
2. **ruff check**: Lint code for style and potential issues
|
|
3. **ruff format**: Auto-format code to maintain consistency
|
|
4. **pytest**: Run test suite for validation
|
|
5. **uv add**: Add new dependencies as needed
|
|
|
|
### Code Quality
|
|
- **ruff configuration**: Enforce consistent Python style
|
|
- **Type hints**: Use modern Python typing for better code clarity
|
|
- **Docstrings**: Document all public APIs and complex logic
|
|
- **Test coverage**: Aim for high coverage on core business logic
|
|
|
|
## Architecture Decisions
|
|
|
|
### Separation of Concerns
|
|
- **TUI layer**: Handle user interface and input/output
|
|
- **Core layer**: Business logic for hosts file management
|
|
- **Utils layer**: Shared utilities and helper functions
|
|
|
|
### Error Handling
|
|
- **Graceful degradation**: Handle missing permissions or file access issues
|
|
- **User feedback**: Clear error messages in the TUI
|
|
- **Recovery mechanisms**: Allow users to retry failed operations
|
|
|
|
### Testing Strategy
|
|
- **Unit tests**: Test core logic in isolation
|
|
- **Integration tests**: Test TUI components with mocked file system
|
|
- **Snapshot testing**: Verify TUI rendering consistency
|
|
- **Mock external dependencies**: DNS resolution and file I/O
|