Main Client

OPNsenseClient is the public entry point for the library.

class aiopnsense.OPNsenseClient(url, username, password, session, opts=None, initial=<object object>, name='OPNsense', *, throw_errors=<object object>)[source]

Async client for supported OPNsense REST endpoints.

Initialize the OPNsense client.

Parameters:

  • url (str) – Base URL of the OPNsense instance.

  • username (str) – Username for API authentication.

  • password (str) – Password for API authentication.

  • session (aiohttp.ClientSession) – HTTP client session used for API requests.

  • opts (MutableMapping[str, Any] | None) – Optional client configuration values (e.g. opts={"verify_ssl": True}).

  • initial (bool | object) – Deprecated alias for throw_errors. When provided, a DeprecationWarning is emitted. Ignored when throw_errors is also set.

  • name (str) – Display name for the client instance.

  • throw_errors (bool | object) – Whether request and decorator errors should be re-raised instead of logged and suppressed. Defaults to False.

Raises:

OPNsenseInvalidArgument – Raised when initial or throw_errors is not a bool.

async validate(*, require_device_id=True)[source]

Validate connectivity, authentication, and minimum firmware support.

This raises request failures regardless of self._throw_errors; those failures are mapped to public OPNsense errors by _run_validation_request.

Parameters:

require_device_id (bool) – Whether validation must resolve a physical-device unique ID.

Raises:
Return type:

None