pyhosts

Manage system hosts files (/etc/hosts) the Pythonic way.

• Platform independent — Linux, macOS, Windows
• Zero dependencies — uses Python standard library only
• Type-safe — full type hints, py.typed, strict mypy
• Immutable models — frozen dataclasses for safety
• List-like API — implements MutableSequence protocol
• Lazy loading — file is read only when accessed

Installation

pip install pyhosts

Quick Start

from pyhosts import Hosts

# Load the system hosts file
hosts = Hosts()

# Iterate over entries
for host in hosts:
    print(f"{host.ip_address}  {host.hostname}")

# Attribute-style access
localhost = hosts.localhost
print(localhost.ip_address)  # IPv4Address('127.0.0.1')

# Check membership
if "localhost" in hosts:
    print("found!")

Usage

Search

# Find all entries matching IP, hostname, or alias
results = hosts.find("192.168.1.1")
results = hosts.find("localhost")

# Find first match
host = hosts.find_one("localhost")

Add and Remove

from pyhosts import Host
from ipaddress import ip_address

# Create a new entry
entry = Host(
    ip_address=ip_address("192.168.1.100"),
    hostname="myserver",
    aliases=("server", "web"),
    comment="Production server",
)

# Add it
hosts.add(entry)

# Remove by query
count = hosts.remove("myserver")

Save

# Save changes to disk
hosts.save()

# Save with automatic backup
hosts.save(backup=True)

List-style Access

# Index, slice, len, in — it's a MutableSequence
first = hosts[0]
total = len(hosts)
hosts[0] = new_entry
del hosts[2]

API Reference

Hosts

The main class for managing the hosts file.

Supports full MutableSequence interface: indexing, slicing, iteration, len(), in, del.

Note: Hosts is not thread-safe. Use external synchronisation (e.g. threading.Lock) when sharing an instance across threads.

Host

Immutable (frozen) dataclass representing a single hosts file entry.

Exceptions

Requirements

• Python 3.10+
• No external dependencies

Development

# Clone and install
git clone https://github.com/igormilovanovic/pyhosts.git
cd pyhosts
pip install -e .
pip install -r test-requirements.txt

# Run tests
pytest test/ -v

# Run tests with coverage
pytest test/ -v --cov=pyhosts

# Lint
pycodestyle pyhosts/ --max-line-length=120

License

MIT