Connection

class activelogic.Connection

The Connection class represents a tcp-level connection to any system that hosts a database daemon (PLDB) and is running firmware 20.30 or later.

Note

API users are adviced to connect using any of the helper methods activelogic.async_connect() or activelogic.sync_connect() rather than instantiating the Connection class itself.

Opened connections are automatically closed when they are garbage collected. The best practice however is to close each one using Connection.close() or to use a context manager.

Connection.machineid

The machine id of the system to which the Python API is connected.

Raises:: ValueError – Not connected.

>>> conn.machineid
'001122334455'

Connection.distversion

The firmware version running on the system to which the Python API is connected.

Raises:: ValueError – Not connected.

>>> conn.distversion
'22.20.06.1'

async Connection.close()

Closes the connection.

No more data will be sent or received. Opened resources will be rendered useless after this call.

Connect

activelogic.sync_connect(host, username, password)

Connects to a system, applying a proxy object on top of the asynchronous API, so that coroutines can be called just like they were normal blocking tasks.

This method may be helpful for simpler tasks or if used directly in a Python interpreter. To close the connection, use Connection.close().

Parameters:

host – Address of the system to connect to.
username –
password –

Raises:

ConnectionRefusedError – Connection attempt is refused by peer.
PLDBIOError – Authorization failure.
PLDBCapabilityError – Server does not announce sufficient capabilities.

Returns:

Proxied Connection instance

>>> conn = api.sync_connect("127.0.1.2", "admin", "password")
>>> rs = conn.ruleset()
>>> conn.close()

Connection can also be used as a context manager. This ensures that connection is closed immediately when the context manager exits.

>>> with api.sync_connect("127.0.1.2", "admin", "password") as conn:
...   rs = conn.ruleset()

Async Connect (advanced)

async activelogic.async_connect(host, username, password)

Connects to a system using the asyncronous API. Most methods in this API, this function included, are implemented as coroutines using the async/await syntax.

Parameters:

host – Address of the system to connect to.
username –
password –

Raises:

ConnectionRefusedError – Connection attempt is refused by peer.
PLDBIOError – Authorization failure.
PLDBCapabilityError – Server does not announce sufficient capabilities.

Returns:

Connection instance

import asyncio
import activelogic as api

async def amain(host, username, password):
    async with await api.async_connect(host, username, password) as conn:

        rs = await conn.ruleset()
        sd = await conn.sysdiag()

        # ...

asyncio.run(amain("127.0.1.2", "admin", "password"))

Note that simply calling a coroutine will not schedule it to be executed:

>>> api.async_connect("127.0.1.2", "admin", "password")
<coroutine object connect at 0x7fda07af7940>

To actually run a coroutine, asyncio provides three main mechanisms:

Await the coroutine.
The asyncio.run() function.
The asyncio.create_task() function.

Please refer to the Python Standard Library documentation for further details.

Resources

async Connection.begin(cls)

Starts a resource and attaches a new session to it.

Parameters:

cls – Resource class.

Raises:

TypeError – Invalid resource.
ValueError – Error attaching a new session to resource.
ValueError – Error retreiving server capabilities.
PLDBCapabilityError – Session (remote or local) does not announce sufficient capabilities.
PLDBCriticalError – Permission is denied.

Returns:

The resource object.

async Connection.config()

Starts the System Configuration resource and attaches a new session to it.

Returns:: New Config resource object.
Raises:: see Connection.begin()

async Connection.sysdiag()

Starts the System Diagnostics resource and attaches a new session to it.

Returns:: New SysDiag resource object.
Raises:: see Connection.begin()

async Connection.channels()

Starts the Channels resource and attaches a new session to it.

Returns:: New Channels resource object.
Raises:: see Connection.begin()

async Connection.ruleset()

Starts the Ruleset resource and attaches a new session to it.

Returns:: New Ruleset resource object.
Raises:: see Connection.begin()

async Connection.fileserv()

Starts the Fileserv resource and attaches a new sesson to it.

Returns:: New Fileserv resource object.
Raises:: see Connection.begin()

async Connection.users()

Starts the Users resource and attaches a new session to it.

Returns:: New Users resource object.
Raises:: see Connection.begin()

async Connection.statsfs()

Starts the StatsFS resource and attaches a new session to it.

Returns:: New StatsFS resource object.
Raises:: see Connection.begin()

async Connection.system_overview()

Starts the SystemOverview resource and attaches a new session to it.

Returns:: New SystemOverview resource object.
Raises:: see Connection.begin()

async Connection.logs()

Starts the Logs resource and attaches a new session to it.

:return New Logs resource object.

Raises:: see Connection.begin()

Restart of Services and System

async Connection.reload(reason='')

Restarts core services on the system.

Note

This command disconnects the connection and all its resources from the system. Manual reconnect is required.

Parameters:: reason (str) – Message describing the reason for the reload.

async Connection.reboot(reason='')

Reboots the system.

Note

This command disconnects the connection and all its resources from the system. Manual reconnect is required.

Parameters:: reason (str) – Message describing the reason for the reboot.