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>)

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) – 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.

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

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

Raises:

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

async validate()

Validate connectivity, authentication, and minimum firmware support.

Note that this will throw errors, regardless of what self._throw_errors is set to.

Raises:

• OPNsenseInvalidURL – Raised when the configured URL is invalid.

• OPNsenseSSLError – Raised when the TLS handshake fails.

• OPNsenseTimeoutError – Raised when validation requests time out.

• OPNsenseInvalidAuth – Raised when API authentication fails.

• OPNsensePrivilegeMissing – Raised when the API user lacks privileges.

• OPNsenseConnectionError – Raised when another client connection error occurs.

• OPNsenseUnknownFirmware – Raised when firmware detection returns no version.

• OPNsenseBelowMinFirmware – Raised when the detected firmware is unsupported.

Return type:

None