Converted Go MIAB tool to Python.

README.md

@@ -0,0 +1,131 @@
+# mailinabox
+
+Python client library and CLI for the [Mail-in-a-Box](https://mailinabox.email/) admin DNS API.
+
+Licensed under the [MIT License](LICENSE).
+
+## Installation
+
+The `miab` command is installed into the active virtual environment by any of the methods below.
+The package depends on `cloud-tools`, which provides the `python_helpers` package.
+
+### Local install
+
+```sh
+pip install -e .   # editable, for development: picks up source changes without reinstalling
+pip install .      # normal install: copies the package in
+```
+
+### Install from git
+
+```sh
+pip install git+<repository-url>@main
+```
+
+### Running without installing
+
+From a repo checkout, run the command as a module with `-m` instead of installing the package:
+
+```sh
+python3 -m mailinabox.cli.miab --help
+```
+
+From outside the checkout, point `PYTHONPATH` at it:
+
+```sh
+PYTHONPATH=/path/to/mailinabox python3 -m mailinabox.cli.miab --help
+```
+
+## Library
+
+```python
+from mailinabox.dns import Client
+
+# Explicit credentials:
+client = Client("box.example.com", "admin@example.com", "password")
+
+# From environment variables (MIAB_* or MAILINABOX_* style):
+client = Client()
+
+client.set_record("foo.example.com", "TXT", "v=spf1 ~all")
+client.add_record("foo.example.com", "A", "1.2.3.4")
+client.delete_record("foo.example.com", "A", "1.2.3.4")
+
+records = client.list_records("TXT")
+```
+
+`list_records` returns a list of `DNSRecord` named tuples with `name`, `type` and `value`
+fields. Every method raises `mailinabox.dns.MailInABoxError` if credentials are missing or the
+API rejects the request.
+
+## CLI
+
+```sh
+miab [--env-file FILE] list   [--type TYPE]
+miab [--env-file FILE] set    [--type TYPE] <name> <value>
+miab [--env-file FILE] add    [--type TYPE] <name> <value>
+miab [--env-file FILE] delete [--type TYPE] <name> [value]
+```
+
+`--type` defaults to `A` for `set`, `add` and `delete`; `list` shows every record type unless
+one is given. Omitting the value for `delete` removes all records of that type for the name.
+
+```sh
+miab list --type TXT
+miab set --type TXT foo.example.com "v=spf1 ~all"
+miab add --type A foo.example.com 1.2.3.4
+miab delete --type A foo.example.com 1.2.3.4
+```
+
+## Credentials
+
+Credentials are read from the environment; either naming style is accepted, with `MIAB_*`
+taking precedence.
+
+```sh
+# MIAB style
+export MIAB_HOST=box.example.com
+export MIAB_USERNAME=admin@example.com
+export MIAB_PASSWORD=password
+
+# Mail-in-a-Box style
+export MAILINABOX_BASE_URL=https://box.example.com
+export MAILINABOX_EMAIL=admin@example.com
+export MAILINABOX_PASSWORD=password
+```
+
+The hostname is parsed out of `MAILINABOX_BASE_URL` when `MIAB_HOST` is not set.
+
+### Environment file
+
+`--env-file|-E` reads the same variables from a docker-style file, overriding any inherited
+from the shell. It is a global option and goes before the command name:
+
+```sh
+miab --env-file box.env list --type TXT
+```
+
+```
+# Mail-in-a-Box credentials
+MIAB_HOST=box.example.com
+MIAB_USERNAME=admin@example.com
+MIAB_PASSWORD=password
+```
+
+Blank lines and lines whose first non-blank character is `#` are ignored; every other line must
+be `NAME=VALUE`. Values are taken literally, as `docker run --env-file` does: quotes are kept
+rather than stripped, `#` after the `=` is part of the value, and no variable interpolation is
+performed.
+
+## Tests
+
+```sh
+python3 -m unittest discover -s tests
+```
+
+## AI Disclaimer
+
+This project was generated with the assistance of AI tools. While efforts have been made to
+ensure the accuracy and reliability of the code, users should review and test the code
+thoroughly before using it in production environments. The author is not responsible for any
+issues arising from the use of this code.