pydhcp 0.2.1rc1__tar.gz

pydhcp-0.2.1rc1/.gitignore

@@ -0,0 +1,20 @@
+# Build/dist output and generated docs site
+dist/
+build/
+site/
+
+# Agent/harness tooling
+AGENTS.md
+.agents/
+CLAUDE.md
+CLAUDE.local.md
+.claude/
+
+# Python-specific patterns
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+.venv/

pydhcp-0.2.1rc1/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.1-rc.1] - 2026-07-12
+
+### Added
+- Expanded DHCP option-type registrations so common well-defined options decode to typed values.
+- Added a "Common DHCP Options" docs page with typed examples and updated the custom-options example to prefer typed assignment.
+- Added stricter option-type validation and `ClasslessRoute` truncation checks.
+- Added wildcard listener `per_interface` support and exported `PktInfoUdpTransport`.
+- Added typed codecs and registrations for policy filters, static routes, user classes, encapsulated vendor/relay sub-options, name service search, subnet selection, and RDNSS selection.
+
+### Fixed
+- Made `DhcpMessage.encode()` idempotent and tolerant of reserved flag bits during decode.
+- Corrected `DhcpMessage.dumps()` field labels and `secs` packing behavior.
+
+## [0.2.0] - 2026-07-12
+
+### Added
+- Created `benchmarks/bench_parse.py` packet parsing and serialization performance benchmarks.
+- Added `benchmarks/README.md` documenting performance baselines.
+- Added `AsyncDhcpListener` and `AsyncDhcpServer` classes implementing asyncio-based event loop integration.
+- Added integration tests for async server in `tests/test_async.py`.
+- Configured MkDocs documentation with Material theme and `mkdocstrings` auto-generated API references.
+- Added `Transport`, `UdpTransport`, and `RequestContext` classes for structured transport-layer abstraction and Interface tracking.
+- Added comprehensive unit testing coverage for packet deserialization and type-safe dictionary operations in `test_message.py` and `test_options.py`.
+- Added integration tests verifying standard client DORA sequences and RFC 2131 routing logic in `tests/integration/test_dora.py`.
+- Added missing `ALL_VPNS` option (Tag 254) to `DhcpOptionCode` after comparing against the latest IANA registry.
+- Populated default `ROUTER` and `DNS` lease options in `DhcpServer.acquire_lease` using the server's interface IP.
+- Added pluggable lease backend API (`LeaseBackend`) and implementations (`InMemoryLeaseBackend`, `FileLeaseBackend`) for state preservation and persistence.
+- Added unit and integration tests for lease backends in `tests/test_lease_backend.py` and `tests/integration/test_dora.py`.
+- Added validation checks for hardware address length (hlen <= 16) during packet decoding.
+- Added socket binding error diagnostics that offer actionable suggestions for permission and address-in-use errors.
+- Added unit tests for binding error handling and malformed packet input in `tests/test_permissions.py` and `tests/test_malformed_packets.py`.
+- Added command-line interface (CLI) with `interfaces`, `server`, `packet`, and `bench` subcommands.
+- Added JSON-based configuration loading support in `config.py`.
+- Added in-process metrics counters (`packets_received`, `packets_sent`, etc.) in `metrics.py` to support observability.
+- Added option parsing and lease allocation performance benchmarks in `benchmarks/bench_options.py`.
+- Added async DHCP server concurrency stress tests under `tests/test_async_concurrency.py`.
+
+### Changed
+- Configured strict typechecking configuration in `pyproject.toml` and resolved all mypy type-checking errors across the library.
+- Refactored `DhcpMessageType` and `OptionOverload` to implement the `DhcpOptionType` interface directly and avoid PEP 561 / type conflicts with `BaseFixedLengthInteger` and Enums.
+- Refactored `DhcpServer.handle` to accept `RequestContext` instead of `SocketSession`, split processing into message-type specific handlers (`handle_discover`, etc.), and comply strictly with RFC 2131 routing paths.
+- Enriched `NetworkInterface` and `host_ip_interfaces()` to yield fully detailed adapter metadata.
+- Refactored `DhcpServer` and `AsyncDhcpServer` to accept and delegate lease lifecycle events (allocate, lookup, renew, release) to a configurable `lease_backend`.
+- Refactored options parsing in `DhcpOptions.decode` to handle truncated option lengths gracefully by logging a warning and parsing remaining bytes instead of crashing.
+- Added debug-level logging for packet arrival and lease allocation including client XIDs.
+- Renamed misspelled `contants.py` to `constants.py` and updated all internal references.
+- Added strict `__all__` public exports list to `src/pydhcp/__init__.py`.
+
+### Fixed
+- Fixed bug in `ClasslessRoute` destination descriptor parsing/serialization that caused incorrect length calculations for CIDR/8.
+- Fixed forward reference type resolution issue for `DhcpOption` in `_options.py`.
+- Fixed options encoding `OverflowError` when option size limit is infinite.
+- Fixed `BaseDhcpOptionCode.__int__` returning constant zero, correcting enum integer conversion for option codes.
+
+## [0.1.0] - 2026-07-11
+
+### Added
+
+- Initial release.
+
+[0.2.0]: https://github.com/jose-pr/pydhcp/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/jose-pr/pydhcp/releases/tag/v0.1.0

pydhcp-0.2.1rc1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jose-pr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pydhcp-0.2.1rc1/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: pydhcp
+Version: 0.2.1rc1
+Summary: A Python DHCP library and server implementation
+Project-URL: Homepage, https://github.com/jose-pr/pydhcp/
+Project-URL: Documentation, https://jose-pr.github.io/pydhcp/
+Project-URL: Issues, https://github.com/jose-pr/pydhcp/issues
+Author: jose-pr
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pip-audit; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# pydhcp
+
+[![Version](https://img.shields.io/pypi/v/pydhcp.svg)](https://pypi.org/project/pydhcp/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pydhcp.svg)](https://pypi.org/project/pydhcp/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/pydhcp/)
+
+A Python DHCP library and server implementation.
+
+## Features
+
+- **DHCP Packet Parsing** — Full support for parsing and constructing DHCP packets.
+- **DHCP Server** — Highly customizable and async-friendly DHCP server.
+
+## Installation
+
+```bash
+pip install pydhcp
+```
+
+## Quick start
+
+### Synchronous Server
+```python
+from pydhcp.server import DhcpServer
+
+server = DhcpServer()
+server.listen()
+```
+
+### Asynchronous Server
+```python
+import asyncio
+from pydhcp.server import AsyncDhcpServer
+
+async def main():
+    server = AsyncDhcpServer()
+    await server.start()
+    # Keep running or handle other async tasks
+    # To stop: await server.stop()
+
+asyncio.run(main())
+```
+
+## Command Line Interface (CLI)
+
+`pydhcp` includes a command line interface for listing network adapters, decoding packets, running benchmarks, and starting servers.
+
+```bash
+# List all network interfaces
+pydhcp interfaces
+
+# Decode a hex-encoded DHCP packet
+pydhcp packet --decode "01010600..."
+
+# Run performance benchmarks
+pydhcp bench
+
+# Start the DHCP server from JSON or INI config
+pydhcp server --config config.json
+
+# Increase logging while debugging
+pydhcp server --listen 127.0.0.1:6767 --log-level debug
+```
+
+## Development
+
+See development notes for environment setup, dependency install, and test commands.
+
+### Releasing
+
+This project follows [Semantic Versioning](https://semver.org/) and keeps a
+[`CHANGELOG.md`](CHANGELOG.md). Pushing a tag matching `v*` triggers the release
+workflow.
+
+### Documentation site
+
+MkDocs builds the API reference from `docs/`, published on every release. The docs also include a "Common DHCP Options" page with typed examples.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pydhcp-0.2.1rc1/README.md

@@ -0,0 +1,82 @@
+# pydhcp
+
+[![Version](https://img.shields.io/pypi/v/pydhcp.svg)](https://pypi.org/project/pydhcp/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pydhcp.svg)](https://pypi.org/project/pydhcp/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/pydhcp/)
+
+A Python DHCP library and server implementation.
+
+## Features
+
+- **DHCP Packet Parsing** — Full support for parsing and constructing DHCP packets.
+- **DHCP Server** — Highly customizable and async-friendly DHCP server.
+
+## Installation
+
+```bash
+pip install pydhcp
+```
+
+## Quick start
+
+### Synchronous Server
+```python
+from pydhcp.server import DhcpServer
+
+server = DhcpServer()
+server.listen()
+```
+
+### Asynchronous Server
+```python
+import asyncio
+from pydhcp.server import AsyncDhcpServer
+
+async def main():
+    server = AsyncDhcpServer()
+    await server.start()
+    # Keep running or handle other async tasks
+    # To stop: await server.stop()
+
+asyncio.run(main())
+```
+
+## Command Line Interface (CLI)
+
+`pydhcp` includes a command line interface for listing network adapters, decoding packets, running benchmarks, and starting servers.
+
+```bash
+# List all network interfaces
+pydhcp interfaces
+
+# Decode a hex-encoded DHCP packet
+pydhcp packet --decode "01010600..."
+
+# Run performance benchmarks
+pydhcp bench
+
+# Start the DHCP server from JSON or INI config
+pydhcp server --config config.json
+
+# Increase logging while debugging
+pydhcp server --listen 127.0.0.1:6767 --log-level debug
+```
+
+## Development
+
+See development notes for environment setup, dependency install, and test commands.
+
+### Releasing
+
+This project follows [Semantic Versioning](https://semver.org/) and keeps a
+[`CHANGELOG.md`](CHANGELOG.md). Pushing a tag matching `v*` triggers the release
+workflow.
+
+### Documentation site
+
+MkDocs builds the API reference from `docs/`, published on every release. The docs also include a "Common DHCP Options" page with typed examples.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pydhcp-0.2.1rc1/benchmarks/README.md

@@ -0,0 +1,25 @@
+# DHCP Library Performance Benchmarks
+
+This directory contains the benchmarks for measuring the serialization and deserialization performance of the `pydhcp` library.
+
+## Benchmarks
+
+### 1. Packet Parsing & Serialization (`benchmarks/bench_parse.py`)
+Measures the operations per second (ops/sec) and total duration for 10,000 iterations of:
+- **Decode**: Deserializing a typical `DHCPDISCOVER` packet payload into a `DhcpMessage` object.
+- **Encode**: Serializing a constructed `DhcpMessage` object back into raw bytes.
+
+#### Running the Benchmark
+From the repository root directory, run:
+```bash
+python benchmarks/bench_parse.py
+```
+
+## Performance Baseline
+
+The baseline measurements taken on a Windows development machine (Python 3.12) are as follows:
+
+| Operation | Total Time (10k iterations) | Throughput (ops/sec) |
+|---|---|---|
+| **Decode** (Deserialization) | ~0.11s | ~92,600 ops/sec |
+| **Encode** (Serialization) | ~0.08s | ~120,800 ops/sec |

pydhcp-0.2.1rc1/benchmarks/bench_options.py

@@ -0,0 +1,58 @@
+import timeit
+import sys
+import pathlib
+
+# Ensure src/ is in the import path
+SRC_DIR = pathlib.Path(__file__).parent.parent / "src"
+sys.path.insert(0, SRC_DIR.as_posix())
+
+from pydhcp.options import DhcpOptions
+from pydhcp.enum import DhcpOptionCode
+from pydhcp.netutils import IPv4
+from pydhcp.lease import InMemoryLeaseBackend
+
+def build_options_payload(option_count: int) -> bytearray:
+    opts = DhcpOptions()
+    for i in range(1, option_count + 1):
+        opts[i] = bytearray([192, 168, 1, i])
+    return opts.encode()
+
+def test_memory_usage():
+    backend = InMemoryLeaseBackend()
+    options = DhcpOptions()
+    for i in range(1000):
+        client_id = f"client-{i}"
+        ip = IPv4("192.168.1.1")
+        backend.allocate(client_id, ip, 3600, options)
+
+def run_benchmarks(iterations: int = 10000):
+    print(f"--- Running DHCP Options & Memory Benchmarks ({iterations:,} iterations) ---")
+    
+    p0 = memoryview(build_options_payload(0))
+    p5 = memoryview(build_options_payload(5))
+    p20 = memoryview(build_options_payload(20))
+    
+    t0 = timeit.timeit(lambda: DhcpOptions().decode(p0), number=iterations)
+    t5 = timeit.timeit(lambda: DhcpOptions().decode(p5), number=iterations)
+    t20 = timeit.timeit(lambda: DhcpOptions().decode(p20), number=iterations)
+    
+    print(f"Decode with 0 options:  {t0:.4f}s ({iterations/t0:.1f} ops/sec)")
+    print(f"Decode with 5 options:  {t5:.4f}s ({iterations/t5:.1f} ops/sec)")
+    print(f"Decode with 20 options: {t20:.4f}s ({iterations/t20:.1f} ops/sec)")
+    
+    opts = DhcpOptions()
+    opts[DhcpOptionCode.SUBNET_MASK] = IPv4("255.255.255.0")
+    
+    def round_trip():
+        encoded = opts.encode()
+        decoded = DhcpOptions()
+        decoded.decode(memoryview(encoded))
+        
+    trt = timeit.timeit(round_trip, number=iterations)
+    print(f"Round-trip encode/decode: {trt:.4f}s ({iterations/trt:.1f} ops/sec)")
+    
+    t_mem = timeit.timeit(test_memory_usage, number=100)
+    print(f"1000 lease allocations (x100 reps): {t_mem:.4f}s ({100/t_mem:.1f} reps/sec)")
+
+if __name__ == "__main__":
+    run_benchmarks()

pydhcp-0.2.1rc1/benchmarks/bench_parse.py

@@ -0,0 +1,77 @@
+import timeit
+import sys
+import pathlib
+from datetime import timedelta
+
+# Ensure src/ is in the import path
+SRC_DIR = pathlib.Path(__file__).parent.parent / "src"
+sys.path.insert(0, SRC_DIR.as_posix())
+
+from pydhcp.message import DhcpMessage
+from pydhcp.enum import OpCode, HardwareAddressType, Flags, DhcpOptionCode, DhcpMessageType
+from pydhcp.netutils import IPv4
+from pydhcp.options import DhcpOptions
+
+def build_benchmark_payload() -> bytes:
+    options = DhcpOptions()
+    options[DhcpOptionCode.DHCP_MESSAGE_TYPE] = bytearray([DhcpMessageType.DHCPDISCOVER.value])
+    options[DhcpOptionCode.CLIENT_IDENTIFIER] = bytearray([1, 0, 17, 34, 51, 68, 85])
+    options[DhcpOptionCode.PARAMETER_REQUEST_LIST] = bytearray([1, 3, 6, 15, 31, 33, 43, 44, 46, 47, 119, 121, 249, 252])
+
+    msg = DhcpMessage(
+        op=OpCode.BOOTREQUEST,
+        htype=HardwareAddressType.ETHERNET,
+        hlen=6,
+        hops=0,
+        xid=0x3903F326,
+        secs=timedelta(seconds=0),
+        flags=Flags.UNICAST,
+        ciaddr=IPv4('0.0.0.0'),
+        yiaddr=IPv4('0.0.0.0'),
+        siaddr=IPv4('0.0.0.0'),
+        giaddr=IPv4('0.0.0.0'),
+        chaddr=b'\x00\x11\x22\x33\x44\x55',
+        sname='',
+        file='',
+        options=options
+    )
+    return bytes(msg.encode())
+
+PAYLOAD_BYTES = build_benchmark_payload()
+
+def run_benchmarks(iterations: int = 10000) -> dict[str, float]:
+    print(f"--- Running DHCP Packet Parsing Benchmarks ({iterations:,} iterations) ---")
+    
+    # 1. Decode Benchmark
+    # We use memoryview(PAYLOAD_BYTES) as is typically done in the listener
+    payload_mv = memoryview(PAYLOAD_BYTES)
+    
+    def test_decode() -> None:
+        DhcpMessage.decode(payload_mv)
+        
+    decode_time = timeit.timeit(test_decode, number=iterations)
+    decode_ops_per_sec = iterations / decode_time
+    print(f"Decode: {decode_time:.4f} seconds ({decode_ops_per_sec:.1f} ops/sec)")
+    
+    # 2. Encode Benchmark
+    msg = DhcpMessage.decode(payload_mv)
+    
+    def test_encode() -> None:
+        msg.encode()
+        
+    encode_time = timeit.timeit(test_encode, number=iterations)
+    encode_ops_per_sec = iterations / encode_time
+    print(f"Encode: {encode_time:.4f} seconds ({encode_ops_per_sec:.1f} ops/sec)")
+    
+    # Return stats for documentation
+    return {
+        "iterations": iterations,
+        "decode_time": decode_time,
+        "decode_ops": decode_ops_per_sec,
+        "encode_time": encode_time,
+        "encode_ops": encode_ops_per_sec,
+    }
+
+
+if __name__ == "__main__":
+    run_benchmarks()

pydhcp-0.2.1rc1/docs/api.md

@@ -0,0 +1,23 @@
+# API Reference
+
+This section provides references for the primary classes in the `pydhcp` package.
+
+## DhcpMessage
+
+::: pydhcp.message.DhcpMessage
+
+## DhcpServer
+
+::: pydhcp.server.DhcpServer
+
+## AsyncDhcpServer
+
+::: pydhcp.server.AsyncDhcpServer
+
+## DhcpListener
+
+::: pydhcp.listener.DhcpListener
+
+## AsyncDhcpListener
+
+::: pydhcp.listener.AsyncDhcpListener

pydhcp-0.2.1rc1/docs/deployment.md

@@ -0,0 +1,45 @@
+# Deployment
+
+`pydhcp` is a pure-Python library, so deployment is mostly about running it with the right permissions and network layout.
+
+## Production checklist
+
+1. Run the server under a dedicated service account.
+2. Make sure the host can bind the DHCP ports you expect to use.
+3. Confirm the selected interface has the address range you want to serve.
+4. Keep lease persistence enabled if you need stable client assignment across restarts.
+
+## systemd
+
+For Linux services, run the server from a unit that starts the CLI entry point directly.
+
+```ini
+[Unit]
+Description=pydhcp server
+After=network-online.target
+
+[Service]
+ExecStart=/opt/pydhcp/.venv/bin/pydhcp server --help
+Restart=on-failure
+User=pydhcp
+Group=pydhcp
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Replace `--help` with the server arguments you actually want in production. The CLI accepts JSON or INI configuration files through `--config`.
+
+## Docker
+
+The server can also run inside a container if the container is allowed to bind the needed UDP ports and see the host network.
+
+- Prefer host networking for real DHCP service.
+- Mount configuration and lease storage explicitly.
+- Keep logs on stdout/stderr so orchestrators can collect them.
+
+## Operational notes
+
+- Use the CLI `interfaces` command to confirm interface detection before serving traffic.
+- If you are debugging packet flow, turn on debug logging and look for the transaction ID in the output.
+- Keep an eye on lease backend state after restarts if you are not using the in-memory backend.

pydhcp-0.2.1rc1/docs/examples.md

@@ -0,0 +1,50 @@
+# Examples
+
+This page collects a few short patterns that are useful when you start wiring `pydhcp` into a real service.
+
+## Custom lease backend
+
+The server accepts a pluggable lease backend. That makes it easy to persist leases in memory for tests and swap in a file-backed store for simple deployments.
+
+```python
+from pydhcp.lease import InMemoryLeaseBackend
+from pydhcp.server import DhcpServer
+
+server = DhcpServer(lease_backend=InMemoryLeaseBackend())
+server.listen()
+```
+
+## Listening on all interfaces
+
+If you want the server to bind every local IPv4 interface, pass `'*'` or `0.0.0.0`.
+You can also force the portable per-interface path with `per_interface=True`.
+
+```python
+from pydhcp.server import DhcpServer
+
+server = DhcpServer(listen="*", per_interface=True)
+server.listen()
+```
+
+## Custom options
+
+`DhcpOptions` behaves like an ordered mapping, so you can build option sets explicitly and preserve encode order.
+
+```python
+from pydhcp import DhcpOptions
+from pydhcp.enum import DhcpOptionCode
+
+options = DhcpOptions()
+options[DhcpOptionCode.HOSTNAME] = "workstation-01"
+options[DhcpOptionCode.DOMAIN_NAME] = "example.internal"
+```
+
+For more typed examples across the built-in option families, see [Common DHCP Options](options.md).
+
+## Inspecting packets
+
+The CLI can decode packets and print their fields, which is handy when you are debugging client behavior or validating captures.
+
+```bash
+pydhcp packet --help
+```

pydhcp-0.2.1rc1/docs/faq.md

@@ -0,0 +1,13 @@
+# FAQ
+
+## Why does the server use a synthetic interface on loopback?
+
+In sandboxed or minimal environments, interface enumeration may not return a matching `NetworkInterface` record for `127.0.0.1`. The server falls back to a synthetic interface so tests and local demos still work.
+
+## Why are some clients sent broadcast replies?
+
+If the server cannot send a direct unicast packet to the requested address, it falls back to broadcast delivery. That keeps local development usable even when the requested lease address is not reachable from the host network.
+
+## Why are the docs split into several short pages?
+
+The project has a few different operational concerns now: API reference, examples, deployment, and troubleshooting. Keeping them separate makes it easier to find the right piece without scrolling through a giant wall of text.

pydhcp-0.2.1rc1/docs/index.md

@@ -0,0 +1,44 @@
+# pydhcp
+
+A Python DHCP library and server implementation.
+
+## Features
+
+- **DHCP Packet Parsing & Construction**: Full control and type safety over DHCP message structures.
+- **Synchronous & Asynchronous Sockets**: Standard threaded listening loops (`DhcpListener`/`DhcpServer`) and modern asyncio endpoints (`AsyncDhcpListener`/`AsyncDhcpServer`).
+- **Flexible Options System**: Easy options manipulation using type-safe custom dictionaries.
+
+## Installation
+
+Install using pip:
+
+```bash
+pip install pydhcp
+```
+
+## Quick Start
+
+### Synchronous DHCP Server
+```python
+from pydhcp.server import DhcpServer
+
+# Automatically binds to default DHCP server ports
+server = DhcpServer()
+server.listen()
+```
+
+### Asynchronous DHCP Server
+```python
+import asyncio
+from pydhcp.server import AsyncDhcpServer
+
+async def main():
+    server = AsyncDhcpServer()
+    await server.start()
+    
+    # Wait or run other async application logic
+    # To shut down cleanly:
+    # await server.stop()
+
+asyncio.run(main())
+```