Metadata-Version: 2.4
Name: octodns-inwx
Version: 0.1.5
Summary: First-class octoDNS provider for INWX
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: octodns>=1.18.0
Requires-Dist: inwx-domrobot>=3.2.0

## INWX provider for octoDNS

An [octoDNS](https://github.com/octodns/octodns/) provider that targets [INWX](https://www.inwx.com/) DNS via the [DOMRobot XML-RPC API](https://www.inwx.com/en/help/apidoc).

### Installation

#### Command line

```
pip install octodns-inwx
```

#### requirements.txt/setup.py

Pinning specific versions or SHAs is recommended to avoid unplanned upgrades.

##### Versions

```
# Start with the latest versions and don't just copy what's here
octodns==1.18.0
octodns-inwx==0.1.0
```

##### SHAs

```
# Start with the latest/specific versions and don't just copy what's here
-e git+https://git@github.com/octodns/octodns.git@9da19749e28f68407a1c246dfdf65663cdc1c422#egg=octodns
-e git+https://git@github.com/fjaeckel/octodns-inwx.git@<sha>#egg=octodns_inwx
```

### Configuration

```yaml
providers:
  inwx:
    class: octodns_inwx.INWXProvider
    # INWX account username (required)
    username: env/INWX_USERNAME
    # INWX API password (required)
    api_password: env/INWX_PASSWORD
    # API endpoint base URL (optional, defaults to the production endpoint)
    #endpoint: https://api.domrobot.com
    # How many times to retry a transient API failure (optional, default 4)
    #retries: 4
    # Base seconds for the exponential retry backoff (optional, default 2.0)
    #retry_backoff: 2.0
```

A dedicated API user with permission to manage the affected domains is recommended.

#### Rate limiting

Large plans (many deletes, or a zone with dozens of changes) can trip INWX'
account-level rate limiting, which surfaces as a generic
`2400 Command failed` on any API method. The provider retries those with an
exponential backoff — raise `retries`/`retry_backoff` if bulk applies still
fail. The backoff pauses every worker, not just the one that was throttled,
since the limit applies to the account rather than the connection.

### Support Information

#### Records

INWXProvider supports A, AAAA, CAA, CNAME, MX, NS, PTR, SRV, TLSA, and TXT.

PTR records are managed the same way as any other record type, so reverse
DNS zones (e.g. `2.0.192.in-addr.arpa.` or `...ip6.arpa.`) can be managed by
octoDNS as long as the corresponding reverse zone is registered with INWX.

Multi-value PTR records (multiple hostnames pointed at the same IP) are
supported, since INWX itself allows storing more than one PTR row per name.

#### Dynamic

INWXProvider does not support dynamic records.

#### Concurrency (`max_workers`)

octoDNS shares a single `INWXProvider`/session across all zones that use it,
and runs `populate()` for those zones concurrently on separate threads when
the manager's `max_workers` is greater than 1. The underlying INWX API is
session-based, so the provider serializes all API calls internally and keeps
the session logged in for the lifetime of the provider instead of logging
out after each zone -- logging out early would kill the session for any
other zone still in flight. If you need to explicitly close the session
(e.g. at the end of a script that uses `INWXProvider` directly), call
`provider.close()`.

### Development

Install the package in editable mode along with the development tools:

```
pip install -r requirements-dev.txt
```

Tests are run with:

```
python -m unittest discover -s tests -v
```

Linting is run with:

```
ruff check .
```

### Releasing

Releases are published to PyPI automatically by [.github/workflows/publish.yml](.github/workflows/publish.yml)
whenever a `v*` tag is pushed. The workflow refuses to publish if the tag
doesn't match the version in `pyproject.toml`, so the two must be bumped
together:

1. Update `version` in [pyproject.toml](pyproject.toml) (e.g. `0.1.2` -> `0.1.3`).
2. Commit the bump, e.g. `git commit -am "Bump version to 0.1.3"`.
3. Tag the commit to match, with a `v` prefix: `git tag v0.1.3`.
4. Push both the commit and the tag: `git push && git push origin v0.1.3`.

Pushing the tag triggers the workflow, which verifies the tag matches
`pyproject.toml`, builds the sdist/wheel, and publishes to PyPI via trusted
publishing (no manual credentials needed).

