pydhcpcdparser

Parse, inspect, edit, validate, and render dhcpcd.conf files with lossless round-tripping.

pydhcpcdparser is a pure-Python library. It does not configure network interfaces or invoke dhcpcd.

Table of Contents

• pydhcpcdparser
  • Table of Contents
  • Features
  • Installation
  • Quick Start
    • Parse and Inspect
    • Create From Scratch
  • Major Functionality Blocks
    • Parsing and Rendering
    • Scope Access
    • Query API
    • Editor API
    • File I/O
    • Validation
    • Effective Configuration
  • Error Handling
  • Examples
  • API Reference
  • Development
  • Release
  • Upstream Reference
  • License

Features

• Lossless round-trip — comments, blank lines, indentation, unknown directives, and duplicate entries are preserved byte-for-byte
• Minimal-diff editing — only the changed directive is rewritten; everything else stays identical
• Scope-aware queries — interface, ssid, and profile blocks follow upstream dhcpcd semantics
• Unknown-directive preservation — forward-compatible with future dhcpcd options
• Separate validation — parsing never fails on unknown content; validation reports diagnostics
• Effective configuration — compute which directives apply for a given interface/ssid/profile
• Zero runtime dependencies — pure Python, works on 3.9+
• Fully typed — ships py.typed with complete type annotations

Installation

pip install pydhcpcdparser

Quick Start

Parse and Inspect

from pydhcpcdparser import parse

source = open("/etc/dhcpcd.conf").read()
doc = parse(source)

# Round-trip: unmodified render matches the original byte-for-byte
assert doc.render() == source

# Inspect interfaces
for name in doc.interfaces():
    print(name)

eth0 = doc.interface("eth0")
print(eth0.static("ip_address"))   # "192.168.1.17/32"
print(eth0.static("routers"))      # "192.168.1.1"

# Edit with minimal diff — only the changed line is rewritten
eth0.set_static("ip_address", "192.168.1.20/24")
doc.write_atomic("/etc/dhcpcd.conf")

Create From Scratch

from pydhcpcdparser import Document

doc = Document()
doc.add_directive("hostname")
doc.add_directive("clientid")
doc.add_blank()

eth0 = doc.add_interface("eth0")
eth0.add_directive("nogateway")
eth0.set_static("ip_address", "192.168.1.17/32")
eth0.set_static("routers", "192.168.1.1")
eth0.set_static("domain_name_servers", "8.8.8.8 8.8.4.4")

print(doc.render())

Major Functionality Blocks

• Parsing with lossless AST and scope derivation:
  • Lexer following upstream get_line() semantics (comment detection, quoting, escaping).
  • Flat ordered AST with scope blocks derived from interface, ssid, profile directives.
• Query and inspection:
  • Document-wide and scope-scoped find, find_all, static, static_all queries.
  • Interface/profile/ssid listing, physical blocks vs logical views.
• Minimal-diff editing:
  • set, remove, replace_first, replace_all, set_static, remove_static.
  • Only modified nodes are rewritten; unmodified nodes preserve original raw text.
• Validation and effective configuration:
  • Directive registry with ~90 known directives and argument requirements.
  • validate() returns diagnostics without modifying the document.
  • effective_config() approximates upstream read_config() directive selection.

Parsing and Rendering

Scope Access

Query API

Editor API

File I/O

Validation

from pydhcpcdparser import parse, validate

doc = parse("interface\nfuture_thing value\nnogateway\nnogateway\n")
for d in validate(doc):
    print(d)
# error: line 1: "interface" requires a value
# warning: line 2: Unknown dhcpcd directive "future_thing"
# warning: line 4: Multiple values found for "nogateway" ...

Diagnostic codes: missing-value, unknown-directive, duplicate-singleton.

Effective Configuration

eff = doc.effective_config(interface="eth0")
eff = doc.effective_config(interface="eth0", ssid="Office WiFi")
eff = doc.effective_config(profile="static_eth0")

eff.find("metric")
eff.static("ip_address")
eff.static_all("routes")

Error Handling

from pydhcpcdparser import (
    parse,
    DhcpcdParseError,
    ScopeNotFoundError,
)

# Strict parsing
try:
    doc = parse('env val="unterminated', strict=True)
except DhcpcdParseError:
    print("Malformed syntax")

# Missing scope
try:
    eth0 = doc.interface("eth99")
except ScopeNotFoundError:
    print("Interface not found")

All library errors inherit from DhcpcdParserError:

• DhcpcdParseError — malformed syntax in strict mode
• DhcpcdValidationError — validation failures
• ScopeNotFoundError — requested scope does not exist
• AmbiguousScopeError — ambiguous scope reference

Examples

See EXAMPLES.md for:

• parsing, inspection, and round-trip examples
• minimal-diff editing workflows
• creating configurations from scratch
• profile fallback patterns
• validation and effective configuration usage

API Reference

For the complete public surface inventory, see API.md:

• all public functions
• all public classes and methods
• all AST node types
• all error classes

Development

# Show available targets
make help

# Create local virtual environment and install dependencies
make venv

# Run tests in Docker
make test

# Lint and type-check in Docker
make lint
make typecheck

# Run all checks (lint, typecheck, docs, security, tests)
make check

# Format code
make format

# Remove local virtual environment
make venv-clean

Release

GitHub Actions workflow in .github/workflows/release.yml handles package publishing via PyPI trusted publisher.

One-time setup:

• Configure a Trusted Publisher in PyPI for .github/workflows/release.yml.

Release flow:

# Tag a release (must match version in pyproject.toml)
git tag v0.1.0
git push origin v0.1.0

The release workflow validates that the tag version matches the package version in pyproject.toml, builds distributions, creates a GitHub Release with auto-generated notes, and publishes to PyPI.

Upstream Reference

Parser behavior is verified against NetworkConfiguration/dhcpcd at commit 5a91691c65f063551553116ca73f2163ad951c9c.

See docs/upstream-compatibility.md for detailed behavioral notes.

License

MIT License - see LICENSE for details.