|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Development Commands |
| 6 | + |
| 7 | +### Testing |
| 8 | +- `python3 -m pytest -vv --cov=python_hosts --cov-report=term-missing --cov-report=xml --cov-report=html --cov-fail-under=90 --cov-branch --junitxml=pytest.xml` - Run tests with coverage (90% minimum) |
| 9 | +- `make test` - Alternative test command (note: currently has incorrect --cov=ipq flag, should be --cov=python_hosts) |
| 10 | +- `python setup.py test` - Legacy test runner using pytest |
| 11 | + |
| 12 | +### Code Quality |
| 13 | +- `ruff check . --ignore E501,F401` - Run linting (ignores line length and unused imports) |
| 14 | +- `make lint` - Alternative lint command |
| 15 | + |
| 16 | +### Environment Setup |
| 17 | +- `python3 -m pip install -r test-requirements.txt` - Install test dependencies |
| 18 | +- `make setup` - Setup development environment |
| 19 | + |
| 20 | +### Build and Distribution |
| 21 | +- `python setup.py sdist` - Build source distribution |
| 22 | +- `make build-docker` - Build Docker image |
| 23 | +- `tox` - Run tests across multiple Python versions (2.7, 3.8-3.11) |
| 24 | + |
| 25 | +### Documentation |
| 26 | +- `cd docs && make html` - Build HTML documentation with Sphinx |
| 27 | +- `cd docs && make clean` - Clean documentation build files |
| 28 | +- `cd docs && make linkcheck` - Check documentation links |
| 29 | +- `cd docs && make coverage` - Generate documentation coverage report |
| 30 | +- Documentation output in `docs/_build/html/` |
| 31 | + |
| 32 | +## Architecture |
| 33 | + |
| 34 | +This is a Python library for managing hosts files (`/etc/hosts` on Unix, `C:\Windows\System32\drivers\etc\hosts` on Windows). |
| 35 | + |
| 36 | +### Core Classes |
| 37 | + |
| 38 | +**`HostsEntry`** (`python_hosts/hosts.py`): |
| 39 | +- Represents a single line in a hosts file |
| 40 | +- Entry types: `ipv4`, `ipv6`, `comment`, `blank` |
| 41 | +- Main attributes: `entry_type`, `address`, `comment`, `names` |
| 42 | +- Uses `__slots__` for memory efficiency |
| 43 | + |
| 44 | +**`Hosts`** (`python_hosts/hosts.py`): |
| 45 | +- Represents an entire hosts file |
| 46 | +- Manages collections of `HostsEntry` objects |
| 47 | +- Supports reading from file paths or URLs |
| 48 | +- Provides methods for adding, removing, and writing entries |
| 49 | + |
| 50 | +### Key Features |
| 51 | +- Import entries from files or URLs (e.g., `hosts.import_url()`) |
| 52 | +- Add/remove individual entries or batches |
| 53 | +- Validate IPv4/IPv6 addresses and hostnames |
| 54 | +- Handle comments and blank lines |
| 55 | +- Support for duplicate name detection with `allow_name_dupliction` parameter |
| 56 | + |
| 57 | +### Module Structure |
| 58 | +- `python_hosts/hosts.py` - Main classes (`Hosts`, `HostsEntry`) |
| 59 | +- `python_hosts/utils.py` - Utility functions for validation (`is_ipv4`, `is_ipv6`, `valid_hostnames`) |
| 60 | +- `python_hosts/exception.py` - Custom exceptions (`HostsException`, `InvalidIPv4Address`, etc.) |
| 61 | +- `python_hosts/__init__.py` - Package exports |
| 62 | + |
| 63 | +### Testing |
| 64 | +- Tests use `pytest` with `tmpdir` fixture for temporary file creation |
| 65 | +- Test files located in `tests/` directory |
| 66 | +- Sample hosts files in `test_files/` for testing various formats |
| 67 | +- Coverage reporting configured for 90% minimum coverage |
0 commit comments