pydhcpctl 0.1.0__tar.gz

pydhcpctl-0.1.0/.gitignore

@@ -0,0 +1,53 @@
+# Dotfiles are opt-in, as a category: a new secret-bearing dotfile (.env,
+# .envrc, .pypirc, .netrc) is ignored before anyone has to remember it.
+/.*
+!/.gitignore
+!/.gitattributes
+!/.github/
+
+# Personal, per-machine overrides: never committed, never packaged (the
+# manifest excludes them too -- a dotfile pattern does not match these names).
+*.local.*
+
+# Agent configs / private notes, for nested occurrences the rule above cannot
+# reach. `.agents` is slashless on purpose: it is usually a symlink, which a
+# directory-only `.agents/` would not match.
+.agents
+CLAUDE*
+.claude
+
+# Virtualenvs
+.venv*/
+.pyvenv/
+venv/
+env/
+
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# Test / coverage / type-check caches
+.pytest_cache/
+.hypothesis/
+.mypy_cache/
+.ruff_cache/
+.coverage*
+htmlcov/
+.tox/
+
+# Docs site build output
+/site/
+
+# Editors / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store

pydhcpctl-0.1.0/CHANGELOG.md

@@ -0,0 +1,143 @@
+# 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.1.0] - 2026-10-19
+
+### Added
+
+- `DHCPServer.render(reservation, action="add")`: what an operation would
+  send, contacting nothing, on every shipped backend.
+- `dhcpctl.testing.BackendContract`: the suite every shipped backend passes,
+  for a third-party backend to run unmodified; it talks to no server.
+- The `dhcpctl` command line (`pydhcpctl[cli]`): `render`, `add`,
+  `complete`, `remove`, `recipe` and `backends`, a reservation given by flags
+  or a document, secrets from `DHCPCTL_*` variables.
+- Published as `pydhcpctl`; the import package is `dhcpctl`.
+- `connect(uri, *, secrets=None, owner="dhcpctl")`, `register_backend`,
+  `unregister_backend`, `backend_names`, `get_backend` and the
+  `dhcpctl.backends` entry-point group.
+- `DHCPServer`: `add`, `remove`, `keep`, `complete`, `ensure_condition`,
+  `condition_recipe`, `remove_condition_member`, `extras`,
+  `secret`, `redacted_uri`. A secret is the caller's when it gives one, else
+  the URI's user or password, so one URI serves several logins; a password is
+  masked in `str`, `repr` and messages.
+- `Reservation`, `Target`, `Scope`, `Condition`, `Completion`,
+  `parse_conditions`, `parse_completion`. What each serves is a pydhcp
+  `DHCPLease` (re-exported): the address (`0.0.0.0` for a MAC-only
+  reservation), the options, and the BOOTP header fields `siaddr`, `sname` and
+  `file`, which are not options 66 and 67; each backend writes them as its
+  server spells the fields. `Reservation.to_mapping` / `from_mapping` and
+  `to_text` / `from_text` write and read a reservation as plain data or a
+  JSON, YAML, TOML or INI document (all but JSON with the `formats` extra),
+  each lease in pydhcp's `DHCPLease.to_mapping` form.
+- Options are pydhcp's `DHCPOptions` and `DHCPOptionCode`, re-exported, and
+  reach a backend as pydhcp objects for it to write as its server needs.
+  A codemap (`option_codes`, an `OptionCodes` enum, pydhcp's
+  `OptionCodeEnum`, its names read by pydhcp's `resolve`) reads a config's option names: declared options with a
+  code and a pydhcp type of their own, aliases of names or codes, over pydhcp's
+  names, values read by pydhcp's `DHCPOptions.from_mapping` (an enum member
+  by name, octets as hex); the Kea and dhcpd backends add their own spellings (`OPTION_NAMES`),
+  and `connect(uri, codes=...)` the caller's; `codes.lease(mapping)` takes
+  the header fields (`next-server`, `file`, an alias) out of a config's options. Declared types belong to the
+  codemap, which starts from the codecs its base has when it is made. netsh's
+  data types come from the codecs. An unset address is `UNSPECIFIED`
+  (pydhcp's `UNSPECIFIED_ADDRESS`, `0.0.0.0`), as in BOOTP.
+- The dnsmasq backend writes its hosts and options files as dnsmasq reads
+  them: each line the value of `--dhcp-host` / `--dhcp-option` without the
+  key (netboot wrote `dhcp-host=` and `dhcp-option=` prefixes, which dnsmasq
+  rejects as "bad hex constant", so no reservation took effect), and the boot
+  file and next server as `option:bootfile-name` / `option:server-ip-address`
+  in place of a `dhcp-boot` line. An extras line for the options file is
+  written the same way. Checked against a real dnsmasq and DHCP client
+  (`tests/test_dnsmasq_real.py`).
+- A dnsmasq directory (`--dhcp-hostsdir`) is SIGHUPed when an entry it may have
+  read is removed or changed: dnsmasq only ever adds what such a directory
+  holds, so a completed client kept its boot file. A new entry still needs no
+  signal. A reservation with options and no `optsfile=` is refused instead of
+  arming the client without them; a trailing `/` on a path that does not exist
+  yet means a directory; names that reduce to one tag get distinct tags; a
+  missing or hung reload command, an unreadable pidfile and a platform without
+  SIGHUP are errors instead of a stray exception or SIGTERM. A local hosts or
+  options file is rewritten under a lock on `.<file>.lock`, so two runs at once
+  no longer drop each other's entries.
+- Every option reaches each server in a form it reads. dhcpd: an option it
+  defines is written under its name in its own syntax (119 codes, taken from
+  dhcpd 4.4 itself); netboot wrote `unknown-<n>` and octets for all but a
+  dozen, which dhcpd parses as the option's own type, so it refused the
+  host's statements and served none of them (70 of 134 options). Negative
+  numbers and domain names are written bare, and octets for an option dhcpd
+  defines with a structure of its own are a `ConfigError`. dnsmasq: a flag,
+  a number list and octets are written as octets (`True`, `576,1500` and
+  `0a0b` were text or refused). Kea: octets go with `csv-format` off, a flag
+  as `true`. Windows: a flag is 1 or 0, and a negative number the DWORD it
+  stores (it refused `-3600` for option 2). Checked by sending every option of a
+  plain codec through a real dhcpd (`dhcpd -t`) and dnsmasq, and one of each
+  codec to a real client (`tests/test_dhcpd_real.py`,
+  `tests/test_dnsmasq_real.py`).
+- Re-arming a client replaces what the server holds for it, on every
+  backend: dhcpd and Kea refused, and the Windows cmdlet threw.
+- Kea conditions work: a condition is a client class of the client's own,
+  tested on its MAC and `option[n].hex` (iPXE's flat option 77 never matched
+  `.text`), and what it overrides is served by a second class of the
+  client's when it does not match, since Kea serves a reservation's values
+  over any class's. The reservation names no `client-classes`, which put the
+  client in the class whatever its test said: on a real Kea every client was
+  handed the reservation's boot file, iPXE or not. `?target=memory` (host_cmds'
+  `operation-target`) arms a Kea with no hosts database. Checked against a
+  real Kea 3.0.4 (`tests/test_kea_real.py`).
+- Commands run through hostctl hosts: the Windows backend's local, ssh and
+  WinRM transports (`hostctl.LocalConfig`, `SSHConfig`, `WinRMConfig`) and a
+  dnsmasq `reload=`, locally or over ssh. hostctl delivers a PowerShell script
+  whole; netboot piped it into `powershell -Command -`, which runs only the
+  first line of a multi-line block and exits 0 even when a cmdlet fails, so
+  reservations were reported armed and were not. A script that ends without
+  printing its closing `{"ok": true}` is a `ServerError`, as are an
+  unreachable host, a refused login and a timeout (`timeout=`, default 120 s).
+  ssh is asyncssh, through `hostctl[ssh]`, rather than the system `ssh`
+  client; it reads `~/.ssh/config` as `ssh` does, and the `ssh` extra now
+  serves windhcp over ssh too. Checked against real Windows PowerShell 5.1
+  (`tests/test_windhcp_delivery.py`), and against a live Windows Server 2025
+  DHCP server over ssh with both methods: arm, re-arm, keep and remove, the
+  policies included (`tests/test_windhcp_live.py`, opt-in).
+- The Windows backend removes a target's own policies when it removes the
+  target (they kept answering its MAC); leaves an existing shared policy as it
+  is, and trusts it on a host without the DhcpServer module; prints, in target
+  mode, the MAC-matched policies it would create rather than a scope-wide one,
+  with every value quoted against injection (typographic quotes included);
+  reads back under `method=netsh` the options it actually set; keeps a
+  reservation through netsh when `method=netsh`; and warns about option 119 and
+  a next-server it cannot set.
+- The Kea backend keeps a reservation and detaches its classes with
+  `reservation-update` (or `reservation-del` then `reservation-add` where Kea
+  lacks it), checking every result: `reservation-add` on an existing
+  reservation was refused, and the detach's answer was ignored. Kea's keep
+  writes the `remove`-phase extras, as the other backends' do; a subnet inside
+  a `shared-networks` entry is found; `service=` other than `dhcp4` is
+  refused.
+- The dhcpd backend keeps a host by deleting and creating it again (dhcpd
+  refuses to create a host that exists, so keeping and leaving a group failed);
+  creates a host in its group in one create, after finding the group by lookup
+  or creating it, and arms nothing when the group cannot be made; in group mode
+  puts each value a condition overrides in the `else` of its test, since a
+  host's statements outrank its group's; writes an option dhcpd has no name
+  for as `unknown-<n>` (`dhcp-option-<n>` does not parse); and refuses to arm a
+  host that exists rather than failing deep in pypureomapi. Checked against a
+  real ISC dhcpd 4.4 and DHCP client (`tests/test_dhcpd_real.py`).
+- Backends for dnsmasq, Kea (`kea`/`keas`), ISC dhcpd over OMAPI and Windows
+  DHCP (PowerShell or netsh; local, ssh or WinRM), taken from netboot 0.4,
+  sending what netboot sent, except that Kea's `option-data` names options by
+  code (netboot sent names Kea does not define: `router`, `lease-time`), and a
+  Kea client class carries the boot file as its `boot-file-name` field, as a
+  reservation does, rather than as option 67.
+- Errors under `DHCPCtlError`: `ConfigError`, `UnknownBackendError`,
+  `BackendUnavailableError`, `MissingMACError`, `ServerError`,
+  `ConditionUnsupportedError`, `ConditionMissingError`.
+
+[Unreleased]: https://github.com/jose-pr/dhcpctl/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/jose-pr/dhcpctl/releases/tag/v0.1.0

pydhcpctl-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jose A.
+
+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.

pydhcpctl-0.1.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.5
+Name: pydhcpctl
+Version: 0.1.0
+Summary: One interface to DHCP servers: arm a reservation on dnsmasq, Kea, ISC dhcpd or Windows DHCP, then remove or keep it.
+Project-URL: Homepage, https://github.com/jose-pr/dhcpctl/
+Project-URL: Documentation, https://jose-pr.github.io/dhcpctl/
+Project-URL: Issues, https://github.com/jose-pr/dhcpctl/issues
+Author: jose-pr
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: System Administrators
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: hostctl<0.5,>=0.4.0
+Requires-Dist: netimps<0.5,>=0.4.1
+Requires-Dist: pathapi-uri<0.2,>=0.1.0
+Requires-Dist: pathapi<0.2,>=0.1.2
+Requires-Dist: pydhcp<0.10,>=0.9.0
+Provides-Extra: cli
+Requires-Dist: duho<0.8,>=0.7.6; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: duho<0.8,>=0.7.6; extra == 'dev'
+Requires-Dist: hostctl[ssh]<0.5,>=0.4.0; extra == 'dev'
+Requires-Dist: hostctl[winrm]<0.5,>=0.4.0; extra == 'dev'
+Requires-Dist: pktcap[toml,yaml]<0.2,>=0.1.1; extra == 'dev'
+Requires-Dist: pydhcp[pktcap]; extra == 'dev'
+Requires-Dist: pypureomapi<2,>=0.8; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: requests<3,>=2.32.3; extra == 'dev'
+Requires-Dist: sftppath[uri]<0.2,>=0.1.3; extra == 'dev'
+Provides-Extra: dhcpd
+Requires-Dist: pypureomapi<2,>=0.8; extra == 'dhcpd'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocs<2; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Requires-Dist: pymdown-extensions<12.2; (python_version < '3.11') and extra == 'docs'
+Provides-Extra: formats
+Requires-Dist: pktcap[toml,yaml]<0.2,>=0.1.1; extra == 'formats'
+Requires-Dist: pydhcp[pktcap]; extra == 'formats'
+Provides-Extra: kea
+Requires-Dist: requests<3,>=2.32.3; extra == 'kea'
+Provides-Extra: ssh
+Requires-Dist: hostctl[ssh]<0.5,>=0.4.0; extra == 'ssh'
+Requires-Dist: sftppath[uri]<0.2,>=0.1.3; extra == 'ssh'
+Provides-Extra: winrm
+Requires-Dist: hostctl[winrm]<0.5,>=0.4.0; extra == 'winrm'
+Description-Content-Type: text/markdown
+
+# dhcpctl
+
+[![Version](https://img.shields.io/pypi/v/pydhcpctl.svg)](https://pypi.org/project/pydhcpctl/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pydhcpctl.svg)](https://pypi.org/project/pydhcpctl/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jose-pr/dhcpctl/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/dhcpctl/)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/dhcpctl/test.yml)](https://github.com/jose-pr/dhcpctl/actions/workflows/test.yml)
+
+One interface to DHCP servers: **arm a reservation** for a client on dnsmasq,
+ISC Kea, ISC dhcpd or Windows DHCP, then **remove it or keep it** without its
+boot options. A server is a URI: its scheme picks the backend and its query says how to
+reach it. The options to serve belong to each reservation.
+Documentation: <https://jose-pr.github.io/dhcpctl/>.
+
+## Features
+
+- **Four servers, one call** — `add`, `remove`, `complete` on dnsmasq (files,
+  local or over `sftp://`), Kea (control agent), dhcpd (OMAPI) and Windows DHCP
+  (PowerShell cmdlets or netsh, locally, over ssh or WinRM).
+- **pydhcp's lease** — what a client is served is a [pydhcp](https://github.com/jose-pr/pydhcp)
+  `DHCPLease`: its address, its `DHCPOptions` named by pydhcp's registry
+  (`router`, `dns`, `option-<n>`) or an alias, each value read by its pydhcp
+  codec before any server sees it, and the BOOTP header fields (`next-server`,
+  `file`); each backend translates them, and backend-native text in a
+  reservation's `extras` rides through untouched.
+- **Conditions** — options served only to clients that match a test (the iPXE
+  chainload), as a Windows policy, a dhcpd `if` or group, or a Kea client class;
+  a backend that cannot express one refuses rather than arming without it, and
+  hands over the server-side recipe when it lacks the rights to create it.
+- **Completion that does not reinstall** — keep a finished client's reservation
+  and replace only its boot options.
+- **Values are data, never source** — dhcpd statements are escaped, Windows
+  scripts get their parameters as a JSON payload, netsh arguments stay array
+  elements.
+- **Nothing required** — each backend's library is an extra, imported only when
+  its scheme is used; secrets come from the URI or the caller, and a password
+  is masked wherever a server is shown.
+- **Reservations as documents** — `Reservation.to_mapping` / `from_mapping`
+  and `to_text` / `from_text` (JSON, YAML, TOML, INI) round-trip a reservation
+  through pydhcp's own option form.
+- **Pluggable** — a backend is a `DHCPServer` subclass registered for a scheme,
+  directly or through the `dhcpctl.backends` entry point.
+
+## Installation
+
+```bash
+pip install pydhcpctl
+```
+
+The distribution is `pydhcpctl`; the import package is `dhcpctl`.
+
+| Scheme | Server | Install |
+| --- | --- | --- |
+| `dnsmasq://` | dnsmasq | nothing locally; `pydhcpctl[ssh]` for `sftp://` paths |
+| `kea://`, `keas://` | ISC Kea control agent | `pydhcpctl[kea]` (requests) |
+| `dhcpd://` | ISC dhcpd over OMAPI | `pydhcpctl[dhcpd]` (pypureomapi) |
+| `windhcp://` | Windows DHCP | nothing locally; `pydhcpctl[ssh]` over ssh, `pydhcpctl[winrm]` over WinRM |
+
+`pydhcpctl[formats]` adds YAML, TOML and INI to `Reservation.to_text` /
+`from_text` (JSON needs nothing), and `pydhcpctl[cli]` the `dhcpctl` command.
+
+Python 3.9 or later.
+
+## Usage
+
+```python
+import dhcpctl
+from ipaddress import ip_network
+
+from netimps import MACAddress
+
+server = dhcpctl.connect("kea://kea01:8000/?service=dhcp4")  # how to reach it, nothing else
+
+# Options by name, and the BOOTP header fields beside them (not options).
+lease = server.codes.lease(
+    {"router": "10.0.0.1", "file": "undionly.kpxe", "next-server": "10.0.0.2"}
+)
+reservation = dhcpctl.Reservation(
+    target=dhcpctl.Target("web01", mac=MACAddress("aa:bb:cc:dd:ee:ff")),
+    scope=dhcpctl.Scope("lan", network=ip_network("10.0.0.0/24")),
+    lease=lease.replace(ip="10.0.0.10"),
+    completion=dhcpctl.Completion(keep=True),  # keep the address when done
+)
+
+server.add(reservation)       # arm
+server.complete(reservation)  # finished: keep the entry, drop its boot options
+```
+
+A condition serves different options to clients that match a test:
+
+```python
+import dataclasses
+
+conditions = dhcpctl.parse_conditions(
+    {"ipxe": {"match": {"user-class": "iPXE"}, "options": {"file": "boot.ipxe"}}}
+)
+server.add(dataclasses.replace(reservation, conditions=conditions))
+print(server.condition_recipe(reservation, conditions["ipxe"]))  # what an admin applies
+```
+
+A secret is the URI's when it carries one, else the caller's, asked for only
+when needed — so it can stay out of a URI that ends up in config or logs:
+
+```python
+server = dhcpctl.connect(
+    "windhcp://dhcp01/?transport=winrm", secrets={"user": "svc", "password": "..."}
+)
+```
+
+## Command line
+
+`pip install pydhcpctl[cli]` adds the `dhcpctl` command (also `python -m
+dhcpctl`). A reservation is given by flags, or as a document with `--from`
+(`.json`, `.yaml`, `.toml`, `.ini`, or `-` for JSON on standard input), which
+can also carry conditions and a completion:
+
+```bash
+# What arming web01 would send, contacting nothing:
+dhcpctl render 'dhcpd://dhcp01/' -n web01 -m aa:bb:cc:dd:ee:ff --ip 10.0.0.10 \
+    -o router=10.0.0.1 -o file=undionly.kpxe
+dhcpctl add 'kea://kea01/?target=memory' --from web01.json   # arm (or re-arm)
+dhcpctl complete 'kea://kea01/?target=memory' --from web01.json --keep
+dhcpctl remove 'windhcp://dhcp01/?transport=winrm' -n web01 -m aa:bb:cc:dd:ee:ff
+dhcpctl recipe 'windhcp://dhcp01/' --from web01.json         # what an admin sets up once
+dhcpctl backends --json
+```
+
+`-o name=value` is an option or header field; a comma makes a list
+(`dns=10.0.0.53,10.0.0.54`) and `json:` a JSON value (`lease-time=json:600`).
+Secrets come from the environment, never a flag: `DHCPCTL_USER`,
+`DHCPCTL_PASSWORD`, `DHCPCTL_KEYNAME`, `DHCPCTL_OMAPI_KEY`. Exit status 0 is
+done, 1 the server refused or could not be reached, 2 the invocation or the
+reservation was wrong.
+
+## Writing a backend
+
+```python
+class Recorder(dhcpctl.DHCPServer):
+    def add(self, reservation): ...
+    def remove(self, reservation): ...
+
+dhcpctl.register_backend("recorder", Recorder)
+dhcpctl.connect("recorder://anything")
+```
+
+or declare it in your package's metadata:
+
+```toml
+[project.entry-points."dhcpctl.backends"]
+recorder = "mypkg.dhcp:Recorder"
+```
+
+A backend is done when it passes the contract the shipped ones pass, which
+talks to no server (it needs pytest, and the backend to implement `render`):
+
+```python
+from dhcpctl.testing import BackendContract
+
+class TestRecorder(BackendContract):
+    uri = "recorder://anything"
+```
+
+## License
+
+MIT

pydhcpctl-0.1.0/README.md

@@ -0,0 +1,165 @@
+# dhcpctl
+
+[![Version](https://img.shields.io/pypi/v/pydhcpctl.svg)](https://pypi.org/project/pydhcpctl/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pydhcpctl.svg)](https://pypi.org/project/pydhcpctl/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jose-pr/dhcpctl/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/dhcpctl/)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/dhcpctl/test.yml)](https://github.com/jose-pr/dhcpctl/actions/workflows/test.yml)
+
+One interface to DHCP servers: **arm a reservation** for a client on dnsmasq,
+ISC Kea, ISC dhcpd or Windows DHCP, then **remove it or keep it** without its
+boot options. A server is a URI: its scheme picks the backend and its query says how to
+reach it. The options to serve belong to each reservation.
+Documentation: <https://jose-pr.github.io/dhcpctl/>.
+
+## Features
+
+- **Four servers, one call** — `add`, `remove`, `complete` on dnsmasq (files,
+  local or over `sftp://`), Kea (control agent), dhcpd (OMAPI) and Windows DHCP
+  (PowerShell cmdlets or netsh, locally, over ssh or WinRM).
+- **pydhcp's lease** — what a client is served is a [pydhcp](https://github.com/jose-pr/pydhcp)
+  `DHCPLease`: its address, its `DHCPOptions` named by pydhcp's registry
+  (`router`, `dns`, `option-<n>`) or an alias, each value read by its pydhcp
+  codec before any server sees it, and the BOOTP header fields (`next-server`,
+  `file`); each backend translates them, and backend-native text in a
+  reservation's `extras` rides through untouched.
+- **Conditions** — options served only to clients that match a test (the iPXE
+  chainload), as a Windows policy, a dhcpd `if` or group, or a Kea client class;
+  a backend that cannot express one refuses rather than arming without it, and
+  hands over the server-side recipe when it lacks the rights to create it.
+- **Completion that does not reinstall** — keep a finished client's reservation
+  and replace only its boot options.
+- **Values are data, never source** — dhcpd statements are escaped, Windows
+  scripts get their parameters as a JSON payload, netsh arguments stay array
+  elements.
+- **Nothing required** — each backend's library is an extra, imported only when
+  its scheme is used; secrets come from the URI or the caller, and a password
+  is masked wherever a server is shown.
+- **Reservations as documents** — `Reservation.to_mapping` / `from_mapping`
+  and `to_text` / `from_text` (JSON, YAML, TOML, INI) round-trip a reservation
+  through pydhcp's own option form.
+- **Pluggable** — a backend is a `DHCPServer` subclass registered for a scheme,
+  directly or through the `dhcpctl.backends` entry point.
+
+## Installation
+
+```bash
+pip install pydhcpctl
+```
+
+The distribution is `pydhcpctl`; the import package is `dhcpctl`.
+
+| Scheme | Server | Install |
+| --- | --- | --- |
+| `dnsmasq://` | dnsmasq | nothing locally; `pydhcpctl[ssh]` for `sftp://` paths |
+| `kea://`, `keas://` | ISC Kea control agent | `pydhcpctl[kea]` (requests) |
+| `dhcpd://` | ISC dhcpd over OMAPI | `pydhcpctl[dhcpd]` (pypureomapi) |
+| `windhcp://` | Windows DHCP | nothing locally; `pydhcpctl[ssh]` over ssh, `pydhcpctl[winrm]` over WinRM |
+
+`pydhcpctl[formats]` adds YAML, TOML and INI to `Reservation.to_text` /
+`from_text` (JSON needs nothing), and `pydhcpctl[cli]` the `dhcpctl` command.
+
+Python 3.9 or later.
+
+## Usage
+
+```python
+import dhcpctl
+from ipaddress import ip_network
+
+from netimps import MACAddress
+
+server = dhcpctl.connect("kea://kea01:8000/?service=dhcp4")  # how to reach it, nothing else
+
+# Options by name, and the BOOTP header fields beside them (not options).
+lease = server.codes.lease(
+    {"router": "10.0.0.1", "file": "undionly.kpxe", "next-server": "10.0.0.2"}
+)
+reservation = dhcpctl.Reservation(
+    target=dhcpctl.Target("web01", mac=MACAddress("aa:bb:cc:dd:ee:ff")),
+    scope=dhcpctl.Scope("lan", network=ip_network("10.0.0.0/24")),
+    lease=lease.replace(ip="10.0.0.10"),
+    completion=dhcpctl.Completion(keep=True),  # keep the address when done
+)
+
+server.add(reservation)       # arm
+server.complete(reservation)  # finished: keep the entry, drop its boot options
+```
+
+A condition serves different options to clients that match a test:
+
+```python
+import dataclasses
+
+conditions = dhcpctl.parse_conditions(
+    {"ipxe": {"match": {"user-class": "iPXE"}, "options": {"file": "boot.ipxe"}}}
+)
+server.add(dataclasses.replace(reservation, conditions=conditions))
+print(server.condition_recipe(reservation, conditions["ipxe"]))  # what an admin applies
+```
+
+A secret is the URI's when it carries one, else the caller's, asked for only
+when needed — so it can stay out of a URI that ends up in config or logs:
+
+```python
+server = dhcpctl.connect(
+    "windhcp://dhcp01/?transport=winrm", secrets={"user": "svc", "password": "..."}
+)
+```
+
+## Command line
+
+`pip install pydhcpctl[cli]` adds the `dhcpctl` command (also `python -m
+dhcpctl`). A reservation is given by flags, or as a document with `--from`
+(`.json`, `.yaml`, `.toml`, `.ini`, or `-` for JSON on standard input), which
+can also carry conditions and a completion:
+
+```bash
+# What arming web01 would send, contacting nothing:
+dhcpctl render 'dhcpd://dhcp01/' -n web01 -m aa:bb:cc:dd:ee:ff --ip 10.0.0.10 \
+    -o router=10.0.0.1 -o file=undionly.kpxe
+dhcpctl add 'kea://kea01/?target=memory' --from web01.json   # arm (or re-arm)
+dhcpctl complete 'kea://kea01/?target=memory' --from web01.json --keep
+dhcpctl remove 'windhcp://dhcp01/?transport=winrm' -n web01 -m aa:bb:cc:dd:ee:ff
+dhcpctl recipe 'windhcp://dhcp01/' --from web01.json         # what an admin sets up once
+dhcpctl backends --json
+```
+
+`-o name=value` is an option or header field; a comma makes a list
+(`dns=10.0.0.53,10.0.0.54`) and `json:` a JSON value (`lease-time=json:600`).
+Secrets come from the environment, never a flag: `DHCPCTL_USER`,
+`DHCPCTL_PASSWORD`, `DHCPCTL_KEYNAME`, `DHCPCTL_OMAPI_KEY`. Exit status 0 is
+done, 1 the server refused or could not be reached, 2 the invocation or the
+reservation was wrong.
+
+## Writing a backend
+
+```python
+class Recorder(dhcpctl.DHCPServer):
+    def add(self, reservation): ...
+    def remove(self, reservation): ...
+
+dhcpctl.register_backend("recorder", Recorder)
+dhcpctl.connect("recorder://anything")
+```
+
+or declare it in your package's metadata:
+
+```toml
+[project.entry-points."dhcpctl.backends"]
+recorder = "mypkg.dhcp:Recorder"
+```
+
+A backend is done when it passes the contract the shipped ones pass, which
+talks to no server (it needs pytest, and the backend to implement `render`):
+
+```python
+from dhcpctl.testing import BackendContract
+
+class TestRecorder(BackendContract):
+    uri = "recorder://anything"
+```
+
+## License
+
+MIT

pydhcpctl-0.1.0/docs/api/reference.md

@@ -0,0 +1,50 @@
+# API reference
+
+## Connecting
+
+::: dhcpctl.connect
+
+::: dhcpctl.register_backend
+
+::: dhcpctl.unregister_backend
+
+::: dhcpctl.backend_names
+
+::: dhcpctl.get_backend
+
+## The contract
+
+::: dhcpctl.DHCPServer
+
+## Reservations
+
+::: dhcpctl.Reservation
+
+::: dhcpctl.Target
+
+::: dhcpctl.Scope
+
+## What is served
+
+`dhcpctl.DHCPLease`, `dhcpctl.DHCPOptions` and `dhcpctl.DHCPOptionCode` are
+pydhcp's, re-exported: see [pydhcp's reference](https://jose-pr.github.io/pydhcp/).
+
+::: dhcpctl.OptionCodes
+
+::: dhcpctl.option_codes
+
+::: dhcpctl.plain_items
+
+## Conditions and completion
+
+::: dhcpctl.Condition
+
+::: dhcpctl.parse_conditions
+
+::: dhcpctl.Completion
+
+::: dhcpctl.parse_completion
+
+## Errors
+
+::: dhcpctl.exceptions